<?xml version="1.0" encoding="utf-8"?>

<!-- Copyright (c) 2007-2010 Nokia Corporation and/or its subsidiary(-ies) All rights reserved. -->

<!-- This component and the accompanying materials are made available under the terms of the License 

"Eclipse Public License v1.0" which accompanies this distribution, 

and is available at the URL "http://www.eclipse.org/legal/epl-v10.html". -->

<!-- Initial Contributors:

    Nokia Corporation - initial contribution.

Contributors: 

-->

<!DOCTYPE concept

  PUBLIC "-//OASIS//DTD DITA Concept//EN" "concept.dtd">

<concept id="GUID-A996FAAF-DB18-4F78-A8DA-873ACD771560" xml:lang="en"><title>Finding

the location of a mobile device</title><prolog><metadata><keywords/></metadata></prolog><conbody>

<p>The Location Acquisition API allows applications to access the <xref href="GUID-BC8D1F02-3FBB-406A-80CE-5836E61EBD82.dita">location information</xref> of

a mobile device regardless of the <xref href="GUID-647F0CA5-5568-4C72-9CB5-C8CBF09B4B4B.dita">location

technology</xref> used. </p>

<p>Typical use cases include:</p>

<ul>

<li><p>Finding the location of a mobile device by using the Global

Positioning System (GPS).</p></li>

<li><p>Finding the location of a mobile device by network based

positioning.</p></li>

<li><p>Basic calculations using location information such as distances,

bearing, and timestamp (see <xref href="jar:GUID-759FBC7F-5384-4487-8457-A8D4B76F6AA6.jar!/html/classTPosition.html" format="application/java-archive"><codeph>TPosition</codeph></xref> and

Extended location information).</p></li>

</ul>

<p>Important implementation considerations include:</p>

<ul>

<li><p>Applications should close their <xref href="jar:GUID-759FBC7F-5384-4487-8457-A8D4B76F6AA6.jar!/html/classRPositioner.html" format="application/java-archive"><codeph>RPositioner</codeph></xref> when

they do not need positioning for an extended period of time. Also, when staying

in background for more then a minute.<draft-comment time="2007-10-01T11:34">Question

for the reviewers, is there any advice we can give the developers on this

issue (For example, can developers use something in TPositionUpdateOptions

to manage this issue?)</draft-comment></p></li>

<li><p>The system automatically selects an appropriate positioning

method, based on the type of the class given as input for Open (<xref href="jar:GUID-759FBC7F-5384-4487-8457-A8D4B76F6AA6.jar!/html/classRPositionServer.html" format="application/java-archive"><codeph>RPositionServer</codeph></xref> <codeph>&amp;aPosServer</codeph>) method. The system tries all available methods until it succeeds. Generally

applications use this method. For special cases, applications can use Open

(<xref href="jar:GUID-759FBC7F-5384-4487-8457-A8D4B76F6AA6.jar!/html/classRPositionServer.html" format="application/java-archive"><codeph>RPositionServer</codeph></xref> <codeph>&amp;aPosServer</codeph>, <codeph>TPositionModuleId aModuleId</codeph>) to

force system to use specified positioning method. In that case system does

not fallback in case of failure</p></li>

</ul>

<note>

<p>The Symbian SDK does not have a Map API, and therefore you must use

a third party API to display the location information you receive on a map.</p>

</note>

<section id="GUID-7BB06E28-B1A5-4CBB-95B3-6F5735F945A6"><title>Getting the location

of a device</title>

<p>To find the location of a mobile device:</p>

<ol>

<li id="GUID-21F99413-A2DC-4588-856B-292FF3C0F6D4"><p>Use the methods

of the Location Acquisition API to construct your application. </p>

<itemgroup>

