This provides APIs for Route Service.

Related Features

This API is related with the following features:

http://tizen.org/feature/network.internet

It is recommended to design feature related codes in your application for reliability.

You can check if a device supports the related features for this API by using System Information, thereby controlling the procedure of your application.

To ensure your application is only running on the device with specific features, please define the features in your manifest file using the manifest editor in the SDK.

More details on featuring your application can be found from Feature List.

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.3.2

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.3.2

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.3.2

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

Related Features

Functions

Typedefs

Typedef Documentation

Function Documentation