Routes

---

This provides APIs for Route Service.

The Maps Route API provides functions to calculate a route that defines a path between a origin and a destination and may, optionally, pass through specific intermediate locations.

Functions
int	maps_service_search_route (const maps_service_h maps, const maps_coordinates_h origin, const maps_coordinates_h destination, maps_preference_h preference, maps_service_search_route_cb callback, void *user_data, int *request_id)
	Queries the Route from origin coordinates to destination. The request is asynchronous.
int	maps_service_search_route_waypoints (const maps_service_h maps, const maps_coordinates_h *waypoint_list, int waypoint_num, maps_preference_h preference, maps_service_search_route_cb callback, void *user_data, int *request_id)
	Queries the Route, passing through a specified way points. The request is asynchronous.
Typedefs
typedef bool(*	maps_service_search_route_cb )(maps_error_e error, int request_id, int index, int total, maps_route_h route, void *user_data)
	Called when the requested routes are found.

---

Typedef Documentation

typedef bool(* maps_service_search_route_cb)(maps_error_e error, int request_id, int index, int total, maps_route_h route, void *user_data)

Called when the requested routes are found.

The Maps Service invokes this callback while iterating through the set of obtained Routes.
If search is failed, the value of total is 0 and route is NULL.

Since :

2.4

Remarks:

The parameter route must be released using maps_route_destroy().
This error code will be reported.
MAPS_ERROR_NONE
MAPS_ERROR_OUT_OF_MEMORY
MAPS_ERROR_INVALID_PARAMETER
MAPS_ERROR_NOT_FOUND.

Parameters:

[in]	error	The result of request
[in]	request_id	The ID of request
[in]	index	The current index of Route in result set, start from 0
[in]	total	The total number of result
[in]	route	The Route data
[in]	user_data	The user data passed from maps_service_search_route() or maps_service_search_route_waypoints()

Returns:

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

Precondition:

maps_service_search_route() or maps_service_search_route_waypoints() will invoke this callback.

See also:

maps_service_search_route()

maps_service_search_route_waypoints()

maps_service_cancel_request()

---

Function Documentation

int maps_service_search_route	(	const maps_service_h	maps,
		const maps_coordinates_h	origin,
		const maps_coordinates_h	destination,
		maps_preference_h	preference,
		maps_service_search_route_cb	callback,
		void *	user_data,
		int *	request_id
	)

Queries the Route from origin coordinates to destination.
The request is asynchronous.

This function gets the Route information for a specified origin and destination coordinates.

Since :

2.4

Privilege Level:

public

Privilege:

http://tizen.org/privilege/mapservice
http://tizen.org/privilege/internet
http://tizen.org/privilege/network.get

Remarks:

To cancel the search request, use maps_service_cancel_request().
To check if Maps Provider is capable of searching routes, use maps_service_provider_is_service_supported() with MAPS_SERVICE_SEARCH_ROUTE passed as service parameter.
Check available data features in the search result using maps_service_provider_is_data_supported() with values, listed in maps_service_data_e passed as data parameter.

Parameters:

[in]	maps	The Maps Service handle
[in]	origin	The starting point
[in]	destination	The destination
[in]	preference	The Route preference handle
[in]	callback	The result callback
[in]	user_data	The user data to be passed to the callback function
[out]	request_id	The request ID

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_PERMISSION_DENIED	Permission Denied
MAPS_ERROR_NOT_SUPPORTED	Not supported
MAPS_ERROR_CONNECTION_TIME_OUT	Timeout error, no answer
MAPS_ERROR_INVALID_OPERATION	Operation is not valid
MAPS_ERROR_NOT_FOUND	Result not found
MAPS_ERROR_KEY_NOT_AVAILABLE	Invalid key
MAPS_ERROR_UNKNOWN	Unknown error

Precondition:

Call maps_service_create() to create Maps Service and get its handle.

Postcondition:

It invokes maps_service_search_route_cb() to deliver obtained Route information.

See also:

maps_service_search_route_waypoints()

maps_service_cancel_request()

maps_service_search_route_cb()

maps_service_provider_is_service_supported()

maps_service_provider_is_data_supported()

int maps_service_search_route_waypoints	(	const maps_service_h	maps,
		const maps_coordinates_h *	waypoint_list,
		int	waypoint_num,
		maps_preference_h	preference,
		maps_service_search_route_cb	callback,
		void *	user_data,
		int *	request_id
	)

Queries the Route, passing through a specified way points.
The request is asynchronous.

This function gets the Route information for the Route, passing through a specified set of way points.

Since :

2.4

Privilege Level:

public

Privilege:

http://tizen.org/privilege/mapservice
http://tizen.org/privilege/internet
http://tizen.org/privilege/network.get

Remarks:

To cancel the search request, use maps_service_cancel_request().
To check if Maps Provider is capable of searching the route passing through the specified way points, use maps_service_provider_is_service_supported() with MAPS_SERVICE_SEARCH_ROUTE_WAYPOINTS passed as service parameter.
Check available data features in the search result using maps_service_provider_is_data_supported() with values, listed in maps_service_data_e passed as data parameter.

Parameters:

[in]	maps	The Maps Service handle
[in]	waypoint_list	The list of way points to go through
[in]	waypoint_num	The number of way points to go through
[in]	preference	The Route preference handle
[in]	callback	The result callback
[in]	user_data	The user data to be passed to the callback function
[out]	request_id	The request ID

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	Service unavailable
MAPS_ERROR_PERMISSION_DENIED	Permission Denied
MAPS_ERROR_CONNECTION_TIME_OUT	Timeout error, no answer
MAPS_ERROR_INVALID_OPERATION	Operation is not valid
MAPS_ERROR_NOT_FOUND	Result not found
MAPS_ERROR_KEY_NOT_AVAILABLE	Invalid key
MAPS_ERROR_UNKNOWN	Unknown error

Precondition:

Call maps_service_create() to create Maps Service and get its handle.

Postcondition:

It invokes maps_service_search_route_cb() to deliver obtained Route information.

See also:

maps_service_search_route()

maps_service_cancel_request()

maps_service_search_route_cb()

maps_service_provider_is_service_supported()

maps_service_provider_is_data_supported()