Service and Providers

---

This provides a list of Maps API errors.

This provides APIs related Search and Preference.

Functions
int	maps_service_foreach_provider (maps_service_provider_info_cb callback, void *user_data)
	Gets available Maps Providers.
int	maps_service_request_user_consent (const char *maps_provider, maps_service_request_user_consent_cb callback, void *user_data)
	Gets the user's consent to use maps data.
int	maps_service_create (const char *maps_provider, maps_service_h *maps)
	Creates a new Maps Service and assigns it with a handle.
int	maps_service_destroy (maps_service_h maps)
	Destroys the Maps Service handle and releases all its resources.
int	maps_service_set_provider_key (maps_service_h maps, const char *provider_key)
	Sets the Maps Key to be used in the requests of Maps Service.
int	maps_service_get_provider_key (const maps_service_h maps, char **provider_key)
	Gets the Maps Key which is to be used in the Maps Service requests.
int	maps_service_set_preference (maps_service_h maps, maps_preference_h preference)
	Sets the Maps Preference.
int	maps_service_get_preference (maps_service_h maps, maps_preference_h *preference)
	Gets the Maps Preference.
int	maps_service_provider_is_service_supported (const maps_service_h maps, maps_service_e service, bool *supported)
	Checks if the Maps Service supports a request.
int	maps_service_provider_is_data_supported (const maps_service_h maps, maps_service_data_e data, bool *supported)
	Checks if the Maps Service supports a data feature.
int	maps_service_cancel_request (const maps_service_h maps, int request_id)
	Cancels the service request.
Typedefs
typedef enum _maps_error_e	maps_error_e
	Enumeration for error codes for Maps Service and Plug-ins.
typedef enum _maps_service_e	maps_service_e
	Enumeration for maps requests available in the Maps Service.
typedef enum _maps_service_data_e	maps_service_data_e
	Enumeration for maps features available in the Maps Service.
typedef bool(*	maps_service_provider_info_cb )(char *maps_provider, void *user_data)
	Called when requesting available Maps Providers.
typedef void(*	maps_service_request_user_consent_cb )(bool consented, const char *maps_provider, void *user_data)
	Called with the information about user's consent.

---

Typedef Documentation

typedef enum _maps_error_e maps_error_e

Enumeration for error codes for Maps Service and Plug-ins.

Since :

2.4

typedef enum _maps_service_data_e maps_service_data_e

Enumeration for maps features available in the Maps Service.

Since :

2.4

typedef enum _maps_service_e maps_service_e

Enumeration for maps requests available in the Maps Service.

Since :

2.4

typedef bool(* maps_service_provider_info_cb)(char *maps_provider, void *user_data)

Called when requesting available Maps Providers.

A Maps Service invokes this callback iteratively as long as available Maps Providers exist.

Since :

2.4

Remarks:

The string maps_provider must be released using free().

Parameters:

[in]	maps_provider	The info of Maps Provider
[in]	user_data	The user data passed from maps_service_foreach_provider()

Returns:

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

Precondition:

maps_service_foreach_provider() will invoke this callback.

See also:

maps_service_foreach_provider()

maps_service_create()

typedef void(* maps_service_request_user_consent_cb)(bool consented, const char *maps_provider, void *user_data)

Called with the information about user's consent.

The Maps Service invokes this callback when the information about user's consent is obtained.

Since :

3.0

Parameters:

[in]	consented	The value of User Consent
[in]	maps_provider	The name of Maps Provider
[in]	user_data	The user data passed from maps_service_request_user_consent()

Precondition:

maps_service_request_user_consent() will invoke this callback.

See also:

maps_service_request_user_consent()

maps_service_create()

---

Enumeration Type Documentation

enum _maps_error_e

Enumeration for error codes for Maps Service and Plug-ins.

Since :

2.4

Enumerator:

MAPS_ERROR_NONE	Successful
MAPS_ERROR_PERMISSION_DENIED	Permission Denied
MAPS_ERROR_OUT_OF_MEMORY	Out of memory
MAPS_ERROR_INVALID_PARAMETER	Invalid parameter
MAPS_ERROR_NOT_SUPPORTED	Not supported
MAPS_ERROR_CONNECTION_TIME_OUT	Timeout error, no answer
MAPS_ERROR_NETWORK_UNREACHABLE	Network unavailable
MAPS_ERROR_INVALID_OPERATION	Operation is not valid
MAPS_ERROR_KEY_NOT_AVAILABLE	Invalid key
MAPS_ERROR_RESOURCE_BUSY	Maps Service busy
MAPS_ERROR_CANCELED	Maps Service request aborted
MAPS_ERROR_UNKNOWN	Unknown error
MAPS_ERROR_USER_NOT_CONSENTED	Not Consented (Since 3.0)
MAPS_ERROR_SERVICE_NOT_AVAILABLE	Service unavailable
MAPS_ERROR_NOT_FOUND	Result not found

