/*

* Copyright (c) 2008-2009 Nokia Corporation and/or its subsidiary(-ies).

* All rights reserved.

* This component and the accompanying materials are made available

* under the terms of the License "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: 

* Definition of CJournal

*

*/

/**

 @file 

 @released

 @internalTechnology 

*/

#ifndef __JOURNAL_H__

#define __JOURNAL_H__

#include <e32base.h>

#include <usif/sts/stsdefs.h>

#include "journalfile.h"

#include "integrityservicesevent.h"

class RFs;

namespace Usif

{

_LIT(KJournalExt, "log"); // extension for journal files on each drive

_LIT(KDriveExt, "drv"); // extension for this transaction's drive array

/**

 * The journal stores integrity services events and their related filenames

 * in files spread across several drives. Each drive has its own journal file

 * so that recovery of drives can occur independantly. This class handles both

 * the reading and writing of these files. The filename of each journal is:

 *

 * JournalPath|TransactionID

 *   |--------|--------|

 * ?:\????????\00000000.log

 *

 * @released

 * @internalTechnology 

 */

class CJournal : public CBase

	{

	public:

		/**

		 * Constructs a new CJournal

		 *

		 * @code

		 *

		 *	TTime currentTime;

		 *	currentTime.UniversalTime();

		 *	_LIT(KIntegrityServicesPath, "\\private\\SID\\");

		 *	iIntegrityServices = CIntegrityServices::NewL(currentTime.Int64(), 

		 *											KIntegrityServicesPath);

		 *

		 * @endcode

		 *

		 * @param aFs reference to the file system provided by CIntegrityServices

		 * @param aLoader reference to the RLoader provided by CIntegrityServices

		 * @param aTransactionID A unique ID provided by the client to

		 *						 identify this transaction. It is suggested

		 *						 that the client use the current time as the

		 *						 unique ID. This value can then be shared

		 *						 between different processes so that they use

		 *						 the same journal.

		 * @param aPath			 The path in which to read and write journal

		 *						 files. eg "\\private\\SID\\"

		 */

		static CJournal* NewL(RFs& aFs, RLoader& aLoader, TStsTransactionId aTransactionID, const TDesC& aPath);

		/**

		 * Constructs a new CJournal and places it on the cleanup stack

		 *

		 * @code

		 *

		 *	TTime currentTime;

		 *	currentTime.UniversalTime();

		 *	_LIT(KIntegrityServicesPath, "\\private\\SID\\");

		 *	iIntegrityServices = CIntegrityServices::NewL(currentTime.Int64(), 

		 *											KIntegrityServicesPath);

		 *

		 * @endcode

		 *

		 * @param aFs reference to the file system provided by CIntegrityServices

		 * @param aLoader reference to the RLoader provided by CIntegrityServices

		 * @param aTransactionID A unique ID provided by the client to

		 *						 identify this transaction. It is suggested

		 *						 that the client use the current time as the

		 *						 unique ID. This value can then be shared

		 *						 between different processes so that they use

		 *						 the same journal.

		 * @param aPath			 The path in which to read and write journal

		 *						 files. eg "\\private\\SID\\"

		 */

		static CJournal* NewLC(RFs& aFs, RLoader& aLoader, TStsTransactionId aTransactionID, const TDesC& aPath);

		virtual ~CJournal();

		/**

		 * Notifies Integrity Services that a file or directory is being added

		 * so that it can be removed if a rollback occurs. A record is created

		 * in the journal file on the appropriate drive.

		 *

		 * @param aFileName - Name of file or directory including path

		 */

		void AddL(const TDesC& aFileName);

		/**

		 * Removes the specified file or directory, first backing it up before

		 * deleting it. A record is created in the journal file on the

		 * appropriate drive.

		 *

		 * @param aFileName - Name of file or directory including path

		 * @param aFileName - the generated backup filename to return

		 */

		void RemoveL(const TDesC& aFileName, TDes& aBackupFileName);

		/**

		 * Notifies Integrity Services that a file or directory is being added

		 * that must later be removed. A record is created in the journal file

		 * on the appropriate drive.

		 *

		 * @param aFileName - Name of file or directory including path

		 */

		void TemporaryL(const TDesC& aFileName);

		/** 

		 * Commits all journals for this transaction 

		 * */

		void CommitL();		

		/**

		 * Performs a file restore operation on a single drive

		 * 

		 * @param aDrive The drive to apply this operation to

		 */

		void RestoreFilesL(TInt aDrive);

		/**

		 * Rolls back the journal on all drives

		 @see CIntegrityServices::RollbackL on explanation for aRecordAllRollbackEvents

		 */

		void RollBackL(TBool aRecordAllRollbackEvents = ETrue);

		/**

		 * Creates the <sysdrive>:\<journal path>\<transactionID>.drv file's name 

		 * This file is used by the journal to keep track of affected drives.

		 * @param aTransactionID The transaction id for which the filename is to be assembled

		 * @param aPath The journal path to be used when assembling the filename.

		 * @param aDrvFileName The assembled fully qualfied filename is returned in this descriptor

		 */

		 static void CreateDrvFileNameL(TStsTransactionId aTransactionID, const TDesC& aPath, TDes& aDrvFileName);

		/**

		 * Creates drive independent journal file name eg: \<journal path>\<transactionID>.<journalfileextension> and appends to aJournalFileName  

		 * @param aTransactionID The transaction id for which the filename is to be assembled

		 * @param aPath The journal path to be used when assembling the filename.

		 * @param aJournalFileName The assembled drive independent filename is appended to the end of this descriptor

		 */

		 static void CreateJournalFileNameL(TStsTransactionId aTransactionID, const TDesC& aPath, TDes& aJournalFileName);

