Positioning technology modules

This document is an overview of the positioning technology module information that is available to client applications using the Location Acquisition API. A positioning technology module is a low-level software component that allows the location server to communicate with the mobile device hardware that obtains position data.

See How to use module information for an example of how to get module information using the Location Acquisition API.

In mobile phones there are typically one or two modules:

• A Network Protocol Module that the location server uses to obtain location information from the network.

• An A-GPS Module that the location server uses to obtain location information from a GPS or A-GPS chipset.

When a client application or remote party makes a request for new location information, a module must be used to service the request. There are three ways in which this module choice can be made:

• The client application chooses a particular module to use for location information requests and specifies this choice to the location server by opening a subsession using RPositioner::Open(RPositionServer &aPosServer, TPositionModuleId aModuleId). This method returns KErrNotFound if the specified module ID does not exist.

• The application specifies a set of position quality criteria to the location server by opening a server subsession using RPositioner::Open(RPositionServer &aPosServer, const TPositionCriteriaBase &aCriteria). When the application makes a location information request, the server chooses the module that best satisfies the quality criteria.

• The application does not specify a particular module and does not specify any location quality criteria when it creates a server subsession. The location server uses the default module to obtain the location information as specified by RPositionServer::GetDefaultModuleId().

The classes TPositionModuleInfo and TPositionQuality hold information about the capabilities of modules and the quality of position information that they can provide. Figure 1 illustrates these classes.

TPositionModuleInfo

TPositionModuleInfo describes a positioning module. This description includes:

• The technology type used by the module.

  A module can use positioning technology which is terminal-based (such as GPS), network based, or a combination of the two (such as A-GPS). The method TPositionModuleInfo::TechnologyType() returns this information.

• The capabilities of the module.

  Different modules have different capabilities which depend on the module technology type. Most modules have the capability to provide latitude and longitude information. Some modules can also supply altitude information, course information and satellite data. This information is returned by the method TPositionModuleInfo::Capabilities() as a bit mask of type TPositionModuleInfo::TCapabilities.

• A unique identifier returned by TPositionModule::ModuleId().

  This identifier is used to select a specific module when a client application wishes to use a specific positioning technology to obtain a location fix.

A TPositionModuleInfo object obtains a reference to its TPositionQuality object by calling TPositionModuleInfo::GetPositionQuality().

TPositionQuality

TPositionQuality describes the quality of information that a positioning module can provide. The quality describes the accuracy of information, the time to obtain a location fix, the cost of obtaining the fix and power consumption:

• TPositionQuality::HorizontalAccuracy() and TPositionQuality::VerticalAccuracy() return location accuracy information.

• TPositionQuality::TimeToFirstFix() and TPositionQuality::TimeToNextFix() return a typical time to get a location fix as a TTimeIntervalMicroSeconds value.

• TPositionQuality::CostIndicator() returns a cost for using the module to get location information. The value returned is an estimate, not a precise cost value and is of type TPositionQuality::TCostIndicator. The cost estimate helps the location server to make a choice of the module to use to get a location fix when a specific module is not chosen by a client application.

• TPositionQuality::PowerConsumption() returns an estimate of power consumption for using a module. This estimate is of type TPositionQuality::TPowerConsumption and as with cost, it helps the location server make a choice of module to use to get a location fix.

TPositionQuality has corresponding setter methods for these quality properties that allow an application to set module quality selection criteria.

How to use module information