Location Manager

---

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:

• http://tizen.org/feature/location
  
• http://tizen.org/feature/location.gps
  
• http://tizen.org/feature/location.wps
  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.

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_enable_method (const location_method_e method, const bool enable)
	Enables the given location method.
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)
	Requests 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 bounds for a given location manager.
int	location_manager_remove_boundary (location_manager_h manager, const location_bounds_h bounds)
	Deletes 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) TIZEN_DEPRECATED_API
	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.
int	location_manager_set_distance_based_location_changed_cb (location_manager_h manager, location_changed_cb callback, int interval, double distance, void *user_data)
	Registers a callback function to be invoked at minimum interval or minimum distance with updated position information.
int	location_manager_unset_distance_based_location_changed_cb (location_manager_h manager)
	Unregisters the callback function.
int	location_manager_set_location_changed_cb (location_manager_h manager, location_changed_cb callback, int interval, void *user_data)
	Registers a callback function to be invoked at defined interval with updated location information.
int	location_manager_unset_location_changed_cb (location_manager_h manager)
	Unregisters the callback function.
int	location_manager_set_location_batch_cb (location_manager_h manager, location_batch_cb callback, int batch_interval, int batch_period, void *user_data)
	Registers a callback function to be invoked when batch_period is expired.
int	location_manager_unset_location_batch_cb (location_manager_h manager)
	Unregisters the callback function.
int	location_manager_start_batch (location_manager_h manager)
	Starts the location batch service.
int	location_manager_stop_batch (location_manager_h manager)
	Stops the location batch service.
int	location_manager_foreach_location_batch (location_manager_h manager, location_batch_get_location_cb callback, void *user_data)
	Retrieves all location information by invoking a specific callback for each location data.
int	location_manager_is_enabled_mock_location (bool *enabled)
	Checks whether the mock location is enabled.
int	location_manager_enable_mock_location (const bool enable)
	Enables mock location.
int	location_manager_set_mock_location (location_manager_h manager, const double latitude, const double longitude, const double altitude, const double speed, const double direction, const double accuracy)
	Sets a mock location for the given location method.
int	location_manager_clear_mock_location (location_manager_h manager)
	Clears a mock location.
int	location_manager_set_fused_mode (location_manager_h manager, location_fused_mode_e mode)
	Changes behavior of the location source selection in the fused location method.
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)
	Called once for each location bound.
typedef void(*	location_changed_cb )(double latitude, double longitude, double altitude, double speed, double direction, double horizontal_accuracy, time_t timestamp, void *user_data)
	Called at defined interval with updated location information.
typedef void(*	location_batch_cb )(int num_of_location, void *user_data)
	Called when the batch interval is expired.
typedef bool(*	location_batch_get_location_cb )(double latitude, double longitude, double altitude, double speed, double direction, double horizontal, double vertical, time_t timestamp, void *user_data)
	Gets iteratively to receive location batch data.

---

Typedef Documentation

typedef void(* location_batch_cb)(int num_of_location, void *user_data)

Called when the batch interval is expired.

Since :

3.0

Parameters:

[in]	num_of_location	The number of location batch data
[in]	user_data	The user data passed from the callback registration function

Precondition:

location_manager_start_batch() will invoke this callback if you register this callback using location_manager_set_location_batch_cb().

See also:

location_manager_start_batch()

location_manager_set_location_batch_cb()

typedef bool(* location_batch_get_location_cb)(double latitude, double longitude, double altitude, double speed, double direction, double horizontal, double vertical, time_t timestamp, void *user_data)

Gets iteratively to receive location batch data.

Since :

3.0

Parameters:

[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]	speed	The updated speed (km/h)
[in]	direction	The updated direction (in degrees from the north)
[in]	horizontal	The horizontal accuracy (meters)
[in]	vertical	The vertical accuracy (meters)
[in]	timestamp	The timestamp (time when measurement took place or 0 if valid)
[in]	user_data	The user data passed from the callback registration function

Returns:

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

Precondition:

location_manager_foreach_location_batch() will invoke this callback.

See also:

location_manager_foreach_location_batch()

typedef bool(* location_bounds_cb)(location_bounds_h bounds, void *user_data)

Called once for each location bound.

Since :

2.3

Parameters:

[in]	bounds	The location bounds handle
[in]	user_data	The user data passed from the callback registration function

Returns:

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

Precondition:

location_manager_foreach_boundary() will invoke this callback.

See also:

location_manager_foreach_boundary()

typedef void(* location_changed_cb)(double latitude, double longitude, double altitude, double speed, double direction, double horizontal_accuracy, time_t timestamp, void *user_data)

Called at defined interval with updated location information.

Since :

2.4

Parameters:

[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]	speed	The updated speed (km/h)
[in]	direction	The updated direction (in degrees from the north)
[in]	horizontal_accuracy	The horizontal accuracy (meters)
[in]	timestamp	The timestamp (time when measurement took place or 0 if valid)
[in]	user_data	The user data passed from the callback registration function

