<?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 task
  PUBLIC "-//OASIS//DTD DITA Task//EN" "task.dtd">
<task id="GUID-567DA7A6-B900-5506-97DA-F425F15CFCB0" xml:lang="en"><title>Host
Settings API Tutorial</title><shortdesc>This document describes how to use the SUPL Host Settings API (deprecated). </shortdesc><prolog><metadata><keywords/></metadata></prolog><taskbody>
<prereq id="GUID-3C812574-821A-4CE0-9010-7BEBECBCEED6"><p>The reader must be familiar with the <xref href="GUID-CC3454B1-21DA-542E-8949-52C30755AC77.dita">SUPL
Protocol Module</xref> of the LBS subsystem. </p><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> </prereq>
<context id="GUID-9D651569-468E-4C91-9A23-5AFB5A50007C"><p>There are three classes of users of the Host Settings API: </p> <ul>
<li id="GUID-CFC35B97-A153-5BB5-A08A-99CAA35ADAE1"><p>The Symbian reference
SUPL Protocol Module. </p> </li>
<li id="GUID-B188E558-7209-5161-A7EB-D76B52E60E69"><p>The Symbian SUPL host
settings device provisioning plug-ins. </p> </li>
<li id="GUID-166D7B7C-D989-5AC1-AF3F-ED286FBB62FD"><p>A licensee host settings
application. </p> </li>
</ul> <p>Device creators will typically only need to use the Host Settings
API to create a host settings application to allow mobile device users to
read the host settings and to set the default SLP. </p> <p>Note that network
operators may not want to allow device users to create new host settings or
to modify the individual properties of host settings such as host address
and port number as defined in <xref href="GUID-5B492B69-19D2-38B8-946F-FD1155513F9F.dita"><apiname>TLbsHostSettingsSupl</apiname></xref>  </p> </context>
<steps id="GUID-5890F26A-EC50-5B4A-89DA-A2BB059C2722">
<step id="GUID-1238A4A5-ED69-5B27-B83D-CD9DB6E5102A"><cmd>How to create host
settings. </cmd>
<info>Host settings can be created using the Host Settings API. They are typically
created by the SUPL Device Provisioning plug-ins for Device Management (<filepath>dmsupladapter.dll</filepath>)
and Client Provisioning (<filepath>cpsupladapter.dll</filepath>). </info>
<info>A network operator can send a Device Management or Client Provisioning
message to the mobile device. The message is processed by one of the Device
Provisioning plug-ins which use the Host Settings API to create host settings. </info>
<info>The example code below shows how the Device Management plug-in creates
host settings: </info>
<stepxmp><codeblock id="GUID-7123BAFF-9013-5EF6-97D9-44A2F28538F7" xml:space="preserve">
// Create a host settings store
// The value of KLbsHostSettingsSuplStoreId is defined in lbshostsettings.h

CLbsHostSettingsStore iLBSHostSettingStore;
iLBSHostSettingStore = CLbsHostSettingsStore::NewL(KLbsHostSettingsSuplStoreId);
</codeblock> </stepxmp>
<info>A Device Provisioning plug-in decodes a received message and creates
host settings: </info>
<stepxmp><codeblock id="GUID-B40F45FF-9DE8-5F0D-9721-C0E05AEC1C15" xml:space="preserve">
TLbsHostSettingsSupl setting;

/* Device Management plug-in decodes message to get host settings properties
   and sets the hosts settings properties, for example:
   setting.SetHostNameAddress(aRequest.Data());
   setting.SetReadOnly(iSetReadOnly); etc.
*/

// Use the Host Settings API to create the host settings

TLbsHostSettingsId settingId;

