![Symbian Developer Library](../../../../../a_stock/images/mainheading.gif)
![]() |
![]() |
|
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
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 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 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.
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.
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.