--- /dev/null Thu Jan 01 00:00:00 1970 +0000
+++ b/backupandrestore/backupengine/src/sbeclient.cpp Tue Feb 02 01:11:40 2010 +0200
@@ -0,0 +1,469 @@
+// Copyright (c) 2004-2009 Nokia Corporation and/or its subsidiary(-ies).
+// All rights reserved.
+// This component and the accompanying materials are made available
+// under the terms of "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:
+//
+// Description:
+// Implementation of CSBEClient class.
+//
+//
+
+/**
+ @file
+ @released
+*/
+
+#include "sbeclient.h"
+#include "sbeclientsession.h"
+#include <connect/panic.h>
+
+namespace conn
+ {
+
+ CSBEClient::CSBEClient()
+ /** Class constructor. */
+ {
+ }
+
+
+ EXPORT_C CSBEClient* CSBEClient::NewL()
+ /**
+ Standard creation method.
+
+ @return a new CSBEClient.
+ */
+ {
+ CSBEClient* self = new (ELeave) CSBEClient();
+ CleanupStack::PushL(self);
+ self->ConstructL();
+ CleanupStack::Pop(self);
+ return self;
+ }
+
+ void CSBEClient::ConstructL()
+ /**
+ Construct this instance of CSBEClient
+ */
+ {
+ iClientSession = RSBEClientSession::NewL();
+
+ User::LeaveIfError(iClientSession->Connect());
+ }
+
+
+ EXPORT_C CSBEClient::~CSBEClient()
+ /**
+ Standard destructor
+ */
+ {
+ if (iClientSession)
+ {
+ iClientSession->Close();
+ }
+
+ delete iClientSession;
+ iClientSession = NULL;
+ }
+
+
+ EXPORT_C void CSBEClient::ListOfDataOwnersL(RPointerArray<CDataOwnerInfo>& aDataOwners)
+ /**
+ Gets a list of all registered data owners.
+ This method can be called regardless of backup or restore mode.
+ N.B. If it is called before a restore the set may not include all data owners that
+ are to be restored.
+
+ If the Secure Backup Engine has not parsed backup registration files then this call
+ will trigger scanning and parsing.
+
+ @param aDataOwners on return an array of information about backup data owners.
+ */
+ {
+ iClientSession->ListOfDataOwnersL(aDataOwners);
+ }
+
+ EXPORT_C void CSBEClient::PublicFileListL(TDriveNumber aDrive, CSBGenericDataType& aGenericDataType, RFileArray& aFiles)
+ /**
+ Gets a list of actual public files associated with an SID for partial backup. This allows
+ a client to backup only the public files associated with an SID.
+ This method must only be called when the device is in backup mode as the set of files may
+ not be final until then. This method takes no account of any snapshots - the full list
+ of candidate public files is returned and it is up to the Secure Backup Server to check
+ file attributes if an incremental backup is required.
+
+ If the Secure Backup Engine has not parsed backup registration files then this call
+ will trigger scanning and parsing.
+
+ @param aDrive the drive concerned.
+ @param aGenericDataType reference to the data type.
+ @param aFiles on return an array of information about files.
+ */
+ {
+ iClientSession->PublicFileListL(aDrive, aGenericDataType, aFiles);
+ }
+
+ EXPORT_C void CSBEClient::RawPublicFileListL(TDriveNumber aDrive, CSBGenericDataType& aGenericDataType,
+ RRestoreFileFilterArray& aFileFilter)
+ /**
+ Gets a list of public files and directories associated with an SID for partial restore.
+ This method must only be called when the device is in restore mode.
+ This method must only be called after a registration file has been supplied and parsed.
+ Directories can be distinguished from files by a terminating slash.
+
+ During a restore operation, the client will have the archive or public files available but the
+ Secure Backup Engine does not. Therefore, the engine cannot list the exact files. This method
+ returns the list of files or directories that were specified in the backup registration file without
+ further analysis and the client can use this information to filter public files for restore.
+
+ This allows a client that has taken a full backup to be selective about restore .
+
+ If the Secure Backup Engine has not parsed backup registration files then this call
+ will trigger scanning and parsing.
+
+ @param aDrive the drive concerned.
+ @param aGenericDataType reference to the data type.
+ @param aFileFilter on return an array of names of files or directories for restore.
+ */
+ {
+ iClientSession->RawPublicFileListL(aDrive, aGenericDataType, aFileFilter);
+ }
+
+ EXPORT_C void CSBEClient::PublicFileListXMLL(TDriveNumber aDrive, TSecureId aSID, HBufC*& aFileList)
+ /**
+ Gets a list of public files and directories associated with an SID for partial backup or restore.
+ This method returns the data in the form of an XML description for compatibility with older
+ devices.
+
+ This method can be called regardless of the backup or restore mode as it does not rely on the
+ set of public files being final.
+
+ If the Secure Backup Engine has not parsed backup registration files then this call
+ will trigger scanning and parsing.
+
+ @param aDrive the drive concerned.
+ @param aSID the data owner.
+ @param aFileList on return a description of the list of files and directories. Must be NULL
+ */
+ {
+ __ASSERT_DEBUG(aFileList == NULL, Panic(KErrArgument));
+ iClientSession->PublicFileListXMLL(aDrive, aSID, aFileList);
+ }
+
+ EXPORT_C void CSBEClient::SetBURModeL(const TDriveList& aDriveList, TBURPartType aBURType,
+ TBackupIncType aBackupIncType)
+ /**
+ Sets B&R on or off and sets the base / increment and full / partial mode and the affected drives
+
+ @param aDriveList the drives affected.
+ @param aBURType is a full or partial backup or restore desired or normal operation.
+ @param aBackupIncType is a backup base or incremental (ignored for restore operations).
+ */
+ {
+ iClientSession->SetBURModeL(aDriveList, aBURType, aBackupIncType);
+ }
+
+ EXPORT_C void CSBEClient::SetSIDListForPartialBURL(RSIDArray& aSIDs)
+ /**
+ If a partial backup is required then this sets the list of data owners.
+ This method must only be called when the device has just been put into backup or restore mode.
+ It must only be called once for a backup or restore operation.
+
+ @param aSIDs array of affected data owners.
+ */
+ {
+ iClientSession->SetSIDListForPartialBURL(aSIDs);
+ }
+
+
+ EXPORT_C void CSBEClient::SIDStatusL(RSIDStatusArray& aSIDStatus)
+ /**
+ Gets the status of a set of data owners.
+ This method must only be called in backup or restore mode.
+
+ You must populate the array with the TDataOwnerAndStatus's for each secure id the client
+ is interested in.
+
+ @param aSIDStatus an array of structures for information about data owners. On return
+ the status information is filled in.
+ */
+ {
+ iClientSession->SIDStatusL(aSIDStatus);
+ }
+
+
+ // Data Access Methods //
+
+ EXPORT_C TPtr8& CSBEClient::TransferDataAddressL()
+ /**
+ Provides access to the base of the global chunk used to transfer data between
+ the Secure Backup Engine and a Secure Backup Server. This method should be used
+ when the Secure Backup Server is providing data to the Secure Backup Engine (either as part
+ of a restore operation or when supplying snapshots during a backup operation.
+
+ The Secure Backup Engine only uses one global chunk at a time. It is not permissible to
+ try to carry out multiple backup or restore operations in parallel. Normally a chunk
+ of global heap would be protected by a mutex. In this case, all the methods of the
+ Secure Backup Engine must be regarded as synchronous and mutually exclusive - it is not
+ permissible to make parallel calls.
+
+ The global chunk used during a backup or restore operation may change and so the address must
+ be requested whenever required rather than being cached.
+
+ @return Pointer to the start of the buffer for writing
+ */
+ {
+ return iClientSession->TransferDataAddressL();
+ }
+
+ EXPORT_C TPtrC8& CSBEClient::TransferDataInfoL(CSBGenericTransferType*& aGenericTransferType,
+ TBool& aFinished)
+ /**
+ Provides access to the data received from the Secure Backup Engine during a backup operation.
+
+ This method should be called after a synchronous or asynchronous request for data has
+ completed.
+
+ @param aGenericTransferType Reference to a CSBGenericTransferType pointer. Must be NULL
+ @param aFinished ETrue if the data is the last chunk, EFalse if there is more to request.
+ @return read only pointer to the global heap.
+ */
+ {
+ __ASSERT_DEBUG(aGenericTransferType == NULL, Panic(KErrArgument));
+ return iClientSession->TransferDataInfoL(aGenericTransferType, aFinished);
+ }
+
+ EXPORT_C void CSBEClient::RequestDataL(CSBGenericTransferType& aGenericTransferType,
+ TRequestStatus& aStatus)
+ /**
+ This method requests package data from the Secure Backup Engine asynchronously.
+ When the relevant AO completes the returned data (and information about it) can be accessed
+ by calling TransferDataInfoL().
+
+ Some forms of backup data may be larger than can be handled in one transfer, in which case this
+ method should be called again with the same arguments until all data is signalled as supplied.
+
+ @param aGenericTransferType Reference to a CSBGenericTransferType object
+ @param aStatus the request status of an Active Object to be completed when the data has been received
+ */
+ {
+ iClientSession->RequestDataL(aGenericTransferType, aStatus);
+ }
+
+ EXPORT_C void CSBEClient::RequestDataL(CSBGenericTransferType& aGenericTransferType)
+ /**
+ This synchronous method requests backup data from the Secure Backup Engine.
+ When the method returns the returned data (and information about it) can be accessed
+ by calling TransferDataInfoL().
+
+ Some forms of backup data may be larger than can be handled in one transfer, in which case this
+ method should be called again with the same arguments until all data is signalled as supplied.
+
+ @param aGenericTransferType Reference to a CSBGenericTransferType object
+ */
+ {
+ iClientSession->RequestDataL(aGenericTransferType);
+ }
+
+ EXPORT_C void CSBEClient::SupplyDataL(CSBGenericTransferType& aGenericTransferType,
+ TBool aFinished, TRequestStatus& aStatus)
+ /**
+ This method supplies some form of package data during a backup or restore
+ operation asynchronously.
+
+ When the relevant Active Object is completed the Secure Backup Engine has absorbed the
+ supplied data.
+
+ Some forms of data may be larger than can be handled in one transfer, in which case this
+ method should be called again with the same arguments until all data has been supplied.
+
+ @param aGenericTransferType Reference to a CSBGenericTransferType object
+ @param aFinished ETrue if this buffer is the last one for this package uid, drive and data type
+ @param aStatus the request status of an Active Object to be completed when the data has been transferred
+ */
+ {
+ iClientSession->SupplyDataL(aGenericTransferType, aFinished, aStatus);
+ }
+
+ EXPORT_C void CSBEClient::SupplyDataL(CSBGenericTransferType& aGenericTransferType,
+ TBool aFinished)
+ /**
+ This synchronous method supplies some form of package data during a backup or
+ restore operation.
+
+ When the method returns the Secure Backup Engine has absorbed the supplied data.
+
+ Some forms of data may be larger than can be handled in one transfer, in which case this
+ method should be called again with the same arguments until all data has been supplied.
+
+ @param aGenericTransferType Reference to a CSBGenericTransferType object
+ @param aFinished ETrue if this buffer is the last one for this package uid, drive and data type
+ */
+ {
+ iClientSession->SupplyDataL(aGenericTransferType, aFinished);
+ }
+
+ EXPORT_C void CSBEClient::AllSnapshotsSuppliedL()
+ /**
+ This method sets the type of backup to base for this particular data owner.
+ The whole device may be subject to an incremental backup but a particular
+ data owner may be subject to a base backup (if they have not been backed
+ up previously). The reverse is not true.
+
+ This method must only be called when the device has just been put into backup mode.
+ It must only be called once for a SID for a backup operation.
+ */
+ {
+ iClientSession->AllSnapshotsSuppliedL();
+ }
+
+ EXPORT_C TUint CSBEClient::ExpectedDataSizeL(CSBGenericTransferType& aGenericTransferType)
+ /**
+ This method returns the expected size of package data that will be supplied. The size
+ data will be used for the purpose of tracking progess during a backup. If it is
+ inaccurate then the user may see irregular progress but the actual backup data will
+ not be affected so it is acceptable to return an estimated value.
+
+ This method must only be called during a backup operation. If it is called when the
+ data owner is not ready for backup then the call will fail.
+
+ @param aGenericTransferType Reference to a CSBGenericTransferType object
+ @return KErrNone if successful.
+ */
+ {
+ return (iClientSession->ExpectedDataSizeL(aGenericTransferType));
+ }
+
+ EXPORT_C void CSBEClient::AllSystemFilesRestored()
+ /**
+ This method is called when all system files have been provided to allow the Secure
+ Backup Engine to start active data owners.
+ */
+ {
+ iClientSession->AllSystemFilesRestored();
+ }
+
+ /**
+ Gets a list of all registered data owners asynchronously.
+ This method can be called regardless of backup or restore mode.
+ N.B. If it is called before a restore the set may not include all data owners that
+ are to be restored.
+
+ If the Secure Backup Engine has not parsed backup registration files then this call
+ will trigger scanning and parsing.
+
+ @param aDataOwners on return an array of information about backup data owners.
+ @param aStatus is TRequestStatus&
+ */
+ EXPORT_C void CSBEClient::ListOfDataOwnersL(RPointerArray<CDataOwnerInfo>& aDataOwners, TRequestStatus& aStatus)
+ {
+ iClientSession->ListOfDataOwnersL(aDataOwners, aStatus);
+ }
+
+ /**
+ Gets a list of actual public files associated with an SID for partial backup asynchronously.
+ This allows a client to backup only the public files associated with an SID.
+ This method must only be called when the device is in backup mode as the set of files may
+ not be final until then. This method takes no account of any snapshots - the full list
+ of candidate public files is returned and it is up to the Secure Backup Server to check
+ file attributes if an incremental backup is required.
+
+ If the Secure Backup Engine has not parsed backup registration files then this call
+ will trigger scanning and parsing.
+
+ @param aDrive the drive concerned.
+ @param aGenericDataType reference to the data type.
+ @param aFiles on return an array of information about files.
+ @param aStatus is TRequestStatus&
+ */
+ EXPORT_C void CSBEClient::PublicFileListL(TDriveNumber aDrive, CSBGenericDataType& aGenericDataType, RFileArray& aFiles, TRequestStatus& aStatus)
+ {
+ iClientSession->PublicFileListL(aDrive, aGenericDataType, aFiles, aStatus);
+ }
+
+ /**
+ Sets B&R on or off and sets the base / increment and full / partial mode and the affected drives asynchronously.
+
+ @param aDriveList the drives affected.
+ @param aBURType is a full or partial backup or restore desired or normal operation.
+ @param aBackupIncType is a backup base or incremental (ignored for restore operations).
+ @param aStatus is TRequestStatus&
+ */
+ EXPORT_C void CSBEClient::SetBURModeL(const TDriveList& aDriveList, TBURPartType aBURType,
+ TBackupIncType aBackupIncType, TRequestStatus& aStatus)
+ {
+ iClientSession->SetBURModeL(aDriveList, aBURType, aBackupIncType, aStatus);
+ }
+
+ /**
+ This method which sets the type of backup to base for this particular data owner asynchronously.
+ The whole device may be subject to an incremental backup but a particular
+ data owner may be subject to a base backup (if they have not been backed
+ up previously). The reverse is not true.
+
+ This method must only be called when the device has just been put into backup mode.
+ It must only be called once for a SID for a backup operation.
+
+ @param aStatus is TRequestStatus&
+ */
+ EXPORT_C void CSBEClient::AllSnapshotsSuppliedL(TRequestStatus& aStatus)
+ {
+ iClientSession->AllSnapshotsSuppliedL(aStatus);
+ }
+
+ /**
+ This method is called asynchronously when all system files have been provided to allow the Secure
+ Backup Engine to start active data owners.
+
+ @param aStatus is TRequestStatus&
+ */
+ EXPORT_C void CSBEClient::AllSystemFilesRestoredL(TRequestStatus& aStatus)
+ {
+ iClientSession->AllSystemFilesRestoredL(aStatus);
+ }
+
+ // Test Methods //
+
+ EXPORT_C TUint CSBEClient::DataChecksum(TDriveNumber /*aDrive*/, TSecureId /*aSID*/)
+ /**
+ Get a 32-bit checksum for private data.
+ This routine is for test purposes. It must be implemented but an invariant checksum
+ value can be provided. Some tests may cause checksum values to be compared.
+
+ @param aDrive the drive containing data being checksummed
+ @param aSID the data owner.
+ @return the 32-bit checksum
+ */
+ {
+ return 0;
+ }
+
+ EXPORT_C void CSBEClient::PublicFileListL(TDriveNumber aDrive, CSBGenericDataType& aGenericDataType,
+ RPointerArray<CSBEFileEntry>& aFileList, TBool& aFinished,
+ TInt aTotalListCursor, TInt aMaxResponseSize, TRequestStatus& aStatus)
+ /** This asynchronous method is used to retrieve the list of public files for the specified data owner
+ on the specified drive. Upon completion of aStatus, the caller should check aFileList
+ @param aDrive The drive that contains the public files being retrieved
+ @param aGenericDataType The identifier for the data owner that owns the public files
+ @param aFileList Upon completion of aStatus, this array will contain the list of public files returned
+ @param aFinished Upon completion of aStatus, this flag will be set to indicate that there are more
+ file entries available for this data owner and another call to this method should be made
+ @param aTotalListCursor Specifies the index into the complete list of public files for this data owner to start
+ the next chunk of file entries from. The number of entries returned by a call to this
+ method can be determined by querying the count of aFileList
+ @param aMaxResponseSize The maximum total size in bytes of externalised CSBEFileEntry objects that will be returned
+ @param aStatus The TRequestStatus that will be completed once the engine has fully processed this request
+ */
+ {
+ iClientSession->PublicFileListL(aDrive, aGenericDataType, aFileList, aFinished, aTotalListCursor, aMaxResponseSize, aStatus);
+ }
+
+ } // end of conn namespace
+
+