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