<?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 <LbsErrors.h>

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 < 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() && (modInfo.TechnologyType() == ETechnologyAssisted) )

  {

  /* Check module capabilities

        In this example does the module supply speed information? */

  TCapabilities caps = modInfo.Capabilities();

  if (caps & 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() && quality.HorizontalAccuracy() < 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(&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>