Location -Acquisition API Runtime Behaviour

Location -Acquisition API Runtime BehaviourThis document describes some differences in runtime behaviour that -application clients may observe depending on the Symbian platform on which -they are running. -

Purpose

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.

Types of runtime behaviour differences

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)

Accuracy of position updates

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>.

- - -

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.

- - -

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.

- - - -

Table 1. Location Acquisition API runtime behavior.

Source of position updates

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.

-Location -Acquisition API Reference -How to Get -Module Status Changes + + + + + +Location +Acquisition API Runtime BehaviourThis document describes some differences in runtime behaviour that +application clients may observe depending on the Symbian platform on which +they are running. +

Purpose

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.

Types of runtime behaviour differences

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)

Accuracy of position updates

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>.

+ + +

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.

+ + +

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.

+ + + +

Table 1. Location Acquisition API runtime behavior.

Source of position updates

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.

+Location +Acquisition API Reference +How to Get +Module Status Changes

\ No newline at end of file