Precondition:

location_manager_start() will invoke this callback if you register this callback using location_manager_set_position_updated_cb().

See also:

location_manager_start()

location_manager_set_distance_based_location_changed_cb()

location_manager_set_location_changed_cb()

typedef struct location_manager_s* location_manager_h

The location manager handle.

Since :

2.3

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.

Since :

2.3

Parameters:

[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]	user_data	The user data passed from the call registration function

Precondition:

location_manager_start() will invoke this callback if you register this callback using location_manager_set_position_updated_cb().

See also:

location_manager_start()

location_manager_set_position_updated_cb()

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.

Since :

2.3

Parameters:

[in]	state	The service state
[in]	user_data	The user data passed from the callback registration function

Precondition:

Either location_manager_start() or location_manager_stop() will invoke this callback if you register this callback using location_manager_set_service_state_changed_cb().

See also:

location_manager_start()

location_manager_stop()

location_manager_set_service_state_changed_cb()

location_service_state_e

typedef void(* location_setting_changed_cb)(location_method_e method, bool enable, void *user_data)

Called when the state of location method is changed.

Since :

2.3

Parameters:

[in]	method	The method changed on setting
[in]	enable	The setting value changed
[in]	user_data	The user data passed from the callback registration function

Precondition:

location_setting_changed_cb() will invoke this callback if you register this callback using location_manager_set_setting_changed_cb().

See also:

location_manager_set_setting_changed_cb()

location_manager_unset_setting_changed_cb()

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()

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.

Since :

2.3

Parameters:

[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]	timestamp	The timestamp (time when measurement took place or 0 if valid)
[in]	user_data	The user data passed from the callback registration function

Precondition:

location_manager_start() will invoke this callback if you register this callback using location_manager_set_velocity_updated_cb().

See also:

location_manager_start()

location_manager_set_velocity_updated_cb()

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.

Since :

2.3

Parameters:

[in]	state	The boundary state
[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]	user_data	The user data passed from the callback registration function

Precondition:

location_manager_start() will invoke this callback if you register this callback using location_manager_set_zone_changed_cb().

See also:

location_boundary_state_e

location_manager_start()

location_manager_set_zone_changed_cb()

---

Enumeration Type Documentation

enum location_accessibility_state_e

Enumeration for the location service accessibility state.

Deprecated:

Deprecated since 3.0

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

enum location_accuracy_level_e

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

enum location_error_e

Enumeration for error code for Location manager.

Since :

2.3

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	Setting for GPS, WPS, or MOCK is turned off
LOCATIONS_ERROR_SECURITY_RESTRICTED	Restricted by security system policy
LOCATIONS_ERROR_SETTING_OFF	Setting for GPS, WPS, or MOCK is turned off (Since 3.0)

enum location_fused_mode_e

Enumeration for the fused location service.

Since :

4.0

Enumerator:

LOCATIONS_FUSED_HIGH_ACCURACY	High accuracy
LOCATIONS_FUSED_BALANCED_POWER	Balanced power

enum location_method_e

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
LOCATIONS_METHOD_PASSIVE	This method can be used to passively receive location updates without power consumption (Since 3.0)
LOCATIONS_METHOD_FUSED	This method uses Fused location (Since 4.0)

enum location_service_state_e

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

int location_manager_add_boundary	(	location_manager_h	manager,
		const location_bounds_h	bounds
	)

Adds 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:

LOCATIONS_ERROR_NONE	Successful
LOCATIONS_ERROR_INVALID_PARAMETER	Invalid parameter
LOCATIONS_ERROR_OUT_OF_MEMORY	Out of memory
LOCATIONS_ERROR_NOT_SUPPORTED	Not supported

Postcondition:

It invokes location_manager_set_zone_changed_cb() when a boundary is entered or exited, if you set a callback with location_manager_set_zone_changed_cb().

See also:

location_manager_remove_boundary()

location_manager_set_zone_changed_cb()

int location_manager_clear_mock_location

(

location_manager_h

manager

)

Clears a mock location.

Since :

3.0

Privilege Level:

public

Privilege:

http://tizen.org/privilege/location

Parameters:

[in]

manager

The location manager handle

Returns:

0 on success, otherwise a negative error value

Return values:

LOCATIONS_ERROR_NONE	Successful
LOCATIONS_ERROR_INVALID_PARAMETER	Invalid argument
LOCATIONS_ERROR_SERVICE_NOT_AVAILABLE	Service not available
LOCATIONS_ERROR_ACCESSIBILITY_NOT_ALLOWED	The application does not have the privilege to call this method
LOCATIONS_ERROR_SETTING_OFF	MOCK location is not enabled
LOCATIONS_ERROR_NOT_SUPPORTED	Not supported

See also:

location_manager_create()

location_manager_is_enabled_mock_location()

location_manager_enable_mock_location()

location_manager_set_mock_location()

int location_manager_create	(	location_method_e	method,
		location_manager_h *	manager
	)

