Tizen Native API  5.5
Route

This provides APIs related to Route information, used in Route Search.

Functions

int maps_route_destroy (maps_route_h route)
 Destroys the route handle and releases all its resources.
int maps_route_clone (const maps_route_h origin, maps_route_h *cloned)
 Clones the route handle.
int maps_route_get_route_id (const maps_route_h route, char **route_id)
 Gets the route ID.
int maps_route_get_origin (const maps_route_h route, maps_coordinates_h *origin)
 Gets the route origin.
int maps_route_get_destination (const maps_route_h route, maps_coordinates_h *destination)
 Gets the route destination.
int maps_route_get_bounding_box (const maps_route_h route, maps_area_h *bounding_box)
 Gets the route bounding box.
int maps_route_get_transport_mode (const maps_route_h route, maps_route_transport_mode_e *transport_mode)
 Gets the route transport mode.
int maps_route_get_total_distance (const maps_route_h route, double *total_distance)
 Gets the route total distance.
int maps_route_get_total_duration (const maps_route_h route, long *total_duration)
 Gets the route total duration.
int maps_route_get_distance_unit (const maps_route_h route, maps_distance_unit_e *distance_unit)
 Gets the route distance units.
int maps_route_foreach_property (const maps_route_h route, maps_route_properties_cb callback, void *user_data)
 Retrieves all properties.
int maps_route_foreach_path (const maps_route_h route, maps_route_path_cb callback, void *user_data)
 Retrieves all coordinates of the path.
int maps_route_foreach_segment (const maps_route_h route, maps_route_segment_cb callback, void *user_data)
 Retrieves all segments of the route.

Typedefs

typedef void * maps_route_h
 The Route handle.
typedef bool(* maps_route_path_cb )(int index, int total, maps_coordinates_h coordinates, void *user_data)
 Called when requesting the path of the Route.
typedef bool(* maps_route_segment_cb )(int index, int total, maps_route_segment_h segment, void *user_data)
 Called when requesting the segments of the Route.
typedef bool(* maps_route_properties_cb )(int index, int total, char *key, void *value, void *user_data)
 Called when requesting the list of Route Properties.

Typedef Documentation

typedef void* maps_route_h

The Route handle.

The handle of Route instance.

Since :
2.4
Remarks:
To release the handle use maps_route_destroy().
To clone the handle use maps_route_clone().
See also:
maps_route_destroy()
maps_route_clone()
typedef bool(* maps_route_path_cb)(int index, int total, maps_coordinates_h coordinates, void *user_data)

Called when requesting the path of the Route.

This callback is invoked while iterating through the list of coordinates, composing the Route.

Since :
2.4
Remarks:
coordinates must be released using maps_coordinates_destroy().
To use coordinates outside this function, clone it with maps_coordinates_clone().
Parameters:
[in]indexThe current index of path point
[in]totalThe total amount of path points
[in]coordinatesThe coordinates
[in]user_dataThe user data passed from maps_route_foreach_path()
Returns:
true to continue with the next iteration of the loop,
false to break out of the loop
Precondition:
maps_route_foreach_path() will invoke this callback.
See also:
maps_route_foreach_path()
maps_coordinates_h
typedef bool(* maps_route_properties_cb)(int index, int total, char *key, void *value, void *user_data)

Called when requesting the list of Route Properties.

This callback is invoked while iterating through the list of Route Properties.

Since :
2.4
Remarks:
key and value must be released using free() and corresponding release method for property value correspondingly.
To use key and value outside this function, you should clone it.
Parameters:
[in]indexThe current index of property
[in]totalThe total amount of properties
[in]keyThe key of property
[in]valueThe value of property
[in]user_dataThe user data passed from maps_route_foreach_property()
Returns:
true to continue with the next iteration of the loop,
false to break out of the loop
Precondition:
maps_route_foreach_property() will invoke this callback.
See also:
maps_route_foreach_property()
typedef bool(* maps_route_segment_cb)(int index, int total, maps_route_segment_h segment, void *user_data)

Called when requesting the segments of the Route.

This callback is invoked while iterating through the list of segments, composing the Route.

