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