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]	index	The current index of path point
[in]	total	The total amount of path points
[in]	coordinates	The coordinates
[in]	user_data	The 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]	index	The current index of property
[in]	total	The total amount of properties
[in]	key	The key of property
[in]	value	The value of property
[in]	user_data	The 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]	index	The current index of segment
[in]	total	The total amount of segments
[in]	segment	The segment or leg of route
[in]	user_data	The 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]	origin	The original route handle
[out]	cloned	A cloned route handle

Returns:: 0 on success, otherwise a negative error value

Return values:

MAPS_ERROR_NONE	Successful
MAPS_ERROR_INVALID_PARAMETER	Invalid parameter
MAPS_ERROR_OUT_OF_MEMORY	Out of memory
MAPS_ERROR_NOT_SUPPORTED	Not supported

See also:: maps_route_destroy()

int maps_route_destroy ( maps_route_h route )

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] route The route handle

Returns:: 0 on success, otherwise a negative error value

Return values:

MAPS_ERROR_NONE	Successful
MAPS_ERROR_INVALID_PARAMETER	Invalid parameter
MAPS_ERROR_NOT_SUPPORTED	Not 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]	route	The route handle
[in]	callback	The callback function to invoke
[in]	user_data	The user data to be passed to the callback function

Returns:: 0 on success, otherwise a negative error value

Return values:

MAPS_ERROR_NONE	Successful
MAPS_ERROR_INVALID_PARAMETER	Invalid parameter
MAPS_ERROR_NOT_FOUND	Result not found
MAPS_ERROR_NOT_SUPPORTED	Not 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]	route	The route handle
[in]	callback	The callback function to invoke
[in]	user_data	The user data to be passed to the callback function

Returns:: 0 on success, otherwise a negative error value

Return values:

MAPS_ERROR_NONE	Successful
MAPS_ERROR_INVALID_PARAMETER	Invalid parameter
MAPS_ERROR_NOT_FOUND	Result not found
MAPS_ERROR_NOT_SUPPORTED	Not 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]	route	The route handle
[in]	callback	The callback function to invoke
[in]	user_data	The user data to be passed to the callback function

Returns:: 0 on success, otherwise a negative error value

Return values:

MAPS_ERROR_NONE	Successful
MAPS_ERROR_INVALID_PARAMETER	Invalid parameter
MAPS_ERROR_NOT_FOUND	Result not found
MAPS_ERROR_NOT_SUPPORTED	Not 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]	route	The route handle
[out]	bounding_box	The bounding box of route

Returns:: 0 on success, otherwise a negative error value

Return values:

MAPS_ERROR_NONE	Successful
MAPS_ERROR_INVALID_PARAMETER	Invalid parameter
MAPS_ERROR_NOT_SUPPORTED	Not 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]	route	The route handle
[out]	destination	The destination of route

Returns:: 0 on success, otherwise a negative error value

Return values:

MAPS_ERROR_NONE	Successful
MAPS_ERROR_INVALID_PARAMETER	Invalid parameter
MAPS_ERROR_NOT_SUPPORTED	Not 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]	route	The route handle
[out]	distance_unit	The distance units

Returns:: 0 on success, otherwise a negative error value

Return values:

MAPS_ERROR_NONE	Successful
MAPS_ERROR_INVALID_PARAMETER	Invalid parameter
MAPS_ERROR_NOT_SUPPORTED	Not 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]	route	The route handle
[out]	origin	The origin of route

Returns:: 0 on success, otherwise a negative error value

Return values:

MAPS_ERROR_NONE	Successful
MAPS_ERROR_INVALID_PARAMETER	Invalid parameter
MAPS_ERROR_NOT_SUPPORTED	Not 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]	route	The route handle
[out]	route_id	The ID of route

Returns:: 0 on success, otherwise a negative error value

Return values:

MAPS_ERROR_NONE	Successful
MAPS_ERROR_INVALID_PARAMETER	Invalid parameter
MAPS_ERROR_NOT_SUPPORTED	Not 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]	route	The route handle
[out]	total_distance	The 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_NONE	Successful
MAPS_ERROR_INVALID_PARAMETER	Invalid parameter
MAPS_ERROR_NOT_SUPPORTED	Not 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]	route	The route handle
[out]	total_duration	The duration

Returns:: 0 on success, otherwise a negative error value

Return values:

MAPS_ERROR_NONE	Successful
MAPS_ERROR_INVALID_PARAMETER	Invalid parameter
MAPS_ERROR_NOT_SUPPORTED	Not 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]	route	The route handle
[out]	transport_mode	The transport mode

Returns:: 0 on success, otherwise a negative error value

Return values:

MAPS_ERROR_NONE	Successful
MAPS_ERROR_INVALID_PARAMETER	Invalid parameter
MAPS_ERROR_NOT_SUPPORTED	Not supported

See also:: maps_route_transport_mode_e

Functions

Typedefs

Typedef Documentation

Function Documentation