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