Functions to determine the current geolocation of the device.
This file defines the geolocation service, which provides functions for reading the device's geolocation. To read the geolocation data, the application must have the read_geolocation capability. To grant an application the read_geolocation capability, the bar-descriptor.xml file in the application's project must contain the line "<action>read_geolocation</action>".
Some of these geolocation functions are designed to return boolean values that indicate whether their associated attributes are valid. For example, geolocation_event_is_altitude_valid() indicates whether the altitude from a GEOLOCATION_INFO event is valid.
In this context, a valid attribute means that the value of the attribute was included in the last update from the geolocation system. For example, if the device cannot obtain a GPS fix, but has Wi-Fi connectivity, the geolocation system will report latitude, longitude, and accuracy. The system will not provide values for any other attributes (such as altitude, heading, and so on), and these attributes are marked as not valid. This means that the validity functions for these attributes will return false.
Subsequently, if the device obtains a GPS fix, the geolocation system will report values for all attributes, and all attributes are marked as valid. This means that the validity functions for these attributes will return true. If the GPS fix is lost, the attributes other than latitude, longitude, and accuracy are marked as not valid again.