williamr@2: /**
williamr@2: * Copyright (c) 2004-2009 Nokia Corporation and/or its subsidiary(-ies).
williamr@2: * All rights reserved.
williamr@2: * This component and the accompanying materials are made available
williamr@4: * under the terms of "Eclipse Public License v1.0"
williamr@2: * which accompanies this distribution, and is available
williamr@4: * at the URL "http://www.eclipse.org/legal/epl-v10.html".
williamr@2: *
williamr@2: * Initial Contributors:
williamr@2: * Nokia Corporation - initial contribution.
williamr@2: *
williamr@2: * Contributors:
williamr@2: *
williamr@2: * Description:
williamr@2: * Declaration of MActiveBackupDataClient and CActiveBackupClient
williamr@2: * 
williamr@2: *
williamr@2: */
williamr@2: 
williamr@2: 
williamr@2: 
williamr@2: /**
williamr@2:  @file
williamr@2:  @released
williamr@2: */
williamr@2: #ifndef __ACTIVEBACKUPCLIENT_H__
williamr@2: #define __ACTIVEBACKUPCLIENT_H__
williamr@2: 
williamr@2: #include <e32base.h>
williamr@2: #include <f32file.h>
williamr@2: #include <e32cmn.h>
williamr@2: #include <connect/sbdefs.h>
williamr@2: 
williamr@2: namespace conn
williamr@2: 	{
williamr@2: 	
williamr@2: 	class MActiveBackupDataClient
williamr@2: 		/**
williamr@2: 		MActiveBackupDataClient is a Mixin to be implemented by an Active Backup client.
williamr@2: 		The client connects to the Secure Backup Server using the CActiveBackupClient
williamr@2: 		class and provides an instance of MActiveBackupDataClient to be called for a
williamr@2: 		range of functions.
williamr@2: 
williamr@2: 		The bulk transfer of data and snapshots is expected to be by means of shared
williamr@2: 		heaps for performance reasons so the API is expected to change in these areas.
williamr@2: 
williamr@2: 		@released
williamr@2: 		@publishedAll
williamr@2: 		*/
williamr@2: 		{
williamr@2: 	public:
williamr@2: 
williamr@2: 		/** 
williamr@2: 		Empty virtual destructor to avoid memory leaks
williamr@2: 		*/
williamr@2: 		virtual ~MActiveBackupDataClient() {}
williamr@2: 
williamr@2: 		///// Backup Methods /////
williamr@2: 
williamr@2: 		/**
williamr@2: 		This method informs the active backup data client that all snapshots have
williamr@2: 		been supplied. If the client has not received a snapshot then it should
williamr@2: 		perform a base backup.
williamr@2: 		*/
williamr@2: 		virtual void AllSnapshotsSuppliedL() = 0;
williamr@2: 
williamr@2: 		/**
williamr@2: 		This method receives all or part of a snapshot of data to allow calculation of an
williamr@2: 		incremental backup.  The snapshot is one that was previously supplied by the data
williamr@2: 		owner.  The snapshot data should be read from the location supplied.
williamr@2: 		The snapshot data may be larger than the location supplied in which case the routine will
williamr@2: 		be called repeatedly until all data has been supplied.
williamr@2: 
williamr@2: 		Snapshot data will also be supplied as part of a restore operation.
williamr@2: 
williamr@2: 		@param aDrive the drive being backed up
williamr@2: 		@param aBuffer a pointer to the base of the location from whence data can be copied.
williamr@2: 		@param aLastSection ETrue if this is the last section of snapshot data, else EFalse.
williamr@2: 		@leave KErrNotSupported if the data owner does not support incremental backups.
williamr@2: 		*/
williamr@2: 		virtual void ReceiveSnapshotDataL(TDriveNumber aDrive, TDesC8& aBuffer, TBool aLastSection) = 0;
williamr@2: 
williamr@2: 		/**
williamr@2: 		This method returns the expected size of backup data that will be supplied.   If an
williamr@2: 		incremental backup is underway then this method will not be called until after
williamr@2: 		ReceiveSnapshotDataL().  The size data will be used for the purpose of tracking progess
williamr@2: 		during a backup.  If it is inaccurate then the user may see irregular progress but the
williamr@2: 		actual backup data will not be affected so it is acceptable to return an estimated
williamr@2: 		value.
williamr@2: 
williamr@2: 		@param aDrive the drive being backed up.
williamr@2: 		@return the size of the data that will be returned
williamr@2: 		*/
williamr@2: 		virtual TUint GetExpectedDataSize(TDriveNumber aDrive) = 0;
williamr@2: 
williamr@2: 		/**
williamr@2: 		This method returns a snapshot of data to accompany a backup.  The snapshot is expected
williamr@2: 		to contain details on files / data being backed up.  The format of the snapshot is only
williamr@2: 		meaningful to the data owner.  The snapshot will be supplied if the data owner is asked
williamr@2: 		for an incremental backup and for a restore operation.  The snapshot data should be
williamr@2: 		copied to the location supplied.
williamr@2: 		The snapshot data may be larger than the location supplied in which case the routine will
williamr@2: 		be called repeatedly until all data has been retrieved.
williamr@2: 
williamr@2: 		@param aDrive the drive being backed up
williamr@2: 		@param aBuffer a pointer to the base of the location where data can be copied.
williamr@2: 		@param aFinished on return ETrue if all data has been returned for this drive, else EFalse.
williamr@2: 		@leave KErrNotSupported if the data owner does not support  incremental backups.
williamr@2: 		*/
williamr@2: 		virtual void GetSnapshotDataL(TDriveNumber aDrive, TPtr8& aBuffer, TBool& aFinished) = 0;
williamr@2: 
williamr@2: 		/**
williamr@2: 		This method prepares the implementor to return backup data.  It will be followed by a
williamr@2: 		sequence of calls to request the actual data.
williamr@2: 
williamr@2: 		@param aDrive the drive being backed up.
williamr@2: 		*/
williamr@2: 		virtual void InitialiseGetBackupDataL(TDriveNumber aDrive) = 0;
williamr@2: 
williamr@2: 		/**
williamr@2: 		This method requests a section of backup data.  InitialiseGetBackupDataL() will have been
williamr@2: 		called prevously to specify the drive concerned.  The data returned may be base or
williamr@2: 		incremental depending on the type of backup and the capability of the data owner.
williamr@2: 
williamr@2: 		@param aBuffer a pointer to the base of the location where data can be copied.
williamr@2: 		@param aFinished on return ETrue if all data has been returned for this drive, else EFalse.
williamr@2: 		*/
williamr@2: 		virtual void GetBackupDataSectionL(TPtr8& aBuffer, TBool& aFinished) = 0;
williamr@2: 
williamr@2: 		///// Restore Methods /////
williamr@2: 
williamr@2: 		/**
williamr@2: 		This method prepares the implementor to receive base restore data for a drive.
williamr@2: 		It will be followed by a sequence of calls to supply the actual data.
williamr@2: 
williamr@2: 		@param aDrive the drive being restored.
williamr@2: 		*/
williamr@2: 		virtual void InitialiseRestoreBaseDataL(TDriveNumber aDrive) = 0;
williamr@2: 
williamr@2: 		/**
williamr@2: 		This method receives a section of base restore data.
williamr@2: 		InitialiseRestoreBaseDataL() will have been called prevously to specify the drive concerned.
williamr@2: 
williamr@2: 		@param aBuffer a pointer to the base of the location whence data can be read.
williamr@2: 		@param aFinished ETrue if all data has been returned for this drive, else EFalse.
williamr@2: 		*/
williamr@2: 		virtual void RestoreBaseDataSectionL(TDesC8& aBuffer, TBool aFinished) = 0;
williamr@2: 
williamr@2: 		/**
williamr@2: 		This method prepares the implementor to receive incremental restore data for a drive.
williamr@2: 		It will be followed by a sequence of calls to supply the actual data.  If multiple
williamr@2: 		increments are supplied then this methid will be called before each increment.
williamr@2: 
williamr@2: 		@param aDrive the drive being restored.
williamr@2: 		*/
williamr@2: 		virtual void InitialiseRestoreIncrementDataL(TDriveNumber aDrive) = 0;
williamr@2: 
williamr@2: 		/**
williamr@2: 		This method receives a section of increment restore data.
williamr@2: 		InitialiseRestoreIncrementDataL() will have been called prevously to specify the 
williamr@2: 		drive concerned.
williamr@2: 
williamr@2: 		@param aBuffer a pointer to the base of the location whence data can be read.
williamr@2: 		@param aFinished ETrue if all data has been returned for this increment, else EFalse.
williamr@2: 		*/
williamr@2: 		virtual void RestoreIncrementDataSectionL(TDesC8& aBuffer, TBool aFinished) = 0;
williamr@2: 
williamr@2: 		/**
williamr@2: 		This method is called when all data to be restored has been supplied.
williamr@2: 
williamr@2: 		@param aDrive the drive being restored.
williamr@2: 		*/
williamr@2: 		virtual void RestoreComplete(TDriveNumber aDrive) = 0;
williamr@2: 
williamr@2: 		/**
williamr@2: 		This method prepares the implementor to return backup data on behalf of another data owner.
williamr@2: 		It will be followed by a sequence of calls to request the actual data. This method is only
williamr@2: 		for use by a proxy data manager that backs up data on behalf of other data owners.  There
williamr@2: 		is no corresponding method for snapshots as it is assumed that a proxy data manager will
williamr@2: 		only handle base data.
williamr@2: 
williamr@2: 		@param aSID the data owner whose data is to be backed up
williamr@2: 		@param aDrive the drive being backed up.
williamr@2: 		*/
williamr@2: 		virtual void InitialiseGetProxyBackupDataL(TSecureId aSID, TDriveNumber aDrive);
williamr@2: 
williamr@2: 		/**
williamr@2: 		This method prepares the implementor to receive base restore data for another data owner
williamr@2: 		for a drive. It will be followed by a sequence of calls to supply the actual data.
williamr@2: 		This method is only for use by a proxy data manager that restores up data on behalf of
williamr@2: 		other data owners.  There is no corresponding method for incremental data as it is assumed
williamr@2: 		that a proxy data manager will only handle base data.
williamr@2: 
williamr@2: 		@param aSID the data owner whose data is to be restored
williamr@2: 		@param aDrive the drive being restored.
williamr@2: 		*/
williamr@2: 		virtual void InitialiseRestoreProxyBaseDataL(TSecureId aSID, TDriveNumber aDrive);
williamr@2: 		
williamr@2: 		///// General Methods /////
williamr@2: 
williamr@2: 		/**
williamr@2: 		This method is called if copying of data is terminated prematurely to allow the 
williamr@2: 		implementor to tidy up.  The same method applies to all types of data and to backup
williamr@2: 		and restore
williamr@2: 		*/
williamr@2: 		virtual void TerminateMultiStageOperation() = 0;
williamr@2: 		
williamr@2: 		/**
williamr@2: 		Gets an extended interface based on a supplied uid.
williamr@2: 		
williamr@2: 		@param aUid Uid which identifies an extended interface
williamr@2: 		@return Pointer to an extended interface
williamr@2: 		*/
williamr@2: 		virtual TAny* GetExtendedInterface(const TInt32 aUid);
williamr@2: 
williamr@2: 		///// Test Methods /////
williamr@2: 		/**
williamr@2: 		Gets a 32-bit checksum for its private data.
williamr@2: 		This routine is for test purposes.  It must be implemented but an invariant checksum 
williamr@2: 		value can be provided.  Some tests may cause checksum values to be compared.
williamr@2:     
williamr@2: 		@param aDrive the drive containing data being checksummed
williamr@2: 		@return the 32-bit checksum
williamr@2: 		*/
williamr@2: 		virtual TUint GetDataChecksum(TDriveNumber aDrive) = 0;
williamr@2: 		};
williamr@2: 
williamr@2: 	inline void MActiveBackupDataClient::InitialiseGetProxyBackupDataL(TSecureId /*aSID*/, TDriveNumber /*aDrive*/)
williamr@2: 	/** Initialises the proxy backup data
williamr@2: 	
williamr@2: 	This is not supported here.
williamr@2: 	
williamr@2: 	@param aSID the secure Id
williamr@2: 	@param aDrive the driver number
williamr@2: 	@leave KErrNotSupported Always.
williamr@2: 	*/
williamr@2: 		{
williamr@2: 		User::Leave(KErrNotSupported);
williamr@2: 		}
williamr@2: 
williamr@2: 	inline void MActiveBackupDataClient::InitialiseRestoreProxyBaseDataL(TSecureId /*aSID*/, TDriveNumber /*aDrive*/)
williamr@2: 		{
williamr@2: 	/** Initialises the proxy backup base data
williamr@2: 	
williamr@2: 	This is not supported here.
williamr@2: 	
williamr@2: 	@param aSID the secure Id
williamr@2: 	@param aDrive the driver number
williamr@2: 	@leave KErrNotSupported Always.
williamr@2: 	*/
williamr@2: 		User::Leave(KErrNotSupported);
williamr@2: 		}
williamr@2: 		
williamr@2: 	inline TAny* MActiveBackupDataClient::GetExtendedInterface(const TInt32 /*aUid*/)
williamr@2: 		{
williamr@2: 		return NULL;
williamr@2: 		}
williamr@2: 				
williamr@2: 	
williamr@2: 	class RABClientSession;
williamr@2: 	class CActiveBackupCallbackHandler;
williamr@2: 	
williamr@2: 	class CActiveBackupClient : public CBase
williamr@2: 		/**
williamr@2: 		CActiveBackupClient provides a connection to the Secure Backup Server for a data owning
williamr@2: 		process.
williamr@2: 
williamr@2: 		It can be used to obtain information about an active backup or restore operation. 
williamr@2: 		It can also be used to signal to the Secure Backup Server when the data owner is ready
williamr@2: 		for backup or restore.
williamr@2: 
williamr@2: 		It is also used by data owners that implement active backup or restore to provide a
williamr@2: 		MActiveBackupDataClient implementation.
williamr@2: 
williamr@2: 		This class owns a RActiveBackupSessionImpl instance and publishes the 
williamr@2: 		public API to the outside world. The reason for this facade class is twofold:
williamr@2: 
williamr@2: 		@li Hiding the implementation details of RActiveBackupSessionImpl 
williamr@2: 
williamr@2: 		@li Future binary compatibility
williamr@2: 
williamr@2: 		@released
williamr@2: 		@publishedAll
williamr@2: 		*/
williamr@2: 		{
williamr@2: 	public:
williamr@2: 		IMPORT_C static CActiveBackupClient* NewL();
williamr@2: 
williamr@2: 		IMPORT_C static CActiveBackupClient* NewL(MActiveBackupDataClient* aClient);
williamr@2: 		IMPORT_C ~CActiveBackupClient();
williamr@2: 		IMPORT_C void BURModeInfoL(TDriveList& aDriveList, TBURPartType& aBackupType, TBackupIncType& aIncBackupType);
williamr@2: 		IMPORT_C TBool DoesPartialBURAffectMeL();
williamr@2: 		IMPORT_C void ConfirmReadyForBURL(TInt aErrorCode);
williamr@2: 
williamr@2: 	private:
williamr@2: 		CActiveBackupClient();
williamr@2: 		void ConstructL();
williamr@2: 		void ConstructL(MActiveBackupDataClient* aClient);
williamr@2: 
williamr@2: 	private:
williamr@2: 		/** Pointer to the client session R class that's wrapped up by this class */
williamr@2: 		RABClientSession* iClientSession;
williamr@2: 		
williamr@2: 		/** Pointer to the Active Backup Callback Handler */
williamr@2: 		CActiveBackupCallbackHandler* iABCallbackHandler;
williamr@2: 		};
williamr@2: 
williamr@2: 	} // end namespace
williamr@2: 
williamr@2: #endif // __ACTIVEBACKUPCLIENT_H__
williamr@4: