2 * Copyright (c) 2014 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.
17 #ifndef __MAPS_PREFERENCE_H__
18 #define __MAPS_PREFERENCE_H__
20 #include <tizen_type.h>
27 * @ingroup CAPI_MAPS_SERVICE_MODULE
28 * @defgroup CAPI_MAPS_PREFERENCE_MODULE Preference
30 * @file maps_preference.h
31 * @brief This file contains the enumerations of Maps API preferences
33 * @addtogroup CAPI_MAPS_PREFERENCE_MODULE
35 * @brief This provides enumerations of Maps API preferences
37 * - - - - - - - - - - - - -
39 * Preference key names
40 * --------------------
42 * The Preferences are organized as a key-value table where available Preference
43 * keys are following strings:
45 * * Place search preferences
46 * - MAPS_PLACE_FILTER_TYPE
47 * - MAPS_PLACE_FILTER_SORT_BY
49 * * Route search preferences
50 * - MAPS_ROUTE_FREEFORM_ADDR_TO_AVOID
51 * - MAPS_ROUTE_STRUCTED_ADDR_TO_AVOID
52 * - MAPS_ROUTE_CIRCLE_AREA_TO_AVOID
53 * - MAPS_ROUTE_RECT_AREA_TO_AVOID
55 * - MAPS_ROUTE_GEOMETRY_BOUNDING_BOX
56 * - MAPS_ROUTE_GEOMETRY_RETRIEVAL
57 * - MAPS_ROUTE_INSTRUCTION_GEOMETRY
58 * - MAPS_ROUTE_INSTRUCTION_BOUNDING_BOX
59 * - MAPS_ROUTE_INSTRUCTION_RETRIEVAL
60 * - MAPS_ROUTE_REALTIME_TRAFFIC
66 * @brief The name of the preference indicating place type while searching
70 #define MAPS_PLACE_FILTER_TYPE "MAPS_PLACE_FILTER_TYPE"
73 * @brief The name of the preference indicating sorting key while
77 #define MAPS_PLACE_FILTER_SORT_BY "MAPS_PLACE_FILTER_SORT_BY"
80 * @brief The name of the preference indicating free-form address to avoid
81 * while computing the route
84 #define MAPS_ROUTE_FREEFORM_ADDR_TO_AVOID "MAPS_ROUTE_FREEFORM_ADDR_TO_AVOID"
87 * @brief The name of the preference indicating structured address to
88 * avoid while computing the route
91 #define MAPS_ROUTE_STRUCTED_ADDR_TO_AVOID "MAPS_ROUTE_STRUCTED_ADDR_TO_AVOID"
94 * @brief The name of the preference indicating circular geographical area
95 * to avoid while computing the route
98 #define MAPS_ROUTE_CIRCLE_AREA_TO_AVOID "MAPS_ROUTE_CIRCLE_AREA_TO_AVOID"
101 * @brief The name of the preference indicating rectangular geographical
102 * area to avoid while computing the route
105 #define MAPS_ROUTE_RECT_AREA_TO_AVOID "MAPS_ROUTE_RECT_AREA_TO_AVOID"
108 * @brief The name of the preference indicating that route should be
109 * computed within a specified bounding box
112 #define MAPS_ROUTE_GEOMETRY_BOUNDING_BOX "MAPS_ROUTE_GEOMETRY_BOUNDING_BOX"
115 * @brief The name of the preference indicating that geometry parameters
116 * should be retrieved while route processing
119 #define MAPS_ROUTE_GEOMETRY_RETRIEVAL "MAPS_ROUTE_GEOMETRY_RETRIEVAL"
122 * @brief The name of the preference indicating that route should be
123 * computed with geometry instructions
126 #define MAPS_ROUTE_INSTRUCTION_GEOMETRY "MAPS_ROUTE_INSTRUCTION_GEOMETRY"
129 * @brief The name of the preference indicating that route should be
130 * computed with bounding box instructions
133 #define MAPS_ROUTE_INSTRUCTION_BOUNDING_BOX "MAPS_ROUTE_INSTRUCTION_BOUNDING_BOX"
136 * @brief The name of the preference indicating that route should be
137 * computed correspondingly to retrieval instructions
140 #define MAPS_ROUTE_INSTRUCTION_RETRIEVAL "MAPS_ROUTE_INSTRUCTION_RETRIEVAL"
143 * @brief The name of the preference indicating that route should be
144 * computed in accordance to real time traffic
147 #define MAPS_ROUTE_REALTIME_TRAFFIC "MAPS_ROUTE_REALTIME_TRAFFIC"
150 * @brief The Maps Preference handle.
151 * @details The Maps Preference handle can be obtained via call of
152 * maps_preference_create().
154 * \n To release the handle use maps_preference_destroy().
155 * \n To clone the handle use maps_preference_clone().
158 * @see maps_preference_create()
159 * @see maps_preference_destroy()
160 * @see maps_preference_clone()
162 typedef void *maps_preference_h;
165 * @brief Enumeration of allowed distance units.
166 * @details This enumeration represents allowed distance units used in Maps
168 * \n This enumeration is used in #maps_area_s.
171 * @see #maps_preference_h
173 typedef enum _maps_distance_unit_e {
174 MAPS_DISTANCE_UNIT_M, /**< for Meter */
175 MAPS_DISTANCE_UNIT_KM, /**< for Kilometer */
176 MAPS_DISTANCE_UNIT_FT, /**< for Foot */
177 MAPS_DISTANCE_UNIT_YD /**< for Yard */
178 } maps_distance_unit_e;
181 * @brief Enumeration of allowed route optimization option.
182 * @details This enumeration represents allowed route optimization option used
184 * \n This enumeration is used in #maps_area_s.
187 * @see #_maps_route_transport_mode_e
188 * @see #_maps_route_feature_weight_e
189 * @see #_maps_route_request_feature_e
191 typedef enum _maps_route_optimization_e {
193 MAPS_ROUTE_TYPE_FASTEST, /**< Indicates the fastest route */
195 MAPS_ROUTE_TYPE_SHORTEST, /**< Indicates the shortest route
198 MAPS_ROUTE_TYPE_ECONOMIC, /**< Indicates the most economic route
201 MAPS_ROUTE_TYPE_SCENIC, /**< Indicates the most scenic route */
203 MAPS_ROUTE_TYPE_FASTESTNOW, /**< Indicates the most fastest route now */
205 MAPS_ROUTE_TYPE_DIRECTDRIVE /**< Indicates direct drive */
207 } maps_route_optimization_e;
210 * @brief Enumeration of preferable route types.
211 * @details This enumeration represents allowed route types used in Route
213 * \n This enumeration is used in #maps_area_s.
216 * @see #_maps_distance_unit_e
217 * @see #_maps_route_feature_weight_e
218 * @see #_maps_route_request_feature_e
220 typedef enum _maps_route_transport_mode_e {
222 MAPS_ROUTE_TRANSPORT_MODE_CAR, /**< Indicates that the route is to be
225 MAPS_ROUTE_TRANSPORT_MODE_PEDESTRIAN, /**< Indicates that the route is
228 MAPS_ROUTE_TRANSPORT_MODE_BICYCLE, /**< Indicates that the route is for
231 MAPS_ROUTE_TRANSPORT_MODE_PUBLICTRANSIT, /**< Indicates that the route
232 is to be traveled using
235 MAPS_ROUTE_TRANSPORT_MODE_TRUCK /**< Indicates that the route is for a
237 } maps_route_transport_mode_e;
240 * @brief Enumeration of route feature weights.
241 * @details This enumeration represents allowed route feature weights used in
243 * \n This enumeration is used in #maps_area_s.
246 * @see #_maps_distance_unit_e
247 * @see #_maps_route_transport_mode_e
248 * @see #_maps_route_request_feature_e
250 typedef enum _maps_route_feature_weight_e {
252 MAPS_ROUTE_FEATURE_WEIGHT_NORMAL, /**< Indicates normal weighting. */
254 MAPS_ROUTE_FEATURE_WEIGHT_PREFER, /**< Indicates that a feature is
257 MAPS_ROUTE_FEATURE_WEIGHT_AVOID, /**< Indicates that a feature is to be
260 MAPS_ROUTE_FEATURE_WEIGHT_SOFTEXCLUDE, /**< Indicates that soft-exclude
261 applies to the feature. */
263 MAPS_ROUTE_FEATURE_WEIGHT_STRICTEXCLUDE /**< Indicates that the feature
264 is to be strictly excluded. */
265 } maps_route_feature_weight_e;
268 * @brief Enumeration of route features.
269 * @details This enumeration represents allowed route features used in Route
271 * \n This enumeration is used in #maps_area_s.
274 * @see #_maps_distance_unit_e
275 * @see #_maps_route_transport_mode_e
276 * @see #_maps_route_feature_weight_e
278 typedef enum _maps_route_request_feature_e {
280 MAPS_ROUTE_FEATURE_NO, /**< Indicates no route features
283 MAPS_ROUTE_FEATURE_TOLL, /**< Indicates toll roads
284 (toll gates/booths). */
286 MAPS_ROUTE_FEATURE_MOTORWAY, /**< Indicates motorway. */
288 MAPS_ROUTE_FEATURE_BOATFERRY, /**< Indicates a boat ferry. */
290 MAPS_ROUTE_FEATURE_RAILFERRY, /**< Indicates rail (train) ferry. */
292 MAPS_ROUTE_FEATURE_PUBLICTTRANSIT, /**< Indicates public transport. */
294 MAPS_ROUTE_FEATURE_TUNNEL, /**< Indicates tunnel. */
296 MAPS_ROUTE_FEATURE_DIRTROAD, /**< Indicates dirt road. */
298 MAPS_ROUTE_FEATURE_PARKS, /**< Indicates park. */
300 MAPS_ROUTE_FEATURE_HOVLANE, /**< Indicates a high-occupancy vehicle
303 MAPS_ROUTE_FEATURE_STAIRS /**< Indicates stairs. */
304 } maps_route_feature_e;
306 /*----------------------------------------------------------------------------*/
309 * @brief Called when requesting the list of Maps Properties.
310 * @details This callback is invoked while iterating through the list of Maps
313 * @remarks @a key and @a value must be released using free() and corresponding
314 * release method for property value correspondingly.
316 * @param[in] index The current index of property
317 * @param[in] total The total amount of properties
318 * @param[in] key The key of property
319 * @param[in] value The value of property
320 * @param[in] user_data The user data passed from
321 * maps_preference_foreach_property()
322 * @return @c true to continue with the next iteration of the loop, \n @c
323 * false to break out of the loop
325 * @pre maps_preference_foreach_property() will invoke this callback.
327 * @see maps_preference_foreach_property()
329 typedef bool(*maps_preference_properties_cb) (int index, int total, char *key,
330 char *value, void *user_data);
332 /*----------------------------------------------------------------------------*/
335 * @brief Creates a new maps preference handle.
336 * @details This function creates a new maps preference handle and allocates all
339 * @remarks @a preference must be released using maps_preference_destroy().
340 * \n @a preference may be cloned using maps_preference_clone().
342 * @param[out] preference A newly created preference handle
343 * @return 0 on success, otherwise a negative error value
344 * @retval #MAPS_ERROR_NONE Successful
345 * @retval #MAPS_ERROR_INVALID_PARAMETER Invalid parameter
346 * @retval #MAPS_ERROR_OUT_OF_MEMORY Out of memory
348 * @see maps_preference_destroy()
349 * @see maps_preference_clone()
351 int maps_preference_create(maps_preference_h *preference);
354 * @brief Destroys the maps preference handle and releases all its
356 * @details This function destroys the maps preference handle and releases all
360 * @param[in] preference The preference handle
361 * @return 0 on success, otherwise a negative error value
362 * @retval #MAPS_ERROR_NONE Successful
363 * @retval #MAPS_ERROR_INVALID_PARAMETER Invalid parameter
365 * @see maps_preference_clone()
367 int maps_preference_destroy(maps_preference_h preference);
370 * @brief Clones the maps preference handle.
371 * @details This function clones the maps preference handle @a origin and all
374 * @remarks @a cloned must be released using maps_preference_destroy().
376 * @param[in] origin The original preference handle
377 * @param[out] cloned A cloned preference handle
378 * @return 0 on success, otherwise a negative error value
379 * @retval #MAPS_ERROR_NONE Successful
380 * @retval #MAPS_ERROR_INVALID_PARAMETER Invalid parameter
381 * @retval #MAPS_ERROR_OUT_OF_MEMORY Out of memory
383 * @see maps_preference_destroy()
385 int maps_preference_clone(const maps_preference_h origin,
386 maps_preference_h *cloned);
388 /*----------------------------------------------------------------------------*/
391 * @brief Gets the distance unit.
392 * @details This function gets the maps distance unit.
395 * @param[in] preference The preference handle
396 * @param[out] unit The distance unit
397 * @return 0 on success, otherwise a negative error value
398 * @retval #MAPS_ERROR_NONE Successful
399 * @retval #MAPS_ERROR_INVALID_PARAMETER Invalid parameter
401 int maps_preference_get_distance_unit(const maps_preference_h preference,
402 maps_distance_unit_e *unit);
405 * @brief Gets the language.
406 * @details This function gets the maps language.
408 * @remarks @a language must be released using free().
410 * @param[in] preference The preference handle
411 * @param[out] language The language
412 * @return 0 on success, otherwise a negative error value
413 * @retval #MAPS_ERROR_NONE Successful
414 * @retval #MAPS_ERROR_INVALID_PARAMETER Invalid parameter
416 int maps_preference_get_language(const maps_preference_h preference,
420 * @brief Gets the max amount of results.
421 * @details This function gets the max amount of results.
424 * @param[in] preference The preference handle
425 * @param[out] max_results The max amount of results
426 * @return 0 on success, otherwise a negative error value
427 * @retval #MAPS_ERROR_NONE Successful
428 * @retval #MAPS_ERROR_INVALID_PARAMETER Invalid parameter
430 int maps_preference_get_max_results(const maps_preference_h preference,
434 * @brief Gets the country code.
435 * @details This function gets the country code.
437 * @remarks @a country_code must be released using free().
439 * @param[in] preference The preference handle
440 * @param[out] country_code The country code
441 * @return 0 on success, otherwise a negative error value
442 * @retval #MAPS_ERROR_NONE Successful
443 * @retval #MAPS_ERROR_INVALID_PARAMETER Invalid parameter
445 int maps_preference_get_country_code(const maps_preference_h preference,
446 char **country_code);
449 * @brief Gets the route optimization.
450 * @details This function gets the route optimization.
453 * @param[in] preference The preference handle
454 * @param[out] optimization The route optimization
455 * @return 0 on success, otherwise a negative error value
456 * @retval #MAPS_ERROR_NONE Successful
457 * @retval #MAPS_ERROR_INVALID_PARAMETER Invalid parameter
459 int maps_preference_get_route_optimization(const maps_preference_h preference,
460 maps_route_optimization_e *
464 * @brief Gets the route transport mode.
465 * @details This function gets the route transport mode.
468 * @param[in] preference The preference handle
469 * @param[out] transport_mode The transport mode
470 * @return 0 on success, otherwise a negative error value
471 * @retval #MAPS_ERROR_NONE Successful
472 * @retval #MAPS_ERROR_INVALID_PARAMETER Invalid parameter
474 int maps_preference_get_route_transport_mode(const maps_preference_h
476 maps_route_transport_mode_e *
480 * @brief Gets the route feature weight.
481 * @details This function gets the route feature weight.
484 * @param[in] preference The preference handle
485 * @param[out] feature_weight The feature weight
486 * @return 0 on success, otherwise a negative error value
487 * @retval #MAPS_ERROR_NONE Successful
488 * @retval #MAPS_ERROR_INVALID_PARAMETER Invalid parameter
490 int maps_preference_get_route_feature_weight(const maps_preference_h
492 maps_route_feature_weight_e *
496 * @brief Gets the route feature.
497 * @details This function gets the route feature.
500 * @param[in] preference The preference handle
501 * @param[out] feature The feature
502 * @return 0 on success, otherwise a negative error value
503 * @retval #MAPS_ERROR_NONE Successful
504 * @retval #MAPS_ERROR_INVALID_PARAMETER Invalid parameter
506 int maps_preference_get_route_feature(const maps_preference_h preference,
507 maps_route_feature_e *feature);
510 * @brief Gets the maps preference value by key.
511 * @details This function gets the maps preference value by key.
513 * @remarks @a value must be released using free().
515 * @param[in] preference The preference handle
516 * @param[in] key The preference key
517 * @param[out] value The preference value
518 * @return 0 on success, otherwise a negative error value
519 * @retval #MAPS_ERROR_NONE Successful
520 * @retval #MAPS_ERROR_INVALID_PARAMETER Invalid parameter
522 int maps_preference_get(const maps_preference_h preference, const char *key,
526 * @brief Retrieves all maps properties.
527 * @details This function retrieves all maps properties.
529 * @remarks The properties will be delivered via
530 * maps_preference_properties_cb().
532 * @param[in] preference The preference handle
533 * @param[in] callback The callback function to invoke
534 * @param[in] user_data The user data to be passed to the callback
536 * @return 0 on success, otherwise a negative error value
537 * @retval #MAPS_ERROR_NONE Successful
538 * @retval #MAPS_ERROR_INVALID_PARAMETER Invalid parameter
539 * @retval #MAPS_ERROR_NOT_FOUND Result not found
541 * @post This function invokes maps_preference_properties_cb() repeatedly to
542 * retrieve each property.
544 * @see maps_preference_properties_cb()
546 int maps_preference_foreach_property(const maps_preference_h preference,
547 maps_preference_properties_cb callback,
550 /*----------------------------------------------------------------------------*/
553 * @brief Sets the maps distance unit.
554 * @details This function sets the maps distance unit.
557 * @param[in] preference The preference handle
558 * @param[in] unit The distance unit
559 * @return 0 on success, otherwise a negative error value
560 * @retval #MAPS_ERROR_NONE Successful
561 * @retval #MAPS_ERROR_INVALID_PARAMETER Invalid parameter
563 * @pre @a preference is created using maps_preference_create().
565 * @see maps_preference_create()
566 * @see maps_preference_get_distance_unit()
568 int maps_preference_set_distance_unit(maps_preference_h preference,
569 const maps_distance_unit_e unit);
572 * @brief Sets the maps language.
573 * @details This function sets the maps language.
576 * @param[in] preference The preference handle
577 * @param[in] language The maps language
578 * @return 0 on success, otherwise a negative error value
579 * @retval #MAPS_ERROR_NONE Successful
580 * @retval #MAPS_ERROR_INVALID_PARAMETER Invalid parameter
582 * @pre @a preference is created using maps_preference_create().
584 * @see maps_preference_create()
585 * @see maps_preference_get_language()
587 int maps_preference_set_language(maps_preference_h preference,
588 const char *language);
591 * @brief Sets the max amount of results.
592 * @details This function sets the max amount of results.
595 * @param[in] preference The preference handle
596 * @param[in] max_results The max amount of results
597 * @return 0 on success, otherwise a negative error value
598 * @retval #MAPS_ERROR_NONE Successful
599 * @retval #MAPS_ERROR_INVALID_PARAMETER Invalid parameter
601 * @pre @a preference is created using maps_preference_create().
603 * @see maps_preference_create()
604 * @see maps_preference_get_max_results()
606 int maps_preference_set_max_results(maps_preference_h preference,
607 const int max_results);
610 * @brief Sets the maps country code.
611 * @details This function sets the maps country code.
614 * @param[in] preference The preference handle
615 * @param[in] country_code The maps country code
616 * @return 0 on success, otherwise a negative error value
617 * @retval #MAPS_ERROR_NONE Successful
618 * @retval #MAPS_ERROR_INVALID_PARAMETER Invalid parameter
620 * @pre @a preference is created using maps_preference_create().
622 * @see maps_preference_create()
623 * @see maps_preference_get_country_code()
625 int maps_preference_set_country_code(maps_preference_h preference,
626 const char *country_code);
629 * @brief Sets the route optimization.
630 * @details This function sets the route optimization.
633 * @param[in] preference The preference handle
634 * @param[in] optimization The route optimization
635 * @return 0 on success, otherwise a negative error value
636 * @retval #MAPS_ERROR_NONE Successful
637 * @retval #MAPS_ERROR_INVALID_PARAMETER Invalid parameter
639 * @pre @a preference is created using maps_preference_create().
641 * @see maps_preference_create()
642 * @see maps_preference_get_route_optimization()
644 int maps_preference_set_route_optimization(maps_preference_h preference,
645 const maps_route_optimization_e
649 * @brief Sets the route transport mode.
650 * @details This function sets the route transport mode.
653 * @param[in] preference The preference handle
654 * @param[in] transport_mode The route transport mode
655 * @return 0 on success, otherwise a negative error value
656 * @retval #MAPS_ERROR_NONE Successful
657 * @retval #MAPS_ERROR_INVALID_PARAMETER Invalid parameter
659 * @pre @a preference is created using maps_preference_create().
661 * @see maps_preference_create()
662 * @see maps_preference_get_route_optimization()
664 int maps_preference_set_route_transport_mode(maps_preference_h preference,
665 const maps_route_transport_mode_e
669 * @brief Sets the route feature weight.
670 * @details This function sets the route feature weight.
673 * @param[in] preference The preference handle
674 * @param[in] feature_weight The route feature weight
675 * @return 0 on success, otherwise a negative error value
676 * @retval #MAPS_ERROR_NONE Successful
677 * @retval #MAPS_ERROR_INVALID_PARAMETER Invalid parameter
679 * @pre @a preference is created using maps_preference_create().
681 * @see maps_preference_create()
682 * @see maps_preference_get_route_feature_weight()
684 int maps_preference_set_route_feature_weight(maps_preference_h preference,
685 const maps_route_feature_weight_e
689 * @brief Sets the route feature.
690 * @details This function sets the route feature.
693 * @param[in] preference The preference handle
694 * @param[in] feature The route feature
695 * @return 0 on success, otherwise a negative error value
696 * @retval #MAPS_ERROR_NONE Successful
697 * @retval #MAPS_ERROR_INVALID_PARAMETER Invalid parameter
699 * @pre @a preference is created using maps_preference_create().
701 * @see maps_preference_create()
702 * @see maps_preference_get_route_feature()
704 int maps_preference_set_route_feature(maps_preference_h preference,
705 const maps_route_feature_e feature);
708 * @brief Sets the preference value by key.
709 * @details This function sets the preference value assigned with a specified
713 * @param[in] preference The preference handle
714 * @param[in] key The key
715 * @param[in] value The value
716 * @return 0 on success, otherwise a negative error value
717 * @retval #MAPS_ERROR_NONE Successful
718 * @retval #MAPS_ERROR_INVALID_PARAMETER Invalid parameter
720 * @pre @a preference is created using maps_preference_create().
722 * @see maps_preference_create()
723 * @see maps_preference_get_property()
724 * @see maps_preference_foreach_property()
726 int maps_preference_set_property(maps_preference_h preference,
727 const char *key, const char *value);
735 #endif /* __MAPS_PREFERENCE_H__ */