The GPS Status & Satellite API provides functions to acquire information about GPS satellites in range and in use.

Required Header

#include <locations.h>

Overview

The GPS Status & Satellite API provides functions to acquire data on satellites that are currently visible to the device. Information like azimuth and elevation of each satellite is available, along with number of satellites in range and in use.

System Info note:: All of the functions require a started location manager with the LOCATIONS_METHOD_GPS method set. See the Location Manager API for details. The gps_status_get_nmea() function gets NMEA data from the GPS system. NMEA 0183 (or NMEA for short) is a combined electrical and data specification for communication between electronic devices. NMEA standard uses a simple ASCII, serial communications protocol that defines how data is transmitted in a "sentence" from one "talker" to multiple "listeners" at a time. For more details, see NMEA_0183. The gps_status_get_satellite() method returns a count of satellites in view. The gps_status_foreach_satellites_in_view() method is an iterator which will invoke a callback function for each satellite in view. The gps_status_get_satellite() method returns a count of satellites in use.

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.gps.satellite

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
int	gps_status_get_nmea (location_manager_h manager, char **nmea)
	Gets the GPS NMEA data.
int	gps_status_get_satellite (location_manager_h manager, int num_of_active, int num_of_inview, time_t *timestamp)
	Gets the information of satellites.
int	gps_status_set_satellite_updated_cb (location_manager_h manager, gps_status_satellite_updated_cb callback, int interval, void *user_data)
	Registers a callback function to be invoked at defined interval with updated satellite information.
int	gps_status_unset_satellite_updated_cb (location_manager_h manager)
	Unregisters the callback function.
int	gps_status_foreach_satellites_in_view (location_manager_h manager, gps_status_get_satellites_cb callback, void *user_data)
	Invokes the callback function for each satellite.
int	gps_status_get_last_satellite (location_manager_h manager, int num_of_active, int num_of_inview, time_t *timestamp)
	Gets the last information of satellites.
int	gps_status_foreach_last_satellites_in_view (location_manager_h manager, gps_status_get_satellites_cb callback, void *user_data)
	Invokes the callback function for each last satellite which is recorded.
Typedefs
typedef bool(*	gps_status_get_satellites_cb )(unsigned int azimuth, unsigned int elevation, unsigned int prn, int snr, bool is_active, void *user_data)
	Called once for each satellite in range.
typedef void(*	gps_status_satellite_updated_cb )(int num_of_active, int num_of_inview, time_t timestamp, void *user_data)
	Called at defined interval with updated satellite information.

Typedef Documentation

typedef bool(* gps_status_get_satellites_cb)(unsigned int azimuth, unsigned int elevation, unsigned int prn, int snr, bool is_active, void *user_data)

Called once for each satellite in range.

Since :: 2.3.1

Parameters:

[in]	azimuth	The azimuth of the satellite (degrees)
[in]	elevation	The elevation of the satellite (meters)
[in]	prn	The PRN of the satellite
[in]	snr	The SNR of the satellite [dB]
[in]	is_active	The flag signaling if satellite is in use
[in]	user_data	The user data passed from the foreach function

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

Precondition:: gps_status_foreach_satellites_in_view() will invoke this callback.; gps_status_foreach_last_satellites_in_view() will invoke this callback.

See also:: gps_status_foreach_satellites_in_view()

typedef void(* gps_status_satellite_updated_cb)(int num_of_active, int num_of_inview, time_t timestamp, void *user_data)

Called at defined interval with updated satellite information.

Since :: 2.3.1

Parameters:

[out]	num_of_active	The last number of active satellites
[out]	num_of_inview	The last number of satellites in view
[out]	timestamp	The last 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()

Function Documentation

int gps_status_foreach_last_satellites_in_view	(	location_manager_h	manager,
		gps_status_get_satellites_cb	callback,
		void *	user_data
	)

Invokes the callback function for each last satellite which is recorded.

Since :: 2.3.1

Privilege Level:: public

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

Remarks:: This function is valid only for location managers with the LOCATIONS_METHOD_GPS method.

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 argument
LOCATIONS_ERROR_INCORRECT_METHOD	Incorrect method
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_NOT_SUPPORTED	Not supported

