/*

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

*

*/

/**

 @file 

 @released

 @internalTechnology 

*/

#ifndef __INTEGRITYSERVICES_H__

#define __INTEGRITYSERVICES_H__

#include <e32base.h>

#include <f32file.h>

#include <usif/sts/stsdefs.h>

#include "integrityservicesevent.h"

class RFs;

namespace Usif

{

class CJournal;

class CIntegrityTreeNode;

/**

 * This class maintains the integrity of installed software by ensuring that

 * the device is always left in a consistent state. If a software modification

 * process (install, upgrade or uninstall) is interrupted then that process is

 * reverted, returning the device to its original state with no orphaned or

 * missing files.

 *

 * @released

 * @internalTechnology 

 */

class CIntegrityServices : public CBase

	{

	public:

		/**

		 * Constructs a new CIntegrityServices object specifying a path for

		 * the journal files

		 *

		 * @code

		 *

		 *	TTime currentTime;

		 *	currentTime.UniversalTime();

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

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

		 *											KIntegrityServicesPath);

		 *

		 * @endcode

		 *

		 * @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.

		 */

		 static CIntegrityServices* NewL(TStsTransactionId aTransactionID);

		/**

		 * Constructs a new CIntegrityServices object specifying a path for

		 * the journal files and puts it on the cleanup stack

		 * @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.

		 */

		 static CIntegrityServices* NewLC(TStsTransactionId aTransactionID);

		 ~CIntegrityServices();

		/**

		 * 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 RegisterNewL(const TDesC& aFileName);

		/**

		 * Instructs Integrity Services to create a new file. 

		 * It is 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

		 * @param newFile - Reference of a file handle that is set to the newly created file

		 * @param aFileMode - File creation mode of the new file (see TFileMode documentation

		 *                    for the possible mode or combination of modes)

		 */

		 void CreateNewL(const TDesC& aFileName, RFile &newFile, TUint aFileMode);

		/**

		 * 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

		 */

		 void RemoveL(const TDesC& aFileName);

		/**

		 * 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 including path

		 */

		 void RegisterTemporaryL(const TDesC& aFileName);

		/**

		 * Instructs Integrity Services to create a new temporary file. 

		 * It is removed if a rollback occurs. A record is created

		 * in the journal file on the appropriate drive.

		 *

		 * @param aFileName - Name of file including path

		 * @param newFile - Reference of a file handle that is set to the newly created file

		 * @param aFileMode - File creation mode of the new file (see TFileMode documentation

		 *                    for the possible mode or combination of modes)

		 */

		 void CreateTemporaryL(const TDesC& aFileName, RFile &newFile, TUint aFileMode);

		/**

		 * Instructs Integrity Services to create a new file.

		 * If the file already exists it's removed to a backup location first before the new file is created. 

		 * The newly created file is removed if a rollback occurs and the old one is restored. 

		 * A record is created in the journal file on the appropriate drive.

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

		 * @param newFile - Reference of a file handle that is set to the newly created file

		 * @param aFileMode - File creation mode of the new file (see TFileMode documentation

		 *                    for the possible mode or combination of modes)

		 */

		 void OverwriteL(const TDesC& aFileName, RFile &newFile, TUint aFileMode);

		/**

		 * Commits the current transaction by deleting backup, temporary and

		 * journal files. The journal files are first refreshed so that

		 * operations shared between processes and spread across multiple

		 * drives are committed at the same time. If any journal file from this

		 * transaction is not present or has already been rolledback the

		 * commit will fail.

		 */

		 void CommitL();

		/**

		 * Starts the recovery process for all drives.

		 * Drive are rolled back independantly since removable media may be at

		 * a different state to internal drives (which may have already been 

		 * rolled back).

		 *

		 * @param aRecordAllRollbackEvents- This parameter specifies whether we should record events during the rollback.

		 *  This allows continuing the rollback in case it has been interrupted. In most cases, this flag should be "on", however

		 *   if we failed a previous roll back due to low space or low memory, it can prevent any roll back due to lack of resources for recording

		 *   the rollback events. In these cases, it should be set to "off".

		 *

		 */

