<?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-FE4794F8-2519-5AC2-BCF7-168ECA6645EA" xml:lang="en"><title>Host

Settings API</title><shortdesc>The 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. </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-DB6A4D4C-8F70-467B-ADD1-1E43C1BB2AC0"><title>Introduction</title> <p>This document describes the <xref href="GUID-CC3454B1-21DA-542E-8949-52C30755AC77.dita">SUPL Protocol Module</xref> (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. </p> <p>Host settings define the SLPs with which a mobile

device may communicate. Host Settings are stored in a central repository.

Settings include the following: </p> <ul>

<li id="GUID-4FE58903-4CF4-5242-959A-C656225F55A9"><p>The SLP hostname and

port. </p> </li>

<li id="GUID-102D4CCF-8032-5849-8158-375D3ECDBD61"><p>The network connection

point that must be used to connect with the SLP. </p> </li>

<li id="GUID-BFCF0F40-CA24-5C1C-A8DD-08199591D98D"><p>The modes of data encryption

and authentication that can be used between the SET and the SLP. </p> </li>

<li id="GUID-0082CAB8-7C64-5368-9E50-D14B67C7759E"><p>The default SLP, which

is used for SET initiated location requests (MO-LR). </p> </li>

<li id="GUID-43F1081D-A31A-5CC6-87BD-5BF712120B3E"><p>Whether host settings

were set by a licensee application or over the network. </p> </li>

</ul> <p>The Host Settings API is used by three types of client: </p> <ul>

<li id="GUID-A3918B0A-2E40-5E79-B376-2343426C15DA"><p>The SUPL Protocol Module. </p> <p>The

SPM reads host settings using the Host Settings API. The SPM requires the

host settings to initiate a connection with an SLP. </p> </li>

<li id="GUID-7C6396E9-10B2-5A5E-A907-6953E4533C9C"><p>SUPL host settings Device

Provisioning plug-ins. </p> <p>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. </p> </li>

<li id="GUID-F770803F-4905-5007-8660-4F5545A44216"><p>A licensee host settings

application. </p> <p>A Symbian licensee can write an application (or modify

any existing LBS settings application) to allow mobile device users to configure

host settings manually. </p> </li>

</ul> </section>

<example><title>API description</title> <p>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). </p> <p>Figure

1 shows the classes and types of the Host Settings API. </p> <fig id="GUID-97FD34C6-253C-5BCD-B29C-D5F9CB552068">

<title>              Figure 1. Classes and types of the Host Settings API.

           </title>

<image href="GUID-8F6627A5-5DDE-5F30-86BF-CFD507DE876B_d0e466435_href.png" placement="inline"/>

</fig> <p>The following table lists the main classes and types of the Host

Settings API (some simple typedefs are excluded). </p> <table id="GUID-01C6E3E0-AE21-5476-AC82-EB11122ACF60">

<tgroup cols="3"><colspec colname="col0"/><colspec colname="col1"/><colspec colname="col2"/>

<thead>

<row>

<entry>Class name</entry>

<entry>Description</entry>

<entry>Header file</entry>

</row>

</thead>

<tbody>

<row>

<entry><p> <xref href="GUID-30917438-ED01-3AFC-9964-9337761D6AB6.dita"><apiname>CLbsHostSettingsStore</apiname></xref>  </p> </entry>

<entry><p>The class used to create, modify and delete SLP host settings in

a host settings store. </p> </entry>

<entry><p> <filepath> lbshostsettings.h</filepath>  </p> </entry>

</row>

<row>

<entry><p> <xref href="GUID-9CBC68BB-3D5A-3781-AA33-D9177435748F.dita"><apiname>MLbsHostSettingsStoreObserver</apiname></xref>  </p> </entry>

<entry><p>The observer class used to monitor changes to host settings. </p> <p>By

specifying an observer when creating <codeph>CLbsHostSettingsStore</codeph>,

an API client receives notifications whenever the specified store changes. </p> <p> <codeph>MLbsHostSettingsStoreObserver::LbsHostSettingsUpdated()</codeph> is called to notify a client that the host settings have changed. </p> <p>Note

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

itself. </p> </entry>

<entry><p> <filepath> lbshostsettings.h</filepath>  </p> </entry>

</row>

<row>

<entry><p> <xref href="GUID-20BC64CE-574C-3B25-97D9-45C7D6DC5D4A.dita"><apiname>TLbsHostSettingsBase</apiname></xref>  </p> </entry>

<entry><p>The base class for host settings, extended by <xref href="GUID-5B492B69-19D2-38B8-946F-FD1155513F9F.dita"><apiname>TLbsHostSettingsSupl</apiname></xref>. <codeph>TLbsHostSettingsBase</codeph> contains

host settings properties that are not SUPL specific. </p> </entry>

<entry><p> <filepath>lbshostsettingsclasstypes.h</filepath>  </p> </entry>

</row>

<row>

