<?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->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->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->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->RewindHostSettings());

TInt err = KErrNone;

while (err != KErrNotFound)

    {

    err = iLBSHostSettingStore->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->RewindHostSettings());

User::LeaveIfError(iLBSHostSettingStore->GetNextHostSettings(setting, settingId));

User::LeaveIfError(iLBSHostSettingStore->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>