include/maps_service.h

   1 /*
   2  * Copyright (c) 2014 Samsung Electronics Co., Ltd All Rights Reserved
   3  *
   4  * Licensed under the Apache License, Version 2.0 (the "License");
   5  * you may not use this file except in compliance with the License.
   6  * You may obtain a copy of the License at
   7  *
   8  * http://www.apache.org/licenses/LICENSE-2.0
   9  *
  10  * Unless required by applicable law or agreed to in writing, software
  11  * distributed under the License is distributed on an "AS IS" BASIS,
  12  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  13  * See the License for the specific language governing permissions and
  14  * limitations under the License.
  15  */
  16
  17 #ifndef __MAPS_SERVICE_H__
  18 #define __MAPS_SERVICE_H__
  19
  20 #include <tizen_type.h>
  21 #include <maps_error.h>
  22 #include <maps_address.h>
  23 #include <maps_area.h>
  24 #include <maps_coordinates.h>
  25 #include <maps_place.h>
  26 #include <maps_place_filter.h>
  27 #include <maps_route.h>
  28
  29 /**
  30  *
  31  * @file maps_service.h
  32  * @brief This file contains the top level functions of Maps API
  33  *
  34  */
  35
  36 #ifdef __cplusplus
  37 extern "C" {
  38 #endif
  39
  40 /*----------------------------------------------------------------------------*/
  41 /*
  42  * Maps Service and Preference
  43  */
  44
  45 /**
  46  * @ingroup     CAPI_MAPS_SERVICE_MODULE
  47  * @defgroup    CAPI_MAPS_SERVICE_AND_PREFERENCE_MODULE Service and Providers
  48  *
  49  * @addtogroup CAPI_MAPS_SERVICE_AND_PREFERENCE_MODULE
  50  * @{
  51  * @brief This provides APIs related Search and Preference.
  52  *
  53  */
  54
  55 /**
  56  * @brief       Enumerations of maps requests available in the Maps Service
  57  * @since_tizen 2.4
  58  */
  59 typedef enum _maps_service_e {
  60         MAPS_SERVICE_GEOCODE,                           /** Indicates that
  61                                 maps_service_geocode() service is allowed */
  62         MAPS_SERVICE_GEOCODE_INSIDE_AREA,               /** Indicates that
  63                 maps_service_geocode_iside_area() service is allowed */
  64         MAPS_SERVICE_GEOCODE_BY_STRUCTURED_ADDRESS,     /** Indicates that
  65         maps_service_geocode_by_structured_address() service is allowed */
  66         MAPS_SERVICE_REVERSE_GEOCODE,                   /** Indicates that
  67                         maps_service_reverse_geocode() service is allowed */
  68         MAPS_SERVICE_SEARCH_PLACE,                      /** Indicates that
  69                                 maps_service_place() service is allowed */
  70         MAPS_SERVICE_SEARCH_PLACE_BY_AREA,              /** Indicates that
  71                 maps_service_search_place_by_area() service is allowed */
  72         MAPS_SERVICE_SEARCH_PLACE_BY_ADDRESS,           /** Indicates that
  73                 maps_service_search_place_by_address() service is allowed */
  74         MAPS_SERVICE_SEARCH_ROUTE,                      /** Indicates that
  75                         maps_service_search_route() service is allowed */
  76         MAPS_SERVICE_SEARCH_ROUTE_WAYPOINTS,            /** Indicates that
  77                 maps_service_search_route_waypoints() service is allowed */
  78         MAPS_SERVICE_CANCEL_REQUEST                     /** Indicates that
  79                         maps_service_cancel_request() service is allowed */
  80 } maps_service_e;
  81
  82 /**
  83  * @brief Enumerations of maps features available in the Maps Service
  84  * @since_tizen 2.4
  85  */
  86 typedef enum _maps_service_data_e {
  87         MAPS_PLACE_ADDRESS,             /**< Indicates the address value in the
  88                                           Place data*/
  89         MAPS_PLACE_RATING,              /**< Indicates the rating value in the
  90                                           Place data*/
  91         MAPS_PLACE_CATEGORIES,          /**< Indicates the place category list
  92                                           in the Place data*/
  93         MAPS_PLACE_ATTRIBUTES,          /**< Indicates the place attribute
  94                                           list in the Place data*/
  95         MAPS_PLACE_CONTACTS,            /**< Indicates the place contact list in
  96                                           the Place data*/
  97         MAPS_PLACE_EDITORIALS,          /**< Indicates the place editorial list
  98                                           in the Place data*/
  99         MAPS_PLACE_REVIEWS,             /**< Indicates the place review list in
 100                                           the Place data*/
 101         MAPS_PLACE_IMAGE,               /**< Indicates the place image in Place
 102                                           the data*/
 103         MAPS_PLACE_SUPPLIER,            /**< Indicates the place supplier link
 104                                           value in the Place data*/
 105         MAPS_PLACE_RELATED,             /**< Indicates the related place link in
 106                                           the Place data*/
 107         MAPS_ROUTE_PATH,                /**< Indicates that the Route Data
 108         Structure is defined as a Path (a list of geographical coordinates) */
 109         MAPS_ROUTE_SEGMENTS_PATH,       /**< Indicates that the Route Data
 110         Structure is defined as a list of Segments while each segment is defined
 111         as a Path*/
 112         MAPS_ROUTE_SEGMENTS_MANEUVERS   /**< Indicates that the Route Data
 113         Structure is defined as a list of Segments while each segment is defined
 114         as a list of Maneuvers*/
 115 } maps_service_data_e;
 116
 117 /**
 118  * @brief       The Maps Service handle
 119  * @details The Maps Service handle can be created by calling of maps_service_create().
 120  * \n To release the handle use maps_service_destroy().
 121  * @since_tizen 2.4
 122  *
 123  * @see maps_service_create()
 124  * @see maps_service_destroy()
 125  */
 126 typedef void *maps_service_h;
 127
 128
 129 /**
 130  * @brief       Called when requesting available Maps Providers.
 131  * @details A Maps Service invokes this callback iteratively as long as available Maps Providers exist.
 132  * @since_tizen 2.4
 133  * @remarks The string @a maps_provider must be released using free().
 134  *
 135  * @param[in]   maps_provider   The info of Maps Provider
 136  * @param[in]   user_data       The user data passed from
 137  * maps_service_foreach_provider()
 138  * @return      @c true to continue with the next iteration of the loop, \n @c
 139  * false to break out of the loop
 140  *
 141  * @pre maps_service_foreach_provider() will invoke this callback.
 142  *
 143  * @see maps_service_foreach_provider()
 144  * @see maps_service_create()
 145  */
 146 typedef bool(*maps_service_provider_info_cb) (char *maps_provider,
 147                                               void *user_data);
 148
 149 /**
 150  * @brief       Gets available Maps Providers.
 151  * @details This function delivers available Maps Providers via
 152  * maps_service_provider_info_cb() callback.
 153  * @since_tizen 2.4
 154  *
 155  * @param[in]   callback        The callback function to receive available Maps Providers
 156  * information
 157  * @param[out]  user_data       The user data to be passed to the callback function
 158  * @return      0 on success, otherwise a negative error value
 159  * @retval      #MAPS_ERROR_NONE Successful
 160  * @retval      #MAPS_ERROR_INVALID_PARAMETER Invalid parameter
 161  * @retval      #MAPS_ERROR_NOT_FOUND Result not found
 162  *
 163  * @post This function invokes maps_service_provider_info_cb() to deliver Maps
 164  * Provider information.
 165  *
 166  * @see maps_service_provider_info_cb()
 167  * @see maps_service_create()
 168  */
 169 int maps_service_foreach_provider(maps_service_provider_info_cb callback,
 170                                   void *user_data);
 171
 172 /**
 173  * @brief       Creates a new Maps Service and assigns it with a handle.
 174  * @details While Maps Service is being created, a Maps Provider is initialized
 175  * and linked with Maps Service handle.
 176  * \n A Maps Service handle is used to query Maps Provider performing services,
 177  * such as Geocoding, Searching Places and Routing.
 178  * @since_tizen 2.4
 179  * @privlevel public
 180  * @privilege %http://tizen.org/privilege/mapservice \n
 181  *            %http://tizen.org/privilege/network.get
 182  *
 183  * @remarks @a maps service handle must be released using maps_service_destroy().
 184  * \n use maps_service_foreach_provider() to choose one of available Providers.
 185  * \n use maps_service_set_provider_key() to set provider's key.
 186  * \n use use maps_service_set_preference() to set various options of Maps Provider.
 187  * \n use maps_service_provider_is_service_supported() and maps_service_provider_is_data_supported()
 188  * to check the Maps Provider's capabilities
 189  *
 190  * @param[in]   maps_provider   The name of Maps Provider
 191  * @param[out]  maps            A handle of the new Maps Service on success
 192  * @return      0 on success, otherwise a negative error value
 193  * @retval      #MAPS_ERROR_NONE Successful
 194  * @retval      #MAPS_ERROR_OUT_OF_MEMORY Out of memory
 195  * @retval      #MAPS_ERROR_INVALID_PARAMETER Invalid parameter
 196  * @retval      #MAPS_ERROR_SERVICE_NOT_AVAILABLE Service not available
 197  * @retval      #MAPS_ERROR_NOT_SUPPORTED Not supported
 198  * @retval      #MAPS_ERROR_PERMISSION_DENIED Permission Denied
 199  *
 200  * @pre Call maps_service_foreach_provider() to get a available Maps Providers.
 201  *
 202  * @see maps_service_foreach_provider()
 203  * @see maps_service_destroy()
 204  * @see maps_service_geocode()
 205  * @see maps_service_geocode_inside_area()
 206  * @see maps_service_reverse_geocode()
 207  * @see maps_service_search_place()
 208  * @see maps_service_search_place_by_area()
 209  * @see maps_service_search_place_by_address()
 210  * @see maps_service_search_route()
 211  * @see maps_service_search_route_waypoints()
 212  * @see maps_service_set_provider_key()
 213  * @see maps_service_set_preference()
 214  * @see maps_service_provider_is_service_supported()
 215  * @see maps_service_provider_is_data_supported()
 216  */
 217 int maps_service_create(const char *maps_provider, maps_service_h *maps);
 218
 219 /**
 220  * @brief       Destroys the Maps Service handle and releases all its resources.
 221  * @details This function releases all used resources of the Maps Service and Maps Provider.
 222  * @since_tizen 2.4
 223  * @privlevel public
 224  * @privilege %http://tizen.org/privilege/mapservice
 225  *
 226  * @param[in]   maps            The Maps Service handle to destroy
 227  * @return      0 on success, otherwise a negative error value
 228  * @retval      #MAPS_ERROR_NONE Successful
 229  * @retval      #MAPS_ERROR_INVALID_PARAMETER Invalid parameter
 230  * @retval      #MAPS_ERROR_NOT_SUPPORTED Not supported
 231  *
 232  * @pre Call maps_service_create() to create Maps Service and get its handle.
 233  *
 234  * @see maps_service_create()
 235  */
 236 int maps_service_destroy(maps_service_h maps);
 237
 238 /**
 239  * @brief       Sets the Maps Key to be used in the requests of Maps Service.
 240  * @details This function sets the Maps Provider's Key which will be used in each Maps
 241  * Service request to Maps Provider.
 242  * \n Maps key can be obtained with maps_service_get_provider_key().
 243  * @since_tizen 2.4
 244  * @remarks To get the @a provider_key, refer to corresponding Maps Provider
 245  * documentation.
 246  * \n To get app_id and app_code of HERE, visit https://developer.here.com/, https://developer.here.com/rest-apis.
 247  *
 248  * @param[in]   maps            The Maps Service handle
 249  * @param[in]   provider_key    The Maps Key to be used
 250  * \n In case of combining two more strings, use slash("/") as a delimiter.
 251  * \n e.g. For HERE "app_id/app_code"
 252  * @return      0 on success, otherwise a negative error value
 253  * @retval      #MAPS_ERROR_NONE Successful
 254  * @retval      #MAPS_ERROR_INVALID_PARAMETER Invalid parameter
 255  * @retval      #MAPS_ERROR_NOT_SUPPORTED Not supported
 256  *
 257  * @pre Call maps_service_create() to create Maps Service and get its handle.
 258  *
 259  * @see maps_service_create()
 260  * @see maps_service_get_provider_key()
 261  */
 262 int maps_service_set_provider_key(maps_service_h maps,
 263                                   const char *provider_key);
 264
 265 /**
 266  * @brief       Gets the Maps Key which is to be used in the Maps Service
 267  * requests
 268  * @details This function gets the Maps Key which is to be used in each Maps
 269  * Service request to Maps Provider.
 270  * \n Maps key can be set with maps_service_set_provider_key().
 271  * @since_tizen 2.4
 272  * @remarks The string @a provider_key must be released using free().
 273  * \n @a maps_service_get_provider_key is always synchronous function.
 274  *
 275  * @param[in]   maps            The Maps Service handle
 276  * @param[out]  provider_key    The Maps Key
 277  * @return      0 on success, otherwise a negative error value
 278  * @retval      #MAPS_ERROR_NONE Successful
 279  * @retval      #MAPS_ERROR_INVALID_PARAMETER Invalid parameter
 280  * @retval      #MAPS_ERROR_NOT_SUPPORTED Not supported
 281  *
 282  * @pre Call maps_service_create() to create Maps Service and get its handle.
 283  *
 284  * @see maps_service_set_provider_key()
 285  * @see maps_service_create()
 286  */
 287 int maps_service_get_provider_key(const maps_service_h maps,
 288                                   char **provider_key);
 289
 290 /**
 291  * @brief       Sets the Maps Preference.
 292  * @details This function sets the Maps Preferences which are used in each Maps
 293  * Service request to Maps Provider.
 294  * @since_tizen 2.4
 295  *
 296  * @param[in]   maps            The handle of Maps Service
 297  * @param[in]   preference      The handle of Maps Preference
 298  * @return      0 on success, otherwise a negative error value
 299  * @retval      #MAPS_ERROR_NONE Successful
 300  * @retval      #MAPS_ERROR_INVALID_PARAMETER Invalid parameter
 301  * @retval      #MAPS_ERROR_NOT_SUPPORTED Not supported
 302  * @retval      #MAPS_ERROR_PERMISSION_DENIED Permission Denied
 303  *
 304  * @pre Call maps_service_create() to create Maps Service and get its handle.
 305  *
 306  * @see maps_service_get_preference()
 307  * @see maps_service_create()
 308  */
 309 int maps_service_set_preference(maps_service_h maps,
 310                                 maps_preference_h preference);
 311
 312 /**
 313  * @brief       Gets the Maps Preference.
 314  * @details This function gets the Maps Preferences which are used in each Maps
 315  * Service request to Maps Provider.
 316  * \n Preferences can be set with maps_service_set_preference().
 317  * @since_tizen 2.4
 318  * @remarks @a preference must be released using maps_preference_destroy().
 319  * \n @a maps_service_get_preference is always synchronous function.
 320  *
 321  * @param[in]   maps            The handle of Maps Service
 322  * @param[out]  preference      The handle of Maps Preference
 323  * @return      0 on success, otherwise a negative error value
 324  * @retval      #MAPS_ERROR_NONE Successful
 325  * @retval      #MAPS_ERROR_INVALID_PARAMETER Invalid parameter
 326  * @retval      #MAPS_ERROR_NOT_SUPPORTED Not supported
 327  *
 328  * @pre Call maps_service_create() to create Maps Service and get its handle.
 329  *
 330  * @see maps_service_set_preference()
 331  * @see maps_service_create()
 332  */
 333 int maps_service_get_preference(maps_service_h maps,
 334                                 maps_preference_h *preference);
 335
 336 /**
 337  * @brief       Checks if the Maps Service supports a request.
 338  * @details This function checks if the Maps Service supports a specified request.
 339  * @since_tizen 2.4
 340  * @remarks @a maps_service_provider_is_service_supported is always synchronous
 341  * function.
 342  *
 343  * @param[in]   maps            The handle of Maps Service
 344  * @param[in]   service         The service to be checked
 345  * @param[out]  supported       Is the service supported
 346  * @return      0 on success, otherwise a negative error value
 347  * @retval      #MAPS_ERROR_NONE Successful, the service is supported
 348  * @retval      #MAPS_ERROR_INVALID_PARAMETER Invalid parameter
 349  * @retval      #MAPS_ERROR_NOT_SUPPORTED Not supported
 350  *
 351  * @pre Call maps_service_create() to create Maps Service and get its handle.
 352  *
 353  * @see maps_service_create()
 354  */
 355 int maps_service_provider_is_service_supported(const maps_service_h maps,
 356                                                maps_service_e service,
 357                                                bool *supported);
 358
 359 /**
 360  * @brief       Checks if the Maps Service supports a data feature.
 361  * @details This function checks if the Maps Service supports a specified data
 362  * feature.
 363  * @since_tizen 2.4
 364  * @remarks @a maps_service_provider_is_data_supported is always synchronous
 365  * function.
 366  *
 367  * @param[in]   maps            The handle of Maps Service
 368  * @param[in]   data            The data feature to be checked
 369  * @param[out]  supported       Is the data feature supported
 370  * @return      0 on success, otherwise a negative error value
 371  * @retval      #MAPS_ERROR_NONE Successful, the data feature is supported
 372  * @retval      #MAPS_ERROR_INVALID_PARAMETER Invalid parameter
 373  * @retval      #MAPS_ERROR_NOT_SUPPORTED Not supported
 374  *
 375  * @pre Call maps_service_create() to create Maps Service and get its handle.
 376  *
 377  * @see maps_service_create()
 378  */
 379 int maps_service_provider_is_data_supported(const maps_service_h maps,
 380                                             maps_service_data_e data,
 381                                             bool *supported);
 382
 383 /*----------------------------------------------------------------------------*/
 384 /*
 385  * Cancel Service Request
 386  */
 387
 388 /**
 389  * @brief       Cancels the service request.
 390  * @details This function cancels the service request initiated by geocode,
 391  * route or place search.
 392  * @since_tizen 2.4
 393  * @privlevel public
 394  * @privilege %http://tizen.org/privilege/mapservice
 395  *
 396  * @param[in]   maps            The Maps Service handle
 397  * @param[in]   request_id      The id of request
 398  * @return      0 on success, otherwise a negative error value
 399  * @retval      #MAPS_ERROR_NONE Successful
 400  * @retval      #MAPS_ERROR_INVALID_PARAMETER Invalid parameter
 401  * @retval      #MAPS_ERROR_NETWORK_UNREACHABLE Network connection failed
 402  * @retval      #MAPS_ERROR_SERVICE_NOT_AVAILABLE Service not available
 403  * @retval      #MAPS_ERROR_PERMISSION_DENIED Permission Denied
 404  * @retval      #MAPS_ERROR_NOT_SUPPORTED Not supported
 405  * @retval      #MAPS_ERROR_CONNECTION_TIME_OUT Timeout error, no answer
 406  * @retval      #MAPS_ERROR_INVALID_OPERATION Operation is not valid
 407  * @retval      #MAPS_ERROR_NOT_FOUND Result not found
 408  * @retval      #MAPS_ERROR_KEY_NOT_AVAILABLE Invalid key
 409  * @retval      #MAPS_ERROR_UNKNOWN Unknown error
 410  *
 411  * @pre @a request_id is obtained from one of followings:
 412  *  * maps_service_geocode()
 413  *  * maps_service_geocode_inside_area()
 414  *  * maps_service_geocode_by_structured_address()
 415  *  * maps_service_reverse_geocode()
 416  *  * maps_service_search_place()
 417  *  * maps_service_search_place_by_area()
 418  *  * maps_service_search_place_by_address()
 419  *  * maps_service_search_route()
 420  *  * maps_service_search_route_waypoints()
 421  * .
 422  * @pre Call maps_service_create() to create Maps Service and get its handle.
 423  *
 424  * @see maps_service_geocode()
 425  * @see maps_service_geocode_inside_area()
 426  * @see maps_service_geocode_by_structured_address()
 427  * @see maps_service_reverse_geocode()
 428  * @see maps_service_search_place()
 429  * @see maps_service_search_place_by_area()
 430  * @see maps_service_search_place_by_address()
 431  * @see maps_service_search_route()
 432  * @see maps_service_search_route_waypoints()
 433  */
 434 int maps_service_cancel_request(const maps_service_h maps, int request_id);
 435
 436 /**
 437  * @}
 438  */
 439
 440 /*----------------------------------------------------------------------------*/
 441 /*
 442  * Geocoder Service
 443  */
 444
 445 /**
 446  *
 447  * @ingroup     CAPI_MAPS_SERVICE_MODULE
 448  * @defgroup    CAPI_MAPS_GEOCODER_MODULE Geocoder
 449  *
 450  * @addtogroup CAPI_MAPS_GEOCODER_MODULE
 451  * @{
 452  * @brief This provides APIs for Geocoder Service
 453  * @details The Maps Geocoding API allows mapping an address to its geographical
 454  * location defined in terms of latitude and longitude; the input can be a
 455  * qualified, structured address or a free form single search text with full
 456  * or partial address information.
 457  * \n The Maps Reverse Geocoding API allows to inverse mapping a geographical
 458  * location (longitude, latitude) to an address;
 459  * it can be used to answer the question "Where am I?".
 460  *
 461  */
 462
 463 /**
 464  * @brief       Called once for each position coordinates converted from the
 465  * given address information.
 466  * @details The Maps Service invokes this callback while iterating through the
 467  * list of obtained coordinates of the specified place.
 468  * \n If search is failed, the value of @a total is 0 and @a coordinates is NULL
 469  * @since_tizen 2.4
 470  * @remarks The parameter @a coordinates must be released using
 471  * maps_coordinates_destroy().
 472  *
 473  * @param[in]   result          The result of request
 474  * @param[in]   request_id      The id of request
 475  * @param[in]   index           The current index of coordinates in result set,
 476  * start from 0
 477  * @param[in]   total           The total number of results
 478  * @param[in]   coordinates     The coordinates of the place
 479  * @param[in]   user_data       The user data passed from maps_service_geocode()
 480  * or maps_service_geocode_inside_area()
 481  * @return      @c true to continue with the next iteration of the loop, \n @c
 482  * false to break out of the loop
 483  *
 484  * @pre maps_service_geocode() or maps_service_geocode_inside_area() will invoke
 485  * this callback.
 486  *
 487  * @see maps_service_geocode()
 488  * @see maps_service_geocode_inside_area()
 489  * @see maps_service_cancel_request()
 490  */
 491 typedef bool(*maps_service_geocode_cb) (maps_error_e result, int request_id,
 492                                         int index, int total,
 493                                         maps_coordinates_h coordinates,
 494                                         void *user_data);
 495
 496 /**
 497  * @brief       Called when the address information is converted from position
 498  * information.
 499  * @details The Maps Service invokes this callback when the address is obtained
 500  * from the specified coordinates.
 501  * \n If search is failed, the value of @a total is 0 and @a address is NULL
 502  * @remarks The parameter @a address must be released using
 503  * maps_address_destroy().
 504  * @since_tizen 2.4
 505  *
 506  * @param[in]   result          The result of request
 507  * @param[in]   request_id      The id of request
 508  * @param[in]   index           The current index of address data in result set,
 509  * start from 0
 510  * @param[in]   total           The total number of results
 511  * @param[in]   address         The requested address information
 512  * @param[in]   user_data       The user data passed from
 513  * maps_service_reverse_geocode()
 514  *
 515  * @pre maps_service_reverse_geocode() will invoke this callback.
 516  *
 517  * @see maps_service_reverse_geocode()
 518  * @see maps_service_cancel_request()
 519  */
 520 typedef void (*maps_service_reverse_geocode_cb) (maps_error_e result,
 521                                                  int request_id, int index,
 522                                                  int total,
 523                                                  maps_address_h address,
 524                                                  void *user_data);
 525
 526 /**
 527  * @brief       Gets the position coordinates for a given address. The request
 528  * is asynchronous.
 529  * @details This function obtains position coordinates for a given free-formed
 530  * address string.
 531  * @since_tizen 2.4
 532  * @privlevel public
 533  * @privilege %http://tizen.org/privilege/mapservice \n
 534  *            %http://tizen.org/privilege/internet \n
 535  *            %http://tizen.org/privilege/network.get
 536  * @remarks %http://tizen.org/privilege/internet is needed to access internet.
 537  * \n To cancel the request, use maps_service_cancel_request().
 538  * \n To check if Maps Provider is capable of geocoding and which preferences of
 539  * geocoding are supported, see the lists of capacities and preferences above.
 540  *
 541  * @param[in]   maps            The Maps Service handle
 542  * @param[in]   address         The free-formed address
 543  * @param[in]   preference      The set of preferences for processing geocoding
 544  * @param[in]   callback        The callback which will receive position
 545  * coordinates
 546  * @param[in]   user_data       The user data to be passed to the callback function
 547  * @param[out]  request_id      The id of request
 548  * @return      0 on success, otherwise a negative error value
 549  * @retval      #MAPS_ERROR_NONE Successful
 550  * @retval      #MAPS_ERROR_INVALID_PARAMETER Invalid parameter
 551  * @retval      #MAPS_ERROR_NETWORK_UNREACHABLE Network connection failed
 552  * @retval      #MAPS_ERROR_SERVICE_NOT_AVAILABLE Service not available
 553  * @retval      #MAPS_ERROR_PERMISSION_DENIED Permission Denied
 554  * @retval      #MAPS_ERROR_NOT_SUPPORTED Not supported
 555  * @retval      #MAPS_ERROR_CONNECTION_TIME_OUT Timeout error, no answer
 556  * @retval      #MAPS_ERROR_INVALID_OPERATION Operation is not valid
 557  * @retval      #MAPS_ERROR_NOT_FOUND Result not found
 558  * @retval      #MAPS_ERROR_KEY_NOT_AVAILABLE Invalid key
 559  * @retval      #MAPS_ERROR_UNKNOWN Unknown error
 560  *
 561  * @pre Call maps_service_create() to create Maps Service and obtain its handle.
 562  * @post It invokes maps_service_geocode_cb() to deliver obtained position
 563  * coordinates.
 564  *
 565  * @see maps_service_geocode_inside_area()
 566  * @see maps_service_geocode_cb()
 567  * @see maps_service_cancel_request()
 568  * @see maps_service_reverse_geocode()
 569  */
 570 int maps_service_geocode(const maps_service_h maps, const char *address,
 571                          const maps_preference_h preference,
 572                          maps_service_geocode_cb callback, void *user_data,
 573                          int *request_id);
 574
 575 /**
 576  * @brief       Gets the position for a given address, within the specified
 577  * bounding box. The request is asynchronous.
 578  * @details This function obtains position coordinates for a given free-formed
 579  * address string within the specified bounding box.
 580  * @since_tizen 2.4
 581  * @privlevel public
 582  * @privilege %http://tizen.org/privilege/mapservice \n
 583  *            %http://tizen.org/privilege/internet \n
 584  *            %http://tizen.org/privilege/network.get
 585  * @remarks %http://tizen.org/privilege/internet is needed to access internet.
 586  * \n Polygonal bounding box is not supported.
 587  * \n To cancel the request, use maps_service_cancel_request().
 588  * \n To check if Maps Provider is capable of geocoding and which preferences of
 589  * geocoding are supported, see the lists of capacities and preferences above.
 590  *
 591  * @param[in]   maps            The Maps Service handle
 592  * @param[in]   address         The free-formed address
 593  * @param[in]   bounds          The bounding box
 594  * @param[in]   preference      The set of preferences for processing geocoding
 595  * @param[in]   callback        The callback which will receive position
 596  * coordinates
 597  * @param[in]   user_data       The user data to be passed to the callback function
 598  * @param[out]  request_id      The id of request
 599  * @return      0 on success, otherwise a negative error value
 600  * @retval      #MAPS_ERROR_NONE Successful
 601  * @retval      #MAPS_ERROR_INVALID_PARAMETER Invalid parameter
 602  * @retval      #MAPS_ERROR_NETWORK_UNREACHABLE Network connection failed
 603  * @retval      #MAPS_ERROR_SERVICE_NOT_AVAILABLE Service not available
 604  * @retval      #MAPS_ERROR_PERMISSION_DENIED Permission Denied
 605  * @retval      #MAPS_ERROR_NOT_SUPPORTED Not supported
 606  * @retval      #MAPS_ERROR_KEY_NOT_AVAILABLE Invalid key
 607  * @retval      #MAPS_ERROR_CONNECTION_TIME_OUT Timeout error, no answer
 608  * @retval      #MAPS_ERROR_INVALID_OPERATION Operation is not valid
 609  * @retval      #MAPS_ERROR_NOT_FOUND Result not found
 610  * @retval      #MAPS_ERROR_KEY_NOT_AVAILABLE Invalid key
 611  * @retval      #MAPS_ERROR_UNKNOWN Unknown error
 612  *
 613  * @pre Call maps_service_create() to create Maps Service and obtain its handle.
 614  * @post It invokes maps_service_geocode_cb() to deliver obtained position
 615  * coordinates.
 616  *
 617  * @see maps_service_geocode_by_structured_address()
 618  * @see maps_service_geocode_inside_area()
 619  * @see maps_service_geocode_cb()
 620  * @see maps_service_geocode()
 621  * @see maps_service_cancel_request()
 622  * @see maps_service_reverse_geocode()
 623  */
 624 int maps_service_geocode_inside_area(const maps_service_h maps,
 625                                      const char *address,
 626                                      const maps_area_h bounds,
 627                                      const maps_preference_h preference,
 628                                      maps_service_geocode_cb callback,
 629                                      void *user_data, int *request_id);
 630
 631 /**
 632  * @brief       Gets the position coordinates for a given address. The request
 633  * is asynchronous.
 634  * @details This function obtains position coordinates for a given structured
 635  * address.
 636  * @since_tizen 2.4
 637  * @privlevel public
 638  * @privilege %http://tizen.org/privilege/mapservice \n
 639  *            %http://tizen.org/privilege/internet \n
 640  *            %http://tizen.org/privilege/network.get
 641  * @remarks %http://tizen.org/privilege/internet is needed to access internet.
 642  * \n To cancel the request, use maps_service_cancel_request().
 643  * \n To check if Maps Provider is capable of geocoding and which preferences of
 644  * geocoding are supported, see the lists of capacities and preferences above.
 645  *
 646  * @param[in]   maps            The Maps Service handle
 647  * @param[in]   address         The structured address
 648  * @param[in]   preference      The set of preferences for processing geocoding
 649  * @param[in]   callback        The callback which will receive position
 650  * coordinates
 651  * @param[in]   user_data       The user data to be passed to the callback function
 652  * @param[out]  request_id      The id of request
 653  * @return      0 on success, otherwise a negative error value
 654  * @retval      #MAPS_ERROR_NONE Successful
 655  * @retval      #MAPS_ERROR_INVALID_PARAMETER Invalid parameter
 656  * @retval      #MAPS_ERROR_NETWORK_UNREACHABLE Network connection failed
 657  * @retval      #MAPS_ERROR_SERVICE_NOT_AVAILABLE Service not available
 658  * @retval      #MAPS_ERROR_PERMISSION_DENIED Permission Denied
 659  * @retval      #MAPS_ERROR_NOT_SUPPORTED Not supported
 660  * @retval      #MAPS_ERROR_CONNECTION_TIME_OUT Timeout error, no answer
 661  * @retval      #MAPS_ERROR_INVALID_OPERATION Operation is not valid
 662  * @retval      #MAPS_ERROR_NOT_FOUND Result not found
 663  * @retval      #MAPS_ERROR_KEY_NOT_AVAILABLE Invalid key
 664  * @retval      #MAPS_ERROR_UNKNOWN Unknown error
 665  *
 666  * @pre Call maps_service_create() to create Maps Service and obtain its handle.
 667  * @post It invokes maps_service_geocode_cb() to deliver obtained position
 668  * coordinates.
 669
 670  * @see maps_service_geocode()
 671  * @see maps_service_geocode_inside_area()
 672  * @see maps_service_geocode_cb()
 673  * @see maps_service_cancel_request()
 674  * @see maps_service_reverse_geocode()
 675  */
 676 int maps_service_geocode_by_structured_address(const maps_service_h maps,
 677                                                const maps_address_h address,
 678                                                const maps_preference_h
 679                                                preference,
 680                                                maps_service_geocode_cb
 681                                                callback, void *user_data,
 682                                                int *request_id);
 683
 684 /**
 685  * @brief       Gets the address for a given position coordinates. The request
 686  * is asynchronous.
 687  * @details This function obtains structured address information for a given
 688  * position coordinates.
 689  * @since_tizen 2.4
 690  * @privlevel public
 691  * @privilege %http://tizen.org/privilege/mapservice \n
 692  *            %http://tizen.org/privilege/internet \n
 693  *            %http://tizen.org/privilege/network.get
 694  * @remarks %http://tizen.org/privilege/internet is needed to access internet.
 695  * \n To cancel the request, use maps_service_cancel_request().
 696  * \n To check if Maps Provider is capable of reverse geocoding and which
 697  * preferences of reverse geocoding are supported, see the lists of capacities
 698  * and preferences above.
 699  *
 700  * @param[in]   maps            The Maps Service handle
 701  * @param[in]   latitude        The latitude [-90.0 ~ 90.0] (degrees)
 702  * @param[in]   longitude       The longitude [-180.0 ~ 180.0] (degrees)
 703  * @param[in]   preference      The set of preferences for processing reverse geocoding
 704  * @param[in]   callback        The callback which will receive address information
 705  * @param[in]   user_data       The user data to be passed to the callback function
 706  * @param[out]  request_id      The id of request
 707  * @return      0 on success, otherwise a negative error value
 708  * @retval      #MAPS_ERROR_NONE Successful
 709  * @retval      #MAPS_ERROR_INVALID_PARAMETER Invalid parameter
 710  * @retval      #MAPS_ERROR_NETWORK_UNREACHABLE Network connection failed
 711  * @retval      #MAPS_ERROR_SERVICE_NOT_AVAILABLE Service not available
 712  * @retval      #MAPS_ERROR_PERMISSION_DENIED Permission Denied
 713  * @retval      #MAPS_ERROR_NOT_SUPPORTED Not supported
 714  * @retval      #MAPS_ERROR_CONNECTION_TIME_OUT Timeout error, no answer
 715  * @retval      #MAPS_ERROR_INVALID_OPERATION Operation is not valid
 716  * @retval      #MAPS_ERROR_NOT_FOUND Result not found
 717  * @retval      #MAPS_ERROR_KEY_NOT_AVAILABLE Invalid key
 718  * @retval      #MAPS_ERROR_UNKNOWN Unknown error
 719  *
 720  * @pre Call maps_service_create() to create Maps Service and obtain its handle.
 721  * @post This function invokes maps_service_reverse_geocode_cb().
 722  *
 723  * @see maps_service_reverse_geocode_cb()
 724  * @see maps_service_cancel_request()
 725  * @see maps_service_geocode()
 726  */
 727 int maps_service_reverse_geocode(const maps_service_h maps, double latitude,
 728                                  double longitude,
 729                                  const maps_preference_h preference,
 730                                  maps_service_reverse_geocode_cb callback,
 731                                  void *user_data, int *request_id);
 732
 733 /**
 734  * @}
 735  */
 736
 737 /*----------------------------------------------------------------------------*/
 738 /*
 739  * Place Service
 740  */
 741
 742 /**
 743  * @ingroup     CAPI_MAPS_SERVICE_MODULE
 744  * @defgroup    CAPI_MAPS_PLACE_MODULE Places
 745  *
 746  * @addtogroup CAPI_MAPS_PLACE_MODULE
 747  * @{
 748  * @brief This provides APIs for Place Service
 749  * @details The Maps Place API allows to find places that are relevant to user
 750  * discovery context.
 751  *
 752  */
 753
 754 /**
 755  * @brief       Called for each result of Place Search request
 756  * @details The Maps Service invokes this callback while iterating through the
 757  * set of obtained Place data.
 758  * \n If search is failed, the value of @a total is 0 and @a place is NULL
 759  * @since_tizen 2.4
 760  * @remarks The parameter @a place must be released using maps_place_destroy().
 761  *
 762  * @param[in]   error           The result of request
 763  * @param[in]   request_id      The request id
 764  * @param[in]   index           The current index of place data in result set,
 765  * start from 0
 766  * @param[in]   total           The total number of results
 767  * @param[in]   place           The resulting Place data
 768  * @param[in]   uesr_data       The user data passed from
 769  * maps_service_search_place(), maps_service_search_place_by_area() or
 770  * maps_service_search_place_by_address()
 771  * @return      @c true to continue with the next iteration of the loop, \n @c
 772  * false to break out of the loop
 773  *
 774  * @pre maps_service_search_place(), maps_service_search_place_by_area() or
 775  * maps_service_search_place_by_address() will invoke this callback.
 776  *
 777  * @see maps_service_search_place()
 778  * @see maps_service_search_place_by_area()
 779  * @see maps_service_search_place_by_address()
 780  */
 781 typedef bool(*maps_service_search_place_cb) (maps_error_e error,
 782                                              int request_id, int index,
 783                                              int total, maps_place_h place,
 784                                              void *user_data);
 785
 786 /**
 787  * @brief       Queries a Place information by a coordinates position and a
 788  * distance. The request is asynchronous.
 789  * @details This function obtains the Place information for a specified distance
 790  * around a given coordinates position.
 791  * @since_tizen 2.4
 792  * @privlevel public
 793  * @privilege %http://tizen.org/privilege/mapservice \n
 794  *            %http://tizen.org/privilege/internet \n
 795  *            %http://tizen.org/privilege/network.get
 796  * @remarks %http://tizen.org/privilege/internet is needed to access internet.
 797  * \n To cancel the search request use maps_service_cancel_request().
 798  * \n To check if Maps Provider is capable of Place Search and which Place
 799  * preferences are supported, see the lists of capacities and preferences above.
 800  * \n The distance unit for searching places supports metric
 801  * but doesn't support imperial.
 802  * Even though applications set #maps_distance_unit_e using maps_preference_set_distance_unit(),
 803  * the unit of distance is meter.
 804  *
 805  * @param[in]   maps            The Maps Service handle
 806  * @param[in]   position        The interested position
 807  * @param[in]   distance        The search area distance in meters
 808  * @param[in]   filter          The filter handle
 809  * @param[in]   preference      The place preference handle
 810  * @param[in]   callback        The result callback
 811  * @param[in]   user_data       The user data to be passed to the callback function
 812  * @param[out]  request_id      The request id
 813  * @return      0 on success, otherwise a negative error value
 814  * @retval      #MAPS_ERROR_NONE Successful
 815  * @retval      #MAPS_ERROR_OUT_OF_MEMORY Out of memory
 816  * @retval      #MAPS_ERROR_INVALID_PARAMETER Invalid parameter
 817  * @retval      #MAPS_ERROR_SERVICE_NOT_AVAILABLE Service not available
 818  * @retval      #MAPS_ERROR_PERMISSION_DENIED Permission Denied
 819  * @retval      #MAPS_ERROR_NOT_SUPPORTED Not supported
 820  * @retval      #MAPS_ERROR_CONNECTION_TIME_OUT Timeout error, no answer
 821  * @retval      #MAPS_ERROR_INVALID_OPERATION Operation is not valid
 822  * @retval      #MAPS_ERROR_NOT_FOUND Result not found
 823  * @retval      #MAPS_ERROR_KEY_NOT_AVAILABLE Invalid key
 824  * @retval      #MAPS_ERROR_RESOURCE_BUSY Places service busy
 825  * @retval      #MAPS_ERROR_CANCELED Places service aborted
 826  * @retval      #MAPS_ERROR_UNKNOWN Unknown error
 827  *
 828  * @pre Call maps_service_create() to create Maps Service and obtain its handle.
 829  * @post It invokes maps_service_search_place_cb() to deliver obtained Place
 830  * information.
 831  *
 832  * @see maps_service_search_place_by_area()
 833  * @see maps_service_search_place_by_address()
 834  * @see maps_service_cancel_request()
 835  * @see maps_service_search_place_cb()
 836  */
 837 int maps_service_search_place(const maps_service_h maps,
 838                               const maps_coordinates_h position, int distance,
 839                               const maps_place_filter_h filter,
 840                               maps_preference_h preference,
 841                               maps_service_search_place_cb callback,
 842                               void *user_data, int *request_id);
 843
 844 /**
 845  * @brief       Queries a Place information by a coordinates boundary. The
 846  * request is asynchronous.
 847  * @details This function obtains the Place information for a specified
 848  * coordinates boundary.
 849  * @since_tizen 2.4
 850  * @privlevel public
 851  * @privilege %http://tizen.org/privilege/mapservice \n
 852  *            %http://tizen.org/privilege/internet \n
 853  *            %http://tizen.org/privilege/network.get
 854  * @remarks %http://tizen.org/privilege/internet is needed to access internet.
 855  * \n @a boundary is supporting only circle type bounds for search.
 856  * \n To cancel the search request use maps_service_cancel_request().
 857  * \n To check if Maps Provider is capable of Place Search and which Place
 858  * preferences are supported, see the lists of capacities and preferences above.
 859  * \n The distance unit for searching places doesn't support imperial but supports metric.
 860  * Even though applications set maps_distance_unit_e using maps_preference_set_distance_unit(),
 861  * the unit of radius of boundary is meter.
 862  *
 863  * @param[in]   maps            The Maps Service handle
 864  * @param[in]   boundary        The interested area
 865  * @param[in]   filter          The filter handle
 866  * @param[in]   preference      The place preference handle
 867  * @param[in]   callback        The result callback
 868  * @param[in]   user_data       The user data to be passed to the callback function
 869  * @param[out]  request_id      The request id
 870  * @return      0 on success, otherwise a negative error value
 871  * @retval      #MAPS_ERROR_NONE Successful
 872  * @retval      #MAPS_ERROR_OUT_OF_MEMORY Out of memory
 873  * @retval      #MAPS_ERROR_INVALID_PARAMETER   Invalid parameter
 874  * @retval      #MAPS_ERROR_SERVICE_NOT_AVAILABLE Service not available
 875  * @retval      #MAPS_ERROR_PERMISSION_DENIED Permission Denied
 876  * @retval      #MAPS_ERROR_NOT_SUPPORTED Not supported
 877  * @retval      #MAPS_ERROR_CONNECTION_TIME_OUT Timeout error, no answer
 878  * @retval      #MAPS_ERROR_INVALID_OPERATION Operation is not valid
 879  * @retval      #MAPS_ERROR_NOT_FOUND Result not found
 880  * @retval      #MAPS_ERROR_KEY_NOT_AVAILABLE Invalid key
 881  * @retval      #MAPS_ERROR_RESOURCE_BUSY Places service busy
 882  * @retval      #MAPS_ERROR_CANCELED Places service aborted
 883  * @retval      #MAPS_ERROR_UNKNOWN Unknown error
 884  *
 885  * @pre Call maps_service_create() to create Maps Service and obtain its
 886  * handle.
 887  * @post It invokes maps_service_search_place_cb() to deliver obtained Place
 888  * information.
 889  *
 890  * @see maps_service_search_place()
 891  * @see maps_service_search_place_by_address()
 892  * @see maps_service_cancel_request()
 893  * @see maps_service_search_place_cb()
 894  */
 895 int maps_service_search_place_by_area(const maps_service_h maps,
 896                                       const maps_area_h boundary,
 897                                       const maps_place_filter_h filter,
 898                                       maps_preference_h preference,
 899                                       maps_service_search_place_cb callback,
 900                                       void *user_data, int *request_id);
 901
 902 /**
 903  * @brief       Queries a Place information by a free-formed address string.
 904  * The request is asynchronous.
 905  * @details This function obtains the Place information for a specified free-
 906  * formed address string.
 907  * @since_tizen 2.4
 908  * @privlevel public
 909  * @privilege %http://tizen.org/privilege/mapservice \n
 910  *            %http://tizen.org/privilege/internet \n
 911  *            %http://tizen.org/privilege/network.get
 912  * @remarks %http://tizen.org/privilege/internet is needed to access internet.
 913  * \n @a boundary is supporting only circle type bounds for search.
 914  * \n To cancel the search request use maps_service_cancel_request().
 915  * \n To check if Maps Provider is capable of Place Search and which Place
 916  * preferences are supported, see the lists of capacities and preferences above.
 917  *
 918  * @param[in]   maps            The Maps Service handle
 919  * @param[in]   address         The interested address
 920  * @param[in]   boundary        The interested area
 921  * @param[in]   filter          The filter handle
 922  * @param[in]   preference      The place preference handle
 923  * @param[in]   callback        The result callback
 924  * @param[in]   user_data       The user data to be passed to the callback function
 925  * @param[out]  request_id      The request id
 926  * @return      0 on success, otherwise a negative error value
 927  * @retval      #MAPS_ERROR_NONE Successful
 928  * @retval      #MAPS_ERROR_OUT_OF_MEMORY Out of memory
 929  * @retval      #MAPS_ERROR_INVALID_PARAMETER   Invalid parameter
 930  * @retval      #MAPS_ERROR_SERVICE_NOT_AVAILABLE Service not available
 931  * @retval      #MAPS_ERROR_PERMISSION_DENIED Permission Denied
 932  * @retval      #MAPS_ERROR_NOT_SUPPORTED Not supported
 933  * @retval      #MAPS_ERROR_CONNECTION_TIME_OUT Timeout error, no answer
 934  * @retval      #MAPS_ERROR_INVALID_OPERATION Operation is not valid
 935  * @retval      #MAPS_ERROR_NOT_FOUND Result not found
 936  * @retval      #MAPS_ERROR_KEY_NOT_AVAILABLE Invalid key
 937  * @retval      #MAPS_ERROR_RESOURCE_BUSY Places service busy
 938  * @retval      #MAPS_ERROR_CANCELED Places service aborted
 939  * @retval      #MAPS_ERROR_UNKNOWN Unknown error
 940  *
 941  * @pre Call maps_service_create() to create Maps Service and obtain its handle.
 942  * @post It invokes maps_service_search_place_cb() to deliver obtained Place
 943  * information.
 944  *
 945  * @see maps_service_search_place()
 946  * @see maps_service_search_place_by_area()
 947  * @see maps_service_cancel_request()
 948  * @see maps_service_search_place_cb()
 949  */
 950 int maps_service_search_place_by_address(const maps_service_h maps,
 951                                          const char *address,
 952                                          const maps_area_h boundary,
 953                                          const maps_place_filter_h filter,
 954                                          maps_preference_h preference,
 955                                          maps_service_search_place_cb
 956                                          callback, void *user_data,
 957                                          int *request_id);
 958
 959 /**
 960  * @}
 961  */
 962
 963 /*----------------------------------------------------------------------------*/
 964 /*
 965  * Route Service
 966  */
 967
 968 /**
 969  * @ingroup     CAPI_MAPS_SERVICE_MODULE
 970  * @defgroup    CAPI_MAPS_ROUTE_MODULE Routes
 971  *
 972  * @addtogroup CAPI_MAPS_ROUTE_MODULE
 973  * @{
 974  * @brief This provides APIs for Rote Service
 975  * @details The Maps Route API provides ways to calculate a route that defines a
 976  * path between a start and a destination and may,
 977  * optionally, pass through specific intermediate locations.
 978  *
 979  */
 980
 981 /**
 982  * @brief       Called when the requested Routes are found.
 983  * @details The Maps Service invokes this callback while iterating through the
 984  * set of obtained Routes.
 985  * \n If search is failed, the value of @a total is 0 and @a route is NULL.
 986  * @since_tizen 2.4
 987  * @remarks The parameter @a route must be released using maps_route_destroy().
 988  *
 989  * @param[in]   error           The result of request
 990  * @param[in]   request_id      The id of request
 991  * @param[in]   index           The current index of Route in result set, start
 992  * from 0
 993  * @param[in]   total           The total number of result
 994  * @param[in]   route           The Route data
 995  * @param[in]   user_data       The user data passed from
 996  * maps_service_search_route() or maps_service_search_route_waypoints()
 997  * @return      @c true to continue with the next iteration of the loop, \n @c
 998  * false to break out of the loop
 999  *
1000  * @pre maps_service_search_route() or maps_service_search_route_waypoints()
1001  * will invoke this callback.
1002  *
1003  * @see maps_service_search_route()
1004  * @see maps_service_search_route_waypoints()
1005  * @see maps_service_cancel_request()
1006  */
1007 typedef bool(*maps_service_search_route_cb) (maps_error_e error,
1008                                              int request_id, int index,
1009                                              int total, maps_route_h route,
1010                                              void *user_data);
1011
1012 /**
1013  * @brief       Queries the Route from origin coordinate to a destination.
1014  * The request is asynchronous.
1015  * @details This function gets the Route information for a specified origin and
1016  * destination coordinates.
1017  * @since_tizen 2.4
1018  * @privlevel public
1019  * @privilege %http://tizen.org/privilege/mapservice \n
1020  *            %http://tizen.org/privilege/internet \n
1021  *            %http://tizen.org/privilege/network.get
1022  * @remarks %http://tizen.org/privilege/internet is needed to access internet.
1023  * \n To cancel the search request use maps_service_cancel_request().
1024  * \n To check if Maps Provider is capable of Route Search and which Route
1025  * preferences are supported, see the lists of capacities and preferences above.
1026  *
1027  * @param[in]   maps            The Maps Service handle
1028  * @param[in]   origin          The starting point
1029  * @param[in]   destination     The destination
1030  * @param[in]   preference      The Route preference handle
1031  * @param[in]   callback        The result callback
1032  * @param[in]   user_data       The user data to be passed to the callback function
1033  * @param[out]  request_id      The request id
1034  * @return      0 on success, otherwise a negative error value
1035  * @retval      #MAPS_ERROR_NONE Successful
1036  * @retval      #MAPS_ERROR_OUT_OF_MEMORY Out of memory
1037  * @retval      #MAPS_ERROR_INVALID_PARAMETER Invalid parameter
1038  * @retval      #MAPS_ERROR_PERMISSION_DENIED Permission Denied
1039  * @retval      #MAPS_ERROR_NOT_SUPPORTED Not supported
1040  * @retval      #MAPS_ERROR_CONNECTION_TIME_OUT Timeout error, no answer
1041  * @retval      #MAPS_ERROR_INVALID_OPERATION Operation is not valid
1042  * @retval      #MAPS_ERROR_NOT_FOUND Result not found
1043  * @retval      #MAPS_ERROR_KEY_NOT_AVAILABLE Invalid key
1044  * @retval      #MAPS_ERROR_UNKNOWN Unknown error
1045  *
1046  * @pre Call maps_service_create() to create Maps Service and get its handle.
1047  * @post It invokes maps_service_search_route_cb() to deliver obtained Route
1048  * information.
1049  *
1050  * @see maps_service_search_route_waypoints()
1051  * @see maps_service_cancel_request()
1052  * @see maps_service_search_route_cb()
1053  */
1054 int maps_service_search_route(const maps_service_h maps,
1055                               const maps_coordinates_h origin,
1056                               const maps_coordinates_h destination,
1057                               maps_preference_h preference,
1058                               maps_service_search_route_cb callback,
1059                               void *user_data, int *request_id);
1060
1061 /**
1062  * @brief       Queries the Route, passing through a specified way points. The
1063  * request is asynchronous.
1064  * @details This function gets the Route information for the Route, passing
1065  * through a specified set of way points.
1066  * @since_tizen 2.4
1067  * @privlevel public
1068  * @privilege %http://tizen.org/privilege/mapservice \n
1069  *            %http://tizen.org/privilege/internet \n
1070  *            %http://tizen.org/privilege/network.get
1071  * @remarks %http://tizen.org/privilege/internet is needed to access internet.
1072  * \n To cancel the search request use maps_service_cancel_request().
1073  * \n To check if Maps Provider is capable of Route Search and which Route
1074  * preferences are supported, see the lists of capacities and preferences above.
1075  *
1076  * @param[in]   maps            The Maps Service handle
1077  * @param[in]   waypoint_list   The list of way points to go through
1078  * @param[in]   waypoint_num    The number of way points to go through
1079  * @param[in]   preference      The Route preference handle
1080  * @param[in]   callback        The result callback
1081  * @param[in]   user_data       The user data to be passed to the callback function
1082  * @param[out]  request_id      The request id
1083  * @return      0 on success, otherwise a negative error value
1084  * @retval      #MAPS_ERROR_NONE Successful
1085  * @retval      #MAPS_ERROR_OUT_OF_MEMORY Out of memory
1086  * @retval      #MAPS_ERROR_INVALID_PARAMETER Invalid parameter
1087  * @retval      #MAPS_ERROR_NOT_SUPPORTED Service unavailable
1088  * @retval      #MAPS_ERROR_PERMISSION_DENIED Permission Denied
1089  * @retval      #MAPS_ERROR_CONNECTION_TIME_OUT Timeout error, no answer
1090  * @retval      #MAPS_ERROR_INVALID_OPERATION Operation is not valid
1091  * @retval      #MAPS_ERROR_NOT_FOUND Result not found
1092  * @retval      #MAPS_ERROR_KEY_NOT_AVAILABLE Invalid key
1093  * @retval      #MAPS_ERROR_UNKNOWN Unknown error
1094  *
1095  * @pre Call maps_service_create() to create Maps Service and get its handle.
1096  * @post It invokes maps_service_search_route_cb() to deliver obtained Route
1097  * information.
1098  *
1099  * @see maps_service_search_route()
1100  * @see maps_service_cancel_request()
1101  * @see maps_service_search_route_cb()
1102  */
1103 int maps_service_search_route_waypoints(const maps_service_h maps,
1104                                         const maps_coordinates_h *
1105                                         waypoint_list, int waypoint_num,
1106                                         maps_preference_h preference,
1107                                         maps_service_search_route_cb callback,
1108                                         void *user_data, int *request_id);
1109
1110 /**
1111  * @}
1112  */
1113
1114 #ifdef __cplusplus
1115 }
1116 #endif
1117 #endif                          /* __MAPS_SERVICE_H__ */