Tizen Native API  3.0
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

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

Since :
2.4

Enumeration for maps features available in the Maps Service.

Since :
2.4

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_providerThe info of Maps Provider
[in]user_dataThe 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]consentedThe value of User Consent
[in]maps_providerThe name of Maps Provider
[in]user_dataThe 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

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

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)

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]mapsThe Maps Service handle
[in]request_idThe ID of request
Returns:
0 on success, otherwise a negative error value
Return values:
MAPS_ERROR_NONESuccessful
MAPS_ERROR_INVALID_PARAMETERInvalid parameter
MAPS_ERROR_NETWORK_UNREACHABLENetwork connection failed
MAPS_ERROR_SERVICE_NOT_AVAILABLEService not available
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:
request_id is obtained from one of followings:
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_providerThe name of Maps Provider
[out]mapsA handle of the new Maps Service on success
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_SERVICE_NOT_AVAILABLEService not available
MAPS_ERROR_NOT_SUPPORTEDNot supported
MAPS_ERROR_PERMISSION_DENIEDPermission Denied
MAPS_ERROR_USER_NOT_CONSENTEDThe 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()

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]mapsThe Maps Service handle to destroy
Returns:
0 on success, otherwise a negative error value
Return values:
MAPS_ERROR_NONESuccessful
MAPS_ERROR_INVALID_PARAMETERInvalid parameter
MAPS_ERROR_NOT_SUPPORTEDNot supported
MAPS_ERROR_PERMISSION_DENIEDPermission 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]callbackThe callback function to receive available Maps Providers information
[out]user_dataThe user data to be passed to the callback function
Returns:
0 on success, otherwise a negative error value
Return values:
MAPS_ERROR_NONESuccessful
MAPS_ERROR_INVALID_PARAMETERInvalid parameter
MAPS_ERROR_NOT_FOUNDResult not found
MAPS_ERROR_NOT_SUPPORTEDNot 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()

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]mapsThe handle of Maps Service
[out]preferenceThe handle of Maps Preference
Returns:
0 on success, otherwise a negative error value
Return values:
MAPS_ERROR_NONESuccessful
MAPS_ERROR_INVALID_PARAMETERInvalid parameter
MAPS_ERROR_NOT_SUPPORTEDNot 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]mapsThe Maps Service handle
[out]provider_keyThe Maps Key
Returns:
0 on success, otherwise a negative error value
Return values:
MAPS_ERROR_NONESuccessful
MAPS_ERROR_INVALID_PARAMETERInvalid parameter
MAPS_ERROR_NOT_SUPPORTEDNot 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]mapsThe handle of Maps Service
[in]dataThe data feature to be checked
[out]supportedIs the data feature supported
Returns:
0 on success, otherwise a negative error value
Return values:
MAPS_ERROR_NONESuccessful
MAPS_ERROR_INVALID_PARAMETERInvalid parameter
MAPS_ERROR_NOT_SUPPORTEDNot 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]mapsThe handle of Maps Service
[in]serviceThe service to be checked
[out]supportedIs the service supported
Returns:
0 on success, otherwise a negative error value
Return values:
MAPS_ERROR_NONESuccessful
MAPS_ERROR_INVALID_PARAMETERInvalid parameter
MAPS_ERROR_NOT_SUPPORTEDNot 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_providerThe name of Maps Provider
[in]callbackThe callback which receives the user's consent decision
[in]user_dataThe user data to be passed to the callback function
Returns:
0 on success, otherwise a negative error value
Return values:
MAPS_ERROR_NONESuccessful
MAPS_ERROR_INVALID_PARAMETERInvalid parameter
MAPS_ERROR_SERVICE_NOT_AVAILABLEService not available
MAPS_ERROR_NOT_SUPPORTEDNot supported
MAPS_ERROR_PERMISSION_DENIEDPermission 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()

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]mapsThe handle of Maps Service
[in]preferenceThe handle of Maps Preference
Returns:
0 on success, otherwise a negative error value
Return values:
MAPS_ERROR_NONESuccessful
MAPS_ERROR_INVALID_PARAMETERInvalid parameter
MAPS_ERROR_NOT_SUPPORTEDNot supported
MAPS_ERROR_PERMISSION_DENIEDPermission 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]mapsThe Maps Service handle
[in]provider_keyThe 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_NONESuccessful
MAPS_ERROR_INVALID_PARAMETERInvalid parameter
MAPS_ERROR_NOT_SUPPORTEDNot supported
Precondition:
Call maps_service_create() to create Maps Service and get its handle.
See also:
maps_service_create()
maps_service_get_provider_key()