Creates a new location manager.

Since :

2.3

Remarks:

You must release manager using location_manager_destroy().

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:

LOCATIONS_ERROR_NONE	Successful
LOCATIONS_ERROR_OUT_OF_MEMORY	Out of memory
LOCATIONS_ERROR_INVALID_PARAMETER	Invalid parameter
LOCATIONS_ERROR_SERVICE_NOT_AVAILABLE	Service not available
LOCATIONS_ERROR_NOT_SUPPORTED	Not supported

See also:

location_manager_destroy()

int location_manager_destroy

(

location_manager_h

manager

)

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:

LOCATIONS_ERROR_NONE	Successful
LOCATIONS_ERROR_INVALID_PARAMETER	Invalid parameter
LOCATIONS_ERROR_NOT_SUPPORTED	Not supported

See also:

location_manager_create()

int location_manager_enable_method	(	const location_method_e	method,
		const bool	enable
	)

Enables the given location method.

Warning:

This is not for use by third-party applications.

Since :

2.3.1

Privilege Level:

platform

Privilege:

http://tizen.org/privilege/location.enable

Parameters:

[in]	method	The location method to be checked
[in]	enable	The value to set

Returns:

0 on success, otherwise a negative error value

Return values:

LOCATIONS_ERROR_NONE	Successful
LOCATIONS_ERROR_INCORRECT_METHOD	Incorrect method
LOCATIONS_ERROR_ACCESSIBILITY_NOT_ALLOWED	Permission denied
LOCATIONS_ERROR_NOT_SUPPORTED	Not supported

See also:

location_manager_is_enabled_method()

location_manager_create()

int location_manager_enable_mock_location

(

const bool

enable

)

Enables mock location.

The mock location is a testing function to make location API and callback deliver a mock location set by location_manager_set_mock_location() instead of real positioning data even in the other applications.

Since :

3.0

Privilege Level:

public

Privilege:

http://tizen.org/privilege/location

Remarks:

The mock location can only be enabled if developer mode is enabled.

Parameters:

[in]

enable

The value to set

Returns:

0 on success, otherwise a negative error value

Return values:

LOCATIONS_ERROR_NONE	Successful
LOCATIONS_ERROR_SETTING_OFF	MOCK location is not enabled
LOCATIONS_ERROR_ACCESSIBILITY_NOT_ALLOWED	Permission denied
LOCATIONS_ERROR_NOT_SUPPORTED	Not supported

See also:

location_manager_is_enabled_mock_location()

location_manager_set_mock_location()

location_manager_clear_mock_location()

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.

Since :

2.3

Parameters:

[in]	manager	The location manager handle
[in]	callback	The iteration callback
[in]	user_data	The user data to be passed to the callback function

Returns:

0 on success, otherwise a negative error value

Return values:

LOCATIONS_ERROR_NONE	Successful
LOCATIONS_ERROR_INVALID_PARAMETER	Invalid parameter
LOCATIONS_ERROR_NOT_SUPPORTED	Not supported

Postcondition:

location_bounds_cb() will be invoked.

See also:

location_manager_add_boundary()

location_manager_remove_boundary()

location_bounds_cb()

int location_manager_foreach_location_batch	(	location_manager_h	manager,
		location_batch_get_location_cb	callback,
		void *	user_data
	)

Retrieves all location information by invoking a specific callback for each location data.

Since :

3.0

Privilege Level:

public

Privilege:

http://tizen.org/privilege/location

Parameters:

[in]	manager	The location manager handle
[in]	callback	The iteration callback function
[in]	user_data	The user data to be passed to the callback function

Returns:

0 on success, otherwise a negative error value

Return values:

LOCATIONS_ERROR_NONE	Successful
LOCATIONS_ERROR_INVALID_PARAMETER	Invalid parameter
LOCATIONS_ERROR_ACCESSIBILITY_NOT_ALLOWED	The application does not have the privilege to call this method
LOCATIONS_ERROR_NOT_SUPPORTED	Not supported

Precondition:

location_manager_foreach_location_batch() is available after location_batch_cb() is invoked.

Postcondition:

location_batch_get_location_cb() will be invoked.

See also:

location_manager_start_batch()

location_batch_cb()

location_batch_get_location_cb()

int location_manager_get_accessibility_state

(

location_accessibility_state_e *

state

)

Gets the current application's location accessibility status.

Deprecated:

Deprecated since 3.0

Since :

2.3

Parameters:

[out]

state

The current location service accessibility status

Returns:

0 on success, otherwise a negative error value

Return values:

LOCATIONS_ERROR_NONE	Successful
LOCATIONS_ERROR_SERVICE_NOT_AVAILABLE	Service not available
LOCATIONS_ERROR_INVALID_PARAMETER	Invalid argument
LOCATIONS_ERROR_NOT_SUPPORTED	Not supported

int location_manager_get_accuracy	(	location_manager_h	manager,
		location_accuracy_level_e *	level,
		double *	horizontal,
		double *	vertical
	)

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:

