Tizen Native API  5.5
GPS Status & Satellite

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]azimuthThe azimuth of the satellite (degrees)
[in]elevationThe elevation of the satellite (meters)
[in]prnThe PRN of the satellite
[in]snrThe SNR of the satellite [dB]
[in]is_activeThe flag signaling if satellite is in use
[in]user_dataThe 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_activeThe last number of active satellites
[out]num_of_inviewThe last number of satellites in view
[out]timestampThe last timestamp (time when measurement took place or 0 if valid)
[in]user_dataThe 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

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]managerThe location manager handle
[in]callbackThe iteration callback function
[in]user_dataThe user data to be passed to the callback function
Returns:
0 on success, otherwise a negative error value
Return values:
LOCATIONS_ERROR_NONESuccessful
LOCATIONS_ERROR_INVALID_PARAMETERInvalid argument
LOCATIONS_ERROR_INCORRECT_METHODIncorrect method
LOCATIONS_ERROR_SERVICE_NOT_AVAILABLEService not available
LOCATIONS_ERROR_ACCESSIBILITY_NOT_ALLOWEDThe application does not have the privilege to call this method
LOCATIONS_ERROR_NOT_SUPPORTEDNot 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]managerThe location manager handle
[in]callbackThe iteration callback function
[in]user_dataThe user data to be passed to the callback function
Returns:
0 on success, otherwise a negative error value
Return values:
LOCATIONS_ERROR_NONESuccessful
LOCATIONS_ERROR_INVALID_PARAMETERInvalid argument
LOCATIONS_ERROR_INCORRECT_METHODIncorrect method
LOCATIONS_ERROR_SERVICE_NOT_AVAILABLEService not available
LOCATIONS_ERROR_ACCESSIBILITY_NOT_ALLOWEDThe application does not have the privilege to call this method
LOCATIONS_ERROR_NOT_SUPPORTEDNot 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]managerThe location manager handle
[out]num_of_activeThe last number of active satellites
[out]num_of_inviewThe last number of satellites in view
[out]timestampThe 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_NONESuccessful
LOCATIONS_ERROR_INVALID_PARAMETERInvalid argument
LOCATIONS_ERROR_INCORRECT_METHODIncorrect method
LOCATIONS_ERROR_SERVICE_NOT_AVAILABLEService not available
LOCATIONS_ERROR_ACCESSIBILITY_NOT_ALLOWEDThe application does not have the privilege to call this method
LOCATIONS_ERROR_NOT_SUPPORTEDNot 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]managerThe location manager handle
[out]nmeaThe NMEA data
Returns:
0 on success, otherwise a negative error value
Return values:
LOCATIONS_ERROR_NONESuccessful
LOCATIONS_ERROR_INVALID_PARAMETERInvalid argument
LOCATIONS_ERROR_SERVICE_NOT_AVAILABLEService not available
LOCATIONS_ERROR_ACCESSIBILITY_NOT_ALLOWEDThe application does not have the privilege to call this method
LOCATIONS_ERROR_NOT_SUPPORTEDNot 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]managerThe location manager handle
[out]num_of_activeThe number of active satellites
[out]num_of_inviewThe number of satellites in view
[out]timestampThe timestamp (time when measurement took place or 0 if valid)
Returns:
0 on success, otherwise a negative error value
Return values:
LOCATIONS_ERROR_NONESuccessful
LOCATIONS_ERROR_INVALID_PARAMETERInvalid argument
LOCATIONS_ERROR_SERVICE_NOT_AVAILABLEService not available
LOCATIONS_ERROR_ACCESSIBILITY_NOT_ALLOWEDThe application does not have the privilege to call this method
LOCATIONS_ERROR_NOT_SUPPORTEDNot 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]managerThe location manager handle
[in]callbackThe callback function to register
[in]intervalThe interval [1 ~ 120] (seconds)
[in]user_dataThe user data to be passed to the callback function
Returns:
0 on success, otherwise a negative error value
Return values:
LOCATIONS_ERROR_NONESuccessful
LOCATIONS_ERROR_INVALID_PARAMETERInvalid parameter
LOCATIONS_ERROR_ACCESSIBILITY_NOT_ALLOWEDThe application does not have the privilege to call this method
LOCATIONS_ERROR_NOT_SUPPORTEDNot 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()

Unregisters the callback function.

Since :
2.3.1
Parameters:
[in]managerThe location manager handle
Returns:
0 on success, otherwise a negative error value
Return values:
LOCATIONS_ERROR_NONESuccessful
LOCATIONS_ERROR_INVALID_PARAMETERInvalid parameter
LOCATIONS_ERROR_NOT_SUPPORTEDNot supported
See also:
gps_status_set_satellite_updated_cb()