enum _maps_service_data_e

Enumeration for maps features available in the Maps Service.

Since :

2.4

Enumerator:

MAPS_PLACE_ADDRESS	Indicates the availability of address value in the Place data
MAPS_PLACE_RATING	Indicates the availability of rating value in the Place data
MAPS_PLACE_CATEGORIES	Indicates the availability of place category list in the Place data
MAPS_PLACE_ATTRIBUTES	Indicates the availability of place attribute list in the Place data
MAPS_PLACE_CONTACTS	Indicates the availability of place contact list in the Place data
MAPS_PLACE_EDITORIALS	Indicates the availability of place editorial list in the Place data
MAPS_PLACE_REVIEWS	Indicates the availability of place review list in the Place data
MAPS_PLACE_IMAGE	Indicates the availability of place image in Place the data
MAPS_PLACE_SUPPLIER	Indicates the availability of place supplier link value in the Place data
MAPS_PLACE_RELATED	Indicates the availability of related place link in the Place data
MAPS_ROUTE_PATH	Indicates that the Route Data Structure is defined as a Path (a list of geographical coordinates)
MAPS_ROUTE_SEGMENTS_PATH	Indicates that the Route Data Structure is defined as a list of Segments while each segment is defined as a Path
MAPS_ROUTE_SEGMENTS_MANEUVERS	Indicates that the Route Data Structure is defined as a list of Segments while each segment is defined as a list of Maneuvers
MAPS_VIEW_TRAFFIC	Indicates the availability of traffic information on the Map (Since 3.0)
MAPS_VIEW_PUBLIC_TRANSIT	Indicates the availability of public transit information on the Map (Since 3.0)
MAPS_VIEW_BUILDING	Indicates the availability of 3D building drawable on the Map (Since 3.0)
MAPS_VIEW_SCALEBAR	Indicates the availability of scale bar on the Map (Since 3.0)

enum _maps_service_e

Enumeration for maps requests available in the Maps Service.

Since :

2.4

Enumerator:

MAPS_SERVICE_GEOCODE	Indicates that maps_service_geocode() service is allowed
MAPS_SERVICE_GEOCODE_INSIDE_AREA	Indicates that maps_service_geocode_inside_area() service is allowed
MAPS_SERVICE_GEOCODE_BY_STRUCTURED_ADDRESS	Indicates that maps_service_geocode_by_structured_address() service is allowed
MAPS_SERVICE_REVERSE_GEOCODE	Indicates that maps_service_reverse_geocode() service is allowed
MAPS_SERVICE_SEARCH_PLACE	Indicates that maps_service_search_place() service is allowed
MAPS_SERVICE_SEARCH_PLACE_BY_AREA	Indicates that maps_service_search_place_by_area() service is allowed
MAPS_SERVICE_SEARCH_PLACE_BY_ADDRESS	Indicates that maps_service_search_place_by_address() service is allowed
MAPS_SERVICE_SEARCH_ROUTE	Indicates that maps_service_search_route() service is allowed
MAPS_SERVICE_SEARCH_ROUTE_WAYPOINTS	Indicates that maps_service_search_route_waypoints() service is allowed
MAPS_SERVICE_CANCEL_REQUEST	Indicates that maps_service_cancel_request() service is allowed
MAPS_SERVICE_MULTI_REVERSE_GEOCODE	Indicates that maps_service_multi_reverse_geocode() service is allowed (Since 3.0)
MAPS_SERVICE_SEARCH_PLACE_LIST	Indicates that maps_service_search_place_list() service is allowed (Since 3.0)
MAPS_SERVICE_SEARCH_GET_PLACE_DETAILS	Indicates that maps_service_search_get_place_details() service is allowed (Since 3.0)
MAPS_SERVICE_VIEW	Indicates that maps view service is allowed (Since 3.0)
MAPS_SERVICE_VIEW_SNAPSHOT	Indicates that maps view snapshot service is allowed (Since 3.0)

