--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/Symbian3/SDK/Source/GUID-4E56E531-5757-5740-9C7D-705D427FA9D5.dita	Thu Jan 21 18:18:20 2010 +0000
@@ -0,0 +1,154 @@
+<?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>
\ No newline at end of file