<?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 xml:lang="en" id="GUID-BADAAC2D-8614-5036-95BC-3889457F7ED0"><title>Positioning Modules</title><shortdesc>This document describes the classes that give information about Positioning Modules. </shortdesc><prolog><metadata><keywords/></metadata></prolog><conbody><section><title>Purpose</title> <p>This document is an overview of the Positioning Module information that is available to client applications using the Location Acquisition API. A Positioning Module is a software component that allows the Location Server to communicate with the mobile device hardware that obtains position data. </p> <p>See <xref href="GUID-A4B47A7A-17EB-570C-AD88-6756B34AF634.dita">How to Use Positioning Module Information</xref> for an example of how to get Positioning Module information using the Location Acquisition API. </p> </section> <section><title>Types of Positioning Modules</title> <p>In mobile devices there may be several Positioning Modules: </p> <ul><li id="GUID-124DDB54-1792-5414-92BF-2EE320962899"><p>A Positioning Module that use GPS and/or A-GPS. </p> </li> <li id="GUID-BCBDB83F-13CE-5421-AFAC-244A94D036D5"><p>A Positioning Module that uses the network to obtain cell-based positions. </p> </li> <li id="GUID-372D7C0E-B264-545D-866A-4BEBD6083DE0"><p>Positioning Modules that use other technologies, such as WLAN positioning. </p> </li> </ul> </section> <section><title>Positioning Module information classes</title> <p>The classes <xref href="GUID-B098F3DB-E2FE-3C5A-8508-4B04D954AB26.dita"><apiname>TPositionModuleInfo</apiname></xref> and <xref href="GUID-1AA235FA-CEC1-3853-8F96-C538C02B596D.dita"><apiname>TPositionQuality</apiname></xref> hold information about the capabilities of Positioning Modules and the quality of position information that they can provide. Figure 1 illustrates these classes. </p> <fig id="GUID-C2A99C08-4F58-56C3-B86B-C032C21EBBF9"><title>

             Figure 1. TPositionModuleInfo and TPositionQuality classes 

          </title> <image href="GUID-5C5A695C-A0BB-53C3-A20B-7C7F4DD718DF_d0e266965_href.png" placement="inline"/></fig> </section> <section><title>TPositionModuleInfo</title> <p> <xref href="GUID-B098F3DB-E2FE-3C5A-8508-4B04D954AB26.dita"><apiname>TPositionModuleInfo</apiname></xref> describes a Positioning Module. This description includes: </p> <ul><li id="GUID-25D7701B-2A8A-5738-A33A-EA6EA5A8A9C2"><p>The technology type used by the Positioning Module. </p> <p>A Positioning Module can use positioning technology which is terminal-based (such as GPS), network based, or a combination of the two (such as A-GPS). The method <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 this information. </p> </li> <li id="GUID-58481363-B2A3-5E25-B78E-1C3F6B13F27B"><p>The capabilities of the Positioning Module. </p> <p>Different Positioning Modules have different capabilities which depend on the Positioning Module technology type. Most Positioning Modules have the capability to provide latitude and longitude information. Some Positioning Modules can also supply altitude information, course information and satellite data. This information is returned by the method <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> as a bit mask of type <xref href="GUID-B098F3DB-E2FE-3C5A-8508-4B04D954AB26.dita#GUID-B098F3DB-E2FE-3C5A-8508-4B04D954AB26/GUID-68CCD83C-23D2-3A90-8830-839B8CB7E712"><apiname>TPositionModuleInfo::TCapabilities</apiname></xref>. </p> </li> <li id="GUID-ACD5EC2F-0541-5116-A984-908D0FC3E3D3"><p>A unique identifier returned by <xref href="GUID-CFB2518D-1AF0-3A4F-91E7-D0612F2B3A51.dita#GUID-CFB2518D-1AF0-3A4F-91E7-D0612F2B3A51/GUID-9F461332-6933-36C9-8CF6-649212CC7EB0"><apiname>TPositionModule::ModuleId()</apiname></xref>. </p> <p>This identifier is used to select a specific Positioning Module when a client application wishes to use a specific positioning technology to obtain a location fix. </p> </li> </ul> <p>A <xref href="GUID-B098F3DB-E2FE-3C5A-8508-4B04D954AB26.dita"><apiname>TPositionModuleInfo</apiname></xref> object obtains a reference to its <xref href="GUID-1AA235FA-CEC1-3853-8F96-C538C02B596D.dita"><apiname>TPositionQuality</apiname></xref> object by calling <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>. </p> </section> <section><title>TPositionQuality</title> <p> <xref href="GUID-1AA235FA-CEC1-3853-8F96-C538C02B596D.dita"><apiname>TPositionQuality</apiname></xref> describes the quality of information that a Positioning Module can provide. The quality describes the accuracy of information, the time to obtain a location fix, the cost of obtaining the fix and power consumption: </p> <ul><li id="GUID-F62CA8E5-841E-5DDF-9080-162BE4FA75A3"><p> <xref href="GUID-1AA235FA-CEC1-3853-8F96-C538C02B596D.dita#GUID-1AA235FA-CEC1-3853-8F96-C538C02B596D/GUID-BF970003-EB72-3692-8540-FA79BE17F5EC"><apiname>TPositionQuality::HorizontalAccuracy()</apiname></xref> and <xref href="GUID-1AA235FA-CEC1-3853-8F96-C538C02B596D.dita#GUID-1AA235FA-CEC1-3853-8F96-C538C02B596D/GUID-5AA1DF65-BE1D-338F-8083-60647C1BDF95"><apiname>TPositionQuality::VerticalAccuracy()</apiname></xref> return location accuracy information. </p> </li> <li id="GUID-A57721DA-FE53-5936-A21D-C2EDC37DDA4D"><p> <xref href="GUID-1AA235FA-CEC1-3853-8F96-C538C02B596D.dita#GUID-1AA235FA-CEC1-3853-8F96-C538C02B596D/GUID-FC1FF7A2-E341-3EB8-8B7E-36C56FADCF10"><apiname>TPositionQuality::TimeToFirstFix()</apiname></xref> and <xref href="GUID-1AA235FA-CEC1-3853-8F96-C538C02B596D.dita#GUID-1AA235FA-CEC1-3853-8F96-C538C02B596D/GUID-33E94EAF-F9A3-3C13-997B-23359DC87731"><apiname>TPositionQuality::TimeToNextFix()</apiname></xref> return a typical time to get a location fix as a <xref href="GUID-B7D6F874-1ABD-3AC6-9329-19DC54C12F18.dita"><apiname>TTimeIntervalMicroSeconds</apiname></xref> value. </p> </li> <li id="GUID-57421139-A63F-59DE-819E-1DF760CEC989"><p> <xref href="GUID-1AA235FA-CEC1-3853-8F96-C538C02B596D.dita#GUID-1AA235FA-CEC1-3853-8F96-C538C02B596D/GUID-3C24190E-14FA-362F-8F25-D3324A35F5DC"><apiname>TPositionQuality::CostIndicator()</apiname></xref> returns a cost for using the Positioning Module to get location information. The value returned is an estimate, not a precise cost value and is of type <xref href="GUID-1AA235FA-CEC1-3853-8F96-C538C02B596D.dita#GUID-1AA235FA-CEC1-3853-8F96-C538C02B596D/GUID-78C084A0-43F8-3040-BD98-70E2E62A5D45"><apiname>TPositionQuality::TCostIndicator</apiname></xref>. The cost estimate helps the location server to make a choice of the Positioning Module to use to get a location fix when a specific Positioning Module is not chosen by a client application. </p> </li> <li id="GUID-CD7D504D-5DEF-5E56-B9A6-A60500390D24"><p> <xref href="GUID-1AA235FA-CEC1-3853-8F96-C538C02B596D.dita#GUID-1AA235FA-CEC1-3853-8F96-C538C02B596D/GUID-A0949CFB-FEAE-30A4-A6B5-B901DDC65850"><apiname>TPositionQuality::PowerConsumption()</apiname></xref> returns an estimate of power consumption for using a Positioning Module. This estimate is of type <xref href="GUID-1AA235FA-CEC1-3853-8F96-C538C02B596D.dita#GUID-1AA235FA-CEC1-3853-8F96-C538C02B596D/GUID-AD77543D-625A-39CF-A1D5-F5B5636E17F7"><apiname>TPositionQuality::TPowerConsumption</apiname></xref> and as with cost, it helps the Location Server make a choice of Positioning Module to use to get a location fix. </p> </li> </ul> </section> <section><title>See also</title> <p><xref href="GUID-A4B47A7A-17EB-570C-AD88-6756B34AF634.dita">How to Use Positioning Module Information</xref>  </p> </section> </conbody></concept>