--- 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 @@
-<?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 xml:lang="en" id="GUID-FE4794F8-2519-5AC2-BCF7-168ECA6645EA"><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: The Host Settings API is deprecated. </p> <section><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_d0e444423_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><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><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><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><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><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>
\ No newline at end of file
+<?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>
\ No newline at end of file