|
1 // Copyright (c) 2007-2009 Nokia Corporation and/or its subsidiary(-ies). |
|
2 // All rights reserved. |
|
3 // This component and the accompanying materials are made available |
|
4 // under the terms of "Eclipse Public License v1.0" |
|
5 // which accompanies this distribution, and is available |
|
6 // at the URL "http://www.eclipse.org/legal/epl-v10.html". |
|
7 // |
|
8 // Initial Contributors: |
|
9 // Nokia Corporation - initial contribution. |
|
10 // |
|
11 // Contributors: |
|
12 // |
|
13 // Description: |
|
14 // Implementation of the LBS Host Settings Interface |
|
15 // |
|
16 // |
|
17 |
|
18 /** |
|
19 @file |
|
20 @publishedPartner |
|
21 @deprecated |
|
22 */ |
|
23 |
|
24 |
|
25 #include <e32base.h> |
|
26 |
|
27 #include <lbs/lbshostsettings.h> |
|
28 #include "lbshostsettingsimpl.h" |
|
29 |
|
30 //============================================================================= |
|
31 // MLbsHostSettingsStoreObserver |
|
32 //============================================================================= |
|
33 |
|
34 /** |
|
35 Provides the version of the observer interface. This can be used |
|
36 by the host settings storage library to determine the functionality |
|
37 supported by the client application. |
|
38 |
|
39 @return Version of the observer interface. |
|
40 */ |
|
41 EXPORT_C TVersion MLbsHostSettingsStoreObserver::Version() const |
|
42 { |
|
43 return TVersion(0, 0, 0); |
|
44 } |
|
45 |
|
46 |
|
47 /** |
|
48 Should not be used. Provides for future expansion of the observer interface. |
|
49 */ |
|
50 EXPORT_C TAny* MLbsHostSettingsStoreObserver::ExtendedInterface |
|
51 ( |
|
52 TInt /*aFunctionNumber*/, |
|
53 TAny* /*aPtr1*/, |
|
54 TAny* /*aPtr2*/ |
|
55 ) |
|
56 { |
|
57 return NULL; |
|
58 } |
|
59 |
|
60 |
|
61 //============================================================================= |
|
62 // CLbsHostSettingsBase |
|
63 // CLbsHostSettingsStore::ConstructL() is defined in the impl.cpp file, in |
|
64 // order to transparently provide multiple implementations |
|
65 //============================================================================= |
|
66 |
|
67 /** |
|
68 Default constructor for the settings store. |
|
69 */ |
|
70 CLbsHostSettingsStore::CLbsHostSettingsStore() |
|
71 { |
|
72 } |
|
73 |
|
74 |
|
75 /** |
|
76 Creates a new connection to the host settings stored for the specified settings store ID. |
|
77 Each ID defines |
|
78 |
|
79 @param aStoreId Specifies the host settings store to open. The value specifies a settings store |
|
80 for a specific protocol, for example SUPL. |
|
81 |
|
82 @return An Instance of the storage class. The calling application becomes the |
|
83 owner of the returned instance and is responsible its cleanup. |
|
84 */ |
|
85 EXPORT_C CLbsHostSettingsStore* CLbsHostSettingsStore::NewL(TLbsHostStoreId aStoreId) |
|
86 { |
|
87 CLbsHostSettingsStore* newStore = new (ELeave) CLbsHostSettingsStore(); |
|
88 CleanupStack::PushL(newStore); |
|
89 newStore->ConstructL(aStoreId, NULL); |
|
90 CleanupStack::Pop(newStore); |
|
91 return newStore; |
|
92 } |
|
93 |
|
94 /** |
|
95 Creates a new connection to the host settings stored for the specified protocol. |
|
96 By specifying an observer, the calling application will receive a notification |
|
97 whenever the specified store is updated by another client. |
|
98 |
|
99 Note: The client application will not receive an update notification for |
|
100 changes made by itself. |
|
101 |
|
102 @param aStoreId Specifies the host settings store to open. |
|
103 @param aObserver The observer receives notifications of updates to |
|
104 the host settings store specified by aStoreId. |
|
105 |
|
106 @return A storage class instance. The calling application becomes the |
|
107 owner of the returned instance and is responsible its cleanup. |
|
108 */ |
|
109 EXPORT_C CLbsHostSettingsStore* CLbsHostSettingsStore::NewL(TLbsHostStoreId aStoreId, MLbsHostSettingsStoreObserver& aObserver) |
|
110 { |
|
111 CLbsHostSettingsStore* newStore = new (ELeave) CLbsHostSettingsStore(); |
|
112 CleanupStack::PushL(newStore); |
|
113 newStore->ConstructL(aStoreId, &aObserver); |
|
114 CleanupStack::Pop(newStore); |
|
115 return newStore; |
|
116 } |
|
117 |
|
118 /** |
|
119 Retrieves the settings for a particular host settings ID. |
|
120 |
|
121 The host settings ID is a persistent identifier that uniquely specifies |
|
122 a host settings within one data store. This method locates and retrieves |
|
123 the settings for the host indicated by the parameter aSettingsId. |
|
124 If the method returns succcessfully, the paramter aSettings contains the |
|
125 details of the specified host. |
|
126 |
|
127 The ID for a particular host settings can be retrieved by calling |
|
128 TLbsHostSettingsBase::HostSettingsId(). |
|
129 |
|
130 An application can monitor data store changes using the observer interface |
|
131 MLbsHostSettingsStoreObserver (passing it as parameter in CLbsHostSettingsStore::NewL()). |
|
132 |
|
133 The parameter aSettings must be derived from TLbsHostSettingsBase. For SUPL |
|
134 related host information, the aSettings parameters must be of type |
|
135 TLbsHostSettingsSupl. |
|
136 |
|
137 @param aSettingsId Specifies the ID of the host setting that should be retrieved. |
|
138 @param aSettings On a successful return, contains the settings for host specified by |
|
139 aSettingsId. |
|
140 |
|
141 @return KErrNone when the settings for the specified host are successfully returned. |
|
142 A negative (error) value when it is not possible to return the stored settings |
|
143 for the specified host. KErrNotFound when the specified host ID |
|
144 is invalid or the associated host setting has been deleted. KErrArgument if the class type |
|
145 of parameter aSettings is incompatible for the information contained in the data store. |
|
146 |
|
147 @see TLbsHostSettingsBase::HostSettingsId() |
|
148 @see TLbsHostSettingsSupl |
|
149 @see MLbsHostSettingsStoreObserver |
|
150 */ |
|
151 EXPORT_C TInt CLbsHostSettingsStore::GetHostSettings(TLbsHostSettingsId aSettingsId,TLbsHostSettingsBase& aSettings) const |
|
152 { |
|
153 return iSettingsStore->GetHostSettings(aSettingsId, aSettings); |
|
154 } |
|
155 |
|
156 |
|
157 /** |
|
158 Resets the client's view of the data store. |
|
159 |
|
160 RewindHostSettings() is used in conjunction with GetNextHostSettings() |
|
161 and GetNextHostSettingsByCreator(). |
|
162 |
|
163 Before calling GetNextHostSettings() or GetNextHostSettingsByCreator() |
|
164 for the first time, the client application must call RewindHostSettings(). |
|
165 This resets the client's view of the data store. When a client subsequently calls |
|
166 GetNextHostSettings() or GetNextHostSettingsByCreator() the details of |
|
167 the first host settings will be returned. |
|
168 |
|
169 @return KErrNone if successful. A negative (error) if it is not possible |
|
170 reset the client view of the data store. |
|
171 |
|
172 @see GetNextHostSettings() |
|
173 @see GetNextHostSettingsByCreator() |
|
174 */ |
|
175 EXPORT_C TInt CLbsHostSettingsStore::RewindHostSettings() |
|
176 { |
|
177 return iSettingsStore->RewindHostSettings(); |
|
178 } |
|
179 |
|
180 |
|
181 /** |
|
182 Retrieves index of the next host settings following on from the specified host |
|
183 settings ID. |
|
184 |
|
185 Used in conjunction with RewindHostSettings() this method allows a client |
|
186 application to iterate through the entire contents of the data store. |
|
187 |
|
188 Before calling GetNextHostSettings() at the beginning of an iteration, the client application must call |
|
189 RewindHostSettings(). This resets the client's view of the data store. |
|
190 When the client subsequently calls GetNextHostSettings() the details of |
|
191 the first host settings will be returned. |
|
192 |
|
193 To iterate through all host settings contained in the data store, the client |
|
194 application should continue to call GetNextHostSettings() until the method |
|
195 returns KErrNotFound. The method returns KErrNotFound if there are no further |
|
196 host settings contained in the data store. |
|
197 |
|
198 @param aSettings On a successful return, contains the details of the |
|
199 next host contained in the data store. |
|
200 |
|
201 @param aSettingsId On a successful return, contains the ID of the |
|
202 next host contained in the data store. |
|
203 |
|
204 @return KErrNone if host settings have been found. A negative (error) value if it |
|
205 is not possible to return the stored settings for the specified host. |
|
206 KErrNotFound if there are no further host settings contained in the data store. |
|
207 KErrArgument if the class type of parameter aSettings is incompatible for the |
|
208 information contained in the data store. |
|
209 |
|
210 @see NumHosts() |
|
211 @see TLbsHostSettingsSupl |
|
212 @see MLbsHostSettingsStoreObserver |
|
213 @see NewL() |
|
214 */ |
|
215 EXPORT_C TInt CLbsHostSettingsStore::GetNextHostSettings(TLbsHostSettingsBase& aSettings, TLbsHostSettingsId& aSettingsId |
|
216 ) |
|
217 { |
|
218 return iSettingsStore->GetNextHostSettings(aSettings, aSettingsId); |
|
219 } |
|
220 |
|
221 |
|
222 |
|
223 /** |
|
224 Retrieves the ID and details of the next host settings (provisioned by the specified creator) |
|
225 in the data store |
|
226 |
|
227 When a host setting is created, the client application specifies the ID of the |
|
228 type of "creator". This indicates (for example) if the settings was created by a |
|
229 control panel application or provisioned from the network. |
|
230 |
|
231 Used in conjunction with RewindHostSettings(), a client application can use |
|
232 GetNextHostSettingsByCreator() to retrieve one or more host settings |
|
233 based on the ID of their creator. |
|
234 |
|
235 To iterate through all host settings contained in the data store, the client |
|
236 application should continue to call GetNextHostSettingsByCreator() until the method |
|
237 returns KErrNotFound. The method returns KErrNotFound when there are no further host settings |
|
238 contained in the data store. |
|
239 |
|
240 @param aCreatorId Specifies the creator ID to be searched for. |
|
241 |
|
242 @param aSettings On a successful return, contains the details of the |
|
243 next host contained in the data store with the specified Creator ID. |
|
244 |
|
245 @param aSettingsId On a successful return, contains the ID of the |
|
246 next host contained in the data store with the specified Creator ID. |
|
247 |
|
248 @return KErrNone if a host with the specified creator has been found and its details |
|
249 successfully returned. A negative (error) value if it is not possible to return |
|
250 the stored settings for the specified host. KErrNotFound when there are no further host |
|
251 settings contained in the data store with the specified creator ID. KErrArgument if |
|
252 the class type of parameter aSettings is incompatible for the information contained in the data store. |
|
253 |
|
254 @see NumHosts() |
|
255 @see TLbsHostSettingsSupl |
|
256 @see MLbsHostSettingsStoreObserver |
|
257 @see NewL() |
|
258 */ |
|
259 EXPORT_C TInt CLbsHostSettingsStore::GetNextHostSettingsByCreator(TLbsHostCreatorId aCreatorId, TLbsHostSettingsBase& aSettings, TLbsHostSettingsId& aSettingsId) |
|
260 { |
|
261 return iSettingsStore->GetNextHostSettingsByCreator(aCreatorId, aSettings, aSettingsId); |
|
262 } |
|
263 |
|
264 /** |
|
265 |
|
266 Replaces the settings for an existing host settings entry in the data store. |
|
267 |
|
268 Note: The data in the parameter aSettings must have been initially obtained by |
|
269 calling GetHostSettings() on the same data store. For SUPL related hosts, the |
|
270 aSettings parameters must be of type TLbsHostSettingsSupl. |
|
271 |
|
272 Updating an entry does not change the default host for the particular data store. |
|
273 If the application wishes to make the updated entry the default host, it must call |
|
274 SetDefaultHost() with the index of that entry. |
|
275 |
|
276 @param aSettingsId Specifies the ID of the host settings to overwrite. |
|
277 @param aSettings Supplied by the caller and contains the updated configuration |
|
278 parameters for the specified host. |
|
279 |
|
280 @return KErrNone when the entry has been successfully updated. |
|
281 A negative (error) value is returned when it has not been possible to |
|
282 update the host settings entry. |
|
283 KErrNotFound if the host settings ID information specified aSettingsId |
|
284 is invalid or has been deleted. |
|
285 KErrArgument if the parameter aSettings does not contains valid settings |
|
286 for host. In particular, it was not obtained using the GetHostSettings() on the same |
|
287 data store or is of the wrong class type. |
|
288 |
|
289 @capability WriteDeviceData |
|
290 @capability NetworkServices |
|
291 @capability Location |
|
292 @see GetHostSettings() |
|
293 @see TLbsHostSettingsSupl() |
|
294 */ |
|
295 EXPORT_C TInt CLbsHostSettingsStore::UpdateHostSettings(TLbsHostSettingsId aSettingsId, const TLbsHostSettingsBase& aSettings) |
|
296 { |
|
297 return iSettingsStore->UpdateHostSettings(aSettingsId, aSettings); |
|
298 } |
|
299 |
|
300 /** |
|
301 |
|
302 Removes the host information with the specified ID from the data store. |
|
303 |
|
304 If the specified host is currently defined as the default host no other host |
|
305 automatically becomes the new default. It is the responsibility of the calling |
|
306 application to select a new default host. This is done using the |
|
307 SetDefaultHostSettings() method. |
|
308 |
|
309 @param aSettingsId Indicates which host setting to delete. |
|
310 |
|
311 @return KErrNone when the host settings specified by aHostIndex has been deleted. |
|
312 A negative (error) value when there has been a problem removing the specified settings. |
|
313 KErrNotFound when the specified host ID is invalid or the associated host setting has already been deleted. |
|
314 |
|
315 @capability WriteDeviceData |
|
316 @see NumHosts() |
|
317 @see GetHostSettings() |
|
318 */ |
|
319 EXPORT_C TInt CLbsHostSettingsStore::DeleteHostSettings(TLbsHostSettingsId aSettingsId) |
|
320 { |
|
321 return iSettingsStore->DeleteHostSettings(aSettingsId); |
|
322 } |
|
323 |
|
324 /** |
|
325 Retrieves the settings for the host that is currently specified as the default host. |
|
326 |
|
327 The default host is primarily used to decide which network server should be used to |
|
328 service terminal initiated location requests. |
|
329 |
|
330 The default host is only changed by calling SetDefaultHostSettings().Adding or |
|
331 updating the settings for a host does not automatically make it the default. |
|
332 |
|
333 @param aSettings On a successful return, contains the details of the default host. |
|
334 |
|
335 @return KErrNone when the default host settings ID has been retrieved. |
|
336 @return A negative (error) value is returned when it is not possible to obtain the |
|
337 active host. |
|
338 @return KErrNotFound is returned if there is no currently defined active host. |
|
339 @return KErrNotFound is also returned when there are no actual host settings |
|
340 defined. |
|
341 @return KErrArgument If the class type of parameter aSettings is incompatible |
|
342 with data types used by the data store. |
|
343 |
|
344 @see SetDefaultHostSettings |
|
345 */ |
|
346 EXPORT_C TInt CLbsHostSettingsStore::GetDefaultHostSettings(TLbsHostSettingsBase& aSettings) const |
|
347 { |
|
348 TLbsHostSettingsId discardedId; |
|
349 return iSettingsStore->GetDefaultHostSettings(aSettings, discardedId); |
|
350 } |
|
351 |
|
352 /** |
|
353 Retrieves the settings for the host that is currently specified as the default host. |
|
354 |
|
355 The default host is primarily used to decide which network server should be used to |
|
356 service terminal initiated location requests. |
|
357 |
|
358 The default host is only changed by calling SetDefaultHostSettings().Adding or |
|
359 updating the settings for a host does not automatically make it the default. |
|
360 |
|
361 @param aSettings On a successful return, contains the details of the default host. |
|
362 @param aSettingsId On a successful return, contains the ID of the default host. |
|
363 |
|
364 @return KErrNone when the default host settings ID has been retrieved. |
|
365 @return A negative (error) value is returned when it is not possible to obtain the |
|
366 active host. |
|
367 @return KErrNotFound is returned if there is no currently defined active host. |
|
368 @return KErrNotFound is also returned when there are no actual host settings |
|
369 defined. |
|
370 @return KErrArgument If the class type of parameter aSettings is incompatible |
|
371 with data types used by the data store. |
|
372 |
|
373 @see SetDefaultHostSettings |
|
374 */ |
|
375 EXPORT_C TInt CLbsHostSettingsStore::GetDefaultHostSettings(TLbsHostSettingsBase& aSettings, TLbsHostSettingsId& aSettingsId) const |
|
376 { |
|
377 return iSettingsStore->GetDefaultHostSettings(aSettings, aSettingsId); |
|
378 } |
|
379 |
|
380 /** |
|
381 |
|
382 Changes the default host to that specified by the supplied ID. |
|
383 |
|
384 The default host is primarily used to decide which network server should be |
|
385 used to service terminal initiated location requests. |
|
386 |
|
387 @param aSettingsId Specifies the ID of the host to use as the default. |
|
388 |
|
389 @return KErrNone if the default host has been successfully updated. |
|
390 A negative (error) value if it is not possible to set the active |
|
391 host to that specified by aHostIndex. KErrNotFound if the specified |
|
392 host ID is invalid or the associated host setting has been deleted. |
|
393 |
|
394 @capability WriteDeviceData |
|
395 @capability NetworkServices |
|
396 @capability Location |
|
397 @see GetDefaultHostSettings() |
|
398 */ |
|
399 EXPORT_C TInt CLbsHostSettingsStore::SetDefaultHostSettings(TLbsHostSettingsId aSettingsId) |
|
400 { |
|
401 return iSettingsStore->SetDefaultHostSettings(aSettingsId); |
|
402 } |
|
403 |
|
404 /** |
|
405 Creates a new host settings entry in the data store. |
|
406 |
|
407 The index of the new entry is returned via the parameter aSettingsId. |
|
408 |
|
409 The aSettings parameter contains the details of the new host entry. This |
|
410 parameter must be derived from TLbsHostSettingsBase and be compatible |
|
411 with entries in the data store. For SUPL related hosts, the aSettings |
|
412 parameter must be of type TLbsHostSettingsSupl. |
|
413 |
|
414 Creating a new entry in the data store does not change the "default" host |
|
415 entry. If the application wishes to make the new entry the default host |
|
416 it must call SetDefaultHost() with the index of that entry. |
|
417 |
|
418 @param aSettings Supplied by the caller and contains the various configuration |
|
419 parameters for the specified host. |
|
420 |
|
421 @param aCreatorId Specifies which application type has created the entry. |
|
422 This is used to distinguish between network and user provision entries. |
|
423 |
|
424 @param aSettingsId Returned parameter that contains the ID of |
|
425 the newly created host entry in the data store. |
|
426 |
|
427 @return KErrNone when a new entry was successfully created in the data store. |
|
428 A negative (error) value is returned when it has not been possible to |
|
429 create a new host settings entry in the data store. |
|
430 KErrArgument if the class type of parameter aSettings is incompatible |
|
431 with data types used by the data store or some settings have undefined values. |
|
432 |
|
433 @capability WriteDeviceData |
|
434 @see GetHostSettings() |
|
435 @see SetDefaultHost() |
|
436 @see DefaultHostIndex() |
|
437 */ |
|
438 |
|
439 EXPORT_C TInt CLbsHostSettingsStore::CreateHostSettings(const TLbsHostSettingsBase& aSettings,TLbsHostCreatorId aCreatorId,TLbsHostSettingsId& aSettingsId) |
|
440 { |
|
441 return iSettingsStore->CreateHostSettings(aSettings, aCreatorId, aSettingsId); |
|
442 } |
|
443 |
|
444 |