---

Function Documentation

int maps_service_cancel_request	(	const maps_service_h	maps,
		int	request_id
	)

Cancels the service request.

This function cancels the service request initiated by geocoding and searching places and routes.

Since :

2.4

Privilege Level:

public

Privilege:

http://tizen.org/privilege/mapservice

Parameters:

[in]	maps	The Maps Service handle
[in]	request_id	The ID of request

Returns:

0 on success, otherwise a negative error value

Return values:

MAPS_ERROR_NONE	Successful
MAPS_ERROR_INVALID_PARAMETER	Invalid parameter
MAPS_ERROR_NETWORK_UNREACHABLE	Network connection failed
MAPS_ERROR_SERVICE_NOT_AVAILABLE	Service not available
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:

request_id is obtained from one of followings:

• maps_service_geocode()
• maps_service_geocode_inside_area()
• maps_service_geocode_by_structured_address()
• maps_service_reverse_geocode()
• maps_service_search_place()
• maps_service_search_place_by_area()
• maps_service_search_place_by_address()
• maps_service_search_route()
• maps_service_search_route_waypoints()

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

See also:

maps_service_geocode()

maps_service_geocode_inside_area()

maps_service_geocode_by_structured_address()

maps_service_reverse_geocode()

maps_service_search_place()

maps_service_search_place_by_area()

maps_service_search_place_by_address()

maps_service_search_route()

maps_service_search_route_waypoints()

int maps_service_create	(	const char *	maps_provider,
		maps_service_h *	maps
	)

Creates a new Maps Service and assigns it with a handle.

While Maps Service is being created, a Maps Provider is initialized and linked with Maps Service handle. A Maps Service handle is used to query Maps Provider performing services, such as Geocoding, Searching Places, and Routing.

Since :

2.4

Privilege Level:

public

Privilege:

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

Remarks:

maps service handle must be released using maps_service_destroy().
Use maps_service_foreach_provider() to choose one of available Providers.
Use maps_service_set_provider_key() to set provider's key.
Use maps_service_set_preference() to set various options of Maps Provider.
Use maps_service_provider_is_service_supported() and maps_service_provider_is_data_supported() to check the Maps Provider's capabilities.

Parameters:

[in]	maps_provider	The name of Maps Provider
[out]	maps	A handle of the new Maps Service on success

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_SERVICE_NOT_AVAILABLE	Service not available
MAPS_ERROR_NOT_SUPPORTED	Not supported
MAPS_ERROR_PERMISSION_DENIED	Permission Denied
MAPS_ERROR_USER_NOT_CONSENTED	The user did not consent

Precondition:

Call maps_service_foreach_provider() to get a available Maps Providers.

See also:

maps_service_foreach_provider()

maps_service_destroy()

maps_service_geocode()

maps_service_geocode_inside_area()

maps_service_reverse_geocode()

maps_service_search_place()

maps_service_search_place_by_area()

maps_service_search_place_by_address()

maps_service_search_route()

maps_service_search_route_waypoints()

maps_service_set_provider_key()

maps_service_set_preference()

maps_service_provider_is_service_supported()

maps_service_provider_is_data_supported()

int maps_service_destroy

(

maps_service_h

maps

)

Destroys the Maps Service handle and releases all its resources.

This function releases all used resources of the Maps Service and Maps Provider.

Since :

2.4

Privilege Level:

public

Privilege:

http://tizen.org/privilege/mapservice

Parameters:

[in]

maps

The Maps Service 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
MAPS_ERROR_PERMISSION_DENIED	Permission Denied

Precondition:

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

See also:

maps_service_create()

int maps_service_foreach_provider	(	maps_service_provider_info_cb	callback,
		void *	user_data
	)

Gets available Maps Providers.

This function delivers available Maps Providers via maps_service_provider_info_cb() callback.

Since :

2.4

Parameters:

[in]	callback	The callback function to receive available Maps Providers information
[out]	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_service_provider_info_cb() to deliver Maps Provider information.

See also:

maps_service_provider_info_cb()

maps_service_create()

int maps_service_get_preference	(	maps_service_h	maps,
		maps_preference_h *	preference
	)

Gets the Maps Preference.

This function gets the Maps Preferences which are used in each Maps Service request to Maps Provider.
Preferences can be set with maps_service_set_preference().

Since :

2.4

Remarks:

