SUPL Protocol Module Quick Start
This document describes how a device creator starts working with the SUPL Protocol Module.
Note: From Symbian^3 the SUPL Protocol Module is deprecated. For the preferred way of using SUPL see SUPL Proxy Protocol Module.
Purpose
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.
Introduction
The SUPL Protocol Module (SPM) is a reference module provided by Symbian and is described in SUPL Protocol Module Overview.
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.
Mandatory tasks
Obtain and set up a SUPL Location Platform
The SUPL Protocol Module Overview and the SUPL specification [1] describe the SUPL Location Platform, the server side platform that supports the SUPL standard.
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.
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.
The details of setting up and configuring an SLP are specific to the platform used and are outside of the scope of this document.
See Test the SUPL Protocol Module for information about how the SPM was tested by Symbian with a commercial SLP.
The SUPL Protocol Module is included as part of the Symbian LBS subsystem distribution.
See SUPL Protocol Module Overview for more information on the components of the SUPL Protocol Module.
Configure an A-GPS Integration Module for LBS
A GPS or Assisted GPS (A-GPS) Integration Module is required to integrate the LBS subsystem with GPS hardware.
A-GPS Location Data Source API 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.
The section GPS/A-GPS Integration Module of the LBS integration and configuration guide describes how to configure an Integration Module's module.ini configuration file so that LBS recognises and uses an Integration Module.
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.
Minimising assistance data requests
The LBS subsystem may be configured to use the SUPL Protocol Module when a user is roaming as described in Configure the LBS administration settings for SUPL. 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.
Configure the LBS administration settings for SUPL
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:
KSettingHomeProtocolModule specifies the implementation UID of the Network Protocol Module ECOM plug-in that is used when the device is in the home network.
KSettingRoamingProtocolModule specifies the implementation UID of the Network Protocol Module ECOM plug-in that is used when the device is roaming.
KLbsProtocolModuleLoading specifies the loading strategy for Network Protocol Modules. See the entry in LBS administration service 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.
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 RMobilePhone::GetNetworkRegistrationStatus() and RMobilePhone::NotifyNetworkRegistrationStatusChange() to report the registration status of the device. LBS calls GetNetworkRegistrationStatus() on startup to get the initial network registration status. It also subscribes for registration status changes by calling NotifyNetworkRegistrationStatusChange(). See Implement ETel TSY Enhancements for more information about changes that are required in a licensee's ETel TSY.
The administration settings are read by LBS on subsystem start-up. It is recommended that they are set in the LBS administration repository initialisation file.
For LBS to load the reference SUPL Protocol Module, the administration settings values must be set to the implementation_uid specified in the ECOM resource file suplprotocolmodule.rss, which is shown below:
// 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; } }; } }; }
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:
#KSettingHomeProtocolModule. 0x0000000E int 0x10285A9D #KSettingRoamingProtocolModule. 0x0000000F int 0x10285A9D ... #KLbsProtocolModuleLoading #Load KSettingHomeProtocolModule or KSettingRoamingProtocolModule based on network registration status 0x00000018 int 1
A default central repository initialisation source file 1028224B.txt can be found in the LBS source tree at <LBS_ROOT>\LbsAdmin\data. Licensees can modify the source file 1028224B.txt and rebuild it to configure their LBS subsystem. The directory <LBS_ROOT>\LbsAdmin\group contains a make file createlbsadminrep.mk that creates the binary file from the text source. This file is exported to \epoc32\data\z\private\10202BE9\1028224B.cre.
Note that the default initialisation file that ships with LBS is not configured to use the Symbian reference SUPL Protocol Module. 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.
Configure the SUPL Location Platform host settings
The Host Settings API 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.
Host Settings can be configured in one or more of the following ways:
Over the air from a Device Management server (Symbian provide a SUPL Host Settings Device Management plug-in).
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).
By a locally installed client application such as an "LBS settings application" that a licensee may have already created to configure other LBS settings.
By installation of a host settings central repository initialisation file.
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.
To begin testing with the SUPL Protocol Module, the simplest approach is to create a host settings initialisation file.
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 Host Settings API.
# 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
The following are the most important points about the values in this file:
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 0x10000000 to 0xB0000000. For SLP Host B the settings keys range from 0x10000001 to 0xB0000001.
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.
The last part of the key specifies the SLP host for which the settings apply: 0x10000000 is the key for the settings creator ID for the SLP Host A settings and 0x10000001 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 0x10000002 to 0xB0000002.
Host Settings API describes how a program can read and create host settings.
The value of EHostAddress must be set to the IP number or domain name of the SLP host server.
The value of EHostName must be set to a name to identify the server (for example in a settings application that allows users to select the SLP).
The values of EAuthMolr and EAuthMtlr describe the authentication and encryption method(s) that are allowed for SET initiated location requests (MO-LR) and network initiated location requests (MT-LR).
Several different levels of authentication and encryption are defined by the Host Settings API enumeration TLbsHostSettingsSupl::_TAuthModes. The values of the enumeration are described in the table shown below. Note that the value in the initialisation file is decimal:
Meaning TLbsHostSettingsSupl::_TAuthModes Numeric value Do not use authentication/encryption
EAuthNone
1
Use TLS
EAuthTls
2
Use ACA + TLS
EAuthAcaTls
4
Use PSK + TLS
EAuthPskTls
8
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.
For example, to specify that either ACA + TLS or PSK + TLS are allowed for SET initiated location requests, EAuthMolr must be set to EAuthAcaTls | EAuthPskTls = 12.
Note that the SUPL specification [1] mandates the use of ACA or PSK with TLS, but turning off authentication and encryption can be useful for testing.
Installing a host settings initialisation file
A host settings initialisation text file can be converted to a binary file using the make file in <LBS_ROOT>\LbsSuplProtocolModule\HostSettingsAPI\group\createlbssuplstore.mk, where <LBS_ROOT> is the root directory of the LBS source tree.
The source file is copied to \epoc32\winscw\c\private\10202be9\10285AA8.cre on the emulator and to z:\private\10202be9\10285AA8.cre on hardware.
Rules for host settings selection
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).
Rules for SET initiated location requests (MO-LR)
If a default host is specified, use it for MO-LR.
The example host settings file shown above contains the following lines:
# default SLP host 0x00000002 int 1
The entry specifies that the host setting keys beginning at 0x10000001 must be used for MO-LR because 1 is the last digit of 0x10000001. This is the host specified as SLP Host 2 in the example host settings file shown above.
If a default host is not specified, use the host that was most recently provisioned from the network.
A timestamp value is associated with each host settings entry as shown in the example host settings file. This key is commented as ETimestamp in the example host settings file.
A creator UID value of 0x10285AA9 is specified for host settings that were provisioned from the network. This UID is the value of KLbsHostSettingsDevProvCreatorId as defined in lbshostsettings.h.
If neither of the above rules can be used to obtain host settings, derive a host address from the IMSI as described in [1].
Rules for network initiated location requests (MT-LR)
Use the host settings that were most recently provisioned from the network.
The host settings with a creator UID value of 0x10285AA9 and the most recent timestamp are used.
If there are no host settings with a creator UID of 0x10285AA9 derive a host address from the IMSI as described in [1].
Implement ETel TSY enhancements
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:
The mobile network cell ID
The SUPL Protocol Module uses the method RMobilePhone::GetCellInfo() to get a cell info object of type TMobilePhoneCellInfoV9, which contains the cell ID as specified in [2] and [3]. The cell ID is passed from the SET to the SLP as part of a SUPL POS INIT message and is used to obtain a cell-based position and/or GPS assistance data.
To use cell-based positioning or request assistance data, the ETel TSY must be implemented to return the cell ID.
Timing advance information for enhanced cell-based positioning
A TMobilePhoneCellInfov9 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 SUPL POS INIT message and allows a more accurate cell-based position to be calculated.
The network registration status
On startup, LBS gets the current network registration status of the device by calling RMobilePhone::GetNetworkRegistrationStatus(). LBS receives notification of changes to the mobile device's network registration status by calling RMobilePhone::NotifyNetworkRegistrationStatusChange(). The ETel TSY must be implemented to return the network registration status for both of these methods.
LBS loads one or more Network Protocol Modules based on the settings specified in the LBS administration settings.
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.
The International Mobile Subscriber Identity (IMSI)
[1] 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.
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 RMobilePhone::GetSubscriberId() 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.
Build a ROM image to include the SUPL Protocol Module
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 .exe and .dll files that are delivered to licensees as part of an LBS distribution.
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.
The following SUPL macros are checked in the LBS .iby files:
SYMBIAN_INCLUDE_LOCATION_SUPLv10 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.
SYMBIAN_EXCLUDE_LOCATION_SUPLv10_SMS excludes the test SMS Trigger plug-in from ROM.
Note that the SMS Trigger plug-in is a test component for licensees to test SUPL INIT messages sent via Mobile Terminated SMS.
SYMBIAN_EXCLUDE_LOCATION_SUPLv10_WAP excludes the WAP Push plug-in from ROM.
To build a ROM image to include the SUPL Protocol Module, a licensee uses a command as shown below:
buildrom lbs.oby -DSYMBIAN_INCLUDE_LOCATION_SUPLv10
where lbs.oby contains the following files:
#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
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 [2] have also been used to test the SPM.
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.
TEF is invoked by the command testexecute.exe <FullFilePath\xxx.script> which can be invoked from eshell in the emulator. testexecute.exe interprets the script commands within the .script file passed to it as an argument.
SUPL TEF test suites
The TEF test suites that were used by Symbian to test the SPM can be found in the SUPL test directory <LBS_ROOT>\test\testproduct\supl where <LBS_ROOT> 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.
A number of sub-directories for different categories of tests exist within this SUPL test directory:
.\molr\real contains tests for SET initiated location requests.
The TEF script file for these tests can be found at .\molr\real\scripts\suplmolrrealtest.script.
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.
.\mtlr\real contains tests for network initiated location requests.
.\omaconformance contains OMA defined tests as described in [2].
MLP Module
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.
OMA defines the Mobile Location Protocol (MLP) specification [3] 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.
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 <LBS_ROOT>\test\testproduct\supl\tools\mlpmodule. The MLP module is used by the Symbian SUPL TEF tests to drive SUPL servers for testing. The MLP is packaged in lbsmlpmodule.dll. The MLP module interface is defined in lbsmlpmodule.h.
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.
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 SendParseLocRequestFromFileL() can be used to read an SLIR document (which must conform to the SLIR DTD [3]) from a file, send the contents to an SLP and parse the returned SLIA to extract a returned handset number and reference position.
If the contents of the SLIR are correctly defined, the SLP will respond by sending a SUPL INIT message to the handset number (MSID) specified in the SLIR.
The example code shown below outlines how to use the MLP module to start a SUPL INIT.
#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);
SUPL Protocol Module development logging
The LBS subsystem contains a logging component in lbspartnercommon.dll. The logging component is used by many LBS subsystem components to write logs to a file. The source file <LBS_ROOT>\LbsPartnerCommon\inc\lbsdevloggermacros.h contains logging macro definitions wrapped in the following #ifdef statement:
#if defined(ENABLE_LBS_DEV_LOGGER) && (defined(_DEBUG)||defined(__WINS__)) // LBS logging macro definitions - details omitted #endif
The SUPL Protocol Module contains its own logging component in supldevlogger.dll. The source file <LBS_ROOT>\LbsSuplProtocolModule\SuplDevLogger\inc\supldevloggermacros.h contains the logging macro definitions wrapped in the following #ifdef statement:
#if defined(ENABLE_SUPL_DEV_LOGGER) && (defined(_DEBUG)||defined(__WINS__)) // SUPL logging macro definitions - details omitted #endif
The logging macros are used for debugging only and are not part of a published interface.
For an emulator build, log messages from the SUPL Protocol Module and other LBS components are written to \epoc32\winscw\c\logs\lbs\lbs.txt. Logging is also enabled for hardware debug builds.
The macro ENABLE_LBS_DEV_LOGGER is defined in several LBS subsystem MMP files. The macro ENABLE_SUPL_DEV_LOGGER 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 #if condition in lbsdevloggermacros.h and supldevloggermacros.h and recompile the LBS codebase to obtain logging messages for hardware release builds. Development logging should not be permanently enabled for release builds.
Optional tasks
Create an application for managing SLP host settings
Configure the SUPL Location Platform host settings describes how to configure SLP host settings using a central repository initialisation file.
Symbian licensees may have previously created a settings application for configuring LBS subsystem behaviour at runtime using the LBS Administration API. Such an application can be extended to allow users to configure SLP host settings using the Host Settings API.
This is an optional task because it is not necessary to give device users any visibility of the host settings or control over them.
See Host Settings API for details of how to configure the host settings at runtime.
Create a handler for SUPL INIT messages received via SMS Trigger
The SUPL Protocol Module Overview describes the WAP Push plug-in and test SMS Trigger plug-in that can be used to process SUPL INIT messages to begin network initiated location requests (MT-LRs).
The WAP Push plug-in can be used to receive SUPL INIT messages sent using WAP Push. The plug-in is packaged in lbssuplwappush.dll and is automatically built into an LBS SUPL ROM image unless it is deliberately excluded. The WAP Push plug-in is loaded by the WAP Push Framework.
The SMS Trigger plug-in can be used to receive SUPL INIT messages sent using SMS. The SMS Trigger plug-in is a Symbian test component. The plug-in is packaged in lbssuplsmstrigger.dll and is automatically built into an LBS SUPL ROM image unless it is deliberately excluded. The SMS Trigger plug-in is loaded by the Symbian messaging Watcher Framework.
It is possible for Symbian licensees to build their own handler for processing SUPL INIT messages received via SMS. The only requirement for any licensee-implemented SUPL INIT message handler is that it uses the SUPL Push API to send the SUPL INIT message into the SUPL Protocol Module.
The source code of the test Symbian SUPL SMS Trigger plug-in can be found in the LBS source code tree at <LBS_ROOT>/LbsSuplProtocolModule/SuplSmsTrigger/.
The source code of the WAP Push plug-in can be found in the LBS source code tree at <LBS_ROOT>/LbsSuplProtocolModule/SuplWapPush/.
Provision SLP root certificate for TLS
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 [1].
Certificate stores are managed using the Symbian certtool application. The tool is used to import certificates for use in the Symbian emulator and allows them to be exported to ROM.
The document Example for Creating a Default Certificate Store describes how to use certtool to create certificate stores for the Symbian emulator and a ROM. Briefly the steps required are as follows:
Obtain the certificate that the SLP uses for TLS.
The SLP vendor, or the network operator that owns the SLP should be able to provide a certificate.
Import the certificate into a Symbian certificate store.
The certificate is imported using the certtool -import command as follows:
certtool -label <label-name> –import <certificate-file>
where label-name is a name used to identify the certificate and <certificate-file> is the filename of the certificate provided by the SLP vendor.
Trust the SLP vendor certificate for use with TLS.
The certificate is trusted for use with TLS using the certtool -setapps -apps command as follows:
certtool –setapps –apps SSL/TLS <label-name>
where label-name is the label given to the certificate when it was imported into the certificate store.
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 Configure the SUPL Location Platform host settings.
Create a plug-in to obtain a pre-shared key for PSK-TLS
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.
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.
Alternative Client Authentication (ACA-TLS) is currently supported by the SUPL Protocol Module.
Configurable conflict control is not yet suported by the SUPL Protocol Module.
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:
SET initiated location request followed by a second SET initiated location request from a new client (two MO-LRs).
Figure 1 illustrates the discussion that follows, which assumes the LBS subsystem is configured to use terminal based GPS.
A new client is one that opens a subsession by calling RPositioner::Open() and makes its first position update request by calling RPositioner::NotifyPositionUpdate().
As shown in figure 1 the location request from each client causes a call to CLbsNetworkProtocolBase::RequestSelfLocation() to be made on the SUPL Protocol Module by the LBS subsystem.
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.
A second location request (from Client 2 in figure 1) causes another call to RequestSelfLocation() 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 MLbsNetworkProtocolObserver::ProcessSessionComplete() on the LBS subsystem with status KErrServerBusy.
If the request is rejected by the SUPL Protocol Module the LBS Location Server completes ALL client application requests and sets their status to KErrServerBusy. In figure 1 both Client 1 and Client 2 receive status KErrServerBusy.
Making a location request after receiving KErrServerBusy
A client that receives the error KErrServerBusy will usually want to make the request again to obtain a position update.
In many cases all that is required is to make another call to RPositioner::NotifyPositionUpdate(). The LBS subsystem calls CLbsNetworkProtocolBase::RequestSelfLocation() on the SUPL Protocol Module with the new client flag set to false.
When the new client flag is false the Protocol Module simply completes the request by calling MLbsNetworkProtocolObserver::ProcessSessionComplete() with return code KErrNone and does not request assistance data from the network.
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:
The A-GPS Positioning Module has calculated a position and has returned it to LBS.
This position can be returned to the client.
The A-GPS Positioning Module has not calculated a position because it has no assistance data.
A position cannot be returned to the client and the request may time out (if the client specified a request timeout).
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 RPositioner::Close() and RPositioner::Open() before calling RPositioner::NotifyPositionUpdate().
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 KErrServerBusy because the SUPL Protocol Module has not yet received a SUPL END message from the network.
Network initiated location request followed by a second network initiated location request (two MT-LRs).
The second location request is not processed.
SET initiated location request followed by a network initiated location request (MO-LR then MT-LR).
The SET initiated location request is completed. The second location request is not processed.
Network initiated location request followed by a SET initiated location request (MT-LR then MO-LR).
The outstanding network initiated location request (MT-LR) is cancelled, and the SET initiated location request (MO-LR) is completed.
References
[1] Open Mobile Alliance Secure User Plane Location (SUPL) Architecture OMA-AD-SUPL-V1_0-20070615-A
[2] Open Mobile Alliance Enabler Test Specification for SUPL OMA-ETS-SUPL-V1_0-20070116-C
[3] Open Mobile Alliance Mobile Location Protocol OMA-LIF-MLP-V3_1-20040316-C
Copyright ©2010 Nokia Corporation and/or its subsidiary(-ies).
All rights
reserved. Unless otherwise stated, these materials are provided under the terms of the Eclipse Public License
v1.0.