Symbian3/SDK/Source/GUID-F6B5F777-D12F-5913-AECE-047DF8C72F1F.dita
author Dominic Pinkman <Dominic.Pinkman@Nokia.com>
Wed, 31 Mar 2010 11:11:55 +0100
changeset 7 51a74ef9ed63
child 8 ae94777fff8f
permissions -rw-r--r--
Week 12 contribution of API Specs and fix SDK submission
Ignore whitespace changes - Everywhere: Within whitespace: At end of lines:
7
51a74ef9ed63 Week 12 contribution of API Specs and fix SDK submission
Dominic Pinkman <Dominic.Pinkman@Nokia.com>
parents:
diff changeset
     1
<?xml version="1.0" encoding="utf-8"?>
51a74ef9ed63 Week 12 contribution of API Specs and fix SDK submission
Dominic Pinkman <Dominic.Pinkman@Nokia.com>
parents:
diff changeset
     2
<!-- Copyright (c) 2007-2010 Nokia Corporation and/or its subsidiary(-ies) All rights reserved. -->
51a74ef9ed63 Week 12 contribution of API Specs and fix SDK submission
Dominic Pinkman <Dominic.Pinkman@Nokia.com>
parents:
diff changeset
     3
<!-- This component and the accompanying materials are made available under the terms of the License 
51a74ef9ed63 Week 12 contribution of API Specs and fix SDK submission
Dominic Pinkman <Dominic.Pinkman@Nokia.com>
parents:
diff changeset
     4
"Eclipse Public License v1.0" which accompanies this distribution, 
51a74ef9ed63 Week 12 contribution of API Specs and fix SDK submission
Dominic Pinkman <Dominic.Pinkman@Nokia.com>
parents:
diff changeset
     5
and is available at the URL "http://www.eclipse.org/legal/epl-v10.html". -->
51a74ef9ed63 Week 12 contribution of API Specs and fix SDK submission
Dominic Pinkman <Dominic.Pinkman@Nokia.com>
parents:
diff changeset
     6
<!-- Initial Contributors:
51a74ef9ed63 Week 12 contribution of API Specs and fix SDK submission
Dominic Pinkman <Dominic.Pinkman@Nokia.com>
parents:
diff changeset
     7
    Nokia Corporation - initial contribution.
51a74ef9ed63 Week 12 contribution of API Specs and fix SDK submission
Dominic Pinkman <Dominic.Pinkman@Nokia.com>
parents:
diff changeset
     8
Contributors: 
51a74ef9ed63 Week 12 contribution of API Specs and fix SDK submission
Dominic Pinkman <Dominic.Pinkman@Nokia.com>
parents:
diff changeset
     9
-->
51a74ef9ed63 Week 12 contribution of API Specs and fix SDK submission
Dominic Pinkman <Dominic.Pinkman@Nokia.com>
parents:
diff changeset
    10
<!DOCTYPE concept
51a74ef9ed63 Week 12 contribution of API Specs and fix SDK submission
Dominic Pinkman <Dominic.Pinkman@Nokia.com>
parents:
diff changeset
    11
  PUBLIC "-//OASIS//DTD DITA Concept//EN" "concept.dtd">
51a74ef9ed63 Week 12 contribution of API Specs and fix SDK submission
Dominic Pinkman <Dominic.Pinkman@Nokia.com>
parents:
diff changeset
    12
<concept xml:lang="en" id="GUID-F6B5F777-D12F-5913-AECE-047DF8C72F1F"><title>How to Get Location Information</title><shortdesc>This document demonstrates how a client application uses the Location Acquisition API to get a position. </shortdesc><prolog><metadata><keywords/></metadata></prolog><conbody><section><title>Purpose</title> <p>This tutorial explains how to get location information using the Location Acquisition API. </p> </section> <section><title>Required background</title> <p><xref href="GUID-65E9C040-AAB6-5C1E-9724-8828DADFC741.dita">Location Acquisition API Overview</xref> describes the main client/server classes of the API. </p> <p><xref href="GUID-ABC01315-D65D-55EA-9D42-4DE6384D517D.dita">Position Data and Info Classes</xref> describes the classes that hold location information. </p> </section> <section><title>Getting location information</title> <p>This section describes how to get location information using the Location Acquisition API. </p> <p><b>Introduction</b> </p> <p>Client applications use the <xref href="GUID-0ADC4654-7F7B-3B53-A2F9-7035670F501B.dita"><apiname>RPositionServer</apiname></xref> and <xref href="GUID-1EAEB7EF-0AC7-37C7-B35F-C9B780FFC575.dita"><apiname>RPositioner</apiname></xref> classes to get position updates. <codeph>RPositionServer</codeph> is used by client applications to manage a session with the Location Server and to get Positioning Module information. <codeph>RPositioner</codeph> is used by client applications to manage a subsession with the Location Server and to get position updates. </p> <p><b>GPS positioning modes</b> </p> <p>The Global Positioning System (GPS) is a technology that is often included in devices that support LBS. </p> <p>For each location request from a client, the LBS subsystem can operate in one of several different GPS positioning modes. The Location Acquisition API hides the details of which GPS positioning mode is in use from client applications. A client makes the same sequence of calls to the API to get a position update whichever positioning mode is used. Note that only some of these positioning modes may be available to a client application at runtime. </p> <p>Each GPS positioning mode is a different way of getting a position fix: </p> <ul><li id="GUID-2BDDAACC-EB8D-5191-A42E-0BFA0B26C7DC"><p>Autonomous </p> <p>LBS uses a GPS Positioning Module to calculate position fixes without assistance data from the network. This mode typically takes the longest time to obtain a location fix compared to the other modes. </p> </li> <li id="GUID-B2E24A6F-F46A-529E-A8F5-FC52F7CD8F0D"><p>Terminal Based Mode </p> <p>LBS uses an A-GPS Positioning Module to calculate position fixes using assistance data from the network. Assistance data specifies the GPS satellites that are above the horizon as seen from the mobile device's current location. Assistance data is used by an A-GPS Positioning Module to reduce the time necessary to obtain a position fix. </p> <p>The network can also supply a <i>reference position</i> to the LBS subsystem as part of the sequence of events. This position is calculated in the network using cell-based techniques and may be less accurate than that obtained from GPS. If a reference position is available, it may be returned to the client before a GPS position. </p> <p>See <xref href="GUID-4E56E531-5757-5740-9C7D-705D427FA9D5.dita">Location Acquisition API Runtime Behaviour</xref> for more information about the position updates that can be returned by LBS. </p> </li> <li id="GUID-018CA9E1-F191-5CC9-8DCD-8FE08CAABD28"><p>Terminal Assisted Mode </p> <p>LBS uses an A-GPS Positioning Module to obtain GPS measurements (using assistance data from the network). GPS measurements are the raw data used to calculate a GPS fix. Measurements are sent to the network and a position fix is calculated by a remote server. The remotely calculated position fix is returned to the mobile device and is known as the <i>final network position</i>. The LBS subsystem returns this position to the client. </p> </li> <li id="GUID-9B1678F5-A53B-5245-9EE4-5809461E2EBB"><p>Simultaneous Terminal Based Mode and Terminal Assisted Mode. </p> <p>LBS passes GPS measurements to the network (as in Terminal Assisted Mode), but also attempts to use those measurements to calculate a GPS position fix (as in Terminal Based Mode). The position returned to the client may be either a GPS position (calculated in the mobile device) or a final network position (calculated using the measurements by a remote server in the network). The position that is calculated first (the GPS position or the final network position) is generally returned to the client. The final network position may also be returned to the client after the return of the GPS position. </p> </li> </ul> <p>Some devices also support a Cell-based Mode in which LBS obtains a position fix from the network without using GPS. This position fix is sometimes less accurate than that obtained using GPS. </p> <p>A client application cannot directly choose the GPS positioning mode that is used for its location request. A handset manufacturer may provide an LBS settings application where the GPS mode can be selected by an end user. However for modes that involve the network (Terminal Based Mode, Terminal Assisted Mode and Cell-based Mode) it is possible for a network operator to override the GPS mode as part of the location request. If a client wants to know precisely how a position fix was calculated, this information is available in the returned position info object (as described in more detail later in this document). </p> <p><b>Example sequence</b> </p> <p>Figure 1 shows a simplified sequence for a client requesting a position update from LBS. The sequence shows simplified behaviour for Terminal Based Mode. The <i>A-GPS Module</i> is a Positioning Module that uses Assisted GPS to calculate a position. The <i>Network Protocol Module</i> is a Positioning Module that obtains GPS assistance data and reference positions (often approximate positions) from the network. Note that Terminal Based Mode may not be available on all mobile devices. This depends on the Positioning Modules that have been installed by the mobile device creator. </p> <fig id="GUID-FD5FEC83-B76D-5D45-AF40-DF5C2F17D404"><title>
51a74ef9ed63 Week 12 contribution of API Specs and fix SDK submission
Dominic Pinkman <Dominic.Pinkman@Nokia.com>
parents:
diff changeset
    13
                Figure 1. Simplified Terminal Based Mode Sequence 
51a74ef9ed63 Week 12 contribution of API Specs and fix SDK submission
Dominic Pinkman <Dominic.Pinkman@Nokia.com>
parents:
diff changeset
    14
             </title> <image href="GUID-D9C4D520-821D-5097-A63C-0BF4C7F59827_d0e271226_href.png" placement="inline"/></fig> <p><b>Example code and description</b> </p> <p>The following code shows a simple example of how a client application can get a single position update. The numbers in the code comments refer to sections that follow the code example. </p> <codeblock id="GUID-7B350944-5178-586B-B381-87DC5104DD1F" xml:space="preserve">#include &lt;lbs.h&gt;
51a74ef9ed63 Week 12 contribution of API Specs and fix SDK submission
Dominic Pinkman <Dominic.Pinkman@Nokia.com>
parents:
diff changeset
    15
#include &lt;lbserrors.h&gt;
51a74ef9ed63 Week 12 contribution of API Specs and fix SDK submission
Dominic Pinkman <Dominic.Pinkman@Nokia.com>
parents:
diff changeset
    16
51a74ef9ed63 Week 12 contribution of API Specs and fix SDK submission
Dominic Pinkman <Dominic.Pinkman@Nokia.com>
parents:
diff changeset
    17
