7 Nokia Corporation - initial contribution. |
7 Nokia Corporation - initial contribution. |
8 Contributors: |
8 Contributors: |
9 --> |
9 --> |
10 <!DOCTYPE task |
10 <!DOCTYPE task |
11 PUBLIC "-//OASIS//DTD DITA Task//EN" "task.dtd"> |
11 PUBLIC "-//OASIS//DTD DITA Task//EN" "task.dtd"> |
12 <task xml:lang="en" id="GUID-567DA7A6-B900-5506-97DA-F425F15CFCB0"><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><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> </prereq> <context><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"> |
12 <task id="GUID-567DA7A6-B900-5506-97DA-F425F15CFCB0" xml:lang="en"><title>Host |
|
13 Settings API Tutorial</title><shortdesc>This document describes how to use the SUPL Host Settings API (deprecated). </shortdesc><prolog><metadata><keywords/></metadata></prolog><taskbody> |
|
14 <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 |
|
15 Protocol Module</xref> of the LBS subsystem. </p><p>Note: From |
|
16 Symbian^3 the SUPL Protocol Module is deprecated. For the preferred way of |
|
17 using SUPL see <xref href="GUID-1F7F543A-8A9C-4460-BDB1-A6866E9DF0B9.dita">SUPL |
|
18 Proxy Protocol Module</xref>. </p> </prereq> |
|
19 <context id="GUID-9D651569-468E-4C91-9A23-5AFB5A50007C"><p>There are three classes of users of the Host Settings API: </p> <ul> |
|
20 <li id="GUID-CFC35B97-A153-5BB5-A08A-99CAA35ADAE1"><p>The Symbian reference |
|
21 SUPL Protocol Module. </p> </li> |
|
22 <li id="GUID-B188E558-7209-5161-A7EB-D76B52E60E69"><p>The Symbian SUPL host |
|
23 settings device provisioning plug-ins. </p> </li> |
|
24 <li id="GUID-166D7B7C-D989-5AC1-AF3F-ED286FBB62FD"><p>A licensee host settings |
|
25 application. </p> </li> |
|
26 </ul> <p>Device creators will typically only need to use the Host Settings |
|
27 API to create a host settings application to allow mobile device users to |
|
28 read the host settings and to set the default SLP. </p> <p>Note that network |
|
29 operators may not want to allow device users to create new host settings or |
|
30 to modify the individual properties of host settings such as host address |
|
31 and port number as defined in <xref href="GUID-5B492B69-19D2-38B8-946F-FD1155513F9F.dita"><apiname>TLbsHostSettingsSupl</apiname></xref> </p> </context> |
|
32 <steps id="GUID-5890F26A-EC50-5B4A-89DA-A2BB059C2722"> |
|
33 <step id="GUID-1238A4A5-ED69-5B27-B83D-CD9DB6E5102A"><cmd>How to create host |
|
34 settings. </cmd> |
|
35 <info>Host settings can be created using the Host Settings API. They are typically |
|
36 created by the SUPL Device Provisioning plug-ins for Device Management (<filepath>dmsupladapter.dll</filepath>) |
|
37 and Client Provisioning (<filepath>cpsupladapter.dll</filepath>). </info> |
|
38 <info>A network operator can send a Device Management or Client Provisioning |
|
39 message to the mobile device. The message is processed by one of the Device |
|
40 Provisioning plug-ins which use the Host Settings API to create host settings. </info> |
|
41 <info>The example code below shows how the Device Management plug-in creates |
|
42 host settings: </info> |
|
43 <stepxmp><codeblock id="GUID-7123BAFF-9013-5EF6-97D9-44A2F28538F7" xml:space="preserve"> |
13 // Create a host settings store |
44 // Create a host settings store |
14 // The value of KLbsHostSettingsSuplStoreId is defined in lbshostsettings.h |
45 // The value of KLbsHostSettingsSuplStoreId is defined in lbshostsettings.h |
15 |
46 |
16 CLbsHostSettingsStore iLBSHostSettingStore; |
47 CLbsHostSettingsStore iLBSHostSettingStore; |
17 iLBSHostSettingStore = CLbsHostSettingsStore::NewL(KLbsHostSettingsSuplStoreId); |
48 iLBSHostSettingStore = CLbsHostSettingsStore::NewL(KLbsHostSettingsSuplStoreId); |
18 </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"> |
49 </codeblock> </stepxmp> |
|
50 <info>A Device Provisioning plug-in decodes a received message and creates |
|
51 host settings: </info> |
|
52 <stepxmp><codeblock id="GUID-B40F45FF-9DE8-5F0D-9721-C0E05AEC1C15" xml:space="preserve"> |
19 TLbsHostSettingsSupl setting; |
53 TLbsHostSettingsSupl setting; |
20 |
54 |
21 /* Device Management plug-in decodes message to get host settings properties |
55 /* Device Management plug-in decodes message to get host settings properties |
22 and sets the hosts settings properties, for example: |
56 and sets the hosts settings properties, for example: |
23 setting.SetHostNameAddress(aRequest.Data()); |
57 setting.SetHostNameAddress(aRequest.Data()); |
29 TLbsHostSettingsId settingId; |
63 TLbsHostSettingsId settingId; |
30 |
64 |
31 // KLbsHostSettingsDevProvCreatorId is defined in lbshostsettings.h |
65 // KLbsHostSettingsDevProvCreatorId is defined in lbshostsettings.h |
32 // settingId is a return parameter that contains a unique ID for the new host setting entry |
66 // settingId is a return parameter that contains a unique ID for the new host setting entry |
33 User::LeaveIfError(iLBSHostSettingStore->CreateHostSettings(setting, KLbsHostSettingsDevProvCreatorId, settingId)); |
67 User::LeaveIfError(iLBSHostSettingStore->CreateHostSettings(setting, KLbsHostSettingsDevProvCreatorId, settingId)); |
34 </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"> |
68 </codeblock> </stepxmp> |
|
69 <info>Note that in general, mobile device users should not be given the ability |
|
70 to create new host settings via a licensee settings application because host |
|
71 settings are defined by network operators. </info> |
|
72 </step> |
|
73 <step id="GUID-E0FAF2CC-A4D7-5A76-82EE-0E8D8619C7B5"><cmd>How to delete host |
|
74 settings. </cmd> |
|
75 <info>Host settings can be deleted using the Host Settings API. </info> |
|
76 <info>A network operator can send a message to a mobile device to delete host |
|
77 settings. The message is processed by either the SUPL Device Management or |
|
78 SUPL Client Provisioning plug-in. </info> |
|
79 <info>The example code below shows how the Device Management plug-in calls |
|
80 the Host Settings API to delete host settings: </info> |
|
81 <stepxmp><codeblock id="GUID-18FCD2DC-4845-5E4F-B1F9-A810B13B3775" xml:space="preserve"> |
35 // Device Management code to get the ID of the settings to be deleted |
82 // Device Management code to get the ID of the settings to be deleted |
36 TInt settingid; |
83 TInt settingid; |
37 GetLuidL(aRequest.UriParser().Uri(), settingid); |
84 GetLuidL(aRequest.UriParser().Uri(), settingid); |
38 TLbsHostSettingsId id = TUid::Uid(settingid); |
85 TLbsHostSettingsId id = TUid::Uid(settingid); |
39 |
86 |
40 // Use the Host Settings API to delete the host settings... |
87 // Use the Host Settings API to delete the host settings... |
41 User::LeaveIfError(iLBSHostSettingStore->DeleteHostSettings(id)); |
88 User::LeaveIfError(iLBSHostSettingStore->DeleteHostSettings(id)); |
42 </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"> |
89 </codeblock> </stepxmp> |
|
90 </step> |
|
91 <step id="GUID-30B1EB05-D763-564C-84E3-049A887F73AA"><cmd>How to modify host |
|
92 settings </cmd> |
|
93 <info>Existing host settings can be modified using the Host Settings API. </info> |
|
94 <info>A network operator can send a message to a mobile device to modify host |
|
95 settings. The message is processed by either the SUPL Device Management or |
|
96 SUPL Client Provisioning plug-in. </info> |
|
97 <info>The example code below shows how the Device Management plug-in calls |
|
98 the Host Settings API to modify host settings: </info> |
|
99 <stepxmp><codeblock id="GUID-04725335-6496-52C5-9C74-4A9D7811DC26" xml:space="preserve"> |
43 // Device Management code to get the ID of the settings to be updated |
100 // Device Management code to get the ID of the settings to be updated |
44 TInt luid; |
101 TInt luid; |
45 GetLuidL(pathStub, luid); |
102 GetLuidL(pathStub, luid); |
46 TLbsHostSettingsId settingid = TUid::Uid(luid); |
103 TLbsHostSettingsId settingid = TUid::Uid(luid); |
47 |
104 |
48 |
105 |
49 // Use the Host Settings API to update the host settings... |
106 // Use the Host Settings API to update the host settings... |
50 iLBSHostSettingStore->UpdateHostSettings(settingid, aSuplSetting); |
107 iLBSHostSettingStore->UpdateHostSettings(settingid, aSuplSetting); |
51 </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"> |
108 </codeblock> </stepxmp> |
|
109 </step> |
|
110 <step id="GUID-F8FE15D9-767A-52E5-93CE-026D29844485"><cmd>How to read host |
|
111 settings </cmd> |
|
112 <info>Host Settings can be read using the Host Settings API. </info> |
|
113 <info>A licensee may want to create a host settings application to display |
|
114 a list of SLP names and to allow a user to select the default SLP (which is |
|
115 used for SET initiated location requests). </info> |
|
116 <info>There are three methods that can be used to read host settings: </info> |
|
117 |
|
118 <substeps id="GUID-ABA13B53-4CEE-5CDA-B7F7-A7B5638C3181"> |
|
119 <substep id="GUID-7026779A-EB1E-5551-A1AE-CEFD7F98C257"><cmd/> |
|
120 <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 |
|
121 the next host settings in the data store. </info> |
|
122 </substep> |
|
123 <substep id="GUID-7CB76E0C-E440-51C9-A3A4-76AB2EA6ABB8"><cmd/> |
|
124 <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 |
|
125 the next host settings created by a specified Host Settings API client. </info> |
|
126 </substep> |
|
127 <substep id="GUID-64B675FF-5074-5F58-BA10-3D87AE5A1283"><cmd/> |
|
128 <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 |
|
129 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 |
|
130 parameter). <codeph>GetNextHostSettings()</codeph> and <codeph>GetNextHostSettingsByCreator()</codeph> return |
|
131 a settings ID as a <codeph>TLbsHostSettingsId</codeph> output parameter. </info> |
|
132 </substep> |
|
133 </substeps> |
|
134 <info>The first two of the above methods allow a program to iterate over the |
|
135 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 |
|
136 calling either of the <codeph>GetNext</codeph> methods in order to begin iteration |
|
137 with the first host settings entry. </info> |
|
138 <stepxmp><codeblock id="GUID-57B81FFA-B798-5CC7-9702-9CD6765B45B5" xml:space="preserve"> |
52 TLbsHostSettingsSupl setting; |
139 TLbsHostSettingsSupl setting; |
53 TLbsHostSettingsId settingId; |
140 TLbsHostSettingsId settingId; |
54 |
141 |
55 User::LeaveIfError(iLBSHostSettingStore->RewindHostSettings()); |
142 User::LeaveIfError(iLBSHostSettingStore->RewindHostSettings()); |
56 |
143 |
65 // Get hostname, host address etc. for this host setting |
152 // Get hostname, host address etc. for this host setting |
66 |
153 |
67 } |
154 } |
68 |
155 |
69 } |
156 } |
70 </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"> |
157 </codeblock> </stepxmp> |
|
158 </step> |
|
159 <step id="GUID-EA0B8441-C245-57EB-9E3A-C2AD267FA89C"><cmd>How to set default |
|
160 host settings </cmd> |
|
161 <info>The default host settings are used by the SUPL Protocol Module for SET |
|
162 initiated location requests (MO-LRs). A licensee may want to allow users to |
|
163 set the default host settings in a host settings application. </info> |
|
164 <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 |
|
165 the SUPL Location Platform host settings</xref> of the document <xref href="GUID-91F95D0C-E4CF-510E-B280-E27F89274ACE.dita">SUPL |
|
166 Protocol Module Quick Start</xref> for details of the rules used by the SUPL |
|
167 Protocol Module for host settings selection for SET initiated and network |
|
168 initiated location requests. </info> |
|
169 <stepxmp><codeblock id="GUID-C1D87EA3-1089-54F1-BDED-5EEC1B1BC93A" xml:space="preserve"> |
71 // Set the first entry in the host settings store to be the default |
170 // Set the first entry in the host settings store to be the default |
72 |
171 |
73 TLbsHostSettingsSupl setting; |
172 TLbsHostSettingsSupl setting; |
74 TLbsHostSettingsId settingId; |
173 TLbsHostSettingsId settingId; |
75 |
174 |
76 User::LeaveIfError(iLBSHostSettingStore->RewindHostSettings()); |
175 User::LeaveIfError(iLBSHostSettingStore->RewindHostSettings()); |
77 User::LeaveIfError(iLBSHostSettingStore->GetNextHostSettings(setting, settingId)); |
176 User::LeaveIfError(iLBSHostSettingStore->GetNextHostSettings(setting, settingId)); |
78 User::LeaveIfError(iLBSHostSettingStore->SetDefaultHostSettings(settingId)); |
177 User::LeaveIfError(iLBSHostSettingStore->SetDefaultHostSettings(settingId)); |
79 |
178 |
80 </codeblock> </stepxmp> </step> </steps> </taskbody><related-links><link href="GUID-FE4794F8-2519-5AC2-BCF7-168ECA6645EA.dita"><linktext>Host |
179 </codeblock> </stepxmp> |
81 Settings API</linktext> </link> <link href="GUID-CC3454B1-21DA-542E-8949-52C30755AC77.dita"><linktext>SUPL Protocol |
180 </step> |
82 Module Overview</linktext> </link> </related-links></task> |
181 </steps> |
|
182 </taskbody><related-links> |
|
183 <link href="GUID-FE4794F8-2519-5AC2-BCF7-168ECA6645EA.dita"><linktext>Host |
|
184 Settings API</linktext></link> |
|
185 <link href="GUID-CC3454B1-21DA-542E-8949-52C30755AC77.dita"><linktext>SUPL Protocol |
|
186 Module Overview</linktext></link> |
|
187 </related-links></task> |