<p>The <xref href="jar:GUID-759FBC7F-5384-4487-8457-A8D4B76F6AA6.jar!/html/classRPositionServer.html" format="application/java-archive"><codeph>RPositionServer</codeph></xref> and <xref href="jar:GUID-759FBC7F-5384-4487-8457-A8D4B76F6AA6.jar!/html/classRPositioner.html" format="application/java-archive"><codeph>RPositioner</codeph></xref> classes

are particularly relevant in getting the location of your device, which is

typically stored in the <xref href="jar:GUID-759FBC7F-5384-4487-8457-A8D4B76F6AA6.jar!/html/classTPositionInfo.html" format="application/java-archive"><codeph>TPositionInfo</codeph></xref> class.</p>

<p>For information on some detailed uses of the API, see the Location Acquisition

API Usage section for:</p>

<ul>

<li><p>a list of the steps required for finding the location of

a mobile device in a basic use case</p></li>

<li><p>how to obtain the current location estimate</p></li>

<li><p>how to obtain an extended location estimate, including information

such as bearing, speed, and available satellites, which is not normally returned

with the current location estimate</p></li>

<li><p>how to obtain your last known position information, using

cached information if available. This means that this method does not retrieve

the location information from the underlying positioning methods.</p></li>

</ul>

</itemgroup>

</li>

<li id="GUID-AC8282F7-4916-4364-960A-0217659C57DD"><p>Make sure <codeph>lbs.lib</codeph> is

accessible to your linker when compiling your application by including it

in your <xref href="GUID-1F7E1476-D7A3-49E4-B05B-F3A0FD6333B6.dita"><codeph>mmp</codeph></xref> file

or by editing the project properties in your IDE, depending on your build

environment.</p></li>

<li id="GUID-6AF9355F-BB88-4C44-A0C7-96ED3B0EF720"><p>Make sure

you have the correct capabilities information set for your application, depending

on your application you need at least <codeph>Location</codeph>.</p></li>

</ol>

</section>

<section id="GUID-3D55E67C-8A43-4214-AB1C-0924285B6DA3"><title>Additional information

on locating your device</title>

<p>For more information, see:</p>

<ul>

<li><p>The purpose and general overview of the Location Acquisition

API.</p></li>

<li><p>The description and class structure of the API.</p></li>

<li><p>A general overview on how to create applications using the

API.</p></li>

<li><p>The <codeph>LocationRefAppForS60</codeph> in the SDK (<codeph>&lt;SDK

installation directory&gt;\S60CppExamples\AutoAdaptedToTouchEx</codeph>), for

an example of how to use the Location Acquisition API.</p></li>

</ul>

</section>

<section id="GUID-94FC6381-CDB3-4F70-B3F5-66D450F827EC"><title>Related APIs</title>

<p>The Symbian platform also offers the following related services:</p>

<ul>

<li><p><xref format="html" href="specs/guides/Exif_API_Specification/Exif_API_Specification.html" scope="external">EXIF

API</xref></p>

<itemgroup>

<p>Allows you to include data, such as location information, in image files.</p>

</itemgroup>

</li>

<li><p><xref format="html" href="specs/guides/Landmarks_API_Specification/Landmarks_API_Specification.html" scope="external">Landmarks

API</xref></p>

<itemgroup>

<p>Allows you to <xref href="GUID-DF756D6C-1E03-4EC0-B074-09611D122359.dita">store

location information on your mobile device</xref>.</p>

</itemgroup>

</li>

<li><p><xref href="GUID-34A82EC4-E795-4884-A1F0-616BFB38F7C3.dita">Bluetooth</xref></p>

<itemgroup>

<p>Allows you to use Bluetooth functions when creating connections between

your mobile device and a Bluetooth enabled GPS receiver.</p>

</itemgroup>

</li>

<li><p><xref href="GUID-F6B5F777-D12F-5913-AECE-047DF8C72F1F.dita">How

to Get Location Information</xref></p>

<itemgroup>

<p>Allows you to use the Location Acquisition API to obtain the position

of the mobile device from the LBS subsystem.</p>

</itemgroup>

</li>

</ul>

</section>

</conbody></concept>