Segment

---

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

Functions
int	maps_route_segment_destroy (maps_route_segment_h segment)
	Destroys the route segment handle and releases all its resources.
int	maps_route_segment_clone (const maps_route_segment_h origin, maps_route_segment_h *cloned)
	Clones the route segment handle.
int	maps_route_segment_get_origin (const maps_route_segment_h segment, maps_coordinates_h *origin)
	Gets the route segment origin.
int	maps_route_segment_get_destination (const maps_route_segment_h segment, maps_coordinates_h *destination)
	Gets the route segment destination.
int	maps_route_segment_get_bounding_box (const maps_route_segment_h segment, maps_area_h *bounding_box)
	Gets the route segment bounding box.
int	maps_route_segment_get_distance (const maps_route_segment_h segment, double *distance)
	Gets the route segment distance.
int	maps_route_segment_get_duration (const maps_route_segment_h segment, long *duration)
	Gets the route segment duration.
int	maps_route_segment_foreach_path (const maps_route_segment_h segment, maps_route_segment_path_cb callback, void *user_data)
	Retrieves all coordinates of the path.
int	maps_route_segment_foreach_maneuver (const maps_route_segment_h segment, maps_route_segment_maneuver_cb callback, void *user_data)
	Retrieves all Maneuvers of the path.
Typedefs
typedef void *	maps_route_segment_h
	The Route Segment handle.
typedef bool(*	maps_route_segment_path_cb )(int index, int total, maps_coordinates_h coordinates, void *user_data)
	Called when requesting the path of the Route Segment.
typedef bool(*	maps_route_segment_maneuver_cb )(int index, int total, maps_route_maneuver_h maneuver, void *user_data)
	Called when requesting the Maneuvers of the Route Segment.

---

Typedef Documentation

typedef void* maps_route_segment_h

The Route Segment handle.

The handle of Route Segment instance.

Since :

2.4

Remarks:

To release the handle use maps_route_segment_destroy().
To clone the handle use maps_route_segment_clone().

See also:

maps_route_segment_destroy()

maps_route_segment_clone()

typedef bool(* maps_route_segment_maneuver_cb)(int index, int total, maps_route_maneuver_h maneuver, void *user_data)

Called when requesting the Maneuvers of the Route Segment.

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

Since :

2.4

Remarks:

Maneuver is valid only in this function and must be released using maps_route_maneuver_destroy().
To use Maneuver outside this function, clone it with maps_route_maneuver_clone().

Parameters:

[in]	index	The current index of Maneuvers list
[in]	total	The total amount of Maneuvers
[in]	maneuver	The Maneuver of route
[in]	user_data	The user data passed from maps_route_segment_foreach_maneuver()

Returns:

true to continue with the next iteration of the loop,
false to break out of the loop

Precondition:

maps_route_segment_foreach_maneuver() will invoke this callback.

See also:

maps_route_segment_foreach_maneuver()

maps_route_maneuver_h

typedef bool(* maps_route_segment_path_cb)(int index, int total, maps_coordinates_h coordinates, void *user_data)

Called when requesting the path of the Route Segment.

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

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 coordinates list
[in]	total	The total amount of coordinates
[in]	coordinates	The current coordinates
[in]	user_data	The user data passed from maps_route_segment_foreach_path()

Returns:

true to continue with the next iteration of the loop,
false to break out of the loop

Precondition:

maps_route_segment_foreach_path() will invoke this callback.

See also:

maps_route_segment_foreach_path()

maps_coordinates_h

---

Function Documentation

int maps_route_segment_clone	(	const maps_route_segment_h	origin,
		maps_route_segment_h *	cloned
	)

Clones the route segment handle.

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

Since :

2.4

Remarks:

cloned must be released using maps_route_segment_destroy().

Parameters:

[in]	origin	The original segment handle
[out]	cloned	A cloned segment handle

Returns:

0 on success, otherwise a negative error value

Return values:

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

See also:

maps_route_segment_destroy()

int maps_route_segment_destroy

(

maps_route_segment_h

segment

)

Destroys the route segment handle and releases all its resources.

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

Since :

2.4

Parameters:

[in]

segment

The segment handle to destroy

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_segment_clone()

int maps_route_segment_foreach_maneuver	(	const maps_route_segment_h	segment,
		maps_route_segment_maneuver_cb	callback,
		void *	user_data
	)

Retrieves all Maneuvers of the path.

This function retrieves all Maneuvers of the route segment path.

Since :

2.4

Remarks:

The coordinates will be delivered via maps_route_segment_maneuver_cb().

Parameters:

[in]	segment	The segment 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_maneuver_cb() repeatedly to retrieve each coordinate point.

See also:

maps_route_segment_maneuver_cb()

int maps_route_segment_foreach_path	(	const maps_route_segment_h	segment,
		maps_route_segment_path_cb	callback,
		void *	user_data
	)

Retrieves all coordinates of the path.

This function retrieves all coordinates of the route segment path.

Since :

2.4

Remarks:

The coordinates will be delivered via maps_route_segment_path_cb().

Parameters:

[in]	segment	The segment 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_path_cb() repeatedly to retrieve each coordinate point.

See also:

maps_route_segment_path_cb()

int maps_route_segment_get_bounding_box	(	const maps_route_segment_h	segment,
		maps_area_h *	bounding_box
	)

Gets the route segment bounding box.

This function gets the route segment bounding box.

Since :

2.4

Remarks:

bounding_box must be released using maps_area_destroy().

Parameters:

[in]	segment	The segment handle
[out]	bounding_box	The bounding box of segment

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_segment_get_destination	(	const maps_route_segment_h	segment,
		maps_coordinates_h *	destination
	)

Gets the route segment destination.

This function gets the route segment destination.

Since :

2.4

Remarks:

destination must be released using maps_coordinates_destroy().

Parameters:

[in]	segment	The segment handle
[out]	destination	The destination of segment

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_coordinates_h

int maps_route_segment_get_distance	(	const maps_route_segment_h	segment,
		double *	distance
	)

Gets the route segment distance.

This function gets the route segment distance.

Since :

2.4

Parameters:

[in]	segment	The segment handle
[out]	distance	The distance of segment

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_segment_get_duration	(	const maps_route_segment_h	segment,
		long *	duration
	)

Gets the route segment duration.

This function gets the route segment duration.

Since :

2.4

Parameters:

[in]	segment	The segment handle
[out]	duration	The distance of segment

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_segment_get_origin	(	const maps_route_segment_h	segment,
		maps_coordinates_h *	origin
	)

Gets the route segment origin.

This function gets the route segment origin.

Since :

2.4

Remarks:

origin must be released using maps_coordinates_destroy().

Parameters:

[in]	segment	The segment handle
[out]	origin	The origin of segment

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_coordinates_h