<?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_d0e460847_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>