Positioning technology module selection criteria

This document describes how module selection criteria are used by the location framework to select a module when a client application makes a request for location information. See How to use module selection criteria for an example of how to use module selection criteria.

Positioning technology modules explains positioning module concepts.

The class TPositionCriteria is used by applications to define module selection criteria as shown in figure 1. The criteria classes are defined in LbsCriteria.h. Module selection criteria consists of:

1. The capabilities required of a module, for example the ability to provide speed or altitude data. Capabilities are defined by the TPositionModuleInfo class.

2. The quality of position required from a module, for example a required horizontal accuracy to within 100 metres and a time to obtain a position of not greater than 30 seconds. Quality of position is defined by the TPositionQuality class.

3. A relative ranking or ordering of the different quality of position parameters, for example cost may be more important than accuracy. Class TPositionSelectionOrder defines the relative importance of the different quality values specified in TPositionQuality. The location framework uses ordering to choose between candidate modules that could satisfy a client application's module selection criteria.

An application uses the method RPositioner::Open() to open a subsession with the location server. There are three overloaded Open() methods that an application can use to open the subsession, one of which allows a TPositionCriteria object to be passed to the location server. If an application passes a TPositionCriteria object in RPositioner::Open(), the location framework:

• Chooses the positioning module with the capabilities that best match those specified in TPositionCriteriaBase::RequiredCapabilities(). The chosen module is used to obtain location updates for location requests made on the open client-server subsession.

• Uses the position accuracy and timeout values specified in TPositionCriteriaBase::TPositionQuality() when the client makes RPositioner::NotifyPositionUpdate() location requests.

Default selection criteria

A client application does not have to supply module selection criteria when it calls RPositioner::Open(). If no criteria are specified then a set of default criteria are used in which horizontal position (latitude and longitude) is the only required module capability.

A standard ordering priority is used in module selection. The priority ranks accuracy first followed by least cost.

When a subsession is opened with a module selection criteria object, the LBS framework compares the property values of the passed criteria object with the property values of all the available positioning modules.

There are three stages to this comparison process:

1. Comparison of module capabilities

   The TPositionCriteria object holds the module capabilities that the application requires, for example the ability to get altitude or speed information. Every module is described by a TPositionModuleInfo object that defines its capabilities. Only those modules that have all of the required capabilities specified in the criteria provided by the client application are considered as candidates to be used to obtain position data.

2. Comparison of position quality

   The TPositionQuality object holds the position quality values that the application requires, for example horizontal accuracy within 100 metres. Every module has a TPositionQuality object that defines its position quality. Only those modules that can provide position data with all the quality values specified by the application are considered as candidates to be used to obtain position data.

3. Ordering of remaining candidate modules

   In some cases, stages 1 and 2 will leave only one module that meets all the criteria and the module selection process is complete.

   In cases where there is more than one candidate module, the TPositionSelectionOrder object that the client application passed within the criteria object is used by the LBS framework to choose the best module from the remaining candidates.

   TPositionSelectionOrder allows an application to assign importance to its specified quality criteria parameters. The importance of a parameter is defined by a TPositionSelectionOrder::TOrder value which defines a qualitative range of importance from 'very high' to 'unimportant'.

   The following describes how the ordering process works:

   Suppose that having completed steps 1 and 2 above that there are two candidate modules remaining. Suppose that the client application created an ordering object and called TPositionSelectionOrder::SetOrderHorizontalAccuracy() passing a value of TPositionSelectionOrder::EOrderHigh and TPositionSelectionOrder::SetOrderCostIndicator() passing a value of TPositionSelectionOrder::EOrderMedium.

   In this case accuracy has the highest priority, so the module that can provide the most accurate position fix would be selected.

   If both modules could supply a fix with the same degree of accuracy, then the cost of obtaining the fix would be compared. The module with the lowest cost estimate would be selected. If other ordering parameters were set, this process would continue until the lowest priority criteria were compared. Comparisons are only performed for ordering parameters set by the client application, so for example, power consumption would not be compared unless the client application had specified an ordering priority for it.

   If at the end of this process there remained more than one module that could supply the position fix, then the location framework will choose one of them.

How to use module selection criteria