|
1 <?xml version="1.0" encoding="utf-8"?> |
|
2 <!-- Copyright (c) 2007-2010 Nokia Corporation and/or its subsidiary(-ies) All rights reserved. --> |
|
3 <!-- This component and the accompanying materials are made available under the terms of the License |
|
4 "Eclipse Public License v1.0" which accompanies this distribution, |
|
5 and is available at the URL "http://www.eclipse.org/legal/epl-v10.html". --> |
|
6 <!-- Initial Contributors: |
|
7 Nokia Corporation - initial contribution. |
|
8 Contributors: |
|
9 --> |
|
10 <!DOCTYPE concept |
|
11 PUBLIC "-//OASIS//DTD DITA Concept//EN" "concept.dtd"> |
|
12 <concept id="GUID-A996FAAF-DB18-4F78-A8DA-873ACD771560" xml:lang="en"><title>Finding |
|
13 the location of a mobile device</title><prolog><metadata><keywords/></metadata></prolog><conbody> |
|
14 <p>The Location Acquisition API allows applications to access the <xref href="GUID-BC8D1F02-3FBB-406A-80CE-5836E61EBD82.dita">location information</xref> of |
|
15 a mobile device regardless of the <xref href="GUID-647F0CA5-5568-4C72-9CB5-C8CBF09B4B4B.dita">location |
|
16 technology</xref> used. </p> |
|
17 <p>Typical use cases include:</p> |
|
18 <ul> |
|
19 <li><p>Finding the location of a mobile device by using the Global |
|
20 Positioning System (GPS).</p></li> |
|
21 <li><p>Finding the location of a mobile device by network based |
|
22 positioning.</p></li> |
|
23 <li><p>Basic calculations using location information such as distances, |
|
24 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 |
|
25 Extended location information).</p></li> |
|
26 </ul> |
|
27 <p>Important implementation considerations include:</p> |
|
28 <ul> |
|
29 <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 |
|
30 they do not need positioning for an extended period of time. Also, when staying |
|
31 in background for more then a minute.<draft-comment time="2007-10-01T11:34">Question |
|
32 for the reviewers, is there any advice we can give the developers on this |
|
33 issue (For example, can developers use something in TPositionUpdateOptions |
|
34 to manage this issue?)</draft-comment></p></li> |
|
35 <li><p>The system automatically selects an appropriate positioning |
|
36 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>&aPosServer</codeph>) method. The system tries all available methods until it succeeds. Generally |
|
37 applications use this method. For special cases, applications can use Open |
|
38 (<xref href="jar:GUID-759FBC7F-5384-4487-8457-A8D4B76F6AA6.jar!/html/classRPositionServer.html" format="application/java-archive"><codeph>RPositionServer</codeph></xref> <codeph>&aPosServer</codeph>, <codeph>TPositionModuleId aModuleId</codeph>) to |
|
39 force system to use specified positioning method. In that case system does |
|
40 not fallback in case of failure</p></li> |
|
41 </ul> |
|
42 <note> |
|
43 <p>The Symbian SDK does not have a Map API, and therefore you must use |
|
44 a third party API to display the location information you receive on a map.</p> |
|
45 </note> |
|
46 <section id="GUID-7BB06E28-B1A5-4CBB-95B3-6F5735F945A6"><title>Getting the location |
|
47 of a device</title> |
|
48 <p>To find the location of a mobile device:</p> |
|
49 <ol> |
|
50 <li id="GUID-21F99413-A2DC-4588-856B-292FF3C0F6D4"><p>Use the methods |
|
51 of the Location Acquisition API to construct your application. </p> |
|
52 <itemgroup> |
|
53 <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 |
|
54 are particularly relevant in getting the location of your device, which is |
|
55 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> |
|
56 <p>For information on some detailed uses of the API, see the Location Acquisition |
|
57 API Usage section for:</p> |
|
58 <ul> |
|
59 <li><p>a list of the steps required for finding the location of |
|
60 a mobile device in a basic use case</p></li> |
|
61 <li><p>how to obtain the current location estimate</p></li> |
|
62 <li><p>how to obtain an extended location estimate, including information |
|
63 such as bearing, speed, and available satellites, which is not normally returned |
|
64 with the current location estimate</p></li> |
|
65 <li><p>how to obtain your last known position information, using |
|
66 cached information if available. This means that this method does not retrieve |
|
67 the location information from the underlying positioning methods.</p></li> |
|
68 </ul> |
|
69 </itemgroup> |
|
70 </li> |
|
71 <li id="GUID-AC8282F7-4916-4364-960A-0217659C57DD"><p>Make sure <codeph>lbs.lib</codeph> is |
|
72 accessible to your linker when compiling your application by including it |
|
73 in your <xref href="GUID-1F7E1476-D7A3-49E4-B05B-F3A0FD6333B6.dita"><codeph>mmp</codeph></xref> file |
|
74 or by editing the project properties in your IDE, depending on your build |
|
75 environment.</p></li> |
|
76 <li id="GUID-6AF9355F-BB88-4C44-A0C7-96ED3B0EF720"><p>Make sure |
|
77 you have the correct capabilities information set for your application, depending |
|
78 on your application you need at least <codeph>Location</codeph>.</p></li> |
|
79 </ol> |
|
80 </section> |
|
81 <section id="GUID-3D55E67C-8A43-4214-AB1C-0924285B6DA3"><title>Additional information |
|
82 on locating your device</title> |
|
83 <p>For more information, see:</p> |
|
84 <ul> |
|
85 <li><p>The purpose and general overview of the Location Acquisition |
|
86 API.</p></li> |
|
87 <li><p>The description and class structure of the API.</p></li> |
|
88 <li><p>A general overview on how to create applications using the |
|
89 API.</p></li> |
|
90 <li><p>The <codeph>LocationRefAppForS60</codeph> in the SDK (<codeph><SDK |
|
91 installation directory>\S60CppExamples\AutoAdaptedToTouchEx</codeph>), for |
|
92 an example of how to use the Location Acquisition API.</p></li> |
|
93 </ul> |
|
94 </section> |
|
95 <section id="GUID-94FC6381-CDB3-4F70-B3F5-66D450F827EC"><title>Related APIs</title> |
|
96 <p>The Symbian platform also offers the following related services:</p> |
|
97 <ul> |
|
98 <li><p><xref format="html" href="specs/guides/Exif_API_Specification/Exif_API_Specification.html" scope="external">EXIF |
|
99 API</xref></p> |
|
100 <itemgroup> |
|
101 <p>Allows you to include data, such as location information, in image files.</p> |
|
102 </itemgroup> |
|
103 </li> |
|
104 <li><p><xref format="html" href="specs/guides/Landmarks_API_Specification/Landmarks_API_Specification.html" scope="external">Landmarks |
|
105 API</xref></p> |
|
106 <itemgroup> |
|
107 <p>Allows you to <xref href="GUID-DF756D6C-1E03-4EC0-B074-09611D122359.dita">store |
|
108 location information on your mobile device</xref>.</p> |
|
109 </itemgroup> |
|
110 </li> |
|
111 <li><p><xref href="GUID-34A82EC4-E795-4884-A1F0-616BFB38F7C3.dita">Bluetooth</xref></p> |
|
112 <itemgroup> |
|
113 <p>Allows you to use Bluetooth functions when creating connections between |
|
114 your mobile device and a Bluetooth enabled GPS receiver.</p> |
|
115 </itemgroup> |
|
116 </li> |
|
117 <li><p><xref href="GUID-F6B5F777-D12F-5913-AECE-047DF8C72F1F.dita">How |
|
118 to Get Location Information</xref></p> |
|
119 <itemgroup> |
|
120 <p>Allows you to use the Location Acquisition API to obtain the position |
|
121 of the mobile device from the LBS subsystem.</p> |
|
122 </itemgroup> |
|
123 </li> |
|
124 </ul> |
|
125 </section> |
|
126 </conbody></concept> |