...
51a74ef9ed63 Week 12 contribution of API Specs and fix SDK submission
Dominic Pinkman <Dominic.Pinkman@Nokia.com>
parents:
diff changeset
    18
51a74ef9ed63 Week 12 contribution of API Specs and fix SDK submission
Dominic Pinkman <Dominic.Pinkman@Nokia.com>
parents:
diff changeset
    19
RPositionServer server;
51a74ef9ed63 Week 12 contribution of API Specs and fix SDK submission
Dominic Pinkman <Dominic.Pinkman@Nokia.com>
parents:
diff changeset
    20
RPositioner positioner;
51a74ef9ed63 Week 12 contribution of API Specs and fix SDK submission
Dominic Pinkman <Dominic.Pinkman@Nokia.com>
parents:
diff changeset
    21
51a74ef9ed63 Week 12 contribution of API Specs and fix SDK submission
Dominic Pinkman <Dominic.Pinkman@Nokia.com>
parents:
diff changeset
    22
// 1. Create a session with the Location Server
51a74ef9ed63 Week 12 contribution of API Specs and fix SDK submission
Dominic Pinkman <Dominic.Pinkman@Nokia.com>
parents:
diff changeset
    23
User::LeaveIfError(server.Connect());
51a74ef9ed63 Week 12 contribution of API Specs and fix SDK submission
Dominic Pinkman <Dominic.Pinkman@Nokia.com>
parents:
diff changeset
    24
CleanupClosePushL(server);
51a74ef9ed63 Week 12 contribution of API Specs and fix SDK submission
Dominic Pinkman <Dominic.Pinkman@Nokia.com>
parents:
diff changeset
    25
51a74ef9ed63 Week 12 contribution of API Specs and fix SDK submission
Dominic Pinkman <Dominic.Pinkman@Nokia.com>
parents:
diff changeset
    26
// 2. Create a subsession with the Location Server using default positioning module
51a74ef9ed63 Week 12 contribution of API Specs and fix SDK submission
Dominic Pinkman <Dominic.Pinkman@Nokia.com>
parents:
diff changeset
    27
User::LeaveIfError(positioner.Open(server));
51a74ef9ed63 Week 12 contribution of API Specs and fix SDK submission
Dominic Pinkman <Dominic.Pinkman@Nokia.com>
parents:
diff changeset
    28
CleanupClosePushL(positioner);
51a74ef9ed63 Week 12 contribution of API Specs and fix SDK submission
Dominic Pinkman <Dominic.Pinkman@Nokia.com>
parents:
diff changeset
    29
51a74ef9ed63 Week 12 contribution of API Specs and fix SDK submission
Dominic Pinkman <Dominic.Pinkman@Nokia.com>
parents:
diff changeset
    30
// 3. Set the requester information - in this example define a requester stack... 
51a74ef9ed63 Week 12 contribution of API Specs and fix SDK submission
Dominic Pinkman <Dominic.Pinkman@Nokia.com>
parents:
diff changeset
    31
51a74ef9ed63 Week 12 contribution of API Specs and fix SDK submission
Dominic Pinkman <Dominic.Pinkman@Nokia.com>
parents:
diff changeset
    32
_LIT(KCntPhone, "+358501234567");
51a74ef9ed63 Week 12 contribution of API Specs and fix SDK submission
Dominic Pinkman <Dominic.Pinkman@Nokia.com>
parents:
diff changeset
    33
_LIT(KSrvName, "MyService");
51a74ef9ed63 Week 12 contribution of API Specs and fix SDK submission
Dominic Pinkman <Dominic.Pinkman@Nokia.com>
parents:
diff changeset
    34
RRequestorStack stack;
51a74ef9ed63 Week 12 contribution of API Specs and fix SDK submission
Dominic Pinkman <Dominic.Pinkman@Nokia.com>
parents:
diff changeset
    35
CRequestor* contact = CRequestor::NewLC(CRequestor::ERequestorContact, CRequestor::EFormatTelephone, KCntPhone);
51a74ef9ed63 Week 12 contribution of API Specs and fix SDK submission
Dominic Pinkman <Dominic.Pinkman@Nokia.com>
parents:
diff changeset
    36
stack.Append(contact);
51a74ef9ed63 Week 12 contribution of API Specs and fix SDK submission
Dominic Pinkman <Dominic.Pinkman@Nokia.com>
parents:
diff changeset
    37
CRequestor* service = CRequestor::NewLC(CRequestor::ERequestorService,    CRequestor::EFormatApplication, KSrvName);
51a74ef9ed63 Week 12 contribution of API Specs and fix SDK submission
Dominic Pinkman <Dominic.Pinkman@Nokia.com>
parents:
diff changeset
    38
stack.Append(service);
51a74ef9ed63 Week 12 contribution of API Specs and fix SDK submission
Dominic Pinkman <Dominic.Pinkman@Nokia.com>
parents:
diff changeset
    39
User::LeaveIfError(positioner.SetRequestor(stack));
51a74ef9ed63 Week 12 contribution of API Specs and fix SDK submission
Dominic Pinkman <Dominic.Pinkman@Nokia.com>
parents:
diff changeset
    40
51a74ef9ed63 Week 12 contribution of API Specs and fix SDK submission
Dominic Pinkman <Dominic.Pinkman@Nokia.com>
parents:
diff changeset
    41
TPositionInfo posInfo;
51a74ef9ed63 Week 12 contribution of API Specs and fix SDK submission
Dominic Pinkman <Dominic.Pinkman@Nokia.com>
parents:
diff changeset
    42
TPosition pos;
51a74ef9ed63 Week 12 contribution of API Specs and fix SDK submission
Dominic Pinkman <Dominic.Pinkman@Nokia.com>
parents:
diff changeset
    43
TRequestStatus status;
51a74ef9ed63 Week 12 contribution of API Specs and fix SDK submission
Dominic Pinkman <Dominic.Pinkman@Nokia.com>
parents:
diff changeset
    44
51a74ef9ed63 Week 12 contribution of API Specs and fix SDK submission
Dominic Pinkman <Dominic.Pinkman@Nokia.com>
parents:
diff changeset
    45
/* 4. To set update options, call RPositioner::SetUpdateOptions(). 
51a74ef9ed63 Week 12 contribution of API Specs and fix SDK submission
Dominic Pinkman <Dominic.Pinkman@Nokia.com>
parents:
diff changeset
    46
      See the description in section 4 below */
51a74ef9ed63 Week 12 contribution of API Specs and fix SDK submission
Dominic Pinkman <Dominic.Pinkman@Nokia.com>
parents:
diff changeset
    47
51a74ef9ed63 Week 12 contribution of API Specs and fix SDK submission
Dominic Pinkman <Dominic.Pinkman@Nokia.com>
parents:
diff changeset
    48
/* 5. Request location information
51a74ef9ed63 Week 12 contribution of API Specs and fix SDK submission
Dominic Pinkman <Dominic.Pinkman@Nokia.com>
parents:
diff changeset
    49
      Could also call positioner.GetLastKnownPosition(posInfo, status) 
51a74ef9ed63 Week 12 contribution of API Specs and fix SDK submission
Dominic Pinkman <Dominic.Pinkman@Nokia.com>
parents:
diff changeset
    50
      to get cached location information */
51a74ef9ed63 Week 12 contribution of API Specs and fix SDK submission
Dominic Pinkman <Dominic.Pinkman@Nokia.com>
parents:
diff changeset
    51
positioner.NotifyPositionUpdate(posInfo, status);
51a74ef9ed63 Week 12 contribution of API Specs and fix SDK submission
Dominic Pinkman <Dominic.Pinkman@Nokia.com>
parents:
diff changeset
    52
User::WaitForRequest(status);
51a74ef9ed63 Week 12 contribution of API Specs and fix SDK submission
Dominic Pinkman <Dominic.Pinkman@Nokia.com>
parents:
diff changeset
    53
51a74ef9ed63 Week 12 contribution of API Specs and fix SDK submission
Dominic Pinkman <Dominic.Pinkman@Nokia.com>
parents:
diff changeset
    54
// 6. Receive location information
51a74ef9ed63 Week 12 contribution of API Specs and fix SDK submission
Dominic Pinkman <Dominic.Pinkman@Nokia.com>
parents:
diff changeset
    55
if (status != KErrNone)
51a74ef9ed63 Week 12 contribution of API Specs and fix SDK submission
Dominic Pinkman <Dominic.Pinkman@Nokia.com>
parents:
diff changeset
    56
 {
51a74ef9ed63 Week 12 contribution of API Specs and fix SDK submission
Dominic Pinkman <Dominic.Pinkman@Nokia.com>
parents:
diff changeset
    57
 // Handle possible client/server errors
51a74ef9ed63 Week 12 contribution of API Specs and fix SDK submission
Dominic Pinkman <Dominic.Pinkman@Nokia.com>
parents:
diff changeset
    58
 ...
51a74ef9ed63 Week 12 contribution of API Specs and fix SDK submission
Dominic Pinkman <Dominic.Pinkman@Nokia.com>
parents:
diff changeset
    59
 }
51a74ef9ed63 Week 12 contribution of API Specs and fix SDK submission
Dominic Pinkman <Dominic.Pinkman@Nokia.com>
parents:
diff changeset
    60
51a74ef9ed63 Week 12 contribution of API Specs and fix SDK submission
Dominic Pinkman <Dominic.Pinkman@Nokia.com>
parents:
diff changeset
    61
// Get the position data object from the wrapper info object
51a74ef9ed63 Week 12 contribution of API Specs and fix SDK submission
Dominic Pinkman <Dominic.Pinkman@Nokia.com>
parents:
diff changeset
    62
posInfo.GetPosition(pos);
51a74ef9ed63 Week 12 contribution of API Specs and fix SDK submission
Dominic Pinkman <Dominic.Pinkman@Nokia.com>
parents:
diff changeset
    63
51a74ef9ed63 Week 12 contribution of API Specs and fix SDK submission
Dominic Pinkman <Dominic.Pinkman@Nokia.com>
parents:
diff changeset
    64
// Use the position data
51a74ef9ed63 Week 12 contribution of API Specs and fix SDK submission
Dominic Pinkman <Dominic.Pinkman@Nokia.com>
parents:
diff changeset
    65
...
51a74ef9ed63 Week 12 contribution of API Specs and fix SDK submission
Dominic Pinkman <Dominic.Pinkman@Nokia.com>
parents:
diff changeset
    66
