Tizen Native API  4.0

This provides APIs for Place 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 Place API allows to find places that are relevant to user discovery context.

Functions

int maps_service_search_place (const maps_service_h maps, const maps_coordinates_h position, int distance, const maps_place_filter_h filter, maps_preference_h preference, maps_service_search_place_cb callback, void *user_data, int *request_id)
 Queries a Place information by a coordinates position and a distance.
The request is asynchronous.
int maps_service_search_place_by_area (const maps_service_h maps, const maps_area_h boundary, const maps_place_filter_h filter, maps_preference_h preference, maps_service_search_place_cb callback, void *user_data, int *request_id)
 Queries a Place information by a coordinates boundary.
The request is asynchronous.
int maps_service_search_place_by_address (const maps_service_h maps, const char *address, const maps_area_h boundary, const maps_place_filter_h filter, maps_preference_h preference, maps_service_search_place_cb callback, void *user_data, int *request_id)
 Queries a Place information by a free-formed address string.
The request is asynchronous.
int maps_service_search_place_list (const maps_service_h maps, const maps_area_h boundary, const maps_place_filter_h filter, maps_preference_h preference, maps_service_search_place_list_cb callback, void *user_data, int *request_id)
 Queries a brief Place information by a coordinates boundary./n The request is asynchronous.
int maps_service_get_place_details (const maps_service_h maps, const char *uri, maps_service_get_place_details_cb callback, void *user_data, int *request_id)
 Queries a Detail Place information by a place uri.
The request is asynchronous.

Typedefs

typedef bool(* maps_service_search_place_cb )(maps_error_e error, int request_id, int index, int total, maps_place_h place, void *user_data)
 Called for each result of Place Search request.
typedef void(* maps_service_search_place_list_cb )(maps_error_e error, int request_id, int total, maps_place_list_h place_list, void *user_data)
 Called for Place list of Place Search request.
typedef void(* maps_service_get_place_details_cb )(maps_error_e error, int request_id, maps_place_h place, void *user_data)
 Called for Place detail information of Place Search request.

Typedef Documentation

typedef void(* maps_service_get_place_details_cb)(maps_error_e error, int request_id, maps_place_h place, void *user_data)

Called for Place detail information of Place Search request.

The Maps Service invokes this callback when the Place detail data obtained from the specified uri.
If search is failed, place is NULL.

Since :
2.3.2
Remarks:
The parameter place must be released using maps_place_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 request ID
[in]placeThe resulting Place data
[in]user_dataThe user data passed from maps_service_get_place_details()
Precondition:
maps_service_get_place_details() will invoke this callback.
See also:
maps_service_get_place_details()
typedef bool(* maps_service_search_place_cb)(maps_error_e error, int request_id, int index, int total, maps_place_h place, void *user_data)

Called for each result of Place Search request.

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

Since :
2.3.2
Remarks:
The parameter place must be released using maps_place_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 request ID
[in]indexThe current index of place data in result set, start from 0
[in]totalThe total number of results
[in]placeThe resulting Place data
[in]user_dataThe user data passed from maps_service_search_place(), maps_service_search_place_by_area() or maps_service_search_place_by_address()
Returns:
true to continue with the next iteration of the loop,
false to break out of the loop
Precondition:
maps_service_search_place(), maps_service_search_place_by_area() or maps_service_search_place_by_address() will invoke this callback.
See also:
maps_service_search_place()
maps_service_search_place_by_area()
maps_service_search_place_by_address()
typedef void(* maps_service_search_place_list_cb)(maps_error_e error, int request_id, int total, maps_place_list_h place_list, void *user_data)

Called for Place list of Place Search request.

The Maps Service invokes this callback when the Place data obtained from the specified coordinates.
If search is failed, the value of total is 0 and place_list is NULL.

Since :
2.3.2
Remarks:
The parameter place_list must be released using maps_place_list_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 request ID
[in]totalThe total number of results
[in]place_listThe resulting Place list data
[in]user_dataThe user data passed from maps_service_search_place_list()
Precondition:
maps_service_search_place_list() will invoke this callback.
See also:
maps_service_search_place_list()
maps_place_list_foreach()

Function Documentation

int maps_service_get_place_details ( const maps_service_h  maps,
const char *  uri,
maps_service_get_place_details_cb  callback,
void *  user_data,
int *  request_id 
)

Queries a Detail Place information by a place uri.
The request is asynchronous.

