--- a/Symbian3/PDK/Source/GUID-CB6B4D1A-ACB9-5571-8C23-4BC095209782.dita Fri Jul 02 12:51:36 2010 +0100
+++ b/Symbian3/PDK/Source/GUID-CB6B4D1A-ACB9-5571-8C23-4BC095209782.dita Fri Jul 16 17:23:46 2010 +0100
@@ -11,17 +11,17 @@
PUBLIC "-//OASIS//DTD DITA Concept//EN" "concept.dtd">
<concept xml:lang="en" id="GUID-CB6B4D1A-ACB9-5571-8C23-4BC095209782"><title>Network Protocol Module API</title><shortdesc>This document describes the Network Protocol Module API that device creators use to develop their own Network Protocol Modules. </shortdesc><prolog><metadata><keywords/></metadata></prolog><conbody><section><title>Contents</title> <ul><li id="GUID-E10D1711-CDF1-5D84-B31C-9EABA33EDA13"><p><xref href="GUID-CB6B4D1A-ACB9-5571-8C23-4BC095209782.dita#GUID-CB6B4D1A-ACB9-5571-8C23-4BC095209782/GUID-0474B8C6-C136-5106-B1D7-F9C9D29C4B5C">Purpose</xref> </p> </li> <li id="GUID-03A88FE5-E7FF-5419-A918-AB7281214B36"><p><xref href="GUID-CB6B4D1A-ACB9-5571-8C23-4BC095209782.dita#GUID-CB6B4D1A-ACB9-5571-8C23-4BC095209782/GUID-770450CB-F7A8-52CF-8567-D4C2A10C093A">Introduction</xref> </p> </li> <li id="GUID-F76EA1F7-8592-563F-8ADD-4C3D5DC73C70"><p><xref href="GUID-CB6B4D1A-ACB9-5571-8C23-4BC095209782.dita#GUID-CB6B4D1A-ACB9-5571-8C23-4BC095209782/GUID-78FAF5FC-FE2E-580B-A937-EFA61834CD0E">Network Protocol Module API description</xref> </p> </li> <li id="GUID-2F039FA6-737B-5F03-891B-840DF39E0CFB"><p><xref href="GUID-CB6B4D1A-ACB9-5571-8C23-4BC095209782.dita#GUID-CB6B4D1A-ACB9-5571-8C23-4BC095209782/GUID-FE060846-86FD-5E89-99CB-10E6433120F4">Using the Network Protocol Module API</xref> </p> </li> <li id="GUID-A131C0D2-F71E-5AD2-BF16-A491408F153B"><p><xref href="GUID-CB6B4D1A-ACB9-5571-8C23-4BC095209782.dita#GUID-CB6B4D1A-ACB9-5571-8C23-4BC095209782/GUID-F4DA8C85-7F74-5FA6-BF05-1DC2636AD764">Network Protocol Module configuration</xref> </p> </li> <li id="GUID-90F0A861-8E04-5B37-B63A-EFC88C18FFFE"><p><xref href="GUID-CB6B4D1A-ACB9-5571-8C23-4BC095209782.dita#GUID-CB6B4D1A-ACB9-5571-8C23-4BC095209782/GUID-CF0C5893-5871-51FA-8AA5-9889010ED031">Loading the Network Protocol Module</xref> </p> </li> <li id="GUID-EC92600E-E7BF-57B4-9D19-14849183F414"><p><xref href="GUID-CB6B4D1A-ACB9-5571-8C23-4BC095209782.dita#GUID-CB6B4D1A-ACB9-5571-8C23-4BC095209782/GUID-6CCBFCC2-0948-5929-BDB8-B91E479C79F9">See also</xref> </p> </li> </ul> </section> <section id="GUID-0474B8C6-C136-5106-B1D7-F9C9D29C4B5C"><title>Purpose</title> <p>A Network Protocol Module is an ECOM plug-in that provides network connectivity for the LBS subsystem. A Network Protocol Module typically supports one Location Based Services network protocol. Location Based Services network protocols are used by the LBS subsystem for the following purposes: </p> <ul><li id="GUID-E10F3069-67E0-5AE5-8A53-F8707C5BB027"><p>To receive location requests from the network. </p> </li> <li id="GUID-61D90CB4-6F74-5B85-B1B3-EC246937BDBA"><p>To send requests for A-GPS assistance data to the network and to receive it. </p> </li> <li id="GUID-41E09C92-B6A9-5071-92F2-CE6BA23E05CA"><p>To send GPS-calculated positions and GPS measurements to the network and to receive calculated positions from the network. </p> </li> </ul> <p>Network Protocol Modules can be classified into two groups, depending on the network operator's network architecture that they are intended to interface with: </p> <ul><li id="GUID-7D75D9E5-E825-5E40-8C84-F77A16D83E98"><p> <i>Control plane architectures</i> use the circuit-switched mobile network and signalling layer to support Location Based Services. </p> <p>To integrate the Symbian LBS subsystem with a control plane architecture, a Symbian licensee must implement their own control plane Network Protocol Module using the Network Protocol Module API described in this document. </p> </li> <li id="GUID-6A3526E2-8C80-56F7-912C-3A892DEBCDEE"><p> <i>User plane architectures</i> use IP bearers independently of the circuit-switched signalling layer. SMS or WAP Push can also be used to initiate location requests. The OMA Secure User Plane Location (SUPL) architecture describes a model for supporting IP-based Location Based Services. </p> <p>Symbian provides a reference <xref href="GUID-816334A7-488B-5F91-8C2E-47076D875013.dita">SUPL Protocol Module</xref> that supports the OMA SUPL v1.0 standard, using the 3GPP Radio Resource LCS Protocol (RRLP) as the protocol payload. The reference SUPL Protocol Module implements the Network Protocol Module API. </p> </li> </ul> <p><xref href="GUID-7233BC33-6060-5D6B-A5D2-01135F059337.dita">LBS architecture overview</xref> gives more details of how a Network Protocol Module fits into the LBS subsystem. </p> </section> <section id="GUID-770450CB-F7A8-52CF-8567-D4C2A10C093A"><title>Introduction</title> <p>A Network Protocol Module is an ECOM plug-in DLL. It communicates with the LBS Network Gateway process via the Network Protocol API and with the network via either the ETel or ESock APIs as shown in figure 1. </p> <fig id="GUID-4E4828B3-2EB3-507B-A2EC-85FA3B096D34"><title>
Figure 1. The Network Gateway Framework
- </title> <image href="GUID-749B7949-8731-519E-8948-CA3E1C5D6861_d0e445911_href.png" placement="inline"/></fig> <p>A Network Protocol Module has several functions: </p> <ul><li id="GUID-B0D80EFC-7B08-5387-88E4-78E814CA1C33"><p>Translating method calls from the LBS subsystem into protocol specific messages which are sent over the network </p> </li> <li id="GUID-8B537CB1-B74A-5CCD-A3C4-518362A4866E"><p>Translating protocol specific messages received from the network into method calls on the LBS subsystem </p> </li> <li id="GUID-9EEB1554-CA73-5DB4-91AA-48470B808207"><p>Queueing and prioritising messages received from the network and messages to be sent to the network </p> </li> <li id="GUID-1299C065-7AF9-5AB8-9ED0-EB3E8CCBC4FC"><p>Performing conflict resolution when a request is made which conflicts with ongoing location requests being processed by the LBS subsystem </p> </li> </ul> <p>Licensees can configure the LBS subsystem to load a different Network Protocol Module when the mobile device is in the home network and when roaming. For example, it is possible to configure LBS to load a licensee control plane Network Protocol Module in the home network and the Symbian reference SUPL Protocol Module when roaming. See <xref href="GUID-CB6B4D1A-ACB9-5571-8C23-4BC095209782.dita#GUID-CB6B4D1A-ACB9-5571-8C23-4BC095209782/GUID-CF0C5893-5871-51FA-8AA5-9889010ED031">Loading the Network Protocol Module</xref> for more details. </p> <p>A Symbian licensee must create a Network Protocol Module to integrate the Symbian LBS subsystem with a control plane architecture. A control plane Network Protocol Module uses the ETel API and the telephony stack for network communications. Symbian does not provide a reference control plane Network Protocol Module. </p> <p>Symbian provides a reference Network Protocol Module that implements the SUPL v1.0 user plane architecture with RRLP as the protocol data payload. See <xref href="GUID-816334A7-488B-5F91-8C2E-47076D875013.dita">SUPL Protocol Module</xref> documentation for more information about this reference module. The SUPL Protocol Module may meet the requirements of Symbian licensees and network operators and so it may not be necessary for licensees to create a custom Network Protocol Module using the API described in this document. </p> <p>Symbian also provide a <i>Test Network Protocol Module</i> as part of the LBS subsystem code distribution which can be found at <filepath><LBS_ROOT>\LbsProtocolModule</filepath>. The test protocol module is not a production quality module for use in a mobile device, neither is it a reference implementation. Its main purpose is to facilitate Symbian's own testing of the LBS subsystem. </p> </section> <section id="GUID-78FAF5FC-FE2E-580B-A937-EFA61834CD0E"><title>Network Protocol Module API description</title> <p>This section describes the classes of the Network Protocol Module API. </p> <p><b>API class diagram </b> </p> <p>A Network Protocol Module and the LBS Network Gateway process communicate using the Network Protocol Module API. The API consists of classes in an observer/observable design pattern. </p> <p>Figure 2 shows the main classes of the Network Protocol Module API. Note that this diagram does not list all of the classes of the API and excludes numerous T classes that are used as method parameters. </p> <p> <b>Note that the virtual methods of CLbsNetworkProtocolBase and CLbsNetworkProtocolBase2 are synchronous and their implementations must return quickly (for example by queueing requests and returning immediately).</b> </p> <fig id="GUID-2B79661F-CE43-5A59-B966-AA7024A5D5E1"><title>
+ </title> <image href="GUID-749B7949-8731-519E-8948-CA3E1C5D6861_d0e451756_href.png" placement="inline"/></fig> <p>A Network Protocol Module has several functions: </p> <ul><li id="GUID-B0D80EFC-7B08-5387-88E4-78E814CA1C33"><p>Translating method calls from the LBS subsystem into protocol specific messages which are sent over the network </p> </li> <li id="GUID-8B537CB1-B74A-5CCD-A3C4-518362A4866E"><p>Translating protocol specific messages received from the network into method calls on the LBS subsystem </p> </li> <li id="GUID-9EEB1554-CA73-5DB4-91AA-48470B808207"><p>Queueing and prioritising messages received from the network and messages to be sent to the network </p> </li> <li id="GUID-1299C065-7AF9-5AB8-9ED0-EB3E8CCBC4FC"><p>Performing conflict resolution when a request is made which conflicts with ongoing location requests being processed by the LBS subsystem </p> </li> </ul> <p>Licensees can configure the LBS subsystem to load a different Network Protocol Module when the mobile device is in the home network and when roaming. For example, it is possible to configure LBS to load a licensee control plane Network Protocol Module in the home network and the Symbian reference SUPL Protocol Module when roaming. See <xref href="GUID-CB6B4D1A-ACB9-5571-8C23-4BC095209782.dita#GUID-CB6B4D1A-ACB9-5571-8C23-4BC095209782/GUID-CF0C5893-5871-51FA-8AA5-9889010ED031">Loading the Network Protocol Module</xref> for more details. </p> <p>A Symbian licensee must create a Network Protocol Module to integrate the Symbian LBS subsystem with a control plane architecture. A control plane Network Protocol Module uses the ETel API and the telephony stack for network communications. Symbian does not provide a reference control plane Network Protocol Module. </p> <p>Symbian provides a reference Network Protocol Module that implements the SUPL v1.0 user plane architecture with RRLP as the protocol data payload. See <xref href="GUID-816334A7-488B-5F91-8C2E-47076D875013.dita">SUPL Protocol Module</xref> documentation for more information about this reference module. The SUPL Protocol Module may meet the requirements of Symbian licensees and network operators and so it may not be necessary for licensees to create a custom Network Protocol Module using the API described in this document. </p> <p>Symbian also provide a <i>Test Network Protocol Module</i> as part of the LBS subsystem code distribution which can be found at <filepath><LBS_ROOT>\LbsProtocolModule</filepath>. The test protocol module is not a production quality module for use in a mobile device, neither is it a reference implementation. Its main purpose is to facilitate Symbian's own testing of the LBS subsystem. </p> </section> <section id="GUID-78FAF5FC-FE2E-580B-A937-EFA61834CD0E"><title>Network Protocol Module API description</title> <p>This section describes the classes of the Network Protocol Module API. </p> <p><b>API class diagram </b> </p> <p>A Network Protocol Module and the LBS Network Gateway process communicate using the Network Protocol Module API. The API consists of classes in an observer/observable design pattern. </p> <p>Figure 2 shows the main classes of the Network Protocol Module API. Note that this diagram does not list all of the classes of the API and excludes numerous T classes that are used as method parameters. </p> <p> <b>Note that the virtual methods of CLbsNetworkProtocolBase and CLbsNetworkProtocolBase2 are synchronous and their implementations must return quickly (for example by queueing requests and returning immediately).</b> </p> <fig id="GUID-2B79661F-CE43-5A59-B966-AA7024A5D5E1"><title>
Figure 2. Main classes of the Network Protocol API
- </title> <image href="GUID-A6E7C805-0515-5F3F-97DB-B5E1A84162B2_d0e445991_href.png" placement="inline"/></fig> <p><b>API classes and types </b> </p> <p>Table 1 lists the main classes of the Network Protocol Module API. Further details about the classes can be found by following the links to reference documentation. </p> <p>The main classes are defined in <filepath>lbsnetprotocolbase.h</filepath>. Additional API classes and types that are used as API method parameters are defined in <filepath>lbsnetcommon.h</filepath> and <filepath>lbsnetclasstypes.h</filepath>. </p> <p>The Network Protocol Module API has <codeph>publishedPartner</codeph> interface access. </p> <table id="GUID-76FAD546-57EB-5046-872A-B551AA94B3E7"><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-479C43CF-8787-3596-93ED-F03A8E5CA2F5.dita"><apiname>CLbsNetworkProtocolBase</apiname></xref> </p> </entry> <entry><p>The original base class for Network Protocol Module implementations. This class is extended by <xref href="GUID-AD071127-974A-35B4-A39F-340CDC6A1A81.dita"><apiname>CLbsNetworkProtocolBase2</apiname></xref> which should be used for new Network Protocol Module implementations. </p> </entry> <entry><p> <filepath>lbsnetprotocolbase.h</filepath> </p> </entry> </row> <row><entry><p> <xref href="GUID-AD071127-974A-35B4-A39F-340CDC6A1A81.dita"><apiname>CLbsNetworkProtocolBase2</apiname></xref> </p> </entry> <entry><p>Extended base class for Network Protocol Module implementations that should be used for new Network Protocol Module implementations. </p> </entry> <entry><p> <filepath>lbsnetprotocolbase.h</filepath> </p> </entry> </row> <row><entry><p> <xref href="GUID-A97ABAA7-46B0-3E26-97C6-123C92CCEEE4.dita"><apiname> MLbsNetworkProtocolObserver</apiname></xref> </p> </entry> <entry><p>The observer interface implemented by the LBS Network Gateway and used by a Network Protocol Module to forward network requests and information to the LBS subsystem. It is also the interface that a protocol module uses to provide responses to requests made by the LBS subsystem via <xref href="GUID-479C43CF-8787-3596-93ED-F03A8E5CA2F5.dita"><apiname>CLbsNetworkProtocolBase</apiname></xref>. </p> </entry> <entry><p> <filepath>lbsnetprotocolbase.h</filepath> </p> </entry> </row> <row><entry><p> <xref href="GUID-D7707B28-D173-3F41-899C-6BEE3C8C3D74.dita"><apiname> MLbsNetworkProtocolObserver2</apiname></xref> </p> </entry> <entry><p>An extended observer interface. This is not yet implemented by the LBS subsystem. </p> </entry> <entry><p> <filepath>lbsnetprotocolbase.h</filepath> </p> </entry> </row> </tbody> </tgroup> </table> <p> <i>Table 1 Classes of the Network Protocol Module API.</i> </p> <p>Network Protocol Modules derive from <xref href="GUID-479C43CF-8787-3596-93ED-F03A8E5CA2F5.dita"><apiname>CLbsNetworkProtocolBase</apiname></xref> or <xref href="GUID-AD071127-974A-35B4-A39F-340CDC6A1A81.dita"><apiname>CLbsNetworkProtocolBase2</apiname></xref>. The LBS subsystem implements the <xref href="GUID-A97ABAA7-46B0-3E26-97C6-123C92CCEEE4.dita"><apiname>MLbsNetworkProtocolObserver</apiname></xref> interface to interact with a Network Protocol Module. </p> <p><b>Libraries </b> </p> <p>The main classes of the Network Protocol Module API are packaged in <filepath>lbsnetprotocol.dll</filepath>. Network Protocol Module implementations link to <filepath>lbsnetprotocol.lib</filepath>. </p> <p><b>LBS configuration </b> </p> <p>In addition to creating and installing a Network Protocol Module, the <xref href="GUID-23BBC1D8-B3A0-5148-A4F1-22ECF3043E4E.dita">LBS administration settings</xref> <codeph>KLbsSettingHomeProtocolModule</codeph> and <codeph>KLbsSettingRoamingProtocolModule</codeph> must be set to the implementation UIDs of the appropriate Network Protocol Module ECOM plug-ins for LBS to load and use them. See <xref href="GUID-CB6B4D1A-ACB9-5571-8C23-4BC095209782.dita#GUID-CB6B4D1A-ACB9-5571-8C23-4BC095209782/GUID-CF0C5893-5871-51FA-8AA5-9889010ED031">Loading the Network Protocol Module</xref> for more information. </p> </section> <section id="GUID-FE060846-86FD-5E89-99CB-10E6433120F4"><title> Using the Network Protocol Module API</title> <p>A Network Protocol Module communicates with two other software components: </p> <ul><li id="GUID-D48F33D4-1BF4-53AE-A86F-CF70F90D5FAF"><p>The LBS Network Gateway process </p> <p>The Network Gateway process communicates with the other components of the LBS subsystem. It is responsible for: </p> <ol id="GUID-856B4F05-80D0-5810-942B-FDAD39418EF7"><li id="GUID-CDCA4733-48C3-5DE9-9A9C-E16BC77F32B4"><p>Handling requests for location from the LBS subsystem and sending them to the network via the Network Protocol Module </p> </li> <li id="GUID-CBC7AD37-EED9-5ACD-8788-AB90C3D3E436"><p>Receiving a reference position (based on Cell ID) from the network via the Network Protocol Module and sending it into LBS in response to 1. </p> </li> <li id="GUID-87B83DC3-F431-55BC-A4DF-3B984A11F2AF"><p>Handling requests for A-GPS assistance data from an A-GPS Integration Module and sending them to the network via the Network Protocol Module </p> </li> <li id="GUID-BECEF30D-3D49-56FF-B61C-F9AF6BD820CB"><p>Receiving A-GPS assistance data from the network via the Network Protocol Module and sending it to the A-GPS Location Manager in response to 3. </p> </li> <li id="GUID-53719E58-C76F-5D75-A874-0C361E14FB15"><p>Handling requests from the LBS subsystem to send device location data to a third party over the network (MO-LR transmit to third party). </p> </li> <li id="GUID-589FDE9F-9012-5857-81E8-676C33513685"><p>Receiving privacy requests and location requests from the network (MT-LR and Emergency MT-LR) via the Network Protocol Module and forwarding them to the LBS subsystem. </p> </li> <li id="GUID-7A8AD974-6545-5B2A-8DDC-5A6AF619104F"><p>Sending responses to MT-LR privacy requests and location requests to the network via the Network Protocol Module in response to 6. </p> </li> </ol> </li> <li id="GUID-55F2693F-2F1C-553C-A5E2-41F47D802061"><p>A network communications stack </p> <p>A Network Protocol Module that integrates with the control plane uses the Symbian ETel API. </p> <p>A Network Protocol Module that integrates with the user plane uses the Symbian ESock API. The Symbian reference <xref href="GUID-816334A7-488B-5F91-8C2E-47076D875013.dita">SUPL Protocol Module</xref> is a user plane Network Protocol Module. </p> </li> </ul> <p>Figures 3, 4 and 5 show simple sequences of interaction between the LBS Network Gateway process, the Network Protocol Module and the network for MO-LR (self locate), MO-LR (transfer to third party) and MT-LR. </p> <p>The behaviour of a Network Protocol Module can be complex when it is linked to a A-GPS Integration Module. Several detailed end-to-end sequence diagrams that document the behaviour of the LBS subsystem including the behaviour expected from a Network Protocol Module can be found in <xref href="GUID-D9EA897E-71FB-5012-8208-49300A19D22C.dita">LBS Sequence Diagrams</xref>. </p> <p> </p> <fig id="GUID-C3A0E3A3-4111-5F0D-ACF2-60DF51FED49C"><title>
+ </title> <image href="GUID-A6E7C805-0515-5F3F-97DB-B5E1A84162B2_d0e451836_href.png" placement="inline"/></fig> <p><b>API classes and types </b> </p> <p>Table 1 lists the main classes of the Network Protocol Module API. Further details about the classes can be found by following the links to reference documentation. </p> <p>The main classes are defined in <filepath>lbsnetprotocolbase.h</filepath>. Additional API classes and types that are used as API method parameters are defined in <filepath>lbsnetcommon.h</filepath> and <filepath>lbsnetclasstypes.h</filepath>. </p> <p>The Network Protocol Module API has <codeph>publishedPartner</codeph> interface access. </p> <table id="GUID-76FAD546-57EB-5046-872A-B551AA94B3E7"><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-479C43CF-8787-3596-93ED-F03A8E5CA2F5.dita"><apiname>CLbsNetworkProtocolBase</apiname></xref> </p> </entry> <entry><p>The original base class for Network Protocol Module implementations. This class is extended by <xref href="GUID-AD071127-974A-35B4-A39F-340CDC6A1A81.dita"><apiname>CLbsNetworkProtocolBase2</apiname></xref> which should be used for new Network Protocol Module implementations. </p> </entry> <entry><p> <filepath>lbsnetprotocolbase.h</filepath> </p> </entry> </row> <row><entry><p> <xref href="GUID-AD071127-974A-35B4-A39F-340CDC6A1A81.dita"><apiname>CLbsNetworkProtocolBase2</apiname></xref> </p> </entry> <entry><p>Extended base class for Network Protocol Module implementations that should be used for new Network Protocol Module implementations. </p> </entry> <entry><p> <filepath>lbsnetprotocolbase.h</filepath> </p> </entry> </row> <row><entry><p> <xref href="GUID-A97ABAA7-46B0-3E26-97C6-123C92CCEEE4.dita"><apiname> MLbsNetworkProtocolObserver</apiname></xref> </p> </entry> <entry><p>The observer interface implemented by the LBS Network Gateway and used by a Network Protocol Module to forward network requests and information to the LBS subsystem. It is also the interface that a protocol module uses to provide responses to requests made by the LBS subsystem via <xref href="GUID-479C43CF-8787-3596-93ED-F03A8E5CA2F5.dita"><apiname>CLbsNetworkProtocolBase</apiname></xref>. </p> </entry> <entry><p> <filepath>lbsnetprotocolbase.h</filepath> </p> </entry> </row> <row><entry><p> <xref href="GUID-D7707B28-D173-3F41-899C-6BEE3C8C3D74.dita"><apiname> MLbsNetworkProtocolObserver2</apiname></xref> </p> </entry> <entry><p>An extended observer interface. This is not yet implemented by the LBS subsystem. </p> </entry> <entry><p> <filepath>lbsnetprotocolbase.h</filepath> </p> </entry> </row> </tbody> </tgroup> </table> <p> <i>Table 1 Classes of the Network Protocol Module API.</i> </p> <p>Network Protocol Modules derive from <xref href="GUID-479C43CF-8787-3596-93ED-F03A8E5CA2F5.dita"><apiname>CLbsNetworkProtocolBase</apiname></xref> or <xref href="GUID-AD071127-974A-35B4-A39F-340CDC6A1A81.dita"><apiname>CLbsNetworkProtocolBase2</apiname></xref>. The LBS subsystem implements the <xref href="GUID-A97ABAA7-46B0-3E26-97C6-123C92CCEEE4.dita"><apiname>MLbsNetworkProtocolObserver</apiname></xref> interface to interact with a Network Protocol Module. </p> <p><b>Libraries </b> </p> <p>The main classes of the Network Protocol Module API are packaged in <filepath>lbsnetprotocol.dll</filepath>. Network Protocol Module implementations link to <filepath>lbsnetprotocol.lib</filepath>. </p> <p><b>LBS configuration </b> </p> <p>In addition to creating and installing a Network Protocol Module, the <xref href="GUID-23BBC1D8-B3A0-5148-A4F1-22ECF3043E4E.dita">LBS administration settings</xref> <codeph>KLbsSettingHomeProtocolModule</codeph> and <codeph>KLbsSettingRoamingProtocolModule</codeph> must be set to the implementation UIDs of the appropriate Network Protocol Module ECOM plug-ins for LBS to load and use them. See <xref href="GUID-CB6B4D1A-ACB9-5571-8C23-4BC095209782.dita#GUID-CB6B4D1A-ACB9-5571-8C23-4BC095209782/GUID-CF0C5893-5871-51FA-8AA5-9889010ED031">Loading the Network Protocol Module</xref> for more information. </p> </section> <section id="GUID-FE060846-86FD-5E89-99CB-10E6433120F4"><title> Using the Network Protocol Module API</title> <p>A Network Protocol Module communicates with two other software components: </p> <ul><li id="GUID-D48F33D4-1BF4-53AE-A86F-CF70F90D5FAF"><p>The LBS Network Gateway process </p> <p>The Network Gateway process communicates with the other components of the LBS subsystem. It is responsible for: </p> <ol id="GUID-856B4F05-80D0-5810-942B-FDAD39418EF7"><li id="GUID-CDCA4733-48C3-5DE9-9A9C-E16BC77F32B4"><p>Handling requests for location from the LBS subsystem and sending them to the network via the Network Protocol Module </p> </li> <li id="GUID-CBC7AD37-EED9-5ACD-8788-AB90C3D3E436"><p>Receiving a reference position (based on Cell ID) from the network via the Network Protocol Module and sending it into LBS in response to 1. </p> </li> <li id="GUID-87B83DC3-F431-55BC-A4DF-3B984A11F2AF"><p>Handling requests for A-GPS assistance data from an A-GPS Integration Module and sending them to the network via the Network Protocol Module </p> </li> <li id="GUID-BECEF30D-3D49-56FF-B61C-F9AF6BD820CB"><p>Receiving A-GPS assistance data from the network via the Network Protocol Module and sending it to the A-GPS Location Manager in response to 3. </p> </li> <li id="GUID-53719E58-C76F-5D75-A874-0C361E14FB15"><p>Handling requests from the LBS subsystem to send device location data to a third party over the network (MO-LR transmit to third party). </p> </li> <li id="GUID-589FDE9F-9012-5857-81E8-676C33513685"><p>Receiving privacy requests and location requests from the network (MT-LR and Emergency MT-LR) via the Network Protocol Module and forwarding them to the LBS subsystem. </p> </li> <li id="GUID-7A8AD974-6545-5B2A-8DDC-5A6AF619104F"><p>Sending responses to MT-LR privacy requests and location requests to the network via the Network Protocol Module in response to 6. </p> </li> </ol> </li> <li id="GUID-55F2693F-2F1C-553C-A5E2-41F47D802061"><p>A network communications stack </p> <p>A Network Protocol Module that integrates with the control plane uses the Symbian ETel API. </p> <p>A Network Protocol Module that integrates with the user plane uses the Symbian ESock API. The Symbian reference <xref href="GUID-816334A7-488B-5F91-8C2E-47076D875013.dita">SUPL Protocol Module</xref> is a user plane Network Protocol Module. </p> </li> </ul> <p>Figures 3, 4 and 5 show simple sequences of interaction between the LBS Network Gateway process, the Network Protocol Module and the network for MO-LR (self locate), MO-LR (transfer to third party) and MT-LR. </p> <p>The behaviour of a Network Protocol Module can be complex when it is linked to a A-GPS Integration Module. Several detailed end-to-end sequence diagrams that document the behaviour of the LBS subsystem including the behaviour expected from a Network Protocol Module can be found in <xref href="GUID-D9EA897E-71FB-5012-8208-49300A19D22C.dita">LBS Sequence Diagrams</xref>. </p> <p> </p> <fig id="GUID-C3A0E3A3-4111-5F0D-ACF2-60DF51FED49C"><title>
Figure 3. Simple MO-LR self locate sequence (for terminal based
positioning)
- </title> <image href="GUID-D98DA21C-B0F4-5267-AF00-94B789AE302A_d0e446285_href.png" placement="inline"/></fig> <fig id="GUID-74F19B87-DE33-5DEC-A15B-C5DEB4A864BF"><title>
+ </title> <image href="GUID-D98DA21C-B0F4-5267-AF00-94B789AE302A_d0e452130_href.png" placement="inline"/></fig> <fig id="GUID-74F19B87-DE33-5DEC-A15B-C5DEB4A864BF"><title>
Figure 4. Simple MO-LR transfer to third party sequence (for terminal
based positioning)
- </title> <image href="GUID-CE49EF9C-C87A-5D4C-91F3-5C2950A5553B_d0e446291_href.png" placement="inline"/></fig> <fig id="GUID-CAB47FC4-249B-5256-90E1-EE94F9577C8E"><title>
+ </title> <image href="GUID-CE49EF9C-C87A-5D4C-91F3-5C2950A5553B_d0e452136_href.png" placement="inline"/></fig> <fig id="GUID-CAB47FC4-249B-5256-90E1-EE94F9577C8E"><title>
Figure 5. Simple MT-LR sequence (for terminal based positioning)
- </title> <image href="GUID-C103A584-3498-5F0A-8F0B-F97D33749CEF_d0e446297_href.png" placement="inline"/></fig> <p><b>CLbsNetworkProtocolBase </b> </p> <p>The following briefly describes the <xref href="GUID-479C43CF-8787-3596-93ED-F03A8E5CA2F5.dita"><apiname>CLbsNetworkProtocolBase</apiname></xref> methods grouped according to their function. The LBS Network Gateway process calls these methods on the licensee Network Protocol Module. More detailed information about the purpose of these methods and their parameter lists can be found by following the links to the Symbian platform reference documentation. </p> <p> <b>Setting tracking mode (if necessary)</b> </p> <p>For MO-LR self locate, an application client can ask the LBS subsystem for periodic location updates. This is known as tracking and is described in the Location Acquisition API document <xref href="GUID-F6B5F777-D12F-5913-AECE-047DF8C72F1F.dita">How to get location information</xref>. </p> <p>When a client requests tracking, the LBS subsystem notifies a Network Protocol Module of this requirement by calling <xref href="GUID-479C43CF-8787-3596-93ED-F03A8E5CA2F5.dita#GUID-479C43CF-8787-3596-93ED-F03A8E5CA2F5/GUID-367DC79E-CB61-3EFB-9928-104F5B6A0021"><apiname>CLbsNetworkProtocolBase::AdviceSystemStatus()</apiname></xref> with a parameter value <xref href="GUID-479C43CF-8787-3596-93ED-F03A8E5CA2F5.dita#GUID-479C43CF-8787-3596-93ED-F03A8E5CA2F5/GUID-1546BC54-76FC-3C4C-BA99-CB13027687EE"><apiname>CLbsNetworkProtocolBase::ESystemStatusClientTracking</apiname></xref>. This method is called before the first location request <xref href="GUID-479C43CF-8787-3596-93ED-F03A8E5CA2F5.dita#GUID-479C43CF-8787-3596-93ED-F03A8E5CA2F5/GUID-0E4234D2-D8B0-302F-8DE5-EA47ED5E594F"><apiname>CLbsNetworkProtocolBase::RequestSelfLocation()</apiname></xref> described below. </p> <p>When there are no longer any tracking LBS clients, the LBS subsystem notifies a Network Protocol Module by calling <codeph>AdviceSystemStatus()</codeph> with a parameter value <xref href="GUID-479C43CF-8787-3596-93ED-F03A8E5CA2F5.dita#GUID-479C43CF-8787-3596-93ED-F03A8E5CA2F5/GUID-B71C5F74-2673-3AFE-813C-41A91E661FD8"><apiname>CLbsNetworkProtocolBase::ESystemStatusNone</apiname></xref>. </p> <p> <b>Requesting and cancelling MO-LR (self locate)</b> </p> <ul><li id="GUID-712CCD16-B4B3-55A7-8B25-8B39DBD1867E"><p> <xref href="GUID-479C43CF-8787-3596-93ED-F03A8E5CA2F5.dita#GUID-479C43CF-8787-3596-93ED-F03A8E5CA2F5/GUID-0E4234D2-D8B0-302F-8DE5-EA47ED5E594F"><apiname>CLbsNetworkProtocolBase::RequestSelfLocation()</apiname></xref> </p> <p>This method is called to initiate an MO-LR (self locate) when GPS is to be used to obtain a location. In cases where the precision of a GPS fix is not required (for example because of less demanding location quality criteria), the method <xref href="GUID-479C43CF-8787-3596-93ED-F03A8E5CA2F5.dita#GUID-479C43CF-8787-3596-93ED-F03A8E5CA2F5/GUID-E52AC2F2-6E42-370B-93EB-48389E062E33"><apiname>CLbsNetworkProtocolBase::RequestNetworkLocation()</apiname></xref> may be called instead for MO-LR (see below). </p> </li> <li id="GUID-ED729CC1-01D9-5420-9A5E-F448D7960F89"><p> <xref href="GUID-479C43CF-8787-3596-93ED-F03A8E5CA2F5.dita#GUID-479C43CF-8787-3596-93ED-F03A8E5CA2F5/GUID-D2C7B03B-8EB8-3CEB-B35E-2EC0B1DB4A04"><apiname>CLbsNetworkProtocolBase::CancelSelfLocation()</apiname></xref> </p> <p>This method is called to cancel an outstanding MO-LR which was made by calling <xref href="GUID-479C43CF-8787-3596-93ED-F03A8E5CA2F5.dita#GUID-479C43CF-8787-3596-93ED-F03A8E5CA2F5/GUID-0E4234D2-D8B0-302F-8DE5-EA47ED5E594F"><apiname>CLbsNetworkProtocolBase::RequestSelfLocation()</apiname></xref>. </p> </li> </ul> <p> <b>Requesting and cancelling MO-LR (self locate) from the network</b> </p> <ul><li id="GUID-1CF3D7CE-C425-573A-8659-EB7DB6D17050"><p> <xref href="GUID-479C43CF-8787-3596-93ED-F03A8E5CA2F5.dita#GUID-479C43CF-8787-3596-93ED-F03A8E5CA2F5/GUID-E52AC2F2-6E42-370B-93EB-48389E062E33"><apiname>CLbsNetworkProtocolBase::RequestNetworkLocation()</apiname></xref> </p> <p>This method is called to initiate an MO-LR when the precision of GPS is not required. In cases where the precision of a GPS fix is required, the method <xref href="GUID-479C43CF-8787-3596-93ED-F03A8E5CA2F5.dita#GUID-479C43CF-8787-3596-93ED-F03A8E5CA2F5/GUID-0E4234D2-D8B0-302F-8DE5-EA47ED5E594F"><apiname>CLbsNetworkProtocolBase::RequestSelfLocation()</apiname></xref> is called instead. </p> </li> <li id="GUID-0185B725-39EA-5CEC-AA64-00A877791A03"><p> <xref href="GUID-479C43CF-8787-3596-93ED-F03A8E5CA2F5.dita#GUID-479C43CF-8787-3596-93ED-F03A8E5CA2F5/GUID-6AA30D7B-3281-39BE-B314-8666809D80A9"><apiname>CLbsNetworkProtocolBase::CancelNetworkLocation()</apiname></xref> </p> <p>This method is called to cancel an outstanding MO-LR which was made by calling <xref href="GUID-479C43CF-8787-3596-93ED-F03A8E5CA2F5.dita#GUID-479C43CF-8787-3596-93ED-F03A8E5CA2F5/GUID-E52AC2F2-6E42-370B-93EB-48389E062E33"><apiname>CLbsNetworkProtocolBase::RequestNetworkLocation()</apiname></xref>. </p> </li> </ul> <p> <b>Requesting and cancelling of MO-LR (transmit to third party)</b> </p> <ul><li id="GUID-F414CB99-1A53-511B-9A59-1E10E4C57D54"><p> <xref href="GUID-479C43CF-8787-3596-93ED-F03A8E5CA2F5.dita#GUID-479C43CF-8787-3596-93ED-F03A8E5CA2F5/GUID-EF593B81-667B-36CB-9457-0B683B76468F"><apiname>CLbsNetworkProtocolBase::RequestTransmitLocation()</apiname></xref> </p> <p>This method is called to send location to a third party. </p> </li> <li id="GUID-906C761E-E497-5AA8-AA93-202FD446BF09"><p> <xref href="GUID-479C43CF-8787-3596-93ED-F03A8E5CA2F5.dita#GUID-479C43CF-8787-3596-93ED-F03A8E5CA2F5/GUID-70188A68-C4CD-3079-B64F-AF3D10CB990D"><apiname>CLbsNetworkProtocolBase::CancelTransmitLocation()</apiname></xref> </p> <p>This method is called to cancel an outstanding request to send location to a third party. </p> </li> </ul> <p> <b>Responding to MT-LR privacy requests</b> </p> <ul><li id="GUID-B30ED2D0-5353-51F8-A311-B5D00C250AF4"><p> <xref href="GUID-479C43CF-8787-3596-93ED-F03A8E5CA2F5.dita#GUID-479C43CF-8787-3596-93ED-F03A8E5CA2F5/GUID-452D97D6-D54C-359C-B193-E152C3690351"><apiname>CLbsNetworkProtocolBase::RespondPrivacyRequest()</apiname></xref> </p> <p>This method is called in response to an MT-LR privacy request in order to accept or reject the request. </p> <p>See <xref href="GUID-CDE5CC9D-F6DE-5A21-97C3-59A2F3398A15.dita">Privacy requests</xref> for more information about how privacy requests are handled by the LBS subsystem. </p> </li> </ul> <p> <b>Processing location requests</b> </p> <p>As shown in figures 3, 4 and 5, MO-LR self locate, MO-LR transfer to third party and MT-LR cause the Network Protocol Module to call <xref href="GUID-A97ABAA7-46B0-3E26-97C6-123C92CCEEE4.dita#GUID-A97ABAA7-46B0-3E26-97C6-123C92CCEEE4/GUID-676C6200-0A3A-331D-9776-17CA53E8A1D7"><apiname>MLbsNetworkProtocolObserver::ProcessLocationRequest()</apiname></xref> on the LBS Network Gateway process. </p> <p>An instance of <xref href="GUID-346C477F-005A-311D-A920-8C0F40E391CE.dita"><apiname>TLbsNetPosRequestMethod</apiname></xref> is passed when the Protocol Module calls <codeph>MLbsNetworkProtocolObserver::ProcessLocationRequest()</codeph>. It defines the type(s) of positioning method the LBS subsystem should use to calculate the device location. </p> <p>A Network Protocol Module can specify up to two positioning methods, if required: <xref href="GUID-346C477F-005A-311D-A920-8C0F40E391CE.dita"><apiname>TLbsNetPosRequestMethod</apiname></xref> contains an array of elements of type <xref href="GUID-1278D006-4DF8-3908-A0A5-9F9FD2CC4C35.dita"><apiname>TLbsNetPosMethod</apiname></xref>. Each <codeph>TLbsNetPosMethod</codeph> element specifies a technology type and the positioning mode that should be used by the LBS subsystem to calculate location. </p> <p>If the array contains two elements, the first element contains the preferred technology type and positioning mode. The second element contains an alternative positioning mode. </p> <p>If the array contains only one element then this specifies the technology type and positioning mode that must be used by the LBS subsystem. </p> <p>Examples of how a Network Protocol Module specifies the positioning mode follows: </p> <ul><li id="GUID-D6A828D2-C209-58DF-8272-49996E4DF68C"><p> <b>Terminal based positioning mode only</b> </p> <p>The Protocol Module creates a single <codeph>TLbsNetPosMethod</codeph> element and calls <xref href="GUID-1278D006-4DF8-3908-A0A5-9F9FD2CC4C35.dita#GUID-1278D006-4DF8-3908-A0A5-9F9FD2CC4C35/GUID-E1A14CDB-267B-3B4D-8C21-6BD85F23AFCB"><apiname>TLbsNetPosMethod::SetPosMethod()</apiname></xref> passing the parameters: </p> <p> <codeph>aPosMeans = KLbsPositioningMeansGps</codeph> </p> <p> <codeph>aPosMode = TPositionModuleInfo::ETechnologyTerminal |
+ </title> <image href="GUID-C103A584-3498-5F0A-8F0B-F97D33749CEF_d0e452142_href.png" placement="inline"/></fig> <p><b>CLbsNetworkProtocolBase </b> </p> <p>The following briefly describes the <xref href="GUID-479C43CF-8787-3596-93ED-F03A8E5CA2F5.dita"><apiname>CLbsNetworkProtocolBase</apiname></xref> methods grouped according to their function. The LBS Network Gateway process calls these methods on the licensee Network Protocol Module. More detailed information about the purpose of these methods and their parameter lists can be found by following the links to the Symbian platform reference documentation. </p> <p> <b>Setting tracking mode (if necessary)</b> </p> <p>For MO-LR self locate, an application client can ask the LBS subsystem for periodic location updates. This is known as tracking and is described in the Location Acquisition API document <xref href="GUID-F6B5F777-D12F-5913-AECE-047DF8C72F1F.dita">How to get location information</xref>. </p> <p>When a client requests tracking, the LBS subsystem notifies a Network Protocol Module of this requirement by calling <xref href="GUID-479C43CF-8787-3596-93ED-F03A8E5CA2F5.dita#GUID-479C43CF-8787-3596-93ED-F03A8E5CA2F5/GUID-367DC79E-CB61-3EFB-9928-104F5B6A0021"><apiname>CLbsNetworkProtocolBase::AdviceSystemStatus()</apiname></xref> with a parameter value <xref href="GUID-479C43CF-8787-3596-93ED-F03A8E5CA2F5.dita#GUID-479C43CF-8787-3596-93ED-F03A8E5CA2F5/GUID-1546BC54-76FC-3C4C-BA99-CB13027687EE"><apiname>CLbsNetworkProtocolBase::ESystemStatusClientTracking</apiname></xref>. This method is called before the first location request <xref href="GUID-479C43CF-8787-3596-93ED-F03A8E5CA2F5.dita#GUID-479C43CF-8787-3596-93ED-F03A8E5CA2F5/GUID-0E4234D2-D8B0-302F-8DE5-EA47ED5E594F"><apiname>CLbsNetworkProtocolBase::RequestSelfLocation()</apiname></xref> described below. </p> <p>When there are no longer any tracking LBS clients, the LBS subsystem notifies a Network Protocol Module by calling <codeph>AdviceSystemStatus()</codeph> with a parameter value <xref href="GUID-479C43CF-8787-3596-93ED-F03A8E5CA2F5.dita#GUID-479C43CF-8787-3596-93ED-F03A8E5CA2F5/GUID-B71C5F74-2673-3AFE-813C-41A91E661FD8"><apiname>CLbsNetworkProtocolBase::ESystemStatusNone</apiname></xref>. </p> <p> <b>Requesting and cancelling MO-LR (self locate)</b> </p> <ul><li id="GUID-712CCD16-B4B3-55A7-8B25-8B39DBD1867E"><p> <xref href="GUID-479C43CF-8787-3596-93ED-F03A8E5CA2F5.dita#GUID-479C43CF-8787-3596-93ED-F03A8E5CA2F5/GUID-0E4234D2-D8B0-302F-8DE5-EA47ED5E594F"><apiname>CLbsNetworkProtocolBase::RequestSelfLocation()</apiname></xref> </p> <p>This method is called to initiate an MO-LR (self locate) when GPS is to be used to obtain a location. In cases where the precision of a GPS fix is not required (for example because of less demanding location quality criteria), the method <xref href="GUID-479C43CF-8787-3596-93ED-F03A8E5CA2F5.dita#GUID-479C43CF-8787-3596-93ED-F03A8E5CA2F5/GUID-E52AC2F2-6E42-370B-93EB-48389E062E33"><apiname>CLbsNetworkProtocolBase::RequestNetworkLocation()</apiname></xref> may be called instead for MO-LR (see below). </p> </li> <li id="GUID-ED729CC1-01D9-5420-9A5E-F448D7960F89"><p> <xref href="GUID-479C43CF-8787-3596-93ED-F03A8E5CA2F5.dita#GUID-479C43CF-8787-3596-93ED-F03A8E5CA2F5/GUID-D2C7B03B-8EB8-3CEB-B35E-2EC0B1DB4A04"><apiname>CLbsNetworkProtocolBase::CancelSelfLocation()</apiname></xref> </p> <p>This method is called to cancel an outstanding MO-LR which was made by calling <xref href="GUID-479C43CF-8787-3596-93ED-F03A8E5CA2F5.dita#GUID-479C43CF-8787-3596-93ED-F03A8E5CA2F5/GUID-0E4234D2-D8B0-302F-8DE5-EA47ED5E594F"><apiname>CLbsNetworkProtocolBase::RequestSelfLocation()</apiname></xref>. </p> </li> </ul> <p> <b>Requesting and cancelling MO-LR (self locate) from the network</b> </p> <ul><li id="GUID-1CF3D7CE-C425-573A-8659-EB7DB6D17050"><p> <xref href="GUID-479C43CF-8787-3596-93ED-F03A8E5CA2F5.dita#GUID-479C43CF-8787-3596-93ED-F03A8E5CA2F5/GUID-E52AC2F2-6E42-370B-93EB-48389E062E33"><apiname>CLbsNetworkProtocolBase::RequestNetworkLocation()</apiname></xref> </p> <p>This method is called to initiate an MO-LR when the precision of GPS is not required. In cases where the precision of a GPS fix is required, the method <xref href="GUID-479C43CF-8787-3596-93ED-F03A8E5CA2F5.dita#GUID-479C43CF-8787-3596-93ED-F03A8E5CA2F5/GUID-0E4234D2-D8B0-302F-8DE5-EA47ED5E594F"><apiname>CLbsNetworkProtocolBase::RequestSelfLocation()</apiname></xref> is called instead. </p> </li> <li id="GUID-0185B725-39EA-5CEC-AA64-00A877791A03"><p> <xref href="GUID-479C43CF-8787-3596-93ED-F03A8E5CA2F5.dita#GUID-479C43CF-8787-3596-93ED-F03A8E5CA2F5/GUID-6AA30D7B-3281-39BE-B314-8666809D80A9"><apiname>CLbsNetworkProtocolBase::CancelNetworkLocation()</apiname></xref> </p> <p>This method is called to cancel an outstanding MO-LR which was made by calling <xref href="GUID-479C43CF-8787-3596-93ED-F03A8E5CA2F5.dita#GUID-479C43CF-8787-3596-93ED-F03A8E5CA2F5/GUID-E52AC2F2-6E42-370B-93EB-48389E062E33"><apiname>CLbsNetworkProtocolBase::RequestNetworkLocation()</apiname></xref>. </p> </li> </ul> <p> <b>Requesting and cancelling of MO-LR (transmit to third party)</b> </p> <ul><li id="GUID-F414CB99-1A53-511B-9A59-1E10E4C57D54"><p> <xref href="GUID-479C43CF-8787-3596-93ED-F03A8E5CA2F5.dita#GUID-479C43CF-8787-3596-93ED-F03A8E5CA2F5/GUID-EF593B81-667B-36CB-9457-0B683B76468F"><apiname>CLbsNetworkProtocolBase::RequestTransmitLocation()</apiname></xref> </p> <p>This method is called to send location to a third party. </p> </li> <li id="GUID-906C761E-E497-5AA8-AA93-202FD446BF09"><p> <xref href="GUID-479C43CF-8787-3596-93ED-F03A8E5CA2F5.dita#GUID-479C43CF-8787-3596-93ED-F03A8E5CA2F5/GUID-70188A68-C4CD-3079-B64F-AF3D10CB990D"><apiname>CLbsNetworkProtocolBase::CancelTransmitLocation()</apiname></xref> </p> <p>This method is called to cancel an outstanding request to send location to a third party. </p> </li> </ul> <p> <b>Responding to MT-LR privacy requests</b> </p> <ul><li id="GUID-B30ED2D0-5353-51F8-A311-B5D00C250AF4"><p> <xref href="GUID-479C43CF-8787-3596-93ED-F03A8E5CA2F5.dita#GUID-479C43CF-8787-3596-93ED-F03A8E5CA2F5/GUID-452D97D6-D54C-359C-B193-E152C3690351"><apiname>CLbsNetworkProtocolBase::RespondPrivacyRequest()</apiname></xref> </p> <p>This method is called in response to an MT-LR privacy request in order to accept or reject the request. </p> <p>See <xref href="GUID-CDE5CC9D-F6DE-5A21-97C3-59A2F3398A15.dita">Privacy requests</xref> for more information about how privacy requests are handled by the LBS subsystem. </p> </li> </ul> <p> <b>Processing location requests</b> </p> <p>As shown in figures 3, 4 and 5, MO-LR self locate, MO-LR transfer to third party and MT-LR cause the Network Protocol Module to call <xref href="GUID-A97ABAA7-46B0-3E26-97C6-123C92CCEEE4.dita#GUID-A97ABAA7-46B0-3E26-97C6-123C92CCEEE4/GUID-676C6200-0A3A-331D-9776-17CA53E8A1D7"><apiname>MLbsNetworkProtocolObserver::ProcessLocationRequest()</apiname></xref> on the LBS Network Gateway process. </p> <p>An instance of <xref href="GUID-346C477F-005A-311D-A920-8C0F40E391CE.dita"><apiname>TLbsNetPosRequestMethod</apiname></xref> is passed when the Protocol Module calls <codeph>MLbsNetworkProtocolObserver::ProcessLocationRequest()</codeph>. It defines the type(s) of positioning method the LBS subsystem should use to calculate the device location. </p> <p>A Network Protocol Module can specify up to two positioning methods, if required: <xref href="GUID-346C477F-005A-311D-A920-8C0F40E391CE.dita"><apiname>TLbsNetPosRequestMethod</apiname></xref> contains an array of elements of type <xref href="GUID-1278D006-4DF8-3908-A0A5-9F9FD2CC4C35.dita"><apiname>TLbsNetPosMethod</apiname></xref>. Each <codeph>TLbsNetPosMethod</codeph> element specifies a technology type and the positioning mode that should be used by the LBS subsystem to calculate location. </p> <p>If the array contains two elements, the first element contains the preferred technology type and positioning mode. The second element contains an alternative positioning mode. </p> <p>If the array contains only one element then this specifies the technology type and positioning mode that must be used by the LBS subsystem. </p> <p>Examples of how a Network Protocol Module specifies the positioning mode follows: </p> <ul><li id="GUID-D6A828D2-C209-58DF-8272-49996E4DF68C"><p> <b>Terminal based positioning mode only</b> </p> <p>The Protocol Module creates a single <codeph>TLbsNetPosMethod</codeph> element and calls <xref href="GUID-1278D006-4DF8-3908-A0A5-9F9FD2CC4C35.dita#GUID-1278D006-4DF8-3908-A0A5-9F9FD2CC4C35/GUID-E1A14CDB-267B-3B4D-8C21-6BD85F23AFCB"><apiname>TLbsNetPosMethod::SetPosMethod()</apiname></xref> passing the parameters: </p> <p> <codeph>aPosMeans = KLbsPositioningMeansGps</codeph> </p> <p> <codeph>aPosMode = TPositionModuleInfo::ETechnologyTerminal |
TPositionModuleInfo::ETechnologyAssisted</codeph> </p> <p>In this case, the LBS subsystem attempts to calculate a GPS location fix using assistance data from the network. </p> </li> <li id="GUID-B25E613C-18D3-5026-8F9A-5EB3CFC0490A"><p> <b>Terminal assisted positioning mode only</b> </p> <p>The Protocol Module creates a single <codeph>TLbsNetPosMethod</codeph> element and calls <xref href="GUID-1278D006-4DF8-3908-A0A5-9F9FD2CC4C35.dita#GUID-1278D006-4DF8-3908-A0A5-9F9FD2CC4C35/GUID-E1A14CDB-267B-3B4D-8C21-6BD85F23AFCB"><apiname>TLbsNetPosMethod::SetPosMethod()</apiname></xref> passing the parameters: </p> <p> <codeph>aPosMeans = KLbsPositioningMeansGps</codeph> </p> <p> <codeph>aPosMode = TPositionModuleInfo::ETechnologyNetwork |
TPositionModuleInfo::ETechnologyAssisted</codeph> </p> <p>In this case, the LBS subsystem attempts to calculate a GPS location fix using assistance data from the network. </p> </li> <li id="GUID-BC446ED6-9800-5B21-A702-A4C5A011C6BE"><p> <b>Terminal based positioning mode (1st choice) & terminal assisted positioning mode (2nd choice)</b> </p> <p>The Protocol Module creates two <codeph>TLbsNetPosMethod</codeph> elements and calls <xref href="GUID-1278D006-4DF8-3908-A0A5-9F9FD2CC4C35.dita#GUID-1278D006-4DF8-3908-A0A5-9F9FD2CC4C35/GUID-E1A14CDB-267B-3B4D-8C21-6BD85F23AFCB"><apiname>TLbsNetPosMethod::SetPosMethod()</apiname></xref> for each: </p> <ul><li id="GUID-FECD0D61-9C99-5C94-A6B9-113DD85571E7"><p>1st Element: </p> <p> <codeph>aPosMeans = KLbsPositioningMeansGps</codeph> </p> <p> <codeph>aPosMode = TPositionModuleInfo::ETechnologyTerminal |
TPositionModuleInfo::ETechnologyAssisted</codeph> </p> </li> </ul> <ul><li id="GUID-8FC84A75-96A9-5C76-B059-B0D70C36531E"><p>2nd Element: </p> <p> <codeph>aPosMeans = KLbsPositioningMeansGps</codeph> </p> <p> <codeph>aPosMode = TPositionModuleInfo::ETechnologyNetwork |