<?xml version="1.0" encoding="utf-8"?>

<!-- Copyright (c) 2007-2010 Nokia Corporation and/or its subsidiary(-ies) All rights reserved. -->

<!-- This component and the accompanying materials are made available under the terms of the License 

"Eclipse Public License v1.0" which accompanies this distribution, 

and is available at the URL "http://www.eclipse.org/legal/epl-v10.html". -->

<!-- Initial Contributors:

    Nokia Corporation - initial contribution.

Contributors: 

-->

<!DOCTYPE concept

  PUBLIC "-//OASIS//DTD DITA Concept//EN" "concept.dtd">

<concept id="GUID-4E56E531-5757-5740-9C7D-705D427FA9D5" xml:lang="en"><title>Location

Acquisition API Runtime Behaviour</title><shortdesc>This document describes some differences in runtime behaviour that

application clients may observe depending on the Symbian platform on which

they are running. </shortdesc><prolog><metadata><keywords/></metadata></prolog><conbody>

<section><title>Purpose</title> <p>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. </p> </section>

<section><title>Types of runtime behaviour differences</title> <p>There are

two main types of runtime behaviour differences: </p> <ul>

<li id="GUID-8B64686F-3159-52F5-A576-30C3B5428E6C"><p>The <xref href="GUID-4E56E531-5757-5740-9C7D-705D427FA9D5.dita#GUID-4E56E531-5757-5740-9C7D-705D427FA9D5/GUID-95EE0194-408E-5366-9273-8F72682E05F2">accuracy of position updates</xref> returned to API clients </p> </li>

<li id="GUID-08F51FA9-4AC9-5B0D-A53C-729828441D5E"><p>The <xref href="GUID-4E56E531-5757-5740-9C7D-705D427FA9D5.dita#GUID-4E56E531-5757-5740-9C7D-705D427FA9D5/GUID-2DF0D6FF-BB17-56B9-B19F-C0F33C6F0F15">source of position updates</xref> (the positioning module from which the

updates may originate) </p> </li>

</ul> <p id="GUID-95EE0194-408E-5366-9273-8F72682E05F2"><b>Accuracy of position updates</b> </p> <p>This

section describes the behavior that a client application can expect depending

on the Symbian platform on which it runs. </p> <p>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). </p> <p>Some

platforms may be configured to return a position update only if it meets the

required accuracy. A call to <xref href="GUID-1EAEB7EF-0AC7-37C7-B35F-C9B780FFC575.dita#GUID-1EAEB7EF-0AC7-37C7-B35F-C9B780FFC575/GUID-321F6046-3551-3ACE-B0A3-26D51FAEB477"><apiname>RPositioner::NotifyPositionUpdate()</apiname></xref> 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 <xref href="GUID-483AE6F4-5DEB-312D-ADDA-FC5AA932DE3D.dita"><apiname>TPositionCriteria</apiname></xref> object

in <xref href="GUID-1EAEB7EF-0AC7-37C7-B35F-C9B780FFC575.dita#GUID-1EAEB7EF-0AC7-37C7-B35F-C9B780FFC575/GUID-AF3D9B5F-8025-3AFF-A101-82025520EBD6"><apiname>RPositioner::Open()</apiname></xref>. If no criteria are specified then

default quality criteria are used to filter position updates returned to the

client. </p> <p>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 <xref href="GUID-AB9F288E-86C6-327A-9E53-2EA746416038.dita#GUID-AB9F288E-86C6-327A-9E53-2EA746416038/GUID-187C862D-500F-3095-8F03-9EF4E4CEF80F"><apiname>TPosition::HorizontalAccuracy()</apiname></xref> and <xref href="GUID-AB9F288E-86C6-327A-9E53-2EA746416038.dita#GUID-AB9F288E-86C6-327A-9E53-2EA746416038/GUID-742043CB-40B1-3BA1-A879-CA2F401C56C3"><apiname>TPosition::VerticalAccuracy()</apiname></xref> of

the returned <xref href="GUID-AB9F288E-86C6-327A-9E53-2EA746416038.dita"><apiname>TPosition</apiname></xref> object. This is advised as the <codeph>TRequestStatus</codeph> return

