<?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-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 

             Figure 2. Main classes of the Network Protocol API 

             Figure 3. Simple MO-LR self locate sequence (for terminal based

             positioning) 

             Figure 4. Simple MO-LR transfer to third party sequence (for terminal

             based positioning) 

             Figure 5. Simple MT-LR sequence (for terminal based positioning) 

                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) &amp; 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 |

                     TPositionModuleInfo::ETechnologyAssisted</codeph>  </p> </li> </ul> <p>In this case, the LBS subsystem attempts to calculate a GPS location fix using assistance data from the network. While LBS is calculating a GPS fix it also returns GPS measurements to the Network Protocol Module. </p> </li> <li id="GUID-89A1F4A4-0FA6-518C-AB8B-FC72A0E67C6F"><p> <b>Position from the network (cell based positioning)</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 = KLbsPositioningMeansCell</codeph>  </p> <p> <codeph>aPosMode = TPositionModuleInfo::ETechnologyNetwork</codeph>  </p> <p>In this case, the LBS subsystem uses the reference location from the network as the location fix. </p> </li> </ul> <p>Calling <codeph>MLbsNetworkProtocolObserver::ProcessLocationRequest()</codeph> causes the LBS subsystem to begin to calculate a location (or begin to obtain GPS measurements necessary to calculate a location). When location data is available, the LBS Network Gateway process calls <xref href="GUID-479C43CF-8787-3596-93ED-F03A8E5CA2F5.dita#GUID-479C43CF-8787-3596-93ED-F03A8E5CA2F5/GUID-D7F6BA26-00D4-3DF4-8E6D-D4E990FA1F04"><apiname>CLbsNetworkProtocolBase::RespondLocationRequest()</apiname></xref>. </p> <p> <b>Requesting A-GPS assistance data</b>  </p> <ul><li id="GUID-5F0513D3-7F52-59E9-8EE7-40B81CE13E22"><p> <xref href="GUID-479C43CF-8787-3596-93ED-F03A8E5CA2F5.dita#GUID-479C43CF-8787-3596-93ED-F03A8E5CA2F5/GUID-9530C97E-DBA4-3253-8C26-8E5300FD812F"><apiname>CLbsNetworkProtocolBase::RequestAssistanceData()</apiname></xref> </p> <p>This method is called to get additional A-GPS assistance data as part of an MO-LR (self locate), MO-LR (transfer to third party) or an MT-LR. Assistance data identifies the satellites that should be visible from the current mobile device location and this reduces the time required to obtain GPS measurements. </p> </li> </ul> <p><b>MLbsNetworkProtocolObserver </b> </p> <p>The following briefly describes the <xref href="GUID-A97ABAA7-46B0-3E26-97C6-123C92CCEEE4.dita"><apiname>MLbsNetworkProtocolObserver</apiname></xref> methods grouped according to their function. A licensee Network Protocol Module calls these methods on the LBS Network Gateway process. 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>Getting the current capabilities of the LBS subsystem</b>  </p> <ul><li id="GUID-23A363FA-507C-52DB-969D-653C0B0A0123"><p> <xref href="GUID-A97ABAA7-46B0-3E26-97C6-123C92CCEEE4.dita#GUID-A97ABAA7-46B0-3E26-97C6-123C92CCEEE4/GUID-8187EB64-5AAA-34A3-B0E0-297A30A2E584"><apiname>MLbsNetworkProtocolObserver::GetCurrentCapabilities()</apiname></xref> </p> <p>This method is called by the Network Protocol Module to get the capabilities of the LBS subsystem, such as whether it can calculate a GPS location fix and the supported GPS modes. The method takes a single parameter of class <xref href="GUID-90640AC2-12C6-3BBB-B620-71AA99F44BFA.dita"><apiname>TLbsNetPosCapabilities</apiname></xref> (defined in <filepath>lbsnetcommon.h</filepath>) that encapsulates methods to discover the protocols and positioning methods supported by the LBS subsystem. </p> <p>Note that the capabilities of the LBS subsystem can change at runtime (because of modification via the LBS Administration API) and therefore a licensee Network Protocol Module should call this method whenever it needs to check the current capabilities of the LBS subsystem. </p> </li> </ul> <p> <b>Updating the LBS Network Gateway with the Network Protocol Module status </b>  </p> <ul><li id="GUID-51402E5F-EA73-5E02-8672-69A993027C50"><p> <xref href="GUID-A97ABAA7-46B0-3E26-97C6-123C92CCEEE4.dita#GUID-A97ABAA7-46B0-3E26-97C6-123C92CCEEE4/GUID-318EE503-8EDF-3562-BD2A-24637B7CB505"><apiname>MLbsNetworkProtocolObserver::ProcessStatusUpdate()</apiname></xref> <b/> </p> <p>This method is called to update the LBS subsystem with the current status of the Network Protocol Module. </p> <p>The method takes a single parameter of type <xref href="GUID-A97ABAA7-46B0-3E26-97C6-123C92CCEEE4.dita#GUID-A97ABAA7-46B0-3E26-97C6-123C92CCEEE4/GUID-81AC4613-8227-3310-B535-A19FB29C7AAA"><apiname>MLbsNetworkProtocolObserver::TLbsNetProtocolServiceMask</apiname></xref>, a bitmask variable that indicates the types of requests currently being handled by the Network Protocol Module. This bitmask variable holds a bitwise OR of values of type <xref href="GUID-A97ABAA7-46B0-3E26-97C6-123C92CCEEE4.dita#GUID-A97ABAA7-46B0-3E26-97C6-123C92CCEEE4/GUID-BA8E1132-CE35-3DD5-AF6B-B198646C2FB6"><apiname>MLbsNetworkProtocolObserver::TLbsNetProtocolService</apiname></xref>. </p> <p>A Network Protocol Module calls this method to inform the LBS subsystem whenever its state has changed, for example after the LBS subsystem has requested a new MO-LR or when an MT-LR is received from the network. </p> </li> </ul> <p> <b>Notifying of MT-LR privacy requests</b>  </p> <ul><li id="GUID-87A7B07A-5148-582B-8E06-55D0E5C6F1F6"><p> <xref href="GUID-A97ABAA7-46B0-3E26-97C6-123C92CCEEE4.dita#GUID-A97ABAA7-46B0-3E26-97C6-123C92CCEEE4/GUID-377A3D40-D844-35C4-8E79-39C819F1890E"><apiname>

                MLbsNetworkProtocolObserver::ProcessPrivacyRequest()</apiname></xref>  </p> <p>This method is called to indicate that an MT-LR privacy request has been received. </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>Requesting a location</b>  </p> <p>For MO-LR (self locate) the LBS Network Gateway process calls <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> (for GPS positioning modes) or <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> (for cell-based positioning modes). </p> <p>For MO-LR (transfer to third party) the LBS Network Gateway calls <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>. In response to these, or when an MT-LR location request is received, the Network Protocol Module calls <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. </p> <p>A <xref href="GUID-346C477F-005A-311D-A920-8C0F40E391CE.dita"><apiname>TLbsNetPosRequestMethod</apiname></xref> parameter specifies the method that should be used by the LBS subsystem to obtain the location fix. </p> <p> <b>Handling receipt of A-GPS assistance data</b>  </p> <ul><li id="GUID-82509F65-1BC8-55F9-9DF5-08341B81F5DF"><p> <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> </p> <p>This method is called when A-GPS assistance data is received from the network. The assistance data is delivered to LBS as an <xref href="GUID-E250BCA2-381D-389E-A7F3-7F520B7CD326.dita"><apiname>RLbsAssistanceDataBuilderSet</apiname></xref> object and is cached by the LBS subsystem. A licensee A-GPS Integration Module is notified when assistance data is delivered to LBS and may request it. </p> </li> </ul> <p> <b>Resetting A-GPS assistance data for testing</b>  </p> <p>If requested to do so by the network, a licensee's Network Protocol Module can instruct the LBS subsystem and the licensee's A-GPS Integration Module to reset any cached assistance data. It does this by calling <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>, with a <xref href="GUID-0F4B82BB-37D6-35AD-993B-F766E1CF0637.dita"><apiname>KPositionAssistanceDataReset</apiname></xref> parameter to tell LBS to reset its cached assistance data and a <xref href="GUID-343E1FD7-9D75-3A41-84EC-B35030C06557.dita"><apiname>TLbsAssistanceDataGroup</apiname></xref> bitmask parameter to specify the types of assistance data to be reset. Using <codeph>ProcessAssistanceData()

          </codeph> in this way has two effects: </p> <ul><li id="GUID-450BB72B-6EB3-54F9-A676-66F25C01DF62"><p>LBS deletes the specified assistance data in its own assistance data cache. </p> </li> <li id="GUID-2FC89FC0-2602-573F-A9D8-ABA6EAE39B5F"><p>LBS calls the A-GPS Location DataSource API method <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> with a <xref href="GUID-0F4B82BB-37D6-35AD-993B-F766E1CF0637.dita"><apiname>KPositionAssistanceDataReset</apiname></xref> parameter (to inform a licensee's A-GPS Integration Module that it must reset its assistance data) and a <xref href="GUID-343E1FD7-9D75-3A41-84EC-B35030C06557.dita"><apiname>TLbsAssistanceDataGroup</apiname></xref> bitmask parameter (to specify the types of assistance data that should be reset). </p> </li> </ul> <p> <b>Updating location data</b>  </p> <ul><li id="GUID-6D522100-FB50-5B57-902C-0EE1DCF4CB63"><p> <xref href="GUID-A97ABAA7-46B0-3E26-97C6-123C92CCEEE4.dita#GUID-A97ABAA7-46B0-3E26-97C6-123C92CCEEE4/GUID-CAB9645E-91AD-326B-8803-45F28505CCCC"><apiname>MLbsNetworkProtocolObserver::ProcessLocationUpdate()</apiname></xref> </p> <p>This method is called to update the LBS subsystem either: </p> <ul><li id="GUID-05143F93-D3D7-5F09-9935-66B2C7D25E6E"><p>When a reference position is returned from the network </p> <p> <codeph>ProcessLocationUpdate()</codeph> returns a <xref href="GUID-73D6F438-C270-33B9-974B-D4D1583E1738.dita"><apiname>TPositionInfoBase</apiname></xref> parameter which contains the reference position. Calling <xref href="GUID-73D6F438-C270-33B9-974B-D4D1583E1738.dita#GUID-73D6F438-C270-33B9-974B-D4D1583E1738/GUID-AC9654DD-2FC8-3B27-8743-83D7B8C58B79"><apiname>TPositionInfoBase::PositionMode()</apiname></xref> returns <codeph>TPositionModuleInfo::ETechnologyNetwork</codeph>. </p> </li> <li id="GUID-F61EF0F4-25A8-5E89-9C3F-3494F7625EF9"><p>When the 'final position' is returned from the network (for MO-LR self locate and MO-LR transfer to third party) </p> <p>The final position is the last position returned from the network. For terminal based positioning, the final position is just the position that LBS sent to the network by calling <xref href="GUID-479C43CF-8787-3596-93ED-F03A8E5CA2F5.dita#GUID-479C43CF-8787-3596-93ED-F03A8E5CA2F5/GUID-D7F6BA26-00D4-3DF4-8E6D-D4E990FA1F04"><apiname>CLbsNetworkProtocolBase::RespondLocationRequest()</apiname></xref>. For terminal assisted positioning, the final position is the one calculated by the network using GPS measurements from the device. </p> <p>For a final position calculated using terminal based positioning <xref href="GUID-73D6F438-C270-33B9-974B-D4D1583E1738.dita#GUID-73D6F438-C270-33B9-974B-D4D1583E1738/GUID-AC9654DD-2FC8-3B27-8743-83D7B8C58B79"><apiname>TPositionInfoBase::PositionMode()</apiname></xref> returns <codeph>TPositionModuleInfo::ETechnologyTerminal |

                     TPositionModuleInfo::ETechnologyAssisted</codeph>. </p> <p>For a final position calculated using terminal assisted positioning <xref href="GUID-73D6F438-C270-33B9-974B-D4D1583E1738.dita#GUID-73D6F438-C270-33B9-974B-D4D1583E1738/GUID-AC9654DD-2FC8-3B27-8743-83D7B8C58B79"><apiname>TPositionInfoBase::PositionMode()</apiname></xref> returns <codeph>TPositionModuleInfo::ETechnologyNetwork |

                     TPositionModuleInfo::ETechnologyAssisted</codeph>. </p> </li> </ul> </li> </ul> <p> <b>Completing a session</b>  </p> <ul><li id="GUID-FC05B479-8906-57B3-AAFD-044BF798C231"><p> <xref href="GUID-A97ABAA7-46B0-3E26-97C6-123C92CCEEE4.dita#GUID-A97ABAA7-46B0-3E26-97C6-123C92CCEEE4/GUID-ACBFB09B-D4D1-36A0-A9D6-FD3207E93E30"><apiname>MLbsNetworkProtocolObserver::ProcessSessionComplete()</apiname></xref> </p> <p>This method is called to indicate that a session is complete (for example that a single MO-LR or MT-LR is complete). </p> </li> </ul> </section> <section id="GUID-F4DA8C85-7F74-5FA6-BF05-1DC2636AD764"><title>Network Protocol Module configuration</title> <p>In addition to coding the Network Protocol Module, there are configuration steps that a device creator may need to complete: </p> <p><b>Update the Network Location Manager .ini file</b> </p> <p>The file <filepath>networklocationmanager.ini</filepath> specifies the positioning capabilities of the network to LBS. It is exported to <filepath>&lt;rom_drive&gt;:\private\10282253\lbs\locmods\</filepath> (<codeph>10282253</codeph> is the UID3 of the LBS Root process) as part of the LBS build process. The contents of the file as delivered with the LBS subsystem are shown below: </p> <codeblock id="GUID-8B3E7412-56A7-58C8-AF2F-72309D0ADA10" xml:space="preserve">

# networklocationmanager.ini

[1]

Version= 0.1.1        #

ModuleId= 271064387    # dec

ModuleName= "NetLocManager"    # 

TechnologyType= 0010    # binary

DeviceLocation= 0010    # binary

Capabilities= 1111    # binary

ClassesSupported= 111111    # binary

TimeToFirstFix= 20000    # ms

TimeToNextFix= 20000    # ms

HorizontalAccuracy= 100 # real

VerticalAccuracy= 100 # real

CostIndicator= 3    # dec

PowerConsumption = 2 # dec

ExecutableName= "lbsnetlocmanager.exe"

</codeblock> <p> <b>Device creators only need to change the contents of the file if the parameters of their Network Protocol Module and the network capabilities are significantly different to the values shown above. </b>  </p> <p>The table below describes each of the values in <filepath>networklocationmanager.ini</filepath>. </p> <table id="GUID-5E925482-2D67-59D3-9F02-0E8ED0E851AB"><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 Network Protocol Module version. </p> </entry> </row> <row><entry><p>ModuleId </p> </entry> <entry><p>A UID (decimal) </p> </entry> <entry><p>The UID3 of the Network Location Manager process. </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. In this file the value specifies network only. </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 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>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> </tbody> </tgroup> </table> <p><b> Create a Network Protocol Module .rss file</b> </p> <p>A Network Protocol Module requires an ECOM resource file. The example below is the resource file for the Symbian reference SUPL Protocol Module. </p> <codeblock id="GUID-07D94413-6611-5F3A-BD4A-3E1B4A06F904" xml:space="preserve">

#include "ecom/registryinfov2.rh"

RESOURCE REGISTRY_INFO theInfo

    {

    resource_format_version = RESOURCE_FORMAT_VERSION_2;

    dll_uid = 0x10285A9C;

    interfaces = 

        {

        INTERFACE_INFO

            {

            // UID of interface that is implemented

            interface_uid = 0x10281D4A;

            implementations = 

                {

                IMPLEMENTATION_INFO

                    {

                    // UID of this interface implementation

                    implementation_uid = 0x10285A9D;

                    version_no = 1;

                    display_name = "SUPL V1 Protocol Module";

                    default_data = "";

                    opaque_data = "";

                    rom_only = 0;

                    }

                };

            }

        };

    }

             </codeblock> <p><b>Update the LBS administration settings</b> </p> <p>The implementation UIDs of the Network Protocol Module implementations must be defined in the <xref href="GUID-852E58C1-EA5C-5B46-9020-4463D3FA06AD.dita">LBS administration repository initialisation file</xref>. The example below shows an initialisation file entry that configures LBS to load the Symbian reference SUPL Protocol Module when the handset is in the home network and also when roaming. </p> <p>Note that if the UID of the Network Protocol Module is changed at runtime by using the LBS Administration API, it is necessary to reboot the handset in order to restart the LBS subsystem and load the different module. </p> <codeblock id="GUID-24D660DD-6FE2-53CD-B88D-FC75AD86D3FD" xml:space="preserve">

#KSettingHomeProtocolModule. Use reference SUPL Protocol Module

0x0000000E  int  0x10285A9D

#KSettingRoamingProtocolModule.

0x0000000F  int  0x10285A9D

</codeblock> </section> <section id="GUID-CF0C5893-5871-51FA-8AA5-9889010ED031"><title>Loading the Network Protocol Module</title> <p>A licensee Network Protocol Module is an ECOM plug-in DLL and is loaded by the LBS Network Gateway process. </p> <ol id="GUID-2C8EF4F1-5227-5520-8811-746119385B54"><li id="GUID-4C441D35-8BD7-592B-B828-16DCB8B2B2C5"><p>On startup, the LBS Network Gateway process reads <codeph>KSettingHomeProtocolModule</codeph> and <codeph>KSettingRoamingProtocolModule</codeph> from the central repository using the <xref href="GUID-23BBC1D8-B3A0-5148-A4F1-22ECF3043E4E.dita">LBS Administration API</xref>. </p> <p>LBS uses the ETel API to obtain the mobile device's registration status with the network and LBS uses this status to decide which Network Protocol Module to load. A Symbian licensee must implement the ETel API methods <xref href="GUID-AA81AFA4-6FAC-3B0D-A082-BE0AEC58CCA8.dita#GUID-AA81AFA4-6FAC-3B0D-A082-BE0AEC58CCA8/GUID-0251C53A-852B-3737-9131-E82C489A5EA9"><apiname>RMobilePhone::GetNetworkRegistrationStatus()</apiname></xref> and <xref href="GUID-AA81AFA4-6FAC-3B0D-A082-BE0AEC58CCA8.dita#GUID-AA81AFA4-6FAC-3B0D-A082-BE0AEC58CCA8/GUID-0B567090-EA9A-3023-8229-EEE43C024D54"><apiname>RMobilePhone::NotifyNetworkRegistrationStatusChange()</apiname></xref> to report the current registration status of the device. </p> <p>Only one Network Protocol Module is loaded by LBS when the mobile device starts. If the network registration status is reported as <xref href="GUID-AA81AFA4-6FAC-3B0D-A082-BE0AEC58CCA8.dita#GUID-AA81AFA4-6FAC-3B0D-A082-BE0AEC58CCA8/GUID-3ECBA96E-CE2C-39AA-ACE4-DEA68BC69607"><apiname>RMobilePhone::ERegisteredOnHomeNetwork</apiname></xref>, LBS loads the Protocol Module plug-in specified by <codeph>KSettingHomeProtocolModule</codeph>. If the network registration status is reported as <xref href="GUID-AA81AFA4-6FAC-3B0D-A082-BE0AEC58CCA8.dita#GUID-AA81AFA4-6FAC-3B0D-A082-BE0AEC58CCA8/GUID-57C20A21-974C-3D12-9351-7728C159A526"><apiname>RMobilePhone::ERegisteredRoaming</apiname></xref>, LBS loads the Protocol Module plug-in specified by <codeph>KSettingRoamingProtocolModule</codeph>. </p> <p> <b>Note that if the network registration status is not reported as ERegisteredOnHomeNetwork or ERegisteredRoaming, LBS does not load a Network Protocol Module and the LBS subsystem will not function.</b>  </p> <p>LBS does not unload a Network Protocol Module once it is loaded. The module remains loaded by the LBS subsystem until the device is restarted. This means that if a different Network Protocol Module is specified for the home network and for roaming, it is necessary to restart the mobile device when changing networks in order to load the correct module. </p> </li> <li id="GUID-F8307B8E-014D-5033-8EB0-740E00E8074C"><p>The LBS Network Gateway process creates a <xref href="GUID-691CF528-01DC-36BE-B6D3-9D3A8C9F05EB.dita"><apiname>TLbsNetProtocolModuleParams</apiname></xref> object, passing a reference to itself in the <codeph>TLbsNetProtocolModuleParams</codeph> constructor (the Network Gateway process is an <xref href="GUID-A97ABAA7-46B0-3E26-97C6-123C92CCEEE4.dita"><apiname>MLbsNetworkProtocolObserver</apiname></xref>). </p> </li> <li id="GUID-1B787BCD-16CA-549A-BF3B-8B47EF5D2093"><p>The LBS Network Gateway process calls <xref href="GUID-479C43CF-8787-3596-93ED-F03A8E5CA2F5.dita#GUID-479C43CF-8787-3596-93ED-F03A8E5CA2F5/GUID-98669CB7-73FC-3C45-985B-C02C7A883948"><apiname>CLbsNetworkProtocolBase::NewL()</apiname></xref>, passing the licensee Network Protocol Module implementation class UID and the <codeph>TLbsNetProtocolModuleParams</codeph> object as parameters. The ECOM framework loads the licensee Network Protocol Module and supplies it with a reference to the LBS Network Gateway process. </p> </li> <li id="GUID-80F24790-77B7-51AA-8864-1455DC912CB5"><p> <i>The following describes the behaviour of a Network Protocol Module that uses the control plane (ETel) and does not describe the behaviour of the Symbian reference SUPL Protocol Module on startup.</i>  </p> <p>When a licensee control plane Network Protocol Module is loaded, there are several methods that it typically needs to call immediately in order to register to receive MT-LR and A-GPS assistance data from the network: </p> <ul><li id="GUID-A69D092D-8210-598F-8E51-FD56DAA77248"><p>The Network Protocol Module instructs the ETel server to pre-allocate memory to handle an Emergency MT-LR by calling <xref href="GUID-7EBCDEF3-FA85-313C-8FA5-526808D40988.dita#GUID-7EBCDEF3-FA85-313C-8FA5-526808D40988/GUID-EFF36B0F-EF6A-3F4E-A582-9FF412E41F50"><apiname>RPhone::SetEmergencyClient()</apiname></xref>, passing a parameter value <xref href="GUID-7EBCDEF3-FA85-313C-8FA5-526808D40988.dita#GUID-7EBCDEF3-FA85-313C-8FA5-526808D40988/GUID-27F15C18-D372-306C-861B-E7C9012630D9"><apiname>RPhone::EEmergencyLCSRequest</apiname></xref>. </p> </li> <li id="GUID-FFBFE93E-65D6-5D64-AB4D-74B1AC844F9C"><p> <xref href="GUID-79C0E667-C026-3652-A043-20818C2A99BE.dita#GUID-79C0E667-C026-3652-A043-20818C2A99BE/GUID-3FE6131C-DFCA-3EF3-A6D8-E9A17C431193"><apiname>RMobileLocationServices::NotifyMeasurementControl()</apiname></xref> registers the module to receive A-GPS assistance data updates from the network. Note that each time this method notifies the caller that assistance data is received, this method must be called again to request further notifications. </p> </li> <li id="GUID-00C400B2-9108-5825-922A-AA850AB563BF"><p> <xref href="GUID-79C0E667-C026-3652-A043-20818C2A99BE.dita#GUID-79C0E667-C026-3652-A043-20818C2A99BE/GUID-973EECAD-4D09-3C07-B3F5-5AB21DBCE14B"><apiname>RMobileLocationServices::NotifyMtlr()</apiname></xref> registers the protocol module to receive MT-LRs from the network. Note that each time this method notifies the caller that an MT-LR is received, this method must be called again to request further notifications. </p> </li> </ul> </li> </ol> </section> </conbody></concept>