Tizen Native API  3.0

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

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]errorThe result of request
[in]request_idThe ID of request
[in]indexThe current index of Route in result set, start from 0
[in]totalThe total number of result
[in]routeThe Route data
[in]user_dataThe 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]mapsThe Maps Service handle
[in]originThe starting point
[in]destinationThe destination
[in]preferenceThe Route preference handle
[in]callbackThe result callback
[in]user_dataThe user data to be passed to the callback function
[out]request_idThe request ID
Returns:
0 on success, otherwise a negative error value
Return values:
MAPS_ERROR_NONESuccessful
MAPS_ERROR_OUT_OF_MEMORYOut of memory
MAPS_ERROR_INVALID_PARAMETERInvalid parameter
MAPS_ERROR_PERMISSION_DENIEDPermission Denied
MAPS_ERROR_NOT_SUPPORTEDNot supported
MAPS_ERROR_CONNECTION_TIME_OUTTimeout error, no answer
MAPS_ERROR_INVALID_OPERATIONOperation is not valid
MAPS_ERROR_NOT_FOUNDResult not found
MAPS_ERROR_KEY_NOT_AVAILABLEInvalid key
MAPS_ERROR_UNKNOWNUnknown 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]mapsThe Maps Service handle
[in]waypoint_listThe list of way points to go through
[in]waypoint_numThe number of way points to go through
[in]preferenceThe Route preference handle
[in]callbackThe result callback
[in]user_dataThe user data to be passed to the callback function
[out]request_idThe request ID
Returns:
0 on success, otherwise a negative error value
Return values:
MAPS_ERROR_NONESuccessful
MAPS_ERROR_OUT_OF_MEMORYOut of memory
MAPS_ERROR_INVALID_PARAMETERInvalid parameter
MAPS_ERROR_NOT_SUPPORTEDService unavailable
MAPS_ERROR_PERMISSION_DENIEDPermission Denied
MAPS_ERROR_CONNECTION_TIME_OUTTimeout error, no answer
MAPS_ERROR_INVALID_OPERATIONOperation is not valid
MAPS_ERROR_NOT_FOUNDResult not found
MAPS_ERROR_KEY_NOT_AVAILABLEInvalid key
MAPS_ERROR_UNKNOWNUnknown 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()