<entry><p> <xref href="GUID-5B492B69-19D2-38B8-946F-FD1155513F9F.dita"><apiname>TLbsHostSettingsSupl</apiname></xref>  </p> </entry>

<entry><p>The class that contains host settings properties that are specific

to SUPL. Each instance of <codeph>TLbsHostSettingsSupl</codeph> describes

the host settings for a single SLP. </p> </entry>

<entry><p> <filepath> lbshostsettingsclasstypes.h</filepath>  </p> </entry>

</row>

<row>

<entry><p> <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>  </p> </entry>

<entry><p>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 <xref href="GUID-5B492B69-19D2-38B8-946F-FD1155513F9F.dita#GUID-5B492B69-19D2-38B8-946F-FD1155513F9F/GUID-90B19A63-AAFE-3723-A907-64DA7F8CE06A"><apiname>TLbsHostSettingsSupl::TAuthModes</apiname></xref> is used. </p> </entry>

<entry><p> <filepath> lbshostsettingsclasstypes.h</filepath>  </p> </entry>

</row>

</tbody>

</tgroup>

</table> </example>

<section id="GUID-7A754DBE-D4BA-474B-A81A-403B09CCA950"><title>Libraries</title> <p>The Host Settings API is packaged in <filepath>lbshostsettings.dll</filepath>.

Clients link to <filepath>lbshostsettings.lib</filepath>. </p> </section>

<section id="GUID-034309EE-64C9-4B3C-A9EF-483DFB8DC2D1"><title>Capabilities</title> <p>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 <codeph>[platsec]</codeph> as shown

below: </p> <codeblock id="GUID-00F674AF-0A9E-55F4-916B-2BF17AF09F04" xml:space="preserve">

[platsec]

cap_rd=AlwaysPass 

cap_wr=WriteDeviceData

</codeblock> <p>Host settings repository initialisation files should have

a write capability of <codeph>WriteDeviceData</codeph> to prevent unauthorised

applications from modifying host settings. A licensee application to manage

host settings will require the <codeph>WriteDeviceData</codeph> capability. </p> <p>See <xref href="GUID-91F95D0C-E4CF-510E-B280-E27F89274ACE.dita">SUPL Protocol Module Quick

Start</xref> for more details about how to pre-configure host settings on

a device. </p> </section>

<section id="GUID-DDB5D2E0-C0EA-4F17-B2F1-390C0F4463A5"><title> Host settings repository initialisation file</title> <p>Host

Settings can be pre-defined on a mobile device using a central repository

initialisation file. </p> <p>Full details of the format of this initialisation

file can be found in the document <xref href="GUID-91F95D0C-E4CF-510E-B280-E27F89274ACE.dita">SUPL

Protocol Module Quick Start</xref>. </p> </section>

<section id="GUID-82865DD9-BD4F-4108-AA9B-CE8B3EDEDCDC"><title>Creating a host settings application</title> <p>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. </p> <p>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. </p> <p>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 <codeph>WriteDeviceData</codeph> capability. </p> </section>

<section id="GUID-C1CA6198-18C7-4D1B-8D75-E2A80560523C"><title>Device provisioning host settings plug-ins</title> <p>SUPL

Device Management objects can use the Host Settings API to set SLP settings

remotely or locally: </p> <ul>

<li id="GUID-7D50CFFE-AF53-50A6-9A30-24A417B4CC4F"><p> <b>Host Settings Device

Management Adapter plug-in</b>  </p> <p>The Symbian Device Management (DM)

Framework provides the infrastructure to provision mobile device settings

remotely using an OMA Device Management message. </p> <p>As part of its support

for SUPL, Symbian supplies a Host Settings DM Adapter plug-in, packaged in <filepath>dmsupladapter.dll</filepath>.

The plug-in manages a DM Management Object for SLP host settings and calls

the Host Settings API to set the host settings. </p> </li>

<li id="GUID-96816807-954A-5636-B255-25BB1F9E08BF"><p> <b>Host Settings Client

Provisioning Adapter plug-in</b>  </p> <p>The Symbian Client Provisioning

(CP) Framework provides the infrastructure to provision mobile device settings

either remotely or locally through a SIM card. </p> <p>As part of its support

for SUPL, Symbian supplies a Host Settings Client Provisioning Adapter plug-in,

packaged in <filepath>cpsupladapter.dll</filepath>. The plug-in calls the

Host Settings API to set the SUPL server host settings that are used by the

SUPL Protocol Module. </p> <p> </p> </li>

</ul> </section>

</conbody><related-links>

<link href="GUID-567DA7A6-B900-5506-97DA-F425F15CFCB0.dita"><linktext>Host    

            Settings API Tutorial</linktext></link>

<link href="GUID-CC3454B1-21DA-542E-8949-52C30755AC77.dita"><linktext>SUPL Protocol

                Module Overview</linktext></link>

<link href="GUID-91F95D0C-E4CF-510E-B280-E27F89274ACE.dita"><linktext>SUPL Protocol

                Module Quick Start</linktext></link>

</related-links></concept>