Host Settings API Tutorial

This document describes how to use the SUPL Host Settings API (deprecated).

1. How to create host settings. Host settings can be created using the Host Settings API. They are typically created by the SUPL Device Provisioning plug-ins for Device Management (dmsupladapter.dll) and Client Provisioning (cpsupladapter.dll). 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. The example code below shows how the Device Management plug-in creates host settings:

   
   // Create a host settings store
   // The value of KLbsHostSettingsSuplStoreId is defined in lbshostsettings.h
   
   CLbsHostSettingsStore iLBSHostSettingStore;
   iLBSHostSettingStore = CLbsHostSettingsStore::NewL(KLbsHostSettingsSuplStoreId);
   

   A Device Provisioning plug-in decodes a received message and creates host settings:

   
   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));
   

   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.
2. How to delete host settings. Host settings can be deleted using the Host Settings API. 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. The example code below shows how the Device Management plug-in calls the Host Settings API to delete host settings:

   
   // 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));
   

3. How to modify host settings Existing host settings can be modified using the Host Settings API. 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. The example code below shows how the Device Management plug-in calls the Host Settings API to modify host settings:

   
   // 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);
   

4. How to read host settings Host Settings can be read using the Host Settings API. 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). There are three methods that can be used to read host settings:
   1. 
      CLbsHostSettingsStore::GetNextHostSettings() gets the next host settings in the data store.
   2. 
      CLbsHostSettingsStore::GetNextHostSettingsByCreator() gets the next host settings created by a specified Host Settings API client.
   3. 
      CLbsHostSettingsStore::GetHostSettings() gets the host settings when the settings ID is known (it is specified by a TLbsHostSettingsId input parameter). GetNextHostSettings() and GetNextHostSettingsByCreator() return a settings ID as a TLbsHostSettingsId output parameter.
   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 CLbsHostSettingsStore::RewindHostSettings() before calling either of the GetNext methods in order to begin iteration with the first host settings entry.

   
   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
   
           } 
   
    }
   

5. How to set default host settings 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. See the section Configure the SUPL Location Platform host settings of the document SUPL Protocol Module Quick Start for details of the rules used by the SUPL Protocol Module for host settings selection for SET initiated and network initiated location requests.

   
   // 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));