LOCATIONS_ERROR_NONE	Successful
LOCATIONS_ERROR_INVALID_PARAMETER	Invalid argument
LOCATIONS_ERROR_SERVICE_NOT_AVAILABLE	Service not available
LOCATIONS_ERROR_GPS_SETTING_OFF	GPS is not enabled
LOCATIONS_ERROR_ACCESSIBILITY_NOT_ALLOWED	The application does not have the privilege to call this method
LOCATIONS_ERROR_NOT_SUPPORTED	Not supported

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:

LOCATIONS_ERROR_NONE	Successful
LOCATIONS_ERROR_INVALID_PARAMETER	Invalid argument
LOCATIONS_ERROR_NOT_SUPPORTED	Not supported

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.

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:

LOCATIONS_ERROR_NONE	Successful
LOCATIONS_ERROR_INVALID_PARAMETER	Invalid argument
LOCATIONS_ERROR_ACCESSIBILITY_NOT_ALLOWED	The application does not have the privilege to call this method
LOCATIONS_ERROR_NOT_SUPPORTED	Not supported

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:

LOCATIONS_ERROR_NONE	Successful
LOCATIONS_ERROR_INVALID_PARAMETER	Invalid argument
LOCATIONS_ERROR_ACCESSIBILITY_NOT_ALLOWED	The application does not have the privilege to call this method
LOCATIONS_ERROR_NOT_SUPPORTED	Not supported

Precondition:

The location manager handle must be created by location_manager_create().

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.

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:

LOCATIONS_ERROR_NONE	Successful
LOCATIONS_ERROR_INVALID_PARAMETER	Invalid argument
LOCATIONS_ERROR_ACCESSIBILITY_NOT_ALLOWED	The application does not have the privilege to call this method
LOCATIONS_ERROR_NOT_SUPPORTED	Not supported

Precondition:

The location manager handle must be created by location_manager_create().

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.

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:

LOCATIONS_ERROR_NONE	Successful
LOCATIONS_ERROR_INVALID_PARAMETER	Invalid argument
LOCATIONS_ERROR_ACCESSIBILITY_NOT_ALLOWED	The application does not have the privilege to call this method
LOCATIONS_ERROR_NOT_SUPPORTED	Not supported

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:

LOCATIONS_ERROR_NONE	Successful
LOCATIONS_ERROR_INVALID_PARAMETER	Invalid argument
LOCATIONS_ERROR_SERVICE_NOT_AVAILABLE	Service not available
LOCATIONS_ERROR_GPS_SETTING_OFF	GPS is not enabled
LOCATIONS_ERROR_ACCESSIBILITY_NOT_ALLOWED	The application does not have the privilege to call this method
LOCATIONS_ERROR_NOT_SUPPORTED	Not supported

Precondition:

The location service state must be LOCATIONS_SERVICE_ENABLED with location_manager_start().

int location_manager_get_method	(	location_manager_h	manager,
		location_method_e *	method
	)

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:

LOCATIONS_ERROR_NONE	Successful
LOCATIONS_ERROR_INVALID_PARAMETER	Invalid parameter
LOCATIONS_ERROR_NOT_SUPPORTED	Not supported

See also:

location_manager_create()

int location_manager_get_position	(	location_manager_h	manager,
		double *	altitude,
		double *	latitude,
		double *	longitude,
		time_t *	timestamp
	)

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:

LOCATIONS_ERROR_NONE	Successful
LOCATIONS_ERROR_INVALID_PARAMETER	Invalid argument
LOCATIONS_ERROR_SERVICE_NOT_AVAILABLE	Service not available
LOCATIONS_ERROR_GPS_SETTING_OFF	GPS is not enabled
LOCATIONS_ERROR_ACCESSIBILITY_NOT_ALLOWED	The application does not have the privilege to call this method
LOCATIONS_ERROR_NOT_SUPPORTED	Not supported

Precondition:

The location service state must be LOCATIONS_SERVICE_ENABLED with location_manager_start().

int location_manager_get_velocity	(	location_manager_h	manager,
		double *	climb,
		double *	direction,
		double *	speed,
		time_t *	timestamp
	)

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:

LOCATIONS_ERROR_NONE	Successful
LOCATIONS_ERROR_INVALID_PARAMETER	Invalid argument
LOCATIONS_ERROR_SERVICE_NOT_AVAILABLE	Service not available
LOCATIONS_ERROR_GPS_SETTING_OFF	GPS is not enabled
LOCATIONS_ERROR_ACCESSIBILITY_NOT_ALLOWED	The application does not have the privilege to call this method
LOCATIONS_ERROR_NOT_SUPPORTED	Not supported

Precondition:

The location service state must be LOCATIONS_SERVICE_ENABLED with location_manager_start().

int location_manager_is_enabled_method	(	location_method_e	method,
		bool *	enable
	)

Checks whether the given location method is enabled or not on setting.

Since :

2.3