parameter may not indicate position quality loss (it may be set to <codeph>KErrNone</codeph> and

not to <codeph>KPositionQualityLoss</codeph>). </p> <p>Table 1 shows the position

updates and <codeph>TRequestStatus</codeph> values that are returned by the

Location Acquisition API when a client calls <xref href="GUID-1EAEB7EF-0AC7-37C7-B35F-C9B780FFC575.dita#GUID-1EAEB7EF-0AC7-37C7-B35F-C9B780FFC575/GUID-321F6046-3551-3ACE-B0A3-26D51FAEB477"><apiname>RPositioner::NotifyPositionUpdate()</apiname></xref>. </p> <table id="GUID-EEE1C9B5-A81C-589D-9636-79E900415F4F">

<tgroup cols="3"><colspec colname="col0"/><colspec colname="col1"/><colspec colname="col2"/>

<thead>

<row>

<entry>Event</entry>

<entry> API response to client (partial updates OFF)</entry>

<entry>API response to client (partial updates ON)</entry>

</row>

</thead>

<tbody>

<row>

<entry><p>Module returns <codeph>&lt;error code&gt;</codeph> before request timeout. </p> </entry>

<entry><p>Position is returned. <codeph>TRequestStatus</codeph> is <codeph>&lt;error

code&gt;</codeph>. </p> </entry>

<entry><p>Position is returned. <codeph>TRequestStatus</codeph> is <codeph>&lt;error

code&gt;</codeph>. </p> </entry>

</row>

<row>

<entry><p>Module returns incomplete position before request timeout. </p> </entry>

<entry><p>Position is not returned. <codeph>NotifyPositionUpdate()</codeph> does

not complete. </p> </entry>

<entry><p>Position is returned. <codeph>TRequestStatus</codeph> is <codeph>KPositionPartialUpdate</codeph>. </p> </entry>

</row>

<row>

<entry><p>Module returns accurate position before request timeout. </p> </entry>

<entry><p>Position is returned. <codeph>TRequestStatus</codeph> is <codeph>KErrNone</codeph>. </p> </entry>

<entry><p>Position is returned. <codeph>TRequestStatus</codeph> is <codeph>KErrNone</codeph>. </p> </entry>

</row>

<row>

<entry><p>Module returns inaccurate position before request timeout. </p> </entry>

<entry><p> <b>If LBS is configured to return all positions:</b>  </p> <p>Position

is returned. <codeph>TRequestStatus</codeph> is <codeph>KErrNone</codeph>. </p> <p> <b>Else

if LBS is configured to return only accurate positions:</b>  </p> <p>Position

is not returned. <codeph>NotifyPositionUpdate()</codeph> does not complete. </p> </entry>

<entry><p> <b>If LBS is configured to return all positions:</b>  </p> <p>Position

is returned. <codeph>TRequestStatus</codeph> is <codeph>KErrNone</codeph>  </p> <p> <b>Else

if LBS is configured to return only accurate positions:</b>  </p> <p>Position

is returned. <codeph>TRequestStatus</codeph> is <codeph>KPositionPartialUpdate</codeph>. </p> </entry>

</row>

<row>

<entry><p>Timeout in Location Server. Module has not yet returned a position. </p> </entry>

<entry><p>Position containing "Not a Number" <codeph>(NaN)</codeph> values

is returned. <codeph>TRequestStatus</codeph> is <codeph>KErrTimedOut</codeph>. </p> </entry>

<entry><p>Position containing <codeph>NaN</codeph> values is returned. <codeph>TRequestStatus</codeph> is <codeph>KErrTimedOut</codeph>. </p> </entry>

</row>

<row>

<entry><p>Timeout in Location Server. Module has previously returned an inaccurate

position. </p> </entry>

<entry><p> <b>If LBS is configured to return all positions:</b>  </p> <p>This

can't happen. Inaccurate position would have been returned to client. </p> <p> <b>Else

if LBS is configured to return only accurate positions:</b>  </p> <p>Inaccurate

position is returned. <codeph>TRequestStatus</codeph> is <codeph>KPositionQualityLoss</codeph>. </p> </entry>

<entry><p>This can't happen. Inaccurate position would have been returned

before the timeout. </p> </entry>

</row>

<row>

<entry><p>Timeout in Location Server. Module has previously returned an incomplete

position. </p> </entry>