// KLbsHostSettingsDevProvCreatorId is defined in lbshostsettings.h
// settingId is a return parameter that contains a unique ID for the new host setting entry
User::LeaveIfError(iLBSHostSettingStore-&gt;CreateHostSettings(setting, KLbsHostSettingsDevProvCreatorId, settingId));
</codeblock> </stepxmp>
<info>Note that in general, mobile device users should not be given the ability
to create new host settings via a licensee settings application because host
settings are defined by network operators. </info>
</step>
<step id="GUID-E0FAF2CC-A4D7-5A76-82EE-0E8D8619C7B5"><cmd>How to delete host
settings. </cmd>
<info>Host settings can be deleted using the Host Settings API. </info>
<info>A network operator can send a message to a mobile device to delete host
settings. The message is processed by either the SUPL Device Management or
SUPL Client Provisioning plug-in. </info>
<info>The example code below shows how the Device Management plug-in calls
the Host Settings API to delete host settings: </info>
<stepxmp><codeblock id="GUID-18FCD2DC-4845-5E4F-B1F9-A810B13B3775" xml:space="preserve">
// Device Management code to get the ID of the settings to be deleted
TInt settingid;
GetLuidL(aRequest.UriParser().Uri(), settingid);
TLbsHostSettingsId id = TUid::Uid(settingid);

// Use the Host Settings API to delete the host settings...
User::LeaveIfError(iLBSHostSettingStore-&gt;DeleteHostSettings(id));
</codeblock> </stepxmp>
</step>
<step id="GUID-30B1EB05-D763-564C-84E3-049A887F73AA"><cmd>How to modify host
settings </cmd>
<info>Existing host settings can be modified using the Host Settings API. </info>
<info>A network operator can send a message to a mobile device to modify host
settings. The message is processed by either the SUPL Device Management or
SUPL Client Provisioning plug-in. </info>
<info>The example code below shows how the Device Management plug-in calls
the Host Settings API to modify host settings: </info>
<stepxmp><codeblock id="GUID-04725335-6496-52C5-9C74-4A9D7811DC26" xml:space="preserve">
// Device Management code to get the ID of the settings to be updated
TInt luid;
GetLuidL(pathStub, luid);
TLbsHostSettingsId settingid = TUid::Uid(luid);


// Use the Host Settings API to update the host settings...
iLBSHostSettingStore-&gt;UpdateHostSettings(settingid, aSuplSetting);
</codeblock> </stepxmp>
</step>
<step id="GUID-F8FE15D9-767A-52E5-93CE-026D29844485"><cmd>How to read host
settings </cmd>
<info>Host Settings can be read using the Host Settings API. </info>
<info>A licensee may want to create a host settings application to display
a list of SLP names and to allow a user to select the default SLP (which is
used for SET initiated location requests). </info>
<info>There are three methods that can be used to read host settings: </info>

