include/maps_plugin.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_PLUGIN_H__
  18 #define __MAPS_PLUGIN_H__
  19
  20 #include <maps_service.h>
  21 #include <maps_plugin_info.h>
  22 #include <maps_extra_types.h>
  23
  24 /**
  25  *
  26  * @ingroup     CAPI_MAPS_PLUGIN_MODULE
  27  * @defgroup    CAPI_MAPS_PLUGIN_AND_PROVIDERS_MODULE Maps Plugin and Providers
  28  *
  29  * @file maps_plugin.h
  30  * @brief This file contains the top level functions of Maps Plugin API
  31  *
  32  * @addtogroup CAPI_MAPS_PLUGIN_AND_PROVIDERS_MODULE
  33  * @{
  34  * @brief This provides APIs related to operations with Maps Plugins
  35  */
  36
  37 #ifdef __cplusplus
  38 extern "C" {
  39 #endif
  40
  41 /**
  42  * @brief       The Maps Plugin handle.
  43  * @details The handle of Maps Plugin instance.
  44  * @since_tizen 2.4
  45  */
  46 typedef void *maps_plugin_h;
  47
  48 /*----------------------------------------------------------------------------*/
  49 /*
  50  * Plugin dedicated functions
  51  */
  52
  53 /**
  54  * @brief       Initialize a new Maps Plugin.
  55  * @details A maps plugin handle can be used to access a specified plugin.
  56  * @since_tizen 2.4
  57  * @remarks @a plugin and it resources must be released in
  58  * maps_plugin_shutdown().
  59  *
  60  * @param[out]  plugin          A handle of a new plugin on success
  61  * @return      0 on success, otherwise a negative error value
  62  * @retval      #MAPS_ERROR_NONE Successful
  63  * @retval      #MAPS_ERROR_OUT_OF_MEMORY Out of memory
  64  * @retval      #MAPS_ERROR_INVALID_PARAMETER Invalid parameter
  65  * @retval      #MAPS_ERROR_SERVICE_NOT_AVAILABLE Service not available
  66  *
  67  * @see maps_plugin_shutdown()
  68  */
  69 int maps_plugin_init(maps_plugin_h *plugin);
  70
  71 /**
  72  * @brief       Destroys the Maps Plugin handle.
  73  * @details This function destroys the maps plugin handle and releases all its
  74  * resources.
  75  * @since_tizen 2.4
  76  *
  77  * @param[in]   plugin          The maps plugin handle to destroy
  78  * @return      0 on success, otherwise a negative error value
  79  * @retval      #MAPS_ERROR_NONE Successful
  80  * @retval      #MAPS_ERROR_INVALID_PARAMETER Invalid parameter
  81  *
  82  * @see maps_plugin_init()
  83  */
  84 int maps_plugin_shutdown(maps_plugin_h plugin);
  85
  86 /**
  87  * @brief       Returns a plugin info.
  88  * @details This function returns a plugin info.
  89  * @since_tizen 2.4
  90  *
  91  * @param[out]  info    A plugin info
  92  * @return      0 on success, otherwise a negative error value
  93  * @retval      #MAPS_ERROR_NONE Successful
  94  * @retval      #MAPS_ERROR_OUT_OF_MEMORY Out of memory
  95  * @retval      #MAPS_ERROR_INVALID_PARAMETER Invalid parameter
  96  * @retval      #MAPS_ERROR_SERVICE_NOT_AVAILABLE Service not available
  97  *
  98  * @see maps_plugin_init()
  99  */
 100 int maps_plugin_get_info(maps_plugin_info_h *info);
 101
 102 /*----------------------------------------------------------------------------*/
 103 /*
 104  * Maps Provider access key, preference and capabilities
 105  */
 106
 107 /**
 108  * @brief       Sets the Maps Key to be used in the Maps Plugin requests.
 109  * @details This function sets the Maps Key which will be used in each Maps
 110  * Plugin request to Maps Provider.
 111  * @since_tizen 2.4
 112  * @remarks To obtain the @a provider_key refer to corresponding Maps Provider
 113  * documentation.
 114  * \n For HERE Maps refer to https://developer.here.com/,
 115  * https://developer.here.com/rest-apis.
 116  *
 117  * @param[in]   provider_key    The Maps Key to be used
 118  * @return      0 on success, otherwise a negative error value
 119  * @retval      #MAPS_ERROR_NONE Successful
 120  * @retval      #MAPS_ERROR_INVALID_PARAMETER Invalid parameter
 121  * @retval      #MAPS_ERROR_NOT_SUPPORTED Not supported
 122  *
 123  * @see maps_plugin_get_provider_key()
 124  */
 125 int maps_plugin_set_provider_key(const char *provider_key);
 126
 127 /**
 128  * @brief       Gets the Maps Key which is to be used in the Maps Service
 129  * requests
 130  * @details This function gets the Maps Key which is to be used in each Maps
 131  * Service request to Maps Provider.
 132  * \n Maps key can be set with maps_plugin_set_provider_key().
 133  * @since_tizen 2.4
 134  * @remarks The string @a provider_key must be released using free().
 135  *
 136  * @param[out]  provider_key    The Maps Key
 137  * @return      0 on success, otherwise a negative error value
 138  * @retval      #MAPS_ERROR_NONE Successful
 139  * @retval      #MAPS_ERROR_INVALID_PARAMETER Invalid parameter
 140  * @retval      #MAPS_ERROR_NOT_SUPPORTED Not supported
 141  *
 142  * @see maps_plugin_set_provider_key()
 143  */
 144 int maps_plugin_get_provider_key(char **provider_key);
 145
 146 /**
 147  * @brief       Sets the Maps Preference.
 148  * @details This function sets the Maps Preferences which are used in each Maps
 149  * Plugin request to Maps Provider.
 150  * @since_tizen 2.4
 151  *
 152  * @param[in]   preference      The handle of Maps Preference
 153  * @return      0 on success, otherwise a negative error value
 154  * @retval      #MAPS_ERROR_NONE Successful
 155  * @retval      #MAPS_ERROR_INVALID_PARAMETER Invalid parameter
 156  * @retval      #MAPS_ERROR_NOT_SUPPORTED Not supported
 157  * @retval      #MAPS_ERROR_PERMISSION_DENIED Permission Denied
 158  *
 159  * @see maps_plugin_get_preference()
 160  */
 161 int maps_plugin_set_preference(maps_item_hashtable_h preference);
 162
 163 /**
 164  * @brief       Gets the Maps Preference.
 165  * @details This function gets the Maps Preferences which are used in each Maps
 166  * Plugin request to Maps Provider.
 167  * \n Preferences can be set with maps_plugin_set_preference().
 168  * @since_tizen 2.4
 169  * @remarks @a preference must be released using maps_preference_destroy().
 170  *
 171  * @param[out]  preference      The handle of Maps Preference
 172  * @return      0 on success, otherwise a negative error value
 173  * @retval      #MAPS_ERROR_NONE Successful
 174  * @retval      #MAPS_ERROR_INVALID_PARAMETER Invalid parameter
 175  * @retval      #MAPS_ERROR_NOT_SUPPORTED Not supported
 176  *
 177  * @see maps_plugin_set_preference()
 178  */
 179 int maps_plugin_get_preference(maps_item_hashtable_h *preference);
 180
 181 /**
 182  * @brief       Checks if the Maps Plugin supports a request.
 183  * @details This function checks if the Maps Plugin supports a specified
 184  * request.
 185  * @since_tizen 2.4
 186  *
 187  * @param[in]   service         The service to be checked
 188  * @param[out]  supported       Is the service supported
 189  * @return      0 on success, otherwise a negative error value
 190  * @retval      #MAPS_ERROR_NONE Successful, the service is supported
 191  * @retval      #MAPS_ERROR_INVALID_PARAMETER Invalid parameter
 192  * @retval      #MAPS_ERROR_NOT_SUPPORTED Not supported
 193  *
 194  * @pre Call maps_service_create() to create Maps Service and obtain its handle.
 195  *
 196  * @see maps_service_create()
 197  */
 198 int maps_plugin_is_service_supported(maps_service_e service,
 199                                      bool *supported);
 200
 201 /**
 202  * @brief       Checks if the Maps Plugin supports a data feature.
 203  * @details This function checks if the Maps Plugin supports a specified data
 204  * feature.
 205  * @since_tizen 2.4
 206  *
 207  * @param[in]   data            The data feature to be checked
 208  * @param[out]  supported       Is the data feature supported
 209  * @return      0 on success, otherwise a negative error value
 210  * @retval      #MAPS_ERROR_NONE Successful, the data feature is supported
 211  * @retval      #MAPS_ERROR_INVALID_PARAMETER Invalid parameter
 212  * @retval      #MAPS_ERROR_NOT_SUPPORTED Not supported
 213  *
 214  * @pre Call maps_service_create() to create Maps Service and obtain its handle.
 215  *
 216  * @see maps_service_create()
 217  */
 218 int maps_plugin_is_data_supported(maps_service_data_e data, bool *supported);
 219
 220 /*----------------------------------------------------------------------------*/
 221 /*
 222  * Geocode
 223  */
 224
 225 /**
 226  * @brief       Gets the position coordinates for a given address.
 227  * @details This function obtains position coordinates for a given free-formed
 228  * address string.
 229  * @since_tizen 2.4
 230  * @privlevel public
 231  * @privilege %http://tizen.org/privilege/mapservice
 232  * @remarks This function requires network access.
 233  * \n To cancel the request use maps_plugin_cancel_request().
 234  *
 235  * @param[in]   address         The free-formed address
 236  * @param[in]   preference      The set of preferences for processing Geocode
 237  * @param[in]   callback        The callback which will receive position
 238  * coordinates
 239  * @param[in]   user_data       The user data to be passed to the callback
 240  * function
 241  * @param[out]  request_id      The id of request
 242  * @return      0 on success, otherwise a negative error value
 243  * @retval      #MAPS_ERROR_NONE Successful
 244  * @retval      #MAPS_ERROR_INVALID_PARAMETER Invalid parameter
 245  * @retval      #MAPS_ERROR_NETWORK_UNREACHABLE Network connection failed
 246  * @retval      #MAPS_ERROR_SERVICE_NOT_AVAILABLE Service not available
 247  * @retval      #MAPS_ERROR_PERMISSION_DENIED Permission Denied
 248  * @retval      #MAPS_ERROR_NOT_SUPPORTED Not supported
 249  * @retval      #MAPS_ERROR_CONNECTION_TIME_OUT Timeout error, no answer
 250  * @retval      #MAPS_ERROR_INVALID_OPERATION Operation is not valid
 251  * @retval      #MAPS_ERROR_NOT_FOUND Result not found
 252  * @retval      #MAPS_ERROR_KEY_NOT_AVAILABLE Invalid key
 253  * @retval      #MAPS_ERROR_UNKNOWN Unknown error
 254  * @retval      #MAPS_ERROR_UNKNOWN Unknown error
 255  *
 256  * @post It invokes maps_service_geocode_cb() to deliver obtained position
 257  * coordinates.
 258  *
 259  * @see maps_plugin_geocode_inside_area()
 260  * @see maps_service_geocode_cb()
 261  * @see maps_plugin_cancel_request()
 262  * @see maps_plugin_reverse_geocode()
 263  */
 264 int maps_plugin_geocode(const char *address,
 265                         const maps_item_hashtable_h preference,
 266                         maps_service_geocode_cb callback, void *user_data,
 267                         int *request_id);
 268
 269 /**
 270  * @brief       Gets the position for a given address, within the specified
 271  * bounding box.
 272  * @details This function obtains position coordinates for a given free-formed
 273  * address string within the specified bounding box.
 274  * @since_tizen 2.4
 275  * @privlevel public
 276  * @privilege %http://tizen.org/privilege/mapservice
 277  * @remarks This function requires network access.
 278  * \n Polygonal bounding box is not supported.
 279  * \n To cancel the request use maps_plugin_cancel_request().
 280  * \n To check if Maps Provider is capable of Geocoding and which Geocode
 281  * preferences are supported see the lists of capacities and preferences above.
 282  *
 283  * @param[in]   address         The free-formed address
 284  * @param[in]   bounds          The bounding box
 285  * @param[in]   preference      The set of preferences for processing Geocode
 286  * @param[in]   callback        The callback which will receive position
 287  * coordinates
 288  * @param[in]   user_data       The user data to be passed to the callback
 289  * function
 290  * @param[out]  request_id      The id of request
 291  * @return      0 on success, otherwise a negative error value
 292  * @retval      #MAPS_ERROR_NONE Successful
 293  * @retval      #MAPS_ERROR_INVALID_PARAMETER Invalid parameter
 294  * @retval      #MAPS_ERROR_NETWORK_UNREACHABLE Network connection failed
 295  * @retval      #MAPS_ERROR_SERVICE_NOT_AVAILABLE Service not available
 296  * @retval      #MAPS_ERROR_PERMISSION_DENIED Permission Denied
 297  * @retval      #MAPS_ERROR_NOT_SUPPORTED Not supported
 298  * @retval      #MAPS_ERROR_KEY_NOT_AVAILABLE Invalid key
 299  * @retval      #MAPS_ERROR_CONNECTION_TIME_OUT Timeout error, no answer
 300  * @retval      #MAPS_ERROR_INVALID_OPERATION Operation is not valid
 301  * @retval      #MAPS_ERROR_NOT_FOUND Result not found
 302  * @retval      #MAPS_ERROR_KEY_NOT_AVAILABLE Invalid key
 303  * @retval      #MAPS_ERROR_UNKNOWN Unknown error
 304  *
 305  * @post It invokes maps_service_geocode_cb() to deliver obtained position
 306  * coordinates.
 307  *
 308  * @see maps_plugin_geocode_by_structured_address
 309  * @see maps_plugin_geocode_inside_area()
 310  * @see maps_service_geocode_cb()
 311  * @see maps_plugin_geocode()
 312  * @see maps_plugin_cancel_request()
 313  * @see maps_plugin_reverse_geocode()
 314  */
 315 int maps_plugin_geocode_inside_area(const char *address,
 316                                     const maps_area_h bounds,
 317                                     const maps_item_hashtable_h preference,
 318                                     maps_service_geocode_cb callback,
 319                                     void *user_data, int *request_id);
 320
 321 /**
 322  * @brief       Gets the position coordinates for a given address.
 323  * @details This function obtains position coordinates for a given structured
 324  * address.
 325  * @since_tizen 2.4
 326  * @privlevel public
 327  * @privilege %http://tizen.org/privilege/mapservice
 328  * @remarks This function requires network access.
 329  * \n To cancel the request use maps_plugin_cancel_request().
 330  * \n To check if Maps Provider is capable of Geocoding and which Geocode
 331  * preferences are supported see the lists of capacities and preferences above.
 332  *
 333  * @param[in]   address         The structured address
 334  * @param[in]   preference      The set of preferences for processing Geocode
 335  * @param[in]   callback        The callback which will receive position
 336  * coordinates
 337  * @param[in]   user_data       The user data to be passed to the callback
 338  * function
 339  * @param[out]  request_id      The id of request
 340  * @return      0 on success, otherwise a negative error value
 341  * @retval      #MAPS_ERROR_NONE Successful
 342  * @retval      #MAPS_ERROR_INVALID_PARAMETER Invalid parameter
 343  * @retval      #MAPS_ERROR_NETWORK_UNREACHABLE Network connection failed
 344  * @retval      #MAPS_ERROR_SERVICE_NOT_AVAILABLE Service not available
 345  * @retval      #MAPS_ERROR_PERMISSION_DENIED Permission Denied
 346  * @retval      #MAPS_ERROR_NOT_SUPPORTED Not supported
 347  * @retval      #MAPS_ERROR_CONNECTION_TIME_OUT Timeout error, no answer
 348  * @retval      #MAPS_ERROR_INVALID_OPERATION Operation is not valid
 349  * @retval      #MAPS_ERROR_NOT_FOUND Result not found
 350  * @retval      #MAPS_ERROR_KEY_NOT_AVAILABLE Invalid key
 351  * @retval      #MAPS_ERROR_UNKNOWN Unknown error
 352  *
 353  * @post It invokes maps_service_geocode_cb() to deliver obtained position
 354  * coordinates.
 355
 356  * @see maps_plugin_geocode()
 357  * @see maps_plugin_geocode_inside_area()
 358  * @see maps_service_geocode_cb()
 359  * @see maps_plugin_cancel_request()
 360  * @see maps_plugin_reverse_geocode()
 361  */
 362 int maps_plugin_geocode_by_structured_address(const maps_address_h address,
 363                                               const maps_preference_h
 364                                               preference,
 365                                               maps_service_geocode_cb
 366                                               callback, void *user_data,
 367                                               int *request_id);
 368
 369 /**
 370  * @brief       Gets the address for a given position coordinates.
 371  * @details This function obtains structured address information for a given
 372  * position coordinates.
 373  * @since_tizen 2.4
 374  * @privlevel public
 375  * @privilege %http://tizen.org/privilege/mapservice
 376  * @remarks This function requires network access.
 377  * \n To cancel the request use maps_plugin_cancel_request().
 378  * \n To check if Maps Provider is capable of Reverse Geocoding and which
 379  * Reverse Geocode preferences are supported see the lists of capacities and
 380  * preferences above.
 381  *
 382  * @param[in]   latitude        The latitude [-90.0 ~ 90.0] (degrees)
 383  * @param[in]   longitude       The longitude [-180.0 ~ 180.0] (degrees)
 384  * @param[in]   preference      The set of preferences for processing Reverse
 385  * Geocode
 386  * @param[in]   callback        The callback which will receive address
 387  * information
 388  * @param[in]   user_data       The user data to be passed to the callback
 389  * function
 390  * @param[out]  request_id      The id of request
 391  * @return      0 on success, otherwise a negative error value
 392  * @retval      #MAPS_ERROR_NONE Successful
 393  * @retval      #MAPS_ERROR_INVALID_PARAMETER Invalid parameter
 394  * @retval      #MAPS_ERROR_NETWORK_UNREACHABLE Network connection failed
 395  * @retval      #MAPS_ERROR_SERVICE_NOT_AVAILABLE Service not available
 396  * @retval      #MAPS_ERROR_PERMISSION_DENIED Permission Denied
 397  * @retval      #MAPS_ERROR_NOT_SUPPORTED Not supported
 398  * @retval      #MAPS_ERROR_CONNECTION_TIME_OUT Timeout error, no answer
 399  * @retval      #MAPS_ERROR_INVALID_OPERATION Operation is not valid
 400  * @retval      #MAPS_ERROR_NOT_FOUND Result not found
 401  * @retval      #MAPS_ERROR_KEY_NOT_AVAILABLE Invalid key
 402  * @retval      #MAPS_ERROR_UNKNOWN Unknown error
 403  *
 404  * @post This function invokes maps_service_reverse_geocode_cb().
 405  *
 406  * @see maps_service_reverse_geocode_cb()
 407  * @see maps_plugin_cancel_request()
 408  * @see maps_plugin_geocode()
 409  */
 410 int maps_plugin_reverse_geocode(double latitude, double longitude,
 411                                 const maps_item_hashtable_h preference,
 412                                 maps_service_reverse_geocode_cb callback,
 413                                 void *user_data, int *request_id);
 414
 415 /*----------------------------------------------------------------------------*/
 416 /*
 417  * Place
 418  */
 419
 420 /**
 421  * @brief       Queries a Place information by a coordinates position and a
 422  * distance.
 423  * @details This function obtains the Place information for a specified distance
 424  * around a given coordinates position.
 425  * @since_tizen 2.4
 426  * @privlevel public
 427  * @privilege %http://tizen.org/privilege/mapservice
 428  * @remarks This function requires network access.
 429  * \n To cancel the search request use maps_plugin_cancel_request().
 430  * \n To check if Maps Provider is capable of Place Search and which Place
 431  * preferences are supported see the lists of capacities and preferences above.
 432  *
 433  * @param[in]   position        The interested position
 434  * @param[in]   distance        The search area distance
 435  * @param[in]   filter          The filter handle
 436  * @param[in]   preference      The place preference handle
 437  * @param[in]   callback        The result callback
 438  * @param[in]   user_data       The user data to be passed to the callback
 439  * function
 440  * @param[out]  request_id      A Request id, can be set to NULL if does not
 441  * require operation cancel
 442  * @return      0 on success, otherwise a negative error value
 443  * @retval      #MAPS_ERROR_NONE Successful
 444  * @retval      #MAPS_ERROR_OUT_OF_MEMORY Out of memory
 445  * @retval      #MAPS_ERROR_INVALID_PARAMETER Invalid parameter
 446  * @retval      #MAPS_ERROR_SERVICE_NOT_AVAILABLE Service not available
 447  * @retval      #MAPS_ERROR_PERMISSION_DENIED Permission Denied
 448  * @retval      #MAPS_ERROR_NOT_SUPPORTED Not supported
 449  * @retval      #MAPS_ERROR_CONNECTION_TIME_OUT Timeout error, no answer
 450  * @retval      #MAPS_ERROR_INVALID_OPERATION Operation is not valid
 451  * @retval      #MAPS_ERROR_NOT_FOUND Result not found
 452  * @retval      #MAPS_ERROR_KEY_NOT_AVAILABLE Invalid key
 453  * @retval      #MAPS_ERROR_RESOURCE_BUSY Places service busy
 454  * @retval      #MAPS_ERROR_CANCELED Places service aborted
 455  * @retval      #MAPS_ERROR_UNKNOWN Unknown error
 456  *
 457  * @post It invokes maps_service_search_place_cb() to deliver obtained Place
 458  * information.
 459  *
 460  * @see maps_plugin_search_place_by_area()
 461  * @see maps_plugin_search_place_by_address()
 462  * @see maps_plugin_cancel_request()
 463  * @see maps_service_search_place_cb()
 464  */
 465 int maps_plugin_search_place(const maps_coordinates_h position, int distance,
 466                              const maps_place_filter_h filter,
 467                              maps_preference_h preference,
 468                              maps_service_search_place_cb callback,
 469                              void *user_data, int *request_id);
 470
 471 /**
 472  * @brief       Queries a Place information by a coordinates boundary.
 473  * @details This function obtains the Place information for a specified
 474  * coordinates boundary.
 475  * @since_tizen 2.4
 476  * @privlevel public
 477  * @privilege %http://tizen.org/privilege/mapservice
 478  * @remarks This function requires network access.
 479  * \n @a boundary is supporting only circle type bounds for search.
 480  * \n To cancel the search request use maps_plugin_cancel_request().
 481  * \n To check if Maps Provider is capable of Place Search and which Place
 482  * preferences are supported see the lists of capacities and preferences above.
 483  *
 484  * @param[in]   boundary        The interested area
 485  * @param[in]   filter          The filter handle
 486  * @param[in]   preference      The place preference handle
 487  * @param[in]   callback        The result callback
 488  * @param[in]   user_data       The user data to be passed to the callback
 489  * function
 490  * @param[out]  request_id      A Request id, can be set to NULL if does not
 491  * required operation cancel
 492  * @return      0 on success, otherwise a negative error value
 493  * @retval      #MAPS_ERROR_NONE Successful
 494  * @retval      #MAPS_ERROR_OUT_OF_MEMORY Out of memory
 495  * @retval      #MAPS_ERROR_INVALID_PARAMETER   Invalid parameter
 496  * @retval      #MAPS_ERROR_SERVICE_NOT_AVAILABLE Service not available
 497  * @retval      #MAPS_ERROR_PERMISSION_DENIED Permission Denied
 498  * @retval      #MAPS_ERROR_NOT_SUPPORTED Not supported
 499  * @retval      #MAPS_ERROR_CONNECTION_TIME_OUT Timeout error, no answer
 500  * @retval      #MAPS_ERROR_INVALID_OPERATION Operation is not valid
 501  * @retval      #MAPS_ERROR_NOT_FOUND Result not found
 502  * @retval      #MAPS_ERROR_KEY_NOT_AVAILABLE Invalid key
 503  * @retval      #MAPS_ERROR_RESOURCE_BUSY Places service busy
 504  * @retval      #MAPS_ERROR_CANCELED Places service aborted
 505  * @retval      #MAPS_ERROR_UNKNOWN Unknown error
 506  *
 507  * @post It invokes maps_service_search_place_cb() to deliver obtained Place
 508  * information.
 509  *
 510  * @see maps_plugin_search_place()
 511  * @see maps_plugin_search_place_by_address()
 512  * @see maps_plugin_cancel_request()
 513  * @see maps_service_search_place_cb()
 514  */
 515 int maps_plugin_search_place_by_area(const maps_area_h boundary,
 516                                      const maps_place_filter_h filter,
 517                                      maps_preference_h preference,
 518                                      maps_service_search_place_cb callback,
 519                                      void *user_data, int *request_id);
 520
 521 /**
 522  * @brief       Queries a Place information by a free-formed address string.
 523  * @details This function obtains the Place information for a specified free-
 524  * formed address string.
 525  * @since_tizen 2.4
 526  * @privlevel public
 527  * @privilege %http://tizen.org/privilege/mapservice
 528  * @remarks This function requires network access.
 529  * \n @a boundary is supporting only circle type bounds for search.
 530  * \n To cancel the search request use maps_plugin_cancel_request().
 531  * \n To check if Maps Provider is capable of Place Search and which Place
 532  * preferences are supported see the lists of capacities and preferences above.
 533  *
 534  * @param[in]   address         The interested address
 535  * @param[in]   boundary        The interested area
 536  * @param[in]   filter          The filter handle
 537  * @param[in]   preference      The place preference handle
 538  * @param[in]   callback        The result callback
 539  * @param[in]   user_data       The user data to be passed to the callback
 540  * function
 541  * @param[out]  request_id      A Request id, can be set to NULL if does not
 542  * required operation cancel
 543  * @return      0 on success, otherwise a negative error value
 544  * @retval      #MAPS_ERROR_NONE Successful
 545  * @retval      #MAPS_ERROR_OUT_OF_MEMORY Out of memory
 546  * @retval      #MAPS_ERROR_INVALID_PARAMETER   Invalid parameter
 547  * @retval      #MAPS_ERROR_SERVICE_NOT_AVAILABLE Service not available
 548  * @retval      #MAPS_ERROR_PERMISSION_DENIED Permission Denied
 549  * @retval      #MAPS_ERROR_NOT_SUPPORTED Not supported
 550  * @retval      #MAPS_ERROR_CONNECTION_TIME_OUT Timeout error, no answer
 551  * @retval      #MAPS_ERROR_INVALID_OPERATION Operation is not valid
 552  * @retval      #MAPS_ERROR_NOT_FOUND Result not found
 553  * @retval      #MAPS_ERROR_KEY_NOT_AVAILABLE Invalid key
 554  * @retval      #MAPS_ERROR_RESOURCE_BUSY Places service busy
 555  * @retval      #MAPS_ERROR_CANCELED Places service aborted
 556  * @retval      #MAPS_ERROR_UNKNOWN Unknown error
 557  *
 558  * @post It invokes maps_service_search_place_cb() to deliver obtained Place
 559  * information.
 560  *
 561  * @see maps_plugin_search_place()
 562  * @see maps_plugin_search_place_by_area()
 563  * @see maps_plugin_cancel_request()
 564  * @see maps_service_search_place_cb()
 565  */
 566 int maps_plugin_search_place_by_address(const char *address,
 567                                         const maps_area_h boundary,
 568                                         const maps_place_filter_h filter,
 569                                         maps_preference_h preference,
 570                                         maps_service_search_place_cb callback,
 571                                         void *user_data, int *request_id);
 572
 573 /*----------------------------------------------------------------------------*/
 574 /*
 575  * Route
 576  */
 577
 578 /**
 579  * @brief       Queries the Route from origin coordinate to a destination.
 580  * @details This function obtains the Route information for a specified origin
 581  * and destination coordinates.
 582  * @since_tizen 2.4
 583  * @privlevel public
 584  * @privilege %http://tizen.org/privilege/mapservice
 585  * @remarks This function requires network access.
 586  * \n To cancel the search request use maps_plugin_cancel_request().
 587  * \n To check if Maps Provider is capable of Route Search and which Route
 588  * preferences are supported see the lists of capacities and preferences above.
 589  *
 590  * @param[in]   origin          The starting point
 591  * @param[in]   destination     The destination
 592  * @param[in]   preference      The Route preference handle
 593  * @param[in]   callback        The result callback
 594  * @param[in]   user_data       The user data to be passed to the callback
 595  * function
 596  * @param[out]  request_id      The request ID
 597  * @return      0 on success, otherwise a negative error value
 598  * @retval      #MAPS_ERROR_NONE Successful
 599  * @retval      #MAPS_ERROR_OUT_OF_MEMORY Out of memory
 600  * @retval      #MAPS_ERROR_INVALID_PARAMETER Invalid parameter
 601  * @retval      #MAPS_ERROR_NOT_SUPPORTED Service unavailable
 602  * @retval      #MAPS_ERROR_PERMISSION_DENIED Permission Denied
 603  * @retval      #MAPS_ERROR_CONNECTION_TIME_OUT Timeout error, no answer
 604  * @retval      #MAPS_ERROR_INVALID_OPERATION Operation is not valid
 605  * @retval      #MAPS_ERROR_NOT_FOUND Result not found
 606  * @retval      #MAPS_ERROR_KEY_NOT_AVAILABLE Invalid key
 607  * @retval      #MAPS_ERROR_UNKNOWN Unknown error
 608  *
 609  * @post It invokes maps_service_search_route_cb() to deliver obtained Route
 610  * information.
 611  *
 612  * @see maps_plugin_search_route_waypoints()
 613  * @see maps_plugin_cancel_request()
 614  * @see maps_service_search_route_cb()
 615  */
 616 int maps_plugin_search_route(const maps_coordinates_h origin,
 617                              const maps_coordinates_h destination,
 618                              maps_preference_h preference,
 619                              maps_service_search_route_cb callback,
 620                              void *user_data, int *request_id);
 621
 622 /**
 623  * @brief       Queries the Route, passing through a specified way points.
 624  * @details This function obtains the Route information for the Route, passing
 625  * through a specified set of way points.
 626  * @since_tizen 2.4
 627  * @privlevel public
 628  * @privilege %http://tizen.org/privilege/mapservice
 629  * @remarks This function requires network access.
 630  * \n To cancel the search request use maps_plugin_cancel_request().
 631  * \n To check if Maps Provider is capable of Route Search and which Route
 632  * preferences are supported see the lists of capacities and preferences above.
 633  *
 634  * @param[in]   waypoint_list   The list of way points to go through
 635  * @param[in]   waypoint_num    The number of way points to go through
 636  * @param[in]   preference      The Route preference handle
 637  * @param[in]   callback        The result callback
 638  * @param[in]   user_data       The user data to be passed to the callback
 639  * function
 640  * @param[out]  request_id      The request ID
 641  * @return      0 on success, otherwise a negative error value
 642  * @retval      #MAPS_ERROR_NONE Successful
 643  * @retval      #MAPS_ERROR_OUT_OF_MEMORY Out of memory
 644  * @retval      #MAPS_ERROR_INVALID_PARAMETER Invalid parameter
 645  * @retval      #MAPS_ERROR_NOT_SUPPORTED Service unavailable
 646  * @retval      #MAPS_ERROR_PERMISSION_DENIED Permission Denied
 647  * @retval      #MAPS_ERROR_CONNECTION_TIME_OUT Timeout error, no answer
 648  * @retval      #MAPS_ERROR_INVALID_OPERATION Operation is not valid
 649  * @retval      #MAPS_ERROR_NOT_FOUND Result not found
 650  * @retval      #MAPS_ERROR_KEY_NOT_AVAILABLE Invalid key
 651  * @retval      #MAPS_ERROR_UNKNOWN Unknown error
 652  *
 653  * @post It invokes maps_service_search_route_cb() to deliver obtained Route
 654  * information.
 655  *
 656  * @see maps_plugin_search_route()
 657  * @see maps_plugin_cancel_request()
 658  * @see maps_service_search_route_cb()
 659  */
 660 int maps_plugin_search_route_waypoints(const maps_coordinates_h *waypoint_list,
 661                                        int waypoint_num,
 662                                        maps_preference_h preference,
 663                                        maps_service_search_route_cb callback,
 664                                        void *user_data, int *request_id);
 665
 666 /*----------------------------------------------------------------------------*/
 667 /*
 668  * Cancel Request
 669  */
 670
 671 /**
 672  * @brief       Cancels the service request.
 673  * @details This function cancels the service request initiated by geocode,
 674  * route or place search.
 675  * @since_tizen 2.4
 676  * @privlevel public
 677  * @privilege %http://tizen.org/privilege/mapservice
 678  * @remarks This function requires network access.
 679  *
 680  * @param[in]   request_id      The id of request
 681  * @return      0 on success, otherwise a negative error value
 682  * @retval      #MAPS_ERROR_NONE Successful
 683  * @retval      #MAPS_ERROR_INVALID_PARAMETER Invalid parameter
 684  * @retval      #MAPS_ERROR_NETWORK_UNREACHABLE Network connection failed
 685  * @retval      #MAPS_ERROR_SERVICE_NOT_AVAILABLE Service not available
 686  * @retval      #MAPS_ERROR_PERMISSION_DENIED Permission Denied
 687  * @retval      #MAPS_ERROR_NOT_SUPPORTED Not supported
 688  * @retval      #MAPS_ERROR_CONNECTION_TIME_OUT Timeout error, no answer
 689  * @retval      #MAPS_ERROR_INVALID_OPERATION Operation is not valid
 690  * @retval      #MAPS_ERROR_NOT_FOUND Result not found
 691  * @retval      #MAPS_ERROR_KEY_NOT_AVAILABLE Invalid key
 692  * @retval      #MAPS_ERROR_UNKNOWN Unknown error
 693  *
 694  * @pre @a request_id is obtained from one of following:
 695  *  - maps_plugin_geocode()
 696  *  - maps_plugin_geocode_inside_area()
 697  *  - maps_plugin_geocode_by_structured_address()
 698  *  - maps_plugin_reverse_geocode()
 699  *  - maps_plugin_search_place()
 700  *  - maps_plugin_search_place_by_area()
 701  *  - maps_plugin_search_place_by_address()
 702  *  - maps_plugin_search_route()
 703  *  - maps_plugin_search_route_waypoints()
 704  *  .
 705  *
 706  * @see maps_plugin_geocode()
 707  * @see maps_plugin_geocode_inside_area()
 708  * @see maps_plugin_geocode_by_structured_address()
 709  * @see maps_plugin_reverse_geocode()
 710  * @see maps_plugin_search_place()
 711  * @see maps_plugin_search_place_by_area()
 712  * @see maps_plugin_search_place_by_address()
 713  * @see maps_plugin_search_route()
 714  * @see maps_plugin_search_route_waypoints()
 715  */
 716 int maps_plugin_cancel_request(int request_id);
 717
 718 #ifdef __cplusplus
 719 }
 720 #endif
 721 /**
 722  * @}
 723  */
 724 #endif                          /* __MAPS_PLUGIN_H__ */