51a74ef9ed63 Week 12 contribution of API Specs and fix SDK submission
Dominic Pinkman <Dominic.Pinkman@Nokia.com>
parents:
diff changeset
    67
// Reissue the location request if necessary by calling NotifyPositionUpdate() again
51a74ef9ed63 Week 12 contribution of API Specs and fix SDK submission
Dominic Pinkman <Dominic.Pinkman@Nokia.com>
parents:
diff changeset
    68
51a74ef9ed63 Week 12 contribution of API Specs and fix SDK submission
Dominic Pinkman <Dominic.Pinkman@Nokia.com>
parents:
diff changeset
    69
/* 7. To cancel or complete a location request a client
51a74ef9ed63 Week 12 contribution of API Specs and fix SDK submission
Dominic Pinkman <Dominic.Pinkman@Nokia.com>
parents:
diff changeset
    70
 calls RPositioner::CancelRequest() or RPositioner::CompleteRequest() */
51a74ef9ed63 Week 12 contribution of API Specs and fix SDK submission
Dominic Pinkman <Dominic.Pinkman@Nokia.com>
parents:
diff changeset
    71
51a74ef9ed63 Week 12 contribution of API Specs and fix SDK submission
Dominic Pinkman <Dominic.Pinkman@Nokia.com>
parents:
diff changeset
    72
// 8. Cleanup
51a74ef9ed63 Week 12 contribution of API Specs and fix SDK submission
Dominic Pinkman <Dominic.Pinkman@Nokia.com>
parents:
diff changeset
    73
stack.Reset();
51a74ef9ed63 Week 12 contribution of API Specs and fix SDK submission
Dominic Pinkman <Dominic.Pinkman@Nokia.com>
parents:
diff changeset
    74
CleanupStack::PopAndDestroy(service);
51a74ef9ed63 Week 12 contribution of API Specs and fix SDK submission
Dominic Pinkman <Dominic.Pinkman@Nokia.com>
parents:
diff changeset
    75
CleanupStack::PopAndDestroy(contact);
51a74ef9ed63 Week 12 contribution of API Specs and fix SDK submission
Dominic Pinkman <Dominic.Pinkman@Nokia.com>
parents:
diff changeset
    76
CleanupStack::PopAndDestroy(&amp;positioner);
51a74ef9ed63 Week 12 contribution of API Specs and fix SDK submission
Dominic Pinkman <Dominic.Pinkman@Nokia.com>
parents:
diff changeset
    77
CleanupStack::PopAndDestroy(&amp;server);
51a74ef9ed63 Week 12 contribution of API Specs and fix SDK submission
Dominic Pinkman <Dominic.Pinkman@Nokia.com>
parents:
diff changeset
    78
</codeblock> <p>The following describes the steps to get location information as shown in the above example: </p> <p><b>1. Create a session with the Location Server </b> </p> <p>To create a session with the Location Server, a client application: </p> <ul><li id="GUID-2AD36917-A3B1-52D1-BBBB-C9A48592E5AA"><p>Creates an instance of <xref href="GUID-0ADC4654-7F7B-3B53-A2F9-7035670F501B.dita"><apiname>RPositionServer</apiname></xref>  </p> </li> <li id="GUID-5771DD5B-C660-5408-8F34-C94D2E8A3419"><p>Calls <xref href="GUID-0ADC4654-7F7B-3B53-A2F9-7035670F501B.dita#GUID-0ADC4654-7F7B-3B53-A2F9-7035670F501B/GUID-23285930-A1D5-3A97-AED4-E979BFA96FDD"><apiname>RPositionServer::Connect()</apiname></xref>  </p> </li> </ul> <p>Standard client-server error codes are returned by calls to open the session. A panic occurs if the client application has already created a session with the Location Server. Error and panic codes specific to LBS are defined in <filepath>LbsErrors.h</filepath>. </p> <p><b>2. Create a subsession with the Location Server </b> </p> <p>Location information requests are issued on a subsession. </p> <p>To create a subsession, an application calls one of three overloaded <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> member functions: </p> <ul><li id="GUID-D6A2BD94-DFE6-5B2D-9CE4-E5C565323F6E"><p> <codeph>RPositioner::Open(RPositionServer&amp; aPosServer)</codeph> uses the Default Positioning Module to get location information. The client application does not specify any position quality criteria (which specify the required position accuracy) and therefore LBS uses default position quality criteria (horizontal accuracy = 50m, vertical accuracy = 1000m, request timeout = 30 seconds). </p> </li> <li id="GUID-B6357BFF-A3DF-5036-90BF-ED2243C752C0"><p> <codeph>RPositioner::Open(RPositionServer&amp; aPosServer,
51a74ef9ed63 Week 12 contribution of API Specs and fix SDK submission
Dominic Pinkman <Dominic.Pinkman@Nokia.com>
parents:
diff changeset
    79
                  TPositionModuleId aModuleId)</codeph> allows a specific Positioning Module to be specified by the client application. LBS uses position quality criteria associated with the specified Positioning Module. No quality criteria are specified and so LBS uses the capabilities of the Positioning Module as the default criteria. </p> <p>See <xref href="GUID-BADAAC2D-8614-5036-95BC-3889457F7ED0.dita">Positioning Modules</xref> for information about Positioning Module position quality and <xref href="GUID-A4B47A7A-17EB-570C-AD88-6756B34AF634.dita">How to Use Positioning Module Information</xref> for more information about how to get a module ID. </p> </li> </ul> <p>The LBS subsystem does not compare the vertical accuracy of a calculated position with the vertical accuracy specified by a client application (specified by position quality criteria, by a quality profile or by a Positioning Module). Only the horizontal accuracy of a calculated position is used to decide if it is accurate enough to be returned to a client application. </p> <p><b>3. Set client requester details </b> </p> <p>A client application can specify the client requesters by calling <xref href="GUID-1EAEB7EF-0AC7-37C7-B35F-C9B780FFC575.dita#GUID-1EAEB7EF-0AC7-37C7-B35F-C9B780FFC575/GUID-E1B082DC-9C01-3852-B1D8-B2FD18235319"><apiname>RPositioner::SetRequestorL()</apiname></xref> before calling <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> <p>This is an optional step. Calling <codeph>SetRequestorL()</codeph> has no effect in this version of the Symbian platform. Calling <codeph>SetRequestorL()</codeph> is required in some devices based on earlier versions of Symbian. To ensure an LBS application runs on devices based on earlier versions of Symbian, it is recommended that it calls <codeph>SetRequestorL()</codeph>. </p> <p>See <xref href="GUID-ACD9E338-DF75-5811-B696-C3900B498218.dita">Privacy Requester Classes</xref> for more information. </p> <p><b>4. Set update options </b> </p> <p>A client application calls <xref href="GUID-1EAEB7EF-0AC7-37C7-B35F-C9B780FFC575.dita#GUID-1EAEB7EF-0AC7-37C7-B35F-C9B780FFC575/GUID-7A8BC23A-6FF9-3AAF-99BF-A6B074FDEA7B"><apiname>RPositioner::SetUpdateOptions()</apiname></xref> to set the update options. Calling this method only affects future calls 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> and <xref href="GUID-1EAEB7EF-0AC7-37C7-B35F-C9B780FFC575.dita#GUID-1EAEB7EF-0AC7-37C7-B35F-C9B780FFC575/GUID-D9E0BC1D-7783-35BA-8D88-223576E4C85E"><apiname>RPositioner::GetLastKnownPosition()</apiname></xref> and does not affect any outstanding requests. </p> <p>A <xref href="GUID-E60595B9-B6E2-38E1-BE1E-A82113C7EC94.dita"><apiname>TPositionUpdateOptions</apiname></xref> parameter specifies the update options and is passed in <codeph>RPositioner::SetUpdateOptions()</codeph>. The properties of <codeph>TPositionUpdateOptions</codeph> are set either on its construction or via setter methods. The following properties can be defined: </p> <ul><li id="GUID-239CCE63-0455-525A-9CC7-8FCE0530B7CB"><p>The time interval between position updates </p> <p> <codeph>TPositionUpdateOptions::SetUpdateInterval(TTimeIntervalMicroSeconds
51a74ef9ed63 Week 12 contribution of API Specs and fix SDK submission
Dominic Pinkman <Dominic.Pinkman@Nokia.com>
parents:
diff changeset
    80
                  aInterval)</codeph> sets the time interval between position updates. </p> <p>Setting a non-zero value indicates that the client requires periodic updates (this is also known as 'tracking'). LBS attempts to send position updates to the client application with this interval between the updates. Note that setting <codeph>aInterval</codeph> to <codeph>0</codeph> (or not setting it) indicates that the client is not tracking. </p> <p> <i>Note that when a client application is tracking, LBS does not return reference positions as periodic updates. See the section on Tracking later in this document for more information on tracking behaviour.</i>  </p> </li> <li id="GUID-3BDBCE8C-53D1-5DE7-B81A-86145460C1BA"><p>A position update timeout </p> <p> <codeph>TPositionUpdateOptions::SetUpdateTimeOut(TTimeIntervalMicroSeconds
51a74ef9ed63 Week 12 contribution of API Specs and fix SDK submission
Dominic Pinkman <Dominic.Pinkman@Nokia.com>
parents:
diff changeset
    81
                  aTimeOut)</codeph> sets a timeout for the location request. It specifies how long the client application is prepared to wait to obtain a position update. If the timeout expires <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 and the client's <codeph>RunL()</codeph> method is called. </p> <p>After a timeout the value set for the client's <codeph>TRequestStatus</codeph> parameter depends on the configuration of the LBS subsystem and may be either <codeph>KErrTimeOut</codeph> or <codeph>KPositionQualityLoss</codeph>. See <xref href="GUID-4E56E531-5757-5740-9C7D-705D427FA9D5.dita">Location Acquisition API runtime behaviour</xref> for more information. </p> <p> <i>Note that calling SetUpdateTimeOut() with a value of 0 (or not setting it) indicates that LBS should not timeout the location request from a client. </i>  </p> </li> <li id="GUID-C0405589-A7DC-58E4-A39A-145943152B50"><p>The maximum age of a position update </p> <p> <codeph>TPositionUpdateOptions::SetMaxUpdateAge(TTimeIntervalMicroSeconds
51a74ef9ed63 Week 12 contribution of API Specs and fix SDK submission
Dominic Pinkman <Dominic.Pinkman@Nokia.com>
parents:
diff changeset
    82
                  aMaxAge)</codeph> specifies the maximum age of the position data returned by <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>. Setting this value allows the Location Server to use cached location information in some cases. The default value of 0 indicates that new position data is required. </p> </li> <li id="GUID-EBCB9F00-1331-5627-95B6-4B1E851776CF"><p>Acceptance of partial updates </p> <p>A partial update is a position update that contains only partial position data. Such a position is called an <i>incomplete position</i>. An example of an incomplete position is one that contains data about the satellites used to obtain a GPS fix but no latitude or longitude data.<codeph/> LBS defines an incomplete position to be one where either <codeph>TPosition::Latitude()</codeph> or <codeph>TPosition::Longitude()</codeph> is <codeph>NaN</codeph> (Not a Number). </p> <p> <codeph>TPositionUpdateOptions::SetAcceptPartialUpdates(TBool
51a74ef9ed63 Week 12 contribution of API Specs and fix SDK submission
Dominic Pinkman <Dominic.Pinkman@Nokia.com>
parents:
diff changeset
    83
                  aPartial)</codeph> allows an application to choose to accept partial updates. If a partial update is returned an application's <codeph>TRequestStatus</codeph> parameter is set to <codeph>KPositionPartialUpdate</codeph> when <codeph>NotifyPositionUpdate()</codeph> completes. </p> <p>If partial updates are not set the default behaviour is for <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> to complete only when the Positioning Module used for the location request has obtained as much information as possible. Note however that this behaviour is configurable by a Symbian device creator (see <xref href="GUID-4E56E531-5757-5740-9C7D-705D427FA9D5.dita">Location Acquisition API runtime behaviour</xref> for more information). </p> </li> </ul> <p><b>Important note on setting update options </b> </p> <p>The default constructor of <xref href="GUID-E60595B9-B6E2-38E1-BE1E-A82113C7EC94.dita"><apiname>TPositionUpdateOptions</apiname></xref> sets all update options to zero by default and is the equivalent of calling the following: </p> <ul><li id="GUID-FA830ED1-156A-5EE9-B27F-7C4AD064A061"><p> <codeph>TPositionUpdateOptions::SetUpdateInterval(0)</codeph> meaning that tracking is off </p> </li> <li id="GUID-0AF71B28-0EE0-549B-BE23-A82A85A3CC1E"><p> <codeph>TPositionUpdateOptions::SetUpdateTimeout(0)</codeph> meaning that LBS should not timeout the client's request </p> </li> <li id="GUID-A66326A6-8350-5B0A-BA67-1E67C8416FEC"><p> <codeph>TPositionUpdateOptions::SetMaxUpdateAge(0)</codeph> meaning that new position data is required </p> </li> <li id="GUID-8FFDD522-7CE8-5627-A630-100562B6AC61"><p> <codeph>TPositionUpdateOptions::SetAcceptPartialUpdates(EFalse)</codeph> meaning the partial updates are not returned </p> </li> </ul> <p>When setting update options, a client should beware of causing unexpected side effects. For example, if a client wants to accept partial updates, it might do the following: </p> <ul><li id="GUID-2C3A765E-9000-55D0-AF80-959E30FC6BCF"><p>Create a new <codeph>TPositionUpdateOptions</codeph> options object </p> </li> <li id="GUID-412495C8-DD14-5F18-B49A-4AB577F7ADFA"><p>Call <codeph>TPositionUpdateOptions::SetAcceptPartialUpdates(ETrue)</codeph>  </p> </li> <li id="GUID-0F75DB2C-A3AE-50DD-AE5F-A9C0767E92EF"><p>Call <codeph>RPositioner::SetUpdateOptions()</codeph> passing the options object as a parameter </p> </li> </ul> <p>However, this process has the side-effect of setting all the other update options to their default values as described above. In particular the client request will now not timeout which is unlikely to be the desired behaviour. To avoid this, a client should usually modify the current update options as follows: </p> <ul><li id="GUID-95B83378-4262-5861-A17A-1813DA6FC339"><p>Get the current update options by calling <xref href="GUID-1EAEB7EF-0AC7-37C7-B35F-C9B780FFC575.dita#GUID-1EAEB7EF-0AC7-37C7-B35F-C9B780FFC575/GUID-69E1F34F-FEF9-3E0C-88B6-DE0458E005A5"><apiname>RPositioner::GetUpdateOptions()</apiname></xref>  </p> </li> <li id="GUID-7C5DE68E-D192-551F-8F30-F4DC35E9D736"><p>Call the appropriate <codeph>TPositionUpdateOptions::SetXXX()</codeph> methods for the options to be changed </p> </li> <li id="GUID-E889905E-5AE5-53D0-BA99-8F430EAC3177"><p>Call <codeph>RPositioner::SetUpdateOptions()</codeph> passing the modified options object as a parameter </p> </li> </ul> <p><b>Examples </b> </p> <p>The following code shows a simple example of how to set update options. Note that all the options are changed by the client. </p> <codeblock id="GUID-A6C75044-19AF-5A77-BB17-18F4B8AA32EE" xml:space="preserve">...
