<?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>
</related-links></concept>