<?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 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>

                Figure 1. Simplified Terminal Based Mode Sequence 

             </title> <image href="GUID-D9C4D520-821D-5097-A63C-0BF4C7F59827_d0e267518_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;

#include <lbserrors.h>

...

RPositionServer server;

RPositioner positioner;

// 1. Create a session with the Location Server

User::LeaveIfError(server.Connect());

CleanupClosePushL(server);

// 2. Create a subsession with the Location Server using default positioning module

User::LeaveIfError(positioner.Open(server));

CleanupClosePushL(positioner);

// 3. Set the requester information - in this example define a requester stack... 

_LIT(KCntPhone, "+358501234567");

_LIT(KSrvName, "MyService");

RRequestorStack stack;

CRequestor* contact = CRequestor::NewLC(CRequestor::ERequestorContact, CRequestor::EFormatTelephone, KCntPhone);

stack.Append(contact);

CRequestor* service = CRequestor::NewLC(CRequestor::ERequestorService,    CRequestor::EFormatApplication, KSrvName);

stack.Append(service);

User::LeaveIfError(positioner.SetRequestor(stack));

TPositionInfo posInfo;

TPosition pos;

TRequestStatus status;

/* 4. To set update options, call RPositioner::SetUpdateOptions(). 

      See the description in section 4 below */

/* 5. Request location information

      Could also call positioner.GetLastKnownPosition(posInfo, status) 

      to get cached location information */

positioner.NotifyPositionUpdate(posInfo, status);

User::WaitForRequest(status);

// 6. Receive location information

if (status != KErrNone)

 {

 // Handle possible client/server errors

 ...

 }

// Get the position data object from the wrapper info object

posInfo.GetPosition(pos);

// Use the position data

...

// Reissue the location request if necessary by calling NotifyPositionUpdate() again

/* 7. To cancel or complete a location request a client

 calls RPositioner::CancelRequest() or RPositioner::CompleteRequest() */

// 8. Cleanup

stack.Reset();

CleanupStack::PopAndDestroy(service);

CleanupStack::PopAndDestroy(contact);

CleanupStack::PopAndDestroy(&positioner);

CleanupStack::PopAndDestroy(&server);

</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,

                  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

                  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

                  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

                  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

                  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">...

TPositionUpdateOptions options;

// Frequency of updates in microseconds

const TTimeIntervalMicroSeconds KUpdateInterval(2000000);

// How long the application is willing to wait before timing out the request

const TTimeIntervalMicroSeconds KTimeOut(4000000);

// The maximum acceptable age of the information in an update

const TTimeIntervalMicroSeconds KMaxUpdateAge(1000000);

options.SetUpdateInterval(KUpdateInterval);

options.SetUpdateTimeOut(KTimeOut);

options.SetMaxUpdateAge(KMaxUpdateAge);

options.SetAcceptPartialUpdates(EFalse);

User::LeaveIfError(positioner.SetUpdateOptions(options));

/* Now when the application requests location information

it will be provided with these options */ 

positioner.NotifyPositionUpdate(posInfo, status);

...

</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">...

TPositionUpdateOptions options;

User::LeaveIfError(positioner.GetUpdateOptions(options));

options.SetAcceptPartialUpdates(ETrue);

User::LeaveIfError(positioner.SetUpdateOptions(options));

// The other update options are unchanged

positioner.NotifyPositionUpdate(posInfo, status);

...

</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;

                  aPosInfo, TPositionAreaInfoBase& aAreaInfo, TRequestStatus& aStatus)

                  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">

// Create an RPositionServer, RPositioner, TRequestStatus as normal and open a session (see above)

...

// Want to know basic position accuracy, so use TPositionAreaInfo

TRequestStatus status;

TPositionInfo posInfo;

TPositionAreaInfo areaInfo;

// Get the last known location and an estimate of its accuracy

positioner.GetLastKnownLocationArea(posInfo, areaInfo, status);

User::WaitForRequest(status);

// Check the return status 

if ( status == KErrNone )

 {

 TPosition pos;

 posInfo.GetPosition(pos);

 TReal64 latitude = pos.Latitude();

 TReal64 longitude = pos.Longitude();

 TTime time = pos.Time();

 /*

 Check the posInfo object to see if it contains valid position data before trying to use it.

 Check position latitude, longitude and (if necessary) altitude for Math::IsNaN().

 Also a good idea to check the timestamp against current time, because this position could be old.

 Details omitted...

 */

 // Get the accuracy of the position

 TPositionAreaInfo::TArea area = areaInfo.Area();

 // Does this position meet your accuracy requirements?

 if (area == TPositionAreaInfo::EAreaCity)

  {

  /* 

  In this example, want city level position accuracy.

  Is this position accurate enough for your application?

  If not you could also check for EAreaDistrict and EAreaStreet.

  TPositionAreaInfo::_TArea defines the values you can check for.

  If this position is accurate enough, do something useful with your returned position data...

  If it is not accurate enough, you may need to get a new full position fix

  Call positioner.NotifyPositionUpdate() to do this.

  */

  }

 }

else

    {

 /*

 Function returned something other than KErrNone.

 It could be KErrNotFound which indicates that no stored position was found.

 Or it could be a system error code if something went wrong - you need to check it.

 */

 }

</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() ==

             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() ==

                  TPositionInfoBase::ETechnologyTerminal |

                  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()

                  == TPositionModuleInfo::ETechnologyNetwork |

                  TPositionModuleInfo::ETechnologyAssisted</codeph>, but it is possible for LBS to return <codeph>TPositionModuleInfo::ETechnologyTerminal |

                  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>

                Figure 2. Position updates when tracking 

             </title> <image href="GUID-C6DDF01D-DF54-5C65-9FAC-D3693D30819F_d0e268483_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>