Week 28 contribution of PDK documentation content. See release notes for details. Fixes bugs Bug 1897, Bug 344, Bug 2681, Bug 463, Bug 1522.
<?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 id="GUID-91F95D0C-E4CF-510E-B280-E27F89274ACE" xml:lang="en"><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: From Symbian^3 the SUPL Protocol Module is deprecated. For the preferred
way of using SUPL see <xref href="GUID-1F7F543A-8A9C-4460-BDB1-A6866E9DF0B9.dita">SUPL
Proxy Protocol Module</xref>. </p>
<section id="GUID-D1488297-52A2-4A72-8A15-975C744EC34B"><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 href="http://www.openmobilealliance.org" scope="external">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_d0e459740_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 href="http://www.openmobilealliance.org" scope="external">Open Mobile Alliance</xref> Secure
User Plane Location (SUPL) Architecture OMA-AD-SUPL-V1_0-20070615-A </p> <p>[2] <xref href="http://www.openmobilealliance.org" scope="external">Open Mobile Alliance</xref> Enabler
Test Specification for SUPL OMA-ETS-SUPL-V1_0-20070116-C </p> <p>[3] <xref href="http://www.openmobilealliance.org" scope="external">Open Mobile Alliance</xref> Mobile
Location Protocol OMA-LIF-MLP-V3_1-20040316-C </p> </section>
</conbody></concept>