|
1 <?xml version="1.0" encoding="utf-8"?> |
|
2 <!-- Copyright (c) 2007-2010 Nokia Corporation and/or its subsidiary(-ies) All rights reserved. --> |
|
3 <!-- This component and the accompanying materials are made available under the terms of the License |
|
4 "Eclipse Public License v1.0" which accompanies this distribution, |
|
5 and is available at the URL "http://www.eclipse.org/legal/epl-v10.html". --> |
|
6 <!-- Initial Contributors: |
|
7 Nokia Corporation - initial contribution. |
|
8 Contributors: |
|
9 --> |
|
10 <!DOCTYPE concept |
|
11 PUBLIC "-//OASIS//DTD DITA Concept//EN" "concept.dtd"> |
|
12 <concept id="GUID-4E56E531-5757-5740-9C7D-705D427FA9D5" xml:lang="en"><title>Location |
|
13 Acquisition API Runtime Behaviour</title><shortdesc>This document describes some differences in runtime behaviour that |
|
14 application clients may observe depending on the Symbian platform on which |
|
15 they are running. </shortdesc><prolog><metadata><keywords/></metadata></prolog><conbody> |
|
16 <section><title>Purpose</title> <p>This document describes some differences |
|
17 in runtime behaviour that a Location Acquisition API client may observe. The |
|
18 exact behaviour of the API depends on the configuration of the LBS subsystem |
|
19 in the Symbian platform and on the positioning technologies that are available. </p> </section> |
|
20 <section><title>Types of runtime behaviour differences</title> <p>There are |
|
21 two main types of runtime behaviour differences: </p> <ul> |
|
22 <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> |
|
23 <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 |
|
24 updates may originate) </p> </li> |
|
25 </ul> <p id="GUID-95EE0194-408E-5366-9273-8F72682E05F2"><b>Accuracy of position updates</b> </p> <p>This |
|
26 section describes the behavior that a client application can expect depending |
|
27 on the Symbian platform on which it runs. </p> <p>A client application may |
|
28 receive a location update whenever a position is available. The current latitude |
|
29 and longitude have been determined but their accuracy may not meet the client’s |
|
30 expectations. A timeout of the client's location request will only occur when |
|
31 it is not possible to calculate a position (irrespective of its quality). </p> <p>Some |
|
32 platforms may be configured to return a position update only if it meets the |
|
33 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 |
|
34 only when the Location Server has a position fix that meets the specified |
|
35 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 |
|
36 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 |
|
37 default quality criteria are used to filter position updates returned to the |
|
38 client. </p> <p>It is recommended that applications are designed to be aware |
|
39 that they may receive positions that do not meet their expected accuracy before |
|
40 the timeout period expires. If accuracy is critical to a client application |
|
41 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 |
|
42 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 |
|
43 parameter may not indicate position quality loss (it may be set to <codeph>KErrNone</codeph> and |
|
44 not to <codeph>KPositionQualityLoss</codeph>). </p> <p>Table 1 shows the position |
|
45 updates and <codeph>TRequestStatus</codeph> values that are returned by the |
|
46 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"> |
|
47 <tgroup cols="3"><colspec colname="col0"/><colspec colname="col1"/><colspec colname="col2"/> |
|
48 <thead> |
|
49 <row> |
|
50 <entry>Event</entry> |
|
51 <entry> API response to client (partial updates OFF)</entry> |
|
52 <entry>API response to client (partial updates ON)</entry> |
|
53 </row> |
|
54 </thead> |
|
55 <tbody> |
|
56 <row> |
|
57 <entry><p>Module returns <codeph><error code></codeph> before request timeout. </p> </entry> |
|
58 <entry><p>Position is returned. <codeph>TRequestStatus</codeph> is <codeph><error |
|
59 code></codeph>. </p> </entry> |
|
60 <entry><p>Position is returned. <codeph>TRequestStatus</codeph> is <codeph><error |
|
61 code></codeph>. </p> </entry> |
|
62 </row> |
|
63 <row> |
|
64 <entry><p>Module returns incomplete position before request timeout. </p> </entry> |
|
65 <entry><p>Position is not returned. <codeph>NotifyPositionUpdate()</codeph> does |
|
66 not complete. </p> </entry> |
|
67 <entry><p>Position is returned. <codeph>TRequestStatus</codeph> is <codeph>KPositionPartialUpdate</codeph>. </p> </entry> |
|
68 </row> |
|
69 <row> |
|
70 <entry><p>Module returns accurate position before request timeout. </p> </entry> |
|
71 <entry><p>Position is returned. <codeph>TRequestStatus</codeph> is <codeph>KErrNone</codeph>. </p> </entry> |
|
72 <entry><p>Position is returned. <codeph>TRequestStatus</codeph> is <codeph>KErrNone</codeph>. </p> </entry> |
|
73 </row> |
|
74 <row> |
|
75 <entry><p>Module returns inaccurate position before request timeout. </p> </entry> |
|
76 <entry><p> <b>If LBS is configured to return all positions:</b> </p> <p>Position |
|
77 is returned. <codeph>TRequestStatus</codeph> is <codeph>KErrNone</codeph>. </p> <p> <b>Else |
|
78 if LBS is configured to return only accurate positions:</b> </p> <p>Position |
|
79 is not returned. <codeph>NotifyPositionUpdate()</codeph> does not complete. </p> </entry> |
|
80 <entry><p> <b>If LBS is configured to return all positions:</b> </p> <p>Position |
|
81 is returned. <codeph>TRequestStatus</codeph> is <codeph>KErrNone</codeph> </p> <p> <b>Else |
|
82 if LBS is configured to return only accurate positions:</b> </p> <p>Position |
|
83 is returned. <codeph>TRequestStatus</codeph> is <codeph>KPositionPartialUpdate</codeph>. </p> </entry> |
|
84 </row> |
|
85 <row> |
|
86 <entry><p>Timeout in Location Server. Module has not yet returned a position. </p> </entry> |
|
87 <entry><p>Position containing "Not a Number" <codeph>(NaN)</codeph> values |
|
88 is returned. <codeph>TRequestStatus</codeph> is <codeph>KErrTimedOut</codeph>. </p> </entry> |
|
89 <entry><p>Position containing <codeph>NaN</codeph> values is returned. <codeph>TRequestStatus</codeph> is <codeph>KErrTimedOut</codeph>. </p> </entry> |
|
90 </row> |
|
91 <row> |
|
92 <entry><p>Timeout in Location Server. Module has previously returned an inaccurate |
|
93 position. </p> </entry> |
|
94 <entry><p> <b>If LBS is configured to return all positions:</b> </p> <p>This |
|
95 can't happen. Inaccurate position would have been returned to client. </p> <p> <b>Else |
|
96 if LBS is configured to return only accurate positions:</b> </p> <p>Inaccurate |
|
97 position is returned. <codeph>TRequestStatus</codeph> is <codeph>KPositionQualityLoss</codeph>. </p> </entry> |
|
98 <entry><p>This can't happen. Inaccurate position would have been returned |
|
99 before the timeout. </p> </entry> |
|
100 </row> |
|
101 <row> |
|
102 <entry><p>Timeout in Location Server. Module has previously returned an incomplete |
|
103 position. </p> </entry> |
|
104 <entry><p>Incomplete position is returned (contains some <codeph>NaN</codeph> values). <codeph>TRequestStatus</codeph> is <codeph>KPositionQualityLoss</codeph>. </p> </entry> |
|
105 <entry><p>This can't happen. The incomplete position would have been returned |
|
106 before the timeout. </p> </entry> |
|
107 </row> |
|
108 <row> |
|
109 <entry><p>Module returns an accurate or an inaccurate position and an error |
|
110 code of <xref href="GUID-A88ADC78-BF9D-31C5-AF05-8613C326D2F3.dita"><apiname>KPositionCalculationFutile</apiname></xref>. </p> </entry> |
|
111 <entry><p>The most accurate available position is returned. </p> <p> <b>If |
|
112 LBS is configured to return all positions:</b> </p> <p> <codeph> TRequestStatus</codeph> is <codeph>KErrNone</codeph>. </p> <p> <b>Else |
|
113 if LBS is configured to return only accurate positions:</b> </p> <p>TRequestStatus |
|
114 is <codeph>KPositionQualityLoss</codeph> if position is inaccurate. </p> </entry> |
|
115 <entry><p>The most accurate available position is returned. </p> <p> <b>If |
|
116 LBS is configured to return all positions:</b> </p> <p> <codeph> TRequestStatus</codeph> is <codeph>KErrNone</codeph>. </p> <p> <b>Else |
|
117 if LBS is configured to return only accurate positions:</b> </p> <p> <codeph>TRequestStatus</codeph> is <codeph>KPositionQualityLoss</codeph> if |
|
118 position is inaccurate. </p> </entry> |
|
119 </row> |
|
120 <row> |
|
121 <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> |
|
122 <entry><p>The most accurate available position is returned. TRequestStatus |
|
123 is <codeph>KPositionQualityLoss</codeph>. </p> </entry> |
|
124 <entry><p>The most accurate available position is returned. TRequestStatus |
|
125 is <codeph>KPositionPartialUpdate</codeph>. </p> </entry> |
|
126 </row> |
|
127 <row> |
|
128 <entry><p>Client calls <codeph>RPositioner::CompleteRequest()</codeph>. </p> </entry> |
|
129 <entry><p>The last calculated position is returned. <codeph>TRequestStatus</codeph> is <codeph>KPositionEarlyComplete</codeph>. </p> </entry> |
|
130 <entry><p>The last calculated position is returned. <codeph>TRequestStatus</codeph> is <codeph>KPositionEarlyComplete</codeph>. </p> </entry> |
|
131 </row> |
|
132 </tbody> |
|
133 </tgroup> |
|
134 </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 |
|
135 section describes differences in the source of the position updates that a |
|
136 client application receives depending on the Symbian platform on which it |
|
137 runs. </p> <p>On platforms with more than one positioning module, a position |
|
138 may be obtained by the Location Server from more than one module (for example, |
|
139 a position may be returned from GPS hardware or from the network). Whether |
|
140 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 |
|
141 was used to open the client/server subsession. </p> <p>On some platforms, |
|
142 when a client/server subsession is opened using <codeph>RPositioner::Open(RPositionServer& |
|
143 aPosServer, TPositionModuleId aModuleId)</codeph> only position |
|
144 updates from the specified module are returned to the client. Opening a subsession |
|
145 using other versions of <codeph>RPositioner::Open()</codeph> can return position |
|
146 updates from other positioning modules. </p> <p>On some platforms LBS may |
|
147 be configured to return position updates from any positioning module when |
|
148 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> |
|
149 </conbody><related-links> |
|
150 <link href="GUID-0D5692FB-305E-58B2-B105-B309BB9AE38D.dita"><linktext>Location |
|
151 Acquisition API Reference</linktext></link> |
|
152 <link href="GUID-F5944819-2942-5ADA-A0AD-510D20BFBDEB.dita"><linktext>How to Get |
|
153 Module Status Changes</linktext></link> |
|
154 </related-links></concept> |