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_types.h>
  22 #include <maps_error.h>
  23 #include <maps_address.h>
  24 #include <maps_area.h>
  25 #include <maps_coordinates.h>
  26 #include <maps_place.h>
  27 #include <maps_place_filter.h>
  28 #include <maps_route.h>
  29 #include <maps_view.h>
  30
  31 /**
  32  *
  33  * @file maps_service.h
  34  * @brief This file contains the top level functions of Maps API
  35  *
  36  */
  37
  38 #ifdef __cplusplus
  39 extern "C" {
  40 #endif
  41
  42 /*----------------------------------------------------------------------------*/
  43 /*
  44  * Maps Service and Preference
  45  */
  46
  47 /**
  48  * @ingroup     CAPI_MAPS_SERVICE_MODULE
  49  * @defgroup    CAPI_MAPS_SERVICE_AND_PREFERENCE_MODULE Service and Providers
  50  *
  51  * @addtogroup CAPI_MAPS_SERVICE_AND_PREFERENCE_MODULE
  52  * @{
  53  * @brief This provides APIs related Search and Preference.
  54  *
  55  */
  56
  57 /**
  58  * @brief       Enumerations of maps requests available in the Maps Service
  59  * @since_tizen @if MOBILE 2.4 @elseif WEARABLE 2.3.2 @endif
  60  */
  61 typedef enum _maps_service_e {
  62         MAPS_SERVICE_GEOCODE,                                   /**< Indicates that maps_service_geocode() service is allowed */
  63         MAPS_SERVICE_GEOCODE_INSIDE_AREA,               /**< Indicates that maps_service_geocode_inside_area() service is allowed */
  64         MAPS_SERVICE_GEOCODE_BY_STRUCTURED_ADDRESS,     /**< Indicates that     maps_service_geocode_by_structured_address() service is allowed */
  65         MAPS_SERVICE_REVERSE_GEOCODE,                   /**< Indicates that maps_service_reverse_geocode() service is allowed */
  66         MAPS_SERVICE_SEARCH_PLACE,                              /**< Indicates that maps_service_search_place() service is allowed */
  67         MAPS_SERVICE_SEARCH_PLACE_BY_AREA,              /**< Indicates that maps_service_search_place_by_area() service is allowed */
  68         MAPS_SERVICE_SEARCH_PLACE_BY_ADDRESS,   /**< Indicates that maps_service_search_place_by_address() service is allowed */
  69         MAPS_SERVICE_SEARCH_ROUTE,                              /**< Indicates that maps_service_search_route() service is allowed */
  70         MAPS_SERVICE_SEARCH_ROUTE_WAYPOINTS,    /**< Indicates that maps_service_search_route_waypoints() service is allowed */
  71         MAPS_SERVICE_CANCEL_REQUEST,                    /**< Indicates that maps_service_cancel_request() service is allowed */
  72         MAPS_SERVICE_MULTI_REVERSE_GEOCODE,             /**< Indicates that maps_service_multi_reverse_geocode() service is allowed @if MOBILE (Since 3.0) @endif */
  73         MAPS_SERVICE_SEARCH_PLACE_LIST,                 /**< Indicates that maps_service_search_place_list() service is allowed @if MOBILE (Since 3.0) @endif */
  74         MAPS_SERVICE_SEARCH_GET_PLACE_DETAILS,  /**< Indicates that maps_service_search_get_place_details() service is allowed @if MOBILE (Since 3.0) @endif */
  75
  76         MAPS_SERVICE_VIEW = 0x100,                              /**< Indicates that maps view service is allowed @if MOBILE (Since 3.0) @endif */
  77         MAPS_SERVICE_VIEW_SNAPSHOT                              /**< Indicates that maps view snapshot service is allowed @if MOBILE (Since 3.0) @endif */
  78 } maps_service_e;
  79
  80 /**
  81  * @brief Enumerations of maps features available in the Maps Service
  82  * @since_tizen @if MOBILE 2.4 @elseif WEARABLE 2.3.2 @endif
  83  */
  84 typedef enum _maps_service_data_e {
  85         MAPS_PLACE_ADDRESS,                             /**< Indicates the availability of address value in the Place data */
  86         MAPS_PLACE_RATING,                              /**< Indicates the availability of rating value in the Place data */
  87         MAPS_PLACE_CATEGORIES,                  /**< Indicates the availability of place category list in the Place data */
  88         MAPS_PLACE_ATTRIBUTES,                  /**< Indicates the availability of place attribute list in the Place data */
  89         MAPS_PLACE_CONTACTS,                    /**< Indicates the availability of place contact list in the Place data */
  90         MAPS_PLACE_EDITORIALS,                  /**< Indicates the availability of place editorial list in the Place data */
  91         MAPS_PLACE_REVIEWS,                             /**< Indicates the availability of place review list in the Place data */
  92         MAPS_PLACE_IMAGE,                               /**< Indicates the availability of place image in Place the data */
  93         MAPS_PLACE_SUPPLIER,                    /**< Indicates the availability of place supplier link value in the Place data */
  94         MAPS_PLACE_RELATED,                             /**< Indicates the availability of related place link in the Place data */
  95         MAPS_ROUTE_PATH,                                /**< Indicates that the Route Data Structure is defined as a Path (a list of geographical coordinates) */
  96         MAPS_ROUTE_SEGMENTS_PATH,               /**< Indicates that the Route Data Structure is defined as a list of Segments while each segment is defined as a Path */
  97         MAPS_ROUTE_SEGMENTS_MANEUVERS,  /**< Indicates that the Route Data Structure is defined as a list of Segments while each segment is defined as a list of Maneuvers*/
  98
  99         MAPS_VIEW_TRAFFIC = 0x100,              /**< Indicates the availability of traffic information on the Map @if MOBILE (Since 3.0) @endif */
 100         MAPS_VIEW_PUBLIC_TRANSIT,               /**< Indicates the availability of public transit information on the Map @if MOBILE (Since 3.0) @endif */
 101         MAPS_VIEW_BUILDING,                             /**< Indicates the availability of 3D building drawable on the Map @if MOBILE (Since 3.0) @endif */
 102         MAPS_VIEW_SCALEBAR                              /**< Indicates the availability of scale bar on the Map @if MOBILE (Since 3.0) @endif */
 103 } maps_service_data_e;
 104
 105
 106 /**
 107  * @brief       Called when requesting available Maps Providers.
 108  * @details A Maps Service invokes this callback iteratively as long as available Maps Providers exist.
 109  * @since_tizen @if MOBILE 2.4 @elseif WEARABLE 2.3.2 @endif
 110  * @remarks The string @a maps_provider must be released using free().
 111  *
 112  * @param[in]   maps_provider   The info of Maps Provider
 113  * @param[in]   user_data       The user data passed from
 114  * maps_service_foreach_provider()
 115  * @return      @c true to continue with the next iteration of the loop, \n @c
 116  * false to break out of the loop
 117  *
 118  * @pre maps_service_foreach_provider() will invoke this callback.
 119  *
 120  * @see maps_service_foreach_provider()
 121  * @see maps_service_create()
 122  */
 123 typedef bool(*maps_service_provider_info_cb) (char *maps_provider,
 124                                               void *user_data);
 125
 126 /**
 127  * @brief       Gets available Maps Providers.
 128  * @details This function delivers available Maps Providers via
 129  * maps_service_provider_info_cb() callback.
 130  * @since_tizen @if MOBILE 2.4 @elseif WEARABLE 2.3.2 @endif
 131  *
 132  * @param[in]   callback        The callback function to receive available Maps Providers
 133  * information
 134  * @param[out]  user_data       The user data to be passed to the callback function
 135  * @return      0 on success, otherwise a negative error value
 136  * @retval      #MAPS_ERROR_NONE Successful
 137  * @retval      #MAPS_ERROR_INVALID_PARAMETER Invalid parameter
 138  * @retval      #MAPS_ERROR_NOT_FOUND Result not found
 139  * @retval      #MAPS_ERROR_NOT_SUPPORTED Not supported
 140  *
 141  * @post This function invokes maps_service_provider_info_cb() to deliver Maps
 142  * Provider information.
 143  *
 144  * @see maps_service_provider_info_cb()
 145  * @see maps_service_create()
 146  */
 147 int maps_service_foreach_provider(maps_service_provider_info_cb callback,
 148                                   void *user_data);
 149
 150 /**
 151  * @brief       Called with the information about user's consent.
 152  * @details The Maps Service invokes this callback when the information about user's consent is obtained.
 153  * @since_tizen @if MOBILE 3.0 @elseif WEARABLE 2.3.2 @endif
 154  *
 155  * @param[in]   consented       The value of User Consent
 156  * @param[in]   maps_provider   The name of Maps Provider
 157  * @param[in]   user_data       The user data passed from maps_service_request_user_consent()
 158  *
 159  * @pre maps_service_request_user_consent() will invoke this callback.
 160  *
 161  * @see maps_service_request_user_consent()
 162  * @see maps_service_create()
 163  */
 164 typedef void(*maps_service_request_user_consent_cb) (bool consented,
 165                                                                 const char *maps_provider, void *user_data);
 166
 167 /**
 168  * @brief       Gets the user's consent to use maps data.
 169  * @details The function gets information whether the user agreed that the application can use maps data.
 170  * If maps_service_request_user_consent() is called when the user didn't agree yet, a popup is shown and
 171  * the user can decide whether to agree or not. Then the result is saved and maps_service_request_user_consent_cb()
 172  * is called. If the user has already agreed, the popup is not shown and only the callback is called.
 173  * The request is asynchronous.
 174  * @since_tizen @if MOBILE 3.0 @elseif WEARABLE 2.3.2 @endif
 175  * @privlevel public
 176  * @privilege %http://tizen.org/privilege/mapservice
 177  *
 178  * @remarks Available map providers can be obtained with maps_service_foreach_provider().
 179  *
 180  * @param[in]   maps_provider   The name of Maps Provider
 181  * @param[in]   callback        The callback which receives the user's consent decision
 182  * @param[in]   user_data       The user data to be passed to the callback function
 183  * @return      0 on success, otherwise a negative error value
 184
 185  * @retval      #MAPS_ERROR_NONE Successful
 186  * @retval      #MAPS_ERROR_INVALID_PARAMETER Invalid parameter
 187  * @retval      #MAPS_ERROR_SERVICE_NOT_AVAILABLE Service not available
 188  * @retval      #MAPS_ERROR_NOT_SUPPORTED Not supported
 189  * @retval      #MAPS_ERROR_PERMISSION_DENIED Permission Denied
 190  *
 191  * @post This function invokes maps_service_request_user_consent_cb() to provide information
 192  * about user consent.
 193  *
 194  * @see maps_service_foreach_provider()
 195  * @see maps_service_request_user_consent_cb()
 196  * @see maps_service_create()
 197  */
 198 int maps_service_request_user_consent(const char *maps_provider,
 199                                                                 maps_service_request_user_consent_cb callback, void *user_data);
 200
 201 /**
 202  * @brief       Creates a new Maps Service and assigns it with a handle.
 203  * @details While Maps Service is being created, a Maps Provider is initialized
 204  * and linked with Maps Service handle.
 205  * \n A Maps Service handle is used to query Maps Provider performing services,
 206  * such as Geocoding, Searching Places and Routing.
 207  * @since_tizen @if MOBILE 2.4 @elseif WEARABLE 2.3.2 @endif
 208  * @privlevel public
 209  * @privilege %http://tizen.org/privilege/mapservice \n
 210  *            %http://tizen.org/privilege/network.get
 211  *
 212  * @remarks @a maps service handle must be released using maps_service_destroy().
 213  * \n use maps_service_foreach_provider() to choose one of available Providers.
 214  * \n use maps_service_set_provider_key() to set provider's key.
 215  * \n use use maps_service_set_preference() to set various options of Maps Provider.
 216  * \n use maps_service_provider_is_service_supported() and
 217  * maps_service_provider_is_data_supported() to check the Maps Provider's
 218  * capabilities
 219  *
 220  * @param[in]   maps_provider   The name of Maps Provider
 221  * @param[out]  maps            A handle of the new Maps Service on success
 222  * @return      0 on success, otherwise a negative error value
 223  * @retval      #MAPS_ERROR_NONE Successful
 224  * @retval      #MAPS_ERROR_OUT_OF_MEMORY Out of memory
 225  * @retval      #MAPS_ERROR_INVALID_PARAMETER Invalid parameter
 226  * @retval      #MAPS_ERROR_SERVICE_NOT_AVAILABLE Service not available
 227  * @retval      #MAPS_ERROR_NOT_SUPPORTED Not supported
 228  * @retval      #MAPS_ERROR_PERMISSION_DENIED Permission Denied
 229  * @retval      #MAPS_ERROR_USER_NOT_CONSENTED The user did not consent
 230  *
 231  * @pre Call maps_service_foreach_provider() to get a available Maps Providers.
 232  *
 233  * @see maps_service_foreach_provider()
 234  * @see maps_service_destroy()
 235  * @see maps_service_geocode()
 236  * @see maps_service_geocode_inside_area()
 237  * @see maps_service_reverse_geocode()
 238  * @see maps_service_search_place()
 239  * @see maps_service_search_place_by_area()
 240  * @see maps_service_search_place_by_address()
 241  * @see maps_service_search_route()
 242  * @see maps_service_search_route_waypoints()
 243  * @see maps_service_set_provider_key()
 244  * @see maps_service_set_preference()
 245  * @see maps_service_provider_is_service_supported()
 246  * @see maps_service_provider_is_data_supported()
 247  */
 248 int maps_service_create(const char *maps_provider, maps_service_h *maps);
 249
 250 /**
 251  * @brief       Destroys the Maps Service handle and releases all its resources.
 252  * @details This function releases all used resources of the Maps Service and Maps Provider.
 253  * @since_tizen @if MOBILE 2.4 @elseif WEARABLE 2.3.2 @endif
 254  * @privlevel public
 255  * @privilege %http://tizen.org/privilege/mapservice
 256  *
 257  * @param[in]   maps            The Maps Service handle to destroy
 258  * @return      0 on success, otherwise a negative error value
 259  * @retval      #MAPS_ERROR_NONE Successful
 260  * @retval      #MAPS_ERROR_INVALID_PARAMETER Invalid parameter
 261  * @retval      #MAPS_ERROR_NOT_SUPPORTED Not supported
 262  * @retval      #MAPS_ERROR_PERMISSION_DENIED Permission Denied
 263  *
 264  * @pre Call maps_service_create() to create Maps Service and get its handle.
 265  *
 266  * @see maps_service_create()
 267  */
 268 int maps_service_destroy(maps_service_h maps);
 269
 270 /**
 271  * @brief       Sets the Maps Key to be used in the requests of Maps Service.
 272  * @details This function sets the Maps Provider's Key which will be used in each Maps
 273  * Service request to Maps Provider.
 274  * \n Maps key can be obtained with maps_service_get_provider_key().
 275  * @since_tizen @if MOBILE 2.4 @elseif WEARABLE 2.3.2 @endif
 276  * @remarks To get the @a provider_key, refer to corresponding Maps Provider
 277  * documentation.
 278  * \n To get app_id and app_code of HERE, visit https://developer.here.com/,
 279  * https://developer.here.com/rest-apis.
 280  *
 281  * @param[in]   maps            The Maps Service handle
 282  * @param[in]   provider_key    The Maps Key to be used
 283  * \n In case of combining two more strings, use slash("/") as a delimiter.
 284  * \n e.g. For HERE "app_id/app_code"
 285  * @return      0 on success, otherwise a negative error value
 286  * @retval      #MAPS_ERROR_NONE Successful
 287  * @retval      #MAPS_ERROR_INVALID_PARAMETER Invalid parameter
 288  * @retval      #MAPS_ERROR_NOT_SUPPORTED Not supported
 289  *
 290  * @pre Call maps_service_create() to create Maps Service and get its handle.
 291  *
 292  * @see maps_service_create()
 293  * @see maps_service_get_provider_key()
 294  */
 295 int maps_service_set_provider_key(maps_service_h maps,
 296                                   const char *provider_key);
 297
 298 /**
 299  * @brief       Gets the Maps Key which is to be used in the Maps Service
 300  * requests
 301  * @details This function gets the Maps Key which is to be used in each Maps
 302  * Service request to Maps Provider.
 303  * \n Maps key can be set with maps_service_set_provider_key().
 304  * @since_tizen @if MOBILE 2.4 @elseif WEARABLE 2.3.2 @endif
 305  * @remarks The string @a provider_key must be released using free().
 306  * \n @a maps_service_get_provider_key is always synchronous function.
 307  *
 308  * @param[in]   maps            The Maps Service handle
 309  * @param[out]  provider_key    The Maps Key
 310  * @return      0 on success, otherwise a negative error value
 311  * @retval      #MAPS_ERROR_NONE Successful
 312  * @retval      #MAPS_ERROR_INVALID_PARAMETER Invalid parameter
 313  * @retval      #MAPS_ERROR_NOT_SUPPORTED Not supported
 314  *
 315  * @pre Call maps_service_create() to create Maps Service and get its handle.
 316  *
 317  * @see maps_service_set_provider_key()
 318  * @see maps_service_create()
 319  */
 320 int maps_service_get_provider_key(const maps_service_h maps,
 321                                   char **provider_key);
 322
 323 /**
 324  * @brief       Sets the Maps Preference.
 325  * @details This function sets the Maps Preferences which are used in each Maps
 326  * Service request to Maps Provider.
 327  * @since_tizen @if MOBILE 2.4 @elseif WEARABLE 2.3.2 @endif
 328  *
 329  * @param[in]   maps            The handle of Maps Service
 330  * @param[in]   preference      The handle of Maps Preference
 331  * @return      0 on success, otherwise a negative error value
 332  * @retval      #MAPS_ERROR_NONE Successful
 333  * @retval      #MAPS_ERROR_INVALID_PARAMETER Invalid parameter
 334  * @retval      #MAPS_ERROR_NOT_SUPPORTED Not supported
 335  * @retval      #MAPS_ERROR_PERMISSION_DENIED Permission Denied
 336  *
 337  * @pre Call maps_service_create() to create Maps Service and get its handle.
 338  *
 339  * @see maps_service_get_preference()
 340  * @see maps_service_create()
 341  */
 342 int maps_service_set_preference(maps_service_h maps,
 343                                 maps_preference_h preference);
 344
 345 /**
 346  * @brief       Gets the Maps Preference.
 347  * @details This function gets the Maps Preferences which are used in each Maps
 348  * Service request to Maps Provider.
 349  * \n Preferences can be set with maps_service_set_preference().
 350  * @since_tizen @if MOBILE 2.4 @elseif WEARABLE 2.3.2 @endif
 351  * @remarks @a preference must be released using maps_preference_destroy().
 352  * \n @a maps_service_get_preference is always synchronous function.
 353  *
 354  * @param[in]   maps            The handle of Maps Service
 355  * @param[out]  preference      The handle of Maps Preference
 356  * @return      0 on success, otherwise a negative error value
 357  * @retval      #MAPS_ERROR_NONE Successful
 358  * @retval      #MAPS_ERROR_INVALID_PARAMETER Invalid parameter
 359  * @retval      #MAPS_ERROR_NOT_SUPPORTED Not supported
 360  *
 361  * @pre Call maps_service_create() to create Maps Service and get its handle.
 362  *
 363  * @see maps_service_set_preference()
 364  * @see maps_service_create()
 365  */
 366 int maps_service_get_preference(maps_service_h maps,
 367                                 maps_preference_h *preference);
 368
 369 /**
 370  * @brief       Checks if the Maps Service supports a request.
 371  * @details This function checks if the Maps Service supports a specified request.
 372  * @since_tizen @if MOBILE 2.4 @elseif WEARABLE 2.3.2 @endif
 373  * @remarks @a maps_service_provider_is_service_supported is always synchronous
 374  * function.
 375  *
 376  * @param[in]   maps            The handle of Maps Service
 377  * @param[in]   service         The service to be checked
 378  * @param[out]  supported       Is the service supported
 379  * @return      0 on success, otherwise a negative error value
 380  * @retval      #MAPS_ERROR_NONE Successful
 381  * @retval      #MAPS_ERROR_INVALID_PARAMETER Invalid parameter
 382  * @retval      #MAPS_ERROR_NOT_SUPPORTED Not supported
 383  *
 384  * @pre Call maps_service_create() to create Maps Service and get its handle.
 385  *
 386  * @see maps_service_create()
 387  */
 388 int maps_service_provider_is_service_supported(const maps_service_h maps,
 389                                                maps_service_e service,
 390                                                bool *supported);
 391
 392 /**
 393  * @brief       Checks if the Maps Service supports a data feature.
 394  * @details This function checks if the Maps Service supports a specified data
 395  * feature.
 396  * @since_tizen @if MOBILE 2.4 @elseif WEARABLE 2.3.2 @endif
 397  * @remarks @a maps_service_provider_is_data_supported is always synchronous
 398  * function.
 399  *
 400  * @param[in]   maps            The handle of Maps Service
 401  * @param[in]   data            The data feature to be checked
 402  * @param[out]  supported       Is the data feature supported
 403  * @return      0 on success, otherwise a negative error value
 404  * @retval      #MAPS_ERROR_NONE Successful
 405  * @retval      #MAPS_ERROR_INVALID_PARAMETER Invalid parameter
 406  * @retval      #MAPS_ERROR_NOT_SUPPORTED Not supported
 407  *
 408  * @pre Call maps_service_create() to create Maps Service and get its handle.
 409  *
 410  * @see maps_service_create()
 411  */
 412 int maps_service_provider_is_data_supported(const maps_service_h maps,
 413                                             maps_service_data_e data,
 414                                             bool *supported);
 415
 416
 417 /*----------------------------------------------------------------------------*/
 418 /*
 419  * Cancel Service Request
 420  */
 421
 422 /**
 423  * @brief       Cancels the service request.
 424  * @details This function cancels the service request initiated by geocoding
 425  * and searching places and routes.
 426
 427  * @since_tizen @if MOBILE 2.4 @elseif WEARABLE 2.3.2 @endif
 428  * @privlevel public
 429  * @privilege %http://tizen.org/privilege/mapservice
 430  *
 431  * @param[in]   maps            The Maps Service handle
 432  * @param[in]   request_id      The id of request
 433  * @return      0 on success, otherwise a negative error value
 434  * @retval      #MAPS_ERROR_NONE Successful
 435  * @retval      #MAPS_ERROR_INVALID_PARAMETER Invalid parameter
 436  * @retval      #MAPS_ERROR_NETWORK_UNREACHABLE Network connection failed
 437  * @retval      #MAPS_ERROR_SERVICE_NOT_AVAILABLE Service not available
 438  * @retval      #MAPS_ERROR_PERMISSION_DENIED Permission Denied
 439  * @retval      #MAPS_ERROR_NOT_SUPPORTED Not supported
 440  * @retval      #MAPS_ERROR_CONNECTION_TIME_OUT Timeout error, no answer
 441  * @retval      #MAPS_ERROR_INVALID_OPERATION Operation is not valid
 442  * @retval      #MAPS_ERROR_NOT_FOUND Result not found
 443  * @retval      #MAPS_ERROR_KEY_NOT_AVAILABLE Invalid key
 444  * @retval      #MAPS_ERROR_UNKNOWN Unknown error
 445  *
 446  * @pre @a request_id is obtained from one of followings:
 447  *  - maps_service_geocode()
 448  *  - maps_service_geocode_inside_area()
 449  *  - maps_service_geocode_by_structured_address()
 450  *  - maps_service_reverse_geocode()
 451  *  - maps_service_search_place()
 452  *  - maps_service_search_place_by_area()
 453  *  - maps_service_search_place_by_address()
 454  *  - maps_service_search_route()
 455  *  - maps_service_search_route_waypoints()
 456  *  .
 457  * @pre Call maps_service_create() to create Maps Service and get its handle.
 458  *
 459  * @see maps_service_geocode()
 460  * @see maps_service_geocode_inside_area()
 461  * @see maps_service_geocode_by_structured_address()
 462  * @see maps_service_reverse_geocode()
 463  * @see maps_service_search_place()
 464  * @see maps_service_search_place_by_area()
 465  * @see maps_service_search_place_by_address()
 466  * @see maps_service_search_route()
 467  * @see maps_service_search_route_waypoints()
 468  */
 469 int maps_service_cancel_request(const maps_service_h maps, int request_id);
 470
 471 /**
 472  * @}
 473  */
 474
 475 /*----------------------------------------------------------------------------*/
 476 /*
 477  * Geocoder Service
 478  */
 479
 480 /**
 481  *
 482  * @ingroup     CAPI_MAPS_SERVICE_MODULE
 483  * @defgroup    CAPI_MAPS_GEOCODER_MODULE Geocoder
 484  *
 485  * @if WEARABLE
 486  * @section     CAPI_MAPS_SERVICE_MODULE_FEATURE Related Features
 487  * This API is related with the following features:\n
 488  *  - http://tizen.org/feature/network.internet\n
 489  *
 490  * It is recommended to design feature related codes in your application for reliability.\n
 491  *
 492  * You can check if a device supports the related features for this API by using
 493  * @ref CAPI_SYSTEM_SYSTEM_INFO_MODULE, thereby controlling the procedure of your application.\n
 494  *
 495  * To ensure your application is only running on the device with specific features,
 496  * please define the features in your manifest file using the manifest editor in the SDK.\n
 497  *
 498  * More details on featuring your application can be found from
 499  * <a href="https://developer.tizen.org/development/getting-started/native-application/understanding-tizen-programming/application-filtering"><b>Feature List</b>.</a>
 500  * @endif
 501  *
 502  * @addtogroup  CAPI_MAPS_GEOCODER_MODULE
 503  * @{
 504  * @brief This provides APIs for Geocoder Service
 505  * @details The Maps Geocoding API allows translating an address to its
 506  * geographical location defined in terms of latitude and longitude;
 507  * the input can be a qualified, structured address or a free form single search
 508  * text with full or partial address information.
 509  * \n The Maps Reverse Geocoding API allows to inverse translating a
 510  * geographical location (longitude, latitude) to an address;
 511  * it can be used to answer the question "Where am I?".
 512  *
 513  */
 514
 515 /**
 516  * @brief       Called once for each position coordinates converted from the
 517  * given address information.
 518  * @details The Maps Service invokes this callback while iterating through the
 519  * list of obtained coordinates of the specified place.
 520  * \n If search is failed, the value of @a total is 0 and @a coordinates is NULL
 521  * @since_tizen @if MOBILE 2.4 @elseif WEARABLE 2.3.2 @endif
 522  * @remarks The parameter @a coordinates must be released using
 523  * maps_coordinates_destroy().
 524  * \n This error code will be reported. \n
 525  *                      #MAPS_ERROR_NONE \n
 526  *                      #MAPS_ERROR_OUT_OF_MEMORY \n
 527  *                      #MAPS_ERROR_INVALID_PARAMETER \n
 528  *                      #MAPS_ERROR_NOT_FOUND.
 529  *
 530  * @param[in]   result          The result of request
 531  * @param[in]   request_id      The id of request
 532  * @param[in]   index           The current index of coordinates in result set,
 533  * start from 0
 534  * @param[in]   total           The total number of results
 535  * @param[in]   coordinates     The coordinates of the place
 536  * @param[in]   user_data       The user data passed from maps_service_geocode()
 537  * or maps_service_geocode_inside_area()
 538  * @return      @c true to continue with the next iteration of the loop, \n @c
 539  * false to break out of the loop
 540  *
 541  * @pre maps_service_geocode() or maps_service_geocode_inside_area() will invoke
 542  * this callback.
 543  *
 544  * @see maps_service_geocode()
 545  * @see maps_service_geocode_inside_area()
 546  * @see maps_service_cancel_request()
 547  */
 548 typedef bool(*maps_service_geocode_cb) (maps_error_e result, int request_id,
 549                                         int index, int total,
 550                                         maps_coordinates_h coordinates,
 551                                         void *user_data);
 552
 553 /**
 554  * @brief       Called when the address information is converted from position
 555  * information.
 556  * @details The Maps Service invokes this callback when the address is obtained
 557  * from the specified coordinates.
 558  * \n If search is failed, the value of @a total is 0 and @a address is NULL
 559  * @remarks The parameter @a address must be released using
 560  * maps_address_destroy().
 561  * \n This error code will be reported. \n
 562  *                      #MAPS_ERROR_NONE \n
 563  *                      #MAPS_ERROR_OUT_OF_MEMORY \n
 564  *                      #MAPS_ERROR_INVALID_PARAMETER \n
 565  *                      #MAPS_ERROR_NOT_FOUND.
 566  * @since_tizen @if MOBILE 2.4 @elseif WEARABLE 2.3.2 @endif
 567  *
 568  * @param[in]   result          The result of request
 569  * @param[in]   request_id      The id of request
 570  * @param[in]   index           The current index of address data in result set,
 571  * start from 0
 572  * @param[in]   total           The total number of results
 573  * @param[in]   address         The requested address information
 574  * @param[in]   user_data       The user data passed from
 575  * maps_service_reverse_geocode()
 576  *
 577  * @pre maps_service_reverse_geocode() will invoke this callback.
 578  *
 579  * @see maps_service_reverse_geocode()
 580  * @see maps_service_cancel_request()
 581  */
 582 typedef void (*maps_service_reverse_geocode_cb) (maps_error_e result,
 583                                                  int request_id, int index,
 584                                                  int total,
 585                                                  maps_address_h address,
 586                                                  void *user_data);
 587
 588 /**
 589  * @brief       Gets the position coordinates for a given address.
 590  * \n The request is asynchronous.
 591  * @details This function obtains position coordinates for a given free-formed
 592  * address string.
 593  * @since_tizen @if MOBILE 2.4 @elseif WEARABLE 2.3.2 @endif
 594  * @privlevel public
 595  * @privilege %http://tizen.org/privilege/mapservice \n
 596  *            %http://tizen.org/privilege/internet \n
 597  *            %http://tizen.org/privilege/network.get
 598  * @remarks To cancel the request, use maps_service_cancel_request().
 599  * \n To check if Maps Provider is capable of geocoding,
 600  * use maps_service_provider_is_service_supported() with
 601  * #MAPS_SERVICE_GEOCODE passed as @a service parameter.
 602  *
 603  * @param[in]   maps            The Maps Service handle
 604  * @param[in]   address         The free-formed address
 605  * @param[in]   preference      The set of preferences for processing geocoding
 606  * @param[in]   callback        The callback which will receive position
 607  * coordinates
 608  * @param[in]   user_data       The user data to be passed to the callback function
 609  * @param[out]  request_id      The id of request
 610  * @return      0 on success, otherwise a negative error value
 611  * @retval      #MAPS_ERROR_NONE Successful
 612  * @retval      #MAPS_ERROR_INVALID_PARAMETER Invalid parameter
 613  * @retval      #MAPS_ERROR_NETWORK_UNREACHABLE Network connection failed
 614  * @retval      #MAPS_ERROR_SERVICE_NOT_AVAILABLE Service not available
 615  * @retval      #MAPS_ERROR_PERMISSION_DENIED Permission Denied
 616  * @retval      #MAPS_ERROR_NOT_SUPPORTED Not supported
 617  * @retval      #MAPS_ERROR_CONNECTION_TIME_OUT Timeout error, no answer
 618  * @retval      #MAPS_ERROR_INVALID_OPERATION Operation is not valid
 619  * @retval      #MAPS_ERROR_NOT_FOUND Result not found
 620  * @retval      #MAPS_ERROR_KEY_NOT_AVAILABLE Invalid key
 621  * @retval      #MAPS_ERROR_UNKNOWN Unknown error
 622  *
 623  * @pre Call maps_service_create() to create Maps Service and obtain its handle.
 624  * @post It invokes maps_service_geocode_cb() to deliver obtained position
 625  * coordinates.
 626  *
 627  * @see maps_service_geocode_inside_area()
 628  * @see maps_service_geocode_cb()
 629  * @see maps_service_cancel_request()
 630  * @see maps_service_reverse_geocode()
 631  * @see maps_service_provider_is_service_supported()
 632  */
 633 int maps_service_geocode(const maps_service_h maps, const char *address,
 634                          const maps_preference_h preference,
 635                          maps_service_geocode_cb callback, void *user_data,
 636                          int *request_id);
 637
 638 /**
 639  * @brief       Gets the position for a given address, within the specified
 640  * bounding box.
 641  * \n The request is asynchronous.
 642  * @details This function obtains position coordinates for a given free-formed
 643  * address string within the specified bounding box.
 644  * @since_tizen @if MOBILE 2.4 @elseif WEARABLE 2.3.2 @endif
 645  * @privlevel public
 646  * @privilege %http://tizen.org/privilege/mapservice \n
 647  *            %http://tizen.org/privilege/internet \n
 648  *            %http://tizen.org/privilege/network.get
 649  * @remarks Polygonal bounding box is not supported.
 650  * \n To cancel the request, use maps_service_cancel_request().
 651  * \n To check if Maps Provider is capable of geocoding inside area,
 652  * use maps_service_provider_is_service_supported() with
 653  * #MAPS_SERVICE_GEOCODE_INSIDE_AREA passed as @a service parameter.
 654  *
 655  * @param[in]   maps            The Maps Service handle
 656  * @param[in]   address         The free-formed address
 657  * @param[in]   bounds          The bounding box
 658  * @param[in]   preference      The set of preferences for processing geocoding
 659  * @param[in]   callback        The callback which will receive position
 660  * coordinates
 661  * @param[in]   user_data       The user data to be passed to the callback function
 662  * @param[out]  request_id      The id of request
 663  * @return      0 on success, otherwise a negative error value
 664  * @retval      #MAPS_ERROR_NONE Successful
 665  * @retval      #MAPS_ERROR_INVALID_PARAMETER Invalid parameter
 666  * @retval      #MAPS_ERROR_NETWORK_UNREACHABLE Network connection failed
 667  * @retval      #MAPS_ERROR_SERVICE_NOT_AVAILABLE Service not available
 668  * @retval      #MAPS_ERROR_PERMISSION_DENIED Permission Denied
 669  * @retval      #MAPS_ERROR_NOT_SUPPORTED Not supported
 670  * @retval      #MAPS_ERROR_KEY_NOT_AVAILABLE Invalid key
 671  * @retval      #MAPS_ERROR_CONNECTION_TIME_OUT Timeout error, no answer
 672  * @retval      #MAPS_ERROR_INVALID_OPERATION Operation is not valid
 673  * @retval      #MAPS_ERROR_NOT_FOUND Result not found
 674  * @retval      #MAPS_ERROR_KEY_NOT_AVAILABLE Invalid key
 675  * @retval      #MAPS_ERROR_UNKNOWN Unknown error
 676  *
 677  * @pre Call maps_service_create() to create Maps Service and obtain its handle.
 678  * @post It invokes maps_service_geocode_cb() to deliver obtained position
 679  * coordinates.
 680  *
 681  * @see maps_service_geocode_by_structured_address()
 682  * @see maps_service_geocode_inside_area()
 683  * @see maps_service_geocode_cb()
 684  * @see maps_service_geocode()
 685  * @see maps_service_cancel_request()
 686  * @see maps_service_reverse_geocode()
 687  * @see maps_service_provider_is_service_supported()
 688  */
 689 int maps_service_geocode_inside_area(const maps_service_h maps,
 690                                      const char *address,
 691                                      const maps_area_h bounds,
 692                                      const maps_preference_h preference,
 693                                      maps_service_geocode_cb callback,
 694                                      void *user_data, int *request_id);
 695
 696 /**
 697  * @brief       Gets the position coordinates for a given address.
 698  * \n The request is asynchronous.
 699  * @details This function obtains position coordinates for a given structured
 700  * address.
 701  * @since_tizen @if MOBILE 2.4 @elseif WEARABLE 2.3.2 @endif
 702  * @privlevel public
 703  * @privilege %http://tizen.org/privilege/mapservice \n
 704  *            %http://tizen.org/privilege/internet \n
 705  *            %http://tizen.org/privilege/network.get
 706  * @remarks To cancel the request, use maps_service_cancel_request().
 707  * \n To check if Maps Provider is capable of geocoding by structured address,
 708  * use maps_service_provider_is_service_supported() with
 709  * #MAPS_SERVICE_GEOCODE_BY_STRUCTURED_ADDRESS passed as @a service parameter.
 710  *
 711  * @param[in]   maps            The Maps Service handle
 712  * @param[in]   address         The structured address
 713  * @param[in]   preference      The set of preferences for processing geocoding
 714  * @param[in]   callback        The callback which will receive position
 715  * coordinates
 716  * @param[in]   user_data       The user data to be passed to the callback function
 717  * @param[out]  request_id      The id of request
 718  * @return      0 on success, otherwise a negative error value
 719  * @retval      #MAPS_ERROR_NONE Successful
 720  * @retval      #MAPS_ERROR_INVALID_PARAMETER Invalid parameter
 721  * @retval      #MAPS_ERROR_NETWORK_UNREACHABLE Network connection failed
 722  * @retval      #MAPS_ERROR_SERVICE_NOT_AVAILABLE Service not available
 723  * @retval      #MAPS_ERROR_PERMISSION_DENIED Permission Denied
 724  * @retval      #MAPS_ERROR_NOT_SUPPORTED Not supported
 725  * @retval      #MAPS_ERROR_CONNECTION_TIME_OUT Timeout error, no answer
 726  * @retval      #MAPS_ERROR_INVALID_OPERATION Operation is not valid
 727  * @retval      #MAPS_ERROR_NOT_FOUND Result not found
 728  * @retval      #MAPS_ERROR_KEY_NOT_AVAILABLE Invalid key
 729  * @retval      #MAPS_ERROR_UNKNOWN Unknown error
 730  *
 731  * @pre Call maps_service_create() to create Maps Service and obtain its handle.
 732  * @post It invokes maps_service_geocode_cb() to deliver obtained position
 733  * coordinates.
 734
 735  * @see maps_service_geocode()
 736  * @see maps_service_geocode_inside_area()
 737  * @see maps_service_geocode_cb()
 738  * @see maps_service_cancel_request()
 739  * @see maps_service_reverse_geocode()
 740  * @see maps_service_provider_is_service_supported()
 741  */
 742 int maps_service_geocode_by_structured_address(const maps_service_h maps,
 743                                                const maps_address_h address,
 744                                                const maps_preference_h
 745                                                preference,
 746                                                maps_service_geocode_cb
 747                                                callback, void *user_data,
 748                                                int *request_id);
 749
 750 /**
 751  * @brief       Gets the address for a given position coordinates.
 752  * \n The request is asynchronous.
 753  * @details This function obtains structured address information for a given
 754  * position coordinates.
 755  * @since_tizen @if MOBILE 2.4 @elseif WEARABLE 2.3.2 @endif
 756  * @privlevel public
 757  * @privilege %http://tizen.org/privilege/mapservice \n
 758  *            %http://tizen.org/privilege/internet \n
 759  *            %http://tizen.org/privilege/network.get
 760  * @remarks To cancel the request, use maps_service_cancel_request().
 761  * \n To check if Maps Provider is capable of reverse geocoding,
 762  * use maps_service_provider_is_service_supported() with
 763  * #MAPS_SERVICE_REVERSE_GEOCODE passed as @a service parameter.
 764  *
 765  * @param[in]   maps            The Maps Service handle
 766  * @param[in]   latitude        The latitude [-90.0 ~ 90.0] (degrees)
 767  * @param[in]   longitude       The longitude [-180.0 ~ 180.0] (degrees)
 768  * @param[in]   preference      The set of preferences for processing reverse geocoding
 769  * @param[in]   callback        The callback which will receive address information
 770  * @param[in]   user_data       The user data to be passed to the callback function
 771  * @param[out]  request_id      The id of request
 772  * @return      0 on success, otherwise a negative error value
 773  * @retval      #MAPS_ERROR_NONE Successful
 774  * @retval      #MAPS_ERROR_INVALID_PARAMETER Invalid parameter
 775  * @retval      #MAPS_ERROR_NETWORK_UNREACHABLE Network connection failed
 776  * @retval      #MAPS_ERROR_SERVICE_NOT_AVAILABLE Service not available
 777  * @retval      #MAPS_ERROR_PERMISSION_DENIED Permission Denied
 778  * @retval      #MAPS_ERROR_NOT_SUPPORTED Not supported
 779  * @retval      #MAPS_ERROR_CONNECTION_TIME_OUT Timeout error, no answer
 780  * @retval      #MAPS_ERROR_INVALID_OPERATION Operation is not valid
 781  * @retval      #MAPS_ERROR_NOT_FOUND Result not found
 782  * @retval      #MAPS_ERROR_KEY_NOT_AVAILABLE Invalid key
 783  * @retval      #MAPS_ERROR_UNKNOWN Unknown error
 784  *
 785  * @pre Call maps_service_create() to create Maps Service and obtain its handle.
 786  * @post This function invokes maps_service_reverse_geocode_cb().
 787  *
 788  * @see maps_service_reverse_geocode_cb()
 789  * @see maps_service_cancel_request()
 790  * @see maps_service_geocode()
 791  * @see maps_service_provider_is_service_supported()
 792  */
 793 int maps_service_reverse_geocode(const maps_service_h maps, double latitude,
 794                                  double longitude,
 795                                  const maps_preference_h preference,
 796                                  maps_service_reverse_geocode_cb callback,
 797                                  void *user_data, int *request_id);
 798
 799
 800 /**
 801  * @brief       Called when respond to a request of multi reverse geocoding.
 802  * @details The Maps Service invokes this callback once when gets the response
 803  * from map service provider.
 804  * \n The value of @a total is same with requested coordinates list size.
 805  * Even though one of address is not provided valid address handle is retrieved.
 806  * @since_tizen @if MOBILE 3.0 @elseif WEARABLE 2.3.2 @endif
 807  * @remarks     You can get the respective address information of @a address_list
 808  * using maps_address_list_foreach().
 809  * \n This error code will be reported. \n
 810  *                      #MAPS_ERROR_NONE \n
 811  *                      #MAPS_ERROR_OUT_OF_MEMORY \n
 812  *                      #MAPS_ERROR_INVALID_PARAMETER \n
 813  *                      #MAPS_ERROR_NOT_FOUND.
 814  *
 815  * @param[in]   result                  The result of request
 816  * @param[in]   request_id              The id of request
 817  * @param[in]   total                   The total number of results
 818  * @param[in]   address_list            The converted address list from the
 819  * requested coordinates list
 820  * @param[in]   user_data               The user data pointer passed from
 821  * maps_service_multi_reverse_geocode()
 822  * @return      @c true to continue with the next iteration of the loop, \n @c
 823  * false to break out of the loop
 824  *
 825  * @pre maps_service_multi_reverse_geocode() will invoke this callback.
 826  *
 827  * @see maps_service_multi_reverse_geocode()
 828  * @see maps_address_list_foreach()
 829  * @see maps_service_cancel_request()
 830  */
 831 typedef bool (*maps_service_multi_reverse_geocode_cb) (maps_error_e result,
 832                                         int request_id,
 833                                         int total,
 834                                         maps_address_list_h address_list,
 835                                         void *user_data);
 836
 837 /**
 838  * @brief       Gets the address list for a given position coordinates list.
 839  * \n The request is asynchronous.
 840  * @details This function obtains structured address information.
 841  * @since_tizen @if MOBILE 3.0 @elseif WEARABLE 2.3.2 @endif
 842  * @privlevel public
 843  * @privilege %http://tizen.org/privilege/mapservice \n
 844  *            %http://tizen.org/privilege/internet \n
 845  *            %http://tizen.org/privilege/network.get
 846  * @remarks To cancel the request, use maps_service_cancel_request().
 847  * \n To check if Maps Provider is capable of multi reverse geocoding,
 848  * use maps_service_provider_is_service_supported() with
 849  * #MAPS_SERVICE_MULTI_REVERSE_GEOCODE passed as @a service parameter.
 850  *
 851  * @param[in]   maps            The Maps Service handle
 852  * @param[in]   coordinates_list The coordinates list [2 ~ 100] (a set of coordinates)
 853  * @param[in]   preference      The set of preferences for processing Reverse
 854  * Geocode
 855  * @param[in]   callback        The callback which will retrieve address list
 856  * @param[in]   user_data       The user data pointer to be passed to the
 857  * callback
 858  * @param[out]  request_id      The id of request
 859  * @return      0 on success, otherwise a negative error value
 860  * @retval      #MAPS_ERROR_NONE Successful
 861  * @retval      #MAPS_ERROR_INVALID_PARAMETER Invalid parameter
 862  * @retval      #MAPS_ERROR_NETWORK_UNREACHABLE Network connection failed
 863  * @retval      #MAPS_ERROR_SERVICE_NOT_AVAILABLE Service not available
 864  * @retval      #MAPS_ERROR_PERMISSION_DENIED Permission Denied
 865  * @retval      #MAPS_ERROR_NOT_SUPPORTED Not supported
 866  * @retval      #MAPS_ERROR_CONNECTION_TIME_OUT Timeout error, no answer
 867  * @retval      #MAPS_ERROR_INVALID_OPERATION Operation is not valid
 868  * @retval      #MAPS_ERROR_NOT_FOUND Result not found
 869  * @retval      #MAPS_ERROR_KEY_NOT_AVAILABLE Invalid key
 870  * @retval      #MAPS_ERROR_UNKNOWN Unknown error
 871  *
 872  * @pre Call maps_service_create() to create Maps Service and obtain its handle.
 873  * @post This function invokes maps_service_multi_reverse_geocode_cb().
 874  *
 875  * @see maps_service_multi_reverse_geocode_cb()
 876  * @see maps_service_cancel_request()
 877  * @see maps_service_reverse_geocode()
 878  * @see maps_service_provider_is_service_supported()
 879  */
 880 int maps_service_multi_reverse_geocode(const maps_service_h maps,
 881                                 maps_coordinates_list_h coordinates_list,
 882                                 const maps_preference_h preference,
 883                                 maps_service_multi_reverse_geocode_cb callback,
 884                                 void *user_data, int *request_id);
 885 /**
 886  * @}
 887  */
 888
 889 /*----------------------------------------------------------------------------*/
 890 /*
 891  * Place Service
 892  */
 893
 894 /**
 895  * @ingroup     CAPI_MAPS_SERVICE_MODULE
 896  * @defgroup    CAPI_MAPS_PLACE_MODULE Places
 897  *
 898  * @if WEARABLE
 899  * @section     CAPI_MAPS_SERVICE_MODULE_FEATURE Related Features
 900  * This API is related with the following features:\n
 901  *  - http://tizen.org/feature/network.internet\n
 902  *
 903  * It is recommended to design feature related codes in your application for reliability.\n
 904  *
 905  * You can check if a device supports the related features for this API by using
 906  * @ref CAPI_SYSTEM_SYSTEM_INFO_MODULE, thereby controlling the procedure of your application.\n
 907  *
 908  * To ensure your application is only running on the device with specific features,
 909  * please define the features in your manifest file using the manifest editor in the SDK.\n
 910  *
 911  * More details on featuring your application can be found from
 912  * <a href="https://developer.tizen.org/development/getting-started/native-application/understanding-tizen-programming/application-filtering"><b>Feature List</b>.</a>
 913  * @endif
 914  *
 915  * @addtogroup  CAPI_MAPS_PLACE_MODULE
 916  * @{
 917  * @brief This provides APIs for Place Service
 918  * @details The Maps Place API allows to find places that are relevant to user
 919  * discovery context.
 920  *
 921  */
 922
 923 /**
 924  * @brief       Called for each result of Place Search request
 925  * @details The Maps Service invokes this callback while iterating through the
 926  * set of obtained Place data.
 927  * \n If search is failed, the value of @a total is 0 and @a place is NULL
 928  * @since_tizen @if MOBILE 2.4 @elseif WEARABLE 2.3.2 @endif
 929  * @remarks The parameter @a place must be released using maps_place_destroy().
 930  * \n This error code will be reported. \n
 931  *                      #MAPS_ERROR_NONE \n
 932  *                      #MAPS_ERROR_OUT_OF_MEMORY \n
 933  *                      #MAPS_ERROR_INVALID_PARAMETER \n
 934  *                      #MAPS_ERROR_NOT_FOUND.
 935  *
 936  * @param[in]   error           The result of request
 937  * @param[in]   request_id      The request id
 938  * @param[in]   index           The current index of place data in result set,
 939  * start from 0
 940  * @param[in]   total           The total number of results
 941  * @param[in]   place           The resulting Place data
 942  * @param[in]   user_data       The user data passed from
 943  * maps_service_search_place(), maps_service_search_place_by_area() or
 944  * maps_service_search_place_by_address()
 945  * @return      @c true to continue with the next iteration of the loop, \n @c
 946  * false to break out of the loop
 947  *
 948  * @pre maps_service_search_place(), maps_service_search_place_by_area() or
 949  * maps_service_search_place_by_address() will invoke this callback.
 950  *
 951  * @see maps_service_search_place()
 952  * @see maps_service_search_place_by_area()
 953  * @see maps_service_search_place_by_address()
 954  */
 955 typedef bool(*maps_service_search_place_cb) (maps_error_e error,
 956                                              int request_id, int index,
 957                                              int total, maps_place_h place,
 958                                              void *user_data);
 959
 960 /**
 961  * @brief       Called for Place list of Place Search request
 962  * @details The Maps Service invokes this callback when the Place data obtained
 963  * from the specified coordinates.
 964  * \n If search is failed, the value of @a total is 0 and @a place_list is NULL
 965  * @since_tizen @if MOBILE 3.0 @elseif WEARABLE 2.3.2 @endif
 966  * @remarks     The parameter @a place_list must be released using maps_place_list_destroy().
 967  * \n This error code will be reported. \n
 968  *                      #MAPS_ERROR_NONE \n
 969  *                      #MAPS_ERROR_OUT_OF_MEMORY \n
 970  *                      #MAPS_ERROR_INVALID_PARAMETER \n
 971  *                      #MAPS_ERROR_NOT_FOUND.
 972  *
 973  * @param[in]   error           The result of request
 974  * @param[in]   request_id      The request id
 975  * @param[in]   total           The total number of results
 976  * @param[in]   place_list      The resulting Place list data
 977  * @param[in]   user_data       The user data passed from maps_service_search_place_list()
 978  *
 979  * @pre maps_service_search_place_list() will invoke this callback.
 980  *
 981  * @see maps_service_search_place_list()
 982  * @see maps_place_list_foreach()
 983  */
 984 typedef void(*maps_service_search_place_list_cb) (maps_error_e error,
 985                                              int request_id, int total, maps_place_list_h place_list, void *user_data);
 986
 987 /**
 988  * @brief       Called for Place detail information of Place Search request
 989  * @details The Maps Service invokes this callback when the Place detail data
 990  * obtained from the specified uri.
 991  * \n If search is failed, @a place is NULL
 992  * @since_tizen @if MOBILE 3.0 @elseif WEARABLE 2.3.2 @endif
 993  * @remarks The parameter @a place must be released using maps_place_destroy().
 994  * \n This error code will be reported. \n
 995  *                      #MAPS_ERROR_NONE \n
 996  *                      #MAPS_ERROR_OUT_OF_MEMORY \n
 997  *                      #MAPS_ERROR_INVALID_PARAMETER \n
 998  *                      #MAPS_ERROR_NOT_FOUND.
 999  *
1000  * @param[in]   error           The result of request
1001  * @param[in]   request_id      The request id
1002  * @param[in]   place           The resulting Place data
1003  * @param[in]   user_data       The user data passed from maps_service_get_place_details()
1004  *
1005  * @pre maps_service_get_place_details() will invoke this callback.
1006  *
1007  * @see maps_service_get_place_details()
1008  */
1009 typedef void(*maps_service_get_place_details_cb) (maps_error_e error,
1010                                              int request_id, maps_place_h place, void *user_data);
1011
1012 /**
1013  * @brief       Queries a Place information by a coordinates position and a
1014  * distance.
1015  * \n The request is asynchronous.
1016  * @details This function obtains the Place information for a specified distance
1017  * around a given coordinates position.
1018  * @since_tizen @if MOBILE 2.4 @elseif WEARABLE 2.3.2 @endif
1019  * @privlevel public
1020  * @privilege %http://tizen.org/privilege/mapservice \n
1021  *            %http://tizen.org/privilege/internet \n
1022  *            %http://tizen.org/privilege/network.get
1023  * @remarks To cancel the search request, use maps_service_cancel_request().
1024  * \n To check if Maps Provider is capable of searching places, use
1025  * maps_service_provider_is_service_supported() with
1026  * #MAPS_SERVICE_SEARCH_PLACE passed as @a service parameter.
1027  * \n Check available data features in the search result using
1028  * maps_service_provider_is_data_supported() with values, listed in
1029  * #maps_service_data_e passed as @a data parameter.
1030  *
1031  * @param[in]   maps            The Maps Service handle
1032  * @param[in]   position        The interested position
1033  * @param[in]   distance        The search area distance
1034  * @param[in]   filter          The filter handle
1035  * @param[in]   preference      The place preference handle
1036  * @param[in]   callback        The result callback
1037  * @param[in]   user_data       The user data to be passed to the callback function
1038  * @param[out]  request_id      The request id
1039  * @return      0 on success, otherwise a negative error value
1040  * @retval      #MAPS_ERROR_NONE Successful
1041  * @retval      #MAPS_ERROR_OUT_OF_MEMORY Out of memory
1042  * @retval      #MAPS_ERROR_INVALID_PARAMETER Invalid parameter
1043  * @retval      #MAPS_ERROR_SERVICE_NOT_AVAILABLE Service not available
1044  * @retval      #MAPS_ERROR_PERMISSION_DENIED Permission Denied
1045  * @retval      #MAPS_ERROR_NOT_SUPPORTED Not supported
1046  * @retval      #MAPS_ERROR_CONNECTION_TIME_OUT Timeout error, no answer
1047  * @retval      #MAPS_ERROR_INVALID_OPERATION Operation is not valid
1048  * @retval      #MAPS_ERROR_NOT_FOUND Result not found
1049  * @retval      #MAPS_ERROR_KEY_NOT_AVAILABLE Invalid key
1050  * @retval      #MAPS_ERROR_RESOURCE_BUSY Places service busy
1051  * @retval      #MAPS_ERROR_CANCELED Places service aborted
1052  * @retval      #MAPS_ERROR_UNKNOWN Unknown error
1053  *
1054  * @pre Call maps_service_create() to create Maps Service and obtain its handle.
1055  * @post It invokes maps_service_search_place_cb() to deliver obtained Place
1056  * information.
1057  *
1058  * @see maps_service_search_place_by_area()
1059  * @see maps_service_search_place_by_address()
1060  * @see maps_service_cancel_request()
1061  * @see maps_service_search_place_cb()
1062  * @see maps_service_provider_is_service_supported()
1063  * @see maps_service_provider_is_data_supported()
1064  */
1065 int maps_service_search_place(const maps_service_h maps,
1066                               const maps_coordinates_h position, int distance,
1067                               const maps_place_filter_h filter,
1068                               maps_preference_h preference,
1069                               maps_service_search_place_cb callback,
1070                               void *user_data, int *request_id);
1071
1072 /**
1073  * @brief       Queries a Place information by a coordinates boundary.
1074  * \n The request is asynchronous.
1075  * @details This function obtains the Place information for a specified
1076  * coordinates boundary.
1077  * @since_tizen @if MOBILE 2.4 @elseif WEARABLE 2.3.2 @endif
1078  * @privlevel public
1079  * @privilege %http://tizen.org/privilege/mapservice \n
1080  *            %http://tizen.org/privilege/internet \n
1081  *            %http://tizen.org/privilege/network.get
1082  * @remarks @a boundary is supporting only circle type bounds for search.
1083  * \n To cancel the search request, use maps_service_cancel_request().
1084  * \n To check if Maps Provider is capable of searching places by coordinates
1085  * boundaries, use maps_service_provider_is_service_supported() with
1086  * #MAPS_SERVICE_SEARCH_PLACE_BY_AREA  passed as @a service parameter.
1087  * \n Check available data features in the search result using
1088  * maps_service_provider_is_data_supported() with values, listed in
1089  * #maps_service_data_e passed as @a data parameter.
1090  *
1091  * @param[in]   maps            The Maps Service handle
1092  * @param[in]   boundary        The interested area
1093  * @param[in]   filter          The filter handle
1094  * @param[in]   preference      The place preference handle
1095  * @param[in]   callback        The result callback
1096  * @param[in]   user_data       The user data to be passed to the callback function
1097  * @param[out]  request_id      The request id
1098  * @return      0 on success, otherwise a negative error value
1099  * @retval      #MAPS_ERROR_NONE Successful
1100  * @retval      #MAPS_ERROR_OUT_OF_MEMORY Out of memory
1101  * @retval      #MAPS_ERROR_INVALID_PARAMETER   Invalid parameter
1102  * @retval      #MAPS_ERROR_SERVICE_NOT_AVAILABLE Service not available
1103  * @retval      #MAPS_ERROR_PERMISSION_DENIED Permission Denied
1104  * @retval      #MAPS_ERROR_NOT_SUPPORTED Not supported
1105  * @retval      #MAPS_ERROR_CONNECTION_TIME_OUT Timeout error, no answer
1106  * @retval      #MAPS_ERROR_INVALID_OPERATION Operation is not valid
1107  * @retval      #MAPS_ERROR_NOT_FOUND Result not found
1108  * @retval      #MAPS_ERROR_KEY_NOT_AVAILABLE Invalid key
1109  * @retval      #MAPS_ERROR_RESOURCE_BUSY Places service busy
1110  * @retval      #MAPS_ERROR_CANCELED Places service aborted
1111  * @retval      #MAPS_ERROR_UNKNOWN Unknown error
1112  *
1113  * @pre Call maps_service_create() to create Maps Service and obtain its
1114  * handle.
1115  * @post It invokes maps_service_search_place_cb() to deliver obtained Place
1116  * information.
1117  *
1118  * @see maps_service_search_place()
1119  * @see maps_service_search_place_by_address()
1120  * @see maps_service_cancel_request()
1121  * @see maps_service_search_place_cb()
1122  * @see maps_service_provider_is_service_supported()
1123  * @see maps_service_provider_is_data_supported()
1124  */
1125 int maps_service_search_place_by_area(const maps_service_h maps,
1126                                       const maps_area_h boundary,
1127                                       const maps_place_filter_h filter,
1128                                       maps_preference_h preference,
1129                                       maps_service_search_place_cb callback,
1130                                       void *user_data, int *request_id);
1131
1132 /**
1133  * @brief       Queries a Place information by a free-formed address string.
1134  * \n The request is asynchronous.
1135  * @details This function obtains the Place information for a specified
1136  * free-formed address string.
1137  * @since_tizen @if MOBILE 2.4 @elseif WEARABLE 2.3.2 @endif
1138  * @privlevel public
1139  * @privilege %http://tizen.org/privilege/mapservice \n
1140  *            %http://tizen.org/privilege/internet \n
1141  *            %http://tizen.org/privilege/network.get
1142  * @remarks @a boundary is supporting only circle type bounds for search.
1143  * \n To cancel the search request, use maps_service_cancel_request().
1144  * \n To check if Maps Provider is capable of searching places by free-formed
1145  * address, use maps_service_provider_is_service_supported() with
1146  * #MAPS_SERVICE_SEARCH_PLACE_BY_ADDRESS passed as @a service parameter.
1147  * \n Check available data features in the search result using
1148  * maps_service_provider_is_data_supported() with values, listed in
1149  * #maps_service_data_e passed as @a data parameter.
1150  *
1151  * @param[in]   maps            The Maps Service handle
1152  * @param[in]   address         The interested address
1153  * @param[in]   boundary        The interested area
1154  * @param[in]   filter          The filter handle
1155  * @param[in]   preference      The place preference handle
1156  * @param[in]   callback        The result callback
1157  * @param[in]   user_data       The user data to be passed to the callback function
1158  * @param[out]  request_id      The request id
1159  * @return      0 on success, otherwise a negative error value
1160  * @retval      #MAPS_ERROR_NONE Successful
1161  * @retval      #MAPS_ERROR_OUT_OF_MEMORY Out of memory
1162  * @retval      #MAPS_ERROR_INVALID_PARAMETER   Invalid parameter
1163  * @retval      #MAPS_ERROR_SERVICE_NOT_AVAILABLE Service not available
1164  * @retval      #MAPS_ERROR_PERMISSION_DENIED Permission Denied
1165  * @retval      #MAPS_ERROR_NOT_SUPPORTED Not supported
1166  * @retval      #MAPS_ERROR_CONNECTION_TIME_OUT Timeout error, no answer
1167  * @retval      #MAPS_ERROR_INVALID_OPERATION Operation is not valid
1168  * @retval      #MAPS_ERROR_NOT_FOUND Result not found
1169  * @retval      #MAPS_ERROR_KEY_NOT_AVAILABLE Invalid key
1170  * @retval      #MAPS_ERROR_RESOURCE_BUSY Places service busy
1171  * @retval      #MAPS_ERROR_CANCELED Places service aborted
1172  * @retval      #MAPS_ERROR_UNKNOWN Unknown error
1173  *
1174  * @pre Call maps_service_create() to create Maps Service and obtain its handle.
1175  * @post It invokes maps_service_search_place_cb() to deliver obtained Place
1176  * information.
1177  *
1178  * @see maps_service_search_place()
1179  * @see maps_service_search_place_by_area()
1180  * @see maps_service_cancel_request()
1181  * @see maps_service_search_place_cb()
1182  * @see maps_service_provider_is_service_supported()
1183  * @see maps_service_provider_is_data_supported()
1184  */
1185 int maps_service_search_place_by_address(const maps_service_h maps,
1186                                          const char *address,
1187                                          const maps_area_h boundary,
1188                                          const maps_place_filter_h filter,
1189                                          maps_preference_h preference,
1190                                          maps_service_search_place_cb
1191                                          callback, void *user_data,
1192                                          int *request_id);
1193
1194 /**
1195  * @brief       Queries a brief Place information by a coordinates boundary.
1196  * /n The request is asynchronous.
1197  * @details This function obtains the brief Place information for a specified coordinates boundary.
1198  * @since_tizen @if MOBILE 3.0 @elseif WEARABLE 2.3.2 @endif
1199  * @privlevel public
1200  * @privilege %http://tizen.org/privilege/mapservice \n
1201  *            %http://tizen.org/privilege/internet \n
1202  *            %http://tizen.org/privilege/network.get
1203  * @remarks To cancel the search request use maps_service_cancel_request().
1204  * \n To check if Maps Provider is capable of Place Search and which Place preferences are supported,
1205  * see the lists of capacities and preferences above.
1206  *
1207  * @param[in]   maps            The Maps Service handle
1208  * @param[in]   boundary        The interested area
1209  * @param[in]   filter          The filter handle
1210  * @param[in]   preference      The place preference handle
1211  * @param[in]   callback        The result callback
1212  * @param[in]   user_data       The user data to be passed to the callback function
1213  * @param[out]  request_id      The request id
1214  * @return      0 on success, otherwise a negative error value
1215  * @retval      #MAPS_ERROR_NONE Successful
1216  * @retval      #MAPS_ERROR_OUT_OF_MEMORY Out of memory
1217  * @retval      #MAPS_ERROR_INVALID_PARAMETER Invalid parameter
1218  * @retval      #MAPS_ERROR_SERVICE_NOT_AVAILABLE Service not available
1219  * @retval      #MAPS_ERROR_PERMISSION_DENIED Permission Denied
1220  * @retval      #MAPS_ERROR_NOT_SUPPORTED Not supported
1221  * @retval      #MAPS_ERROR_CONNECTION_TIME_OUT Timeout error, no answer
1222  * @retval      #MAPS_ERROR_INVALID_OPERATION Operation is not valid
1223  * @retval      #MAPS_ERROR_NOT_FOUND Result not found
1224  * @retval      #MAPS_ERROR_KEY_NOT_AVAILABLE Invalid key
1225  * @retval      #MAPS_ERROR_RESOURCE_BUSY Places service busy
1226  * @retval      #MAPS_ERROR_CANCELED Places service aborted
1227  * @retval      #MAPS_ERROR_UNKNOWN Unknown error
1228  *
1229  * @pre Call maps_service_create() to create Maps Service and obtain its handle.
1230  * @post It invokes maps_service_search_place_list_cb() to deliver obtained Place information.
1231  *
1232  * @see maps_service_get_place_details()
1233  * @see maps_service_search_place_list_cb()
1234  * @see maps_service_cancel_request()
1235  * @see maps_service_provider_is_service_supported()
1236  */
1237 int maps_service_search_place_list(const maps_service_h maps,
1238                               const maps_area_h boundary,
1239                               const maps_place_filter_h filter,
1240                               maps_preference_h preference,
1241                               maps_service_search_place_list_cb callback,
1242                               void *user_data, int *request_id);
1243
1244 /**
1245  * @brief       Queries a Detail place information by a place uri.
1246  * \n The request is asynchronous.
1247  * @details This function obtains the Detail place information for a specified place uri
1248  * @since_tizen @if MOBILE 3.0 @elseif WEARABLE 2.3.2 @endif
1249  * @privlevel public
1250  * @privilege %http://tizen.org/privilege/mapservice \n
1251  *            %http://tizen.org/privilege/internet \n
1252  *            %http://tizen.org/privilege/network.get
1253  * @remarks To cancel the search request use maps_service_cancel_request().
1254  * \n To check if Maps Provider is capable of Place Search and which Place preferences are supported,
1255  * see the lists of capacities and preferences above.
1256  *
1257  * @param[in]   maps            The Maps Service handle
1258  * @param[in]   uri                     The interested place uri
1259  * @param[in]   callback        The result callback
1260  * @param[in]   user_data       The user data to be passed to the callback function
1261  * @param[out]  request_id      The request id
1262  * @return      0 on success, otherwise a negative error value
1263  * @retval      #MAPS_ERROR_NONE Successful
1264  * @retval      #MAPS_ERROR_OUT_OF_MEMORY Out of memory
1265  * @retval      #MAPS_ERROR_INVALID_PARAMETER Invalid parameter
1266  * @retval      #MAPS_ERROR_SERVICE_NOT_AVAILABLE Service not available
1267  * @retval      #MAPS_ERROR_PERMISSION_DENIED Permission Denied
1268  * @retval      #MAPS_ERROR_NOT_SUPPORTED Not supported
1269  * @retval      #MAPS_ERROR_CONNECTION_TIME_OUT Timeout error, no answer
1270  * @retval      #MAPS_ERROR_INVALID_OPERATION Operation is not valid
1271  * @retval      #MAPS_ERROR_NOT_FOUND Result not found
1272  * @retval      #MAPS_ERROR_KEY_NOT_AVAILABLE Invalid key
1273  * @retval      #MAPS_ERROR_RESOURCE_BUSY Places service busy
1274  * @retval      #MAPS_ERROR_CANCELED Places service aborted
1275  * @retval      #MAPS_ERROR_UNKNOWN Unknown error
1276  *
1277  * @pre Call maps_service_create() to create Maps Service and obtain its handle.
1278  * @pre @a uri is obtained from maps_service_search_place_list()
1279  * @post It invokes maps_service_get_place_details_cb() to deliver obtained Place information.
1280  *
1281  * @see maps_service_search_place_list()
1282  * @see maps_service_get_place_details_cb()
1283  * @see maps_service_cancel_request()
1284  * @see maps_service_provider_is_service_supported()
1285  */
1286 int maps_service_get_place_details(const maps_service_h maps,
1287                               const char *uri, maps_service_get_place_details_cb callback,
1288                               void *user_data, int *request_id);
1289
1290 /**
1291  * @}
1292  */
1293
1294 /*----------------------------------------------------------------------------*/
1295 /*
1296  * Route Service
1297  */
1298
1299 /**
1300  * @ingroup     CAPI_MAPS_SERVICE_MODULE
1301  * @defgroup    CAPI_MAPS_ROUTE_MODULE Routes
1302  *
1303  * @if WEARABLE
1304  * @section     CAPI_MAPS_SERVICE_MODULE_FEATURE Related Features
1305  * This API is related with the following features:\n
1306  *  - http://tizen.org/feature/network.internet\n
1307  *
1308  * It is recommended to design feature related codes in your application for reliability.\n
1309  *
1310  * You can check if a device supports the related features for this API by using
1311  * @ref CAPI_SYSTEM_SYSTEM_INFO_MODULE, thereby controlling the procedure of your application.\n
1312  *
1313  * To ensure your application is only running on the device with specific features,
1314  * please define the features in your manifest file using the manifest editor in the SDK.\n
1315  *
1316  * More details on featuring your application can be found from
1317  * <a href="https://developer.tizen.org/development/getting-started/native-application/understanding-tizen-programming/application-filtering"><b>Feature List</b>.</a>
1318  * @endif
1319  *
1320  * @addtogroup  CAPI_MAPS_ROUTE_MODULE
1321  * @{
1322  * @brief This provides APIs for Route Service
1323  * @details The Maps Route API provides functions to calculate a route that
1324  * defines a path between a origin and a destination and may, optionally, pass
1325  * through specific intermediate locations.
1326  *
1327  */
1328
1329 /**
1330  * @brief       Called when the requested routes are found.
1331  * @details The Maps Service invokes this callback while iterating through the
1332  * set of obtained Routes.
1333  * \n If search is failed, the value of @a total is 0 and @a route is NULL.
1334  * @since_tizen @if MOBILE 2.4 @elseif WEARABLE 2.3.2 @endif
1335  * @remarks The parameter @a route must be released using maps_route_destroy().
1336  * \n This error code will be reported. \n
1337  *                      #MAPS_ERROR_NONE \n
1338  *                      #MAPS_ERROR_OUT_OF_MEMORY \n
1339  *                      #MAPS_ERROR_INVALID_PARAMETER \n
1340  *                      #MAPS_ERROR_NOT_FOUND.
1341  *
1342  * @param[in]   error           The result of request
1343  * @param[in]   request_id      The id of request
1344  * @param[in]   index           The current index of Route in result set, start
1345  * from 0
1346  * @param[in]   total           The total number of result
1347  * @param[in]   route           The Route data
1348  * @param[in]   user_data       The user data passed from
1349  * maps_service_search_route() or maps_service_search_route_waypoints()
1350  * @return      @c true to continue with the next iteration of the loop, \n @c
1351  * false to break out of the loop
1352  *
1353  * @pre maps_service_search_route() or maps_service_search_route_waypoints()
1354  * will invoke this callback.
1355  *
1356  * @see maps_service_search_route()
1357  * @see maps_service_search_route_waypoints()
1358  * @see maps_service_cancel_request()
1359  */
1360 typedef bool(*maps_service_search_route_cb) (maps_error_e error,
1361                                              int request_id, int index,
1362                                              int total, maps_route_h route,
1363                                              void *user_data);
1364
1365 /**
1366  * @brief       Queries the Route from origin coordinates to destination.
1367  * \n The request is asynchronous.
1368  * @details This function gets the Route information for a specified origin and
1369  * destination coordinates.
1370  * @since_tizen @if MOBILE 2.4 @elseif WEARABLE 2.3.2 @endif
1371  * @privlevel public
1372  * @privilege %http://tizen.org/privilege/mapservice \n
1373  *            %http://tizen.org/privilege/internet \n
1374  *            %http://tizen.org/privilege/network.get
1375  * @remarks To cancel the search request, use maps_service_cancel_request().
1376  * \n To check if Maps Provider is capable of searching routes, use
1377  * maps_service_provider_is_service_supported() with
1378  * #MAPS_SERVICE_SEARCH_ROUTE passed as @a service parameter.
1379  * \n Check available data features in the search result using
1380  * maps_service_provider_is_data_supported() with values, listed in
1381  * #maps_service_data_e passed as @a data parameter.
1382  *
1383  * @param[in]   maps            The Maps Service handle
1384  * @param[in]   origin          The starting point
1385  * @param[in]   destination     The destination
1386  * @param[in]   preference      The Route preference handle
1387  * @param[in]   callback        The result callback
1388  * @param[in]   user_data       The user data to be passed to the callback function
1389  * @param[out]  request_id      The request id
1390  * @return      0 on success, otherwise a negative error value
1391  * @retval      #MAPS_ERROR_NONE Successful
1392  * @retval      #MAPS_ERROR_OUT_OF_MEMORY Out of memory
1393  * @retval      #MAPS_ERROR_INVALID_PARAMETER Invalid parameter
1394  * @retval      #MAPS_ERROR_PERMISSION_DENIED Permission Denied
1395  * @retval      #MAPS_ERROR_NOT_SUPPORTED Not supported
1396  * @retval      #MAPS_ERROR_CONNECTION_TIME_OUT Timeout error, no answer
1397  * @retval      #MAPS_ERROR_INVALID_OPERATION Operation is not valid
1398  * @retval      #MAPS_ERROR_NOT_FOUND Result not found
1399  * @retval      #MAPS_ERROR_KEY_NOT_AVAILABLE Invalid key
1400  * @retval      #MAPS_ERROR_UNKNOWN Unknown error
1401  *
1402  * @pre Call maps_service_create() to create Maps Service and get its handle.
1403  * @post It invokes maps_service_search_route_cb() to deliver obtained Route
1404  * information.
1405  *
1406  * @see maps_service_search_route_waypoints()
1407  * @see maps_service_cancel_request()
1408  * @see maps_service_search_route_cb()
1409  * @see maps_service_provider_is_service_supported()
1410  * @see maps_service_provider_is_data_supported()
1411  */
1412 int maps_service_search_route(const maps_service_h maps,
1413                               const maps_coordinates_h origin,
1414                               const maps_coordinates_h destination,
1415                               maps_preference_h preference,
1416                               maps_service_search_route_cb callback,
1417                               void *user_data, int *request_id);
1418
1419 /**
1420  * @brief       Queries the Route, passing through a specified way points.
1421  * \n The request is asynchronous.
1422  * @details This function gets the Route information for the Route, passing
1423  * through a specified set of way points.
1424  * @since_tizen @if MOBILE 2.4 @elseif WEARABLE 2.3.2 @endif
1425  * @privlevel public
1426  * @privilege %http://tizen.org/privilege/mapservice \n
1427  *            %http://tizen.org/privilege/internet \n
1428  *            %http://tizen.org/privilege/network.get
1429  * @remarks To cancel the search request, use maps_service_cancel_request().
1430  * \n To check if Maps Provider is capable of searching the route passing
1431  * through the specified way points, use
1432  * maps_service_provider_is_service_supported() with
1433  * #MAPS_SERVICE_SEARCH_ROUTE_WAYPOINTS passed as @a service parameter.
1434  * \n Check available data features in the search result using
1435  * maps_service_provider_is_data_supported() with values, listed in
1436  * #maps_service_data_e passed as @a data parameter.
1437  *
1438  * @param[in]   maps            The Maps Service handle
1439  * @param[in]   waypoint_list   The list of way points to go through
1440  * @param[in]   waypoint_num    The number of way points to go through
1441  * @param[in]   preference      The Route preference handle
1442  * @param[in]   callback        The result callback
1443  * @param[in]   user_data       The user data to be passed to the callback function
1444  * @param[out]  request_id      The request id
1445  * @return      0 on success, otherwise a negative error value
1446  * @retval      #MAPS_ERROR_NONE Successful
1447  * @retval      #MAPS_ERROR_OUT_OF_MEMORY Out of memory
1448  * @retval      #MAPS_ERROR_INVALID_PARAMETER Invalid parameter
1449  * @retval      #MAPS_ERROR_NOT_SUPPORTED Service unavailable
1450  * @retval      #MAPS_ERROR_PERMISSION_DENIED Permission Denied
1451  * @retval      #MAPS_ERROR_CONNECTION_TIME_OUT Timeout error, no answer
1452  * @retval      #MAPS_ERROR_INVALID_OPERATION Operation is not valid
1453  * @retval      #MAPS_ERROR_NOT_FOUND Result not found
1454  * @retval      #MAPS_ERROR_KEY_NOT_AVAILABLE Invalid key
1455  * @retval      #MAPS_ERROR_UNKNOWN Unknown error
1456  *
1457  * @pre Call maps_service_create() to create Maps Service and get its handle.
1458  * @post It invokes maps_service_search_route_cb() to deliver obtained Route
1459  * information.
1460  *
1461  * @see maps_service_search_route()
1462  * @see maps_service_cancel_request()
1463  * @see maps_service_search_route_cb()
1464  * @see maps_service_provider_is_service_supported()
1465  * @see maps_service_provider_is_data_supported()
1466  */
1467 int maps_service_search_route_waypoints(const maps_service_h maps,
1468                                         const maps_coordinates_h *
1469                                         waypoint_list, int waypoint_num,
1470                                         maps_preference_h preference,
1471                                         maps_service_search_route_cb callback,
1472                                         void *user_data, int *request_id);
1473
1474 /**
1475  * @}
1476  */
1477
1478 #ifdef __cplusplus
1479 }
1480 #endif
1481 #endif                          /* __MAPS_SERVICE_H__ */