This document describes some differences in runtime behaviour that application clients may observe depending on the Symbian platform on which they are running.
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 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 behavior that a client application can expect depending on the Symbian 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 behavior.
This section describes differences in the source of the position updates that a client application receives depending on the Symbian 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.