<substeps id="GUID-ABA13B53-4CEE-5CDA-B7F7-A7B5638C3181">
<substep id="GUID-7026779A-EB1E-5551-A1AE-CEFD7F98C257"><cmd/>
<info> <xref href="GUID-30917438-ED01-3AFC-9964-9337761D6AB6.dita#GUID-30917438-ED01-3AFC-9964-9337761D6AB6/GUID-1CF97B00-2E7C-3E96-83C6-B7551A896215"><apiname>CLbsHostSettingsStore::GetNextHostSettings()</apiname></xref> gets
the next host settings in the data store. </info>
</substep>
<substep id="GUID-7CB76E0C-E440-51C9-A3A4-76AB2EA6ABB8"><cmd/>
<info> <xref href="GUID-30917438-ED01-3AFC-9964-9337761D6AB6.dita#GUID-30917438-ED01-3AFC-9964-9337761D6AB6/GUID-86FA035F-4ED9-3ADA-ABC9-E42229659288"><apiname>CLbsHostSettingsStore::GetNextHostSettingsByCreator()</apiname></xref> gets
the next host settings created by a specified Host Settings API client. </info>
</substep>
<substep id="GUID-64B675FF-5074-5F58-BA10-3D87AE5A1283"><cmd/>
<info> <xref href="GUID-30917438-ED01-3AFC-9964-9337761D6AB6.dita#GUID-30917438-ED01-3AFC-9964-9337761D6AB6/GUID-47FA6FAA-8529-3CBF-9DCD-7D0358EE2980"><apiname>CLbsHostSettingsStore::GetHostSettings()</apiname></xref> gets the
host settings when the settings ID is known (it is specified by a <xref href="GUID-A8BEC3F1-3DC4-3F36-8A27-56F8ECB6CACB.dita"><apiname>TLbsHostSettingsId</apiname></xref> input
parameter). <codeph>GetNextHostSettings()</codeph> and <codeph>GetNextHostSettingsByCreator()</codeph> return
a settings ID as a <codeph>TLbsHostSettingsId</codeph> output parameter. </info>
</substep>
</substeps>
<info>The first two of the above methods allow a program to iterate over the
host settings in the data store. It is necessary to call <xref href="GUID-30917438-ED01-3AFC-9964-9337761D6AB6.dita#GUID-30917438-ED01-3AFC-9964-9337761D6AB6/GUID-B69CF40F-010D-3571-B563-6054263352FF"><apiname>CLbsHostSettingsStore::RewindHostSettings()</apiname></xref> before
calling either of the <codeph>GetNext</codeph> methods in order to begin iteration
with the first host settings entry. </info>
<stepxmp><codeblock id="GUID-57B81FFA-B798-5CC7-9702-9CD6765B45B5" xml:space="preserve">
TLbsHostSettingsSupl setting;
TLbsHostSettingsId settingId;

User::LeaveIfError(iLBSHostSettingStore-&gt;RewindHostSettings());

TInt err = KErrNone;
while (err != KErrNotFound)
    {
    err = iLBSHostSettingStore-&gt;GetNextHostSettings(setting, settingId);
                    
    if (err == KErrNone)
        {
        // settingId contains a unique settingId
        // Get hostname, host address etc. for this host setting

        } 

 }
</codeblock> </stepxmp>
</step>
<step id="GUID-EA0B8441-C245-57EB-9E3A-C2AD267FA89C"><cmd>How to set default
host settings </cmd>
<info>The default host settings are used by the SUPL Protocol Module for SET
initiated location requests (MO-LRs). A licensee may want to allow users to
set the default host settings in a host settings application. </info>
<info>See the section <xref href="GUID-91F95D0C-E4CF-510E-B280-E27F89274ACE.dita#GUID-91F95D0C-E4CF-510E-B280-E27F89274ACE/GUID-061F50BE-F291-53D9-ACD9-B36D19B01E54">Configure
the SUPL Location Platform host settings</xref> of the document <xref href="GUID-91F95D0C-E4CF-510E-B280-E27F89274ACE.dita">SUPL
Protocol Module Quick Start</xref> for details of the rules used by the SUPL
Protocol Module for host settings selection for SET initiated and network
initiated location requests. </info>
<stepxmp><codeblock id="GUID-C1D87EA3-1089-54F1-BDED-5EEC1B1BC93A" xml:space="preserve">
// Set the first entry in the host settings store to be the default

TLbsHostSettingsSupl setting;
TLbsHostSettingsId settingId;

User::LeaveIfError(iLBSHostSettingStore-&gt;RewindHostSettings());
User::LeaveIfError(iLBSHostSettingStore-&gt;GetNextHostSettings(setting, settingId));
User::LeaveIfError(iLBSHostSettingStore-&gt;SetDefaultHostSettings(settingId));

</codeblock> </stepxmp>
</step>
</steps>
</taskbody><related-links>
<link href="GUID-FE4794F8-2519-5AC2-BCF7-168ECA6645EA.dita"><linktext>Host    
            Settings API</linktext></link>
<link href="GUID-CC3454B1-21DA-542E-8949-52C30755AC77.dita"><linktext>SUPL Protocol
                Module Overview</linktext></link>
</related-links></task>