|
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-A4B47A7A-17EB-570C-AD88-6756B34AF634" xml:lang="en"><title>How |
|
13 to Use Positioning Module Information</title><shortdesc>This document describes how a client application uses the API to |
|
14 get information about the available Positioning Modules. </shortdesc><prolog><metadata><keywords/></metadata></prolog><conbody> |
|
15 <section><title>Purpose</title> <p>This section describes how a client application |
|
16 gets Positioning Module information using the Location Acquisition API and |
|
17 how this information can be used in a request for location information. </p> </section> |
|
18 <section><title>Required background</title> <p><xref href="GUID-BADAAC2D-8614-5036-95BC-3889457F7ED0.dita">Positioning |
|
19 Modules</xref> describes module concepts. </p> </section> |
|
20 <section><title>How to get information about all Positioning Modules</title> <p>Client |
|
21 applications use the <xref href="GUID-0ADC4654-7F7B-3B53-A2F9-7035670F501B.dita"><apiname>RPositionServer</apiname></xref> class to get information |
|
22 about the Positioning Modules available to the Location Server. Applications |
|
23 may want this information in order to choose a particular Positioning Module |
|
24 to use for location information requests. </p> <p>The following code is a |
|
25 simple example of how a client application can get Positioning Module information. |
|
26 The client specifies use of assisted GPS and accuracy better than 10 metres. </p> <codeblock id="GUID-CEB67C2F-3FE7-5622-BDD1-253264A5467B" xml:space="preserve">#include <lbs.h> |
|
27 #include <LbsErrors.h> |
|
28 |
|
29 RPositionServer server; |
|
30 |
|
31 TUint numModules; |
|
32 TPositionModuleId modId; |
|
33 TPositionModuleInfo modInfo; |
|
34 TPositionModuleStatus modStatus; |
|
35 |
|
36 TBool foundModule = EFalse; |
|
37 |
|
38 |
|
39 // 1. Create a session with the Location Server |
|
40 User::LeaveIfError(server.Connect()); |
|
41 CleanupClosePushL(server); |
|
42 |
|
43 // 2. Get the number of modules installed |
|
44 User::LeaveIfError(server.GetNumModules(numModules)); |
|
45 |
|
46 // 3. Iterate over the modules to get information about each module |
|
47 // 4. Get the availability of a module |
|
48 // 5. Get information about the module technology, quality etc. |
|
49 |
|
50 for (TUint I=0 ; I < numModules ; I++) |
|
51 { |
|
52 User::LeaveIfError(server.GetModuleInfoByIndex(I, modInfo)); |
|
53 |
|
54 /* Check module technology type and availability |
|
55 In this example - does the module support assisted capability |
|
56 and is the module available? */ |
|
57 |
|
58 if ( modInfo.IsAvailable() && (modInfo.TechnologyType() == ETechnologyAssisted) ) |
|
59 { |
|
60 |
|
61 /* Check module capabilities |
|
62 In this example does the module supply speed information? */ |
|
63 |
|
64 TCapabilities caps = modInfo.Capabilities(); |
|
65 if (caps & ECapabilitySpeed) |
|
66 { |
|
67 // Check module position quality |
|
68 TPositionQuality quality; |
|
69 modInfo.GetPositionQuality(quality); |
|
70 |
|
71 // In this example, check for horizontal accuracy better than 10 metres |
|
72 if ( !quality.HorizontalAccuracy().IsNaN() && quality.HorizontalAccuracy() < 10 ) |
|
73 { |
|
74 // This module has all the required characteristics! |
|
75 modId = modInfo.ModuleId(); |
|
76 foundModule = ETrue; |
|
77 break; // stop searching |
|
78 } |
|
79 } |
|
80 } |
|
81 } |
|
82 |
|
83 if (foundModule) |
|
84 { |
|
85 // Can use the module to get location information |
|
86 ... |
|
87 } |
|
88 else |
|
89 { |
|
90 // No module meets these requirements. Look for another? |
|
91 ... |
|
92 } |
|
93 |
|
94 // 6. Close the server session |
|
95 CleanupStack::PopAndDestroy(&server); |
|
96 |
|
97 </codeblock> <p>The following sections describe the steps to get Positioning |
|
98 Module information: </p> <p><b>1. Create a session with the Location Server </b> </p> <p>A client application |
|
99 creates a session with the Location Server from which Positioning Module information |
|
100 is obtained. Note that if a server session has been created already (for example |
|
101 to get location information) then the application must use it. If the application |
|
102 attempts to open a second session with the server a panic will occur. </p> <p><b>2. Get the number of Positioning Modules installed </b> </p> <p>The number |
|
103 of installed Positioning Modules is known to the Location Server and is available |
|
104 to client applications by calling <xref href="GUID-0ADC4654-7F7B-3B53-A2F9-7035670F501B.dita#GUID-0ADC4654-7F7B-3B53-A2F9-7035670F501B/GUID-75239E9F-6062-3EA2-8830-D0E4D5BE0E64"><apiname>RPositionServer::GetNumModules()</apiname></xref>. </p> <p><b>3. Iterate over the Positioning Modules to get information about each |
|
105 one </b> </p> <p>Once a client application knows the number of Positioning |
|
106 Modules, it can easily iterate over them to get information for each one by |
|
107 calling <xref href="GUID-0ADC4654-7F7B-3B53-A2F9-7035670F501B.dita#GUID-0ADC4654-7F7B-3B53-A2F9-7035670F501B/GUID-C5ED1EFB-FABC-30C4-8AD9-02344E52D8AF"><apiname>RPositionServer::GetModuleInfoByIndex()</apiname></xref>. </p> <p><b>4. Get the availability of a Positioning Module </b> </p> <p> <xref href="GUID-B098F3DB-E2FE-3C5A-8508-4B04D954AB26.dita#GUID-B098F3DB-E2FE-3C5A-8508-4B04D954AB26/GUID-1020CC8C-30B6-355B-8AB0-99E23DEE74D2"><apiname>TPositionModuleInfo::IsAvailable()</apiname></xref> returns |
|
108 the availability of a Positioning Module. If this method returns <codeph>EFalse</codeph> then |
|
109 the Positioning Module cannot be used. It may have been taken offline or there |
|
110 may be a device hardware problem. The availability will not change unless |
|
111 there is some kind of user intervention, such as bringing the unavailable |
|
112 Positioning Module back online in a control panel. </p> <p> <i>Note</i> </p> <p>A |
|
113 Positioning Module also has a status that can change over time. Module status |
|
114 provides more detailed information about a Positioning Module's state than |
|
115 a simple availability flag. Module status information is held in a <xref href="GUID-F8376F62-46F2-3E7C-9536-920DB6FC6039.dita"><apiname>TPositionModuleStatus</apiname></xref> object. |
|
116 A Positioning Module's status at a point in time is discovered by calling <xref href="GUID-0ADC4654-7F7B-3B53-A2F9-7035670F501B.dita#GUID-0ADC4654-7F7B-3B53-A2F9-7035670F501B/GUID-676FAC1B-1989-3D3C-84A5-DF82B874D7A3"><apiname>RPositionServer::GetModuleStatus()</apiname></xref>. </p> <p><b>5. Get information about the Positioning Module technology, capabilities |
|
117 and position quality </b> </p> <p> <xref href="GUID-B098F3DB-E2FE-3C5A-8508-4B04D954AB26.dita#GUID-B098F3DB-E2FE-3C5A-8508-4B04D954AB26/GUID-A806BBFD-007C-372A-95F5-A53FCE1BA07F"><apiname>TPositionModuleInfo::TechnologyType()</apiname></xref> returns |
|
118 information about the type of technology used by the Positioning Module. </p> <p> <xref href="GUID-B098F3DB-E2FE-3C5A-8508-4B04D954AB26.dita#GUID-B098F3DB-E2FE-3C5A-8508-4B04D954AB26/GUID-1C4AAC64-DAD0-39D7-BD39-3DEE548CEA84"><apiname>TPositionModuleInfo::Capabilities()</apiname></xref> returns |
|
119 a Positioning Module's capabilities as a bit mask. </p> <p> <xref href="GUID-B098F3DB-E2FE-3C5A-8508-4B04D954AB26.dita#GUID-B098F3DB-E2FE-3C5A-8508-4B04D954AB26/GUID-AE23F158-982D-388E-B188-D86E9951856E"><apiname>TPositionModuleInfo::GetPositionQuality()</apiname></xref> returns |
|
120 a <xref href="GUID-1AA235FA-CEC1-3853-8F96-C538C02B596D.dita"><apiname>TPositionQuality</apiname></xref> object that describes the quality of |
|
121 position that the Positioning Module can provide. </p> <p><b>6. Close the server session </b> </p> <p>If the server session is not |
|
122 needed for any further processing then the application must close it. </p> </section> |
|
123 <section><title>How to get information about a specific Positioning |
|
124 Module</title> <p>A client application calls <xref href="GUID-0ADC4654-7F7B-3B53-A2F9-7035670F501B.dita#GUID-0ADC4654-7F7B-3B53-A2F9-7035670F501B/GUID-068D63E2-BCA1-3575-B3A2-F87C80CEB61C"><apiname>RPositionServer::GetModuleById()</apiname></xref> to |
|
125 get information about a Positioning Module when its ID is known. </p> <codeblock id="GUID-F7A4BA9A-A02D-5439-95EF-237DBBCC2C0F" xml:space="preserve"> |
|
126 TPositionModuleInfo modInfo; |
|
127 |
|
128 // modId is known to the client application |
|
129 User::LeaveIfError(server.GetModuleInfoById(modId, modInfo)); |
|
130 ... |
|
131 </codeblock> </section> |
|
132 </conbody><related-links> |
|
133 <link href="GUID-F6B5F777-D12F-5913-AECE-047DF8C72F1F.dita"><linktext>How to Get |
|
134 Location Information</linktext></link> |
|
135 <link href="GUID-F5944819-2942-5ADA-A0AD-510D20BFBDEB.dita"><linktext>How to Get |
|
136 Module Status Changes</linktext></link> |
|
137 </related-links></concept> |