Addition of the PDK content and example code for Documentation_content according to Feature bug 1607 and bug 1608
<?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-5DD17088-1F9C-5810-8143-5067A2B18330"><title>A-GPS Location Data Source API</title><shortdesc>This document describes the A-GPS Location Data Source API that device creators use to integrate with A-GPS hardware. </shortdesc><prolog><metadata><keywords/></metadata></prolog><conbody><section><title>Purpose</title> <p>This document describes the A-GPS (Assisted GPS) Location Data Source API that a licensee's GPS/A-GPS Integration Module must implement to integrate GPS hardware with the LBS subsystem. It is intended to give licensee Integration Module writers an understanding of the API, how it is called by the LBS subsystem and the behaviour expected from Integration Modules. </p> <p>This document contains links to A-GPS Location Data Source API reference documentation that can be followed to obtain full descriptions of API classes and methods. </p> </section> <section><title>Contents</title> <ul><li id="GUID-30D3903B-3AD2-5BFF-9372-141501AF8F4A"><p><xref href="GUID-5DD17088-1F9C-5810-8143-5067A2B18330.dita#GUID-5DD17088-1F9C-5810-8143-5067A2B18330/GUID-1F7525B3-0A1F-5B01-87D9-153E855F59E1">Introduction</xref> </p> </li> <li id="GUID-4A49C11E-C2FE-5436-8910-650336BEFD45"><p><xref href="GUID-5DD17088-1F9C-5810-8143-5067A2B18330.dita#GUID-5DD17088-1F9C-5810-8143-5067A2B18330/GUID-0A902E30-86FE-5E97-98DE-AAA181A784E8">GPS modes</xref> </p> </li> <li id="GUID-8C334B9A-DE46-5254-9054-B2E9B20B6D6E"><p><xref href="GUID-5DD17088-1F9C-5810-8143-5067A2B18330.dita#GUID-5DD17088-1F9C-5810-8143-5067A2B18330/GUID-D923FAFA-AFFA-53B6-921C-100A14B720E3">A-GPS Location Data Source API description</xref> </p> </li> <li id="GUID-7914AC04-0AD0-52B7-8ECA-03FA6BD9FD99"><p><xref href="GUID-5DD17088-1F9C-5810-8143-5067A2B18330.dita#GUID-5DD17088-1F9C-5810-8143-5067A2B18330/GUID-1BAF7733-25E1-53A7-AEE7-61B9EC2DA540">Using the A-GPS Location Data Source API</xref> </p> <ul><li id="GUID-8A63B20C-3AD8-59DB-B9CC-31580EB20E86"><p><xref href="GUID-5DD17088-1F9C-5810-8143-5067A2B18330.dita#GUID-5DD17088-1F9C-5810-8143-5067A2B18330/GUID-A9D4C00D-37A3-544F-B9E0-6A5176ABD8C7">LBS loads the A-GPS Integration Module</xref> </p> </li> <li id="GUID-58E72E3B-5BBC-5463-BC6B-B004C45E9059"><p><xref href="GUID-5DD17088-1F9C-5810-8143-5067A2B18330.dita#GUID-5DD17088-1F9C-5810-8143-5067A2B18330/GUID-EF629CC3-EFA8-559E-970C-1AC5B7B93324">LBS sets GPS options (including the GPS mode)</xref> </p> </li> <li id="GUID-2DDBF855-FF3F-53E1-AC2D-9CAED5DB6115"><p><xref href="GUID-5DD17088-1F9C-5810-8143-5067A2B18330.dita#GUID-5DD17088-1F9C-5810-8143-5067A2B18330/GUID-F4A152A0-82D5-52C1-9640-535B62088CDF">LBS sends power advice</xref> </p> </li> <li id="GUID-F57A9877-2786-504F-97C8-9564DF952877"><p><xref href="GUID-5DD17088-1F9C-5810-8143-5067A2B18330.dita#GUID-5DD17088-1F9C-5810-8143-5067A2B18330/GUID-B661DC32-76A0-570D-B6B6-B0C69712C427">LBS requests location update</xref> </p> </li> <li id="GUID-A8967BB1-0C27-5DE7-B7DA-F42B1DFD56D4"><p><xref href="GUID-5DD17088-1F9C-5810-8143-5067A2B18330.dita#GUID-5DD17088-1F9C-5810-8143-5067A2B18330/GUID-23A6EF21-DF43-5894-8159-27442A6828C6">Module requests assistance data</xref> </p> </li> <li id="GUID-7B0906BC-24D7-5948-A01E-3C3374F6A913"><p><xref href="GUID-5DD17088-1F9C-5810-8143-5067A2B18330.dita#GUID-5DD17088-1F9C-5810-8143-5067A2B18330/GUID-4820CF1C-DE98-5CC1-9A0E-72C5874A28D0">LBS notifies the A-GPS Integration Module of assistance data availability</xref> </p> </li> <li id="GUID-0DB2D9A5-3CB4-5461-B3A8-6E0B026B5722"><p><xref href="GUID-5DD17088-1F9C-5810-8143-5067A2B18330.dita#GUID-5DD17088-1F9C-5810-8143-5067A2B18330/GUID-9FEAEAA5-1555-5ADC-AF92-DC2C1BF00278">Module retrieves A-GPS assistance data items</xref> </p> </li> <li id="GUID-5BB24321-02EF-537D-88C3-F11BB85AAEA7"><p><xref href="GUID-5DD17088-1F9C-5810-8143-5067A2B18330.dita#GUID-5DD17088-1F9C-5810-8143-5067A2B18330/GUID-B3949496-29ED-55B6-BB2F-25BA85CC662E">Module notifies LBS of a location update</xref> </p> </li> <li id="GUID-2725FBBD-7411-5B87-A030-293EF0E3E19C"><p><xref href="GUID-5DD17088-1F9C-5810-8143-5067A2B18330.dita#GUID-5DD17088-1F9C-5810-8143-5067A2B18330/GUID-84D16C45-7ABC-5701-9E02-AF5EEFB34565">Cancelling a location update request</xref> </p> </li> <li id="GUID-203BDAD2-F575-56AD-8750-4968BFB783C3"><p><xref href="GUID-5DD17088-1F9C-5810-8143-5067A2B18330.dita#GUID-5DD17088-1F9C-5810-8143-5067A2B18330/GUID-906DA81C-CB41-58C4-8CA1-79552404B5B4">Resetting A-GPS assistance data</xref> </p> </li> <li id="GUID-2CC29D5D-7F93-582E-9D96-D0234ED48D6B"><p><xref href="GUID-5DD17088-1F9C-5810-8143-5067A2B18330.dita#GUID-5DD17088-1F9C-5810-8143-5067A2B18330/GUID-6FFF6FDB-1A8F-5503-9F0E-D31B7F21CD12">GPS hardware device status changes and quality status changes</xref> </p> </li> </ul> </li> <li id="GUID-F3264B23-2842-54A8-8AD6-6146A3752A8D"><p><xref href="GUID-5DD17088-1F9C-5810-8143-5067A2B18330.dita#GUID-5DD17088-1F9C-5810-8143-5067A2B18330/GUID-1F7525B3-0A1F-5B01-87D9-153E855F59E1">Integration module configuration</xref> </p> </li> <li id="GUID-D58188A6-8B54-5A76-9597-C0F747263A08"><p><xref href="GUID-5DD17088-1F9C-5810-8143-5067A2B18330.dita#GUID-5DD17088-1F9C-5810-8143-5067A2B18330/GUID-8C81482A-AB8E-5040-9D4A-3EB784765ACB">See also</xref> </p> </li> </ul> </section> <section id="GUID-1F7525B3-0A1F-5B01-87D9-153E855F59E1"><title>Introduction</title> <p>Licensees who want to use GPS technology in their phones must integrate the GPS hardware with the LBS subsystem. To do this they must create a GPS or A-GPS (Assisted GPS) Integration Module. An Integration Module provides the adaptation layer between the LBS subsystem and the GPS hardware. It is an ECOM plug-in that is loaded by the LBS subsystem A-GPS Location Manager on start-up. </p> <p>This document describes the A-GPS Location Data Source API. The API defines the interface between the LBS subsystem and an Integration Module. Symbian provides a reference implementation of an A-GPS Integration Module based on a SiRF chipset. Licensees can use the Symbian reference implementation as the basis of their own A-GPS Integration Module (see <xref href="GUID-8A77545C-3AB8-538B-868E-4F2111E767EF.dita">A-GPS reference module overview</xref> for more information). </p> <p>For a high-level description of LBS architecture, see <xref href="GUID-7233BC33-6060-5D6B-A5D2-01135F059337.dita">LBS architecture overview</xref>. For a more detailed explanation of the architecture see <filepath>SGL.TS0004.202
LBS Architectural Description </filepath> (in the LBS source distribution documentation folder). </p> </section> <section id="GUID-0A902E30-86FE-5E97-98DE-AAA181A784E8"><title> GPS modes</title> <p>Different GPS hardware chipsets may support different GPS capabilities: hardware may produce GPS position fixes (latitude, longitude and altitude data) or, more simply, GPS measurements that must be used by software outside of the GPS hardware to calculate a position fix. </p> <p>The four GPS modes supported by the LBS subsystem are: </p> <ul><li id="GUID-01F89630-7BB6-5229-BE0C-AA28622C8025"><p> <b>Autonomous mode</b> </p> <p>In <i>autonomous mode</i> GPS hardware calculates a position fix without using assistance data from the network. This typically takes longer than if assistance data were used to calculate the fix. </p> </li> <li id="GUID-98D9B182-4225-572F-B5A8-C256DE5D1CDB"><p> <b>Terminal based mode</b> (TB) </p> <p>In <i>terminal based mode</i> the Integration Module and GPS hardware use assistance data received from the network to calculate a GPS position fix and return it to the LBS subsystem. </p> </li> <li id="GUID-3642B59E-8152-5A29-B624-EDAF1D186D0B"><p> <b>Terminal assisted mode</b> (TA) </p> <p>In <i>terminal assisted mode</i>, the GPS hardware produces GPS measurements (with the help of assistance data from the network). </p> <p>In the Symbian LBS subsystem the Integration Module returns the GPS measurements which are sent to a network-based server. The measurements are used to calculate a position fix. </p> </li> <li id="GUID-58D818F1-B865-5ED3-8575-91B1768BC7F8"><p> <b>Simultaneous support of TB + TA modes</b> </p> <p>GPS hardware may be able to return both GPS measurements and position fixes. An Integration Module can return the GPS measurements as they are received from GPS satellites together with GPS position fixes that are increasingly complete and/or accurate. </p> <p>As in TA mode, the LBS subsystem returns the GPS measurements to the network for calculation. Either the network of the Integration Module may be the first to return a position of the required accuracy (as specified by a client process). </p> </li> </ul> <p>Licensees can implement their Integration Modules to support more than one GPS mode. A module may support terminal based mode with the ability to fallback to autonomous mode if assistance data is not available. A module may also be designed to support either TB or TA, but not TB + TA. </p> <p>An Integration Module publishes the GPS mode it supports in a configuration file. LBS uses the configuration file, the LBS subsystem administration settings and any preferences received from the network to set the GPS mode that an Integration Module uses to calculate a position fix. Later sections of this document describe how LBS sets an Integration Module's GPS mode. </p> </section> <section id="GUID-D923FAFA-AFFA-53B6-921C-100A14B720E3"><title>A-GPS Location Data Source API description</title> <p>This section describes the classes of the A-GPS Location Data Source API. </p> <p><b>A-GPS Location Data Source API class diagram </b> </p> <p>Figure 1 shows the classes of the A-GPS Location Data Source API. </p> <p>The main classes of the API are <xref href="GUID-A458AA58-8BD6-303B-89E5-C99000376615.dita"><apiname>CLbsLocationSourceGpsBase</apiname></xref> and <xref href="GUID-CE22C141-E1DC-38BB-AC11-76853A7B2590.dita"><apiname>MLbsLocationSourceGpsObserver</apiname></xref> which together model an observer/observable design pattern. A licensee's Integration Module must derive from <codeph>CLbsLocationSourceGpsBase</codeph>. The LBS subsystem (A-GPS Location Manager) implements <codeph>MLbsLocationSourceGpsObserver</codeph>. </p> <p> <b>Note: All of the methods of the CLbsLocationSourceGpsBase are synchronous and their implementations in a licensee Integration Module must return quickly.</b> </p> <fig id="GUID-FCB831B6-D0EA-5B04-BF4C-281017287721"><title>
Figure 1. A-GPS Location Data Source API classes
</title> <image href="GUID-905EA9A9-C72C-5632-A95E-B4ED0BD10316_d0e433229_href.png" placement="inline"/></fig> <p><b>API classes and types </b> </p> <p>Table 1 lists the classes and types that define the A-GPS Location Data Source API. Further details about the classes can be found by following the links to reference documentation. </p> <p>The A-GPS Location Data Source API has <codeph>publishedPartner</codeph> interface access. </p> <table id="GUID-03DE9669-4C08-5B9D-B900-C831DEAC2E05"><tgroup cols="3"><colspec colname="col0"/><colspec colname="col1"/><colspec colname="col2"/><thead><row><entry>Class/type name</entry> <entry>Description</entry> <entry>Header file</entry> </row> </thead> <tbody><row><entry><p> <xref href="GUID-A458AA58-8BD6-303B-89E5-C99000376615.dita"><apiname>CLbsLocationSourceGpsBase</apiname></xref> </p> </entry> <entry><p>The base class for all A-GPS Integration Module implementations. It defines the methods that the LBS subsystem uses to request GPS measurements or a GPS position fix, to set the mode of operation of the GPS hardware and to send power advice. </p> </entry> <entry><p> <filepath>LbsLocDataSourceGpsBase.h</filepath> </p> </entry> </row> <row><entry><p> <xref href="GUID-CE22C141-E1DC-38BB-AC11-76853A7B2590.dita"><apiname>MLbsLocationSourceGpsObserver</apiname></xref> </p> </entry> <entry><p>The GPS Integration Module observer class implemented by the LBS subsystem (A-GPS Location Manager). It defines the methods that an A-GPS module uses to request assistance data, return GPS measurements or a position fix, and send module status messages into LBS. </p> </entry> <entry><p> <filepath>LbsLocDataSourceGpsBase.h</filepath> </p> </entry> </row> <row><entry><p> <xref href="GUID-A458AA58-8BD6-303B-89E5-C99000376615.dita#GUID-A458AA58-8BD6-303B-89E5-C99000376615/GUID-4FDB2D40-8212-303B-9039-EAEDE14627FC"><apiname>CLbsLocationSourceGpsBase::TPowerMode</apiname></xref> </p> </entry> <entry><p>Defines a set of values for power advice. A value is a parameter in <xref href="GUID-A458AA58-8BD6-303B-89E5-C99000376615.dita#GUID-A458AA58-8BD6-303B-89E5-C99000376615/GUID-E676384E-6528-3A63-A6FC-8CED25C0976E"><apiname>CLbsLocationSourceGpsBase::AdvisePowerMode()</apiname></xref>. </p> </entry> <entry><p> <filepath>LbsLocDataSourceGpsBase.h</filepath> </p> </entry> </row> <row><entry><p> <xref href="GUID-B5C832B0-93B1-30F2-B549-E468CB5A13B7.dita"><apiname> TLbsLocRequestQuality</apiname></xref> </p> </entry> <entry><p>Specifies the desired quality of a location request. <codeph>TLbsLocRequestQuality</codeph> is used to specify the desired quality of a location request to an Integration Module. A reference to an object of this type is passed to <xref href="GUID-14FCF07F-EF83-3D71-8598-503FF1530589.dita#GUID-14FCF07F-EF83-3D71-8598-503FF1530589/GUID-964C3C84-7CB4-316B-8B1D-892FC36FECE6"><apiname>CLbsLocationSourceBase::UpdateLocation()</apiname></xref>. </p> </entry> <entry><p> <filepath>LbsLocDataSourceGpsBase.h</filepath> </p> </entry> </row> <row><entry><p> <xref href="GUID-B0986288-97BA-35FE-B35B-04DDAE079B76.dita"><apiname> TLbsGpsOptions</apiname></xref> </p> </entry> <entry><p>This is the default class used to hold various global settings for the GPS integration module including the GPS positioning mode required. It has the method <xref href="GUID-B0986288-97BA-35FE-B35B-04DDAE079B76.dita#GUID-B0986288-97BA-35FE-B35B-04DDAE079B76/GUID-0F539830-ECFE-3CE2-AC56-DB2A196E7CED"><apiname>TLbsGpsOptions::SetGpsMode()</apiname></xref> that is used to set the GPS positioning mode of the module (such as terminal based or terminal assisted mode). </p> </entry> <entry><p> <filepath>LbsLocDataSourceGpsBase.h</filepath> </p> </entry> </row> <row><entry><p> <xref href="GUID-2CCCF864-C56B-3E82-85FF-5675340BD355.dita"><apiname> TLbsGpsOptionsItem</apiname></xref> (from v9.3) </p> </entry> <entry><p>An item in a <xref href="GUID-333F10FF-C647-3A07-9EFA-B1A2CF0B96C1.dita"><apiname>TLbsGpsOptionsArray</apiname></xref>. The item specifies the type of update required from a module - a position fix or a set of GPS measurements or both. </p> </entry> <entry><p> <filepath>LbsLocDataSourceGpsBase.h</filepath> </p> </entry> </row> <row><entry><p> <xref href="GUID-333F10FF-C647-3A07-9EFA-B1A2CF0B96C1.dita"><apiname> TLbsGpsOptionsArray</apiname></xref> (from v9.3) </p> </entry> <entry><p>This class is derived from <xref href="GUID-B0986288-97BA-35FE-B35B-04DDAE079B76.dita"><apiname>TLbsGpsOptions</apiname></xref>. It is only passed as a parameter in <xref href="GUID-A458AA58-8BD6-303B-89E5-C99000376615.dita#GUID-A458AA58-8BD6-303B-89E5-C99000376615/GUID-0744F006-FF77-3FBA-A33B-9EE403924820"><apiname>CLbsLocationSourceGpsBase::UpdateLocation()</apiname></xref> when the network has asked the LBS subsystem to work in TB + TA mode. For more information see <xref href="GUID-5DD17088-1F9C-5810-8143-5067A2B18330.dita#GUID-5DD17088-1F9C-5810-8143-5067A2B18330/GUID-EF629CC3-EFA8-559E-970C-1AC5B7B93324">LBS sets GPS options</xref>. </p> </entry> <entry><p> <filepath>LbsLocDataSourceGpsBase.h</filepath> </p> </entry> </row> </tbody> </tgroup> </table> <p> <i>Table 1 Classes and types of the A-GPS Location Data Source API.</i> </p> <p>Table 2 lists the assistance data classes and types that are passed across the API. The classes and types are used to specify the assistance data that an Integration Module requires. For more information see the links to reference documentation. </p> <table id="GUID-94D91F10-86DC-5D1E-81CC-0153D640C823"><tgroup cols="3"><colspec colname="col0"/><colspec colname="col1"/><colspec colname="col2"/><thead><row><entry>Class/type name</entry> <entry>Description</entry> <entry>Header file</entry> </row> </thead> <tbody><row><entry><p> <xref href="GUID-58DA9D8B-50F6-38CB-B5BC-D8C1784ACFDB.dita"><apiname> TLbsAssistanceDataItem</apiname></xref> </p> </entry> <entry><p>The class defines the type of assistance data that an Integration Module requires. A bitmask of type <xref href="GUID-343E1FD7-9D75-3A41-84EC-B35030C06557.dita"><apiname>TLbsAssistanceDataGroup</apiname></xref> is composed of <xref href="GUID-58DA9D8B-50F6-38CB-B5BC-D8C1784ACFDB.dita"><apiname>TLbsAssistanceDataItem</apiname></xref> values. The class and the bitmask are used to pass requests for assistance data between the Integration Module and the LBS subsystem. </p> </entry> <entry><p> <filepath>LbsAssistanceDataBase.h</filepath> </p> </entry> </row> <row><entry><p> <xref href="GUID-343E1FD7-9D75-3A41-84EC-B35030C06557.dita"><apiname>TLbsAssistanceDataGroup</apiname></xref> </p> </entry> <entry><p>Bitmask of <xref href="GUID-58DA9D8B-50F6-38CB-B5BC-D8C1784ACFDB.dita"><apiname>TLbsAssistanceDataItem</apiname></xref> values. </p> </entry> <entry><p> <filepath>LbsAssistanceDataBase.h</filepath> </p> </entry> </row> <row><entry><p> <xref href="GUID-5EB8A06F-5D70-35C0-ADAC-62A2A6126F8D.dita"><apiname>RDataBuilderRootBase</apiname></xref> </p> </entry> <entry><p>Base class of readers for assistance data. Each type of assistance data requires its own reader that is derived from <codeph>RDataBuilderRootBase</codeph>. </p> </entry> <entry><p> <filepath>LbsAssistanceDataBase.h</filepath> </p> </entry> </row> </tbody> </tgroup> </table> <p> <i>Table 2 Assistance data classes passed across the API</i> </p> <p>Table 3 lists position info classes that are passed across the API from an Integration Module to the LBS subsystem. For more information see the links to reference documentation. </p> <table id="GUID-BADFAAAD-1B60-5E8B-BFCB-A128C755FAFC"><tgroup cols="3"><colspec colname="col0"/><colspec colname="col1"/><colspec colname="col2"/><thead><row><entry>Class/type name</entry> <entry>Description</entry> <entry>Header file</entry> </row> </thead> <tbody><row><entry><p> <xref href="GUID-73D6F438-C270-33B9-974B-D4D1583E1738.dita"><apiname>TPositionInfoBase</apiname></xref> </p> </entry> <entry><p>Base class for classes that hold GPS position fixes or GPS measurements. </p> </entry> <entry><p> <filepath>LbsPositionInfo.h</filepath> </p> </entry> </row> <row><entry><p> <xref href="GUID-54AE0674-C49D-3329-8B77-3A58EFFC03D7.dita"><apiname>TPositionSatelliteInfo</apiname></xref> </p> </entry> <entry><p>Holds a position fix and satellite information. </p> </entry> <entry><p> <filepath>LbsSatelliteInfo.h</filepath> </p> </entry> </row> <row><entry><p> <xref href="GUID-66C5B5DB-6B9A-3071-816C-F51AEED2E8DE.dita"><apiname>TPositionGpsMeasurementInfo</apiname></xref> </p> </entry> <entry><p>Holds GPS measurements. </p> </entry> <entry><p> <filepath>LbsGpsMeasurement.h </filepath> </p> </entry> </row> </tbody> </tgroup> </table> <p> <i>Table 3 Position Info classes</i> </p> <p><b>Libraries </b> </p> <p>The main classes of the A-GPS Location Data Source API are packaged in <filepath>lbslocdatasource.dll</filepath>. Integration Module implementations link to <filepath>lbslocdatasource.lib</filepath>. </p> <p>Assistance data classes are packaged in <filepath>lbsassistancedata.dll</filepath>. Clients link to <filepath>lbsassistancedata.lib</filepath>. </p> <p>Position info classes are packaged in <filepath>lbsselflocate.dll</filepath>. Clients link to <filepath>lbsselflocate.lib</filepath>. </p> </section> <section id="GUID-1BAF7733-25E1-53A7-AEE7-61B9EC2DA540"><title>Using the A-GPS Location Data Source API</title> <p>Licensees use the API to create an Integration Module to interface their device GPS hardware with the LBS subsystem. The API provides the means by which the LBS subsystem and an Integration Module interact. Details of how the Integration Module interact with the GPS hardware are hardware-specific and are not part of the API. </p> <p>This section describes how an Integration Module and the LBS subsystem use the API to interact. It is intended to give a description of the general order in which the API methods are called by the LBS subsystem and to give a better understanding of their purpose. </p> <p>The behaviour of an A-GPS Integration Module can be complex when it is linked to a Network Protocol Module. Several detailed end-to-end sequence diagrams that document the behaviour of the LBS subsystem including the behaviour expected from an Integration Module are given in <xref href="GUID-D9EA897E-71FB-5012-8208-49300A19D22C.dita">LBS Sequence Diagrams</xref>. </p> <p>Figure 2 shows a simplified sequence for an MO-LR self locate (a self-locate request from the <xref href="GUID-D0318BB6-0B9F-5A1C-AB0B-61BA22D28661.dita">Location Acquisition API</xref>). Terminal based positioning involves obtaining assistance data (and possibly a reference position) from the network via a <xref href="GUID-8985B028-4BCD-5858-B22F-EECC52B7B9EB.dita">Network Protocol Module</xref>. The discussion that follows describes the main flow of events for MO-LR self locate. </p> <fig id="GUID-9DD5D060-D96C-57E1-8029-624638969C30"><title>
Figure 2. Simplified sequence for MO-LR self locate request
</title> <image href="GUID-5344014E-A6F4-5243-9D55-BB2C5C78A463_d0e433754_href.png" placement="inline"/></fig> <p>The following explains a simple flow of events between the LBS subsystem and an A-GPS Integration Module (for terminal based positioning): </p> <ul><li id="GUID-961B08BC-F54E-5F61-B10A-6D14B68D546E"><p><xref href="GUID-5DD17088-1F9C-5810-8143-5067A2B18330.dita#GUID-5DD17088-1F9C-5810-8143-5067A2B18330/GUID-A9D4C00D-37A3-544F-B9E0-6A5176ABD8C7">LBS loads the A-GPS Integration Module</xref> </p> </li> <li id="GUID-2924CFD9-E916-5305-994B-D6A7EFDCD247"><p><xref href="GUID-5DD17088-1F9C-5810-8143-5067A2B18330.dita#GUID-5DD17088-1F9C-5810-8143-5067A2B18330/GUID-EF629CC3-EFA8-559E-970C-1AC5B7B93324">LBS sets GPS options (including the GPS mode)</xref> </p> </li> <li id="GUID-7B4236F5-897F-5846-AE9A-9A1EA1DAC8FA"><p><xref href="GUID-5DD17088-1F9C-5810-8143-5067A2B18330.dita#GUID-5DD17088-1F9C-5810-8143-5067A2B18330/GUID-F4A152A0-82D5-52C1-9640-535B62088CDF">LBS sends power advice</xref> </p> </li> <li id="GUID-82F51F6B-636E-51F3-AC3C-5623B2F5E9DA"><p><xref href="GUID-5DD17088-1F9C-5810-8143-5067A2B18330.dita#GUID-5DD17088-1F9C-5810-8143-5067A2B18330/GUID-B661DC32-76A0-570D-B6B6-B0C69712C427">LBS requests location update</xref> </p> </li> <li id="GUID-06022E8B-4EBA-531C-A4C2-41029B19575D"><p><xref href="GUID-5DD17088-1F9C-5810-8143-5067A2B18330.dita#GUID-5DD17088-1F9C-5810-8143-5067A2B18330/GUID-23A6EF21-DF43-5894-8159-27442A6828C6">Module requests assistance data</xref> </p> </li> <li id="GUID-24A0D421-75CC-528C-B47A-C1D75AD1855C"><p><xref href="GUID-5DD17088-1F9C-5810-8143-5067A2B18330.dita#GUID-5DD17088-1F9C-5810-8143-5067A2B18330/GUID-4820CF1C-DE98-5CC1-9A0E-72C5874A28D0">LBS notifies the A-GPS Integration Module of assistance data availability</xref> </p> </li> <li id="GUID-5013410C-6129-599C-90D8-52345921F843"><p><xref href="GUID-5DD17088-1F9C-5810-8143-5067A2B18330.dita#GUID-5DD17088-1F9C-5810-8143-5067A2B18330/GUID-9FEAEAA5-1555-5ADC-AF92-DC2C1BF00278">Module retrieves A-GPS assistance data items</xref> </p> </li> <li id="GUID-53581CD5-7DEF-572A-A989-972ACC12E933"><p><xref href="GUID-5DD17088-1F9C-5810-8143-5067A2B18330.dita#GUID-5DD17088-1F9C-5810-8143-5067A2B18330/GUID-B3949496-29ED-55B6-BB2F-25BA85CC662E">Module notifies LBS of a location update</xref> </p> </li> </ul> <p>In addition to the typical flow of events described, a module can also notify LBS of GPS <xref href="GUID-5DD17088-1F9C-5810-8143-5067A2B18330.dita#GUID-5DD17088-1F9C-5810-8143-5067A2B18330/GUID-6FFF6FDB-1A8F-5503-9F0E-D31B7F21CD12">device status changes and quality status changes</xref>. </p> <p>The implementation of <xref href="GUID-A458AA58-8BD6-303B-89E5-C99000376615.dita"><apiname>CLbsLocationSourceGpsBase</apiname></xref> methods must not call <xref href="GUID-CE22C141-E1DC-38BB-AC11-76853A7B2590.dita"><apiname>MLbsLocationSourceGpsObserver</apiname></xref> methods or stack overflow may eventually occur. The exception to this rule is <xref href="GUID-A458AA58-8BD6-303B-89E5-C99000376615.dita#GUID-A458AA58-8BD6-303B-89E5-C99000376615/GUID-0370A120-0222-3559-A4B5-89C997B192D7"><apiname>CLbsLocationSourceGpsBase::AssistanceDataEvent()</apiname></xref>: implementations may call <xref href="GUID-CE22C141-E1DC-38BB-AC11-76853A7B2590.dita#GUID-CE22C141-E1DC-38BB-AC11-76853A7B2590/GUID-AAEE001E-B121-3590-88A8-97200645BFA9"><apiname>MLbsLocationSourceGpsObserver::GetAssistanceDataItem()</apiname></xref> multiple times to get all the request assistance data items. </p> <p>Each of the steps above and shown in figure 2 is described in more detail in the following sections, with links to API reference documentation. </p> <p id="GUID-A9D4C00D-37A3-544F-B9E0-6A5176ABD8C7"><b>LBS loads the A-GPS Integration Module</b> </p> <p>The Integration Module is packaged as an ECOM plug-in DLL. When the LBS subsystem starts up, the A-GPS Location Manager process uses the ECOM framework to load the Integration Module. The A-GPS Location Manager calls <xref href="GUID-A458AA58-8BD6-303B-89E5-C99000376615.dita#GUID-A458AA58-8BD6-303B-89E5-C99000376615/GUID-DE91837E-AD18-3236-9678-E21EF655721A"><apiname>CLbsLocationSourceGpsBase::NewL()</apiname></xref>, passing a reference to itself as an <xref href="GUID-CE22C141-E1DC-38BB-AC11-76853A7B2590.dita"><apiname>MLbsLocationSourceGpsObserver</apiname></xref> and the ID of the ECOM implementation DLL to load. </p> <p>For more information about how to configure LBS to use an Integration Module see <xref href="GUID-D18B4715-3942-52EA-9D2F-E145037FA47A.dita">LBS integration and configuration guide</xref>. </p> <p id="GUID-EF629CC3-EFA8-559E-970C-1AC5B7B93324"><b>LBS sets GPS options (including the GPS mode)</b> </p> <p> <b/> The GPS mode specifies how the A-GPS Integration Module should obtain a location fix. There are four modes supported by the LBS subsystem as described in <xref href="GUID-5DD17088-1F9C-5810-8143-5067A2B18330.dita#GUID-5DD17088-1F9C-5810-8143-5067A2B18330/GUID-0A902E30-86FE-5E97-98DE-AAA181A784E8">GPS modes</xref>: </p> <ul><li id="GUID-A6E6DBC8-E9FB-5492-9FEC-D81FC45B6C06"><p>Autonomous mode </p> </li> <li id="GUID-A174195F-F3E1-5A6B-9EEC-DEBEDB2942C1"><p>Terminal based mode (TB) </p> </li> <li id="GUID-9B17E6D2-4E69-57E2-AF7B-B86C5089D795"><p>Terminal assisted mode (TA) </p> </li> <li id="GUID-ED605E09-31D7-5982-B6CA-A81B762190D9"><p>Simultaneous TB + TA </p> </li> </ul> <p><b>GPS mode settings values </b> </p> <p>The LBS subsystem calls <xref href="GUID-A458AA58-8BD6-303B-89E5-C99000376615.dita#GUID-A458AA58-8BD6-303B-89E5-C99000376615/GUID-353317B8-81BE-3C9D-8186-CC7CB1056AA1"><apiname>CLbsLocationSourceGpsBase::SetGpsOptions()</apiname></xref> to set the GPS mode. The LBS subsystem calls this method when an Integration Module is first loaded by the LBS subsystem and when an MO-LR begins (when the setting value is taken from the LBS administration setting value for <xref href="GUID-28C5F57D-16F7-3433-9398-1441C949EBC4.dita"><apiname>KLbsSettingHomeGpsMode</apiname></xref>). </p> <p>As shown in figure 2, <codeph>SetGpsOptions()</codeph> may be called again as part of a location request if the network requests a different GPS mode from the one that is currently set. The mode that is set should be used by the Integration Module for all further location requests until the next call from LBS to <codeph>SetGpsOptions()</codeph>. </p> <p>Table 1 shows a list of values of <xref href="GUID-E8B4B321-6B45-3764-ADD2-CD05A5533945.dita#GUID-E8B4B321-6B45-3764-ADD2-CD05A5533945/GUID-9F902F01-29A3-3929-B045-83C72DB96E39"><apiname>CLbsAdmin::TGpsMode</apiname></xref> that are passed in <codeph>SetGpsOptions()</codeph>. </p> <table id="GUID-D4793B94-3461-51BF-87A9-360703CA0F95"><tgroup cols="2"><colspec colname="col0"/><colspec colname="col1"/><thead><row><entry>TGpsMode</entry> <entry>Meaning</entry> </row> </thead> <tbody><row><entry><p>EGpsPreferTerminalBased </p> </entry> <entry><p>Prefer Terminal Based (PTB): Integration module should use Terminal Based Positioning (TB) if possible. If TB is not possible then fallback to autonomous mode. </p> </entry> </row> <row><entry><p>EGpsAutonomous </p> </entry> <entry><p>Use Autonomous GPS: Module must not request any assistance data from the network and calculate a position without it. </p> </entry> </row> <row><entry><p>EGpsPreferTerminalAssisted </p> </entry> <entry><p>Prefer Terminal Assisted (PTA): Module must use Terminal Assisted Positioning (TA) if possible. If TA is not possible then fallback to autonomous mode if possible. </p> </entry> </row> <row><entry><p>EGpsAlwaysTerminalAssisted </p> </entry> <entry><p>Always Terminal Assisted (ATA): Module must always use TA and return an error if this is not possible. If the Integration Module is not able to use TA it calls <xref href="GUID-CE22C141-E1DC-38BB-AC11-76853A7B2590.dita#GUID-CE22C141-E1DC-38BB-AC11-76853A7B2590/GUID-170901F1-435D-3BC1-985B-49BA0876BD92"><apiname>MLbsLocationSourceGpsObserver::UpdateLocation()</apiname></xref> with a status code of <codeph>KErrNotSupported</codeph>. </p> </entry> </row> <row><entry><p>EGpsAlwaysTerminalBased </p> </entry> <entry><p>Always Terminal Based (ATB): Module must always use TB and return an error if this is not possible. <b>This value is not currently supported.</b> </p> </entry> </row> </tbody> </tgroup> </table> <p>Table 1. <codeph>TGpsMode</codeph> values and their meanings. </p> <p>A licensee's Integration Module is not required to support all of these modes. Licensees modify the Integration Module <xref href="GUID-D18B4715-3942-52EA-9D2F-E145037FA47A.dita">module.ini</xref> file <codeph>DeviceGpsModeCaps</codeph> setting to publish a module's capabilities to the LBS subsystem. </p> <p>Valid values of <codeph>DeviceGpsModeCaps</codeph> in <filepath>module.ini</filepath> are as follows: </p> <ul><li id="GUID-E35E03DA-2CFF-5E9A-AFCD-0EF5C46A173D"><p>0001 - Module supports Terminal Based positioning and is also able to calculate position autonomously if assistance data is unavailable or does not arrive on time (for example a fix is obtained before assistance data delivery). </p> </li> <li id="GUID-6826468C-4BE8-5CD0-A834-F5EA468914FC"><p>0010 - Module supports Terminal Assisted positioning. The module may (but does not have to) be able to calculate position autonomously if Terminal Assisted positioning does not succeed (for example the network is unavailable). </p> </li> <li id="GUID-8F42ED59-5645-5B72-8C9C-78351CD4FA26"><p>0011 - Module supports Terminal Based positioning OR Terminal Assisted positioning and is also able to calculate position autonomously if assistance data is unavailable, or does not arrive on time (for example a fix is obtained before assistance data delivery). </p> </li> <li id="GUID-26BCC149-7FE2-5766-9754-7D102546E4C7"><p>0100 - Module can perform Terminal Assisted AND Terminal Based positioning at the same time (TB + TA). It is also able to calculate position autonomously if assistance data is unavailable (e.g. network error), or does not arrive on time (e.g. a fix is obtained before assistance data delivery). NOTE: If this bit is set then it is not necessary to set either of the less significant 2 bits as they are implied. </p> </li> </ul> <p> <i>If DeviceGpsModeCaps is not specified in this file, LBS assumes that the module can support both Terminal Based AND Terminal Assisted GPS modes at the same time.</i> </p> <p>There are two slightly different methods of specifying the GPS mode to an Integration Module. Both methods involve the A-GPS Location Manager calling <xref href="GUID-A458AA58-8BD6-303B-89E5-C99000376615.dita#GUID-A458AA58-8BD6-303B-89E5-C99000376615/GUID-353317B8-81BE-3C9D-8186-CC7CB1056AA1"><apiname>CLbsLocationSourceGpsBase::SetGpsOptions()</apiname></xref>: </p> <p><b>Setting a single positioning mode </b> </p> <p>(For autonomous mode, terminal based mode and terminal assisted mode) </p> <p>LBS creates an object of class <xref href="GUID-B0986288-97BA-35FE-B35B-04DDAE079B76.dita"><apiname>TLbsGpsOptions</apiname></xref> and calls <xref href="GUID-B0986288-97BA-35FE-B35B-04DDAE079B76.dita#GUID-B0986288-97BA-35FE-B35B-04DDAE079B76/GUID-0F539830-ECFE-3CE2-AC56-DB2A196E7CED"><apiname>TLbsGpsOptions::SetGpsMode()</apiname></xref> with a single parameter of type <xref href="GUID-E8B4B321-6B45-3764-ADD2-CD05A5533945.dita#GUID-E8B4B321-6B45-3764-ADD2-CD05A5533945/GUID-9F902F01-29A3-3929-B045-83C72DB96E39"><apiname>CLbsAdmin::TGpsMode</apiname></xref>: </p> <p>To set the Integration Module to use autonomous mode, LBS calls <codeph>SetGpsMode()</codeph> with the parameter value <codeph>CLbsAdmin::EGpsAutonomous</codeph>. </p> <p>To set terminal based mode, LBS calls <codeph>SetGpsMode()</codeph> with the parameter value <codeph>CLbsAdmin::EGpsPreferTerminalBased</codeph>. This specifies that a GPS position fix is required from the Integration Module (the module should use TB if possible, but fallback to autonomous mode if no assistance data is available). </p> <p>To set terminal assisted mode, LBS calls <codeph>SetGpsMode()</codeph> with the parameter value <codeph>CLbsAdmin::EGpsPreferTerminalAssisted</codeph> or <codeph>CLbsAdmin::EGpsAlwaysTerminalAssisted</codeph>. This specifies that GPS measurements are required from the module. The two parameter values have the following meanings: </p> <ul><li id="GUID-3218BAD8-AF6D-50A5-8B60-E2B07E0E7719"><p> <codeph>EGpsPreferTerminalAssisted</codeph> means that a module should use TA if possible but fallback to autonomous mode if this is not possible (for example a network error). </p> </li> <li id="GUID-5DEA5362-9291-52E3-A57A-84F39A9E9FB3"><p> <codeph>EGpsAlwaysTerminalAssisted</codeph> means that a module should <i>always</i> use TA. If TA is not possible (for example because of a network error) then the Integration Module must signal an error by calling <xref href="GUID-CE22C141-E1DC-38BB-AC11-76853A7B2590.dita#GUID-CE22C141-E1DC-38BB-AC11-76853A7B2590/GUID-170901F1-435D-3BC1-985B-49BA0876BD92"><apiname>MLbsLocationSourceGpsObserver::UpdateLocation()</apiname></xref> with an error status code (a negative code). </p> </li> </ul> <p>To set the GPS mode on the Integration Module, LBS calls <xref href="GUID-A458AA58-8BD6-303B-89E5-C99000376615.dita#GUID-A458AA58-8BD6-303B-89E5-C99000376615/GUID-353317B8-81BE-3C9D-8186-CC7CB1056AA1"><apiname>CLbsLocationSourceGpsBase::SetGpsOptions()</apiname></xref> passing the <codeph>TLbsGpsOptions</codeph> reference as a parameter. </p> <p>If LBS attempts to set an Integration Module's GPS mode to one that it does not support then the Integration Module must call <xref href="GUID-CE22C141-E1DC-38BB-AC11-76853A7B2590.dita#GUID-CE22C141-E1DC-38BB-AC11-76853A7B2590/GUID-170901F1-435D-3BC1-985B-49BA0876BD92"><apiname>MLbsLocationSourceGpsObserver::UpdateLocation()</apiname></xref> with a status parameter of <codeph>KErrNotSupported</codeph>. Note that the Symbian reference A-GPS Integration Module does not support Terminal Assisted mode or TB + TA mode. </p> <p>As part of a location request, the network can specify the required GPS modes to LBS (see <xref href="GUID-CB6B4D1A-ACB9-5571-8C23-4BC095209782.dita">Network Protocol Module</xref> documentation for more information about how a Protocol Module specifies these modes). If the network asks for Terminal Assisted mode, the LBS subsystem uses the value of the administration setting <codeph>KLbsSettingHomeGpsMode</codeph> to decide which mode is sent to the Integration Module, either <codeph>
EGpsPreferTerminalAssisted</codeph> or <codeph>EGpsAlwaysTerminalAssisted</codeph>. </p> <p><b>Setting multiple positioning modes (TB + TA) </b> </p> <p>The network can specify two positioning modes that LBS should use (see <xref href="GUID-CB6B4D1A-ACB9-5571-8C23-4BC095209782.dita">Network Protocol Module</xref> for more information about how the modes are specified to LBS). </p> <p>If the Integration Module is capable of supporting both TB and TA simultaneously <codeph>(DevGpsModeCaps = 0100</codeph> in <filepath>module.ini</filepath>) then LBS specifies both modes to a module as follows: </p> <p>LBS creates an object of class <xref href="GUID-333F10FF-C647-3A07-9EFA-B1A2CF0B96C1.dita"><apiname>TLbsGpsOptionsArray</apiname></xref>. Each element of the array is a <xref href="GUID-2CCCF864-C56B-3E82-85FF-5675340BD355.dita"><apiname>TLbsGpsOptionsItem</apiname></xref> object which can hold one of two values of type <xref href="GUID-2CCCF864-C56B-3E82-85FF-5675340BD355.dita#GUID-2CCCF864-C56B-3E82-85FF-5675340BD355/GUID-BEA2FC56-F307-35B5-9815-D8121729958D"><apiname>TLbsGpsOptionsItem::TPosUpdateType</apiname></xref>, set by calling <xref href="GUID-2CCCF864-C56B-3E82-85FF-5675340BD355.dita#GUID-2CCCF864-C56B-3E82-85FF-5675340BD355/GUID-4429FBD5-C8BD-3A91-AA26-10E6D8C9F925"><apiname>TLbsGpsOptionsItem::SetLocUpdateType()</apiname></xref>: </p> <ul><li id="GUID-6381FDF6-1203-51A6-B5ED-DFFF58E72C5C"><p> <codeph>TLbsOptionsItem::EPosUpdateCalculation</codeph> specifies that a calculated position is required from the Integration Module </p> </li> <li id="GUID-E836DF8A-C222-5CB2-8CC6-BE451972CEF1"><p> <codeph>TLbsOptionsItem:EPosUpdateMeasurement</codeph> specifies that a set of GPS measurements are required from the Integration Module </p> </li> </ul> <p>LBS creates an array with two <codeph>TLbsGpsOptionsItem</codeph> elements, the first of type <codeph>TLbsOptionsItem::EPosUpdateCalculation</codeph> and the second of type <codeph>TLbsOptionsItem:EPosUpdateMeasurement.</codeph> </p> <p>LBS calls <xref href="GUID-B0986288-97BA-35FE-B35B-04DDAE079B76.dita#GUID-B0986288-97BA-35FE-B35B-04DDAE079B76/GUID-0F539830-ECFE-3CE2-AC56-DB2A196E7CED"><apiname>TLbsGpsOptions::SetGpsMode()</apiname></xref> with a parameter value of <codeph>EGpsPreferTerminalBased</codeph>. To set the GPS mode on the Integration Module, LBS calls <xref href="GUID-A458AA58-8BD6-303B-89E5-C99000376615.dita#GUID-A458AA58-8BD6-303B-89E5-C99000376615/GUID-353317B8-81BE-3C9D-8186-CC7CB1056AA1"><apiname>CLbsLocationSourceGpsBase::SetGpsOptions()</apiname></xref> passing the <codeph>TLbsGpsOptions</codeph> reference as a parameter. </p> <p>The type and position of the elements in the array controls the type of data the Integration Module returns when it notifies LBS of a <xref href="GUID-5DD17088-1F9C-5810-8143-5067A2B18330.dita#GUID-5DD17088-1F9C-5810-8143-5067A2B18330/GUID-B3949496-29ED-55B6-BB2F-25BA85CC662E">location update</xref>. </p> <p id="GUID-F4A152A0-82D5-52C1-9640-535B62088CDF"><b>LBS sends power advice</b> </p> <p>Power advice messages are sent from LBS to notify the Integration Module that it should change its power status. Power advice is sent by LBS calling <xref href="GUID-A458AA58-8BD6-303B-89E5-C99000376615.dita#GUID-A458AA58-8BD6-303B-89E5-C99000376615/GUID-E676384E-6528-3A63-A6FC-8CED25C0976E"><apiname>CLbsLocationSourceGpsBase::AdvisePowerMode()</apiname></xref>, passing a <xref href="GUID-A458AA58-8BD6-303B-89E5-C99000376615.dita#GUID-A458AA58-8BD6-303B-89E5-C99000376615/GUID-4FDB2D40-8212-303B-9039-EAEDE14627FC"><apiname>CLbsLocationSourceGpsBase::TPowerMode</apiname></xref> value as a parameter. The Integration Module must implement its own code to control the power mode of the GPS hardware. The meanings of the <codeph>TPowerMode</codeph> values are as follows: </p> <table id="GUID-C622FD4D-0C9F-58DC-BC95-3ADFCCC6D74A"><tgroup cols="2"><colspec colname="col0"/><colspec colname="col1"/><thead><row><entry>TPowerMode</entry> <entry>Meaning</entry> </row> </thead> <tbody><row><entry><p> <codeph>EPowerModeOn</codeph> </p> </entry> <entry><p>Advise the module to turn on GPS hardware power </p> </entry> </row> <row><entry><p> <codeph>EPowerModeStandby</codeph> </p> </entry> <entry><p>Advise the module to set the GPS hardware power to standby </p> </entry> </row> <row><entry><p> <codeph>EPowerModeOff</codeph> </p> </entry> <entry><p>Advise the module to turn off GPS hardware power </p> </entry> </row> <row><entry><p> <codeph>EPowerModeClose</codeph> </p> </entry> <entry><p>Advise the module that the LBS subsystem is shutting down </p> </entry> </row> </tbody> </tgroup> </table> <p>When the GPS hardware changes its power mode the Integration Module must notify LBS of a <xref href="GUID-5DD17088-1F9C-5810-8143-5067A2B18330.dita#GUID-5DD17088-1F9C-5810-8143-5067A2B18330/GUID-6FFF6FDB-1A8F-5503-9F0E-D31B7F21CD12">device status change</xref> by calling <xref href="GUID-CE22C141-E1DC-38BB-AC11-76853A7B2590.dita#GUID-CE22C141-E1DC-38BB-AC11-76853A7B2590/GUID-ED633D07-535A-3B07-9DEF-B19688542E7B"><apiname>MLbsLocationSourceGpsObserver::UpdateDeviceStatus()</apiname></xref>. This message not shown on figure 2. </p> <p id="GUID-B661DC32-76A0-570D-B6B6-B0C69712C427"><b>LBS requests a location update (for a GPS position fix or GPS measurements)</b> </p> <p>LBS calls <xref href="GUID-A458AA58-8BD6-303B-89E5-C99000376615.dita#GUID-A458AA58-8BD6-303B-89E5-C99000376615/GUID-C5784C56-C6BA-3D11-AFEB-D08CA8E3E083"><apiname>CLbsLocationSourceGpsBase::RequestLocationUpdate()</apiname></xref> to request a location update. The method should be implemented to return as soon as possible. At some later time the A-GPS Integration Module informs LBS that a location update is available by calling <xref href="GUID-CE22C141-E1DC-38BB-AC11-76853A7B2590.dita#GUID-CE22C141-E1DC-38BB-AC11-76853A7B2590/GUID-170901F1-435D-3BC1-985B-49BA0876BD92"><apiname>MLbsLocationSourceGpsObserver::UpdateLocation()</apiname></xref>. </p> <p>The full signature of the method is <codeph>RequestLocationUpdate(const
TTime &aTargetTime, const TLbsLocRequestQuality
&aQuality)</codeph>. </p> <p> <codeph>aTargetTime</codeph> specifies when a location update is required. When the GPS module responds by calling <xref href="GUID-CE22C141-E1DC-38BB-AC11-76853A7B2590.dita#GUID-CE22C141-E1DC-38BB-AC11-76853A7B2590/GUID-170901F1-435D-3BC1-985B-49BA0876BD92"><apiname>MLbsLocationSourceGpsObserver::UpdateLocation()</apiname></xref> it is <codeph>aTargetTime</codeph> that is used to couple a location update request and response within the LBS subsystem. Therefore an Integration Module must use <codeph>aTargetTime</codeph> to identify the response to LBS. </p> <p> <codeph>aQuality</codeph> specifies quality criteria for the request including the required position accuracy and a <codeph>MaxFixTime</codeph> which is the maximum time that the Integration Module should spend processing the location request. If the Integration Module is not capable of delivering a position within <codeph>MaxFixTime</codeph> then it must return an incomplete update. See the section <xref href="GUID-5DD17088-1F9C-5810-8143-5067A2B18330.dita#GUID-5DD17088-1F9C-5810-8143-5067A2B18330/GUID-B3949496-29ED-55B6-BB2F-25BA85CC662E">Module notifies LBS of a location update</xref> for more details. </p> <p id="GUID-23A6EF21-DF43-5894-8159-27442A6828C6"><b>Module requests assistance data (if necessary)</b> </p> <p>Depending on the GPS mode that was set before the location request was made and the age of any assistance data it may already have, an A-GPS Integration Module may request assistance data from the LBS subsystem by calling <xref href="GUID-CE22C141-E1DC-38BB-AC11-76853A7B2590.dita#GUID-CE22C141-E1DC-38BB-AC11-76853A7B2590/GUID-B111B2A2-C52C-3D98-B82B-30958017AE5E"><apiname>MLbsLocationSourceGpsObserver::RequestAssistanceData()</apiname></xref>. </p> <p>The Integration Module specifies the type of assistance data it requires by creating a <xref href="GUID-DA483177-76AC-3110-A9BD-9CD97BF590CD.dita"><apiname>TLbsAsistanceDataGroup</apiname></xref> bitmask which contains bit values from the <xref href="GUID-58DA9D8B-50F6-38CB-B5BC-D8C1784ACFDB.dita"><apiname>TLbsAssistanceDataItem</apiname></xref> enumeration. Each value of <codeph>TLbsAssistanceDataItem</codeph> specifies a particular type of assistance data. </p> <p>The module passes a bitwise OR of <xref href="GUID-58DA9D8B-50F6-38CB-B5BC-D8C1784ACFDB.dita"><apiname>TLbsAssistanceDataItem</apiname></xref> values as a <xref href="GUID-DA483177-76AC-3110-A9BD-9CD97BF590CD.dita"><apiname>TLbsAsistanceDataGroup</apiname></xref> parameter in a call to <xref href="GUID-CE22C141-E1DC-38BB-AC11-76853A7B2590.dita#GUID-CE22C141-E1DC-38BB-AC11-76853A7B2590/GUID-B111B2A2-C52C-3D98-B82B-30958017AE5E"><apiname>MLbsLocationSourceGpsObserver::RequestAssistanceData()</apiname></xref>. </p> <p> <b>Notes:</b> </p> <ol id="GUID-F5A7B705-AE6A-5EDB-AC33-261728E16306"><li id="GUID-6B0AD674-3E49-5790-858C-BC4DEB32E85B"><p>Calling <codeph>RequestAssistanceData()</codeph> causes LBS to retrieve new assistance data from the network. The LBS subsystem caches assistance data when it is retrieved. Before calling <codeph>RequestAssistanceData()</codeph> for new assistance data it is most efficient for an Integration Module to check the timestamp of the assistance data cached by LBS by calling <xref href="GUID-CE22C141-E1DC-38BB-AC11-76853A7B2590.dita#GUID-CE22C141-E1DC-38BB-AC11-76853A7B2590/GUID-680269D6-F65D-36B4-8738-6A7BD021B500"><apiname>MLbsLocationSourceGpsObserver::GetAssistanceDataItemTimeStamp()</apiname></xref>. The Integration Module can use the returned timestamp to decide if it the assistance data is still valid, or if it needs to obtain new data by calling <codeph>RequestAssistanceData()</codeph>. </p> <p>A licensee can implement an Integration Module to have its own assistance data cache. An Integration Module can be instructed to reset its assistance data cache. See <xref href="GUID-5DD17088-1F9C-5810-8143-5067A2B18330.dita#GUID-5DD17088-1F9C-5810-8143-5067A2B18330/GUID-906DA81C-CB41-58C4-8CA1-79552404B5B4">Resetting A-GPS assistance data</xref> for more information. </p> </li> <li id="GUID-07219A38-77AA-56FA-8300-5F0B9A837580"><p>If a Integration Module does not require assistance data (possibly because the assistance data it currently has is still accurate) then it must respond to <codeph>RequestLocationUpdate()</codeph> by calling <codeph>RequestAssistanceData() </codeph> with a parameter <codeph>bitmask=0</codeph>. </p> </li> </ol> <p id="GUID-4820CF1C-DE98-5CC1-9A0E-72C5874A28D0"><b>LBS notifies the A-GPS Integration Module of assistance data availability</b> </p> <p>When LBS obtains assistance data from the network it informs the module by calling <xref href="GUID-A458AA58-8BD6-303B-89E5-C99000376615.dita#GUID-A458AA58-8BD6-303B-89E5-C99000376615/GUID-0370A120-0222-3559-A4B5-89C997B192D7"><apiname>CLbsLocationSourceGpsBase::AssistanceDataEvent()</apiname></xref>. As shown in figure 2, this method may be called multiple times as new assistance data arrives from the network. LBS can call this method to deliver assistance data at any time, not just immediately after a module calls <codeph>RequestAssistanceData()</codeph>. </p> <p>The type of assistance data available is indicated by a <xref href="GUID-DA483177-76AC-3110-A9BD-9CD97BF590CD.dita"><apiname>TLbsAsistanceDataGroup</apiname></xref> bitmask parameter which contains <xref href="GUID-58DA9D8B-50F6-38CB-B5BC-D8C1784ACFDB.dita"><apiname>TLbsAssistanceDataItem</apiname></xref> values. </p> <p> <b>Note: </b> This method is used to notify LBS of a network error during a location request in which case the status parameter is set to a negative error code (a network or network protocol specific error code). </p> <p id="GUID-9FEAEAA5-1555-5ADC-AF92-DC2C1BF00278"><b>Module retrieves A-GPS assistance data items</b> </p> <p>When it is notified that assistance data is available, the A-GPS Integration Module uses <xref href="GUID-CE22C141-E1DC-38BB-AC11-76853A7B2590.dita#GUID-CE22C141-E1DC-38BB-AC11-76853A7B2590/GUID-AAEE001E-B121-3590-88A8-97200645BFA9"><apiname>MLbsLocationSourceGpsObserver::GetAssistanceDataItem()</apiname></xref> to get obtain it. </p> <p>Where more than one item of assistance data is available (as indicated by the <xref href="GUID-DA483177-76AC-3110-A9BD-9CD97BF590CD.dita"><apiname>TLbsAsistanceDataGroup</apiname></xref> bitmask parameter passed with <xref href="GUID-A458AA58-8BD6-303B-89E5-C99000376615.dita#GUID-A458AA58-8BD6-303B-89E5-C99000376615/GUID-0370A120-0222-3559-A4B5-89C997B192D7"><apiname>CLbsLocationSourceGpsBase::AssistanceDataEvent()</apiname></xref>) it is necessary to call <codeph>GetAssistanceDataItem()</codeph> for each item. </p> <p id="GUID-B3949496-29ED-55B6-BB2F-25BA85CC662E"><b>Module notifies LBS of a location update</b> </p> <p>When the Integration Module calculates a GPS position fix or has obtained GPS position measurements it calls <xref href="GUID-CE22C141-E1DC-38BB-AC11-76853A7B2590.dita#GUID-CE22C141-E1DC-38BB-AC11-76853A7B2590/GUID-170901F1-435D-3BC1-985B-49BA0876BD92"><apiname>MLbsLocationSourceGpsObserver::UpdateLocation()</apiname></xref>. The parameter list of <codeph>UpdateLocation()</codeph> is as follows: </p> <p>void UpdateLocation(TInt aStatus, const TPositionInfoBase *aPosInfoArray[], TInt aNumItems, const TTime &aTargetTime); </p> <p> <codeph>aPosInfoArray</codeph> is a return parameter that is a pointer to an array of <xref href="GUID-73D6F438-C270-33B9-974B-D4D1583E1738.dita"><apiname>TPositionInfoBase</apiname></xref> objects. What an Integration Module returns in this parameter depends on the GPS positioning mode that was set by calling <xref href="GUID-A458AA58-8BD6-303B-89E5-C99000376615.dita#GUID-A458AA58-8BD6-303B-89E5-C99000376615/GUID-353317B8-81BE-3C9D-8186-CC7CB1056AA1"><apiname>CLbsLocationSourceGpsBase::SetGpsOptions()</apiname></xref>. </p> <ul><li id="GUID-E3302167-A878-5327-9F85-5ECB09D37FB2"><p>Autonomous mode and Terminal Based mode </p> <p>The Integration Module returns a pointer to a single <xref href="GUID-54AE0674-C49D-3329-8B77-3A58EFFC03D7.dita"><apiname>TPositionSatelliteInfo</apiname></xref> object. It contains a position fix and GPS satellite details. The position fix may be incomplete if the Integration Module was unable to calculate the position completely before the <codeph>MaxFixTime</codeph> (specified as part of the location request) expired. For example, a position may be returned that contains only horizontal but not vertical co-ordinates. Missing co-ordinate values are set to NaN. </p> <p>Up until <codeph>MaxFixTime</codeph>, an Integration Module calls <xref href="GUID-CE22C141-E1DC-38BB-AC11-76853A7B2590.dita#GUID-CE22C141-E1DC-38BB-AC11-76853A7B2590/GUID-170901F1-435D-3BC1-985B-49BA0876BD92"><apiname>MLbsLocationSourceGpsObserver::UpdateLocation()</apiname></xref> whenever it has calculated a more accurate or complete position fix. </p> </li> <li id="GUID-6E130074-B491-530F-A63E-4984342601B0"><p>Terminal Assisted mode </p> <p>The Integration Module returns a pointer to a single <xref href="GUID-66C5B5DB-6B9A-3071-816C-F51AEED2E8DE.dita"><apiname>TPositionGpsMeasurementInfo</apiname></xref> object. It contains a set of GPS measurements, but not a position fix. </p> <p>Up until <codeph>MaxFixTime</codeph>, an Integration Module calls <xref href="GUID-CE22C141-E1DC-38BB-AC11-76853A7B2590.dita#GUID-CE22C141-E1DC-38BB-AC11-76853A7B2590/GUID-170901F1-435D-3BC1-985B-49BA0876BD92"><apiname>MLbsLocationSourceGpsObserver::UpdateLocation()</apiname></xref> whenever it obtains additional GPS measurements. Measurements are sent to the network where they are used to calculate a position. </p> </li> <li id="GUID-F621F779-D38E-53B9-8E5B-FDFAC1208451"><p>Terminal Based mode + Terminal Assisted mode (TB + TA) </p> <p>The Integration Module returns a pointer to an array of elements derived from class <xref href="GUID-73D6F438-C270-33B9-974B-D4D1583E1738.dita"><apiname>TPositionInfoBase</apiname></xref>. </p> <p>Specifically, the array has elements of the derived classes <xref href="GUID-54AE0674-C49D-3329-8B77-3A58EFFC03D7.dita"><apiname>TPositionSatelliteInfo</apiname></xref> and <xref href="GUID-66C5B5DB-6B9A-3071-816C-F51AEED2E8DE.dita"><apiname>TPositionGpsMeasurementInfo</apiname></xref>. The number and type of elements returned must be as specified by LBS when it set the GPS mode. In practice, this means that the array returned by an Integration Module must have two elements: </p> <ul><li id="GUID-1824215B-DEB2-5D40-8441-45B44702B55E"><p>The first element is of class <xref href="GUID-54AE0674-C49D-3329-8B77-3A58EFFC03D7.dita"><apiname>TPositionSatelliteInfo</apiname></xref> (and contains a position fix that may be incomplete) </p> </li> <li id="GUID-8ADABF7B-98DE-5E07-AE72-9C3B9D760D8E"><p>The second element is of class <xref href="GUID-66C5B5DB-6B9A-3071-816C-F51AEED2E8DE.dita"><apiname>TPositionGpsMeasurementInfo</apiname></xref> and contains GPS measurements. </p> </li> </ul> <p>As in TA and TB modes, the Integration Module calls <xref href="GUID-CE22C141-E1DC-38BB-AC11-76853A7B2590.dita#GUID-CE22C141-E1DC-38BB-AC11-76853A7B2590/GUID-170901F1-435D-3BC1-985B-49BA0876BD92"><apiname>MLbsLocationSourceGpsObserver::UpdateLocation()</apiname></xref> whenever it obtains additional GPS measurements or calculates a more accurate or complete position fix (up until the location request <codeph>MaxFixTime</codeph>). </p> </li> </ul> <p> <b>Error codes</b> </p> <p>An Integration Module must return a location update (positions and/or measurements) by the <codeph>MaxFixTime</codeph> that was specified by LBS in <xref href="GUID-A458AA58-8BD6-303B-89E5-C99000376615.dita#GUID-A458AA58-8BD6-303B-89E5-C99000376615/GUID-C5784C56-C6BA-3D11-AFEB-D08CA8E3E083"><apiname>CLbsLocationSourceGpsBase::RequestLocationUpdate()</apiname></xref>. If an Integration Module has only incomplete data by <codeph>MaxFixTime</codeph> it must return it (<codeph>aStatus == KErrNone</codeph>). </p> <p>If an Integration Module decides that it will be unable to calculate a position fix with the specified quality criteria, then rather than waiting until <codeph>MaxFixTime</codeph> it can return its best available position (which may be incomplete or contain invalid data) with <codeph>aStatus ==
KPositionCalculationFutile</codeph>. </p> <p id="GUID-84D16C45-7ABC-5701-9E02-AF5EEFB34565"><b>Cancelling a location update request</b> </p> <p>LBS can cancel an outstanding location request by calling <xref href="GUID-A458AA58-8BD6-303B-89E5-C99000376615.dita#GUID-A458AA58-8BD6-303B-89E5-C99000376615/GUID-F6BC1743-7DD3-30FD-9E94-BC13E907D17C"><apiname>CLbsLocationSourceGpsBase::CancelLocationRequest()</apiname></xref> (not shown on figure 2). </p> <p id="GUID-906DA81C-CB41-58C4-8CA1-79552404B5B4"><b>Resetting A-GPS assistance data</b> </p> <p>During testing it is useful to be able to reset some or all of the A-GPS assistance data cached by an Integration Module. One of the main benefits is to allow the Time To First Fix (TTFF) of a module to be tested without the need to restart the LBS subsystem or the mobile device. </p> <p>A licensee Network Protocol Module calls <xref href="GUID-A97ABAA7-46B0-3E26-97C6-123C92CCEEE4.dita#GUID-A97ABAA7-46B0-3E26-97C6-123C92CCEEE4/GUID-24F29872-17BA-3B13-A7A3-B36113786964"><apiname>MLbsNetworkProtocolObserver::ProcessAssistanceData()</apiname></xref> to tell the LBS subsystem to reset some or all of its assistance data. The Network Protocol Module passes a parameter value of <xref href="GUID-0F4B82BB-37D6-35AD-993B-F766E1CF0637.dita"><apiname>KPositionAssistanceDataReset</apiname></xref> to specify that LBS must clear the assistance data in its cache and a <xref href="GUID-343E1FD7-9D75-3A41-84EC-B35030C06557.dita"><apiname>TLbsAssistanceDataGroup</apiname></xref> parameter to specify the bitmask of types of assistance data that must be reset. </p> <p>LBS responds by clearing the specified types of assistance data in its own cache. It also calls <xref href="GUID-A458AA58-8BD6-303B-89E5-C99000376615.dita#GUID-A458AA58-8BD6-303B-89E5-C99000376615/GUID-0370A120-0222-3559-A4B5-89C997B192D7"><apiname>CLbsLocationSourceGpsBase::AssistanceDataEvent()</apiname></xref> on the Integration Module with a <xref href="GUID-0F4B82BB-37D6-35AD-993B-F766E1CF0637.dita"><apiname>KPositionAssistanceDataReset</apiname></xref> parameter to specify an assistance data reset and a <xref href="GUID-343E1FD7-9D75-3A41-84EC-B35030C06557.dita"><apiname>TLbsAssistanceDataGroup</apiname></xref> parameter to specify the bitmask of types of assistance data that must be reset. If the licensee A-GPS Integration Module implements its own assistance data cache it must clear the types of assistance data specified by LBS. </p> <p>Figure 3 shows a simple sequence for assistance data reset, followed by the start of an MO-LR. </p> <fig id="GUID-1EE2C2E5-AD4F-50F7-B05E-EE9FFDF9B0D6"><title>
Figure 3. Assistance data reset before location request
</title> <image href="GUID-7C6FB773-0F87-5937-BF44-BEB8F4B6A62C_d0e434816_href.png" placement="inline"/></fig> <p id="GUID-6FFF6FDB-1A8F-5503-9F0E-D31B7F21CD12"><b>GPS hardware device status changes and quality status changes</b> </p> <p>(Not shown on figure 2) </p> <p><b>Device status changes </b> </p> <p>When the base GPS hardware changes its power mode the Integration Module must notify LBS by calling <xref href="GUID-CE22C141-E1DC-38BB-AC11-76853A7B2590.dita#GUID-CE22C141-E1DC-38BB-AC11-76853A7B2590/GUID-ED633D07-535A-3B07-9DEF-B19688542E7B"><apiname>MLbsLocationSourceGpsObserver::UpdateDeviceStatus()</apiname></xref>. </p> <p><b>Quality status changes </b> </p> <p>If an Integration Module detects that there is a change in the quality of position it is able to provide it must notify LBS by calling <xref href="GUID-CE22C141-E1DC-38BB-AC11-76853A7B2590.dita#GUID-CE22C141-E1DC-38BB-AC11-76853A7B2590/GUID-1EDA3DF0-392A-3362-B8FA-58E822D5FC21"><apiname>MLbsLocationSourceGpsObserver::UpdateDataQualityStatus()</apiname></xref>. </p> <p>See <xref href="GUID-AC7069ED-8CA5-55FC-9DF6-595C0505C672.dita">here</xref> for more information about how client applications can get updates of device status changes and quality status changes. </p> </section> <section id="GUID-3CBF2797-5F9D-50B2-A74A-1810A943CEAA"><title>Integration module configuration</title> <p>In addition to coding the Integration Module, there are configuration steps that a licensee must complete: </p> <p><b>Create a GPS Integration Module .ini file</b> </p> <p>The GPS Integration Module .ini file identifies a GPS 'source of location' to LBS. This is the pairing of the GPS/A-GPS Integration Module ECom plug-in with the A-GPS Location Manager process. </p> <p>The module .ini file created by a device creator for their own Integration Module must have the same layout as the following example and it must be exported to <filepath><rom_drive>:\private\10282253\lbs\locmods\</filepath> (<codeph>10282253</codeph> is the UID3 of the LBS Root process). </p> <codeblock id="GUID-2A4885EC-7129-5055-B678-55B8CA1FF3F5" xml:space="preserve">
# example_datasource.ini
[1]
Version= 0.2.1 #
ModuleId= 271064388 # dec
ModuleName= "Example_AGPS_Module”
TechnologyType= 0101 # binary
DeviceLocation= 1 # binary
Capabilities= 11111 # binary
ClassesSupported= 111111 # binary
TimeToFirstFix= 90000 # ms
TimeToNextFix= 1000 # ms
HorizontalAccuracy= 5.4 # real
VerticalAccuracy= 5.4 # real
CostIndicator= 2 # dec
PowerConsumption= 2 # dec
DataSourceId= 271065673 # dec
ExecutableName= "lbsgpslocmanager.exe"
DeviceGpsModeCaps=1011 # binary - Exclusive TA OR TB (+ Autonomous)</codeblock> <p>The table below describes each of the values in a module .ini file. </p> <p>Note: the <codeph>ModuleId</codeph> UID is decimal and must be the UID of the A-GPS Location Manager process. The <codeph>DataSourceId</codeph> UID is also decimal and is the implementation UID of the Integration Module ECOM plug-in. </p> <table id="GUID-5D6649C5-E761-59A5-AC79-90FC684C0999"><tgroup cols="3"><colspec colname="col0"/><colspec colname="col1"/><colspec colname="col2"/><thead><row><entry> Parameter </entry> <entry> Type </entry> <entry> Description </entry> </row> </thead> <tbody><row><entry><p>Version </p> </entry> <entry><p>A string </p> </entry> <entry><p>The GPS Integration Module version. </p> </entry> </row> <row><entry><p>ModuleId </p> </entry> <entry><p>A UID (decimal) </p> </entry> <entry><p>The UID3 of the location manager process that uses this GPS Integration Module. </p> </entry> </row> <row><entry><p>TechnologyType </p> </entry> <entry><p>A binary value from <xref href="GUID-B098F3DB-E2FE-3C5A-8508-4B04D954AB26.dita#GUID-B098F3DB-E2FE-3C5A-8508-4B04D954AB26/GUID-03AF8C51-1CAF-3F4C-BED1-17844FAE8423"><apiname>TPositionModuleInfo::_TTechnologyType</apiname></xref> </p> </entry> <entry><p>The technology types the module supports: one or more of handset based, network based or network assisted. </p> </entry> </row> <row><entry><p>DeviceLocation </p> </entry> <entry><p>A bitmask value from <xref href="GUID-B098F3DB-E2FE-3C5A-8508-4B04D954AB26.dita#GUID-B098F3DB-E2FE-3C5A-8508-4B04D954AB26/GUID-3AD1FF55-D635-3C41-AB06-EF426E0B6993"><apiname>TPositionModuleInfo::_TDeviceLocation</apiname></xref> </p> </entry> <entry><p>Specifies whether the GPS Integration Module is internal or external to the handset. Currently only internal modules are supported. Defined in <filepath>LbsCommon.h</filepath>. </p> </entry> </row> <row><entry><p>Capabilities </p> </entry> <entry><p>A bitmask value from <xref href="GUID-B098F3DB-E2FE-3C5A-8508-4B04D954AB26.dita#GUID-B098F3DB-E2FE-3C5A-8508-4B04D954AB26/GUID-C798CBA5-39BE-3072-9E9B-5910C4835DCC"><apiname>TPositionModuleInfo::_TCapabilities</apiname></xref> </p> </entry> <entry><p>A bitmask value that defines the capabilities of this module (such as the ability to provide vertical position and speed data). Defined in <filepath>LbsCommon.h</filepath>. </p> </entry> </row> <row><entry><p>ClassesSupported </p> </entry> <entry><p>A bitmask value from <xref href="GUID-BC8B2D08-1B64-35BB-8F58-4E7123650BD7.dita"><apiname>_TPositionInfoClassType</apiname></xref> </p> </entry> <entry><p>A bitmask value that defines the class types that are supported by this module. Defined in <filepath>LbsClassTypes.h</filepath>. </p> </entry> </row> <row><entry><p>TimeToFirstFix </p> </entry> <entry><p>An integer value </p> </entry> <entry><p>The time to get the first location fix (in milliseconds) </p> </entry> </row> <row><entry><p>TimeToNextFix </p> </entry> <entry><p>An integer value </p> </entry> <entry><p>The time to get subsequent location fixes after the first location fix (in milliseconds). </p> </entry> </row> <row><entry><p>HorizontalAccuracy </p> </entry> <entry><p>A real value </p> </entry> <entry><p>The maximum accuracy of horizontal position that the module can supply (in metres). For example 100 if the location fix is accurate to within 100m. </p> </entry> </row> <row><entry><p>VerticalAccuracy </p> </entry> <entry><p>A real value </p> </entry> <entry><p>The maximum accuracy of vertical position that the module can supply (in metres). </p> </entry> </row> <row><entry><p>CostIndicator </p> </entry> <entry><p>A value from <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> </p> </entry> <entry><p>A qualitative measure of the financial cost to the handset owner of using this module to obtain a location fix. Defined in <filepath>LbsCommon.h</filepath>. </p> </entry> </row> <row><entry><p>PowerConsumption </p> </entry> <entry><p>A value from <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> </p> </entry> <entry><p>A qualitative measure of the power consumption of using this module to obtain a location fix. Defined in <filepath>LbsCommon.h</filepath>. </p> </entry> </row> <row><entry><p>DataSourceId </p> </entry> <entry><p>A UID (decimal) </p> </entry> <entry><p>The UID3 of the module ECOM plug-in. </p> </entry> </row> <row><entry><p>ExecutableName </p> </entry> <entry><p>A string </p> </entry> <entry><p>The name of the location manager process that uses this module. </p> </entry> </row> <row><entry><p>DeviceGpsModeCaps </p> </entry> <entry><p>A binary value </p> </entry> <entry><p>The positioning modes supported by the module. The values are defined in <filepath>LbsExtendModuleInfo.h</filepath>. Possible values are: </p> <p>0001 - Module supports Terminal Based positioning and is also able to calculate position autonomously if assistance data is unavailable, or does not arrive on time (e.g. a fix is obtained before assistance data delivery). </p> <p>0010 - Module supports Terminal Assisted positioning. The module may, but does not have to be able to calculate position autonomously if Terminal Assisted positioning does not succeed (e.g. network is unavailable). </p> <p>0011 - Module supports Terminal Based positioning OR Terminal Assisted positioning and is also able to calculate position autonomously if assistance data is unavailable, or does not arrive on time (e.g. a fix is obtained before assistance data delivery). </p> <p>0100 - Module can perform Terminal Assisted AND Terminal Based positioning at the same time. It is also able to calculate position autonomously if assistance data is unavailable (e.g. network error), or does not arrive on time (e.g. a fix is obtained before assistance data delivery). NOTE: If this bit is set then it is not necessary to set either of the less significant 2 bits as they are implied. </p> <p> <i>If DeviceGpsModeCaps is not specified in this file, LBS assumes that the module can support both Terminal Based AND Terminal Assisted GPS modes at the same time.</i> </p> </entry> </row> </tbody> </tgroup> </table> <p><b> Create an Integration Module .rss file</b> </p> <p>A GPS Integration Module is implemented as an ECOM plug-in and has a .rss resource file that specifies the UIDs of the interface and the implementation class. </p> <p> <b>The value of DataSourceId in the module .ini file is decimal and must be equal to the hexadecimal implementation_uid value specified in the module ECOM .rss file.</b> </p> <p>An example .rss file is shown below. The <codeph>implementation_uid</codeph> value of <codeph>0x10282249</codeph> is the hexadecimal value of the <codeph>DataSourceId</codeph> value of <codeph>271065673</codeph> specified in <filepath>example_datasource.ini</filepath> above. </p> <codeblock id="GUID-3D14C891-840D-510B-8CB0-1935E16CD3B2" xml:space="preserve">// example_datasource.rss
//
// The Example Data Source resource file
#include "ecom/registryinfov2.rh"
RESOURCE REGISTRY_INFO theInfo
{
resource_format_version = RESOURCE_FORMAT_VERSION_2;
dll_uid = 0x10281D6D;
interfaces =
{
INTERFACE_INFO
{
interface_uid = 0x10281D73;
implementations =
{
IMPLEMENTATION_INFO
{
implementation_uid = 0x10282249;
version_no = 1;
display_name = "Example GPS Module";
default_data = "";
opaque_data = "";
rom_only = 0;
}
};
}
};
}
</codeblock> <p>The <filepath>module.ini</filepath> file described in the <xref href="GUID-D18B4715-3942-52EA-9D2F-E145037FA47A.dita">LBS integration and configuration guide</xref> must be modified to describe the capabilities of the Integration Module. Parameters that may need to be changed by licensees include the time to get a first fix and the accuracy of position fixes that can be delivered. </p> <p><b>Update the LBS administration settings</b> </p> <p>The <xref href="GUID-23BBC1D8-B3A0-5148-A4F1-22ECF3043E4E.dita">LBS administration</xref> setting <codeph>KLbsSettingHomeGpsMode</codeph> (and <codeph>KLbsSettingRoamingGpsMode</codeph>) must be set. The settings specify the default GPS positioning mode that LBS sets for the Integration Module. A default value can be specified in the <xref href="GUID-852E58C1-EA5C-5B46-9020-4463D3FA06AD.dita">administration repository initialisation file</xref> and it can also be set at runtime via the <xref href="GUID-9348D79B-D4BF-50B0-B787-DDA2765CE058.dita">LBS Administration API</xref>. The set of GPS positioning mode values are defined by <xref href="GUID-E8B4B321-6B45-3764-ADD2-CD05A5533945.dita#GUID-E8B4B321-6B45-3764-ADD2-CD05A5533945/GUID-9F902F01-29A3-3929-B045-83C72DB96E39"><apiname>CLbsAdmin::TGpsMode</apiname></xref>. </p> <p>Note : When the network is involved in a location request (which it is for any GPS mode other than autonomous) it can request a GPS mode that overrides the administration setting. For more information about how the positioning mode is set and the behaviour that the LBS subsystem expects from an Integration Module see <xref href="GUID-5DD17088-1F9C-5810-8143-5067A2B18330.dita#GUID-5DD17088-1F9C-5810-8143-5067A2B18330/GUID-EF629CC3-EFA8-559E-970C-1AC5B7B93324">LBS sets GPS options</xref>. </p> </section> </conbody></concept>