Precondition:: The location service state must be LOCATIONS_SERVICE_ENABLED with location_manager_start().; The gps_status_satellite_updated_cb must be set with gps_status_set_satellite_updated_cb().

Postcondition:: It invokes gps_status_get_satellites_cb().

See also:: gps_status_get_last_satellite(); gps_status_get_satellites_cb()

int gps_status_foreach_satellites_in_view	(	location_manager_h	manager,
		gps_status_get_satellites_cb	callback,
		void *	user_data
	)

Invokes the callback function for each satellite.

Since :: 2.3.1

Privilege Level:: public

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

Remarks:: This function is valid only for location managers with the LOCATIONS_METHOD_GPS method.

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 argument
LOCATIONS_ERROR_INCORRECT_METHOD	Incorrect method
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_NOT_SUPPORTED	Not supported

Precondition:: The location service state must be LOCATIONS_SERVICE_ENABLED with location_manager_start().; The gps_status_satellite_updated_cb must be set with gps_status_set_satellite_updated_cb().

Postcondition:: It invokes gps_status_get_satellites_cb().

See also:: gps_status_get_satellite(); gps_status_get_satellites_cb()

int gps_status_get_last_satellite	(	location_manager_h	manager,
		int *	num_of_active,
		int *	num_of_inview,
		time_t *	timestamp
	)

Gets the last information of satellites.

Since :: 2.3.1

Privilege Level:: public

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

Remarks:: This call is valid only for location managers with LOCATIONS_METHOD_GPS method.

Parameters:

[in]	manager	The location manager handle
[out]	num_of_active	The last number of active satellites
[out]	num_of_inview	The last number of satellites in view
[out]	timestamp	The last timestamp (time when last 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_INCORRECT_METHOD	Incorrect method
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_NOT_SUPPORTED	Not supported

Precondition:: The location service state must be LOCATIONS_SERVICE_ENABLED with location_manager_start().; The gps_status_satellite_updated_cb must be set with gps_status_set_satellite_updated_cb().

See also:: gps_status_foreach_satellites_in_view()

int gps_status_get_nmea	(	location_manager_h	manager,
		char **	nmea
	)

Gets the GPS NMEA data.

Since :: 2.3.1

Remarks:: This call is valid only for location managers with LOCATIONS_METHOD_GPS method. You must release nmea using free().

Parameters:

[in]	manager	The location manager handle
[out]	nmea	The NMEA data

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_NOT_SUPPORTED	Not supported

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

See also:: location_manager_start()

int gps_status_get_satellite	(	location_manager_h	manager,
		int *	num_of_active,
		int *	num_of_inview,
		time_t *	timestamp
	)

Gets the information of satellites.

Since :: 2.3.1

Privilege Level:: public

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

Remarks:: This call is valid only for location managers with LOCATIONS_METHOD_GPS method.

Parameters:

[in]	manager	The location manager handle
[out]	num_of_active	The number of active satellites
[out]	num_of_inview	The number of satellites in view
[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_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().; The gps_status_satellite_updated_cb must be set with gps_status_set_satellite_updated_cb().

See also:: gps_status_foreach_satellites_in_view()

int gps_status_set_satellite_updated_cb	(	location_manager_h	manager,
		gps_status_satellite_updated_cb	callback,
		int	interval,
		void *	user_data
	)

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

Since :: 2.3.1

Privilege Level:: public

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

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_ACCESSIBILITY_NOT_ALLOWED	The application does not have the privilege to call this method
LOCATIONS_ERROR_NOT_SUPPORTED	Not supported

Postcondition:: gps_status_satellite_updated_cb() will be invoked.

See also:: gps_status_unset_satellite_updated_cb(); gps_status_satellite_updated_cb(); gps_status_get_satellite(); gps_status_foreach_satellites_in_view(); gps_status_get_last_satellite(); gps_status_foreach_last_satellites_in_view()

int gps_status_unset_satellite_updated_cb ( location_manager_h manager )

Unregisters the callback function.

Since :: 2.3.1

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

Required Header

Overview

Related Features

Functions

Typedefs

Typedef Documentation

Function Documentation