51a74ef9ed63 Week 12 contribution of API Specs and fix SDK submission
Dominic Pinkman <Dominic.Pinkman@Nokia.com>
parents:
diff changeset
    84
51a74ef9ed63 Week 12 contribution of API Specs and fix SDK submission
Dominic Pinkman <Dominic.Pinkman@Nokia.com>
parents:
diff changeset
    85
TPositionUpdateOptions options;
51a74ef9ed63 Week 12 contribution of API Specs and fix SDK submission
Dominic Pinkman <Dominic.Pinkman@Nokia.com>
parents:
diff changeset
    86
51a74ef9ed63 Week 12 contribution of API Specs and fix SDK submission
Dominic Pinkman <Dominic.Pinkman@Nokia.com>
parents:
diff changeset
    87
// Frequency of updates in microseconds
51a74ef9ed63 Week 12 contribution of API Specs and fix SDK submission
Dominic Pinkman <Dominic.Pinkman@Nokia.com>
parents:
diff changeset
    88
const TTimeIntervalMicroSeconds KUpdateInterval(2000000);
51a74ef9ed63 Week 12 contribution of API Specs and fix SDK submission
Dominic Pinkman <Dominic.Pinkman@Nokia.com>
parents:
diff changeset
    89
51a74ef9ed63 Week 12 contribution of API Specs and fix SDK submission
Dominic Pinkman <Dominic.Pinkman@Nokia.com>
parents:
diff changeset
    90
// How long the application is willing to wait before timing out the request
51a74ef9ed63 Week 12 contribution of API Specs and fix SDK submission
Dominic Pinkman <Dominic.Pinkman@Nokia.com>
parents:
diff changeset
    91
const TTimeIntervalMicroSeconds KTimeOut(4000000);
51a74ef9ed63 Week 12 contribution of API Specs and fix SDK submission
Dominic Pinkman <Dominic.Pinkman@Nokia.com>
parents:
diff changeset
    92
51a74ef9ed63 Week 12 contribution of API Specs and fix SDK submission
Dominic Pinkman <Dominic.Pinkman@Nokia.com>
parents:
diff changeset
    93
// The maximum acceptable age of the information in an update
51a74ef9ed63 Week 12 contribution of API Specs and fix SDK submission
Dominic Pinkman <Dominic.Pinkman@Nokia.com>
parents:
diff changeset
    94
const TTimeIntervalMicroSeconds KMaxUpdateAge(1000000);
51a74ef9ed63 Week 12 contribution of API Specs and fix SDK submission
Dominic Pinkman <Dominic.Pinkman@Nokia.com>
parents:
diff changeset
    95
51a74ef9ed63 Week 12 contribution of API Specs and fix SDK submission
Dominic Pinkman <Dominic.Pinkman@Nokia.com>
parents:
diff changeset
    96
options.SetUpdateInterval(KUpdateInterval);
51a74ef9ed63 Week 12 contribution of API Specs and fix SDK submission
Dominic Pinkman <Dominic.Pinkman@Nokia.com>
parents:
diff changeset
    97
options.SetUpdateTimeOut(KTimeOut);
51a74ef9ed63 Week 12 contribution of API Specs and fix SDK submission
Dominic Pinkman <Dominic.Pinkman@Nokia.com>
parents:
diff changeset
    98
options.SetMaxUpdateAge(KMaxUpdateAge);
51a74ef9ed63 Week 12 contribution of API Specs and fix SDK submission
Dominic Pinkman <Dominic.Pinkman@Nokia.com>
parents:
diff changeset
    99
options.SetAcceptPartialUpdates(EFalse);
51a74ef9ed63 Week 12 contribution of API Specs and fix SDK submission
Dominic Pinkman <Dominic.Pinkman@Nokia.com>
parents:
diff changeset
   100
51a74ef9ed63 Week 12 contribution of API Specs and fix SDK submission
Dominic Pinkman <Dominic.Pinkman@Nokia.com>
parents:
diff changeset
   101
User::LeaveIfError(positioner.SetUpdateOptions(options));
51a74ef9ed63 Week 12 contribution of API Specs and fix SDK submission
Dominic Pinkman <Dominic.Pinkman@Nokia.com>
parents:
diff changeset
   102
51a74ef9ed63 Week 12 contribution of API Specs and fix SDK submission
Dominic Pinkman <Dominic.Pinkman@Nokia.com>
parents:
diff changeset
   103
/* Now when the application requests location information
51a74ef9ed63 Week 12 contribution of API Specs and fix SDK submission
Dominic Pinkman <Dominic.Pinkman@Nokia.com>
parents:
diff changeset
   104
it will be provided with these options */ 
51a74ef9ed63 Week 12 contribution of API Specs and fix SDK submission
Dominic Pinkman <Dominic.Pinkman@Nokia.com>
parents:
diff changeset
   105
51a74ef9ed63 Week 12 contribution of API Specs and fix SDK submission
Dominic Pinkman <Dominic.Pinkman@Nokia.com>
parents:
diff changeset
   106
positioner.NotifyPositionUpdate(posInfo, status);
51a74ef9ed63 Week 12 contribution of API Specs and fix SDK submission
Dominic Pinkman <Dominic.Pinkman@Nokia.com>
parents:
diff changeset
   107