		 void RollBackL(TBool aRecordAllRollbackEvents = ETrue);

		/**

		 * Returns the TransactionID

		 *

		 * @return a TStsTransactionId representing the transaction

		 */

		inline TStsTransactionId TransactionId() const;

		/**

		 * Scans through the transaction path and returns a list if transaction ids that have been found.

		 *  

		 * @param idArray - an array of TStsTransactionId in which the found ids are returned to the caller

		 */

		static void GetListOfTransactionsL(RArray<TStsTransactionId>& aIdArray);

		/**

		 * Roll back all transactions that it can find in the transaction path in the filesystem

		 * Important note: The function tries the best effort to roll back all transactions found. 

		 *                 Failing to roll back one transaction doesn't influence the roll back of others,

		 *                 however if any of the transactions fail to roll back properly the function finally

		 *                 will leave with the latest error encountered. (After it has tried to roll back all!)    

		 */

		static void RollbackAllL();

		/**

		 * Creates a backup file by copying the source to a defined backup name. This MUST be used for executables.

		 * The source files will then be deleted by invoking RLoader::Delete

		 * @param aSource	the file to backup

		 * @param aBackup	the name of the backup file

		*/

		void CopyToBackupL(const TDesC& aSource, const TDesC& aBackup);

		/**

		 * Failure types - indicate when to simulate power failure during

		 * testing

		 */

		enum TFailType

			{

			EFailNone,

			EFailAddingNewFile,

			EFailRemovingFile,

			EFailAddingTempFile,

			EFailRestoringFile,

			EFailDeletingFile,

			EFailInstallComplete,

			EFailNewFilesRemoved,

			EFailOldFilesRestored,

			EFailTempFilesRemoved,

			EFailBackupFilesRemoved,

			};

		/**

		 * Failure position - indicate when to simulate power failure during

		 * testing

		 */	

		enum TFailPosition

			{

			EBeforeJournal,

			EAfterJournal,

			EBeforeAction,

			EAfterAction

			};

	private:

		/**

		 * Constructor for 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.

		 */

		 CIntegrityServices(TStsTransactionId aTransactionID);

		/**

		 * Second phase constructor for CIntegrityServices

		 *

		 */

		 void ConstructL();

		/**

		 * Removes a trailing slash from directory name, if needed.

		 * 

		 * @param aFileName the filename to modify. If the filename does not represent a directory, it is not modified

		 */

		static void NormalizeDirectoryName(TDes& aFileName);

	private:

	    /**

		 * Pointer to the journal - uses log file(s) for persistant storage

		 * A log file is created on each drive involved so that they can be

		 * recovered independantly.

		 */

		CJournal* iJournal;

		/**

		 * Provided by the client to identify this transaction.

		 */

		TStsTransactionId iTransactionID;

		/**

		 * The supplied path in which to read and write journal files.

		 */

		TPath iJournalPath;

		 /**

		 The drive number for the system drive.

		 */

		 TDriveNumber iSystemDrive;

	private:

		RFs iFs;

		RLoader iLoader;

	public:

	    /** 

		 * Failure type (used only by test code)

		 */

		static TFailType iFailType;

		/** 

		 * Failure position (used only by test code)

		 */

		static TFailPosition iFailPosition;

		/** 

		 * Specify the name of the file to fail on (used only in test code)

		 */

		static TFileName iFailFileName;

		static TBool iIsFailureTestingEnabled;

		/**

		 * Test utility function

		 *

		 * @param aFailType		 The operation on which to fail

		 * @param aFailPosition	 The position at which to fail

		 * @param aFailFileName	 The filename on which to fail

		 */

		static void SimulatePowerFailureL(TFailType aFailType, TFailPosition aPosition, const TDesC& aFailFileName);

	};

inline TStsTransactionId CIntegrityServices::TransactionId() const

	{

	return iTransactionID;

	}

} //namespace

#endif