<?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>&lt;LBS_ROOT&gt;\LbsAdmin\data</filepath>. Licensees can modify

the source file <filepath>1028224B.txt</filepath> and rebuild it to configure

their LBS subsystem. The directory <filepath>&lt;LBS_ROOT&gt;\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>&lt;LBS_ROOT&gt;\LbsSuplProtocolModule\HostSettingsAPI\group\createlbssuplstore.mk</filepath>,

where <filepath>&lt;LBS_ROOT&gt;</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              &lt;FullFilePath\xxx.script&gt;</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>&lt;LBS_ROOT&gt;\test\testproduct\supl</filepath> where <filepath>&lt;LBS_ROOT&gt;</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>&lt;LBS_ROOT&gt;\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