Parameters:

[in]	method	The location method to be checked
[out]	enable	The result value of checking the given location method

Returns:

0 on success, otherwise a negative error value

Return values:

LOCATIONS_ERROR_NONE	Successful
LOCATIONS_ERROR_INCORRECT_METHOD	Incorrect method
LOCATIONS_ERROR_INVALID_PARAMETER	Invalid parameter
LOCATIONS_ERROR_NOT_SUPPORTED	Not supported

See also:

location_manager_create()

location_manager_set_setting_changed_cb()

location_manager_unset_setting_changed_cb()

int location_manager_is_enabled_mock_location

(

bool *

enabled

)

Checks whether the mock location is enabled.

Since :

3.0

Parameters:

[out]

enabled

Indicates whether the mock location is enabled

Returns:

0 on success, otherwise a negative error value

Return values:

LOCATIONS_ERROR_NONE	Successful
LOCATIONS_ERROR_INVALID_PARAMETER	Invalid parameter
LOCATIONS_ERROR_NOT_SUPPORTED	Not supported

See also:

location_manager_enable_mock_location()

location_manager_set_mock_location()

location_manager_clear_mock_location()

bool location_manager_is_supported_method

(

location_method_e

method

)

Checks whether the given location method is available.

Since :

2.3

Remarks:

The specific error code can be obtained using the get_last_result() method. Error codes are described in Exception section.

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

Return values:

LOCATIONS_ERROR_NONE	Successful
LOCATIONS_ERROR_NOT_SUPPORTED	Not supported
LOCATIONS_ERROR_INCORRECT_METHOD	Incorrect method

See also:

location_manager_create()

location_manager_get_method()

int location_manager_remove_boundary	(	location_manager_h	manager,
		const location_bounds_h	bounds
	)

Deletes 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:

LOCATIONS_ERROR_NONE	Successful
LOCATIONS_ERROR_INVALID_PARAMETER	Invalid parameter
LOCATIONS_ERROR_OUT_OF_MEMORY	Out of memory
LOCATIONS_ERROR_NOT_SUPPORTED	Not supported

See also:

location_manager_add_boundary()

int location_manager_request_single_location	(	location_manager_h	manager,
		int	timeout,
		location_updated_cb	callback,
		void *	user_data
	)

Requests to update current location once.

Since :

2.3

Privilege Level:

public

Privilege:

http://tizen.org/privilege/location

Remarks:

Do not request to start the location service using the same manager handler. Calling this function invokes a location service event. When the location service is updated, location_updated_cb.

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:

LOCATIONS_ERROR_NONE	Successful
LOCATIONS_ERROR_INVALID_PARAMETER	Invalid parameter
LOCATIONS_ERROR_INCORRECT_METHOD	Incorrect method
LOCATIONS_ERROR_SERVICE_NOT_AVAILABLE	Service not available
LOCATIONS_ERROR_NETWORK_FAILED	Network failed
LOCATIONS_ERROR_GPS_SETTING_OFF	GPS is not enabled
LOCATIONS_ERROR_ACCESSIBILITY_NOT_ALLOWED	The application does not have the privilege to call this method
LOCATIONS_ERROR_NOT_SUPPORTED	Not supported

Postcondition:

It invokes location_updated_cb().

int location_manager_set_distance_based_location_changed_cb	(	location_manager_h	manager,
		location_changed_cb	callback,
		int	interval,
		double	distance,
		void *	user_data
	)

Registers a callback function to be invoked at minimum interval or minimum distance with updated position information.

Since :

2.4

Parameters:

[in]	manager	The location manager handle
[in]	callback	The callback function to register
[in]	interval	The minimum interval between position updates [1 ~ 120] (seconds)
[in]	distance	The minimum distance between position updates [1 ~ 120] (meters)
[in]	user_data	The user data to be passed to the callback function

Returns:

0 on success, otherwise a negative error value

Return values:

LOCATIONS_ERROR_NONE	Successful
LOCATIONS_ERROR_INVALID_PARAMETER	Invalid parameter
LOCATIONS_ERROR_NOT_SUPPORTED	Not supported

Postcondition:

location_changed_cb() will be invoked.

See also:

location_manager_unset_distance_based_location_changed_cb()

location_changed_cb()

int location_manager_set_fused_mode	(	location_manager_h	manager,
		location_fused_mode_e	mode
	)

Changes behavior of the location source selection in the fused location method.

Since :

4.0

Parameters:

[in]	manager	The location manager handle
[in]	mode	The fused mode.

Returns:

0 on success, otherwise a negative error value

Return values:

LOCATIONS_ERROR_NONE	Successful
LOCATIONS_ERROR_INVALID_PARAMETER	Invalid parameter
LOCATIONS_ERROR_INCORRECT_METHOD	Incorrect method
LOCATIONS_ERROR_SERVICE_NOT_AVAILABLE	The service is not available
LOCATIONS_ERROR_NOT_SUPPORTED	Not supported

See also:

