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 |
Position is returned. |
Position is returned. |
Module returns incomplete position before request timeout. |
Position is not returned. |
Position is returned. |
Module returns accurate position before request timeout. |
Position is returned. |
Position is returned. |
Module returns inaccurate position before request timeout. |
If LBS is configured to return all positions: Position
is returned. Else if LBS is configured to return only accurate positions: Position
is not returned. |
If LBS is configured to return all positions: Position
is returned. Else if LBS is configured to return only accurate positions: Position
is returned. |
Timeout in Location Server. Module has not yet returned a position. |
Position containing "Not a Number" |
Position containing |
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. |
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 |
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: Else if LBS is configured to return only accurate positions: TRequestStatus
is |
The most accurate available position is returned. If LBS is configured to return all positions: Else if LBS is configured to return only accurate positions: |
Module returns an incomplete position and an error code of KPositionCalculationFutile. |
The most accurate available position is returned. TRequestStatus
is |
The most accurate available position is returned. TRequestStatus
is |
Client calls |
The last calculated position is returned. |
The last calculated position is returned. |
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.