51a74ef9ed63 Week 12 contribution of API Specs and fix SDK submission
Dominic Pinkman <Dominic.Pinkman@Nokia.com>
parents:
diff changeset
   108
...
51a74ef9ed63 Week 12 contribution of API Specs and fix SDK submission
Dominic Pinkman <Dominic.Pinkman@Nokia.com>
parents:
diff changeset
   109
51a74ef9ed63 Week 12 contribution of API Specs and fix SDK submission
Dominic Pinkman <Dominic.Pinkman@Nokia.com>
parents:
diff changeset
   110
</codeblock> <p>The following code example shows an example of how to change one update option (to accept partial updates). </p> <codeblock id="GUID-6AEAAEBA-0841-502C-A6AF-11E9A5B5BD88" xml:space="preserve">...
51a74ef9ed63 Week 12 contribution of API Specs and fix SDK submission
Dominic Pinkman <Dominic.Pinkman@Nokia.com>
parents:
diff changeset
   111
51a74ef9ed63 Week 12 contribution of API Specs and fix SDK submission
Dominic Pinkman <Dominic.Pinkman@Nokia.com>
parents:
diff changeset
   112
TPositionUpdateOptions options;
51a74ef9ed63 Week 12 contribution of API Specs and fix SDK submission
Dominic Pinkman <Dominic.Pinkman@Nokia.com>
parents:
diff changeset
   113
51a74ef9ed63 Week 12 contribution of API Specs and fix SDK submission
Dominic Pinkman <Dominic.Pinkman@Nokia.com>
parents:
diff changeset
   114
User::LeaveIfError(positioner.GetUpdateOptions(options));
51a74ef9ed63 Week 12 contribution of API Specs and fix SDK submission
Dominic Pinkman <Dominic.Pinkman@Nokia.com>
parents:
diff changeset
   115
options.SetAcceptPartialUpdates(ETrue);
51a74ef9ed63 Week 12 contribution of API Specs and fix SDK submission
Dominic Pinkman <Dominic.Pinkman@Nokia.com>
parents:
diff changeset
   116
User::LeaveIfError(positioner.SetUpdateOptions(options));
51a74ef9ed63 Week 12 contribution of API Specs and fix SDK submission
Dominic Pinkman <Dominic.Pinkman@Nokia.com>
parents:
diff changeset
   117
51a74ef9ed63 Week 12 contribution of API Specs and fix SDK submission
Dominic Pinkman <Dominic.Pinkman@Nokia.com>
parents:
diff changeset
   118
// The other update options are unchanged
51a74ef9ed63 Week 12 contribution of API Specs and fix SDK submission
Dominic Pinkman <Dominic.Pinkman@Nokia.com>
parents:
diff changeset
   119
51a74ef9ed63 Week 12 contribution of API Specs and fix SDK submission
Dominic Pinkman <Dominic.Pinkman@Nokia.com>
parents:
diff changeset
   120
positioner.NotifyPositionUpdate(posInfo, status);
51a74ef9ed63 Week 12 contribution of API Specs and fix SDK submission
Dominic Pinkman <Dominic.Pinkman@Nokia.com>
parents:
diff changeset
   121
51a74ef9ed63 Week 12 contribution of API Specs and fix SDK submission
Dominic Pinkman <Dominic.Pinkman@Nokia.com>
parents:
diff changeset
   122
...
51a74ef9ed63 Week 12 contribution of API Specs and fix SDK submission
Dominic Pinkman <Dominic.Pinkman@Nokia.com>
parents:
diff changeset
   123
51a74ef9ed63 Week 12 contribution of API Specs and fix SDK submission
Dominic Pinkman <Dominic.Pinkman@Nokia.com>
parents:
diff changeset
   124
</codeblock> <p> <b>Notes</b>  </p> <p>When 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> or <xref href="GUID-1EAEB7EF-0AC7-37C7-B35F-C9B780FFC575.dita#GUID-1EAEB7EF-0AC7-37C7-B35F-C9B780FFC575/GUID-D9E0BC1D-7783-35BA-8D88-223576E4C85E"><apiname>RPositioner::GetLastKnownPosition()</apiname></xref> completes, it is necessary to re-issue the request by calling one of these methods again to obtain further updates even if <xref href="GUID-1EAEB7EF-0AC7-37C7-B35F-C9B780FFC575.dita#GUID-1EAEB7EF-0AC7-37C7-B35F-C9B780FFC575/GUID-7A8BC23A-6FF9-3AAF-99BF-A6B074FDEA7B"><apiname>RPositioner::SetUpdateOptions()</apiname></xref> has been called. Setting update options allows a client to specify when the next position update is required, but does not cause periodic requests to the Location Server to be made. </p> <p>A client application can only have one outstanding request for location information per <codeph>RPositioner</codeph> subsession. An attempt to make a second request for location information while one is still outstanding causes a panic to occur. An application must cancel an outstanding request before it makes another request. This process is described in step 7. </p> <p><b>5. Request the location information </b> </p> <p>An application can call one the following methods to obtain position data: </p> <ul><li id="GUID-8026ACFD-3519-5917-B64C-6BB5349E0793"><p> <i>RPositioner::NotifyPositionUpdate()</i>  </p> <p>A client application 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> to request a position update. The LBS subsystem can either request that a Positioning Module obtains a new position and returns it to the client or simply returns an existing position calculated at some earlier time. The precise action taken by LBS depends on the quality of position required by the client because it is possible that a position obtained some time ago may meet the client application's position quality requirements. </p> <p> <codeph>RPositioner::NotifyPositionUpdate()</codeph> is a client-server asynchronous call. The client application can pass any position info class that derives from <xref href="GUID-73D6F438-C270-33B9-974B-D4D1583E1738.dita"><apiname>TPositionInfoBase</apiname></xref>. The standard position info class is <xref href="GUID-D5B2E933-209D-3871-8E27-CC5C8855C745.dita"><apiname>TPositionInfo</apiname></xref> which is supported by all Positioning Modules. An application can get extended location information (if there is a Positioning Module that can supply it) by passing one of the specialised position info classes such as <xref href="GUID-E438D9D8-8DC2-39E3-B5D2-9EBD1D2EED82.dita"><apiname>TCourseInfo</apiname></xref> or <xref href="GUID-54AE0674-C49D-3329-8B77-3A58EFFC03D7.dita"><apiname>TPositionSatelliteInfo</apiname></xref> instead of <xref href="GUID-D5B2E933-209D-3871-8E27-CC5C8855C745.dita"><apiname>TPositionInfo</apiname></xref>. </p> <p>See <xref href="GUID-ABC01315-D65D-55EA-9D42-4DE6384D517D.dita">Position data and info classes</xref> for more information about position data and wrapper info classes. </p> </li> <li id="GUID-8C8CD6DD-5ED1-5F73-9FCD-611579838CD0"><p> <i>RPositioner::GetLastKnownPosition()</i>  </p> <p>A client application calls <xref href="GUID-1EAEB7EF-0AC7-37C7-B35F-C9B780FFC575.dita#GUID-1EAEB7EF-0AC7-37C7-B35F-C9B780FFC575/GUID-D9E0BC1D-7783-35BA-8D88-223576E4C85E"><apiname>RPositioner::GetLastKnownPosition()</apiname></xref> to request the device's last known position. </p> <p> <codeph>RPositioner::GetLastKnownPosition()</codeph> is a client-server asynchronous call. Calling this method does not instigate a new position fix even if the LBS subsystem does not have a last known position. It is therefore possible that this method will fail to return a position if one was not previously calculated. Client applications must check for this possibility by checking the values of <codeph>TCoordinate::Latitude()</codeph> and <codeph>TCoordinate::Longitude()</codeph> of the <xref href="GUID-AB9F288E-86C6-327A-9E53-2EA746416038.dita"><apiname>TPosition</apiname></xref> object inside of the <xref href="GUID-D5B2E933-209D-3871-8E27-CC5C8855C745.dita"><apiname>TPositionInfo</apiname></xref> parameter. If latitude and longitude data are not available they are set to <codeph>NaN</codeph> (Not a Number). An application may also need to check the timestamp of the information to ensure it still meets its needs as it is possible that the last position update was obtained some time ago. </p> <p>If the LBS subsystem has a position from a previous request a call to <xref href="GUID-1EAEB7EF-0AC7-37C7-B35F-C9B780FFC575.dita#GUID-1EAEB7EF-0AC7-37C7-B35F-C9B780FFC575/GUID-D9E0BC1D-7783-35BA-8D88-223576E4C85E"><apiname>RPositioner::GetLastKnownPosition()</apiname></xref> is more efficient in terms of request response time and device power consumption. It may also be cheaper for the mobile device owner who may be charged to obtain a new position. </p> </li> <li id="GUID-462ACD7E-9E6E-5366-8538-4EF5416CB2E7"><p> <i>RPositioner::GetLastKnownPositionArea()</i>  </p> <p>A client application calls <xref href="GUID-1EAEB7EF-0AC7-37C7-B35F-C9B780FFC575.dita#GUID-1EAEB7EF-0AC7-37C7-B35F-C9B780FFC575/GUID-A8484963-B2C4-339D-AF8C-056792444D89"><apiname>RPositioner::GetLastKnownPositionArea()</apiname></xref> to request the last known position that most closely matches the device's current location. The device's current location is estimated from the network cell ID received from the network. </p> <p> <codeph>RPositioner::GetLastKnownPositionArea()</codeph> is a client-server asynchronous call. The client application can request the LBS subsystem to provide either basic or the extended area information. The exact signature of the method is as follows: </p> <p> <codeph>RPositioner::GetLastKnownPositionArea(TPositionInfoBase&amp;
51a74ef9ed63 Week 12 contribution of API Specs and fix SDK submission
Dominic Pinkman <Dominic.Pinkman@Nokia.com>
parents:
diff changeset
   125
                  aPosInfo, TPositionAreaInfoBase&amp; aAreaInfo, TRequestStatus&amp; aStatus)