location_manager_create()

int location_manager_set_location_batch_cb	(	location_manager_h	manager,
		location_batch_cb	callback,
		int	batch_interval,
		int	batch_period,
		void *	user_data
	)

Registers a callback function to be invoked when batch_period is expired.

Since :

3.0

Remarks:

The batch_period should be greater than or equal to the batch_interval. In addition, sometimes the period may not work as you intended, the maximum permissible value for batch_period is device specific.

Parameters:

[in]	manager	The location manager handle
[in]	callback	The callback function to register
[in]	batch_interval	The batch sampling interval [1 ~ 255] (seconds)
[in]	batch_period	The batch period [1 ~ 60000] (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:

LOCATIONS_ERROR_NONE	Successful
LOCATIONS_ERROR_INVALID_PARAMETER	Invalid parameter
LOCATIONS_ERROR_NOT_SUPPORTED	Not supported

Postcondition:

location_batch_cb() will be invoked.

See also:

location_manager_start_batch()

location_batch_cb()

location_manager_unset_location_batch_cb()

int location_manager_set_location_changed_cb	(	location_manager_h	manager,
		location_changed_cb	callback,
		int	interval,
		void *	user_data
	)

Registers a callback function to be invoked at defined interval with updated location information.

Since :

2.4

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:

LOCATIONS_ERROR_NONE	Successful
LOCATIONS_ERROR_INVALID_PARAMETER	Invalid parameter
LOCATIONS_ERROR_NOT_SUPPORTED	Not supported

Postcondition:

location_changed_cb() will be invoked.

See also:

location_manager_unset_location_changed_cb()

location_changed_cb()

int location_manager_set_mock_location	(	location_manager_h	manager,
		const double	latitude,
		const double	longitude,
		const double	altitude,
		const double	speed,
		const double	direction,
		const double	accuracy
	)

Sets a mock location for the given location method.

The location sets the given altitude, latitude, longitude, climb, direction, speed, level, horizontal, and vertical accuracy.

Since :

3.0

Privilege Level:

public

Privilege:

http://tizen.org/privilege/location

Parameters:

[in]	manager	The location manager handle
[in]	latitude	The current latitude [-90.0 ~ 90.0] (degrees)
[in]	longitude	The current longitude [-180.0 ~ 180.0] (degrees)
[in]	altitude	The current altitude (meters)
[in]	speed	The speed (km/h)
[in]	direction	The direction, degrees from the north [0.0 ~ 360.0]
[in]	accuracy	The horizontal accuracy (meters)

Returns:

0 on success, otherwise a negative error value

Return values:

LOCATIONS_ERROR_NONE	Successful
LOCATIONS_ERROR_INVALID_PARAMETER	Invalid argument
LOCATIONS_ERROR_SERVICE_NOT_AVAILABLE	Service not available
LOCATIONS_ERROR_SETTING_OFF	MOCK location is not enabled
LOCATIONS_ERROR_ACCESSIBILITY_NOT_ALLOWED	The application does not have the privilege to call this method
LOCATIONS_ERROR_NOT_SUPPORTED	Not supported

See also:

location_manager_create()

location_manager_is_enabled_mock_location()

location_manager_enable_mock_location()

location_manager_clear_mock_location()

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.

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:

LOCATIONS_ERROR_NONE	Successful
LOCATIONS_ERROR_INVALID_PARAMETER	Invalid parameter
LOCATIONS_ERROR_NOT_SUPPORTED	Not supported

Postcondition:

location_position_updated_cb() will be invoked.

See also:

location_manager_unset_position_updated_cb()

location_position_updated_cb()

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.

Since :

2.3

Parameters:

[in]	manager	The location manager handle
[in]	callback	The callback function to register
[in]	user_data	The user data to be passed to the callback function

Returns:

0 on success, otherwise a negative error value

Return values:

LOCATIONS_ERROR_NONE	Successful
LOCATIONS_ERROR_INVALID_PARAMETER	Invalid parameter
LOCATIONS_ERROR_NOT_SUPPORTED	Not supported

Postcondition:

location_service_state_changed_cb() will be invoked.

See also:

location_manager_unset_service_state_changed_cb()

location_service_state_changed_cb()

location_manager_start()

location_manager_stop()

location_service_state_e

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.

Since :

2.3

Parameters:

[in]	method	The method to observe
[in]	callback	The callback function to register
[in]	user_data	The user data to be passed to the callback function

Returns:

0 on success, otherwise a negative error value

Return values:

LOCATIONS_ERROR_NONE	Successful
LOCATIONS_ERROR_INVALID_PARAMETER	Invalid parameter
LOCATIONS_ERROR_INCORRECT_METHOD	Incorrect method
LOCATIONS_ERROR_NOT_SUPPORTED	Not supported

Postcondition:

location_setting_changed_cb() will be invoked.

See also:

location_manager_unset_setting_changed_cb()

location_setting_changed_cb()

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.

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:

LOCATIONS_ERROR_NONE	Successful
LOCATIONS_ERROR_INVALID_PARAMETER	Invalid parameter
LOCATIONS_ERROR_NOT_SUPPORTED	Not supported

Postcondition:

location_velocity_updated_cb() will be invoked.

See also:

location_manager_unset_velocity_updated_cb()

location_velocity_updated_cb()

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.

Since :

2.3

Parameters:

[in]	manager	The location manager handle
[in]	callback	The callback function to register
[in]	user_data	The user data to be passed to the callback function

Returns:

0 on success, otherwise a negative error value

Return values:

LOCATIONS_ERROR_NONE	Successful
LOCATIONS_ERROR_INVALID_PARAMETER	Invalid parameter
LOCATIONS_ERROR_NOT_SUPPORTED	Not supported

Precondition:

location_manager_add_boundary() is called before.

Postcondition:

location_zone_changed_cb() will be invoked.

See also:

location_manager_unset_zone_changed_cb()

location_zone_changed_cb()

int location_manager_start

(

location_manager_h

manager

)

Starts the location service.

Since :

2.3

Privilege Level:

public

Privilege:

http://tizen.org/privilege/location

Remarks:

There is no limit on number of location managers for which this function was called.

Calling this function invokes a location service event. When the location service is enabled, the service state change callback (set using location_manager_set_service_state_changed_cb()) notifies the user with LOCATIONS_SERVICE_ENABLED as the first argument, and the service starts.

The started service is a requirement for calling these functions: location_manager_get_position(), location_manager_get_velocity(), location_manager_get_accuracy(), gps_status_get_nmea(), gps_status_get_satellite(), gps_status_foreach_satellites_in_view().

Once you stop the service using location_manager_stop(), you can no longer call the functions listed above.

Starting and stopping the service is in the scope of the given location manager only (if there is more than one manager, starting and stopping should be executed for each of them separately).

Parameters:

[in]

manager

The location manager handle

Returns:

0 on success, otherwise a negative error value

Return values:

LOCATIONS_ERROR_NONE	Successful
LOCATIONS_ERROR_INVALID_PARAMETER	Invalid parameter
LOCATIONS_ERROR_SERVICE_NOT_AVAILABLE	Service not available
LOCATIONS_ERROR_NETWORK_FAILED	Network failed
LOCATIONS_ERROR_GPS_SETTING_OFF	GPS is not enabled
LOCATIONS_ERROR_ACCESSIBILITY_NOT_ALLOWED	The application does not have the privilege to call this method
LOCATIONS_ERROR_NOT_SUPPORTED	Not supported

Postcondition:

It invokes location_position_updated_cb(), location_velocity_updated_cb(), location_zone_changed_cb(), and location_service_state_changed_cb().

See also:

location_manager_stop()

location_manager_get_position()

location_manager_get_velocity()

location_manager_get_accuracy()

location_manager_set_service_state_changed_cb()

location_manager_set_position_updated_cb()

location_position_updated_cb()

location_manager_set_velocity_updated_cb()

location_velocity_updated_cb()

location_manager_set_zone_changed_cb()

location_zone_changed_cb()

int location_manager_start_batch

(

location_manager_h

manager

)

Starts the location batch service.

Calling this function starts location batch service, location_batch_cb() will be invoked every batch_period seconds. After that, you can obtain all locations with location_manager_foreach_location_batch().

Since :

3.0

Privilege Level:

public

Privilege:

http://tizen.org/privilege/location

Remarks:

Calling this function invokes a location service event. When the location service is enabled, the service state change callback (set using location_manager_set_service_state_changed_cb()) notifies the user with LOCATIONS_SERVICE_ENABLED as the first argument, and the service starts.

Parameters:

[in]

manager

The location manager handle

Returns:

0 on success, otherwise a negative error value

Return values:

LOCATIONS_ERROR_NONE	Successful
LOCATIONS_ERROR_INVALID_PARAMETER	Invalid parameter
LOCATIONS_ERROR_INCORRECT_METHOD	Incorrect method
LOCATIONS_ERROR_SERVICE_NOT_AVAILABLE	Service not available
LOCATIONS_ERROR_NETWORK_FAILED	Network failed
LOCATIONS_ERROR_GPS_SETTING_OFF	GPS is not enabled
LOCATIONS_ERROR_ACCESSIBILITY_NOT_ALLOWED	The application does not have the privilege to call this method
LOCATIONS_ERROR_NOT_SUPPORTED	Not supported

Precondition:

location_manager_set_location_batch_cb()

See also:

location_manager_set_service_state_changed_cb()

location_service_state_changed_cb()

location_manager_foreach_location_batch()

location_manager_stop_batch()

int location_manager_stop

(

location_manager_h

manager

)

Stops the location service.

Since :

2.3

Remarks:

This function initiates the process of stopping the service. When the process is finished, callback set using location_manager_set_service_state_changed_cb() will be called, with LOCATIONS_SERVICE_DISABLED as first argument. When that happens, the service is stopped and the user is notified.

You can stop and start the location manager as needed.

Parameters:

[in]

manager

The location manager handle

Returns:

0 on success, otherwise a negative error value

Return values:

LOCATIONS_ERROR_NONE	Successful
LOCATIONS_ERROR_INVALID_PARAMETER	Invalid parameter
LOCATIONS_ERROR_SERVICE_NOT_AVAILABLE	Service not available
LOCATIONS_ERROR_NETWORK_FAILED	Network failed
LOCATIONS_ERROR_NOT_SUPPORTED	Not supported

See also:

location_manager_start()

location_manager_set_service_state_changed_cb()

location_service_state_changed_cb()

int location_manager_stop_batch

(

location_manager_h

manager

)

Stops the location batch service.

Since :

3.0

Remarks:

This function initiates the process of stopping the service. When the process is finished, callback set using location_manager_set_service_state_changed_cb() will be called, with LOCATIONS_SERVICE_DISABLED as the first argument.

Parameters:

[in]

manager

The location manager handle

Returns:

0 on success, otherwise a negative error value

Return values:

LOCATIONS_ERROR_NONE	Successful
LOCATIONS_ERROR_INVALID_PARAMETER	Invalid parameter
LOCATIONS_ERROR_SERVICE_NOT_AVAILABLE	Service not available
LOCATIONS_ERROR_NETWORK_FAILED	Network failed
LOCATIONS_ERROR_NOT_SUPPORTED	Not supported

See also:

location_manager_start_batch()

location_manager_set_service_state_changed_cb()

location_service_state_changed_cb()

int location_manager_unset_distance_based_location_changed_cb

(

location_manager_h

manager

)

Unregisters the callback function.

Since :

2.4

Parameters:

[in]

manager

The location manager handle

Returns:

0 on success, otherwise a negative error value

Return values:

LOCATIONS_ERROR_NONE	Successful
LOCATIONS_ERROR_INVALID_PARAMETER	Invalid parameter
LOCATIONS_ERROR_NOT_SUPPORTED	Not supported

See also:

location_manager_set_distance_based_location_changed_cb()

int location_manager_unset_location_batch_cb

(

location_manager_h

manager

)

Unregisters the callback function.

Since :

3.0

Parameters:

[in]

manager

The location manager handle

Returns:

0 on success, otherwise a negative error value

Return values:

LOCATIONS_ERROR_NONE	Successful
LOCATIONS_ERROR_INVALID_PARAMETER	Invalid parameter
LOCATIONS_ERROR_NOT_SUPPORTED	Not supported

See also:

location_manager_set_location_batch_cb()

int location_manager_unset_location_changed_cb

(

location_manager_h

manager

)

Unregisters the callback function.

Since :

2.4

Parameters:

[in]

manager

The location manager handle

Returns:

0 on success, otherwise a negative error value

Return values:

LOCATIONS_ERROR_NONE	Successful
LOCATIONS_ERROR_INVALID_PARAMETER	Invalid parameter
LOCATIONS_ERROR_NOT_SUPPORTED	Not supported

See also:

location_manager_set_location_changed_cb()

int location_manager_unset_position_updated_cb

(

location_manager_h

manager

)

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:

LOCATIONS_ERROR_NONE	Successful
LOCATIONS_ERROR_INVALID_PARAMETER	Invalid parameter
LOCATIONS_ERROR_NOT_SUPPORTED	Not supported

See also:

location_manager_set_position_updated_cb()

int location_manager_unset_service_state_changed_cb

(

location_manager_h

manager

)

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:

LOCATIONS_ERROR_NONE	Successful
LOCATIONS_ERROR_INVALID_PARAMETER	Invalid parameter
LOCATIONS_ERROR_NOT_SUPPORTED	Not supported

See also:

location_manager_set_service_state_changed_cb()

int location_manager_unset_setting_changed_cb

(

location_method_e

method

)

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:

LOCATIONS_ERROR_NONE	Successful
LOCATIONS_ERROR_INVALID_PARAMETER	Invalid parameter
LOCATIONS_ERROR_INCORRECT_METHOD	Incorrect method
LOCATIONS_ERROR_NOT_SUPPORTED	Not supported

See also:

location_manager_set_setting_changed_cb()

int location_manager_unset_velocity_updated_cb

(

location_manager_h

manager

)

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:

LOCATIONS_ERROR_NONE	Successful
LOCATIONS_ERROR_INVALID_PARAMETER	Invalid parameter
LOCATIONS_ERROR_NOT_SUPPORTED	Not supported

See also:

location_manager_set_velocity_updated_cb()

int location_manager_unset_zone_changed_cb

(

location_manager_h

manager

)

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:

LOCATIONS_ERROR_NONE	Successful
LOCATIONS_ERROR_INVALID_PARAMETER	Invalid parameter
LOCATIONS_ERROR_NOT_SUPPORTED	Not supported

See also:

location_manager_set_zone_changed_cb()