preference must be released using maps_preference_destroy().
maps_service_get_preference is always synchronous function.

Parameters:

[in]	maps	The handle of Maps Service
[out]	preference	The handle of Maps Preference

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

Precondition:

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

See also:

maps_service_set_preference()

maps_service_create()

int maps_service_get_provider_key	(	const maps_service_h	maps,
		char **	provider_key
	)

Gets the Maps Key which is to be used in the Maps Service requests.

This function gets the Maps Key which is to be used in each Maps Service request to Maps Provider.
Maps Key can be set with maps_service_set_provider_key().

Since :

2.4

Remarks:

The string provider_key must be released using free().
maps_service_get_provider_key is always synchronous function.

Parameters:

[in]	maps	The Maps Service handle
[out]	provider_key	The Maps Key

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

Precondition:

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

See also:

maps_service_set_provider_key()

maps_service_create()

int maps_service_provider_is_data_supported	(	const maps_service_h	maps,
		maps_service_data_e	data,
		bool *	supported
	)

Checks if the Maps Service supports a data feature.

This function checks if the Maps Service supports a specified data feature.

Since :

2.4

Remarks:

maps_service_provider_is_data_supported is always a synchronous function.

Parameters:

[in]	maps	The handle of Maps Service
[in]	data	The data feature to be checked
[out]	supported	Is the data feature supported

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

Precondition:

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

See also:

maps_service_create()

int maps_service_provider_is_service_supported	(	const maps_service_h	maps,
		maps_service_e	service,
		bool *	supported
	)

Checks if the Maps Service supports a request.

This function checks if the Maps Service supports a specified request.

Since :

2.4

Remarks:

maps_service_provider_is_service_supported is always synchronous function.

Parameters:

[in]	maps	The handle of Maps Service
[in]	service	The service to be checked
[out]	supported	Is the service supported

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

Precondition:

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

See also:

maps_service_create()

int maps_service_request_user_consent	(	const char *	maps_provider,
		maps_service_request_user_consent_cb	callback,
		void *	user_data
	)

Gets the user's consent to use maps data.

The function gets information whether the user agreed that the application can use maps data. If maps_service_request_user_consent() is called when the user didn't agree yet, a popup is shown and the user can decide whether to agree or not. Then the result is saved and maps_service_request_user_consent_cb() is called. If the user has already agreed, the popup is not shown and only the callback is called. The request is asynchronous.

Since :

3.0

Privilege Level:

public

Privilege:

http://tizen.org/privilege/mapservice

Remarks:

Available map providers can be obtained with maps_service_foreach_provider().

Parameters:

[in]	maps_provider	The name of Maps Provider
[in]	callback	The callback which receives the user's consent decision
[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_SERVICE_NOT_AVAILABLE	Service not available
MAPS_ERROR_NOT_SUPPORTED	Not supported
MAPS_ERROR_PERMISSION_DENIED	Permission Denied

Postcondition:

This function invokes maps_service_request_user_consent_cb() to provide information about user consent.

See also:

maps_service_foreach_provider()

maps_service_request_user_consent_cb()

maps_service_create()

int maps_service_set_preference	(	maps_service_h	maps,
		maps_preference_h	preference
	)

Sets the Maps Preference.

This function sets the Maps Preferences which are used in each Maps Service request to Maps Provider.

Since :

2.4

Parameters:

[in]	maps	The handle of Maps Service
[in]	preference	The handle of Maps Preference

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
MAPS_ERROR_PERMISSION_DENIED	Permission Denied

Precondition:

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

See also:

maps_service_get_preference()

maps_service_create()

int maps_service_set_provider_key	(	maps_service_h	maps,
		const char *	provider_key
	)

Sets the Maps Key to be used in the requests of Maps Service.

This function sets the Maps Provider's Key which will be used in each Maps Service request to Maps Provider.
Maps Key can be obtained with maps_service_get_provider_key().

Since :

2.4

Remarks:

To get the provider_key, refer to corresponding Maps Provider documentation.
To get app_id and app_code of HERE, visit https://developer.here.com/, https://developer.here.com/rest-apis.

Parameters:

[in]	maps	The Maps Service handle
[in]	provider_key	The Maps Key to be used. In case of combining two more strings, use slash("/") as a delimiter. e.g. For HERE "app_id/app_code"

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

Precondition:

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

See also:

maps_service_create()

maps_service_get_provider_key()