51a74ef9ed63 Week 12 contribution of API Specs and fix SDK submission
Dominic Pinkman <Dominic.Pinkman@Nokia.com>
parents:
diff changeset
   126
                  const;</codeph>  </p> <p>A client passes in <codeph>aPosInfo</codeph>, <codeph>aAreaInfo</codeph> and <codeph>aStatus</codeph> parameters. </p> <ul><li id="GUID-44BEA85B-1CFF-5380-B9FE-8659029CD52D"><p>On completion, <codeph>aPosInfo</codeph> contains the last known position that is the best match with information received from the network. </p> </li> <li id="GUID-8A708090-5281-5BC7-8EFE-A935317F9531"><p> <codeph>aAreaInfo</codeph> contains an estimate of the accuracy of the last known position. <codeph>TPositionAreaInfoBase</codeph> is the base class for two position area data classes. A client can pass a <xref href="GUID-5FA78254-70C7-3105-B6CE-E1A294C8F773.dita"><apiname>TPositionAreaInfo</apiname></xref> object to get basic position accuracy information, or it can pass a <xref href="GUID-BC7DEDAF-80AE-34DC-8FD8-CF77FA511B3D.dita"><apiname>TPositionAreaExtendedInfo</apiname></xref> object to get extra information about how the accuracy estimate was calculated. </p> </li> </ul> <p>If successful, <codeph>GetLastKnownPositionArea()</codeph> returns the best matching last known position in the <codeph>aPosInfo</codeph> parameter, an estimate of the position accuracy in the <codeph>aAreaInfo</codeph> parameter and a result code of <codeph>KErrNone</codeph>. </p> <p>See <xref href="GUID-1EAEB7EF-0AC7-37C7-B35F-C9B780FFC575.dita#GUID-1EAEB7EF-0AC7-37C7-B35F-C9B780FFC575/GUID-A8484963-B2C4-339D-AF8C-056792444D89"><apiname>RPositioner::GetLastKnownPositionArea()</apiname></xref> for more information about using this method and the returned error codes. </p> <p>See <xref href="GUID-70E1117B-17F0-5CF4-A5D0-35D3BEBB0FEA.dita">Position Area Data Classes</xref> for information about the classes that used to obtain the position accuracy estimate. </p> <p>The following code fragment shows how to use the method and check the accuracy of the returned position: </p> <codeblock id="GUID-2AC03D72-4105-5752-A294-08D64CAFB3A5" xml:space="preserve">
51a74ef9ed63 Week 12 contribution of API Specs and fix SDK submission
Dominic Pinkman <Dominic.Pinkman@Nokia.com>
parents:
diff changeset
   127
// Create an RPositionServer, RPositioner, TRequestStatus as normal and open a session (see above)
51a74ef9ed63 Week 12 contribution of API Specs and fix SDK submission
Dominic Pinkman <Dominic.Pinkman@Nokia.com>
parents:
diff changeset
   128
51a74ef9ed63 Week 12 contribution of API Specs and fix SDK submission
Dominic Pinkman <Dominic.Pinkman@Nokia.com>
parents:
diff changeset
   129
...
51a74ef9ed63 Week 12 contribution of API Specs and fix SDK submission
Dominic Pinkman <Dominic.Pinkman@Nokia.com>
parents:
diff changeset
   130
51a74ef9ed63 Week 12 contribution of API Specs and fix SDK submission
Dominic Pinkman <Dominic.Pinkman@Nokia.com>
parents:
diff changeset
   131
// Want to know basic position accuracy, so use TPositionAreaInfo
51a74ef9ed63 Week 12 contribution of API Specs and fix SDK submission
Dominic Pinkman <Dominic.Pinkman@Nokia.com>
parents:
diff changeset
   132
51a74ef9ed63 Week 12 contribution of API Specs and fix SDK submission
Dominic Pinkman <Dominic.Pinkman@Nokia.com>
parents:
diff changeset
   133
TRequestStatus status;
51a74ef9ed63 Week 12 contribution of API Specs and fix SDK submission
Dominic Pinkman <Dominic.Pinkman@Nokia.com>
parents:
diff changeset
   134
TPositionInfo posInfo;
51a74ef9ed63 Week 12 contribution of API Specs and fix SDK submission
Dominic Pinkman <Dominic.Pinkman@Nokia.com>
parents:
diff changeset
   135
TPositionAreaInfo areaInfo;
51a74ef9ed63 Week 12 contribution of API Specs and fix SDK submission
Dominic Pinkman <Dominic.Pinkman@Nokia.com>
parents:
diff changeset
   136
51a74ef9ed63 Week 12 contribution of API Specs and fix SDK submission
Dominic Pinkman <Dominic.Pinkman@Nokia.com>
parents:
diff changeset
   137
// Get the last known location and an estimate of its accuracy
51a74ef9ed63 Week 12 contribution of API Specs and fix SDK submission
Dominic Pinkman <Dominic.Pinkman@Nokia.com>
parents:
diff changeset
   138
51a74ef9ed63 Week 12 contribution of API Specs and fix SDK submission
Dominic Pinkman <Dominic.Pinkman@Nokia.com>
parents:
diff changeset
   139
positioner.GetLastKnownLocationArea(posInfo, areaInfo, status);
51a74ef9ed63 Week 12 contribution of API Specs and fix SDK submission
Dominic Pinkman <Dominic.Pinkman@Nokia.com>
parents:
diff changeset
   140
User::WaitForRequest(status);
51a74ef9ed63 Week 12 contribution of API Specs and fix SDK submission
Dominic Pinkman <Dominic.Pinkman@Nokia.com>
parents:
diff changeset
   141
51a74ef9ed63 Week 12 contribution of API Specs and fix SDK submission
Dominic Pinkman <Dominic.Pinkman@Nokia.com>
parents:
diff changeset
   142
// Check the return status 
51a74ef9ed63 Week 12 contribution of API Specs and fix SDK submission
Dominic Pinkman <Dominic.Pinkman@Nokia.com>
parents:
diff changeset
   143
51a74ef9ed63 Week 12 contribution of API Specs and fix SDK submission
Dominic Pinkman <Dominic.Pinkman@Nokia.com>
parents:
diff changeset
   144
if ( status == KErrNone )
51a74ef9ed63 Week 12 contribution of API Specs and fix SDK submission
Dominic Pinkman <Dominic.Pinkman@Nokia.com>
parents:
diff changeset
   145
 {
51a74ef9ed63 Week 12 contribution of API Specs and fix SDK submission
Dominic Pinkman <Dominic.Pinkman@Nokia.com>
parents:
diff changeset
   146
51a74ef9ed63 Week 12 contribution of API Specs and fix SDK submission
Dominic Pinkman <Dominic.Pinkman@Nokia.com>
parents:
diff changeset
   147
 TPosition pos;
51a74ef9ed63 Week 12 contribution of API Specs and fix SDK submission
Dominic Pinkman <Dominic.Pinkman@Nokia.com>
parents:
diff changeset
   148
 posInfo.GetPosition(pos);
51a74ef9ed63 Week 12 contribution of API Specs and fix SDK submission
Dominic Pinkman <Dominic.Pinkman@Nokia.com>
parents:
diff changeset
   149
 TReal64 latitude = pos.Latitude();
51a74ef9ed63 Week 12 contribution of API Specs and fix SDK submission
Dominic Pinkman <Dominic.Pinkman@Nokia.com>
parents:
diff changeset
   150
 TReal64 longitude = pos.Longitude();
51a74ef9ed63 Week 12 contribution of API Specs and fix SDK submission
Dominic Pinkman <Dominic.Pinkman@Nokia.com>
parents:
diff changeset
   151
 TTime time = pos.Time();
51a74ef9ed63 Week 12 contribution of API Specs and fix SDK submission
Dominic Pinkman <Dominic.Pinkman@Nokia.com>
parents:
diff changeset
   152
51a74ef9ed63 Week 12 contribution of API Specs and fix SDK submission
Dominic Pinkman <Dominic.Pinkman@Nokia.com>
parents:
diff changeset
   153
 /*
51a74ef9ed63 Week 12 contribution of API Specs and fix SDK submission
Dominic Pinkman <Dominic.Pinkman@Nokia.com>
parents:
diff changeset
   154
 Check the posInfo object to see if it contains valid position data before trying to use it.
51a74ef9ed63 Week 12 contribution of API Specs and fix SDK submission
Dominic Pinkman <Dominic.Pinkman@Nokia.com>
parents:
diff changeset
   155
 Check position latitude, longitude and (if necessary) altitude for Math::IsNaN().
51a74ef9ed63 Week 12 contribution of API Specs and fix SDK submission
Dominic Pinkman <Dominic.Pinkman@Nokia.com>
parents:
diff changeset
   156
 Also a good idea to check the timestamp against current time, because this position could be old.
51a74ef9ed63 Week 12 contribution of API Specs and fix SDK submission
Dominic Pinkman <Dominic.Pinkman@Nokia.com>
parents:
diff changeset
   157
 Details omitted...
51a74ef9ed63 Week 12 contribution of API Specs and fix SDK submission
Dominic Pinkman <Dominic.Pinkman@Nokia.com>
parents:
diff changeset
   158
 */
51a74ef9ed63 Week 12 contribution of API Specs and fix SDK submission
Dominic Pinkman <Dominic.Pinkman@Nokia.com>
parents:
diff changeset
   159
51a74ef9ed63 Week 12 contribution of API Specs and fix SDK submission
Dominic Pinkman <Dominic.Pinkman@Nokia.com>
parents:
diff changeset
   160
 // Get the accuracy of the position
51a74ef9ed63 Week 12 contribution of API Specs and fix SDK submission
Dominic Pinkman <Dominic.Pinkman@Nokia.com>
parents:
diff changeset
   161
 TPositionAreaInfo::TArea area = areaInfo.Area();
51a74ef9ed63 Week 12 contribution of API Specs and fix SDK submission
Dominic Pinkman <Dominic.Pinkman@Nokia.com>
parents:
diff changeset
   162
 
51a74ef9ed63 Week 12 contribution of API Specs and fix SDK submission
Dominic Pinkman <Dominic.Pinkman@Nokia.com>
parents:
diff changeset
   163
 // Does this position meet your accuracy requirements?
51a74ef9ed63 Week 12 contribution of API Specs and fix SDK submission
Dominic Pinkman <Dominic.Pinkman@Nokia.com>
parents:
diff changeset
   164
51a74ef9ed63 Week 12 contribution of API Specs and fix SDK submission
Dominic Pinkman <Dominic.Pinkman@Nokia.com>
parents:
diff changeset
   165
 if (area == TPositionAreaInfo::EAreaCity)
51a74ef9ed63 Week 12 contribution of API Specs and fix SDK submission
Dominic Pinkman <Dominic.Pinkman@Nokia.com>
parents:
diff changeset
   166
  {
51a74ef9ed63 Week 12 contribution of API Specs and fix SDK submission
Dominic Pinkman <Dominic.Pinkman@Nokia.com>
parents:
diff changeset
   167
  
51a74ef9ed63 Week 12 contribution of API Specs and fix SDK submission
Dominic Pinkman <Dominic.Pinkman@Nokia.com>
parents:
diff changeset
   168
  /* 
51a74ef9ed63 Week 12 contribution of API Specs and fix SDK submission
Dominic Pinkman <Dominic.Pinkman@Nokia.com>
parents:
diff changeset
   169
  In this example, want city level position accuracy.
51a74ef9ed63 Week 12 contribution of API Specs and fix SDK submission
Dominic Pinkman <Dominic.Pinkman@Nokia.com>
parents:
diff changeset
   170
  Is this position accurate enough for your application?
51a74ef9ed63 Week 12 contribution of API Specs and fix SDK submission
Dominic Pinkman <Dominic.Pinkman@Nokia.com>
parents:
diff changeset
   171
  
51a74ef9ed63 Week 12 contribution of API Specs and fix SDK submission
Dominic Pinkman <Dominic.Pinkman@Nokia.com>
parents:
diff changeset
   172
  If not you could also check for EAreaDistrict and EAreaStreet.
51a74ef9ed63 Week 12 contribution of API Specs and fix SDK submission
Dominic Pinkman <Dominic.Pinkman@Nokia.com>
parents:
diff changeset
   173
  TPositionAreaInfo::_TArea defines the values you can check for.
51a74ef9ed63 Week 12 contribution of API Specs and fix SDK submission
Dominic Pinkman <Dominic.Pinkman@Nokia.com>
parents:
diff changeset
   174
  
51a74ef9ed63 Week 12 contribution of API Specs and fix SDK submission
Dominic Pinkman <Dominic.Pinkman@Nokia.com>
parents:
diff changeset
   175
  If this position is accurate enough, do something useful with your returned position data...
51a74ef9ed63 Week 12 contribution of API Specs and fix SDK submission
Dominic Pinkman <Dominic.Pinkman@Nokia.com>
parents:
diff changeset
   176
  
51a74ef9ed63 Week 12 contribution of API Specs and fix SDK submission
Dominic Pinkman <Dominic.Pinkman@Nokia.com>
parents:
diff changeset
   177
  If it is not accurate enough, you may need to get a new full position fix
51a74ef9ed63 Week 12 contribution of API Specs and fix SDK submission
Dominic Pinkman <Dominic.Pinkman@Nokia.com>
parents:
diff changeset
   178
  Call positioner.NotifyPositionUpdate() to do this.
51a74ef9ed63 Week 12 contribution of API Specs and fix SDK submission
Dominic Pinkman <Dominic.Pinkman@Nokia.com>
parents:
diff changeset
   179
  */
51a74ef9ed63 Week 12 contribution of API Specs and fix SDK submission
Dominic Pinkman <Dominic.Pinkman@Nokia.com>
parents:
diff changeset
   180
  
51a74ef9ed63 Week 12 contribution of API Specs and fix SDK submission
Dominic Pinkman <Dominic.Pinkman@Nokia.com>
parents:
diff changeset
   181
  }
51a74ef9ed63 Week 12 contribution of API Specs and fix SDK submission
Dominic Pinkman <Dominic.Pinkman@Nokia.com>
parents:
diff changeset
   182
 
51a74ef9ed63 Week 12 contribution of API Specs and fix SDK submission
Dominic Pinkman <Dominic.Pinkman@Nokia.com>
parents:
diff changeset
   183
 }