		 static TInt RecoverTransactionIdFromDrvFileName(const TDesC& aDrvFileName, TStsTransactionId& aTransactionID);

	private:

		CJournal(RFs& aFs, RLoader& aLoader);

		/**

		 * Second phase constructor for CJournal

		 *

		 * @param aTransactionID A unique ID provided by the client to

		 *						 identify this transaction. It is suggested

		 *						 that the client use the current time as the

		 *						 unique ID. This value can then be shared

		 *						 between different processes so that they use

		 *						 the same journal.

		 * @param aPath			 The path in which to read and write journal

		 *						 files. eg "\\private\\SID\\"

		 */

		void ConstructL(TStsTransactionId aTransactionID, const TDesC& aPath);

		/**

		 * Closes then deletes all files used by this journal. Records completed

		 * drives to the drives array.

		 */

		void DeleteJournalFilesL();

		/**

		 * Removes the journal file from the indicated drive if possible.

		 * @see CIntegrityServices::RollbackL on explanation for aRecordAllRollbackEvents		 

		 *

		 */

		void DeleteJournalFileL(TInt aDrive, TBool aRecordAllRollbackEvents = ETrue );

		/**

		 * Removes the drives file from the system drive for this journal.

		 *

		 */

		void DeleteDrivesFileL();

		/**

		 * Reads the array of drives used by this transaction from a file.

		 */

		void RefreshDrivesArrayL();

		/**

		 * Opens a CJournalFile object on this drive, locking the journal file

		 * and preventing use by other instances of CIntegrityServices using

		 * the same Transaction ID. If a journal file does not exist it will

		 * be created.

		 *

		 * @param aDrive the drive on which to open the journal file

		 */

		TInt PrepareToWriteL(TInt aDrive);

		/**

		 * Adds the specified drive to the drives array used by this

		 * transaction an records it in a file.

		 *

		 * @param aDrive the drive to add

		 */

		void UpdateDrivesFileL(TInt aDrive);

		/**

		 * Performs the initial read of the drives file, and creates journal file

		 * objects for every present drive already used in this transaction.

		 */

		void InitJournalsL();

		/**

		 * Closes, then deletes the journal file opened with StartRollbackL().

		@see CIntegrityServices::RollbackL on explanation for aRecordAllRollbackEvents		 

		 */

		void FinishRollbackL(TInt aDrive, TBool aRecordAllRollbackEvents = ETrue );

		/**

		 * Returns the last event found in the journal files.

		 * (used to determine how far the installation progressed)

		 *

		 * @return TIntegrityServicesEvent representing the last event in the journal

		 */

		TIntegrityServicesEvent LastEventL() const;

		/**

		 * Performs a file delete operation on all drives referenced by this journal

		 * 

		 * @param aTypeFilter The type of file to apply this operation to

		 * @param aFailType The type of test failure to induce during testing

		 */	

		void DeleteFilesL(TIntegrityServicesEvent aTypeFilter);

		/**

		 * Performs a file delete operation on a single drive

		 * 

		 * @param aTypeFilter The type of file to apply this operation to

		 * @param aDrive The drive to apply this operation to

		 * @param aFailType The type of test failure to induce during testing

		 */

		void DeleteFilesL(TIntegrityServicesEvent aTypeFilter, TInt aDrive);		

		/**

		 * Write a journal event to a specific drive

		 *

		 * @param aEvent the TEvent describing the current operation

		 * @param aDrive The drive to write the event to

		 * @param aSerializeEventToJournal Specifies whether the journal event should be serialized

		 */

		void WriteJournalEventL(TIntegrityServicesEvent aEvent, TInt aDrive, TBool aSerializeEventToJournal);

  		/**

  		 * Performs recovery of the journal for a particular drive.

  		 * 

  		 * @param aDrive	The drive to rollback

		 * @param aRecordAllRollbackEvents @see CIntegrityServices::RollbackL

  		 */

  		void RollBackDriveL(TInt aDrive, TBool aRecordAllRollbackEvents);

		/**

		 * Writes the event to all journal files

		 *

		 * @param aEvent the TEvent describing the current operation

		 */

		void WriteJournalEventL(TIntegrityServicesEvent aEvent);

		/**

		 * Opens all journal file(s) belonging to this transaction, first

		 * reading and verifying the existing contents. The files remain

		 * open (and therefore locked) until FinishCommitL() is called.

		 */

		void StartCommitL();

		/*

		 * Closes, then deletes the journal file(s) opened with StartCommitL().

		 */

		void FinishCommitL();

		/**

		 * Retrieves the last event from the journal on a specific drive

		 *

		 * @param aDrive The drive for which to retrieve the last event

		 * @return TIntegrityServicesEvent representing the last event in the journal

		 */

		TIntegrityServicesEvent LastEventL(TInt aDrive) const;		

		/**

		 * Retrieves the matching index in iJournalFiles for a journal which matches aDrive. Returns KErrNotFound if there's no journal for the drive

		 */

		TInt FindJournalFileIndexL(TInt aDrive) const;

	    /**

		 * Reference to opened file server session

		 */

		RFs& iFs;

		/**

		 * Reference to RLoader server session

		 */

		RLoader& iLoader;

		/**

		 * The generic journal filename (does not include a drive)

		 */

		TFileName iJournalFileName;

		/**

		 * The filename for the drives array (located on the system drive)

		 * This file stores the drives used, and drives completed for this

		 * transaction.

		 */

		TFileName iDriveArrayFileName;

		/**

		 * The array of completed drives for this transaction

		 */

		RArray<TInt> iCompletedDrives;

		RArray<TInt> iAllDrives;

		/**

		 * Array of CJournalFile objects

		 */

		RPointerArray<CJournalFile> iJournalFiles;

	};

} ///namespace

#endif