include/poi.h

   1 /*
   2  * Copyright (c) 2011-2013 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
  18 #ifndef __TIZEN_LOCATOIN_POI_H__
  19 #define __TIZEN_LOCATOIN_POI_H__
  20
  21 #include <tizen.h>
  22 #include <time.h>
  23 #include <location_bounds.h>
  24
  25
  26 #ifdef __cplusplus
  27 extern "C"
  28 {
  29 #endif
  30
  31 #define POI_ERROR_CLASS TIZEN_ERROR_LOCATION_CLASS | 0x50
  32
  33 /**
  34  * @brief The POI service handle
  35  * @ingroup CAPI_LOCATION_POI_MODULE
  36  */
  37 typedef void * poi_service_h;
  38
  39 /**
  40  * @brief The POI preference handle
  41  * @ingroup CAPI_LOCATION_POI_PREFERENCE_MODULE
  42  */
  43 typedef void * poi_preference_h;
  44
  45 /**
  46  * @brief The POI filter handle
  47  * @ingroup CAPI_LOCATION_POI_FILTER_MODULE
  48  */
  49 typedef void * poi_filter_h;
  50
  51 /**
  52  * @brief The POI handle
  53  * @ingroup CAPI_LOCATION_POI_POI_MODULE
  54  */
  55 typedef void * poi_h;
  56
  57
  58 /**
  59  * @brief Enumerations of sort order
  60  * @ingroup CAPI_LOCATION_POI_PREFERENCE_MODULE
  61  */
  62 typedef enum {
  63         POI_SORTORDER_NONE,      /**< None of sorting the results in order.*/
  64         POI_SORTORDER_ASC,      /**< A constant for sorting the results in ascending order */
  65         POI_SORTORDER_DESC      /**< A constant for sorting the results in descending order */
  66 } poi_sort_order_e;
  67
  68
  69
  70 /**
  71  * @brief Enumerations of error code for POI
  72  * @ingroup CAPI_LOCATION_POI_MODULE
  73  */
  74 typedef enum
  75 {
  76     POI_ERROR_NONE = TIZEN_ERROR_NONE,                             /**< Successful */
  77     POI_ERROR_OUT_OF_MEMORY = TIZEN_ERROR_OUT_OF_MEMORY,           /**< Out of memory */
  78     POI_ERROR_INVALID_PARAMETER = TIZEN_ERROR_INVALID_PARAMETER,                   /**< Invalid parameter */
  79     POI_ERROR_NETWORK_FAILED = POI_ERROR_CLASS | 0x02,                  /**< Network unavailable*/
  80     POI_ERROR_SERVICE_NOT_AVAILABLE = POI_ERROR_CLASS | 0x03,   /**< Service unavailable */
  81     POI_ERROR_INVALID_KEY = POI_ERROR_CLASS | 0x04,   /**< Invalid key */
  82     POI_ERROR_RESULT_NOT_FOUND = POI_ERROR_CLASS | 0x05,   /**< Result not found */
  83 } poi_error_e;
  84
  85
  86 /**
  87  * @brief The result of POI search
  88  * @ingroup CAPI_LOCATION_POI_MODULE
  89  * @remarks @a poi is valid only in this function. To use the @a poi outside this function, copy the handle with poi_clone() function.\nIf failed to search, lenght is 0 and poi is NULL
  90  * @param [in] error The result of request
  91  * @param [in] request_id The request id
  92  * @param [in] index    The index of POI data in result set, start from 0
  93  * @param [in] length The number of result
  94  * @param [in] poi      The result data
  95  * @param [in] uesr_data  The user data passed from the request function
  96  * @return @c true to continue with the next iteration of the loop, \n @c false to break outsp of the loop.
  97  * @see poi_service_search_by_position()
  98  * @see poi_service_search_by_area()
  99  * @see poi_service_search_by_address()
 100  */
 101 typedef bool (*poi_service_search_cb)(poi_error_e error, int request_id , int index, int length , poi_h poi , void * user_data);
 102
 103 /**
 104  * @brief Called once for each properties
 105  * @ingroup CAPI_LOCATION_POI_PREFERENCE_MODULE
 106  * @remarks @a key and value are valid only in this function.
 107  * @param   [in] key  The key string
 108  * @param   [in] value  The value string
 109  * @param   [in] uesr_data  The user data passed from the foreach function
 110  * @return @c true to continue with the next iteration of the loop, \n @c false to break outsp of the loop.
 111  * @see poi_preference_foreach_properties()
 112  */
 113 typedef bool (*poi_preference_properties_cb)(const char *key , const char *value,  void *user_data);
 114
 115 /**
 116  * @brief Called once for each available keys
 117  * @ingroup CAPI_LOCATION_POI_PREFERENCE_MODULE
 118  * @remarks @a key is valid only in this function.
 119  * @param   [in] key  The key string
 120  * @param   [in] uesr_data  The user data passed from the foreach function
 121  * @return @c true to continue with the next iteration of the loop, \n @c false to break outsp of the loop.
 122  * @see poi_preference_foreach_available_keys()
 123  */
 124 typedef bool (*poi_preference_available_key_cb)(const char *key , void *user_data);
 125
 126 /**
 127  * @brief Called once for each available values
 128  * @ingroup CAPI_LOCATION_POI_PREFERENCE_MODULE
 129  * @remarks @a value is valid only in this function.
 130  * @param   [in] value  The value string
 131  * @param   [in] uesr_data  The user data passed from the foreach function
 132  * @return @c true to continue with the next iteration of the loop, \n @c false to break outsp of the loop.
 133  * @see poi_preference_foreach_available_values()
 134  */
 135 typedef bool (*poi_preference_available_value_cb)(const char *value , void *user_data);
 136
 137
 138 /**
 139  * @brief Called once for each sortable field
 140  * @ingroup CAPI_LOCATION_POI_PREFERENCE_MODULE
 141  * @remarks @a field is valid only in this function.
 142  * @param   [in] field  The field string
 143  * @param   [in] uesr_data  The user data passed from the foreach function
 144  * @return @c true to continue with the next iteration of the loop, \n @c false to break outsp of the loop.
 145  * @see poi_preference_foreach_sortable_field()
 146  */
 147 typedef bool (*poi_preference_sortable_field_cb)(const char *field , void *user_data);
 148
 149 /**
 150  * @brief Called once for each properties
 151  * @ingroup CAPI_LOCATION_POI_FILTER_MODULE
 152  * @remarks @a key and value are valid only in this function.
 153  * @param   [in] key  The key string
 154  * @param   [in] value  The value string
 155  * @param   [in] uesr_data  The user data passed from the foreach function
 156  * @return @c true to continue with the next iteration of the loop, \n @c false to break outsp of the loop.
 157  * @see poi_filter_foreach_available_keys()
 158  */
 159 typedef bool (*poi_filter_properties_cb)(const char *key , const char *value , void *user_data);
 160
 161
 162 /**
 163  * @brief Called once for each available keys
 164  * @ingroup CAPI_LOCATION_POI_FILTER_MODULE
 165  * @remarks @a key is valid only in this function.
 166  * @param   [in] key  The key string
 167  * @param   [in] uesr_data  The user data passed from the foreach function
 168  * @return @c true to continue with the next iteration of the loop, \n @c false to break outsp of the loop.
 169  * @see poi_filter_foreach_available_keys()
 170  */
 171 typedef bool (*poi_filter_available_key_cb)(const char *key , void *user_data);
 172
 173 /**
 174  * @brief Called once for each available values
 175  * @ingroup CAPI_LOCATION_POI_FILTER_MODULE
 176  * @remarks @a value is valid only in this function.
 177  * @param   [in] value  The value string
 178  * @param   [in] uesr_data  The user data passed from the foreach function
 179  * @return @c true to continue with the next iteration of the loop, \n @c false to break outsp of the loop.
 180  * @see poi_filter_foreach_available_values()
 181  */
 182 typedef bool (*poi_filter_available_value_cb)(const char *value , void *user_data);
 183
 184
 185 /**
 186  * @brief Called once for each urls
 187  * @ingroup CAPI_LOCATION_POI_POI_MODULE
 188  * @remarks @a url and description are valid only in this function.
 189  * @param   [in] url  The url
 190  * @param   [in] description  The description
 191  * @param   [in] uesr_data  The user data passed from the foreach function
 192  * @return @c true to continue with the next iteration of the loop, \n @c false to break outsp of the loop.
 193  * @see poi_foreach_urls()
 194  */
 195 typedef bool (*poi_urls_cb)(const char *url , const char *description, void *user_data);
 196
 197 /**
 198  * @brief Called once for each properties
 199  * @ingroup CAPI_LOCATION_POI_POI_MODULE
 200  * @remarks @a key and value are valid only in this function.
 201  * @param   [in] key  The key of property
 202  * @param   [in] value  The value of property
 203  * @param   [in] uesr_data  The user data passed from the foreach function
 204  * @return @c true to continue with the next iteration of the loop, \n @c false to break outsp of the loop.
 205  * @see poi_foreach_properties()
 206  */
 207 typedef bool (*poi_properties_cb)(const char *key, const char* value, void *user_data);
 208
 209 /**
 210  * @brief Called once for each categories
 211  * @ingroup CAPI_LOCATION_POI_POI_MODULE
 212  * @remarks @a category is valid only in this function.
 213  * @param   [in] category The category
 214  * @param   [in] uesr_data  The user data passed from the foreach function
 215  * @return @c true to continue with the next iteration of the loop, \n @c false to break outsp of the loop.
 216  * @see poi_foreach_categories()
 217  */
 218 typedef bool (*poi_categories_cb)(const char *category, void *user_data);
 219
 220
 221
 222 /**
 223  * @brief Creates a new POI service handle.
 224  * @ingroup CAPI_LOCATION_POI_MODULE
 225  * @remarks @a service must be released poi_service_destroy() by you.
 226  * @param   [out] service  A handle of a new POI service handle on success
 227  * @return 0 on success, otherwise a negative error value.
 228  * @retval #POI_ERROR_NONE Successful
 229  * @retval #POI_ERROR_OUT_OF_MEMORY Out of memory
 230  * @retval #POI_ERROR_INVALID_PARAMETER Invalid parameter
 231  * @retval #POI_ERROR_SERVICE_NOT_AVAILABLE Service not available
 232  * @see poi_service_destroy()
 233  */
 234 int poi_service_create(poi_service_h *service);
 235
 236
 237 /**
 238  * @brief       Destroys the POI service handle and releases all its resources.
 239  * @ingroup CAPI_LOCATION_POI_MODULE
 240  * @param   [in] service        The POI service handle to destroy
 241  * @return  0 on success, otherwise a negative error value.
 242  * @retval #POI_ERROR_NONE Successful
 243  * @retval #POI_ERROR_INVALID_PARAMETER Invalid parameter
 244  * @see poi_service_create()
 245  */
 246 int poi_service_destroy(poi_service_h service);
 247
 248 /**
 249  * @brief       Gets POI preference
 250  * @ingroup CAPI_LOCATION_POI_MODULE
 251  * @remarks @a preference must be released poi_preference_destroy() by you.
 252  * @param [in] service The POI service handle
 253  * @param [out] preference The POI preference handle
 254  * @return  0 on success, otherwise a negative error value.
 255  * @retval #POI_ERROR_NONE Successful
 256  * @retval #POI_ERROR_INVALID_PARAMETER Invalid parameter
 257  * @see poi_service_set_preference()
 258  */
 259 int poi_service_get_preference(poi_service_h service , poi_preference_h *preference);
 260
 261 /**
 262  * @brief       Sets POI preference
 263  * @ingroup CAPI_LOCATION_POI_MODULE
 264  * @remarks @a preference handle is copied by frameworks
 265  * @param [in] service The POI service handle
 266  * @param [in] preference The POI preference handle
 267  * @return  0 on success, otherwise a negative error value.
 268  * @retval #POI_ERROR_NONE Successful
 269  * @retval #POI_ERROR_INVALID_PARAMETER Invalid parameter
 270  * @see poi_service_set_preference()
 271  */
 272 int poi_service_set_preference(poi_service_h service , poi_preference_h preference);
 273
 274
 275
 276 /**
 277  * @brief Request a search
 278  * @ingroup CAPI_LOCATION_POI_MODULE
 279  * @param [in] service The POI service handle
 280  * @param [in] position The interested position
 281  * @param [in] distance The search area distance
 282  * @param [in] filter The filter handle
 283  * @param [in] callback The result callback
 284  * @param [in] user_data The user data to be passed to the callback function
 285  * @param [out] request_id A Request id, can be set to NULL if does not required operation cancel
 286  * @return 0 on success, otherwise a negative error value.
 287  * @retval #POI_ERROR_NONE Successful
 288  * @retval #POI_ERROR_OUT_OF_MEMORY Out of memory
 289  * @retval #POI_ERROR_INVALID_PARAMETER Invalid parameter
 290  * @retval #POI_ERROR_SERVICE_NOT_AVAILABLE Service not available
 291  * @see poi_service_search_by_area()
 292  * @see poi_service_search_by_address()
 293  * @see poi_service_search_cancel()
 294  * @see poi_service_search_cb()
 295  */
 296 int poi_service_search (poi_service_h service, location_coords_s position, int distance , poi_filter_h filter, poi_service_search_cb callback, void * user_data, int * request_id);
 297
 298 /**
 299  * @brief Request a search by area
 300  * @ingroup CAPI_LOCATION_POI_MODULE
 301  * @remarks boundary is supporting only circle type bounds for search.
 302  * @param [in] service The POI service handle
 303  * @param [in] boundary The interested area
 304  * @param [in] filter The filter handle
 305  * @param [in] callback The result callback
 306  * @param [in] user_data The user data to be passed to the callback function
 307  * @param [out] request_id A Request id, can be set to NULL if does not required operation cancel
 308  * @return 0 on success, otherwise a negative error value.
 309  * @retval #POI_ERROR_NONE Successful
 310  * @retval #POI_ERROR_OUT_OF_MEMORY Out of memory
 311  * @retval #POI_ERROR_INVALID_PARAMETER Invalid parameter
 312  * @retval #POI_ERROR_SERVICE_NOT_AVAILABLE Service not available
 313  * @see poi_service_search_by_position()
 314  * @see poi_service_search_by_address()
 315  * @see poi_service_search_cancel()
 316  * @see poi_service_search_cb()
 317  */
 318 int poi_service_search_by_area (poi_service_h service, location_bounds_h boundary , poi_filter_h filter, poi_service_search_cb callback, void * user_data, int * request_id);
 319
 320 /**
 321  * @brief Request a search by area
 322  * @ingroup CAPI_LOCATION_POI_MODULE
 323  * @param [in] service The POI service handle
 324  * @param [in] address The interested address
 325  * @param [in] distance The search area distance
 326  * @param [in] filter The filter handle
 327  * @param [in] callback The result callback
 328  * @param [in] user_data The user data to be passed to the callback function
 329  * @param [out] request_id A Request id, can be set to NULL if does not required operation cancel
 330  * @return 0 on success, otherwise a negative error value.
 331  * @retval #POI_ERROR_NONE Successful
 332  * @retval #POI_ERROR_OUT_OF_MEMORY Out of memory
 333  * @retval #POI_ERROR_INVALID_PARAMETER Invalid parameter
 334  * @retval #POI_ERROR_SERVICE_NOT_AVAILABLE Service not available
 335  * @see poi_service_search_by_area()
 336  * @see poi_service_search_by_position()
 337  * @see poi_service_search_cancel()
 338  * @see poi_service_search_cb()
 339  */
 340 int poi_service_search_by_address(poi_service_h service, const char* address, int distance, poi_filter_h filter, poi_service_search_cb callback, void * user_data, int * request_id);
 341
 342 /**
 343  * @brief Cancel the search request
 344  * @ingroup CAPI_LOCATION_POI_MODULE
 345  * @param [in] service The POI service handle
 346  * @param [in] request_id The request id to cancel
 347  * @return 0 on success, otherwise a negative error value.
 348  * @retval #POI_ERROR_NONE Successful
 349  * @retval #POI_ERROR_INVALID_PARAMETER Invalid parameter
 350  * @pre poi_service_search_by_area() or poi_service_search_by_position() or poi_service_search_by_address() should be called before.
 351  * @see poi_service_search_by_area()
 352  * @see poi_service_search_by_position()
 353  * @see poi_service_search_by_address()
 354  */
 355 int poi_service_cancel(poi_service_h service, int request_id);
 356
 357
 358
 359 /**
 360  * @brief Creates a new POI preference handle.
 361  * @ingroup CAPI_LOCATION_POI_PREFERENCE_MODULE
 362  * @remarks @a preference must be released poi_preference_destroy() by you.
 363  * @param   [out] preference  A handle of a new POI preference handle on success
 364  * @return 0 on success, otherwise a negative error value.
 365  * @retval #POI_ERROR_NONE Successful
 366  * @retval #POI_ERROR_OUT_OF_MEMORY Out of memory
 367  * @retval #POI_ERROR_INVALID_PARAMETER Invalid parameter
 368  * @see poi_preference_destroy()
 369  */
 370 int poi_preference_create(poi_preference_h *preference );
 371
 372 /**
 373  * @brief       Destroys the POI preference handle and releases all its resources.
 374  * @ingroup CAPI_LOCATION_POI_PREFERENCE_MODULE
 375  * @param   [in] preference     The POI preference handle to destroy
 376  * @return  0 on success, otherwise a negative error value.
 377  * @retval #POI_ERROR_NONE Successful
 378  * @retval #POI_ERROR_INVALID_PARAMETER Invalid parameter
 379  * @see poi_service_create()
 380  */
 381 int poi_preference_destroy(poi_preference_h preference );
 382
 383 /**
 384  * @brief Gets the preference value
 385  * @ingroup CAPI_LOCATION_POI_PREFERENCE_MODULE
 386  *
 387  * @param[in] preference        The handle to the POI preference
 388  * @param[in] key       The key of preference
 389  * @param[out] value The preference value
 390  * @return        0 on success, otherwise a negative error value.
 391  * @retval #POI_ERROR_NONE Successful
 392  * @retval #POI_ERROR_INVALID_PARAMETER Invalid parameter
 393  * @retval #POI_ERROR_INVALID_KEY       Invalid key
 394  *
 395  * @see poi_preference_set()
 396  */
 397 int poi_preference_get(poi_preference_h preference, const char *key, char **value);
 398
 399 /**
 400  * @brief Sets the preference value
 401  * @ingroup CAPI_LOCATION_POI_PREFERENCE_MODULE
 402  *
 403  * @param[in] preference        The handle to the POI preference
 404  * @param[in] key       The key of preference
 405  * @param[in] value The preference value to set , could be NULL if want remove value
 406  * @return        0 on success, otherwise a negative error value.
 407  * @retval #POI_ERROR_NONE Successful
 408  * @retval #POI_ERROR_INVALID_PARAMETER Invalid parameter
 409  * @retval #POI_ERROR_INVALID_KEY       Invalid key
 410  *
 411  * @see poi_preference_get()
 412  */
 413 int poi_preference_set(poi_preference_h preference, const char *key, const char *value);
 414
 415 /**
 416  * @brief Sets the number of maximum result
 417  * @ingroup CAPI_LOCATION_POI_PREFERENCE_MODULE
 418  *
 419  * @param[in] preference        The handle to the POI preference
 420  * @param[in] max_result        The number of maximum result
 421  * @return        0 on success, otherwise a negative error value.
 422  * @retval #POI_ERROR_NONE Successful
 423  * @retval #POI_ERROR_INVALID_PARAMETER Invalid parameter
 424  *
 425  * @see poi_preference_get_max_result()
 426  */
 427 int poi_preference_set_max_result(poi_preference_h preference, int max_result);
 428
 429 /**
 430  * @brief Gets the number of maximum result
 431  * @ingroup CAPI_LOCATION_POI_PREFERENCE_MODULE
 432  *
 433  * @param[in] preference        The handle to the POI preference
 434  * @param[out] max_result       The number of maximum result
 435  * @return        0 on success, otherwise a negative error value.
 436  * @retval #POI_ERROR_NONE Successful
 437  * @retval #POI_ERROR_INVALID_PARAMETER Invalid parameter
 438  *
 439  * @see poi_preference_set_max_result()
 440  */
 441 int poi_preference_get_max_result(poi_preference_h preference, int* max_result);
 442
 443 /**
 444  * @brief Sets the sort option
 445  * @ingroup CAPI_LOCATION_POI_PREFERENCE_MODULE
 446  *
 447  * @param[in] preference        The handle to the POI preference
 448  * @param[in] field             The field name for sorting
 449  * @param[in] order      The sort order
 450  * @return        0 on success, otherwise a negative error value.
 451  * @retval #POI_ERROR_NONE Successful
 452  * @retval #POI_ERROR_INVALID_PARAMETER Invalid parameter
 453  *
 454  * @see poi_preference_get_sort()
 455  */
 456 int poi_preference_set_sort(poi_preference_h preference , const char* field , poi_sort_order_e order);
 457
 458 /**
 459  * @brief Gets the sort option
 460  * @ingroup CAPI_LOCATION_POI_PREFERENCE_MODULE
 461  *
 462  * @remarks @a field must be released @c free() by you.
 463  * @param[in] preference        The handle to the POI preference
 464  * @param[out] field            The field name for sorting
 465  * @param[out] order     The sort order
 466  * @return        0 on success, otherwise a negative error value.
 467  * @retval #POI_ERROR_NONE Successful
 468  * @retval #POI_ERROR_INVALID_PARAMETER Invalid parameter
 469  *
 470  * @see poi_preference_set_sort()
 471  */
 472 int poi_preference_get_sort(poi_preference_h preference , char** field,  poi_sort_order_e *order);
 473
 474 /**
 475  * @brief Retrieves all properties in preference
 476  * @ingroup CAPI_LOCATION_POI_PREFERENCE_MODULE
 477  *
 478  * @param[in] preference        The handle to the POI preference
 479  * @param[in] callback  The callback function to invoke
 480  * @param[in] user_data The user data to be passed to the callback function
 481  * @return        0 on success, otherwise a negative error value.
 482  * @retval #POI_ERROR_NONE Successful
 483  * @retval #POI_ERROR_INVALID_PARAMETER Invalid parameter
 484  * @post        This function invokes poi_preference_properties_cb() repeatdly to retrieve each preference properties.
 485  *
 486  * @see poi_preference_properties_cb()
 487  */
 488 int poi_preference_foreach_properties( poi_preference_h preference, poi_preference_properties_cb callback , void * user_data);
 489
 490 /**
 491  * @brief Retrieves all available preference keys
 492  * @ingroup CAPI_LOCATION_POI_PREFERENCE_MODULE
 493  *
 494  * @param[in] service The POI service handle
 495  * @param[in] callback  The callback function to invoke
 496  * @param[in] user_data The user data to be passed to the callback function
 497  * @return        0 on success, otherwise a negative error value.
 498  * @retval #POI_ERROR_NONE Successful
 499  * @retval #POI_ERROR_INVALID_PARAMETER Invalid parameter
 500  * @post        This function invokes poi_preference_available_key_cb() repeatdly to retrieve each available preference keys.
 501  *
 502  * @see poi_preference_available_key_cb()
 503  */
 504 int poi_preference_foreach_available_keys( poi_service_h service,  poi_preference_available_key_cb callback , void * user_data);
 505
 506 /**
 507  * @brief Retrieves all available preference values
 508  * @ingroup CAPI_LOCATION_POI_PREFERENCE_MODULE
 509  *
 510  * @param[in] service The POI service handle
 511  * @param[in] key       The key string
 512  * @param[in] callback  The callback function to invoke
 513  * @param[in] user_data The user data to be passed to the callback function
 514  * @return        0 on success, otherwise a negative error value.
 515  * @retval #POI_ERROR_NONE Successful
 516  * @retval #POI_ERROR_INVALID_PARAMETER Invalid parameter
 517  * @retval #POI_ERROR_INVALID_KEY       Invalid key
 518  * @post        This function invokes poi_preference_available_value_cb() repeatdly to retrieve each available preference values.
 519  *
 520  * @see poi_preference_available_value_cb()
 521  */
 522 int poi_preference_foreach_available_values( poi_service_h service, const char *key,  poi_preference_available_value_cb callback , void * user_data);
 523
 524 /**
 525  * @brief Retrieves all sortable fields
 526  * @ingroup CAPI_LOCATION_POI_PREFERENCE_MODULE
 527  *
 528  * @param[in] service The POI service handle
 529  * @param[in] callback  The callback function to invoke
 530  * @param[in] user_data The user data to be passed to the callback function
 531  * @return        0 on success, otherwise a negative error value.
 532  * @retval #POI_ERROR_NONE Successful
 533  * @retval #POI_ERROR_INVALID_PARAMETER Invalid parameter
 534  * @post        This function invokes poi_preference_sortable_field_cb() repeatdly to retrieve each sortable fields.
 535  *
 536  * @see poi_preference_sortable_field_cb()
 537  * @see poi_preference_set_sort()
 538  * @see         poi_preference_get_sort()
 539  */
 540 int poi_preference_foreach_sortable_field( poi_service_h service , poi_preference_sortable_field_cb callback , void * user_data);
 541
 542
 543 /**
 544  * @brief Creates a new POI filter handle.
 545  * @ingroup CAPI_LOCATION_POI_FILTER_MODULE
 546  * @remarks @a filter must be released poi_filter_destroy() by you.
 547  * @param   [out] filter  A handle of a new POI filter handle on success
 548  * @return 0 on success, otherwise a negative error value.
 549  * @retval #POI_ERROR_NONE Successful
 550  * @retval #POI_ERROR_OUT_OF_MEMORY Out of memory
 551  * @retval #POI_ERROR_INVALID_PARAMETER Invalid parameter
 552  * @see poi_filter_destroy()
 553  */
 554 int poi_filter_create(poi_filter_h *filter);
 555
 556
 557 /**
 558  * @brief       Destroys the POI filter handle and releases all its resources.
 559  * @ingroup CAPI_LOCATION_POI_FILTER_MODULE
 560  * @param   [in] filter The POI filter handle to destroy
 561  * @return  0 on success, otherwise a negative error value.
 562  * @retval #POI_ERROR_NONE Successful
 563  * @retval #POI_ERROR_INVALID_PARAMETER Invalid parameter
 564  * @see poi_filter_create()
 565  */
 566 int poi_filter_destroy(poi_filter_h filter);
 567
 568 /**
 569  * @brief       Sets the filter value
 570  * @ingroup CAPI_LOCATION_POI_FILTER_MODULE
 571  * @param  [in] filter  The handle to the POI filter
 572  * @param       [in] key        The key of filter
 573  * @param       [in] value The filter value to set , could be NULL if want remove value
 574  * @return  0 on success, otherwise a negative error value.
 575  * @retval #POI_ERROR_NONE Successful
 576  * @retval #POI_ERROR_INVALID_PARAMETER Invalid parameter
 577  * @see poi_filter_get()
 578  * @see poi_filter_foreach_available_keys()
 579  */
 580 int poi_filter_set(poi_filter_h filter, const char* key, const char* value);
 581
 582 /**
 583  * @brief       Gets the filter value
 584  * @ingroup CAPI_LOCATION_POI_FILTER_MODULE
 585  * @remarks @a value must be released @c free() by you.
 586  * @param  [in] filter  The handle to the POI filter
 587  * @param       [in] key        The key of filter
 588  * @param       [out] value The filter value
 589  * @return  0 on success, otherwise a negative error value.
 590  * @retval #POI_ERROR_NONE Successful
 591  * @retval #POI_ERROR_INVALID_PARAMETER Invalid parameter
 592  * @see poi_filter_set()
 593  * @see poi_filter_foreach_available_keys()
 594  */
 595 int poi_filter_get(poi_filter_h filter, const char* key, char** value);
 596
 597 /**
 598  * @brief Retrieves all filter properties
 599  * @ingroup CAPI_LOCATION_POI_FILTER_MODULE
 600  *
 601  * @param[in] filter    The handle to the POI filter
 602  * @param[in] callback  The callback function to invoke
 603  * @param[in] user_data The user data to be passed to the callback function
 604  * @return        0 on success, otherwise a negative error value.
 605  * @retval #POI_ERROR_NONE Successful
 606  * @retval #POI_ERROR_INVALID_PARAMETER Invalid parameter
 607  * @post        This function invokes poi_filter_available_key_cb() repeatdly to retrieve each available filter keys.
 608  *
 609  * @see poi_filter_properties_cb()
 610  * @see poi_filter_get()
 611  * @see poi_filter_set()
 612  */
 613 int poi_filter_foreach_properties(poi_filter_h filter, poi_filter_properties_cb callback , void * user_data);
 614
 615 /**
 616  * @brief Retrieves all available filter keys
 617  * @ingroup CAPI_LOCATION_POI_FILTER_MODULE
 618  *
 619  * @param[in] service The POI service handle
 620  * @param[in] callback  The callback function to invoke
 621  * @param[in] user_data The user data to be passed to the callback function
 622  * @return        0 on success, otherwise a negative error value.
 623  * @retval #POI_ERROR_NONE Successful
 624  * @retval #POI_ERROR_INVALID_PARAMETER Invalid parameter
 625  * @post        This function invokes poi_filter_available_key_cb() repeatdly to retrieve each available filter keys.
 626  *
 627  * @see poi_preference_available_key_cb()
 628  * @see poi_filter_get()
 629  * @see poi_filter_set()
 630  */
 631 int poi_filter_foreach_available_keys( poi_service_h service, poi_filter_available_key_cb callback , void * user_data);
 632
 633 /**
 634  * @brief Retrieves all available filter values
 635  * @ingroup CAPI_LOCATION_POI_FILTER_MODULE
 636  *
 637  * @param[in] service The POI service handle
 638  * @param[in] key       The key string
 639  * @param[in] callback  The callback function to invoke
 640  * @param[in] user_data The user data to be passed to the callback function
 641  * @return        0 on success, otherwise a negative error value.
 642  * @retval #POI_ERROR_NONE Successful
 643  * @retval #POI_ERROR_INVALID_PARAMETER Invalid parameter
 644  * @retval #POI_ERROR_INVALID_KEY       Invalid key
 645  * @post        This function invokes poi_filter_available_value_cb() repeatdly to retrieve each available filter values.
 646  *
 647  * @see poi_filter_available_value_cb()
 648  * @see poi_filter_get()
 649  * @see poi_filter_set()
 650  */
 651 int poi_filter_foreach_available_values( poi_service_h service, const char *key, poi_filter_available_value_cb callback , void * user_data);
 652
 653
 654 /**
 655  * @brief Creates a new POI handle.
 656  * @ingroup CAPI_LOCATION_POI_POI_MODULE
 657  * @remarks @a poi must be released poi_destroy() by you.
 658  * @param   [out] poi  A handle of a new POI handle on success
 659  * @return 0 on success, otherwise a negative error value.
 660  * @retval #POI_ERROR_NONE Successful
 661  * @retval #POI_ERROR_OUT_OF_MEMORY Out of memory
 662  * @retval #POI_ERROR_INVALID_PARAMETER Invalid parameter
 663  * @see poi_destroy()
 664  * @see poi_clone()
 665  */
 666 int poi_create(poi_h *poi);
 667
 668 /**
 669  * @brief       Destroys the POI handle and releases all its resources.
 670  * @ingroup CAPI_LOCATION_POI_POI_MODULE
 671  * @param   [in] poi The POI handle to destroy
 672  * @return  0 on success, otherwise a negative error value.
 673  * @retval #POI_ERROR_NONE Successful
 674  * @retval #POI_ERROR_INVALID_PARAMETER Invalid parameter
 675  * @see poi_create()
 676  * @see poi_clone()
 677  */
 678 int poi_destroy(poi_h poi);
 679
 680 /**
 681  * @brief       Clones the POI handle
 682  * @ingroup CAPI_LOCATION_POI_POI_MODULE
 683  * @remarks @a cloned must be released poi_destroy() by you.
 684  * @param  [out] cloned A cloned POI handle
 685  * @param       [in] origin     The original POI handle
 686  * @return  0 on success, otherwise a negative error value.
 687  * @retval #POI_ERROR_NONE Successful
 688  * @retval #POI_ERROR_OUT_OF_MEMORY Out of memory
 689  * @retval #POI_ERROR_INVALID_PARAMETER Invalid parameter
 690  * @see poi_create()
 691  * @see poi_destroy()
 692  */
 693 int poi_clone(poi_h* cloned, poi_h origin);
 694
 695 /**
 696  * @brief       Gets the POI id
 697  * @ingroup CAPI_LOCATION_POI_POI_MODULE
 698  * @param  [in] poi             The handle to POI
 699  * @param       [out] id        The POI id
 700  * @return  0 on success, otherwise a negative error value.
 701  * @retval #POI_ERROR_NONE Successful
 702  * @retval #POI_ERROR_INVALID_PARAMETER Invalid parameter
 703  */
 704 int poi_get_id(poi_h poi, int *id);
 705
 706 /**
 707  * @brief       Gets the POI name
 708  * @ingroup CAPI_LOCATION_POI_POI_MODULE
 709  * @remarks @a name must be released with @c free() by you.
 710  * @param  [in] poi             The handle to POI
 711  * @param       [out] name      The POI name
 712  * @return  0 on success, otherwise a negative error value.
 713  * @retval #POI_ERROR_NONE Successful
 714  * @retval #POI_ERROR_INVALID_PARAMETER Invalid parameter
 715  */
 716 int poi_get_name(poi_h poi, char **name);
 717
 718 /**
 719  * @brief       Gets the POI position
 720  * @ingroup CAPI_LOCATION_POI_POI_MODULE
 721  * @param  [in] poi             The handle to POI
 722  * @param       [out] position  The POI position
 723  * @return  0 on success, otherwise a negative error value.
 724  * @retval #POI_ERROR_NONE Successful
 725  * @retval #POI_ERROR_INVALID_PARAMETER Invalid parameter
 726  */
 727 int poi_get_position(poi_h poi, location_coords_s *position);
 728
 729 /**
 730  * @brief       Gets the POI address
 731  * @ingroup CAPI_LOCATION_POI_POI_MODULE
 732  * @remarks All output values must be released with @c free() by you.
 733  * @param  [in] poi             The handle to POI
 734  * @param       [out] building_number    The building number
 735  * @param       [out] postal_code       The postal delivery code
 736  * @param       [out] street    The full street name
 737  * @param       [out] city      The city name
 738  * @param       [out] district  The municipal district name
 739  * @param       [out] state     The state or province region of a nation
 740  * @param       [out] country_code      The country code
 741  * @return  0 on success, otherwise a negative error value.
 742  * @retval #POI_ERROR_NONE Successful
 743  * @retval #POI_ERROR_INVALID_PARAMETER Invalid parameter
 744  */
 745 int poi_get_address(poi_h poi, char **building_number, char **postal_code, char **street, char **city, char **district, char **state, char **country_code);
 746
 747 /**
 748  * @brief       Gets the POI description
 749  * @ingroup CAPI_LOCATION_POI_POI_MODULE
 750  * @remarks @a description must be released with @c free() by you.
 751  * @param  [in] poi             The handle to POI
 752  * @param       [out] description       The POI description
 753  * @return  0 on success, otherwise a negative error value.
 754  * @retval #POI_ERROR_NONE Successful
 755  * @retval #POI_ERROR_INVALID_PARAMETER Invalid parameter
 756  */
 757 int poi_get_description(poi_h poi, char** description);
 758
 759 /**
 760  * @brief       Gets the POI timestamp
 761  * @ingroup CAPI_LOCATION_POI_POI_MODULE
 762  * @param  [in] poi             The handle to POI
 763  * @param       [out] timestamp The POI timestamp
 764  * @return  0 on success, otherwise a negative error value.
 765  * @retval #POI_ERROR_NONE Successful
 766  * @retval #POI_ERROR_INVALID_PARAMETER Invalid parameter
 767  */
 768 int poi_get_timestamp(poi_h poi , time_t *timestamp);
 769
 770 /**
 771  * @brief       Gets the POI bounding rect
 772  * @ingroup CAPI_LOCATION_POI_POI_MODULE
 773  * @param  [in] poi             The handle to POI
 774  * @param       [out] top_left  The top left position
 775  * @param       [out] bottom_right The bottom right position
 776  * @return  0 on success, otherwise a negative error value.
 777  * @retval #POI_ERROR_NONE Successful
 778  * @retval #POI_ERROR_INVALID_PARAMETER Invalid parameter
 779  */
 780 int poi_get_bounding_rect(poi_h poi , location_coords_s *top_left, location_coords_s *bottom_right);
 781
 782 /**
 783  * @brief       Gets the POI author
 784  * @ingroup CAPI_LOCATION_POI_POI_MODULE
 785  * @remarks @a author must be released with @c free() by you.
 786  * @param  [in] poi             The handle to POI
 787  * @param       [out] author            The POI author
 788  * @return  0 on success, otherwise a negative error value.
 789  * @retval #POI_ERROR_NONE Successful
 790  * @retval #POI_ERROR_INVALID_PARAMETER Invalid parameter
 791  */
 792 int poi_get_author(poi_h poi , char** author);
 793
 794 /**
 795  * @brief       Gets the POI phone number
 796  * @ingroup CAPI_LOCATION_POI_POI_MODULE
 797  * @remarks @a phone_number must be released with @c free() by you.
 798  * @param  [in] poi             The handle to POI
 799  * @param       [out] phone_number              The POI phone number
 800  * @return  0 on success, otherwise a negative error value.
 801  * @retval #POI_ERROR_NONE Successful
 802  * @retval #POI_ERROR_INVALID_PARAMETER Invalid parameter
 803  */
 804 int poi_get_phone_number(poi_h poi , char **phone_number);
 805
 806 /**
 807  * @brief       Retrieves all urls
 808  * @ingroup CAPI_LOCATION_POI_POI_MODULE
 809  * @param  [in] poi             The handle to POI
 810  * @param       [in] callback   The callback function to invoke
 811  * @param       [in] user_data  The user data to be passed to the callback function
 812  * @return  0 on success, otherwise a negative error value.
 813  * @retval #POI_ERROR_NONE Successful
 814  * @retval #POI_ERROR_INVALID_PARAMETER Invalid parameter
 815  * @post        This function invokes poi_urls_cb() repeatdly to retrieve each urls.
 816  * @see poi_urls_cb()
 817  */
 818 int poi_foreach_urls(poi_h poi, poi_urls_cb callback , void * user_data);
 819
 820 /**
 821  * @brief       Retrieves all properties
 822  * @ingroup CAPI_LOCATION_POI_POI_MODULE
 823  * @param  [in] poi             The handle to POI
 824  * @param       [in] callback   The callback function to invoke
 825  * @param       [in] user_data  The user data to be passed to the callback function
 826  * @return  0 on success, otherwise a negative error value.
 827  * @retval #POI_ERROR_NONE Successful
 828  * @retval #POI_ERROR_INVALID_PARAMETER Invalid parameter
 829  * @post        This function invokes poi_properties_cb() repeatdly to retrieve each properties.
 830  * @see poi_properties_cb()
 831  */
 832 int poi_foreach_properties(poi_h poi, poi_properties_cb callback, void * user_data);
 833
 834 /**
 835  * @brief       Retrieves all categories
 836  * @ingroup CAPI_LOCATION_POI_POI_MODULE
 837  * @param  [in] poi             The handle to POI
 838  * @param       [in] callback   The callback function to invoke
 839  * @param       [in] user_data  The user data to be passed to the callback function
 840  * @return  0 on success, otherwise a negative error value.
 841  * @retval #POI_ERROR_NONE Successful
 842  * @retval #POI_ERROR_INVALID_PARAMETER Invalid parameter
 843  * @post        This function invokes poi_categories_cb() repeatdly to retrieve each categories.
 844  * @see poi_categories_cb()
 845  */
 846 int poi_foreach_categories(poi_h poi , poi_categories_cb callback , void * user_data);
 847
 848
 849 #ifdef __cplusplus
 850 }
 851 #endif
 852
 853 #endif /* __TIZEN_LOCATION_POI_H__ */
 854