This function obtains the Detail Place information for a specified place uri.

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 Place Search and which Place preferences are supported, see the lists of capacities and preferences above.
Parameters:
[in]mapsThe Maps Service handle
[in]uriThe interested place uri
[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_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_RESOURCE_BUSYPlaces service busy
MAPS_ERROR_CANCELEDPlaces service aborted
MAPS_ERROR_UNKNOWNUnknown error
Precondition:
Call maps_service_create() to create Maps Service and obtain its handle.
uri is obtained from maps_service_search_place_list()
Postcondition:
It invokes maps_service_get_place_details_cb() to deliver obtained Place information.
See also:
maps_service_search_place_list()
maps_service_get_place_details_cb()
maps_service_cancel_request()
maps_service_provider_is_service_supported()
int maps_service_search_place ( const maps_service_h  maps,
const maps_coordinates_h  position,
int  distance,
const maps_place_filter_h  filter,
maps_preference_h  preference,
maps_service_search_place_cb  callback,
void *  user_data,
int *  request_id 
)

Queries a Place information by a coordinates position and a distance.
The request is asynchronous.

This function obtains the Place information for a specified distance around a given coordinates position.

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 places, use maps_service_provider_is_service_supported() with MAPS_SERVICE_SEARCH_PLACE 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]positionThe interested position
[in]distanceThe search area distance
[in]filterThe filter handle
[in]preferenceThe place 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_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_RESOURCE_BUSYPlaces service busy
MAPS_ERROR_CANCELEDPlaces service aborted
MAPS_ERROR_UNKNOWNUnknown error
Precondition:
Call maps_service_create() to create Maps Service and obtain its handle.
Postcondition:
It invokes maps_service_search_place_cb() to deliver obtained Place information.
See also:
maps_service_search_place_by_area()
maps_service_search_place_by_address()
maps_service_cancel_request()
maps_service_search_place_cb()
maps_service_provider_is_service_supported()
maps_service_provider_is_data_supported()
int maps_service_search_place_by_address ( const maps_service_h  maps,
const char *  address,
const maps_area_h  boundary,
const maps_place_filter_h  filter,
maps_preference_h  preference,
maps_service_search_place_cb  callback,
void *  user_data,
int *  request_id 
)

Queries a Place information by a free-formed address string.
The request is asynchronous.

This function obtains the Place information for a specified free-formed address string.

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:
boundary supports only circle type bounds for search.
To cancel the search request, use maps_service_cancel_request().
To check if Maps Provider is capable of searching places by free-formed address, use maps_service_provider_is_service_supported() with MAPS_SERVICE_SEARCH_PLACE_BY_ADDRESS 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]addressThe interested address
[in]boundaryThe interested area
[in]filterThe filter handle
[in]preferenceThe place 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_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_RESOURCE_BUSYPlaces service busy
MAPS_ERROR_CANCELEDPlaces service aborted
MAPS_ERROR_UNKNOWNUnknown error
Precondition:
Call maps_service_create() to create Maps Service and obtain its handle.
Postcondition:
It invokes maps_service_search_place_cb() to deliver obtained Place information.
See also:
maps_service_search_place()
maps_service_search_place_by_area()
maps_service_cancel_request()
maps_service_search_place_cb()
maps_service_provider_is_service_supported()
maps_service_provider_is_data_supported()
int maps_service_search_place_by_area ( const maps_service_h  maps,
const maps_area_h  boundary,
const maps_place_filter_h  filter,
maps_preference_h  preference,
maps_service_search_place_cb  callback,
void *  user_data,
int *  request_id 
)

Queries a Place information by a coordinates boundary.
The request is asynchronous.

This function obtains the Place information for a specified coordinates boundary.

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:
boundary is supporting only circle type bounds for search.
To cancel the search request, use maps_service_cancel_request().
To check if Maps Provider is capable of searching places by coordinates boundaries, use maps_service_provider_is_service_supported() with MAPS_SERVICE_SEARCH_PLACE_BY_AREA 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]boundaryThe interested area
[in]filterThe filter handle
[in]preferenceThe place 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_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_RESOURCE_BUSYPlaces service busy
MAPS_ERROR_CANCELEDPlaces service aborted
MAPS_ERROR_UNKNOWNUnknown error
Precondition:
Call maps_service_create() to create Maps Service and obtain its handle.
Postcondition:
It invokes maps_service_search_place_cb() to deliver obtained Place information.
See also:
maps_service_search_place()
maps_service_search_place_by_address()
maps_service_cancel_request()
maps_service_search_place_cb()
maps_service_provider_is_service_supported()
maps_service_provider_is_data_supported()
int maps_service_search_place_list ( const maps_service_h  maps,
const maps_area_h  boundary,
const maps_place_filter_h  filter,
maps_preference_h  preference,
maps_service_search_place_list_cb  callback,
void *  user_data,
int *  request_id 
)

Queries a brief Place information by a coordinates boundary./n The request is asynchronous.

This function obtains the brief Place information for a specified coordinates boundary.

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 Place Search and which Place preferences are supported, see the lists of capacities and preferences above.
Parameters:
[in]mapsThe Maps Service handle
[in]boundaryThe interested area
[in]filterThe filter handle
[in]preferenceThe place 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_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_RESOURCE_BUSYPlaces service busy
MAPS_ERROR_CANCELEDPlaces service aborted
MAPS_ERROR_UNKNOWNUnknown error
Precondition:
Call maps_service_create() to create Maps Service and obtain its handle.
Postcondition:
It invokes maps_service_search_place_list_cb() to deliver obtained Place information.
See also:
maps_service_get_place_details()
maps_service_search_place_list_cb()
maps_service_cancel_request()
maps_service_provider_is_service_supported()