4 * Copyright (c) 2010-2011 Samsung Electronics Co., Ltd. All rights reserved.
6 * Contact: Youngae Kang <youngae.kang@samsung.com>, Yunhan Kim <yhan.kim@samsung.com>,
7 * Genie Kim <daejins.kim@samsung.com>, Minjune Kim <sena06.kim@samsung.com>
9 * Licensed under the Apache License, Version 2.0 (the "License");
10 * you may not use this file except in compliance with the License.
11 * You may obtain a copy of the License at
13 * http://www.apache.org/licenses/LICENSE-2.0
15 * Unless required by applicable law or agreed to in writing, software
16 * distributed under the License is distributed on an "AS IS" BASIS,
17 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
18 * See the License for the specific language governing permissions and
19 * limitations under the License.
22 #ifndef __LOCATION_ROUTE_H__
23 #define __LOCATION_ROUTE_H__
25 #include <location-map-types.h>
30 * @file location-route.h
31 * @brief This file contains the internal definitions and structures related to Route.
35 * @addtogroup LocationMapService
37 * @defgroup LocationMapServiceRoute Location Route
38 * @brief This is a Location Route for providing location map services.
39 * @addtogroup LocationMapServiceRoute
44 * @brief Create a new Location route preference
46 * @pre #location_init should be called before.\n
48 * @return a #LocationRoutePreference
49 * @retval NULL if error occured
50 * @see location_route_pref_free
52 LocationRoutePreference *location_route_pref_new (void);
55 * @brief Copy Location route preference
57 * @pre #location_init should be called before.\n
59 * @param [in] pref - a #LocationRoutePreference
60 * @return a new #LocationRoutePreference
61 * @retval NULL if error occured
63 LocationRoutePreference *location_route_pref_copy (const LocationRoutePreference *pref);
66 * @brief Free Location route preference
68 * @pre #location_init should be called before.\n
70 * @param [in] pref - a #LocationRoutePreference
71 * @see location_route_pref_new
75 void location_route_pref_free (LocationRoutePreference * pref);
78 * @brief Get a list of address structures to be avoided in Location route preference
79 * @remarks The service provider should support route service.
80 * @pre #location_route_pref_new should be called before.
82 * @param [in] pref - a #LocationRoutePreference
84 * @retval list of #LocationAddress
85 * @see location_route_pref_set_addr_to_avoid
87 GList *location_route_pref_get_addr_to_avoid (const LocationRoutePreference *pref);
90 * @brief Get a list of area to be avoided in Location route preference
91 * @remarks The service provider should support route service.
92 * @pre #location_route_pref_new should be called before.
94 * @param [in] pref - a #LocationRoutePreference
96 * @retval list of #LocationBoundary
97 * @see location_route_pref_set_area_to_avoid
99 GList *location_route_pref_get_area_to_avoid (const LocationRoutePreference *pref);
102 * @brief Get a list of features to be avoided in Location route preference
103 * @remarks The service provider should support route service.
104 * @pre #location_route_pref_new should be called before.
106 * @param [in] pref - a #LocationRoutePreference
108 * @retval list of gchar
109 * @see location_route_pref_set_feature_to_avoid
111 GList *location_route_pref_get_feature_to_avoid (const LocationRoutePreference *pref);
114 * @brief Get a list of freeformed address to be avoided in Location route preference
115 * @remarks The service provider should support route service.
116 * @pre #location_route_pref_new should be called before.
118 * @param [in] pref - a #LocationRoutePreference
120 * @retval list of gchar
121 * @see location_route_pref_set_freeformed_to_avoid
123 GList *location_route_pref_get_freeformed_addr_to_avoid (const LocationRoutePreference *pref);
126 * @brief Get a list of bounding box to be avoided in Location route preference
127 * @remarks The service provider should support route service.
128 * @pre #location_route_pref_new should be called before.
130 * @param [in] pref - a #LocationRoutePreference
131 * @return #LocationBoundary
132 * @retval bounding box
133 * @see location_route_pref_set_addr_to_avoid
135 LocationBoundary *location_route_pref_get_bounding_box (const LocationRoutePreference *pref);
138 * @brief Get a maximum number of matches returned from route service provider
139 * @remarks The service provider should support route service.
140 * @pre #location_route_pref_new should be called before.
142 * @param [in] pref - a #LocationRoutePreference
144 * @retval maximum number of matches
145 * @see location_route_pref_set_max_result
147 guint location_route_pref_get_max_result (const LocationRoutePreference *pref);
150 * @brief Get a route type to be used in route service
151 * @remarks The service provider should support route service.
152 * @pre #location_route_pref_new should be called before.
154 * @param [in] pref - a #LocationRoutePreference
157 * @see location_route_pref_set_route_type
159 gchar *location_route_pref_get_route_type (const LocationRoutePreference *pref);
162 * @brief Get a transport mode to be used in route service
163 * @remarks The service provider should support route service.
164 * @pre #location_route_pref_new should be called before.
166 * @param [in] pref - a #LocationRoutePreference
168 * @retval transport mode
169 * @see location_route_pref_set_transport_mode
171 gchar *location_route_pref_get_transport_mode (const LocationRoutePreference *pref);
174 * @brief Get whether the route service provider must provide the route geometry in the service requests
175 * @remarks The service provider should support route service.
176 * @pre #location_route_pref_new should be called before.
178 * @param [in] pref - a #LocationRoutePreference
180 * @retval TRUE if used
181 * @see location_route_pref_set_geometry_used
183 gboolean location_route_pref_get_geometry_used (const LocationRoutePreference *pref);
185 * @brief Get whether the route service provider must provide the route instruction bounding box in the service requests
186 * @remarks The service provider should support route service.
187 * @pre #location_route_pref_new should be called before.
189 * @param [in] pref - a #LocationRoutePreference
191 * @retval TRUE if used
192 * @see location_route_pref_set_instruction_bounding_box_used
194 gboolean location_route_pref_get_instruction_bounding_box_used (const LocationRoutePreference *pref);
196 * @brief Get whether the route service provider must provide the route geometry in the service requests
197 * @remarks The service provider should support route service.
198 * @pre #location_route_pref_new should be called before.
200 * @param [in] pref - a #LocationRoutePreference
202 * @retval TRUE if used
203 * @see location_route_pref_set_instruction_geometry_used
205 gboolean location_route_pref_get_instruction_geometry_used (const LocationRoutePreference *pref);
208 * @brief Get whether the route service provider must provide the route instruction in the service requests
209 * @remarks The service provider should support route service.
210 * @pre #location_route_pref_new should be called before.
212 * @param [in] pref - a #LocationRoutePreference
214 * @retval TRUE if used
215 * @see location_route_pref_set_instruction_used
217 gboolean location_route_pref_get_instruction_used (const LocationRoutePreference *pref);
219 * @brief Get whether the route service provider must provide traffic data in the service requests
220 * @remarks The service provider should support route service.
221 * @pre #location_route_pref_new should be called before.
223 * @param [in] pref - a #LocationRoutePreference
225 * @retval TRUE if used
226 * @see location_route_pref_set_traffic_data_used
228 gboolean location_route_pref_get_traffic_data_used (const LocationRoutePreference *pref);
230 * @brief Get a list of Property Keys in #LocationRoutePreference
231 * @remarks The service provider should support route service.
232 * @pre #location_route_pref_new should be called before.
234 * @param [in] pref - a #LocationRoutePreference
236 * @retval list of property key
238 GList *location_route_pref_get_property_key (const LocationRoutePreference *pref);
240 * @brief Get Property value in #LocationRoutePreference
241 * @remarks The service provider should support route service.
242 * @pre #location_route_pref_new should be called before.
244 * @param [in] pref - a #LocationRoutePreference
246 * @retval property value
247 * @see location_route_pref_set_property
249 gpointer location_route_pref_get_property (const LocationRoutePreference *pref, gconstpointer key);
252 * @brief Set a list of address structures to be avoided in #LocationRoutePreference
253 * @remarks The service provider should support route service.
254 * @pre #location_route_pref_new should be called before.
256 * @param [in] pref - a #LocationRoutePreference
257 * @param [in] addr - a list of #LocationAddress
259 * @retval TRUE if success
260 * @see location_route_pref_get_addr_to_avoid
262 gboolean location_route_pref_set_addr_to_avoid (LocationRoutePreference * pref, GList *addr);
265 * @brief Set a list of area to be avoided in Location route preference
266 * @remarks The service provider should support route service.
267 * @pre #location_route_pref_new should be called before.
269 * @param [in] pref - a #LocationRoutePreference
270 * @param [in] area - a list of #LocationBoundary
272 * @retval TRUE if success
273 * @see location_route_pref_get_area_to_avoid
275 gboolean location_route_pref_set_area_to_avoid (LocationRoutePreference * pref, GList *area);
278 * @brief Set a list of features to be avoided in Location route preference
279 * @remarks The service provider should support route service.
280 * @pre #location_route_pref_new should be called before.
282 * @param [in] pref - a #LocationRoutePreference
283 * @param [in] feature - a list of features
285 * @retval TRUE if success
286 * @see location_route_pref_get_feature_to_avoid
288 gboolean location_route_pref_set_feature_to_avoid (LocationRoutePreference * pref, GList * feature);
291 * @brief Set a list of freeformed address to be avoided in Location route preference
292 * @remarks The service provider should support route service.
293 * @pre #location_route_pref_new should be called before.
295 * @param [in] pref - a #LocationRoutePreference
296 * @param [in] addr - a list of #gchar
298 * @retval TRUE if success
299 * @see location_route_pref_get_freeformed_addr_to_avoid
301 gboolean location_route_pref_set_freeformed_addr_to_avoid (LocationRoutePreference *pref, GList * freeformed_addr);
304 * @brief Set a bounding box #LocationBoundary in Location route preference
305 * @remarks The service provider should support route service.
306 * @pre #location_route_pref_new should be called before.
308 * @param [in] pref - a #LocationRoutePreference
309 * @param [in] bbox - a #LocationBoundary
311 * @retval TRUE if success
312 * @see location_route_pref_get_bounding_box
314 gboolean location_route_pref_set_bounding_box (LocationRoutePreference *pref, const LocationBoundary *boundary);
317 * @brief Set a maximum number of matches returned from route service provider
318 * @remarks The service provider should support route service.
319 * @pre #location_route_pref_new should be called before.
321 * @param [in] pref - a #LocationRoutePreference
322 * @param [in] max_num - a #gint
324 * @retval TRUE if success
325 * @see location_route_pref_set_max_result
327 gboolean location_route_pref_set_max_result (LocationRoutePreference *pref, guint max_num);
330 * @brief Set a route type to be used in route service
331 * @remarks The service provider should support route service.
332 * @pre #location_route_pref_new should be called before.
334 * @param [in] pref - a #LocationRoutePreference
335 * @param [in] type - a #gchar
337 * @retval TRUE if success
338 * @see location_route_pref_get_route_type
340 gboolean location_route_pref_set_route_type (LocationRoutePreference *pref, const gchar *type);
343 * @brief Set a transport mode to be used in route service
344 * @remarks The service provider should support route service.
345 * @pre #location_route_pref_new should be called before.
347 * @param [in] pref - a #LocationRoutePreference
348 * @param [in] mode - a #gchar
350 * @retval TRUE if success
351 * @see location_route_pref_get_transport_mode
353 gboolean location_route_pref_set_transport_mode (LocationRoutePreference *pref, const gchar * mode);
356 * @brief Set whether the route service provider must provide the route geometry in the service requests
357 * @remarks The service provider should support route service.
358 * @pre #location_route_pref_new should be called before.
360 * @param [in] pref - a #LocationRoutePreference
361 * @param [in] is_used - a #gboolean
363 * @retval TRUE if success
364 * @see location_route_pref_get_geometry_used
366 gboolean location_route_pref_set_geometry_used (LocationRoutePreference *pref, gboolean is_used);
369 * @brief Set whether the route service provider must provide the route instruction bounding box in the service requests
370 * @remarks The service provider should support route service.
371 * @pre #location_route_pref_new should be called before.
373 * @param [in] pref - a #LocationRoutePreference
374 * @param [in] is_used - a #gboolean
376 * @retval TRUE if success
377 * @see location_route_pref_get_instruction_bounding_box_used
379 gboolean location_route_pref_set_instruction_bounding_box_used (LocationRoutePreference *pref, gboolean is_used);
382 * @brief Set whether the route service provider must provide the route geometry in the service requests
383 * @remarks The service provider should support route service.
384 * @pre #location_route_pref_new should be called before.
386 * @param [in] pref - a #LocationRoutePreference
387 * @param [in] is_used - a #gboolean
389 * @retval TRUE if success
390 * @see location_route_pref_get_instruction_geometry_used
392 gboolean location_route_pref_set_instruction_geometry_used (LocationRoutePreference *pref, gboolean is_used);
395 * @brief Set whether the route service provider must provide the route instruction in the service requests
396 * @remarks The service provider should support route service.
397 * @pre #location_route_pref_new should be called before.
399 * @param [in] pref - a #LocationRoutePreference
400 * @param [in] is_used - a #gboolean
402 * @retval TRUE if success
403 * @see location_route_pref_get_instruction_used
405 gboolean location_route_pref_set_instruction_used (LocationRoutePreference *pref, gboolean is_used);
408 * @brief Set whether the route service provider must provide traffic data in the service requests
409 * @remarks The service provider should support route service.
410 * @pre #location_route_pref_new should be called before.
412 * @param [in] pref - a #LocationRoutePreference
413 * @param [in] is_used - a #gboolean
415 * @retval TRUE if success
416 * @see location_route_pref_get_traffic_data_used
418 gboolean location_route_pref_set_traffic_data_used (LocationRoutePreference *pref, gboolean is_used);
421 * @brief Set Property in Location route proference
422 * @remarks The service provider should support route service.
423 * @pre #location_route_pref_new should be called before.
425 * @param [in] pref - a #LocationRoutePreference
426 * @param [in] key - a #gconstpointer
427 * @param [in] value - a #gconstpointer
429 * @retval TRUE if success
430 * @see location_route_pref_get_property
432 gboolean location_route_pref_set_property (LocationRoutePreference *pref, gconstpointer key, gconstpointer value);
435 * @defgroup LocationMapServiceRouteResult Location Route Result
436 * @brief This provides structure, enumeration and APIs for Route Result
437 * @addtogroup LocationMapServiceRouteResult
441 * @brief Create a new Location route
442 * @remarks The service provider should support route service.
445 * @return #LocationRoute
446 * @retval a new location route
447 * @see location_route_free
449 LocationRoute *location_route_new (void);
451 * @brief Copy Location route
452 * @remarks The service provider should support route service.
455 * @param [in] route - a #LocationRoute
456 * @return #LocationRoute
457 * @retval a copied location route
459 LocationRoute *location_route_copy (const LocationRoute *route);
462 * @brief Free #LocationRoute
463 * @remarks The service provider should support route service.
466 * @param [in] route - a #LocationRoute
470 void location_route_free (LocationRoute *route);
473 * @brief Get the origin of Location route
474 * @remarks The service provider should support route service.
477 * @param [in] route - a #LocationRoute
478 * @return #Location position
480 * @see location_route_set_origin
482 LocationPosition *location_route_get_origin (const LocationRoute *route);
485 * @brief Get the destination of Location route
486 * @remarks The service provider should support route service.
489 * @param [in] route - a #LocationRoute
490 * @return #LocationPosition
491 * @retval destination
492 * @see location_route_set_destination
494 LocationPosition *location_route_get_destination (const LocationRoute *route);
497 * @brief Get the bounding box of Location route
498 * @remarks The service provider should support route service.
501 * @param [in] route - a #LocationRoute
502 * @return #LocationBoundary
503 * @retval bounding box
504 * @see location_route_set_bounding box
506 LocationBoundary *location_route_get_bounding_box (const LocationRoute *route);
509 * @brief Get the total distance of Location route
510 * @remarks The service provider should support route service.
513 * @param [in] route - a #LocationRoute
515 * @retval total distance
516 * @see location_route_set_total_distance
518 gdouble location_route_get_total_distance (const LocationRoute *route);
521 * @brief Get the distance unit of Location route
522 * @remarks The service provider should support route service.
525 * @param [in] route - a #LocationRoute
527 * @retval distance unit
528 * @see location_route_set_distance_unit
530 gchar *location_route_get_distance_unit (const LocationRoute *route);
533 * @brief Get the total duration of location route
534 * @remarks The service provider should support route service.
537 * @param [in] route - a #LocationRoute
539 * @retval total duration
540 * @see location_route_set_total_duration
542 glong location_route_get_total_duration (const LocationRoute *route);
545 * @brief Get the list of property key of Location route
546 * @remarks The service provider should support route service.
549 * @param [in] route - a #LocationRoute
551 * @retval list of property keys
552 * @see location_route_set_property
554 GList *location_route_get_property_key (const LocationRoute *route);
557 * @brief Get the property value of Location route
558 * @remarks The service provider should support route service.
561 * @param [in] route - a #LocationRoute
562 * @return gconstpointer
564 * @see location_route_set_property
566 gpointer location_route_get_property (const LocationRoute *route, gconstpointer key);
569 * @brief Get the list of segments in Location route
570 * @remarks The service provider should support route service.
573 * @param [in] route - a #LocationRoute
575 * @retval list of #LocationRouteSegment
576 * @see location_route_set_route_segment
578 GList *location_route_get_route_segment (const LocationRoute *route);
581 * @brief Create a new Location route segment
582 * @remarks The service provider should support route service.
585 * @return #LocationPositionSegment
586 * @retval Location route segment
587 * @see location_route_segment_free
589 LocationRouteSegment *location_route_segment_new (void);
592 * @brief Copy Location route segment
593 * @remarks The service provider should support route service.
596 * @param [in] segment - a #LocationRouteSegment
597 * @return #LocationRouteSegment
598 * @retval copied Location route segment
600 LocationRouteSegment *location_route_segment_copy (LocationRouteSegment *segment);
603 * @brief Free Location route segment
604 * @remarks The service provider should support route service.
607 * @param [in] segment - a #LocationRouteSegment
610 * @see location_route_segment_new
612 void location_route_segment_free (LocationRouteSegment *segment);
615 * @brief Get the start point #LocationPosition of #LocationRouteSegment
616 * @remarks The service provider should support route service.
619 * @param [in] segment - a #LocationRouteSegment
622 * @see location_route_segment_set_start_point
624 LocationPosition *location_route_segment_get_start_point (const LocationRouteSegment *segment);
627 * @brief Get the end point #LocationPosition of #LocationRouteSegment
628 * @remarks The service provider should support route service.
631 * @param [in] segment - a #LocationRouteSegment
634 * @see location_route_segment_set_end_point
636 LocationPosition *location_route_segment_get_end_point (const LocationRouteSegment *segment);
639 * @brief Get the bounding box #LocationBoundary of #LocationRouteSegment
640 * @remarks The service provider should support route service.
643 * @param [in] segment - a #LocationRouteSegment
646 * @see location_route_segment_set_bounding_box
648 LocationBoundary *location_route_segment_get_bounding_box (const LocationRouteSegment *segment);
651 * @brief Get the distance of #LocationRouteSegment
652 * @remarks The service provider should support route service.
655 * @param [in] segment - a #LocationRouteSegment
658 * @see location_route_segment_set_distance
660 gdouble location_route_segment_get_distance (const LocationRouteSegment *segment);
663 * @brief Get the duration #LocationRouteSegment
664 * @remarks The service provider should support route service.
667 * @param [in] segment - a #LocationRouteSegment
670 * @see location_route_segment_set_duration
672 glong location_route_segment_get_duration (const LocationRouteSegment *segment);
675 * @brief Get the list of property keys of #LocationRouteSegment
676 * @remarks The service provider should support route service.
679 * @param [in] segment - a #LocationRouteSegment
682 * @see location_route_segment_set_property_key
684 GList *location_route_segment_get_property_key (const LocationRouteSegment *segment);
687 * @brief Get the property value of #LocationRouteSegment
688 * @remarks The service provider should support route service.
691 * @param [in] segment - a #LocationRouteSegment
694 * @see location_route_segment_set_property
696 gpointer location_route_segment_get_property (const LocationRouteSegment *segment, gconstpointer key);
699 * @brief Get the list of route steps #LocationRouteStep in #LocationRouteSegment
700 * @remarks The service provider should support route service.
703 * @param [in] segment - a #LocationRouteSegment
706 * @see location_route_segment_set_route_step
708 GList *location_route_segment_get_route_step (const LocationRouteSegment *segment);
711 * @brief Create a new #LocationRouteStep
712 * @remarks The service provider should support route service.
716 * @return #LocationRouteStep
718 * @see location_route_step_free
720 LocationRouteStep *location_route_step_new (void);
723 * @brief Copy #LocationRouteStep
724 * @remarks The service provider should support route service.
727 * @param [in] step - a #LocationRouteStep
728 * @return #LocationRouteStep
730 * @see location_route_step_new
732 LocationRouteStep *location_route_step_copy (LocationRouteStep *step);
735 * @brief Free #LocationRouteStep
736 * @remarks The service provider should support route service.
739 * @param [in] step - a #LocationRouteStep
742 * @see location_route_step_new
744 void location_route_step_free (LocationRouteStep *step);
747 * @brief Get the start point #LocationPosition of #LocationRouteStep
748 * @remarks The service provider should support route service.
751 * @param [in] step - a #LocationRouteStep
752 * @return #LocationPosition
753 * @retval start point
754 * @see location_route_step_set_start_point
756 LocationPosition *location_route_step_get_start_point (const LocationRouteStep *step);
759 * @brief Get the end point #LocationPosition of #LocationRouteStep
760 * @remarks The service provider should support route service.
763 * @param [in] step - a #LocationRouteStep
764 * @return #LocationPosition
766 * @see location_route_step_set_end_point
768 LocationPosition *location_route_step_get_end_point (const LocationRouteStep *step);
771 * @brief Get the bounding box #LocationBoundary of #LocationRouteStep
772 * @remarks The service provider should support route service.
775 * @param [in] step - a #LocationRouteStep
776 * @return #LocationBoundary
777 * @retval bounding box
778 * @see location_route_step_set_bounding_box
780 LocationBoundary *location_route_step_get_bounding_box (const LocationRouteStep *step);
783 * @brief Get the distance of #LocationRouteStep
784 * @remarks The service provider should support route service.
787 * @param [in] step - a #LocationRouteStep
790 * @see location_route_step_set_distance
792 gdouble location_route_step_get_distance (const LocationRouteStep *step);
795 * @brief Get the duration of #LocationRouteStep
796 * @remarks The service provider should support route service.
799 * @param [in] step - a #LocationRouteStep
802 * @see location_route_step_set_duration
804 glong location_route_step_get_duration (const LocationRouteStep *step);
807 * @brief Get the transport mode of #LocationRouteStep
808 * @remarks The service provider should support route service.
811 * @param [in] step - a #LocationRouteStep
813 * @retval transport mode
814 * @see location_route_step_set_transport_mode
816 gchar *location_route_step_get_transport_mode (const LocationRouteStep *step);
819 * @brief Get the instruction of #LocationRouteStep
820 * @remarks The service provider should support route service.
823 * @param [in] step - a #LocationRouteStep
825 * @retval instruction
826 * @see location_route_step_set_instruction
828 gchar *location_route_step_get_instruction (const LocationRouteStep *step);
831 * @brief Get the list of geometry #LocationPosition of #LocationRouteStep
832 * @remarks The service provider should support route service.
835 * @param [in] step - a #LocationRouteStep
837 * @retval a list of LocationPosition
838 * @see location_route_step_set_geometry
840 GList *location_route_step_get_geometry (const LocationRouteStep *step);
843 * @brief Get the list of property key of #LocationRouteStep
844 * @remarks The service provider should support route service.
847 * @param [in] step - a #LocationRouteStep
849 * @retval a list of property key
850 * @see location_route_step_set_property_key
852 GList *location_route_step_get_property_key (const LocationRouteStep *step);
855 * @brief Get the property value of #LocationRouteStep
856 * @remarks The service provider should support route service.
859 * @param [in] step - a #LocationRouteStep
860 * @param [in] key - a gconstpointer
863 * @see location_route_step_set_property
865 gpointer location_route_step_get_property (const LocationRouteStep *step, gconstpointer key);