/*

* 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 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 "journalfile.h"

#include "integrityservicesevent.h"

class RFs;

namespace Swi

{

_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, TInt64 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, TInt64 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);

		/**

		 * 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();

		/**

		 * Opens the journal file on the specified drive, first reading and

		 * verifying the existing contents. The files remain open (and

		 * therefore locked) until FinishRollbackL() is called.

		 *

		 * @param aDrive the drive to rollback

		 */

		void StartRollbackL(TInt aDrive);

		/*

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

		 */

		void FinishRollbackL(TInt aDrive);

		/**

		 * Writes the event to all journal files

		 *

		 * @param aEvent the TEvent describing the current operation

		 */

		void WriteJournalEventL(TIntegrityServicesEvent aEvent);

		/**

		 * 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

		 */

		void WriteJournalEventL(TIntegrityServicesEvent aEvent, TInt aDrive);

		/**

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

		 * 

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

		 * @param aIntegrityServices The parent class for this operation, used for test purposes only

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

		 */

		void RestoreFilesL(TIntegrityServicesEvent aTypeFilter, CIntegrityServices& aIntegrityServices, CIntegrityServices::TFailType aFailType);

		/**

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

		 * 

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

		 * @param aIntegrityServices The parent class for this operation, used for test purposes only

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

		 */

		void DeleteFilesL(TIntegrityServicesEvent aTypeFilter, CIntegrityServices& aIntegrityServices, CIntegrityServices::TFailType aFailType);

		/**

		 * Performs a file restore 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 aIntegrityServices The parent class for this operation, used for test purposes only

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

		 */

		void RestoreFilesL(TIntegrityServicesEvent aTypeFilter, TInt aDrive,

			CIntegrityServices& aIntegrityServices, CIntegrityServices::TFailType aFailType);

		/**

		 * 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 aIntegrityServices The parent class for this operation, used for test purposes only

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

		 */

		void DeleteFilesL(TIntegrityServicesEvent aTypeFilter, TInt aDrive,

			CIntegrityServices& aIntegrityServices, CIntegrityServices::TFailType aFailType);

		/**

		 * 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 LastEvent() const;

		/**

		 * 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;

		/**

		 * @return a reference to the array of drives used by this journal

		 */

		inline const RArray<TInt>& Drives() const;

		/**

		 * @return a reference to the array of completed journal drives

		 */

		inline const RArray<TInt>& CompletedDrives() const;

		/**

		 * Ensures the drives are up to date with the underlying media.

		 */

		 void SynchL();

	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(TInt64 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.

		 *

		 */

		void DeleteJournalFileL(TInt aDrive);

		/**

		 * 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 UpdateDrivesArrayL(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();

	    /**

		 * 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 all drives used by this transaction

		 */

		RArray<TInt> iJournalDrives;

		/**

		 * The array of completed drives for this transaction

		 */

		RArray<TInt> iCompletedDrives;

		RArray<TInt> iAllDrives;

		/**

		 * Array of CJournalFile objects

		 */

		RPointerArray<CJournalFile> iJournalFiles;

	};

inline const RArray<TInt>& CJournal::Drives() const

	{

	return iJournalDrives;

	}

inline const RArray<TInt>& CJournal::CompletedDrives() const

	{

	return iCompletedDrives;

	}

} ///namespace

#endif