diff -r 000000000000 -r d0791faffa3f backupandrestore/backupengine/src/sbeclient.cpp --- /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 + +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& 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& 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& 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 + +