<entry><p>Incomplete position is returned (contains some <codeph>NaN</codeph> values). <codeph>TRequestStatus</codeph> is <codeph>KPositionQualityLoss</codeph>. </p> </entry>

<entry><p>This can't happen. The incomplete position would have been returned

before the timeout. </p> </entry>

</row>

<row>

<entry><p>Module returns an accurate or an inaccurate position and an error

code of <xref href="GUID-A88ADC78-BF9D-31C5-AF05-8613C326D2F3.dita"><apiname>KPositionCalculationFutile</apiname></xref>. </p> </entry>

<entry><p>The most accurate available position is returned. </p> <p> <b>If

LBS is configured to return all positions:</b>  </p> <p> <codeph> TRequestStatus</codeph> is <codeph>KErrNone</codeph>. </p> <p> <b>Else

if LBS is configured to return only accurate positions:</b>  </p> <p>TRequestStatus

is <codeph>KPositionQualityLoss</codeph> if position is inaccurate. </p> </entry>

<entry><p>The most accurate available position is returned. </p> <p> <b>If

LBS is configured to return all positions:</b>  </p> <p> <codeph> TRequestStatus</codeph> is <codeph>KErrNone</codeph>. </p> <p> <b>Else

if LBS is configured to return only accurate positions:</b>  </p> <p> <codeph>TRequestStatus</codeph> is <codeph>KPositionQualityLoss</codeph> if

position is inaccurate. </p> </entry>

</row>

<row>

<entry><p>Module returns an incomplete position and an error code of <xref href="GUID-A88ADC78-BF9D-31C5-AF05-8613C326D2F3.dita"><apiname>KPositionCalculationFutile</apiname></xref>. </p> </entry>

<entry><p>The most accurate available position is returned. TRequestStatus

is <codeph>KPositionQualityLoss</codeph>. </p> </entry>

<entry><p>The most accurate available position is returned. TRequestStatus

is <codeph>KPositionPartialUpdate</codeph>. </p> </entry>

</row>

<row>

<entry><p>Client calls <codeph>RPositioner::CompleteRequest()</codeph>. </p> </entry>

<entry><p>The last calculated position is returned. <codeph>TRequestStatus</codeph> is <codeph>KPositionEarlyComplete</codeph>. </p> </entry>

<entry><p>The last calculated position is returned. <codeph>TRequestStatus</codeph> is <codeph>KPositionEarlyComplete</codeph>. </p> </entry>

</row>

</tbody>

</tgroup>

</table> <p>Table 1. Location Acquisition API runtime behavior. </p> <p id="GUID-2DF0D6FF-BB17-56B9-B19F-C0F33C6F0F15"><b>Source of position updates</b> </p> <p>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. </p> <p>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 <xref href="GUID-1EAEB7EF-0AC7-37C7-B35F-C9B780FFC575.dita#GUID-1EAEB7EF-0AC7-37C7-B35F-C9B780FFC575/GUID-AF3D9B5F-8025-3AFF-A101-82025520EBD6"><apiname>RPositioner::Open()</apiname></xref> method

was used to open the client/server subsession. </p> <p>On some platforms,

when a client/server subsession is opened using <codeph>RPositioner::Open(RPositionServer&amp;

aPosServer, TPositionModuleId              aModuleId)</codeph> only position

updates from the specified module are returned to the client. Opening a subsession

using other versions of <codeph>RPositioner::Open()</codeph> can return position

updates from other positioning modules. </p> <p>On some platforms LBS may

be configured to return position updates from any positioning module when

any version of <xref href="GUID-1EAEB7EF-0AC7-37C7-B35F-C9B780FFC575.dita#GUID-1EAEB7EF-0AC7-37C7-B35F-C9B780FFC575/GUID-AF3D9B5F-8025-3AFF-A101-82025520EBD6"><apiname>RPositioner::Open()</apiname></xref> is used. </p> </section>

</conbody><related-links>

<link href="GUID-0D5692FB-305E-58B2-B105-B309BB9AE38D.dita"><linktext>Location

Acquisition API Reference</linktext></link>

<link href="GUID-F5944819-2942-5ADA-A0AD-510D20BFBDEB.dita"><linktext>How to Get

Module Status Changes</linktext></link>