--- /dev/null Thu Jan 01 00:00:00 1970 +0000
+++ b/Symbian3/PDK/Source/GUID-91F95D0C-E4CF-510E-B280-E27F89274ACE.dita Fri Jan 22 18:26:19 2010 +0000
@@ -0,0 +1,199 @@
+<?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-91F95D0C-E4CF-510E-B280-E27F89274ACE"><title>SUPL Protocol Module Quick Start </title><shortdesc>This document describes how a device creator starts working with the SUPL Protocol Module. </shortdesc><prolog><metadata><keywords/></metadata></prolog><conbody><p>Note: The SUPL Protocol Module is deprecated. </p> <section><title>Contents</title> <ul><li id="GUID-9C7133FF-1314-565B-B7E4-24336106DFD0"><p><xref href="GUID-91F95D0C-E4CF-510E-B280-E27F89274ACE.dita#GUID-91F95D0C-E4CF-510E-B280-E27F89274ACE/GUID-6C811E0E-FF79-5E06-8A62-6251CBD2C28F">Purpose</xref> </p> </li> <li id="GUID-258503E8-82E0-5150-AA5F-A3790697C422"><p><xref href="GUID-91F95D0C-E4CF-510E-B280-E27F89274ACE.dita#GUID-91F95D0C-E4CF-510E-B280-E27F89274ACE/GUID-7EB8FA0D-7892-5EF1-95BF-561163CB2A7F">Introduction</xref> </p> </li> <li id="GUID-57375575-BF24-5036-B5DD-0B4A0BEC0B57"><p><xref href="GUID-91F95D0C-E4CF-510E-B280-E27F89274ACE.dita#GUID-91F95D0C-E4CF-510E-B280-E27F89274ACE/GUID-CA9E94AC-B779-51F5-9407-74F6855AE559">Mandatory tasks</xref> </p> <ul><li id="GUID-EA0AD505-6FEF-5CB6-AF0D-305123CB8F97"><p><xref href="GUID-91F95D0C-E4CF-510E-B280-E27F89274ACE.dita#GUID-91F95D0C-E4CF-510E-B280-E27F89274ACE/GUID-1146D14D-FC0C-55B4-AD2A-A9F7F71A8299">Obtain and set up a SUPL Location Platform</xref> </p> </li> <li id="GUID-3D8393E1-E10F-56AF-ACA5-0BDFACCC537B"><p><xref href="GUID-91F95D0C-E4CF-510E-B280-E27F89274ACE.dita#GUID-91F95D0C-E4CF-510E-B280-E27F89274ACE/GUID-0C287261-D374-5056-93E1-59D8732CBE53">Get the SUPL Protocol Module</xref> </p> </li> <li id="GUID-E8111D40-1AE2-5FAF-A10E-FD22D1F42DE2"><p><xref href="GUID-91F95D0C-E4CF-510E-B280-E27F89274ACE.dita#GUID-91F95D0C-E4CF-510E-B280-E27F89274ACE/GUID-F20DE179-AAC8-501D-928A-AB153A0C5F37">Configure an A-GPS Integration Module for LBS</xref> </p> </li> <li id="GUID-CAC78758-721D-5A1D-A74D-1878A09755E1"><p><xref href="GUID-91F95D0C-E4CF-510E-B280-E27F89274ACE.dita#GUID-91F95D0C-E4CF-510E-B280-E27F89274ACE/GUID-DCC0652D-F67D-5422-8E87-4F2CCBE7B89F">Configure the LBS administration settings for SUPL</xref> </p> </li> <li id="GUID-3606684E-68CB-52E2-A165-F27588AC4C65"><p><xref href="GUID-91F95D0C-E4CF-510E-B280-E27F89274ACE.dita#GUID-91F95D0C-E4CF-510E-B280-E27F89274ACE/GUID-061F50BE-F291-53D9-ACD9-B36D19B01E54">Configure the SUPL Location Platform host settings</xref> </p> </li> <li id="GUID-5F6DD9FC-7477-5C70-8250-C51A7B8EF0B2"><p><xref href="GUID-91F95D0C-E4CF-510E-B280-E27F89274ACE.dita#GUID-91F95D0C-E4CF-510E-B280-E27F89274ACE/GUID-145112E6-6DDE-5FF6-A61A-2414E2B2EDF8">Implement ETel TSY enhancements</xref> </p> </li> <li id="GUID-5431453F-16A9-5A53-828F-3953FEA51844"><p><xref href="GUID-91F95D0C-E4CF-510E-B280-E27F89274ACE.dita#GUID-91F95D0C-E4CF-510E-B280-E27F89274ACE/GUID-C99DDA3C-FB8D-5C87-95EB-787BC4E58651">Build a ROM image to include the SUPL Protocol Module</xref> </p> </li> <li id="GUID-D2F5E821-F9A3-5886-8524-9DC8C9EF7059"><p><xref href="GUID-91F95D0C-E4CF-510E-B280-E27F89274ACE.dita#GUID-91F95D0C-E4CF-510E-B280-E27F89274ACE/GUID-FBE89F3C-7D98-528F-8DF4-93077A604C65">Test the SUPL Protocol Module</xref> </p> <ul><li id="GUID-40F6AF44-5215-5BF3-B266-6A1E15E042BF"><p><xref href="GUID-91F95D0C-E4CF-510E-B280-E27F89274ACE.dita#GUID-91F95D0C-E4CF-510E-B280-E27F89274ACE/GUID-A0D16304-B733-5CE8-9038-70DDF8C6493E">SUPL Protocol Module development logging</xref> </p> </li> </ul> </li> </ul> </li> <li id="GUID-2D366E0F-4865-510F-94B1-E0EE12F9B937"><p><xref href="GUID-91F95D0C-E4CF-510E-B280-E27F89274ACE.dita#GUID-91F95D0C-E4CF-510E-B280-E27F89274ACE/GUID-98ADB801-5665-5677-8A46-EB9F3BE40B45">Optional tasks</xref> </p> <ul><li id="GUID-78EC3BDE-404D-5AA8-9EC9-AF0AC364ABDB"><p><xref href="GUID-91F95D0C-E4CF-510E-B280-E27F89274ACE.dita#GUID-91F95D0C-E4CF-510E-B280-E27F89274ACE/GUID-1B8100CB-B9C2-5C7E-8973-EC0FF06E06C5">Create an application for managing SLP host settings</xref> </p> </li> <li id="GUID-0162916F-B1B7-5175-9CEB-80975CA91864"><p><xref href="GUID-91F95D0C-E4CF-510E-B280-E27F89274ACE.dita#GUID-91F95D0C-E4CF-510E-B280-E27F89274ACE/GUID-6E2ED828-D1D6-5FA8-9508-058360932E1B">Create a handler for SUPL INIT messages received via SMS Trigger</xref> </p> </li> <li id="GUID-984F42B9-C3A7-5ECD-A1D8-B3A3CD95BBC1"><p><xref href="GUID-91F95D0C-E4CF-510E-B280-E27F89274ACE.dita#GUID-91F95D0C-E4CF-510E-B280-E27F89274ACE/GUID-9F4E4AED-4276-5587-81FF-E43883A51971">Provision SLP root certificate for Transport Level Security (TLS)</xref> </p> </li> <li id="GUID-06FAE256-69CA-518D-A6F0-C68DD05CBDFD"><p><xref href="GUID-91F95D0C-E4CF-510E-B280-E27F89274ACE.dita#GUID-91F95D0C-E4CF-510E-B280-E27F89274ACE/GUID-62ECFF09-BBED-59FF-A835-057A67309E62">Create a plug-in to obtain a pre-shared key for PSK-TLS</xref> </p> </li> <li id="GUID-0048A93C-71F7-5F30-BB5A-1AABF10D040E"><p><xref href="GUID-91F95D0C-E4CF-510E-B280-E27F89274ACE.dita#GUID-91F95D0C-E4CF-510E-B280-E27F89274ACE/GUID-F4BA8794-2F67-5AE3-B099-FFCC156F6722">Define conflict control rules</xref> </p> </li> </ul> </li> <li id="GUID-8015C091-4038-5C5F-8F1C-8144D1AA3728"><p><xref href="GUID-91F95D0C-E4CF-510E-B280-E27F89274ACE.dita#GUID-91F95D0C-E4CF-510E-B280-E27F89274ACE/GUID-89156A75-D752-51FE-9949-DF080B4C8EB0">See also</xref> </p> </li> <li id="GUID-968D3341-9320-5E31-815D-85800C44EAC5"><p><xref href="GUID-91F95D0C-E4CF-510E-B280-E27F89274ACE.dita#GUID-91F95D0C-E4CF-510E-B280-E27F89274ACE/GUID-A3C8C7E8-981F-5CF1-A69C-0C1110951254">References</xref> </p> </li> </ul> </section> <section id="GUID-6C811E0E-FF79-5E06-8A62-6251CBD2C28F"><title>Purpose</title> <p>This document describes the tasks required to start using and testing the LBS subsystem SUPL Protocol Module and to integrate it into a device. It describes the components outside of the LBS subsystem that must be provided or modified to support SUPL and the LBS subsystem settings that must be configured so LBS can use the SUPL Protocol Module. </p> </section> <section id="GUID-7EB8FA0D-7892-5EF1-95BF-561163CB2A7F"><title>Introduction</title> <p>The SUPL Protocol Module (SPM) is a reference module provided by Symbian and is described in <xref href="GUID-CC3454B1-21DA-542E-8949-52C30755AC77.dita">SUPL Protocol Module Overview</xref>. </p> <p>Using the SPM and integrating it into a product requires a licensee to perform several tasks. Some of the tasks must be performed by all licensees and others are optional depending on how a licensee and network operator intend to use the SUPL Protocol Module. </p> </section> <section id="GUID-CA9E94AC-B779-51F5-9407-74F6855AE559"><title>Mandatory tasks</title> <p id="GUID-1146D14D-FC0C-55B4-AD2A-A9F7F71A8299"><b>Obtain and set up a SUPL Location Platform</b> </p> <p>The <xref href="GUID-CC3454B1-21DA-542E-8949-52C30755AC77.dita">SUPL Protocol Module Overview</xref> and the SUPL specification [<xref href="GUID-91F95D0C-E4CF-510E-B280-E27F89274ACE.dita#GUID-91F95D0C-E4CF-510E-B280-E27F89274ACE/GUID-A3C8C7E8-981F-5CF1-A69C-0C1110951254">1</xref>] describe the SUPL Location Platform, the server side platform that supports the SUPL standard. </p> <p>The Symbian reference SUPL Protocol Module has been tested with a commercial SUPL Location Platform (SLP). There are several different SLPs available from different vendors and a network operator may choose to use a different SLP to the one used by Symbian to test the SPM. </p> <p> <i>A licensee who intends to integrate the SPM into a device must verify that it works with the SLP chosen by the target network operator.</i> </p> <p>The details of setting up and configuring an SLP are specific to the platform used and are outside of the scope of this document. </p> <p>See <xref href="GUID-91F95D0C-E4CF-510E-B280-E27F89274ACE.dita#GUID-91F95D0C-E4CF-510E-B280-E27F89274ACE/GUID-FBE89F3C-7D98-528F-8DF4-93077A604C65">Test the SUPL Protocol Module</xref> for information about how the SPM was tested by Symbian with a commercial SLP. </p> <p id="GUID-0C287261-D374-5056-93E1-59D8732CBE53"><b>Get the SUPL Protocol Module</b> </p> <p>The SUPL Protocol Module is included as part of the Symbian LBS subsystem distribution. </p> <p>See <xref href="GUID-CC3454B1-21DA-542E-8949-52C30755AC77.dita">SUPL Protocol Module Overview</xref> for more information on the components of the SUPL Protocol Module. </p> <p id="GUID-F20DE179-AAC8-501D-928A-AB153A0C5F37"><b>Configure an A-GPS Integration Module for LBS</b> </p> <p>A GPS or Assisted GPS (A-GPS) Integration Module is required to integrate the LBS subsystem with GPS hardware. </p> <p><xref href="GUID-8F2BA0D3-1549-5837-A105-3AB484CDB80B.dita">A-GPS Location Data Source API</xref> describes how to use the A-GPS Location Data Source API to implement an Integration Module and the design of Symbian's reference SiRF A-GPS Integration Module implementation. </p> <p>The section <i>GPS/A-GPS Integration Module</i> of the <xref href="GUID-D18B4715-3942-52EA-9D2F-E145037FA47A.dita">LBS integration and configuration guide</xref> describes how to configure an Integration Module's <codeph>module.ini</codeph> configuration file so that LBS recognises and uses an Integration Module. </p> <p>The SPM supports Autonomous Mode GPS, Terminal Based Mode GPS and Terminal Assisted Mode GPS. It also supports Cell-based positioning if the accuracy of GPS is not required. </p> <p><b>Minimising assistance data requests </b> </p> <p>The LBS subsystem may be configured to use the SUPL Protocol Module when a user is roaming as described in <xref href="GUID-91F95D0C-E4CF-510E-B280-E27F89274ACE.dita#GUID-91F95D0C-E4CF-510E-B280-E27F89274ACE/GUID-DCC0652D-F67D-5422-8E87-4F2CCBE7B89F">Configure the LBS administration settings for SUPL</xref>. When roaming, charges for data, including GPS assistance data may be high. It is therefore important that a licensee's A-GPS Integration Module request only the types of assistance data it requires. Requests for necessary assistance data may unnecessarily increase the costs to the user of using GPS. </p> <p id="GUID-DCC0652D-F67D-5422-8E87-4F2CCBE7B89F"><b>Configure the LBS administration settings for SUPL</b> </p> <p>There are two LBS administration settings that specify the implementation UIDs of the Network Protocol Modules loaded by LBS and one that specifies how Network Protocol Modules are loaded: </p> <ul><li id="GUID-5448D0D5-775C-5082-A620-040D9F746C1B"><p> <codeph>KSettingHomeProtocolModule</codeph> specifies the implementation UID of the Network Protocol Module ECOM plug-in that is used when the device is in the home network. </p> </li> <li id="GUID-FEEE1897-E530-57D7-9BA9-A192FD3E5830"><p> <codeph>KSettingRoamingProtocolModule</codeph> specifies the implementation UID of the Network Protocol Module ECOM plug-in that is used when the device is roaming. </p> </li> <li id="GUID-10A29556-6C51-5E97-96C9-BFBAF475251D"><p> <codeph>KLbsProtocolModuleLoading</codeph> specifies the loading strategy for Network Protocol Modules. See the entry in <xref href="GUID-9348D79B-D4BF-50B0-B787-DDA2765CE058.dita">LBS administration service</xref> for details about the effects of this setting. Note that if LBS cannot obtain a network registration status then it cannot use a Network Protocol Module and location requests will fail. </p> <p>LBS uses the ETel API to obtain the mobile device's network registration status. LBS uses this status at startup to decide which Network Protocol Module to load. A Symbian licensee must implement the 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 registration status of the device. LBS calls <codeph>GetNetworkRegistrationStatus()</codeph> on startup to get the initial network registration status. It also subscribes for registration status changes by calling <codeph>NotifyNetworkRegistrationStatusChange()</codeph>. See <xref href="GUID-91F95D0C-E4CF-510E-B280-E27F89274ACE.dita#GUID-91F95D0C-E4CF-510E-B280-E27F89274ACE/GUID-145112E6-6DDE-5FF6-A61A-2414E2B2EDF8">Implement ETel TSY Enhancements</xref> for more information about changes that are required in a licensee's ETel TSY. </p> </li> </ul> <p>The administration settings are read by LBS on subsystem start-up. It is recommended that they are set in the <xref href="GUID-852E58C1-EA5C-5B46-9020-4463D3FA06AD.dita">LBS administration repository initialisation file</xref>. </p> <p>For LBS to load the reference SUPL Protocol Module, the administration settings values must be set to the <codeph>implementation_uid</codeph> specified in the ECOM resource file <filepath>suplprotocolmodule.rss</filepath>, which is shown below: </p> <codeblock id="GUID-5D171531-39D1-51F1-8D47-53A23AC41750" xml:space="preserve">
+// suplprotocolmodule.rss
+//
+
+#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>LBS administration settings to use the SUPL Protocol Module in the home network and when roaming are shown below, together with the module loading strategy setting: </p> <codeblock id="GUID-91AD5D81-CAA2-55F2-BB87-0B28416391AF" xml:space="preserve">
+#KSettingHomeProtocolModule.
+0x0000000E int 0x10285A9D
+#KSettingRoamingProtocolModule.
+0x0000000F int 0x10285A9D
+
+...
+
+#KLbsProtocolModuleLoading
+#Load KSettingHomeProtocolModule or KSettingRoamingProtocolModule based on network registration status
+0x00000018 int 1</codeblock> <p>A default central repository initialisation source file <filepath>1028224B.txt</filepath> can be found in the LBS source tree at <filepath><LBS_ROOT>\LbsAdmin\data</filepath>. Licensees can modify the source file <filepath>1028224B.txt</filepath> and rebuild it to configure their LBS subsystem. The directory <filepath><LBS_ROOT>\LbsAdmin\group</filepath> contains a make file <filepath>createlbsadminrep.mk</filepath> that creates the binary file from the text source. This file is exported to <filepath>\epoc32\data\z\private\10202BE9\1028224B.cre</filepath>. </p> <p> <b>Note that the default initialisation file that ships with LBS is not configured to use the Symbian reference SUPL Protocol Module.</b> Licensees must modify the settings described above to use the reference SUPL Protocol Module when the device is in the home network and when roaming. </p> <p id="GUID-061F50BE-F291-53D9-ACD9-B36D19B01E54"><b>Configure the SUPL Location Platform host settings</b> </p> <p>The <xref href="GUID-FE4794F8-2519-5AC2-BCF7-168ECA6645EA.dita">Host Settings API</xref> is the interface through which SLP host settings are configured at runtime. The API is a wrapper on a central repository area that defines the host settings for SET initiated and network initiated location requests. The settings also define the encryption and authentication methods that must be used between the SET and the SLP. </p> <p>Host Settings can be configured in one or more of the following ways: </p> <ul><li id="GUID-E14D26B7-836E-5204-A5F2-C0B181130318"><p>Over the air from a Device Management server (Symbian provide a SUPL Host Settings Device Management plug-in). </p> </li> <li id="GUID-6F707444-1ACE-5B6D-866F-0468D8EEA47C"><p>Over the air, or from a local data source (such as a SIM card), using Client Provisioning (Symbian provide a SUPL Host Settings Client Provisioning plug-in). </p> </li> <li id="GUID-56958247-9FE0-5114-AEFD-391FD053E224"><p>By a locally installed client application such as an "LBS settings application" that a licensee may have already created to configure other LBS settings. </p> </li> <li id="GUID-109221DF-1D46-50DD-A720-174EEA1A81A6"><p>By installation of a host settings central repository initialisation file. </p> </li> </ul> <p>More that one of these methods can be used by a licensee and network operator to configure the SLP host settings. For example, host settings can be pre-configured in the device in a central repository initialisation file, the default SLP can be changed via an LBS settings application and a network operator can also send Device Management messages to change the settings over-the-air. </p> <p>To begin testing with the SUPL Protocol Module, the simplest approach is to create a host settings initialisation file. </p> <p>An example host settings initialisation text file is shown below. The comments refer to the methods that are used to get SLP host settings via the <xref href="GUID-FE4794F8-2519-5AC2-BCF7-168ECA6645EA.dita">Host Settings API</xref>. </p> <codeblock id="GUID-718286A4-3964-5B29-9583-D2C464DB4F52" xml:space="preserve">
+# 1.0 File Version For Supl Host Settings
+
+# This file is compiled into the binary '.cre' version
+# by an extension makefile (createbinaryrep.mk), which
+# is called as part of the standard abld build process.
+#
+# The ".cre" version is the one used to install the
+# repository when the ROM is built.
+cenrep
+version 1
+
+[platsec]
+cap_rd=AlwaysPass
+cap_wr=WriteDeviceData
+
+[Main]
+#counter for record IDs in the settings store - 2 in this case
+0x00000001 int 2 0
+# default SLP host
+0x00000002 int 1
+# ---------- SLP Host A ----------
+# ECreatorId
+# Host settings creator - device provisioning in this case
+# Value is KLbsHostSettingsDevProvCreatorId as defined in lbshostsettings.h
+0x10000000 int 0x10285AA9 // TLbsHostSettingsBase::CreatorId()
+# EConnectionId
+0x20000000 int 0 // TLbsHostSettingsSupl::GetConnectionPoint() - Connection point
+# EConnectionIdType
+0x30000000 int 1 // TLbsHostSettingsSupl::GetConnectionPoint() - Connection type
+# EHostAddress
+0x40000000 string8 <ENTER HOST 1 ADDRESS HERE> // TLbsHostSettingsSupl::GetHostNameAddress()
+# EReadOnly
+0x50000000 int 0 // TLbsHostSettingsSupl::GetReadOnly()
+# EHostPort
+0x60000000 int 7275 // Standard port for SUPL - TLbsHostSettingsSupl::GetPortId()
+# EHostName
+0x70000000 string8 <ENTER HOST 1 NAME HERE> // TLbsHostSettingsSupl::GetName()
+# EProviderId
+0x80000000 string8 Symbian // TLbsHostSettingsSupl::GetProviderId()
+# ETimestamp
+0x90000000 string 20080514:134400.000000 // TLbsHostSettingsBase::LastModified()
+# EAuthMoLr
+0xA0000000 int 1 // TLbsHostSettingsSupl::GetAuthModesMolr()
+# EAuthMtLr
+0xB0000000 int 1 // TLbsHostSettingsSupl::GetAuthModesMtlr()
+
+# ---------- SLP Host B (uses TLS) ----------
+# ECreatorId
+0x10000001 int 0x10285AA9
+# EConnectionId
+0x20000001 int 0
+# EConnectionIdType
+0x30000001 int 0
+# EHostAddress
+0x40000001 string8 <ENTER HOST 2 ADDRESS HERE>
+# EReadOnly
+0x50000001 int 0
+# EHostPort
+0x60000001 int 7275
+# EHostName
+0x70000001 string8 <ENTER HOST 2 NAME HERE>
+# EProviderId
+0x80000001 string8 Symbian
+# ETimestamp
+0x90000001 string 20080514:134400.000000
+# EAuthMoLr
+0xA0000001 int 2
+# EAuthMtLr
+0xB0000001 int 2
+</codeblock> <p>The following are the most important points about the values in this file: </p> <ul><li id="GUID-07E1D482-DB28-513B-B917-764081C00CDB"><p>The settings for each SLP host have a unique key range. In the example above the keys for the SLP Host A settings range from <codeph>0x10000000</codeph> to <codeph>0xB0000000</codeph>. For SLP Host B the settings keys range from <codeph>0x10000001</codeph> to <codeph>0xB0000001</codeph>. </p> <p>The first part of the key describes the type of setting. For SLP Host A, 0x10000000 is the key for the settings creator ID and 0x20000000 is the key for the settings connection point ID. </p> <p>The last part of the key specifies the SLP host for which the settings apply: <codeph>0x10000000</codeph> is the key for the settings creator ID for the SLP Host A settings and <codeph>0x10000001</codeph> is the key for the settings creator UID of the SLP Host B settings. The unique value for the last part of the key identifies that a group of settings values belong to the same SLP Host. To specify new settings for an SLP Host C, the next logical range of keys is <codeph>0x10000002</codeph> to <codeph>0xB0000002</codeph>. </p> <p><xref href="GUID-FE4794F8-2519-5AC2-BCF7-168ECA6645EA.dita">Host Settings API</xref> describes how a program can read and create host settings. </p> </li> <li id="GUID-76A087F5-AB7D-504C-A67C-450F93CC4EDA"><p>The value of <codeph>EHostAddress</codeph> must be set to the IP number or domain name of the SLP host server. </p> </li> <li id="GUID-FA586B8F-750F-5EA3-9B5D-4E05AE6A556F"><p>The value of <codeph>EHostName</codeph> must be set to a name to identify the server (for example in a settings application that allows users to select the SLP). </p> </li> <li id="GUID-1A1AEF76-EDE9-5855-8A13-8F99E25EBB6E"><p>The values of <codeph>EAuthMolr</codeph> and <codeph>EAuthMtlr</codeph> describe the authentication and encryption method(s) that are allowed for SET initiated location requests (MO-LR) and network initiated location requests (MT-LR). </p> <p>Several different levels of authentication and encryption are defined by the Host Settings API enumeration <xref href="GUID-5B492B69-19D2-38B8-946F-FD1155513F9F.dita#GUID-5B492B69-19D2-38B8-946F-FD1155513F9F/GUID-08CE8437-2BEB-3FCE-ABCD-0D842D079560"><apiname>TLbsHostSettingsSupl::_TAuthModes</apiname></xref>. The values of the enumeration are described in the table shown below. Note that the value in the initialisation file is decimal: </p> <table id="GUID-6C8B40BC-770C-5F14-813A-C3059E6BD1BA"><tgroup cols="3"><colspec colname="col0"/><colspec colname="col1"/><colspec colname="col2"/><thead><row><entry>Meaning</entry> <entry>TLbsHostSettingsSupl::_TAuthModes</entry> <entry>Numeric value</entry> </row> </thead> <tbody><row><entry><p>Do not use authentication/encryption </p> </entry> <entry><p> <codeph>EAuthNone</codeph> </p> </entry> <entry><p>1 </p> </entry> </row> <row><entry><p>Use TLS </p> </entry> <entry><p> <codeph>EAuthTls</codeph> </p> </entry> <entry><p>2 </p> </entry> </row> <row><entry><p>Use ACA + TLS </p> </entry> <entry><p> <codeph>EAuthAcaTls</codeph> </p> </entry> <entry><p>4 </p> </entry> </row> <row><entry><p>Use PSK + TLS </p> </entry> <entry><p> <codeph>EAuthPskTls</codeph> </p> </entry> <entry><p>8 </p> </entry> </row> </tbody> </tgroup> </table> <p>The values are bitwise added to describe the set of possible types of authentication and encryption that can be used between the SET and an SLP. At runtime the SET and the SLP negotiate to use the highest level of security and authentication supported by both. </p> <p>For example, to specify that either ACA + TLS or PSK + TLS are allowed for SET initiated location requests, <codeph>EAuthMolr</codeph> must be set to <codeph>EAuthAcaTls | EAuthPskTls</codeph> = 12. </p> <p>Note that the SUPL specification [<xref href="GUID-91F95D0C-E4CF-510E-B280-E27F89274ACE.dita#GUID-91F95D0C-E4CF-510E-B280-E27F89274ACE/GUID-A3C8C7E8-981F-5CF1-A69C-0C1110951254">1</xref>] mandates the use of ACA or PSK with TLS, but turning off authentication and encryption can be useful for testing. </p> </li> </ul> <p><b>Installing a host settings initialisation file </b> </p> <p>A host settings initialisation text file can be converted to a binary file using the make file in <filepath><LBS_ROOT>\LbsSuplProtocolModule\HostSettingsAPI\group\createlbssuplstore.mk</filepath>, where <filepath><LBS_ROOT></filepath> is the root directory of the LBS source tree. </p> <p>The source file is copied to <filepath>\epoc32\winscw\c\private\10202be9\10285AA8.cre</filepath> on the emulator and to <filepath>z:\private\10202be9\10285AA8.cre</filepath> on hardware. </p> <p><b>Rules for host settings selection </b> </p> <p>This section describes the rules that are used by the SUPL Protocol Module to choose SLP host settings for SET initiated location requests (MO-LRs) and network initiated location requests (MT-LRs). </p> <p> <b>Rules for SET initiated location requests (MO-LR)</b> </p> <ul><li id="GUID-652019AF-0038-5580-9CFF-0B7A16B04F8F"><p>If a default host is specified, use it for MO-LR. </p> <p>The example host settings file shown above contains the following lines: </p> <codeblock id="GUID-F4788690-5E37-550A-A20E-18CCE60DAABE" xml:space="preserve">
+# default SLP host
+0x00000002 int 1
+</codeblock> <p>The entry specifies that the host setting keys beginning at <codeph>0x10000001</codeph> must be used for MO-LR because 1 is the last digit of <codeph>0x10000001</codeph>. This is the host specified as SLP Host 2 in the example host settings file shown above. </p> </li> <li id="GUID-3FF3EC3C-0356-5544-B363-CEA95B8B8EE3"><p>If a default host is not specified, use the host that was most recently provisioned from the network. </p> <p>A timestamp value is associated with each host settings entry as shown in the example host settings file. This key is commented as <codeph>ETimestamp</codeph> in the example host settings file. </p> <p>A creator UID value of <codeph>0x10285AA9</codeph> is specified for host settings that were provisioned from the network. This UID is the value of <codeph>KLbsHostSettingsDevProvCreatorId</codeph> as defined in <filepath>lbshostsettings.h</filepath>. </p> </li> <li id="GUID-C770A9B1-F9CA-59A2-A7FB-C4E5BA13158B"><p>If neither of the above rules can be used to obtain host settings, derive a host address from the <xref href="GUID-91F95D0C-E4CF-510E-B280-E27F89274ACE.dita#GUID-91F95D0C-E4CF-510E-B280-E27F89274ACE/GUID-145112E6-6DDE-5FF6-A61A-2414E2B2EDF8">IMSI</xref> as described in [<xref href="GUID-91F95D0C-E4CF-510E-B280-E27F89274ACE.dita#GUID-91F95D0C-E4CF-510E-B280-E27F89274ACE/GUID-A3C8C7E8-981F-5CF1-A69C-0C1110951254">1</xref>]. </p> </li> </ul> <p> <b>Rules for network initiated location requests (MT-LR)</b> </p> <ul><li id="GUID-2D213DB0-BA6B-5CDB-AC9A-4866A0611E53"><p>Use the host settings that were most recently provisioned from the network. </p> <p>The host settings with a creator UID value of <codeph>0x10285AA9</codeph> and the most recent timestamp are used. </p> </li> <li id="GUID-A8D4079D-87C2-58CD-ACC6-58AFF28BF4A2"><p>If there are no host settings with a creator UID of <codeph>0x10285AA9</codeph> derive a host address from the <xref href="GUID-91F95D0C-E4CF-510E-B280-E27F89274ACE.dita#GUID-91F95D0C-E4CF-510E-B280-E27F89274ACE/GUID-145112E6-6DDE-5FF6-A61A-2414E2B2EDF8">IMSI</xref> as described in [<xref href="GUID-91F95D0C-E4CF-510E-B280-E27F89274ACE.dita#GUID-91F95D0C-E4CF-510E-B280-E27F89274ACE/GUID-A3C8C7E8-981F-5CF1-A69C-0C1110951254">1</xref>]. </p> </li> </ul> <p id="GUID-145112E6-6DDE-5FF6-A61A-2414E2B2EDF8"><b>Implement ETel TSY enhancements</b> </p> <p>LBS and the SUPL Protocol Module use the ETel API to get location information, network status information and mobile subscriber identity information. The following types of information must be available to the SUPL Protocol Module: </p> <ul><li id="GUID-CDB56FE0-977A-5184-A4C3-B92768709792"><p>The mobile network cell ID </p> <p>The SUPL Protocol Module uses the method <xref href="GUID-AA81AFA4-6FAC-3B0D-A082-BE0AEC58CCA8.dita#GUID-AA81AFA4-6FAC-3B0D-A082-BE0AEC58CCA8/GUID-622488D3-9665-3249-85EE-D509D17193F6"><apiname>RMobilePhone::GetCellInfo()</apiname></xref> to get a cell info object of type <xref href="GUID-C5598BFB-9048-3527-AD66-D45819813B71.dita"><apiname>TMobilePhoneCellInfoV9</apiname></xref>, which contains the cell ID as specified in [<xref href="GUID-91F95D0C-E4CF-510E-B280-E27F89274ACE.dita#GUID-91F95D0C-E4CF-510E-B280-E27F89274ACE/GUID-A3C8C7E8-981F-5CF1-A69C-0C1110951254">2</xref>] and [<xref href="GUID-91F95D0C-E4CF-510E-B280-E27F89274ACE.dita#GUID-91F95D0C-E4CF-510E-B280-E27F89274ACE/GUID-A3C8C7E8-981F-5CF1-A69C-0C1110951254">3</xref>]. The cell ID is passed from the SET to the SLP as part of a <codeph>SUPL POS INIT</codeph> message and is used to obtain a cell-based position and/or GPS assistance data. </p> <p>To use cell-based positioning or request assistance data, the ETel TSY must be implemented to return the cell ID. </p> </li> <li id="GUID-F2A16BDF-9DE0-58DD-B6BF-10660ED6F1F9"><p>Timing advance information for enhanced cell-based positioning </p> <p>A <xref href="GUID-653A00A1-9007-30BB-8E0B-43E39C3A27E0.dita"><apiname>TMobilePhoneCellInfov9</apiname></xref> object also contains a timing advance parameter to support enhanced cell-based positioning in GSM networks. If the licensee ETel TSY can provide timing advance information, it is returned to the network as part of a <codeph>SUPL POS
+ INIT</codeph> message and allows a more accurate cell-based position to be calculated. </p> </li> <li id="GUID-47326313-B2E5-5C08-A549-4C5F689C26DE"><p>The network registration status </p> <p>On startup, LBS gets the current network registration status of the device by calling <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>. LBS receives notification of changes to the mobile device's network registration status by calling <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>. The ETel TSY must be implemented to return the network registration status for both of these methods. </p> <p>LBS loads one or more Network Protocol Modules based on the settings specified in the <xref href="GUID-91F95D0C-E4CF-510E-B280-E27F89274ACE.dita#GUID-91F95D0C-E4CF-510E-B280-E27F89274ACE/GUID-DCC0652D-F67D-5422-8E87-4F2CCBE7B89F">LBS administration settings</xref>. </p> <p> <b>Note that if the ETel TSY is not implemented to report the network registration status, LBS cannot use a Network Protocol Modules and location requests will fail.</b> </p> </li> <li id="GUID-66889509-4B4C-5D2B-A833-ABD9638584A3"><p>The International Mobile Subscriber Identity (IMSI) </p> <p>[<xref scope="external" href="http://www.openmobilealliance.org">1</xref>] describes how the IMSI must be used to derive a default Home SUPL Location Platform (H-SLP) host address if the value has not been provisioned on the mobile device by some other means. </p> <p>The SUPL Protocol Module derives a default H-SLP host address from the IMSI if it cannot be obtained using the Host Settings API. It uses the <xref href="GUID-AA81AFA4-6FAC-3B0D-A082-BE0AEC58CCA8.dita#GUID-AA81AFA4-6FAC-3B0D-A082-BE0AEC58CCA8/GUID-3E541EF3-E466-382F-9979-605A4EDC4B30"><apiname>RMobilePhone::GetSubscriberId()</apiname></xref> method to obtain the IMSI. The ETEL TSY must be implemented to return the IMSI to handle situations where the H-SLP host address has not been provisioned by other means. </p> </li> </ul> <p id="GUID-C99DDA3C-FB8D-5C87-95EB-787BC4E58651"><b>Build a ROM image to include the SUPL Protocol Module</b> </p> <p>The SUPL Protocol Module and its supporting components are all built as part of the standard LBS code build process. The components are part of the set of LBS <filepath>.exe</filepath> and <filepath>.dll</filepath> files that are delivered to licensees as part of an LBS distribution. </p> <p>The SUPL Protocol Module and its supporting components are not included by default in an LBS ROM image. It is necessary for a licensee to specify ROM build macros to include the SUPL Protocol Module in a ROM image. </p> <p>The following SUPL macros are checked in the LBS .iby files: </p> <ul><li id="GUID-EE1CFEF6-D108-512C-9B39-ED2FD66209D7"><p> <b>SYMBIAN_INCLUDE_LOCATION_SUPLv10</b> includes the SUPL Protocol Module, the WAP Push Handler plug-in, the test SMS Trigger plug-in and the Host Settings API DLL in ROM. </p> </li> <li id="GUID-6D337264-76C9-52E2-B30E-83D9B9EF3F9A"><p> <b>SYMBIAN_EXCLUDE_LOCATION_SUPLv10_SMS</b> excludes the test SMS Trigger plug-in from ROM. </p> <p>Note that the SMS Trigger plug-in is a test component for licensees to test <codeph>SUPL INIT</codeph> messages sent via Mobile Terminated SMS. </p> </li> <li id="GUID-3A443D85-F1DD-59E3-BFD6-097BF60FE1BC"><p> <b>SYMBIAN_EXCLUDE_LOCATION_SUPLv10_WAP</b> excludes the WAP Push plug-in from ROM. </p> </li> </ul> <p>To build a ROM image to include the SUPL Protocol Module, a licensee uses a command as shown below: </p> <codeblock id="GUID-94114427-BB0F-5C14-8B06-9858336BE059" xml:space="preserve">
+buildrom lbs.oby -DSYMBIAN_INCLUDE_LOCATION_SUPLv10
+</codeblock> <p>where <codeph>lbs.oby</codeph> contains the following files: </p> <codeblock id="GUID-5F40AC8D-04FC-56D9-A732-09BDD86FBAE1" xml:space="preserve">
+#if !defined(SYMBIAN_EXCLUDE_LOCATION)
+
+#include "lbsadmin.iby"
+
+#include "lbslocserver.iby"
+
+#include "lbsagpslocmanager.iby"
+
+#include "LbsNetworkLocationManager.iby"
+
+#include "lbsnetworkrequesthandler.iby"
+
+#include "lbsnetgateway.iby"
+
+#include "lbssupl.iby" // Includes checks for SUPL ROM build macros
+
+#include "sirfdatasource.iby" // Only required to include the Symbian reference A-GPS module
+
+#endif // SYMBIAN_EXCLUDE_LOCATION
+</codeblock> <p id="GUID-FBE89F3C-7D98-528F-8DF4-93077A604C65"><b>Test the SUPL Protocol Module</b> </p> <p>This section describes how the SUPL Protocol Module was tested for SET initiated location requests (MO-LRs) and network initiated location requests (MT-LRs). A set of OMA SUPL conformance test cases [<xref href="GUID-91F95D0C-E4CF-510E-B280-E27F89274ACE.dita#GUID-91F95D0C-E4CF-510E-B280-E27F89274ACE/GUID-A3C8C7E8-981F-5CF1-A69C-0C1110951254">2</xref>] have also been used to test the SPM. </p> <p>Symbian licensees can use the Symbian tests as the basis for testing the SPM with their own SLP. The SPM was tested by Symbian with a commercial SUPL server using the Symbian Test Execute Framework (TEF). TEF runs individual test steps (test cases or part test cases) defined by test scripts and provides logging containing the test results in html (or xml) files on the device. </p> <p>TEF is invoked by the command <codeph>testexecute.exe
+ <FullFilePath\xxx.script></codeph> which can be invoked from <codeph>eshell</codeph> in the emulator. <codeph>testexecute.exe</codeph> interprets the script commands within the <codeph>.script</codeph> file passed to it as an argument. </p> <p><b>SUPL TEF test suites </b> </p> <p>The TEF test suites that were used by Symbian to test the SPM can be found in the SUPL test directory <filepath><LBS_ROOT>\test\testproduct\supl</filepath> where <filepath><LBS_ROOT></filepath> is the LBS subsystem source distribution root directory. Some of these tests were performed using Symbian simulation components and others were performed using a commercial SUPL server. </p> <p>A number of sub-directories for different categories of tests exist within this SUPL test directory: </p> <ul><li id="GUID-52AA248B-7262-517F-88A5-EF34DE842B92"><p> <filepath>.\molr\real</filepath> contains tests for SET initiated location requests. </p> <p>The TEF script file for these tests can be found at <filepath>.\molr\real\scripts\suplmolrrealtest.script</filepath>. </p> <p>It should be noted that the test scripts are customised for internal Symbian testing. In particular they use a Symbian test A-GPS Integration Module. Licensees may need to modify test scripts and test cases to meet their own needs. </p> </li> <li id="GUID-48006F0C-6769-5B30-818B-6DBECCAD853F"><p> <filepath>.\mtlr\real</filepath> contains tests for network initiated location requests. </p> </li> <li id="GUID-07DA731B-B32E-5D2A-BA61-7A523C2E122A"><p> <filepath>.\omaconformance</filepath> contains OMA defined tests as described in [<xref href="GUID-91F95D0C-E4CF-510E-B280-E27F89274ACE.dita#GUID-91F95D0C-E4CF-510E-B280-E27F89274ACE/GUID-A3C8C7E8-981F-5CF1-A69C-0C1110951254">2</xref>]. </p> </li> </ul> <p><b>MLP Module </b> </p> <p>The MLP Module is released to licensees as an unsupported test component that may assist them in testing the SUPL Protocol Module with a SUPL Location Platform. </p> <p>OMA defines the Mobile Location Protocol (MLP) specification [<xref href="GUID-91F95D0C-E4CF-510E-B280-E27F89274ACE.dita#GUID-91F95D0C-E4CF-510E-B280-E27F89274ACE/GUID-A3C8C7E8-981F-5CF1-A69C-0C1110951254">3</xref>] for sending requests for location from a client to a server and for receiving location responses. MLP can be used to cause an SLP to start a network initiated location request. </p> <p>Symbian has developed an MLP test module for SUPL Protocol Module testing within Symbian. It is delivered as part of the LBS source distribution at <filepath><LBS_ROOT>\test\testproduct\supl\tools\mlpmodule</filepath>. The MLP module is used by the Symbian SUPL TEF tests to drive SUPL servers for testing. The MLP is packaged in <filepath>lbsmlpmodule.dll</filepath>. The MLP module interface is defined in <filepath>lbsmlpmodule.h</filepath>. </p> <p>The MLP Module is not required to test the SUPL Protocol Module with an SLP. It does not have a published interface but can be used by licensees to send an MLP Standard Location Immediate Request (SLIR) via HTTP Post to an SLP to initiate a network initiated location request. The server responds with a Standard Location Immediate Answer (SLIA) that can be parsed by the MLP. </p> <p>To use the MLP Module a client opens a server connection and uses one of several request methods to send an SLIR to an SLP. The method <codeph>SendParseLocRequestFromFileL()</codeph> can be used to read an SLIR document (which must conform to the SLIR DTD [<xref href="GUID-91F95D0C-E4CF-510E-B280-E27F89274ACE.dita#GUID-91F95D0C-E4CF-510E-B280-E27F89274ACE/GUID-A3C8C7E8-981F-5CF1-A69C-0C1110951254">3</xref>]) from a file, send the contents to an SLP and parse the returned SLIA to extract a returned handset number and reference position. </p> <p>If the contents of the SLIR are correctly defined, the SLP will respond by sending a <codeph>SUPL INIT</codeph> message to the handset number (MSID) specified in the SLIR. </p> <p>The example code shown below outlines how to use the MLP module to start a <codeph>SUPL INIT</codeph>. </p> <codeblock id="GUID-4972DF0E-0A08-57D9-8616-37F7EE37A2B9" xml:space="preserve">
+#include <lbsmlpmodule.h>
+
+...
+
+_LIT(KTestSLIRFile1, "c:\\testdata\\configs\\slir1.txt"); // Set this to the location of SLIR data file
+_LIT8(KTheURL, "http://slp_hostname:port/"); // Set this to the SLP host & port
+
+TPtrC theFile(KTestSLIRFile1);
+TPtrC8 url(KTheURL);
+
+HBufC8* handset = NULL;
+TPosition pos;
+TInt timeout = 300; // MLP times out if no SLIA received from SLP
+TInt error;
+
+TAny* serverState = OpenServerL(url);
+error = SendParseLocRequestFromFileL(serverState, theFile, timeout, handset, pos);
+
+// Can check the handset and pos variables to verify what the SLP returned in the SLIA
+// If all is well, SLP should send SUPL INIT messsage to the handset specified in the SLIR
+// WAP Push plug-in or SMS Trigger plug-in will process the SUPL INIT and SPM will open a connection to the SLP...
+
+// Cleanup
+if (handset)
+ {
+ delete handset;
+ }
+
+CloseServer(serverState);
+</codeblock> <p id="GUID-A0D16304-B733-5CE8-9038-70DDF8C6493E"><b>SUPL Protocol Module development logging</b> </p> <p>The LBS subsystem contains a logging component in <filepath>lbspartnercommon.dll</filepath>. The logging component is used by many LBS subsystem components to write logs to a file. The source file <filepath><LBS_ROOT>\LbsPartnerCommon\inc\lbsdevloggermacros.h</filepath> contains logging macro definitions wrapped in the following <codeph>#ifdef</codeph> statement: </p> <codeblock id="GUID-42D8E23B-B560-5C01-BB9F-63BCCF7B860A" xml:space="preserve">
+#if defined(ENABLE_LBS_DEV_LOGGER) && (defined(_DEBUG)||defined(__WINS__))
+
+// LBS logging macro definitions - details omitted
+
+#endif
+</codeblock> <p>The SUPL Protocol Module contains its own logging component in <filepath>supldevlogger.dll</filepath>. The source file <filepath><LBS_ROOT>\LbsSuplProtocolModule\SuplDevLogger\inc\supldevloggermacros.h</filepath> contains the logging macro definitions wrapped in the following <codeph>#ifdef</codeph> statement: </p> <codeblock id="GUID-27F2E716-9BF3-5BDC-8422-91EB07628DE7" xml:space="preserve">
+#if defined(ENABLE_SUPL_DEV_LOGGER) && (defined(_DEBUG)||defined(__WINS__))
+
+// SUPL logging macro definitions - details omitted
+
+#endif
+</codeblock> <p>The logging macros are used for debugging only and are not part of a published interface. </p> <p>For an emulator build, log messages from the SUPL Protocol Module and other LBS components are written to <filepath>\epoc32\winscw\c\logs\lbs\lbs.txt</filepath>. Logging is also enabled for hardware debug builds. </p> <p>The macro <codeph>ENABLE_LBS_DEV_LOGGER</codeph> is defined in several LBS subsystem MMP files. The macro <codeph>ENABLE_SUPL_DEV_LOGGER</codeph> is defined in the SUPL Protocol Module MMP files. Logging is turned on for emulator builds and for hardware debug builds. It is necessary to modify the <codeph>#if</codeph> condition in <filepath>lbsdevloggermacros.h </filepath> and <filepath>supldevloggermacros.h</filepath> and recompile the LBS codebase to obtain logging messages for hardware release builds. Development logging should not be permanently enabled for release builds. </p> </section> <section id="GUID-98ADB801-5665-5677-8A46-EB9F3BE40B45"><title>Optional tasks</title> <p id="GUID-1B8100CB-B9C2-5C7E-8973-EC0FF06E06C5"><b>Create an application for managing SLP host settings</b> </p> <p><xref href="GUID-91F95D0C-E4CF-510E-B280-E27F89274ACE.dita#GUID-91F95D0C-E4CF-510E-B280-E27F89274ACE/GUID-061F50BE-F291-53D9-ACD9-B36D19B01E54">Configure the SUPL Location Platform host settings</xref> describes how to configure SLP host settings using a central repository initialisation file. </p> <p>Symbian licensees may have previously created a settings application for configuring LBS subsystem behaviour at runtime using the <xref href="GUID-9348D79B-D4BF-50B0-B787-DDA2765CE058.dita">LBS Administration API</xref>. Such an application can be extended to allow users to configure SLP host settings using the <xref href="GUID-FE4794F8-2519-5AC2-BCF7-168ECA6645EA.dita">Host Settings API</xref>. </p> <p>This is an optional task because it is not necessary to give device users any visibility of the host settings or control over them. </p> <p>See <xref href="GUID-FE4794F8-2519-5AC2-BCF7-168ECA6645EA.dita">Host Settings API</xref> for details of how to configure the host settings at runtime. </p> <p id="GUID-6E2ED828-D1D6-5FA8-9508-058360932E1B"><b>Create a handler for SUPL INIT messages received via SMS Trigger</b> </p> <p>The <xref href="GUID-CC3454B1-21DA-542E-8949-52C30755AC77.dita">SUPL Protocol Module Overview</xref> describes the WAP Push plug-in and test SMS Trigger plug-in that can be used to process <codeph>SUPL INIT</codeph> messages to begin network initiated location requests (MT-LRs). </p> <p>The WAP Push plug-in can be used to receive <codeph>SUPL INIT</codeph> messages sent using WAP Push. The plug-in is packaged in <codeph>lbssuplwappush.dll</codeph> and is automatically built into an <xref href="GUID-91F95D0C-E4CF-510E-B280-E27F89274ACE.dita#GUID-91F95D0C-E4CF-510E-B280-E27F89274ACE/GUID-C99DDA3C-FB8D-5C87-95EB-787BC4E58651">LBS SUPL ROM image</xref> unless it is deliberately excluded. The WAP Push plug-in is loaded by the WAP Push Framework. </p> <p>The SMS Trigger plug-in can be used to receive <codeph>SUPL INIT</codeph> messages sent using SMS. The SMS Trigger plug-in is a Symbian <i>test component</i>. The plug-in is packaged in <codeph>lbssuplsmstrigger.dll</codeph> and is automatically built into an <xref href="GUID-91F95D0C-E4CF-510E-B280-E27F89274ACE.dita#GUID-91F95D0C-E4CF-510E-B280-E27F89274ACE/GUID-C99DDA3C-FB8D-5C87-95EB-787BC4E58651">LBS SUPL ROM image</xref> unless it is deliberately excluded. The SMS Trigger plug-in is loaded by the Symbian messaging Watcher Framework. </p> <p>It is possible for Symbian licensees to build their own handler for processing <codeph>SUPL INIT</codeph> messages received via SMS. The only requirement for any licensee-implemented <codeph>SUPL INIT</codeph> message handler is that it uses the <xref href="GUID-E7DD9CFD-F477-5D25-BC10-BEBFB1022F7E.dita">SUPL Push API</xref> to send the SUPL INIT message into the SUPL Protocol Module. </p> <p>The source code of the test Symbian SUPL SMS Trigger plug-in can be found in the LBS source code tree at <filepath><LBS_ROOT>/LbsSuplProtocolModule/SuplSmsTrigger/</filepath>. </p> <p>The source code of the WAP Push plug-in can be found in the LBS source code tree at <filepath><LBS_ROOT>/LbsSuplProtocolModule/SuplWapPush/</filepath>. </p> <p id="GUID-9F4E4AED-4276-5587-81FF-E43883A51971"><b>Provision SLP root certificate for TLS</b> </p> <p>To use Transport Level Security (TLS) for communication encryption between the mobile device and the SLP it is necessary to import the SLP root certificate into a certificate store on the mobile device. While using TLS is not required for simple testing, it is required for SET - SLP communications in production deployments [<xref href="GUID-91F95D0C-E4CF-510E-B280-E27F89274ACE.dita#GUID-91F95D0C-E4CF-510E-B280-E27F89274ACE/GUID-A3C8C7E8-981F-5CF1-A69C-0C1110951254">1</xref>]. </p> <p>Certificate stores are managed using the Symbian <filepath>certtool</filepath> application. The tool is used to import certificates for use in the Symbian emulator and allows them to be exported to ROM. </p> <p>The document <xref href="GUID-DF4A992B-E03B-57F5-9D5B-1C112FC16544.dita">Example for Creating a Default Certificate Store</xref> describes how to use certtool to create certificate stores for the Symbian emulator and a ROM. Briefly the steps required are as follows: </p> <ul><li id="GUID-578067EA-905A-5382-89B6-994496EE5A08"><p>Obtain the certificate that the SLP uses for TLS. </p> <p>The SLP vendor, or the network operator that owns the SLP should be able to provide a certificate. </p> </li> <li id="GUID-75471AC1-F1EA-510B-B9C5-A7DCEED47948"><p>Import the certificate into a Symbian certificate store. </p> <p>The certificate is imported using the <codeph>certtool
+ -import</codeph> command as follows: </p> <codeblock id="GUID-78C197FD-9017-5122-A00F-A11C1746172F" xml:space="preserve">
+certtool -label <label-name> –import <certificate-file>
+</codeblock> <p>where <i>label-name</i> is a name used to identify the certificate and <i><certificate-file></i> is the filename of the certificate provided by the SLP vendor. </p> </li> <li id="GUID-2865169D-A3CB-5999-9562-E3F2061E2309"><p>Trust the SLP vendor certificate for use with TLS. </p> <p>The certificate is trusted for use with TLS using the <codeph>certtool -setapps -apps</codeph> command as follows: </p> <codeblock id="GUID-6BC6A9F2-E0B6-5BFE-9F36-F83860273AC5" xml:space="preserve">certtool –setapps –apps SSL/TLS <label-name></codeblock> <p>where <i>label-name</i> is the label given to the certificate when it was imported into the certificate store. </p> </li> <li id="GUID-5805699D-A0C3-50F9-82F8-B67B14387BDB"><p>The host settings must be modified to specify that TLS must be used between the SUPL Protocol Module and the SUPL Location Platform as described in the section <xref href="GUID-91F95D0C-E4CF-510E-B280-E27F89274ACE.dita#GUID-91F95D0C-E4CF-510E-B280-E27F89274ACE/GUID-061F50BE-F291-53D9-ACD9-B36D19B01E54">Configure the SUPL Location Platform host settings</xref>. </p> </li> </ul> <p id="GUID-62ECFF09-BBED-59FF-A835-057A67309E62"><b>Create a plug-in to obtain a pre-shared key for PSK-TLS</b> </p> <p> <b>Note: The Pre-Shared Keys API is not yet implemented and it is not yet possible to use PSK-TLS with the SUPL Protocol Module.</b> </p> <p>A future release of the SUPL Protocol Module will include support to retrieve a pre-shared key via the Pre-Shared Keys (PSK) API, which will enable the use of PSK-TLS. When the PSK API is implemented this section will describe how to configure LBS to use it. It is not yet possible to use PSK-TLS with the SUPL Protocol Module. </p> <p>Alternative Client Authentication (ACA-TLS) is currently supported by the SUPL Protocol Module. </p> <p id="GUID-F4BA8794-2F67-5AE3-B099-FFCC156F6722"><b>Define conflict control rules</b> </p> <p> <b>Configurable conflict control is not yet suported by the SUPL Protocol Module.</b> </p> <p>Currently a simple set of rules is built into the SUPL Protocol Module for the following situations when a second location request is received by LBS while a previously received location request is still being processed: </p> <ul><li id="GUID-694BE785-64ED-550D-8870-9EBEC643F8CA"><p>SET initiated location request followed by a second SET initiated location request from a new client (two MO-LRs). </p> <p>Figure 1 illustrates the discussion that follows, which assumes the LBS subsystem is configured to use terminal based GPS. </p> <p>A <i>new client</i> is one that opens a subsession by calling <xref href="GUID-1EAEB7EF-0AC7-37C7-B35F-C9B780FFC575.dita#GUID-1EAEB7EF-0AC7-37C7-B35F-C9B780FFC575/GUID-AF3D9B5F-8025-3AFF-A101-82025520EBD6"><apiname>RPositioner::Open()</apiname></xref> and makes its first position update request by calling <xref href="GUID-1EAEB7EF-0AC7-37C7-B35F-C9B780FFC575.dita#GUID-1EAEB7EF-0AC7-37C7-B35F-C9B780FFC575/GUID-321F6046-3551-3ACE-B0A3-26D51FAEB477"><apiname>RPositioner::NotifyPositionUpdate()</apiname></xref>. </p> <p>As shown in figure 1 the location request from each client causes a call to <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> to be made on the SUPL Protocol Module by the LBS subsystem. </p> <p>For the first request (from Client 1 in figure 1) the SUPL Protocol Module requests and receives assistance data from the network and this is used by the LBS subsystem (by an A-GPS Positioning Module) to begin to calculate a position. </p> <p>A second location request (from Client 2 in figure 1) causes another call to <codeph>RequestSelfLocation()</codeph> to be made on the SUPL Protocol Module, but it is not processed if the first request is still being processed. The SUPL Protocol Module rejects the request by simply calling <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> on the LBS subsystem with status <codeph>KErrServerBusy.</codeph> </p> <p>If the request is rejected by the SUPL Protocol Module the LBS Location Server completes ALL client application requests and sets their status to <codeph>KErrServerBusy</codeph>. In figure 1 both Client 1 and Client 2 receive status <codeph>KErrServerBusy</codeph>. </p> <fig id="GUID-DCD0CDE1-EA45-53D3-A2DE-F38786408881"><title>
+ Figure 1. Processing of two SET initiated requests from
+ different clients.
+ </title> <image href="GUID-09EFBBDE-780D-5A16-8E3B-78DEFF1F8938_d0e443364_href.png" placement="inline"/></fig> <p> <i>Making a location request after receiving KErrServerBusy</i> </p> <p>A client that receives the error <codeph>KErrServerBusy</codeph> will usually want to make the request again to obtain a position update. </p> <p>In many cases all that is required is to make another call to <xref href="GUID-1EAEB7EF-0AC7-37C7-B35F-C9B780FFC575.dita#GUID-1EAEB7EF-0AC7-37C7-B35F-C9B780FFC575/GUID-321F6046-3551-3ACE-B0A3-26D51FAEB477"><apiname>RPositioner::NotifyPositionUpdate()</apiname></xref>. The LBS subsystem 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> on the SUPL Protocol Module with the new client flag set to false. </p> <p>When the new client flag is false the Protocol Module simply completes the request by calling <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> with return code<codeph> KErrNone</codeph> and does not request assistance data from the network. </p> <p>The behaviour that a client observes depends on whether LBS previously received assistance data that allowed the A-GPS Positioning Module to calculate a position. There are two possibilities: </p> <ul><li id="GUID-5B33A0DE-6B61-5E3C-A8C7-805243D662DB"><p>The A-GPS Positioning Module has calculated a position and has returned it to LBS. </p> <p>This position can be returned to the client. </p> </li> <li id="GUID-6777B793-077B-5E2E-8D4D-82E5133A975C"><p>The A-GPS Positioning Module has not calculated a position because it has no assistance data. </p> <p>A position cannot be returned to the client and the request may time out (if the client specified a request timeout). </p> <p>To get assistance data from the network the client must be identified to the SUPL Protocol Module as a new client. To do this a client calls <xref href="GUID-1EAEB7EF-0AC7-37C7-B35F-C9B780FFC575.dita#GUID-1EAEB7EF-0AC7-37C7-B35F-C9B780FFC575/GUID-DE09BADB-6D90-3995-A893-F949F9C37A2B"><apiname>RPositioner::Close()</apiname></xref> and <xref href="GUID-1EAEB7EF-0AC7-37C7-B35F-C9B780FFC575.dita#GUID-1EAEB7EF-0AC7-37C7-B35F-C9B780FFC575/GUID-AF3D9B5F-8025-3AFF-A101-82025520EBD6"><apiname>RPositioner::Open()</apiname></xref> before calling <xref href="GUID-1EAEB7EF-0AC7-37C7-B35F-C9B780FFC575.dita#GUID-1EAEB7EF-0AC7-37C7-B35F-C9B780FFC575/GUID-321F6046-3551-3ACE-B0A3-26D51FAEB477"><apiname>RPositioner::NotifyPositionUpdate()</apiname></xref>. </p> </li> </ul> <p>Note that in general a second SET initiated request made by a new client soon after the successful completion of a different new client request may also complete with status <codeph>KErrServerBusy</codeph> because the SUPL Protocol Module has not yet received a <codeph>SUPL END</codeph> message from the network. </p> </li> <li id="GUID-762747F6-FBA7-5486-A43D-DEA978D7E9DB"><p>Network initiated location request followed by a second network initiated location request (two MT-LRs). </p> <p>The second location request is not processed. </p> </li> <li id="GUID-A161782D-7716-5241-BE3C-D2691A8B3F80"><p>SET initiated location request followed by a network initiated location request (MO-LR then MT-LR). </p> <p>The SET initiated location request is completed. The second location request is not processed. </p> </li> <li id="GUID-87F72D74-524B-5D51-861E-F7CBEF31E872"><p>Network initiated location request followed by a SET initiated location request (MT-LR then MO-LR). </p> <p>The outstanding network initiated location request (MT-LR) is cancelled, and the SET initiated location request (MO-LR) is completed. </p> </li> </ul> </section> <section id="GUID-89156A75-D752-51FE-9949-DF080B4C8EB0"><title>See also</title> <p><xref href="GUID-CC3454B1-21DA-542E-8949-52C30755AC77.dita">SUPL Protocol Module Overview</xref> </p> <p><xref href="GUID-E7DD9CFD-F477-5D25-BC10-BEBFB1022F7E.dita">SUPL Push API</xref> </p> <p><xref href="GUID-FE4794F8-2519-5AC2-BCF7-168ECA6645EA.dita">Host Settings API</xref> </p> <p><xref href="GUID-DF4A992B-E03B-57F5-9D5B-1C112FC16544.dita">Example for Creating a Default Certificate Store</xref> </p> </section> <section id="GUID-A3C8C7E8-981F-5CF1-A69C-0C1110951254"><title>References</title> <p>[1] <xref scope="external" href="http://www.openmobilealliance.org">Open Mobile Alliance</xref> Secure User Plane Location (SUPL) Architecture OMA-AD-SUPL-V1_0-20070615-A </p> <p>[2] <xref scope="external" href="http://www.openmobilealliance.org">Open Mobile Alliance</xref> Enabler Test Specification for SUPL OMA-ETS-SUPL-V1_0-20070116-C </p> <p>[3] <xref scope="external" href="http://www.openmobilealliance.org">Open Mobile Alliance</xref> Mobile Location Protocol OMA-LIF-MLP-V3_1-20040316-C </p> </section> </conbody></concept>
\ No newline at end of file