Host Settings API

Introduction

This document describes the SUPL Protocol Module (SPM) Host Settings API. Host settings are properties that describe the SUPL Location Platforms (SLPs) with which a mobile device (the SUPL Enabled Terminal or SET) may communicate.

Host settings define the SLPs with which a mobile device may communicate. Host Settings are stored in a central repository. Settings include the following:

• The SLP hostname and port.

• The network connection point that must be used to connect with the SLP.

• The modes of data encryption and authentication that can be used between the SET and the SLP.

• The default SLP, which is used for SET initiated location requests (MO-LR).

• Whether host settings were set by a licensee application or over the network.

The Host Settings API is used by three types of client:

• The SUPL Protocol Module.

  The SPM reads host settings using the Host Settings API. The SPM requires the host settings to initiate a connection with an SLP.

• SUPL host settings Device Provisioning plug-ins.

  Symbian provides a Device Management plug-in and a Client Provisioning plug-in that allow SUPL host settings to be provisioned over the air or by Client Provisioning files. The plug-ins use the Host Settings API to set host settings which can then be used by the SUPL Protocol Module.

• A licensee host settings application.

  A Symbian licensee can write an application (or modify any existing LBS settings application) to allow mobile device users to configure host settings manually.

Libraries

The Host Settings API is packaged in lbshostsettings.dll. Clients link to lbshostsettings.lib.

Capabilities

The Host Settings API uses the central repository as the host settings data store implementation. A client application is required to have the capabilities specified in a host settings repository initialisation file which has a section [platsec] as shown below:

[platsec]
cap_rd=AlwaysPass 
cap_wr=WriteDeviceData

Host settings repository initialisation files should have a write capability of WriteDeviceData to prevent unauthorised applications from modifying host settings. A licensee application to manage host settings will require the WriteDeviceData capability.

See SUPL Protocol Module Quick Start for more details about how to pre-configure host settings on a device.

Host settings repository initialisation file

Host Settings can be pre-defined on a mobile device using a central repository initialisation file.

Full details of the format of this initialisation file can be found in the document SUPL Protocol Module Quick Start.

Creating a host settings application

Licensees can give device users the ability to make changes to host settings. Device users may want to change host settings in certain circumstances such as when changing network providers. Licensees can create a UI settings application to allow device users to configure host settings.

When creating a settings application, licensees need to consider which host settings users should be allowed to change. Device users may, for example, want to specify the default SLP, but they should never need to change the security mode specified for host settings.

An application for changing host settings needs to call the Host Settings API to set the SUPL server host settings that are used by the SUPL Protocol Module. Such an application requires the WriteDeviceData capability.

Device provisioning host settings plug-ins

SUPL Device Management objects can use the Host Settings API to set SLP settings remotely or locally:

• Host Settings Device Management Adapter plug-in

  The Symbian Device Management (DM) Framework provides the infrastructure to provision mobile device settings remotely using an OMA Device Management message.

  As part of its support for SUPL, Symbian supplies a Host Settings DM Adapter plug-in, packaged in dmsupladapter.dll. The plug-in manages a DM Management Object for SLP host settings and calls the Host Settings API to set the host settings.

• Host Settings Client Provisioning Adapter plug-in

  The Symbian Client Provisioning (CP) Framework provides the infrastructure to provision mobile device settings either remotely or locally through a SIM card.

  As part of its support for SUPL, Symbian supplies a Host Settings Client Provisioning Adapter plug-in, packaged in cpsupladapter.dll. The plug-in calls the Host Settings API to set the SUPL server host settings that are used by the SUPL Protocol Module.