--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/Symbian3/SDK/Source/GUID-A4B47A7A-17EB-570C-AD88-6756B34AF634.dita	Thu Jan 21 18:18:20 2010 +0000
@@ -0,0 +1,137 @@
+<?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>
\ No newline at end of file