Tizen Native API
7.0
|
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
- 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.
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
- 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().
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
- 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().
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
- 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().
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
- 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().
int gps_status_get_nmea | ( | location_manager_h | manager, |
char ** | nmea | ||
) |
Gets the GPS NMEA data.
- Since :
- 2.3
- 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
- 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().
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
- 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.
int gps_status_unset_satellite_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