Functions |
bool | location_manager_is_supported_method (location_method_e method) |
| Checks whether the given location method is available.
|
int | location_manager_is_enabled_method (location_method_e method, bool *enable) |
| Checks whether the given location method is enabled or not on setting.
|
int | location_manager_create (location_method_e method, location_manager_h *manager) |
| Creates a new location manager.
|
int | location_manager_destroy (location_manager_h manager) |
| Releases the location manager.
|
int | location_manager_request_single_location (location_manager_h manager, int timeout, location_updated_cb callback, void *user_data) |
| Request to update current location once.
|
int | location_manager_start (location_manager_h manager) |
| Starts the location service.
|
int | location_manager_stop (location_manager_h manager) |
| Stops the location service.
|
int | location_manager_add_boundary (location_manager_h manager, const location_bounds_h bounds) |
| Adds a bounds for a given location manager.
|
int | location_manager_remove_boundary (location_manager_h manager, const location_bounds_h bounds) |
| Deletes a bounds for a given location manager.
|
int | location_manager_foreach_boundary (location_manager_h manager, location_bounds_cb callback, void *user_data) |
| Retrieves all location bounds by invoking a specific callback for each location bounds.
|
int | location_manager_get_method (location_manager_h manager, location_method_e *method) |
| Gets the given location manager's method.
|
int | location_manager_get_position (location_manager_h manager, double *altitude, double *latitude, double *longitude, time_t *timestamp) |
| Gets the current position information.
|
int | location_manager_get_location (location_manager_h manager, double *altitude, double *latitude, double *longitude, double *climb, double *direction, double *speed, location_accuracy_level_e *level, double *horizontal, double *vertical, time_t *timestamp) |
| Gets the current position information.
|
int | location_manager_get_velocity (location_manager_h manager, double *climb, double *direction, double *speed, time_t *timestamp) |
| Gets the current velocity information.
|
int | location_manager_get_accuracy (location_manager_h manager, location_accuracy_level_e *level, double *horizontal, double *vertical) |
| Gets the current accuracy information.
|
int | location_manager_get_last_position (location_manager_h manager, double *altitude, double *latitude, double *longitude, time_t *timestamp) |
| Gets the last position information which is recorded.
|
int | location_manager_get_last_location (location_manager_h manager, double *altitude, double *latitude, double *longitude, double *climb, double *direction, double *speed, location_accuracy_level_e *level, double *horizontal, double *vertical, time_t *timestamp) |
| Gets the last location information.
|
int | location_manager_get_last_velocity (location_manager_h manager, double *climb, double *direction, double *speed, time_t *timestamp) |
| Gets the last velocity information which is recorded.
|
int | location_manager_get_last_accuracy (location_manager_h manager, location_accuracy_level_e *level, double *horizontal, double *vertical) |
| Gets the last accuracy information which is recorded.
|
int | location_manager_get_accessibility_state (location_accessibility_state_e *state) |
| Gets the current application's location accessibility status.
|
int | location_manager_set_position_updated_cb (location_manager_h manager, location_position_updated_cb callback, int interval, void *user_data) |
| Registers a callback function to be invoked at defined interval with updated position information.
|
int | location_manager_unset_position_updated_cb (location_manager_h manager) |
| Unregisters the callback function.
|
int | location_manager_set_velocity_updated_cb (location_manager_h manager, location_velocity_updated_cb callback, int interval, void *user_data) |
| Registers a callback function to be invoked at defined interval with updated velocity information.
|
int | location_manager_unset_velocity_updated_cb (location_manager_h manager) |
| Unregisters the callback function.
|
int | location_manager_set_service_state_changed_cb (location_manager_h manager, location_service_state_changed_cb callback, void *user_data) |
| Registers a callback function to be invoked when the location service state is changed.
|
int | location_manager_unset_service_state_changed_cb (location_manager_h manager) |
| Unregisters the callback function.
|
int | location_manager_set_zone_changed_cb (location_manager_h manager, location_zone_changed_cb callback, void *user_data) |
| Registers a callback function to be invoked when the previously set boundary area is entered or left.
|
int | location_manager_unset_zone_changed_cb (location_manager_h manager) |
| Unregisters the callback function.
|
int | location_manager_set_setting_changed_cb (location_method_e method, location_setting_changed_cb callback, void *user_data) |
| Registers a callback function to be invoked when the location setting is changed.
|
int | location_manager_unset_setting_changed_cb (location_method_e method) |
| Unregisters the callback function.
|
int | location_manager_get_distance (double start_latitude, double start_longitude, double end_latitude, double end_longitude, double *distance) |
| Gets the distance in meters between two locations.
|
Typedefs |
typedef struct location_manager_s * | location_manager_h |
| The location manager handle.
|
typedef void(* | location_position_updated_cb )(double latitude, double longitude, double altitude, time_t timestamp, void *user_data) |
| Called at defined interval with updated position information.
|
typedef void(* | location_velocity_updated_cb )(double speed, double direction, double climb, time_t timestamp, void *user_data) |
| Called at defined interval with updated velocity information.
|
typedef void(* | location_updated_cb )(location_error_e error, double latitude, double longitude, double altitude, time_t timestamp, double speed, double direction, double climb, void *user_data) |
| Called at defined interval with updated location information.
|
typedef void(* | location_service_state_changed_cb )(location_service_state_e state, void *user_data) |
| Called when the state of location service is changed from enabled to disabled or vice versa.
|
typedef void(* | location_zone_changed_cb )(location_boundary_state_e state, double latitude, double longitude, double altitude, time_t timestamp, void *user_data) |
| Called when the user defined zones are entered or exited.
|
typedef void(* | location_setting_changed_cb )(location_method_e method, bool enable, void *user_data) |
| Called when the state of location method is changed.
|
typedef bool(* | location_bounds_cb )(location_bounds_h bounds, void *user_data) |
| Gets called iteratively to notify you of location bounds.
|
This Location Manager API provides functions for obtaining information related to geographical location. This API provides functions to acquire information related to the current position. Notifications on events like service becoming enabled or disabled, new position data being available and others can also be acquired.
Required Header
#include <locations.h>
Overview
The Location Manager API provides functions to acquire information about geographical location, including both as accurate a current position as possible, and receiving notification of changes in position, crossing boundary "fences", and velocity changes detected by the device.
The related Geolocation API can be used to convert the location to a physical address.
Notifications can be received about the following events:
- Change in service status (enabled / disabled)
- New position and velocity information becoming available
- Given area being entered or left (geofencing)
Information on GPS satellites is provided by the GPS Status & Satellite API.
The main component of the Location Service is the location manager. A location manager serves as a gateway so the application does not have to manage the details of the back-end connection, which might be GPS, WiFi or others, although it may instruct the location manager as to a preference. The location manager also manages the callback functions which it invokes when a given event takes place.
The location manager has the following properties:
- Method
- Boundary
- 'Position updated' callback
- 'Service state change' callback
- 'Velocity updated' callback
- 'Boundary event' callback
The method property of a location manager (location_method_e) determines the source of location information. It can be set only once - when the location manager is instantiated. The method can be one specific location method, or hybrid.
A location manager set to the hybrid method will automatically choose the best method available at the moment, choosing between GPS, WPS and WPS. Note that the method may change any time, due to signals coming in/out of range, and so on. If more than one method is available, priorities are as follows:
1. GPS
2. WPS
If no methods are available, the service state is changed to disabled and the appropriate callback is called. See location_manager_set_service_state_changed_cb() and location_service_state_changed_cb().
The boundary property describes a border enclosing an area. The area can be circular - defined by its center in geographic coordinates a radius, or rectangular - defined by the geographic coordinates of its top left and bottom right corner. The location manager will use the selected method to track if the area has been entered or exited. The location manager will send asynchronous notifications by invoking previously registered callback functions on such change events.
There may be multiple location managers. Callback functions to receive notifications are registered to a specific location manager, not to the location service as a whole. So it is, for example, possible to define several different geographic areas or fences, using different location methods, each being tracked by a different location manager and leading to distinct callbacks.
Setting and unsetting callbacks for the manager can be done at any time, however before callbacks set for a given location manager can be invoked, the location service must be started for that location manager. This constraint holds for managers with GPS, WPS and Hybrid methods. See the Location manager life cycle section below. Note the start/stop functions apply only to the individual location manager and do not affect any other location managers that may be running.
Only one callback can be set for a given event within the scope of a single location manager. Successive callback setting will result in the new callback replacing the old one. If an 'unset callback' function is called when there is no callback set, no error is returned. Callbacks can be set and unset any number of times.
Location manager life cycle
1. Create location manager ( location_manager_create() )
2. Set callbacks and other required information
3. Start service with location_manager_start()
4. Wait until state change callback ( location_service_state_changed_cb() ) is called with LOCATIONS_SERVICE_ENABLED as first argument
5. Other callbacks are working now, wait for events and process
6. Stop service with location_manager_stop()
7. Wait until state change callback ( location_service_state_changed_cb() ) is called with LOCATIONS_SERVICE_DISABLED as first argument
8. Destroy location manager (location_manager_destroy())
After stopping the location service for a given location manager, the location manager can still be used. So some functions can be called if they do not require a location service running on your device. The location service can be re-started later.
If a location manager is no longer needed and is going to be destroyed, it is not mandatory to call location_manager_stop(), as location_manager_destroy() will call it automatically.
Note that after a location manager has been destroyed, the handle (location_manager_h) can be reused - location_manager_create() can be called again for this handle. In other words, the state before creation and after destruction can be treated as the same state.
Related Features
This API is related with the following features:
It is recommended to design feature related codes in your application for reliability.
You can check if a devrice 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.
Typedef Documentation
The location manager handle.
- Since :
- 2.3
typedef void(* location_updated_cb)(location_error_e error, double latitude, double longitude, double altitude, time_t timestamp, double speed, double direction, double climb, void *user_data) |
Called at defined interval with updated location information.
- Since :
- 2.3
- Parameters:
-
[in] | error | LOCATIONS_ERROR_NONE Successful |
[in] | latitude | The updated latitude [-90.0 ~ 90.0] (degrees) |
[in] | longitude | The updated longitude [-180.0 ~ 180.0] (degrees) |
[in] | altitude | The updated altitude (meters) |
[in] | timestamp | The timestamp (time when measurement took place or 0 if valid) |
[in] | speed | The updated speed (km/h) |
[in] | direction | The updated direction (in degrees from the north) |
[in] | climb | The updated climb (km/h) |
[in] | user_data | The user data passed from the callback registration function |
- Precondition:
- location_manager_request_single_location() will invoke this callback.
- See also:
- location_manager_request_single_location()
Enumeration Type Documentation
Enumeration for the location service accessibility state.
- Since :
- 2.3
- Enumerator:
LOCATIONS_ACCESS_STATE_NONE |
Access state is not determined
|
LOCATIONS_ACCESS_STATE_DENIED |
Access denied
|
LOCATIONS_ACCESS_STATE_ALLOWED |
Access authorized
|
Enumeration for Approximate accuracy level of given information.
- Since :
- 2.3
- Enumerator:
LOCATIONS_ACCURACY_NONE |
Invalid data
|
LOCATIONS_ACCURACY_COUNTRY |
Country accuracy level
|
LOCATIONS_ACCURACY_REGION |
Regional accuracy level
|
LOCATIONS_ACCURACY_LOCALITY |
Local accuracy level
|
LOCATIONS_ACCURACY_POSTALCODE |
Postal accuracy level
|
LOCATIONS_ACCURACY_STREET |
Street accuracy level
|
LOCATIONS_ACCURACY_DETAILED |
Detailed accuracy level
|
Enumeration for error code for Location manager.
- Enumerator:
LOCATIONS_ERROR_NONE |
Successful
|
LOCATIONS_ERROR_OUT_OF_MEMORY |
Out of memory
|
LOCATIONS_ERROR_INVALID_PARAMETER |
Invalid parameter
|
LOCATIONS_ERROR_ACCESSIBILITY_NOT_ALLOWED |
Permission denied
|
LOCATIONS_ERROR_NOT_SUPPORTED |
Not supported
|
LOCATIONS_ERROR_INCORRECT_METHOD |
Location manager contains incorrect method for a given call
|
LOCATIONS_ERROR_NETWORK_FAILED |
Network unavailable
|
LOCATIONS_ERROR_SERVICE_NOT_AVAILABLE |
Location service is not available
|
LOCATIONS_ERROR_GPS_SETTING_OFF |
GPS/WPS setting is not enabled
|
LOCATIONS_ERROR_SECURITY_RESTRICTED |
Restricted by security system policy
|
Enumeration for Location method type.
- Since :
- 2.3
- Enumerator:
LOCATIONS_METHOD_NONE |
Undefined method
|
LOCATIONS_METHOD_HYBRID |
This method selects the best method available at the moment
|
LOCATIONS_METHOD_GPS |
This method uses Global Positioning System
|
LOCATIONS_METHOD_WPS |
This method uses WiFi Positioning System
|
Enumeration for the state of the location service.
- Since :
- 2.3
- Enumerator:
LOCATIONS_SERVICE_DISABLED |
Service is disabled
|
LOCATIONS_SERVICE_ENABLED |
Service is enabled
|
Function Documentation
Creates a new location manager.
- Since :
- 2.3
- Parameters:
-
[in] | method | The location method |
[out] | manager | The location manager handle that is newly created |
- Returns:
0
on success otherwise a negative error value
- Return values:
-
- See also:
- location_manager_destroy()
Releases the location manager.
- Since :
- 2.3
- Parameters:
-
[in] | manager | The location manager handle |
- Returns:
0
on success otherwise a negative error value
- Return values:
-
- See also:
- location_manager_create()
Gets the current application's location accessibility status.
- Since :
- 2.3
- Parameters:
-
[out] | state | The current location service accessibility status. |
- Returns:
- 0 on success, otherwise a negative error value.
- Return values:
-
Gets the current accuracy information.
- Since :
- 2.3
- Privilege Level:
- public
- Privilege:
- http://tizen.org/privilege/location
- Parameters:
-
[in] | manager | The location manager handle |
[out] | level | The accuracy level |
[out] | horizontal | The horizontal accuracy (meters) |
[out] | vertical | The vertical accuracy (meters) |
- Returns:
- 0 on success, otherwise a negative error value.
- Return values:
-
- Precondition:
- The location service state must be LOCATIONS_SERVICE_ENABLED with location_manager_start()
int location_manager_get_distance |
( |
double |
start_latitude, |
|
|
double |
start_longitude, |
|
|
double |
end_latitude, |
|
|
double |
end_longitude, |
|
|
double * |
distance |
|
) |
| |
Gets the distance in meters between two locations.
- Since :
- 2.3
- Parameters:
-
[in] | start_latitude | The starting latitude [-90.0 ~ 90.0] (degrees) |
[in] | start_longitude | The starting longitude [-180.0 ~ 180.0] (degrees) |
[in] | end_latitude | The ending latitude [-90.0 ~ 90.0] (degrees) |
[in] | end_longitude | The ending longitude [-180.0 ~ 180.0] (degrees) |
[out] | distance | The distance between two locations (meters) |
- Returns:
- 0 on success, otherwise a negative error value.
- Return values:
-
Gets the last accuracy information which is recorded.
- Since :
- 2.3
- Privilege Level:
- public
- Privilege:
- http://tizen.org/privilege/location
- Parameters:
-
[in] | manager | The location manager handle |
[out] | level | The last accuracy level |
[out] | horizontal | The last horizontal accuracy (meters) |
[out] | vertical | The last vertical accuracy (meters) |
- Returns:
- 0 on success, otherwise a negative error value.
- Return values:
-
- Precondition:
- The location manager handle must be created by location_manager_create()
int location_manager_get_last_location |
( |
location_manager_h |
manager, |
|
|
double * |
altitude, |
|
|
double * |
latitude, |
|
|
double * |
longitude, |
|
|
double * |
climb, |
|
|
double * |
direction, |
|
|
double * |
speed, |
|
|
location_accuracy_level_e * |
level, |
|
|
double * |
horizontal, |
|
|
double * |
vertical, |
|
|
time_t * |
timestamp |
|
) |
| |
Gets the last location information.
The altitude, latitude, longitude, climb, direction, speed and timestamp
values should be 0, if there is no record of any previous position information.
- Since :
- 2.3
- Privilege Level:
- public
- Privilege:
- http://tizen.org/privilege/location
- Parameters:
-
[in] | manager | The location manager handle |
[out] | altitude | The current altitude (meters) |
[out] | latitude | The current latitude [-90.0 ~ 90.0] (degrees) |
[out] | longitude | The current longitude [-180.0 ~ 180.0] (degrees) |
[out] | climb | The climb (km/h) |
[out] | direction | The direction, degrees from the north |
[out] | speed | The speed (km/h) |
[out] | level | The accuracy level |
[out] | horizontal | The horizontal accuracy (meters) |
[out] | vertical | The vertical accuracy (meters) |
[out] | timestamp | The timestamp (time when measurement took place or 0 if valid) |
- Returns:
0
on success, otherwise a negative error value.
- Return values:
-
- Precondition:
- The location manager handle must be created by location_manager_create()
Gets the last position information which is recorded.
The altitude, latitude, longitude, and timestamp
values should be 0, if there is no record of any previous position information.
- Since :
- 2.3
- Privilege Level:
- public
- Privilege:
- http://tizen.org/privilege/location
- Parameters:
-
[in] | manager | The location manager handle |
[out] | altitude | The last altitude (meters) |
[out] | latitude | The last latitude [-90.0 ~ 90.0] (degrees) |
[out] | longitude | The last longitude [-180.0 ~ 180.0] (degrees) |
[out] | timestamp | The timestamp (time when measurement took place or 0 if valid) |
- Returns:
0
on success, otherwise a negative error value.
- Return values:
-
- Precondition:
- The location manager handle must be created by location_manager_create()
Gets the last velocity information which is recorded.
The climb, direction and speed values should be 0
, if there is no record of any previous velocity information.
- Since :
- 2.3
- Privilege Level:
- public
- Privilege:
- http://tizen.org/privilege/location
- Parameters:
-
[in] | manager | The location manager handle |
[out] | climb | The last climb (km/h) |
[out] | direction | The last direction, degrees from the north |
[out] | speed | The last speed (km/h) |
[out] | timestamp | The timestamp (time when measurement took place or 0 if valid) |
- Returns:
0
on success, otherwise a negative error value.
- Return values:
-
- Precondition:
- The location manager handle must be created by location_manager_create()
int location_manager_get_location |
( |
location_manager_h |
manager, |
|
|
double * |
altitude, |
|
|
double * |
latitude, |
|
|
double * |
longitude, |
|
|
double * |
climb, |
|
|
double * |
direction, |
|
|
double * |
speed, |
|
|
location_accuracy_level_e * |
level, |
|
|
double * |
horizontal, |
|
|
double * |
vertical, |
|
|
time_t * |
timestamp |
|
) |
| |
Gets the current position information.
The result contains the current altitude, latitude, longitude, climb, direction, speed, level, horizontal and vertical with a measurement timestamp.
- Since :
- 2.3
- Privilege Level:
- public
- Privilege:
- http://tizen.org/privilege/location
- Parameters:
-
[in] | manager | The location manager handle |
[out] | altitude | The current altitude (meters) |
[out] | latitude | The current latitude [-90.0 ~ 90.0] (degrees) |
[out] | longitude | The current longitude [-180.0 ~ 180.0] (degrees) |
[out] | climb | The climb (km/h) |
[out] | direction | The direction, degrees from the north |
[out] | speed | The speed (km/h) |
[out] | level | The accuracy level |
[out] | horizontal | The horizontal accuracy (meters) |
[out] | vertical | The vertical accuracy (meters) |
[out] | timestamp | The timestamp (time when measurement took place or 0 if valid) |
- Returns:
- 0 on success, otherwise a negative error value.
- Return values:
-
- Precondition:
- The location service state must be LOCATIONS_SERVICE_ENABLED with location_manager_start()
Gets the given location manager's method.
- Since :
- 2.3
- Parameters:
-
[in] | manager | The location manager handle |
[out] | method | The location method |
- Returns:
0
on success, otherwise a negative error value.
- Return values:
-
- See also:
- location_manager_create()
Gets the current position information.
The result contains the current altitude, latitude, and longitude, with a measurement timestamp.
- Since :
- 2.3
- Privilege Level:
- public
- Privilege:
- http://tizen.org/privilege/location
- Parameters:
-
[in] | manager | The location manager handle |
[out] | altitude | The current altitude (meters) |
[out] | latitude | The current latitude [-90.0 ~ 90.0] (degrees) |
[out] | longitude | The current longitude [-180.0 ~ 180.0] (degrees) |
[out] | timestamp | The timestamp (time when measurement took place or 0 if valid) |
- Returns:
- 0 on success, otherwise a negative error value.
- Return values:
-
- Precondition:
- The location service state must be LOCATIONS_SERVICE_ENABLED with location_manager_start()
Gets the current velocity information.
The result contains the current climb, direction, and speed, with a measurement timestamp.
- Since :
- 2.3
- Privilege Level:
- public
- Privilege:
- http://tizen.org/privilege/location
- Parameters:
-
[in] | manager | The location manager handle |
[out] | climb | The climb (km/h) |
[out] | direction | The direction, degrees from the north |
[out] | speed | The speed (km/h) |
[out] | timestamp | The timestamp (time when measurement took place or 0 if valid) |
- Returns:
0
on success, otherwise a negative error value
- Return values:
-
- Precondition:
- The location service state must be LOCATIONS_SERVICE_ENABLED with location_manager_start()
Checks whether the given location method is available.
- Since :
- 2.3
- Parameters:
-
[in] | method | The location method to be checked |
- Returns:
true
if the specified location method is supported, otherwise false
if it is not available
- Exceptions:
-
- See also:
- location_manager_create()
-
location_manager_get_method()
Deletes a bounds for a given location manager.
- Since :
- 2.3
- Parameters:
-
[in] | manager | The location manager handle |
[in] | bounds | The location bounds handle |
- Returns:
0
on success, otherwise a negative error value
- Return values:
-
- See also:
- location_manager_add_boundary()
Request to update current location once.
- Since :
- 2.3
- Privilege Level:
- public
- Privilege:
- http://tizen.org/privilege/location
- Parameters:
-
[in] | manager | The location manager handle |
[in] | timeout | Timeout to stop requesting single location after |
[in] | callback | The location callback function to register |
[in] | user_data | The user data to be passed to the callback function |
- Return values:
-
- Postcondition:
- It invokes location_updated_cb().
Registers a callback function to be invoked at defined interval with updated position information.
- Since :
- 2.3
- Parameters:
-
[in] | manager | The location manager handle |
[in] | callback | The callback function to register |
[in] | interval | The interval [1 ~ 120] (seconds) |
[in] | user_data | The user data to be passed to the callback function |
- Returns:
0
on success, otherwise a negative error value.
- Return values:
-
- Postcondition:
- location_position_updated_cb() will be invoked
- See also:
- location_manager_unset_position_updated_cb()
-
location_position_updated_cb()
Registers a callback function to be invoked at defined interval with updated velocity information.
- Since :
- 2.3
- Parameters:
-
[in] | manager | The location manager handle |
[in] | callback | The callback function to register |
[in] | interval | The interval [1 ~ 120] (seconds) |
[in] | user_data | The user data to be passed to the callback function |
- Returns:
0
on success, otherwise a negative error value.
- Return values:
-
- Postcondition:
- location_velocity_updated_cb() will be invoked
- See also:
- location_manager_unset_velocity_updated_cb()
-
location_velocity_updated_cb()
Unregisters the callback function.
- Since :
- 2.3
- Parameters:
-
[in] | manager | The location manager handle |
- Returns:
0
on success, otherwise a negative error value.
- Return values:
-
- See also:
- location_manager_set_position_updated_cb()
Unregisters the callback function.
- Since :
- 2.3
- Parameters:
-
[in] | method | The method to observe |
- Returns:
- 0 on success, otherwise a negative error value.
- Return values:
-
- See also:
- location_manager_set_setting_changed_cb()
Unregisters the callback function.
- Since :
- 2.3
- Parameters:
-
[in] | manager | The location manager handle |
- Returns:
0
on success, otherwise a negative error value.
- Return values:
-
- See also:
- location_manager_set_velocity_updated_cb()
Unregisters the callback function.
- Since :
- 2.3
- Parameters:
-
[in] | manager | The location manager handle |
- Returns:
- 0 on success, otherwise a negative error value.
- Return values:
-
- See also:
- location_manager_set_zone_changed_cb()