51a74ef9ed63 Week 12 contribution of API Specs and fix SDK submission
Dominic Pinkman <Dominic.Pinkman@Nokia.com>
parents:
diff changeset
   184
51a74ef9ed63 Week 12 contribution of API Specs and fix SDK submission
Dominic Pinkman <Dominic.Pinkman@Nokia.com>
parents:
diff changeset
   185
else
51a74ef9ed63 Week 12 contribution of API Specs and fix SDK submission
Dominic Pinkman <Dominic.Pinkman@Nokia.com>
parents:
diff changeset
   186
51a74ef9ed63 Week 12 contribution of API Specs and fix SDK submission
Dominic Pinkman <Dominic.Pinkman@Nokia.com>
parents:
diff changeset
   187
    {
51a74ef9ed63 Week 12 contribution of API Specs and fix SDK submission
Dominic Pinkman <Dominic.Pinkman@Nokia.com>
parents:
diff changeset
   188
51a74ef9ed63 Week 12 contribution of API Specs and fix SDK submission
Dominic Pinkman <Dominic.Pinkman@Nokia.com>
parents:
diff changeset
   189
 /*
51a74ef9ed63 Week 12 contribution of API Specs and fix SDK submission
Dominic Pinkman <Dominic.Pinkman@Nokia.com>
parents:
diff changeset
   190
 Function returned something other than KErrNone.
51a74ef9ed63 Week 12 contribution of API Specs and fix SDK submission
Dominic Pinkman <Dominic.Pinkman@Nokia.com>
parents:
diff changeset
   191
 It could be KErrNotFound which indicates that no stored position was found.
51a74ef9ed63 Week 12 contribution of API Specs and fix SDK submission
Dominic Pinkman <Dominic.Pinkman@Nokia.com>
parents:
diff changeset
   192
 Or it could be a system error code if something went wrong - you need to check it.
51a74ef9ed63 Week 12 contribution of API Specs and fix SDK submission
Dominic Pinkman <Dominic.Pinkman@Nokia.com>
parents:
diff changeset
   193
 */
51a74ef9ed63 Week 12 contribution of API Specs and fix SDK submission
Dominic Pinkman <Dominic.Pinkman@Nokia.com>
parents:
diff changeset
   194
51a74ef9ed63 Week 12 contribution of API Specs and fix SDK submission
Dominic Pinkman <Dominic.Pinkman@Nokia.com>
parents:
diff changeset
   195
 }
51a74ef9ed63 Week 12 contribution of API Specs and fix SDK submission
Dominic Pinkman <Dominic.Pinkman@Nokia.com>
parents:
diff changeset
   196
</codeblock> </li> </ul> <p>Client applications must always check the value of the <codeph>TRequestStatus</codeph> parameter as this indicates the success or failure of the location request and may indicate that specified location accuracy criteria could not be satisfied at the time of the request. </p> <p>The value of <codeph>TRequestStatus</codeph> that is set when a position update occurs or times out depends on the configuration of the LBS subsystem. See <xref href="GUID-4E56E531-5757-5740-9C7D-705D427FA9D5.dita">Location Acquisition API runtime behaviour</xref> for more information. </p> <p><b>6. Receive and use the location information </b> </p> <p>When the Location Server obtains a position, the client's <xref href="GUID-E0B34F3E-D4C4-3232-B8B1-7DB35B454646.dita"><apiname>TRequestStatus</apiname></xref> variable is updated. In the example, the <xref href="GUID-D5B2E933-209D-3871-8E27-CC5C8855C745.dita"><apiname>TPositionInfo</apiname></xref> object that was passed 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> holds the new position data in a <xref href="GUID-AB9F288E-86C6-327A-9E53-2EA746416038.dita"><apiname>TPosition</apiname></xref> object. </p> <p> <b>Important notes</b>  </p> <p>An application should test what kind of position is returned by <codeph>NotifyPositionUpdate()</codeph>. <xref href="GUID-73D6F438-C270-33B9-974B-D4D1583E1738.dita#GUID-73D6F438-C270-33B9-974B-D4D1583E1738/GUID-AC9654DD-2FC8-3B27-8743-83D7B8C58B79"><apiname>TPositionInfoBase::PositionMode()</apiname></xref> returns a bitmask value of type <xref href="GUID-B098F3DB-E2FE-3C5A-8508-4B04D954AB26.dita#GUID-B098F3DB-E2FE-3C5A-8508-4B04D954AB26/GUID-AE121191-0B6A-39D8-9379-386EFF58CF0A"><apiname>TPositionModuleInfo::TTechnologyType</apiname></xref> that is composed of values of type <xref href="GUID-B098F3DB-E2FE-3C5A-8508-4B04D954AB26.dita#GUID-B098F3DB-E2FE-3C5A-8508-4B04D954AB26/GUID-03AF8C51-1CAF-3F4C-BED1-17844FAE8423"><apiname>TPositionModuleInfo::_TTechnologyType</apiname></xref>. Valid combinations of this value are as follows: </p> <table id="GUID-8D2D95EF-9749-5D72-9F1D-FB878961DE84"><tgroup cols="2"><colspec colname="col0"/><colspec colname="col1"/><thead><row><entry>TPositionInfoBase::PositionMode()</entry> <entry>Meaning</entry> </row> </thead> <tbody><row><entry><p>ETechnologyNetwork </p> </entry> <entry><p>A reference position obtained from the network </p> </entry> </row> <row><entry><p>ETechnologyTerminal | ETechnologyAssisted </p> </entry> <entry><p>A position calculated using GPS with assistance data from the network </p> </entry> </row> <row><entry><p>ETechnologyNetwork | ETechnologyAssisted </p> </entry> <entry><p>A position calculated using GPS measurements by a remote server in the network </p> </entry> </row> <row><entry><p>ETechnologyTerminal </p> </entry> <entry><p>A position calculated using GPS without assistance data (autonomous mode) </p> </entry> </row> </tbody> </tgroup> </table> <p>A reference position <i>may</i> be returned to a client application by the Location Server before a more accurate position fix is available. Whether a reference position is made available to the Location Server depends on the implementation of the Positioning Modules by the Symbian device creator or handset manufacturer. </p> <p>If a reference position is returned, the behaviour is as follows: </p> <p> <b>For the first call to RPositioner::NotifyPositionUpdate()</b>  </p> <p> <codeph>NotifyPositionUpdate()</codeph> completes and a <i>reference position</i> is returned to the client. The client application can check for return of a reference position by checking for <codeph>TPositionInfoBase()::PositionMode() ==
51a74ef9ed63 Week 12 contribution of API Specs and fix SDK submission
Dominic Pinkman <Dominic.Pinkman@Nokia.com>
parents:
diff changeset
   197
             TPositionModuleInfo::ETechnologyNetwork</codeph>. If a reference position is returned it may not satisfy the application's position accuracy quality criteria and the application will need to make another <codeph>NotifyPositionUpdate()</codeph> request. </p> <p> <b>For subsequent calls to RPositioner::NotifyPositionUpdate()</b> (made by the same client subsession) </p> <p> <codeph>NotifyPositionUpdate()</codeph> completes and a position is returned to the client. This position may be either: </p> <ul><li id="GUID-F707A545-244D-5110-80CF-CBE9FFECC05C"><p>Calculated in the mobile device by GPS with assistance data (for Terminal Based Mode) </p> <p> <codeph>TPositionInfo::PositionMode() ==
