Location Acquisition API runtime behaviour in The Location Acquisition API

This document describes some differences in runtime behaviour that a Location Acquisition API client may observe. The exact behaviour of the API depends on the configuration of the LBS subsystem in the Symbian OS based platform and on the positioning technologies that are available.

There are two main types of runtime behaviour differences:

The accuracy of position updates returned to API clients
The source of position updates (the positioning module from which the updates may originate)

This section describes the behaviour that a client application can expect depending on the Symbian OS based platform on which it runs.

A client application may receive a location update whenever a position is available. The current latitude and longitude have been determined but their accuracy may not meet the client’s expectations. A timeout of the client's location request will only occur when it is not possible to calculate a position (irrespective of its quality).

Some platforms may be configured to return a position update only if it meets the required accuracy. A call to RPositioner::NotifyPositionUpdate() completes only when the Location Server has a position fix that meets the specified quality criteria. A client may set its accuracy requirements by passing a TPositionCriteria object in RPositioner::Open(). If no criteria are specified then default quality criteria are used to filter position updates returned to the client.

It is recommended that applications are designed to be aware that they may receive positions that do not meet their expected accuracy before the timeout period expires. If accuracy is critical to a client application it should check the accuracy values TPosition::HorizontalAccuracy() and TPosition::VerticalAccuracy() of the returned TPosition object. This is advised as the TRequestStatus return parameter may not indicate position quality loss (it may be set to KErrNone and not to KPositionQualityLoss).

Table 1 shows the position updates and TRequestStatus values that are returned by the Location Acquisition API when a client calls RPositioner::NotifyPositionUpdate().

Event	API response to client (partial updates OFF)	API response to client (partial updates ON)
Module returns `<error code>` before request timeout.	Position is returned. `TRequestStatus` is `<error code>`.	Position is returned. `TRequestStatus` is `<error code>`.
Module returns incomplete position before request timeout.	Position is not returned. `NotifyPositionUpdate()` does not complete.	Position is returned. `TRequestStatus` is `KPositionPartialUpdate`.
Module returns accurate position before request timeout.	Position is returned. `TRequestStatus` is `KErrNone`.	Position is returned. `TRequestStatus` is `KErrNone`.
Module returns inaccurate position before request timeout.	If LBS is configured to return all positions: Position is returned. `TRequestStatus` is `KErrNone`. Else if LBS is configured to return only accurate positions: Position is not returned. `NotifyPositionUpdate()` does not complete.	If LBS is configured to return all positions: Position is returned. `TRequestStatus` is `KErrNone` Else if LBS is configured to return only accurate positions: Position is returned. `TRequestStatus` is `KPositionPartialUpdate`.
Timeout in Location Server. Module has not yet returned a position.	Position containing "Not a Number" `(NaN)` values is returned. `TRequestStatus` is `KErrTimedOut`.	Position containing `NaN` values is returned. `TRequestStatus` is `KErrTimedOut`.
Timeout in Location Server. Module has previously returned an inaccurate position.	If LBS is configured to return all positions: This can't happen. Inaccurate position would have been returned to client. Else if LBS is configured to return only accurate positions: Inaccurate position is returned. `TRequestStatus` is `KPositionQualityLoss`.	This can't happen. Inaccurate position would have been returned before the timeout.
Timeout in Location Server. Module has previously returned an incomplete position.	Incomplete position is returned (contains some `NaN` values). `TRequestStatus` is `KPositionQualityLoss`.	This can't happen. The incomplete position would have been returned before the timeout.
Module returns an accurate or an inaccurate position and an error code of `KPositionCalculationFutile`.	The most accurate available position is returned. If LBS is configured to return all positions: `TRequestStatus` is `KErrNone`. Else if LBS is configured to return only accurate positions: TRequestStatus is `KPositionQualityLoss` if position is inaccurate.	The most accurate available position is returned. If LBS is configured to return all positions: `TRequestStatus` is `KErrNone`. Else if LBS is configured to return only accurate positions: `TRequestStatus` is `KPositionQualityLoss` if position is inaccurate.
Module returns an incomplete position and an error code of `KPositionCalculationFutile`.	The most accurate available position is returned. TRequestStatus is `KPositionQualityLoss`.	The most accurate available position is returned. TRequestStatus is `KPositionPartialUpdate`.
Client calls `RPositioner::CompleteRequest()`.	The last calculated position is returned. `TRequestStatus` is `KPositionEarlyComplete`.	The last calculated position is returned. `TRequestStatus` is `KPositionEarlyComplete`.

Table 1. Location Acquisition API runtime behaviour.

This section describes differences in the source of the position updates that a client application receives depending on the Symbian OS based platform on which it runs.

On platforms with more than one positioning module, a position may be obtained by the Location Server from more than one module (for example, a position may be returned from GPS hardware or from the network). Whether a position is returned to the Location Acquisition API client depends on which RPositioner::Open() method was used to open the client/server subsession.

On some platforms, when a client/server subsession is opened using RPositioner::Open(RPositionServer& aPosServer, TPositionModuleId aModuleId) only position updates from the specified module are returned to the client. Opening a subsession using other versions of RPositioner::Open() can return position updates from other positioning modules.

On some platforms LBS may be configured to return position updates from any positioning module when any version of RPositioner::Open() is used.

How to get location information

Location Acquisition API runtime behaviour

Purpose

Types of runtime behaviour differences

Accuracy of position updates

Source of position updates

See also