|
1 // Copyright (c) 2004-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 CSBEClient class. |
|
15 // |
|
16 // |
|
17 |
|
18 /** |
|
19 @file |
|
20 @released |
|
21 */ |
|
22 |
|
23 #include "sbeclient.h" |
|
24 #include "sbeclientsession.h" |
|
25 #include <connect/panic.h> |
|
26 |
|
27 namespace conn |
|
28 { |
|
29 |
|
30 CSBEClient::CSBEClient() |
|
31 /** Class constructor. */ |
|
32 { |
|
33 } |
|
34 |
|
35 |
|
36 EXPORT_C CSBEClient* CSBEClient::NewL() |
|
37 /** |
|
38 Standard creation method. |
|
39 |
|
40 @return a new CSBEClient. |
|
41 */ |
|
42 { |
|
43 CSBEClient* self = new (ELeave) CSBEClient(); |
|
44 CleanupStack::PushL(self); |
|
45 self->ConstructL(); |
|
46 CleanupStack::Pop(self); |
|
47 return self; |
|
48 } |
|
49 |
|
50 void CSBEClient::ConstructL() |
|
51 /** |
|
52 Construct this instance of CSBEClient |
|
53 */ |
|
54 { |
|
55 iClientSession = RSBEClientSession::NewL(); |
|
56 |
|
57 User::LeaveIfError(iClientSession->Connect()); |
|
58 } |
|
59 |
|
60 |
|
61 EXPORT_C CSBEClient::~CSBEClient() |
|
62 /** |
|
63 Standard destructor |
|
64 */ |
|
65 { |
|
66 if (iClientSession) |
|
67 { |
|
68 iClientSession->Close(); |
|
69 } |
|
70 |
|
71 delete iClientSession; |
|
72 iClientSession = NULL; |
|
73 } |
|
74 |
|
75 |
|
76 EXPORT_C void CSBEClient::ListOfDataOwnersL(RPointerArray<CDataOwnerInfo>& aDataOwners) |
|
77 /** |
|
78 Gets a list of all registered data owners. |
|
79 This method can be called regardless of backup or restore mode. |
|
80 N.B. If it is called before a restore the set may not include all data owners that |
|
81 are to be restored. |
|
82 |
|
83 If the Secure Backup Engine has not parsed backup registration files then this call |
|
84 will trigger scanning and parsing. |
|
85 |
|
86 @param aDataOwners on return an array of information about backup data owners. |
|
87 */ |
|
88 { |
|
89 iClientSession->ListOfDataOwnersL(aDataOwners); |
|
90 } |
|
91 |
|
92 EXPORT_C void CSBEClient::PublicFileListL(TDriveNumber aDrive, CSBGenericDataType& aGenericDataType, RFileArray& aFiles) |
|
93 /** |
|
94 Gets a list of actual public files associated with an SID for partial backup. This allows |
|
95 a client to backup only the public files associated with an SID. |
|
96 This method must only be called when the device is in backup mode as the set of files may |
|
97 not be final until then. This method takes no account of any snapshots - the full list |
|
98 of candidate public files is returned and it is up to the Secure Backup Server to check |
|
99 file attributes if an incremental backup is required. |
|
100 |
|
101 If the Secure Backup Engine has not parsed backup registration files then this call |
|
102 will trigger scanning and parsing. |
|
103 |
|
104 @param aDrive the drive concerned. |
|
105 @param aGenericDataType reference to the data type. |
|
106 @param aFiles on return an array of information about files. |
|
107 */ |
|
108 { |
|
109 iClientSession->PublicFileListL(aDrive, aGenericDataType, aFiles); |
|
110 } |
|
111 |
|
112 EXPORT_C void CSBEClient::RawPublicFileListL(TDriveNumber aDrive, CSBGenericDataType& aGenericDataType, |
|
113 RRestoreFileFilterArray& aFileFilter) |
|
114 /** |
|
115 Gets a list of public files and directories associated with an SID for partial restore. |
|
116 This method must only be called when the device is in restore mode. |
|
117 This method must only be called after a registration file has been supplied and parsed. |
|
118 Directories can be distinguished from files by a terminating slash. |
|
119 |
|
120 During a restore operation, the client will have the archive or public files available but the |
|
121 Secure Backup Engine does not. Therefore, the engine cannot list the exact files. This method |
|
122 returns the list of files or directories that were specified in the backup registration file without |
|
123 further analysis and the client can use this information to filter public files for restore. |
|
124 |
|
125 This allows a client that has taken a full backup to be selective about restore . |
|
126 |
|
127 If the Secure Backup Engine has not parsed backup registration files then this call |
|
128 will trigger scanning and parsing. |
|
129 |
|
130 @param aDrive the drive concerned. |
|
131 @param aGenericDataType reference to the data type. |
|
132 @param aFileFilter on return an array of names of files or directories for restore. |
|
133 */ |
|
134 { |
|
135 iClientSession->RawPublicFileListL(aDrive, aGenericDataType, aFileFilter); |
|
136 } |
|
137 |
|
138 EXPORT_C void CSBEClient::PublicFileListXMLL(TDriveNumber aDrive, TSecureId aSID, HBufC*& aFileList) |
|
139 /** |
|
140 Gets a list of public files and directories associated with an SID for partial backup or restore. |
|
141 This method returns the data in the form of an XML description for compatibility with older |
|
142 devices. |
|
143 |
|
144 This method can be called regardless of the backup or restore mode as it does not rely on the |
|
145 set of public files being final. |
|
146 |
|
147 If the Secure Backup Engine has not parsed backup registration files then this call |
|
148 will trigger scanning and parsing. |
|
149 |
|
150 @param aDrive the drive concerned. |
|
151 @param aSID the data owner. |
|
152 @param aFileList on return a description of the list of files and directories. Must be NULL |
|
153 */ |
|
154 { |
|
155 __ASSERT_DEBUG(aFileList == NULL, Panic(KErrArgument)); |
|
156 iClientSession->PublicFileListXMLL(aDrive, aSID, aFileList); |
|
157 } |
|
158 |
|
159 EXPORT_C void CSBEClient::SetBURModeL(const TDriveList& aDriveList, TBURPartType aBURType, |
|
160 TBackupIncType aBackupIncType) |
|
161 /** |
|
162 Sets B&R on or off and sets the base / increment and full / partial mode and the affected drives |
|
163 |
|
164 @param aDriveList the drives affected. |
|
165 @param aBURType is a full or partial backup or restore desired or normal operation. |
|
166 @param aBackupIncType is a backup base or incremental (ignored for restore operations). |
|
167 */ |
|
168 { |
|
169 iClientSession->SetBURModeL(aDriveList, aBURType, aBackupIncType); |
|
170 } |
|
171 |
|
172 EXPORT_C void CSBEClient::SetSIDListForPartialBURL(RSIDArray& aSIDs) |
|
173 /** |
|
174 If a partial backup is required then this sets the list of data owners. |
|
175 This method must only be called when the device has just been put into backup or restore mode. |
|
176 It must only be called once for a backup or restore operation. |
|
177 |
|
178 @param aSIDs array of affected data owners. |
|
179 */ |
|
180 { |
|
181 iClientSession->SetSIDListForPartialBURL(aSIDs); |
|
182 } |
|
183 |
|
184 |
|
185 EXPORT_C void CSBEClient::SIDStatusL(RSIDStatusArray& aSIDStatus) |
|
186 /** |
|
187 Gets the status of a set of data owners. |
|
188 This method must only be called in backup or restore mode. |
|
189 |
|
190 You must populate the array with the TDataOwnerAndStatus's for each secure id the client |
|
191 is interested in. |
|
192 |
|
193 @param aSIDStatus an array of structures for information about data owners. On return |
|
194 the status information is filled in. |
|
195 */ |
|
196 { |
|
197 iClientSession->SIDStatusL(aSIDStatus); |
|
198 } |
|
199 |
|
200 |
|
201 // Data Access Methods // |
|
202 |
|
203 EXPORT_C TPtr8& CSBEClient::TransferDataAddressL() |
|
204 /** |
|
205 Provides access to the base of the global chunk used to transfer data between |
|
206 the Secure Backup Engine and a Secure Backup Server. This method should be used |
|
207 when the Secure Backup Server is providing data to the Secure Backup Engine (either as part |
|
208 of a restore operation or when supplying snapshots during a backup operation. |
|
209 |
|
210 The Secure Backup Engine only uses one global chunk at a time. It is not permissible to |
|
211 try to carry out multiple backup or restore operations in parallel. Normally a chunk |
|
212 of global heap would be protected by a mutex. In this case, all the methods of the |
|
213 Secure Backup Engine must be regarded as synchronous and mutually exclusive - it is not |
|
214 permissible to make parallel calls. |
|
215 |
|
216 The global chunk used during a backup or restore operation may change and so the address must |
|
217 be requested whenever required rather than being cached. |
|
218 |
|
219 @return Pointer to the start of the buffer for writing |
|
220 */ |
|
221 { |
|
222 return iClientSession->TransferDataAddressL(); |
|
223 } |
|
224 |
|
225 EXPORT_C TPtrC8& CSBEClient::TransferDataInfoL(CSBGenericTransferType*& aGenericTransferType, |
|
226 TBool& aFinished) |
|
227 /** |
|
228 Provides access to the data received from the Secure Backup Engine during a backup operation. |
|
229 |
|
230 This method should be called after a synchronous or asynchronous request for data has |
|
231 completed. |
|
232 |
|
233 @param aGenericTransferType Reference to a CSBGenericTransferType pointer. Must be NULL |
|
234 @param aFinished ETrue if the data is the last chunk, EFalse if there is more to request. |
|
235 @return read only pointer to the global heap. |
|
236 */ |
|
237 { |
|
238 __ASSERT_DEBUG(aGenericTransferType == NULL, Panic(KErrArgument)); |
|
239 return iClientSession->TransferDataInfoL(aGenericTransferType, aFinished); |
|
240 } |
|
241 |
|
242 EXPORT_C void CSBEClient::RequestDataL(CSBGenericTransferType& aGenericTransferType, |
|
243 TRequestStatus& aStatus) |
|
244 /** |
|
245 This method requests package data from the Secure Backup Engine asynchronously. |
|
246 When the relevant AO completes the returned data (and information about it) can be accessed |
|
247 by calling TransferDataInfoL(). |
|
248 |
|
249 Some forms of backup data may be larger than can be handled in one transfer, in which case this |
|
250 method should be called again with the same arguments until all data is signalled as supplied. |
|
251 |
|
252 @param aGenericTransferType Reference to a CSBGenericTransferType object |
|
253 @param aStatus the request status of an Active Object to be completed when the data has been received |
|
254 */ |
|
255 { |
|
256 iClientSession->RequestDataL(aGenericTransferType, aStatus); |
|
257 } |
|
258 |
|
259 EXPORT_C void CSBEClient::RequestDataL(CSBGenericTransferType& aGenericTransferType) |
|
260 /** |
|
261 This synchronous method requests backup data from the Secure Backup Engine. |
|
262 When the method returns the returned data (and information about it) can be accessed |
|
263 by calling TransferDataInfoL(). |
|
264 |
|
265 Some forms of backup data may be larger than can be handled in one transfer, in which case this |
|
266 method should be called again with the same arguments until all data is signalled as supplied. |
|
267 |
|
268 @param aGenericTransferType Reference to a CSBGenericTransferType object |
|
269 */ |
|
270 { |
|
271 iClientSession->RequestDataL(aGenericTransferType); |
|
272 } |
|
273 |
|
274 EXPORT_C void CSBEClient::SupplyDataL(CSBGenericTransferType& aGenericTransferType, |
|
275 TBool aFinished, TRequestStatus& aStatus) |
|
276 /** |
|
277 This method supplies some form of package data during a backup or restore |
|
278 operation asynchronously. |
|
279 |
|
280 When the relevant Active Object is completed the Secure Backup Engine has absorbed the |
|
281 supplied data. |
|
282 |
|
283 Some forms of data may be larger than can be handled in one transfer, in which case this |
|
284 method should be called again with the same arguments until all data has been supplied. |
|
285 |
|
286 @param aGenericTransferType Reference to a CSBGenericTransferType object |
|
287 @param aFinished ETrue if this buffer is the last one for this package uid, drive and data type |
|
288 @param aStatus the request status of an Active Object to be completed when the data has been transferred |
|
289 */ |
|
290 { |
|
291 iClientSession->SupplyDataL(aGenericTransferType, aFinished, aStatus); |
|
292 } |
|
293 |
|
294 EXPORT_C void CSBEClient::SupplyDataL(CSBGenericTransferType& aGenericTransferType, |
|
295 TBool aFinished) |
|
296 /** |
|
297 This synchronous method supplies some form of package data during a backup or |
|
298 restore operation. |
|
299 |
|
300 When the method returns the Secure Backup Engine has absorbed the supplied data. |
|
301 |
|
302 Some forms of data may be larger than can be handled in one transfer, in which case this |
|
303 method should be called again with the same arguments until all data has been supplied. |
|
304 |
|
305 @param aGenericTransferType Reference to a CSBGenericTransferType object |
|
306 @param aFinished ETrue if this buffer is the last one for this package uid, drive and data type |
|
307 */ |
|
308 { |
|
309 iClientSession->SupplyDataL(aGenericTransferType, aFinished); |
|
310 } |
|
311 |
|
312 EXPORT_C void CSBEClient::AllSnapshotsSuppliedL() |
|
313 /** |
|
314 This method sets the type of backup to base for this particular data owner. |
|
315 The whole device may be subject to an incremental backup but a particular |
|
316 data owner may be subject to a base backup (if they have not been backed |
|
317 up previously). The reverse is not true. |
|
318 |
|
319 This method must only be called when the device has just been put into backup mode. |
|
320 It must only be called once for a SID for a backup operation. |
|
321 */ |
|
322 { |
|
323 iClientSession->AllSnapshotsSuppliedL(); |
|
324 } |
|
325 |
|
326 EXPORT_C TUint CSBEClient::ExpectedDataSizeL(CSBGenericTransferType& aGenericTransferType) |
|
327 /** |
|
328 This method returns the expected size of package data that will be supplied. The size |
|
329 data will be used for the purpose of tracking progess during a backup. If it is |
|
330 inaccurate then the user may see irregular progress but the actual backup data will |
|
331 not be affected so it is acceptable to return an estimated value. |
|
332 |
|
333 This method must only be called during a backup operation. If it is called when the |
|
334 data owner is not ready for backup then the call will fail. |
|
335 |
|
336 @param aGenericTransferType Reference to a CSBGenericTransferType object |
|
337 @return KErrNone if successful. |
|
338 */ |
|
339 { |
|
340 return (iClientSession->ExpectedDataSizeL(aGenericTransferType)); |
|
341 } |
|
342 |
|
343 EXPORT_C void CSBEClient::AllSystemFilesRestored() |
|
344 /** |
|
345 This method is called when all system files have been provided to allow the Secure |
|
346 Backup Engine to start active data owners. |
|
347 */ |
|
348 { |
|
349 iClientSession->AllSystemFilesRestored(); |
|
350 } |
|
351 |
|
352 /** |
|
353 Gets a list of all registered data owners asynchronously. |
|
354 This method can be called regardless of backup or restore mode. |
|
355 N.B. If it is called before a restore the set may not include all data owners that |
|
356 are to be restored. |
|
357 |
|
358 If the Secure Backup Engine has not parsed backup registration files then this call |
|
359 will trigger scanning and parsing. |
|
360 |
|
361 @param aDataOwners on return an array of information about backup data owners. |
|
362 @param aStatus is TRequestStatus& |
|
363 */ |
|
364 EXPORT_C void CSBEClient::ListOfDataOwnersL(RPointerArray<CDataOwnerInfo>& aDataOwners, TRequestStatus& aStatus) |
|
365 { |
|
366 iClientSession->ListOfDataOwnersL(aDataOwners, aStatus); |
|
367 } |
|
368 |
|
369 /** |
|
370 Gets a list of actual public files associated with an SID for partial backup asynchronously. |
|
371 This allows a client to backup only the public files associated with an SID. |
|
372 This method must only be called when the device is in backup mode as the set of files may |
|
373 not be final until then. This method takes no account of any snapshots - the full list |
|
374 of candidate public files is returned and it is up to the Secure Backup Server to check |
|
375 file attributes if an incremental backup is required. |
|
376 |
|
377 If the Secure Backup Engine has not parsed backup registration files then this call |
|
378 will trigger scanning and parsing. |
|
379 |
|
380 @param aDrive the drive concerned. |
|
381 @param aGenericDataType reference to the data type. |
|
382 @param aFiles on return an array of information about files. |
|
383 @param aStatus is TRequestStatus& |
|
384 */ |
|
385 EXPORT_C void CSBEClient::PublicFileListL(TDriveNumber aDrive, CSBGenericDataType& aGenericDataType, RFileArray& aFiles, TRequestStatus& aStatus) |
|
386 { |
|
387 iClientSession->PublicFileListL(aDrive, aGenericDataType, aFiles, aStatus); |
|
388 } |
|
389 |
|
390 /** |
|
391 Sets B&R on or off and sets the base / increment and full / partial mode and the affected drives asynchronously. |
|
392 |
|
393 @param aDriveList the drives affected. |
|
394 @param aBURType is a full or partial backup or restore desired or normal operation. |
|
395 @param aBackupIncType is a backup base or incremental (ignored for restore operations). |
|
396 @param aStatus is TRequestStatus& |
|
397 */ |
|
398 EXPORT_C void CSBEClient::SetBURModeL(const TDriveList& aDriveList, TBURPartType aBURType, |
|
399 TBackupIncType aBackupIncType, TRequestStatus& aStatus) |
|
400 { |
|
401 iClientSession->SetBURModeL(aDriveList, aBURType, aBackupIncType, aStatus); |
|
402 } |
|
403 |
|
404 /** |
|
405 This method which sets the type of backup to base for this particular data owner asynchronously. |
|
406 The whole device may be subject to an incremental backup but a particular |
|
407 data owner may be subject to a base backup (if they have not been backed |
|
408 up previously). The reverse is not true. |
|
409 |
|
410 This method must only be called when the device has just been put into backup mode. |
|
411 It must only be called once for a SID for a backup operation. |
|
412 |
|
413 @param aStatus is TRequestStatus& |
|
414 */ |
|
415 EXPORT_C void CSBEClient::AllSnapshotsSuppliedL(TRequestStatus& aStatus) |
|
416 { |
|
417 iClientSession->AllSnapshotsSuppliedL(aStatus); |
|
418 } |
|
419 |
|
420 /** |
|
421 This method is called asynchronously when all system files have been provided to allow the Secure |
|
422 Backup Engine to start active data owners. |
|
423 |
|
424 @param aStatus is TRequestStatus& |
|
425 */ |
|
426 EXPORT_C void CSBEClient::AllSystemFilesRestoredL(TRequestStatus& aStatus) |
|
427 { |
|
428 iClientSession->AllSystemFilesRestoredL(aStatus); |
|
429 } |
|
430 |
|
431 // Test Methods // |
|
432 |
|
433 EXPORT_C TUint CSBEClient::DataChecksum(TDriveNumber /*aDrive*/, TSecureId /*aSID*/) |
|
434 /** |
|
435 Get a 32-bit checksum for private data. |
|
436 This routine is for test purposes. It must be implemented but an invariant checksum |
|
437 value can be provided. Some tests may cause checksum values to be compared. |
|
438 |
|
439 @param aDrive the drive containing data being checksummed |
|
440 @param aSID the data owner. |
|
441 @return the 32-bit checksum |
|
442 */ |
|
443 { |
|
444 return 0; |
|
445 } |
|
446 |
|
447 EXPORT_C void CSBEClient::PublicFileListL(TDriveNumber aDrive, CSBGenericDataType& aGenericDataType, |
|
448 RPointerArray<CSBEFileEntry>& aFileList, TBool& aFinished, |
|
449 TInt aTotalListCursor, TInt aMaxResponseSize, TRequestStatus& aStatus) |
|
450 /** This asynchronous method is used to retrieve the list of public files for the specified data owner |
|
451 on the specified drive. Upon completion of aStatus, the caller should check aFileList |
|
452 @param aDrive The drive that contains the public files being retrieved |
|
453 @param aGenericDataType The identifier for the data owner that owns the public files |
|
454 @param aFileList Upon completion of aStatus, this array will contain the list of public files returned |
|
455 @param aFinished Upon completion of aStatus, this flag will be set to indicate that there are more |
|
456 file entries available for this data owner and another call to this method should be made |
|
457 @param aTotalListCursor Specifies the index into the complete list of public files for this data owner to start |
|
458 the next chunk of file entries from. The number of entries returned by a call to this |
|
459 method can be determined by querying the count of aFileList |
|
460 @param aMaxResponseSize The maximum total size in bytes of externalised CSBEFileEntry objects that will be returned |
|
461 @param aStatus The TRequestStatus that will be completed once the engine has fully processed this request |
|
462 */ |
|
463 { |
|
464 iClientSession->PublicFileListL(aDrive, aGenericDataType, aFileList, aFinished, aTotalListCursor, aMaxResponseSize, aStatus); |
|
465 } |
|
466 |
|
467 } // end of conn namespace |
|
468 |
|
469 |