<?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-A4B47A7A-17EB-570C-AD88-6756B34AF634" xml:lang="en"><title>How+
−
to Use Positioning Module Information</title><shortdesc>This document describes how a client application uses the API to+
−
get information about the available Positioning Modules. </shortdesc><prolog><metadata><keywords/></metadata></prolog><conbody>+
−
<section><title>Purpose</title> <p>This section describes how a client application+
−
gets Positioning Module information using the Location Acquisition API and+
−
how this information can be used in a request for location information. </p> </section>+
−
<section><title>Required background</title> <p><xref href="GUID-BADAAC2D-8614-5036-95BC-3889457F7ED0.dita">Positioning+
−
Modules</xref> describes module concepts. </p> </section>+
−
<section><title>How to get information about all Positioning Modules</title> <p>Client+
−
applications use the <xref href="GUID-0ADC4654-7F7B-3B53-A2F9-7035670F501B.dita"><apiname>RPositionServer</apiname></xref> class to get information+
−
about the Positioning Modules available to the Location Server. Applications+
−
may want this information in order to choose a particular Positioning Module+
−
to use for location information requests. </p> <p>The following code is a+
−
simple example of how a client application can get Positioning Module information.+
−
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 &lt;lbs.h&gt;+
−
#include &lt;LbsErrors.h&gt;+
−
+
−
RPositionServer server;+
−
+
−
TUint numModules;+
−
TPositionModuleId modId;+
−
TPositionModuleInfo modInfo;+
−
TPositionModuleStatus modStatus;+
−
+
−
TBool foundModule = EFalse;+
−
+
−
+
−
// 1. Create a session with the Location Server+
−
User::LeaveIfError(server.Connect());+
−
CleanupClosePushL(server);+
−
+
−
// 2. Get the number of modules installed+
−
User::LeaveIfError(server.GetNumModules(numModules));+
−
+
−
// 3. Iterate over the modules to get information about each module+
−
// 4. Get the availability of a module+
−
// 5. Get information about the module technology, quality etc.+
−
+
−
for (TUint I=0 ; I &lt; numModules ; I++)+
−
 {+
−
 User::LeaveIfError(server.GetModuleInfoByIndex(I, modInfo));+
−
        +
−
 /* Check module technology type and availability +
−
    In this example - does the module support assisted capability+
−
    and is the module available? */+
−
 +
−
 if ( modInfo.IsAvailable() &amp;&amp; (modInfo.TechnologyType() == ETechnologyAssisted) )+
−
  {+
−
+
−
  /* Check module capabilities+
−
        In this example does the module supply speed information? */+
−
+
−
  TCapabilities caps = modInfo.Capabilities();+
−
  if (caps &amp; ECapabilitySpeed) +
−
   { +
−
   // Check module position quality+
−
   TPositionQuality quality;+
−
   modInfo.GetPositionQuality(quality);+
−
                                    +
−
   // In this example, check for horizontal accuracy better than 10 metres+
−
   if ( !quality.HorizontalAccuracy().IsNaN() &amp;&amp; quality.HorizontalAccuracy() &lt; 10 )+
−
    {+
−
    // This module has all the required characteristics!+
−
    modId = modInfo.ModuleId();+
−
    foundModule = ETrue;+
−
    break; // stop searching+
−
    }+
−
   }    +
−
  }+
−
 }+
−
+
−
if (foundModule)+
−
 {+
−
 // Can use the module to get location information+
−
 ...+
−
 }+
−
else +
−
 {+
−
    // No module meets these requirements. Look for another?+
−
    ...+
−
 }+
−
+
−
// 6. Close the server session+
−
CleanupStack::PopAndDestroy(&amp;server);+
−
+
−
</codeblock> <p>The following sections describe the steps to get Positioning+
−
Module information: </p> <p><b>1. Create a session with the Location Server </b> </p> <p>A client application+
−
creates a session with the Location Server from which Positioning Module information+
−
is obtained. Note that if a server session has been created already (for example+
−
to get location information) then the application must use it. If the application+
−
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+
−
of installed Positioning Modules is known to the Location Server and is available+
−
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+
−
one </b> </p> <p>Once a client application knows the number of Positioning+
−
Modules, it can easily iterate over them to get information for each one by+
−
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+
−
the availability of a Positioning Module. If this method returns <codeph>EFalse</codeph> then+
−
the Positioning Module cannot be used. It may have been taken offline or there+
−
may be a device hardware problem. The availability will not change unless+
−
there is some kind of user intervention, such as bringing the unavailable+
−
Positioning Module back online in a control panel. </p> <p> <i>Note</i>  </p> <p>A+
−
Positioning Module also has a status that can change over time. Module status+
−
provides more detailed information about a Positioning Module's state than+
−
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.+
−
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+
−
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+
−
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+
−
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+
−
a <xref href="GUID-1AA235FA-CEC1-3853-8F96-C538C02B596D.dita"><apiname>TPositionQuality</apiname></xref> object that describes the quality of+
−
position that the Positioning Module can provide. </p> <p><b>6. Close the server session </b> </p> <p>If the server session is not+
−
needed for any further processing then the application must close it. </p> </section>+
−
<section><title>How to get information about a specific Positioning      +
−
    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+
−
get information about a Positioning Module when its ID is known. </p> <codeblock id="GUID-F7A4BA9A-A02D-5439-95EF-237DBBCC2C0F" xml:space="preserve">+
−
TPositionModuleInfo modInfo;+
−
+
−
// modId is known to the client application+
−
User::LeaveIfError(server.GetModuleInfoById(modId, modInfo));+
−
...+
−
</codeblock> </section>+
−
</conbody><related-links>+
−
<link href="GUID-F6B5F777-D12F-5913-AECE-047DF8C72F1F.dita"><linktext>How to Get+
−
Location Information</linktext></link>+
−
<link href="GUID-F5944819-2942-5ADA-A0AD-510D20BFBDEB.dita"><linktext>How to Get+
−
Module Status Changes</linktext></link>+
−
</related-links></concept>+
−