diff -r 2e2dc3d30ca8 -r 341166945d65 homescreenapp/hsdomainmodel/src/hsbackuprestoreactivecallback.cpp --- a/homescreenapp/hsdomainmodel/src/hsbackuprestoreactivecallback.cpp Thu Jun 24 13:11:40 2010 +0100 +++ b/homescreenapp/hsdomainmodel/src/hsbackuprestoreactivecallback.cpp Fri Jun 25 19:19:22 2010 +0300 @@ -16,20 +16,22 @@ */ -// INCLUDE FILES #include #include "hsbackuprestoreactivecallback.h" #include "hsbackuprestoreobserver.h" -// CONSTANTS - -// ======== MEMBER FUNCTIONS ======== +/*! + \class CHsBURActiveCallback + \ingroup group_hsdomainmodel + \brief B&R active callback. + Home screen active callback in backup/restore. +*/ -// --------------------------------------------------------------------------- -// -// --------------------------------------------------------------------------- -// +/*! + Constructor. + \a observer Backup restore observer +*/ CHsBURActiveCallback* CHsBURActiveCallback::NewL(HsBackupRestoreObserver* observer) { CHsBURActiveCallback* self = @@ -41,27 +43,42 @@ return self; } -// --------------------------------------------------------------------------- -// Destructor -// --------------------------------------------------------------------------- -// +/*! + Destructor. +*/ CHsBURActiveCallback::~CHsBURActiveCallback() { } -// --------------------------------------------------------------------------- -// Inform that all data has been backed up or restored. -// --------------------------------------------------------------------------- -// +/*! + This method informs the active backup data client that all + snapshots have been supplied. If the client has not + received a snapshot then it should perform a base backup. + Inform that all data has been backed up or restored. +*/ void CHsBURActiveCallback::AllSnapshotsSuppliedL() { // No implementation needed. Must not leave } -// --------------------------------------------------------------------------- -// Not supported. -// --------------------------------------------------------------------------- -// +/*! + This method receives all or part of a snapshot of data to allow + calculation of an incremental backup. The snapshot is one that + was previously supplied by the data owner. The snapshot data + should be read from the location supplied. The snapshot data may + be larger than the location supplied in which case the routine + will be called repeatedly until all data has been supplied. + + Snapshot data will also be supplied as part of a restore operation + + @param aDrive the drive being backed up + @param aBuffer a pointer to the base of the location from whence + data can be copied. + @param aLastSection ETrue if this is the last section of snapshot + data, else EFalse. + + Not supported. +*/ void CHsBURActiveCallback::ReceiveSnapshotDataL( TDriveNumber /*aDrive*/, TDesC8& /*aBuffer*/, TBool /*aLastSection*/) { @@ -69,10 +86,20 @@ User::Leave( KErrNotSupported ); } -// --------------------------------------------------------------------------- -// Make a guess about data size. -// --------------------------------------------------------------------------- -// +/*! + This method returns the expected size of backup data that will be + supplied. If an incremental backup is underway then this method + then this method will not be called until after + ReceiveSnapshotDataL(). 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. + + @param aDrive the drive being backed up. + @return the size of the data that will be returned + + Make a guess about data size. +*/ TUint CHsBURActiveCallback::GetExpectedDataSize( TDriveNumber /*aDrive*/) { @@ -80,10 +107,26 @@ return 0; } -// --------------------------------------------------------------------------- -// Not supported. -// --------------------------------------------------------------------------- -// +/*! + This method returns a snapshot of data to accompany a backup. The + snapshot is expected to contain details on files / data being + backed up. The format of the snapshot is only meaningful to the + data owner. The snapshot will be supplied if the data owner is + asked for an incremental backup and for a restore operation. The + snapshot data should be copied to the location supplied. + + The snapshot data may be larger than the location supplied in + which case the routine will be called repeatedly until all data + has been retrieved. + + @param aDrive the drive being backed up + @param aBuffer a pointer to the base of the location where data + can be copied. + @param aFinished on return ETrue if all data has been returned + for this drive, else EFalse. + + Not supported. +*/ void CHsBURActiveCallback::GetSnapshotDataL( TDriveNumber /*aDrive*/, TPtr8& /*aBuffer*/, TBool& /*aFinished*/) { @@ -91,19 +134,33 @@ User::Leave( KErrNotSupported ); } -// --------------------------------------------------------------------------- -// Initialize for backup. -// --------------------------------------------------------------------------- -// +/*! + This method prepares the implementor to return backup data. It + will be followed by a sequence of calls to request the actual + data. + + @param aDrive the drive being backed up. + + Initialize for backup. +*/ void CHsBURActiveCallback::InitialiseGetBackupDataL( TDriveNumber /*aDrive*/) { iObserver->backupRestoreStarted(); } -// --------------------------------------------------------------------------- -// --------------------------------------------------------------------------- -// +/*! + This method requests a section of backup data. + InitialiseGetBackupDataL() will have been called previously to + specify the drive concerned. The data returned may be base or + incremental depending on the type of backup and the capability of + the data owner. + + @param aBuffer a pointer to the base of the location where data + can be copied. + @param aFinished on return ETrue if all data has been returned + for this drive, else EFalse. +*/ void CHsBURActiveCallback::GetBackupDataSectionL( TPtr8& /*aBuffer*/, TBool& aFinished) { @@ -111,10 +168,15 @@ aFinished = ETrue; } -// --------------------------------------------------------------------------- -// Initialize restore. -// --------------------------------------------------------------------------- -// +/*! + This method prepares the implementor to receive base restore data + for a drive. It will be followed by a sequence of calls to supply + the actual data. + + @param aDrive the drive being restored. + + Initialize restore. +*/ void CHsBURActiveCallback::InitialiseRestoreBaseDataL( TDriveNumber /*aDrive*/ ) { @@ -122,11 +184,19 @@ User::Leave( KErrNotSupported ); } -// --------------------------------------------------------------------------- -// Run state machine for restore. Receive stream from BUR engine and turn it -// to file(s). -// --------------------------------------------------------------------------- -// +/*! + This method receives a section of base restore data. + InitialiseRestoreBaseDataL() will have been called previously to + specify the drive concerned. + + @param aBuffer a pointer to the base of the location whence data + can be read. + @param aFinished ETrue if all data has been returned for this + drive, else EFalse. + + Run state machine for restore. Receive stream from BUR engine and turn it + to file(s). +*/ void CHsBURActiveCallback::RestoreBaseDataSectionL( TDesC8& /*aBuffer*/, TBool /*aFinished*/ ) { @@ -134,10 +204,16 @@ User::Leave( KErrNotSupported ); } -// --------------------------------------------------------------------------- -// Incremental restoration is not supported. -// --------------------------------------------------------------------------- -// +/*! + This method prepares the implementor to receive incremental + restore data for a drive. It will be followed by a sequence + of calls to supply the actual data. If multiple increments + are supplied then this methid will be called before each increment + + @param aDrive the drive being restored. + + Not supported. +*/ void CHsBURActiveCallback::InitialiseRestoreIncrementDataL( TDriveNumber /*aDrive*/) { @@ -145,10 +221,18 @@ User::Leave( KErrNotSupported ); } -// --------------------------------------------------------------------------- -// Incremental restoration is not supported. -// --------------------------------------------------------------------------- -// +/*! + This method receives a section of increment restore data. + InitialiseRestoreIncrementDataL() will have been called + previously to specify the drive concerned. + + @param aBuffer a pointer to the base of the location whence data + can be read. + @param aFinished ETrue if all data has been returned for this + increment, else EFalse. + + Not supported. +*/ void CHsBURActiveCallback::RestoreIncrementDataSectionL( TDesC8& /*aBuffer*/, TBool /*aFinished*/) { @@ -156,47 +240,56 @@ User::Leave( KErrNotSupported ); } -// --------------------------------------------------------------------------- -// Called when restore is complete - sets data back to initial state. -// --------------------------------------------------------------------------- -// +/*! + This method is called when all data to be restored has been + supplied. + + @param aDrive the drive being restored. + + Called when restore is complete - sets data back to initial state. +*/ void CHsBURActiveCallback::RestoreComplete(TDriveNumber /*aDrive*/) { // No implementation needed } -// --------------------------------------------------------------------------- -// Tidy up when operation is over. -// --------------------------------------------------------------------------- -// +/*! + This method is called if copying of data is terminated prematurely + to allow the implementor to tidy up. The same method applies to + all types of data and to backup and restore. + Tidy up when operation is over. +*/ void CHsBURActiveCallback::TerminateMultiStageOperation() { // No implementation needed } -// --------------------------------------------------------------------------- -// -// --------------------------------------------------------------------------- -// +/*! + Gets a 32-bit checksum for its 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 + @return the 32-bit checksum +*/ TUint CHsBURActiveCallback::GetDataChecksum(TDriveNumber /*aDrive*/) { // No implementation needed return 0; } -// --------------------------------------------------------------------------- -// C++ constructor. -// --------------------------------------------------------------------------- -// +/*! + C++ constructor. +*/ CHsBURActiveCallback::CHsBURActiveCallback(HsBackupRestoreObserver* observer) { iObserver = observer; } -// --------------------------------------------------------------------------- -// 2nd phase constructor. -// --------------------------------------------------------------------------- -// +/*! + 2nd phase constructor. +*/ void CHsBURActiveCallback::ConstructL() { }