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