2 * Copyright (c) 2011-2013 Samsung Electronics Co., Ltd All Rights Reserved
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
8 * http://www.apache.org/licenses/LICENSE-2.0
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.
18 #ifndef __TIZEN_LOCATOIN_POI_H__
19 #define __TIZEN_LOCATOIN_POI_H__
23 #include <location_bounds.h>
31 #define POI_ERROR_CLASS TIZEN_ERROR_LOCATION_CLASS | 0x50
34 * @brief The POI service handle
35 * @ingroup CAPI_LOCATION_POI_MODULE
37 typedef void * poi_service_h;
40 * @brief The POI preference handle
41 * @ingroup CAPI_LOCATION_POI_PREFERENCE_MODULE
43 typedef void * poi_preference_h;
46 * @brief The POI filter handle
47 * @ingroup CAPI_LOCATION_POI_FILTER_MODULE
49 typedef void * poi_filter_h;
52 * @brief The POI handle
53 * @ingroup CAPI_LOCATION_POI_POI_MODULE
59 * @brief Enumerations of sort order
60 * @ingroup CAPI_LOCATION_POI_PREFERENCE_MODULE
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 */
71 * @brief Enumerations of error code for POI
72 * @ingroup CAPI_LOCATION_POI_MODULE
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 */
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()
101 typedef bool (*poi_service_search_cb)(poi_error_e error, int request_id , int index, int length , poi_h poi , void * user_data);
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()
113 typedef bool (*poi_preference_properties_cb)(const char *key , const char *value, void *user_data);
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()
124 typedef bool (*poi_preference_available_key_cb)(const char *key , void *user_data);
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()
135 typedef bool (*poi_preference_available_value_cb)(const char *value , void *user_data);
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()
147 typedef bool (*poi_preference_sortable_field_cb)(const char *field , void *user_data);
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()
159 typedef bool (*poi_filter_properties_cb)(const char *key , const char *value , void *user_data);
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()
171 typedef bool (*poi_filter_available_key_cb)(const char *key , void *user_data);
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()
182 typedef bool (*poi_filter_available_value_cb)(const char *value , void *user_data);
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()
195 typedef bool (*poi_urls_cb)(const char *url , const char *description, void *user_data);
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()
207 typedef bool (*poi_properties_cb)(const char *key, const char* value, void *user_data);
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()
218 typedef bool (*poi_categories_cb)(const char *category, void *user_data);
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()
234 int poi_service_create(poi_service_h *service);
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()
246 int poi_service_destroy(poi_service_h service);
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()
259 int poi_service_get_preference(poi_service_h service , poi_preference_h *preference);
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()
272 int poi_service_set_preference(poi_service_h service , poi_preference_h preference);
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()
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);
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()
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);
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()
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);
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()
355 int poi_service_cancel(poi_service_h service, int request_id);
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()
370 int poi_preference_create(poi_preference_h *preference );
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()
381 int poi_preference_destroy(poi_preference_h preference );
384 * @brief Gets the preference value
385 * @ingroup CAPI_LOCATION_POI_PREFERENCE_MODULE
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
395 * @see poi_preference_set()
397 int poi_preference_get(poi_preference_h preference, const char *key, char **value);
400 * @brief Sets the preference value
401 * @ingroup CAPI_LOCATION_POI_PREFERENCE_MODULE
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
411 * @see poi_preference_get()
413 int poi_preference_set(poi_preference_h preference, const char *key, const char *value);
416 * @brief Sets the number of maximum result
417 * @ingroup CAPI_LOCATION_POI_PREFERENCE_MODULE
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
425 * @see poi_preference_get_max_result()
427 int poi_preference_set_max_result(poi_preference_h preference, int max_result);
430 * @brief Gets the number of maximum result
431 * @ingroup CAPI_LOCATION_POI_PREFERENCE_MODULE
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
439 * @see poi_preference_set_max_result()
441 int poi_preference_get_max_result(poi_preference_h preference, int* max_result);
444 * @brief Sets the sort option
445 * @ingroup CAPI_LOCATION_POI_PREFERENCE_MODULE
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
454 * @see poi_preference_get_sort()
456 int poi_preference_set_sort(poi_preference_h preference , const char* field , poi_sort_order_e order);
459 * @brief Gets the sort option
460 * @ingroup CAPI_LOCATION_POI_PREFERENCE_MODULE
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
470 * @see poi_preference_set_sort()
472 int poi_preference_get_sort(poi_preference_h preference , char** field, poi_sort_order_e *order);
475 * @brief Retrieves all properties in preference
476 * @ingroup CAPI_LOCATION_POI_PREFERENCE_MODULE
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.
486 * @see poi_preference_properties_cb()
488 int poi_preference_foreach_properties( poi_preference_h preference, poi_preference_properties_cb callback , void * user_data);
491 * @brief Retrieves all available preference keys
492 * @ingroup CAPI_LOCATION_POI_PREFERENCE_MODULE
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.
502 * @see poi_preference_available_key_cb()
504 int poi_preference_foreach_available_keys( poi_service_h service, poi_preference_available_key_cb callback , void * user_data);
507 * @brief Retrieves all available preference values
508 * @ingroup CAPI_LOCATION_POI_PREFERENCE_MODULE
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.
520 * @see poi_preference_available_value_cb()
522 int poi_preference_foreach_available_values( poi_service_h service, const char *key, poi_preference_available_value_cb callback , void * user_data);
525 * @brief Retrieves all sortable fields
526 * @ingroup CAPI_LOCATION_POI_PREFERENCE_MODULE
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.
536 * @see poi_preference_sortable_field_cb()
537 * @see poi_preference_set_sort()
538 * @see poi_preference_get_sort()
540 int poi_preference_foreach_sortable_field( poi_service_h service , poi_preference_sortable_field_cb callback , void * user_data);
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()
554 int poi_filter_create(poi_filter_h *filter);
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()
566 int poi_filter_destroy(poi_filter_h filter);
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()
580 int poi_filter_set(poi_filter_h filter, const char* key, const char* value);
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()
595 int poi_filter_get(poi_filter_h filter, const char* key, char** value);
598 * @brief Retrieves all filter properties
599 * @ingroup CAPI_LOCATION_POI_FILTER_MODULE
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.
609 * @see poi_filter_properties_cb()
610 * @see poi_filter_get()
611 * @see poi_filter_set()
613 int poi_filter_foreach_properties(poi_filter_h filter, poi_filter_properties_cb callback , void * user_data);
616 * @brief Retrieves all available filter keys
617 * @ingroup CAPI_LOCATION_POI_FILTER_MODULE
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.
627 * @see poi_preference_available_key_cb()
628 * @see poi_filter_get()
629 * @see poi_filter_set()
631 int poi_filter_foreach_available_keys( poi_service_h service, poi_filter_available_key_cb callback , void * user_data);
634 * @brief Retrieves all available filter values
635 * @ingroup CAPI_LOCATION_POI_FILTER_MODULE
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.
647 * @see poi_filter_available_value_cb()
648 * @see poi_filter_get()
649 * @see poi_filter_set()
651 int poi_filter_foreach_available_values( poi_service_h service, const char *key, poi_filter_available_value_cb callback , void * user_data);
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
666 int poi_create(poi_h *poi);
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
678 int poi_destroy(poi_h poi);
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
693 int poi_clone(poi_h* cloned, poi_h origin);
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
704 int poi_get_id(poi_h poi, int *id);
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
716 int poi_get_name(poi_h poi, char **name);
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
727 int poi_get_position(poi_h poi, location_coords_s *position);
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
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);
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
757 int poi_get_description(poi_h poi, char** description);
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
768 int poi_get_timestamp(poi_h poi , time_t *timestamp);
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
780 int poi_get_bounding_rect(poi_h poi , location_coords_s *top_left, location_coords_s *bottom_right);
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
792 int poi_get_author(poi_h poi , char** author);
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
804 int poi_get_phone_number(poi_h poi , char **phone_number);
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.
818 int poi_foreach_urls(poi_h poi, poi_urls_cb callback , void * user_data);
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()
832 int poi_foreach_properties(poi_h poi, poi_properties_cb callback, void * user_data);
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()
846 int poi_foreach_categories(poi_h poi , poi_categories_cb callback , void * user_data);
853 #endif /* __TIZEN_LOCATION_POI_H__ */