Since :
2.4
Remarks:
segment is valid only in this function and must be released using maps_route_segment_destroy().
To use segment outside this function, clone it with maps_route_segment_clone().
Parameters:
[in]indexThe current index of segment
[in]totalThe total amount of segments
[in]segmentThe segment or leg of route
[in]user_dataThe user data passed from maps_route_foreach_segment()
Returns:
true to continue with the next iteration of the loop,
false to break out of the loop
Precondition:
maps_route_foreach_segment() will invoke this callback.
See also:
maps_route_foreach_segment()
maps_route_segment_h

Function Documentation

int maps_route_clone ( const maps_route_h  origin,
maps_route_h cloned 
)

Clones the route handle.

This function clones the route handle origin and all its resources.

Since :
2.4
Remarks:
cloned must be released using maps_route_destroy().
Parameters:
[in]originThe original route handle
[out]clonedA cloned route handle
Returns:
0 on success, otherwise a negative error value
Return values:
MAPS_ERROR_NONESuccessful
MAPS_ERROR_INVALID_PARAMETERInvalid parameter
MAPS_ERROR_OUT_OF_MEMORYOut of memory
MAPS_ERROR_NOT_SUPPORTEDNot supported
See also:
maps_route_destroy()

Destroys the route handle and releases all its resources.

This function destroys the route handle and releases all its resources.

Since :
2.4
Parameters:
[in]routeThe route handle
Returns:
0 on success, otherwise a negative error value
Return values:
MAPS_ERROR_NONESuccessful
MAPS_ERROR_INVALID_PARAMETERInvalid parameter
MAPS_ERROR_NOT_SUPPORTEDNot supported
See also:
maps_route_clone()
int maps_route_foreach_path ( const maps_route_h  route,
maps_route_path_cb  callback,
void *  user_data 
)

Retrieves all coordinates of the path.

This function retrieves all coordinates of the route path.

Since :
2.4
Remarks:
The coordinates will be delivered via maps_route_path_cb().
Parameters:
[in]routeThe route handle
[in]callbackThe callback function to invoke
[in]user_dataThe user data to be passed to the callback function
Returns:
0 on success, otherwise a negative error value
Return values:
MAPS_ERROR_NONESuccessful
MAPS_ERROR_INVALID_PARAMETERInvalid parameter
MAPS_ERROR_NOT_FOUNDResult not found
MAPS_ERROR_NOT_SUPPORTEDNot supported
Postcondition:
This function invokes maps_route_path_cb() repeatedly to retrieve each coordinate point.
See also:
maps_route_path_cb()
int maps_route_foreach_property ( const maps_route_h  route,
maps_route_properties_cb  callback,
void *  user_data 
)

Retrieves all properties.

This function retrieves all route properties.

Since :
2.4
Remarks:
The properties will be delivered via maps_route_properties_cb().
Parameters:
[in]routeThe route handle
[in]callbackThe callback function to invoke
[in]user_dataThe user data to be passed to the callback function
Returns:
0 on success, otherwise a negative error value
Return values:
MAPS_ERROR_NONESuccessful
MAPS_ERROR_INVALID_PARAMETERInvalid parameter
MAPS_ERROR_NOT_FOUNDResult not found
MAPS_ERROR_NOT_SUPPORTEDNot supported
Postcondition:
This function invokes maps_route_properties_cb() repeatedly to retrieve each property.
See also:
maps_route_properties_cb()
int maps_route_foreach_segment ( const maps_route_h  route,
maps_route_segment_cb  callback,
void *  user_data 
)

Retrieves all segments of the route.

This function retrieves all segments of the route.

Since :
2.4
Remarks:
The segments will be delivered via maps_route_path_cb().
Parameters:
[in]routeThe route handle
[in]callbackThe callback function to invoke
[in]user_dataThe user data to be passed to the callback function
Returns:
0 on success, otherwise a negative error value
Return values:
MAPS_ERROR_NONESuccessful
MAPS_ERROR_INVALID_PARAMETERInvalid parameter
MAPS_ERROR_NOT_FOUNDResult not found
MAPS_ERROR_NOT_SUPPORTEDNot supported
Postcondition:
This function invokes maps_route_segment_cb() repeatedly to retrieve each segment.
See also:
maps_route_segment_cb()
int maps_route_get_bounding_box ( const maps_route_h  route,
maps_area_h bounding_box 
)

Gets the route bounding box.

This function gets the route bounding box.

