Positioning technology module status

This document describes positioning technology module status, which applications access through the Location Acquisition API.

A module has a status which is represented by a TPositionModuleStatus object. The status describes the low-level state of a module, such as whether it is disabled, initialising, or ready to retrieve location data, as well as its data quality status.

A change in 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 module status and event classes.

TPositionModuleStatus

TPositionModuleStatus describes the status of a module. An application gets information about a 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 module, such as the chipset used by an A-GPS 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 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.

When a module's status changes, a module status event occurs.

There are three types of module status events:

• Device status events

• Data quality status events

• System level events. These events indicate that a 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 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 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 module are required.

When the status of a 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 module status is obtained by calling TPositionModuleStatusEvent::GetModuleStatus() providing a TPositionModuleStatus reference as a parameter.

See How to get module status changes for an example.

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 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 technology module. For example, a phone status bar could be updated to show that GPS is active when location information is being received.

Positioning technology modules