diff -r 4816d766a08a -r f345bda72bc4 Symbian3/PDK/Source/GUID-FE4794F8-2519-5AC2-BCF7-168ECA6645EA.dita --- a/Symbian3/PDK/Source/GUID-FE4794F8-2519-5AC2-BCF7-168ECA6645EA.dita Tue Mar 30 11:42:04 2010 +0100 +++ b/Symbian3/PDK/Source/GUID-FE4794F8-2519-5AC2-BCF7-168ECA6645EA.dita Tue Mar 30 11:56:28 2010 +0100 @@ -1,21 +1,164 @@ - - - - - -Host Settings APIThe Host Settings API is used by the SUPL Protocol Module to get the host settings. It is also used by a device creator's application or device provisioning plug-in to set host settings.

Note: The Host Settings API is deprecated.

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.

API description

The Host Settings API enables clients to get and set SUPL Location Platform host settings. The Host Settings API provides a set of methods to create, modify and delete host settings in a host settings data store (implemented as a central repository).

Figure 1 shows the classes and types of the Host Settings API.

- Figure 1. Classes and types of the Host Settings API. -

The following table lists the main classes and types of the Host Settings API (some simple typedefs are excluded).

Class name Description Header file

CLbsHostSettingsStore

The class used to create, modify and delete SLP host settings in a host settings store.

lbshostsettings.h

MLbsHostSettingsStoreObserver

The observer class used to monitor changes to host settings.

By specifying an observer when creating CLbsHostSettingsStore, an API client receives notifications whenever the specified store changes.

MLbsHostSettingsStoreObserver::LbsHostSettingsUpdated() is called to notify a client that the host settings have changed.

Note that an API client will not receive notifications of settings updates it makes itself.

lbshostsettings.h

TLbsHostSettingsBase

The base class for host settings, extended by TLbsHostSettingsSupl. TLbsHostSettingsBase contains host settings properties that are not SUPL specific.

lbshostsettingsclasstypes.h

TLbsHostSettingsSupl

The class that contains host settings properties that are specific to SUPL. Each instance of TLbsHostSettingsSupl describes the host settings for a single SLP.

lbshostsettingsclasstypes.h

TLbsHostSettingsSupl::_TAuthModes

The enumerated type that specifies the authentication and encryption methods that can be used with an SLP. To specify a combination of these values, a bitmask of type TLbsHostSettingsSupl::TAuthModes is used.

lbshostsettingsclasstypes.h

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.

Host - Settings API Tutorial SUPL Protocol - Module Overview SUPL Protocol - Module Quick Start \ No newline at end of file + + + + + +Host +Settings APIThe Host Settings API is used by the SUPL Protocol Module to get +the host settings. It is also used by a device creator's application or device +provisioning plug-in to set host settings. +

Note: From Symbian^3 the SUPL Protocol Module is deprecated. For the preferred +way of using SUPL see SUPL +Proxy Protocol Module.

+
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.

    • +
+API description

The Host Settings API enables clients +to get and set SUPL Location Platform host settings. The Host Settings API +provides a set of methods to create, modify and delete host settings in a +host settings data store (implemented as a central repository).

Figure +1 shows the classes and types of the Host Settings API.

+ Figure 1. Classes and types of the Host Settings API. + + +

The following table lists the main classes and types of the Host +Settings API (some simple typedefs are excluded).

+ + + +Class name +Description +Header file + + + + +

CLbsHostSettingsStore

+

The class used to create, modify and delete SLP host settings in +a host settings store.

+

lbshostsettings.h

+ + +

MLbsHostSettingsStoreObserver

+

The observer class used to monitor changes to host settings.

By +specifying an observer when creating CLbsHostSettingsStore, +an API client receives notifications whenever the specified store changes.

MLbsHostSettingsStoreObserver::LbsHostSettingsUpdated() is called to notify a client that the host settings have changed.

Note +that an API client will not receive notifications of settings updates it makes +itself.

+

lbshostsettings.h

+ + +

TLbsHostSettingsBase

+

The base class for host settings, extended by TLbsHostSettingsSupl. TLbsHostSettingsBase contains +host settings properties that are not SUPL specific.

+

lbshostsettingsclasstypes.h

+ + +

TLbsHostSettingsSupl

+

The class that contains host settings properties that are specific +to SUPL. Each instance of TLbsHostSettingsSupl describes +the host settings for a single SLP.

+

lbshostsettingsclasstypes.h

+ + +

TLbsHostSettingsSupl::_TAuthModes

+

The enumerated type that specifies the authentication and encryption +methods that can be used with an SLP. To specify a combination of these values, +a bitmask of type TLbsHostSettingsSupl::TAuthModes is used.

+

lbshostsettingsclasstypes.h

+ + + +
 +
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.

    • +
+ +Host + Settings API Tutorial +SUPL Protocol + Module Overview +SUPL Protocol + Module Quick Start + \ No newline at end of file