51a74ef9ed63 Week 12 contribution of API Specs and fix SDK submission
Dominic Pinkman <Dominic.Pinkman@Nokia.com>
parents:
diff changeset
   198
                  TPositionInfoBase::ETechnologyTerminal |
51a74ef9ed63 Week 12 contribution of API Specs and fix SDK submission
Dominic Pinkman <Dominic.Pinkman@Nokia.com>
parents:
diff changeset
   199
                  TPositionInfoBase::ETechnologyAssisted</codeph>  </p> </li> <li id="GUID-289DE4DD-469D-58F0-8534-0B4353CDEC24"><p>Returned from the network, a position known as the <i>final network position</i> (for Terminal Assisted Mode) </p> <p>The value of <xref href="GUID-D5B2E933-209D-3871-8E27-CC5C8855C745.dita#GUID-D5B2E933-209D-3871-8E27-CC5C8855C745/GUID-A01CF36E-6EF9-395A-94DC-AB94478C66BE"><apiname>TPositionInfo::PositionMode()</apiname></xref> for a final network position depends on the configuration of the LBS subsystem: </p> <p>Normal behaviour is to return <codeph>TPositionInfo::PositionMode()
51a74ef9ed63 Week 12 contribution of API Specs and fix SDK submission
Dominic Pinkman <Dominic.Pinkman@Nokia.com>
parents:
diff changeset
   200
                  == TPositionModuleInfo::ETechnologyNetwork |
51a74ef9ed63 Week 12 contribution of API Specs and fix SDK submission
Dominic Pinkman <Dominic.Pinkman@Nokia.com>
parents:
diff changeset
   201
                  TPositionModuleInfo::ETechnologyAssisted</codeph>, but it is possible for LBS to return <codeph>TPositionModuleInfo::ETechnologyTerminal |
51a74ef9ed63 Week 12 contribution of API Specs and fix SDK submission
Dominic Pinkman <Dominic.Pinkman@Nokia.com>
parents:
diff changeset
   202
                  TPositionModuleInfo::ETechnologyAssisted</codeph> if it is configured to do so. See <xref href="GUID-4E56E531-5757-5740-9C7D-705D427FA9D5.dita">Location Acquisition API runtime behaviour</xref> for more information. </p> </li> </ul> <p>Note that <codeph>NotifyPositionUpdate()</codeph> may complete early if a GPS positioning module signals to LBS that it will be unable to return a location fix with the required quality criteria. In this case the Location Server returns the best location fix it can obtain to the client. The value of the <codeph>TRequestStatus</codeph> parameter of the client is set to either <codeph>KPositionQualityLoss</codeph> or <codeph>KErrNone</codeph> depending on the configuration of <xref href="GUID-4E56E531-5757-5740-9C7D-705D427FA9D5.dita">Location Acquisition API runtime behaviour</xref>. </p> <p><b>Tracking </b> </p> <p>A position update time line for tracking is shown in figure 2. Note that the exact behaviour of tracking on systems may differ from that shown in Figure 2. </p> <p>A client application has previously called <codeph>TPositionUpdateOptions::SetUpdateInterval(T)</codeph> and <codeph>RPositioner::SetUpdateOptions()</codeph> (not shown in figure 2). Partial updates are not set. LBS is also configured to return reference positions and accurate positions only (see <xref href="GUID-4E56E531-5757-5740-9C7D-705D427FA9D5.dita">Location Acquisition API runtime behaviour</xref> for more information about this behaviour). The important points are: </p> <ul><li id="GUID-644F7437-0207-5B16-B38C-C695DC5BB83B"><p>A client application makes its first call to <codeph>RPositioner::NotifyPositionUpdate()</codeph> (First NPUD in figure 2). </p> </li> <li id="GUID-E9F2BBA1-8F8A-516C-BB01-640535090820"><p>After a time t, the client's <codeph>RunL()</codeph> method is called and it receives its first position update (the reference position update Ref Pos in figure 2). This first position update is delivered to the client by LBS as soon as possible (t is as short as possible and is not equal to T). The client then makes its next call to <codeph>NotifyPositionUpdate()</codeph> (the next NPUD in figure 2). When tracking, a client application should make its next call to <codeph>RPositioner::NotifyPositionUpdate()</codeph> as soon as possible in its <codeph>RunL()</codeph> method. The time between the client's <codeph>RunL()</codeph> and the client's next NPUD is exaggerated for clarity in Figure 2. </p> </li> <li id="GUID-8D670561-5F51-5836-AA24-3B0CC0417BB7"><p>At a time t + T (where T is the update interval) the client's <codeph>RunL()</codeph> method is called and it receives the next position update (GPS Pos in figure 2). The client makes its next call to <codeph>NotifyPositionUpdate()</codeph>. </p> </li> <li id="GUID-E93AE6CA-DF93-56AD-B68B-A60A1B96F128"><p>The next position update is expected at time t + 2T, but in the case shown in figure 2 this is not possible (the mobile device may have moved into an area where the GPS signal is weak). In general if it is not possible to obtain an accurate GPS fix by time t + nT, but the fix is obtained a short time later, the next position update is delivered as soon as possible after time t + nT (after t + 2T in figure 2). </p> </li> <li id="GUID-9E52BD1C-7BD4-55F8-BF75-98669883C0CF"><p>The client makes its next call to <codeph>NotifyPositionUpdate()</codeph> and at time t + (n+1)T the next position update is delivered (at t + 3T in figure 2). </p> <p> <i>The important point to note is that LBS attempts to deliver position updates at regular times t + nT but the time interval between position updates may temporarily be greater than or less than T.</i>  </p> </li> <li id="GUID-A7F59CB4-BFC7-5F88-8AF2-C8D6C24122D9"><p>Note that if partial updates were enabled, an incomplete position would be delivered at time t + 2T if it were available. Also note that an inaccurate position would be delivered if one was available at that time and LBS was configured to return it. </p> <p> </p> </li> </ul> <fig id="GUID-916FB3EF-08C6-5A0C-8D72-881FEEC7C161"><title>
51a74ef9ed63 Week 12 contribution of API Specs and fix SDK submission
Dominic Pinkman <Dominic.Pinkman@Nokia.com>
parents:
diff changeset
   203
                Figure 2. Position updates when tracking 
51a74ef9ed63 Week 12 contribution of API Specs and fix SDK submission
Dominic Pinkman <Dominic.Pinkman@Nokia.com>
parents:
diff changeset
   204
             </title> <image href="GUID-C6DDF01D-DF54-5C65-9FAC-D3693D30819F_d0e272191_href.png" placement="inline"/></fig> <p><b>Error codes </b> </p> <p>The value of a client's <codeph>TRequestStatus</codeph> can be set to an LBS error code (defined in <filepath>lbserrors.h</filepath>) <i>or an error code defined in a licensee's Positioning Module</i>. An error causes <codeph>NotifyPositionUpdate()</codeph> to complete. An application should always check the value of <codeph>TRequestStatus</codeph> when its <codeph>RunL()</codeph> method is called. </p> <p><b>7. Cancel or complete a location information request </b> </p> <p>To cancel a location request a client application calls <xref href="GUID-BC95F637-51F6-3D99-9265-C6DFD903C5BC.dita#GUID-BC95F637-51F6-3D99-9265-C6DFD903C5BC/GUID-168130E7-459D-3108-9418-94773D802EAE"><apiname>RPositionerSubSessionBase::CancelRequest()</apiname></xref>, passing a <xref href="GUID-355E1EEF-A312-3BB8-9655-9DD6805A3CDD.dita"><apiname>EPositionerNotifyPositionUpdate</apiname></xref> parameter. The client's <codeph>TRequestStatus</codeph> is set to <codeph>KErrCancel</codeph> if the request was successfully cancelled and no position update is returned. </p> <p>To complete a location request early, a client application calls <xref href="GUID-BC95F637-51F6-3D99-9265-C6DFD903C5BC.dita#GUID-BC95F637-51F6-3D99-9265-C6DFD903C5BC/GUID-88F0FA62-BC72-3BC5-B42E-FA0A26F3E405"><apiname>RPositionerSubSessionBase::CompleteRequest()</apiname></xref> passing a <xref href="GUID-355E1EEF-A312-3BB8-9655-9DD6805A3CDD.dita"><apiname>EPositionerNotifyPositionUpdate</apiname></xref> parameter. Calling this method does not cancel the position update, but asks the Location Server to return any available position data. The returned position update may be different from that which would have been returned if the request had been allowed to complete normally. If the request is completed early, the client's <codeph>TRequestStatus</codeph> is set to <codeph>KPositionEarlyComplete</codeph>. </p> <p><b>8. Close the subsession and session </b> </p> <p> <xref href="GUID-1EAEB7EF-0AC7-37C7-B35F-C9B780FFC575.dita#GUID-1EAEB7EF-0AC7-37C7-B35F-C9B780FFC575/GUID-DE09BADB-6D90-3995-A893-F949F9C37A2B"><apiname>RPositioner::Close()</apiname></xref> closes the subsession. <xref href="GUID-0ADC4654-7F7B-3B53-A2F9-7035670F501B.dita#GUID-0ADC4654-7F7B-3B53-A2F9-7035670F501B/GUID-3D081F5B-F8D6-3168-951F-EDBC2364EB76"><apiname>RPositionServer::Close()</apiname></xref> closes the server session. In the code example the cleanup stack function is used. Any privacy requester objects created by a client must also be cleaned up. </p> </section> </conbody></concept>