Since :
2.4
Remarks:
bounding_box must be released using maps_area_destroy().
Parameters:
[in]routeThe route handle
[out]bounding_boxThe bounding box of route
Returns:
0 on success, otherwise a negative error value
Return values:
MAPS_ERROR_NONESuccessful
MAPS_ERROR_INVALID_PARAMETERInvalid parameter
MAPS_ERROR_NOT_SUPPORTEDNot supported
See also:
maps_area_h
int maps_route_get_destination ( const maps_route_h  route,
maps_coordinates_h destination 
)

Gets the route destination.

This function gets the route destination.

Since :
2.4
Remarks:
destination must be released using maps_coordinates_destroy().
Parameters:
[in]routeThe route handle
[out]destinationThe destination of route
Returns:
0 on success, otherwise a negative error value
Return values:
MAPS_ERROR_NONESuccessful
MAPS_ERROR_INVALID_PARAMETERInvalid parameter
MAPS_ERROR_NOT_SUPPORTEDNot supported
See also:
maps_route_get_origin()
maps_coordinates_h
int maps_route_get_distance_unit ( const maps_route_h  route,
maps_distance_unit_e distance_unit 
)

Gets the route distance units.

This function gets the route distance units.

Since :
2.4
Parameters:
[in]routeThe route handle
[out]distance_unitThe distance units
Returns:
0 on success, otherwise a negative error value
Return values:
MAPS_ERROR_NONESuccessful
MAPS_ERROR_INVALID_PARAMETERInvalid parameter
MAPS_ERROR_NOT_SUPPORTEDNot supported
See also:
maps_distance_unit_e
int maps_route_get_origin ( const maps_route_h  route,
maps_coordinates_h origin 
)

Gets the route origin.

This function gets the route origin.

Since :
2.4
Remarks:
origin must be released using maps_coordinates_destroy().
Parameters:
[in]routeThe route handle
[out]originThe origin of route
Returns:
0 on success, otherwise a negative error value
Return values:
MAPS_ERROR_NONESuccessful
MAPS_ERROR_INVALID_PARAMETERInvalid parameter
MAPS_ERROR_NOT_SUPPORTEDNot supported
See also:
maps_route_get_destination()
maps_coordinates_h
int maps_route_get_route_id ( const maps_route_h  route,
char **  route_id 
)

Gets the route ID.

This function gets the route ID.

Since :
2.4
Remarks:
id must be released using free().
Parameters:
[in]routeThe route handle
[out]route_idThe ID of route
Returns:
0 on success, otherwise a negative error value
Return values:
MAPS_ERROR_NONESuccessful
MAPS_ERROR_INVALID_PARAMETERInvalid parameter
MAPS_ERROR_NOT_SUPPORTEDNot supported
int maps_route_get_total_distance ( const maps_route_h  route,
double *  total_distance 
)

Gets the route total distance.

This function gets the route total distance.

Since :
2.4
Parameters:
[in]routeThe route handle
[out]total_distanceThe distance of route. You can get the distance unit by route_get_distance_unit()
Returns:
0 on success, otherwise a negative error value
Return values:
MAPS_ERROR_NONESuccessful
MAPS_ERROR_INVALID_PARAMETERInvalid parameter
MAPS_ERROR_NOT_SUPPORTEDNot supported
See also:
maps_route_get_total_duration()
int maps_route_get_total_duration ( const maps_route_h  route,
long *  total_duration 
)

Gets the route total duration.

This function gets the route total duration.

Since :
2.4
Parameters:
[in]routeThe route handle
[out]total_durationThe duration
Returns:
0 on success, otherwise a negative error value
Return values:
MAPS_ERROR_NONESuccessful
MAPS_ERROR_INVALID_PARAMETERInvalid parameter
MAPS_ERROR_NOT_SUPPORTEDNot supported
See also:
maps_route_get_total_distance()
int maps_route_get_transport_mode ( const maps_route_h  route,
maps_route_transport_mode_e transport_mode 
)

Gets the route transport mode.

This function gets the route transport mode.

Since :
2.4
Parameters:
[in]routeThe route handle
[out]transport_modeThe transport mode
Returns:
0 on success, otherwise a negative error value
Return values:
MAPS_ERROR_NONESuccessful
MAPS_ERROR_INVALID_PARAMETERInvalid parameter
MAPS_ERROR_NOT_SUPPORTEDNot supported
See also:
maps_route_transport_mode_e