Positioning Module Status
This document describes positioning technology module status, which applications access through the Location Acquisition API.
Purpose
This document describes Positioning Module status, which applications access through the Location Acquisition API.
Positioning Module status
A Positioning Module has a status which is represented by a TPositionModuleStatus object. The status describes the low-level state of a Positioning Module, such as whether it is disabled, initialising, or ready to retrieve location data, as well as its data quality status.
A change in Positioning Module status is indicated by a status event. Details of the event are held in a TPositionModuleStatusEvent object. Client applications can receive notification of status events from the location server.
Figure 1 illustrates Positioning Module status and event classes.
TPositionModuleStatus
TPositionModuleStatus describes the status of a Positioning Module. An application gets information about a Positioning Module's current status by calling RPositionServer::GetModuleStatus(). There are two status types - device status and data quality status.
Device status
Device status is the status of the hardware device utilised by a Positioning Module, such as the chipset used by an A-GPS Positioning Module.
TPositionModuleStatus::DeviceStatus() returns the device status as a TPositionModuleStatus::TDeviceStatus value. The value returned can indicate a transient device status, such as whether the hardware is disabled, initialising, or ready. It can also indicate a more serious device error state.
Data quality status
Data quality status describes the accuracy of the location data that a Positioning Module is able to provide at a point in time.
TPositionModuleStatus::DataQualityStatus() returns the data quality status as a TPositionModuleStatus::TDataQualityStatus value. This value indicates whether the quality of location data is normal (the ideal condition), partially degraded or completely degraded. Location data quality can become degraded because the mobile device has moved out of range of any base stations or is in a position where it cannot receive signals from positioning satellites. Note that loss of information quality does not indicate a device error, which would be flagged by a change in the device status.
Positioning Module status events
When a Positioning Module's status changes, a Positioning Module status event occurs.
There are three types of Positioning Module status events:
Device status events
Data quality status events
System level events. These events indicate that a Positioning Module has been added or removed in the system.
TPositionModuleStatusEvent
An object of class TPositionModuleStatusEvent has two functions:
As the object on which an application defines the types of Positioning Module status events for which it requests notification. These are set by calling TPositionModuleStatusEvent::SetRequestedEvents() passing a TPositionModuleStatusEventBase::TModuleEvent bitmask value as a parameter to define the combination of events
As the object on which the location framework sets the type of events that have occurred. These are retrieved by calling TPositionModuleStatusEvent::OccurredEvents() and checking the returned TPositionModuleStatusEventBase::TModuleEvent value.
Event notification
An application calls RPositionServer::NotifyModuleStatusEvent() to receive notification of Positioning Module status changes, passing a reference to a TPositionModuleStatusEvent object on which it has set the requested events. An application also supplies a TRequestStatus object and optionally a TPositionModuleId object if status changes from only one Positioning Module are required.
When the status of a Positioning Module changes, the client application is notified. The TPositionModuleStatusEvent object that was supplied to the location server now also contains details of the events that have occurred and these are obtained by calling TPositionModuleStatusEvent::OccurredEvents().
The Positioning Module status is obtained by calling TPositionModuleStatusEvent::GetModuleStatus() providing a TPositionModuleStatus reference as a parameter.
See How to Get Positioning Module Status Changes for an example.
Uses of Positioning Module status
Quality status events are useful for applications that need to modify their behaviour based on the quality of location information that can be received. For example, an application may need to show a message when a user moves into an area where the accuracy of location information is degraded to a lower quality than is required because of distance from a base station or inability to receive satellite signals.
Device status events and system Positioning Module events are most useful to software components that perform administrative operations, such as taking a Positioning Module online or offline. The events can be used to notify when such an administrative operation is complete.
Device status events can also be used to keep a user informed as to the status of a particular Positioning Module. For example, a phone status bar could be updated to show that GPS is active when location information is being received.