/*

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

*

*/

/**

 @file 

 @released

 @internalTechnology

*/

#ifndef __JOURNALFILE_H__

#define __JOURNALFILE_H__

#include <e32base.h>

#include <s32file.h>

#include "integrityservicesevent.h"

#include "integritytree.h"

namespace Usif

{

/**

 * The purpose of this class is to wrap a RFileWriteStream so that multiple

 * journal files can be held open by the client. This eliminates the need to 

 * constantly open and close files. 

 *

 * @released

 * @internalTechnology 

 */

class CJournalFile : public CBase

	{

	public:

		/**

		 * Constructs a new CJournalFile

		 *

		 * @param aFs reference to the supplied file system session

		 * @param aLoader reference to the RLoader session

		 * @param aFileName the filename of the journal

		 */

		static CJournalFile* NewL(RFs& aFs, RLoader& aLoader, const TDesC& aFileName, TInt aDrive);

		/**

		 * Constructs a new CJournalFile an places it on the cleanup stack

		 *

		 * @param aFs reference to the supplied file system session

		 * @param aLoader reference to the RLoader session

		 * @param aFileName the filename of the journal

		 */

		static CJournalFile* NewLC(RFs& aFs, RLoader& aLoader, const TDesC& aFileName, TInt aDrive);

		virtual ~CJournalFile();

		/**

		 * Records an event in this journal file.

		 *

		 * @param aEvent	the event to record

		 * @param aEvent	specifies whether the event should be serialized. If set to False, only the "in-memory" state of the journal is changed

		 This parameter is used in possible low memory or low disk space conditions.

		 */

		void EventL(TIntegrityServicesEvent aEvent, TBool aSerializeEventToJournal = ETrue);

		/**

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

		/**

		 * Checks if the file being removed has already been journalled for

		 * adding in the same journal file.  If it has been, nothing is

		 * journalled and the backup file name is set to zero length. Otherwise

		 * a record is journalled for the removal and the backup filename is

		 * set to the appropriate next name to use.

		 *

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

		 * @param aBackupFileName - the generated backup filename to return or

		 *                          zero-length if the file doesn't need to

		 *                          be backed up.

		 */

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

		/**

		 * Performs an operation on the file tree structure

		 *

		 * @param aFunc A function to apply to all nodes

		 * @param aTypeFilter The type of node to apply the function to

		 * @param aFailType The type of failure to induce, used exclusively in testing.

		 *

		 */

		void JournalOperationL(TTreeWalkFunctionL aFunc, TIntegrityServicesEvent aTypeFilter,

			CIntegrityServices::TFailType aFailType);

		/**

		 * Returns the last event found in the journal, used to determine how far the 

		 * installation progressed

		 *

		 * @return TIntegrityServicesEvent representing the last event in the file

		 */

		TIntegrityServicesEvent LastEvent() const;

		/**

		 * Checks that the filename is valid and complete

		 *

		 * @param aFs a reference to an open file system session

		 * @param aFileName the filename to check

		 * @return TInt representing the drive specified in this filename

		 */

		static TInt CheckFileNameL(RFs& aFs, const TDesC& aFileName);

		/**

		 * Accessor method that tells us which drive this journal file is on

		 */

		TInt Drive();

		/**

		 * Closes any file handle held open by this object. The journal file object

		 * must not be used again after this call.

		 */

		void Close();

	private:

		/**

		 * Constructor for CJournalFile

		 *

		 * @param aFs a reference to the supplied file system session

		 * @param aLoader reference to the RLoader session

		 */

		CJournalFile(RFs& aFs, RLoader& aLoader, TInt aDrive);

		/**

		 * Second phase constructor for CJournalFile

		 *

		 * @param aFileName the filename of the journal

		 */

		void ConstructL(const TDesC& aFileName);

		/**

		 * Reads and verifies the journal file

		 */

		void ReadL();

		/**

		 * Reads and verifies a journal entry from the supplied stream

		 *

		 * @param aJournalStream the stream to read

		 * @param aDrive used to verify files referred to are only from that drive

		 */

		void ReadEntryL(RFileReadStream& aJournalStream, TInt aDrive);

		/**

		 * Prepares to write to the journal file by opening an RFileWriteStream

		 */

		void PrepareToWriteL();

		/**

		 * Generates the next backup filename for this journal file.

		 */

		void NextBackupFileNameL(TDes& aBackupFileName);

		/**

		 * Reference to the supplied file system session

		 */

		RFs& iFs;

		/**

		 * Reference to RLoader server session

		 */

		RLoader& iLoader;

		/**

		 * The write stream for this journal

		 */

		RFileWriteStream iWriteStream;

		/**

		 * The last journal event recorded in the journal

		 */

		TIntegrityServicesEvent iLastEvent;

		CIntegrityTreeNode* iTreeRoot;

		/**

		 * The count of backup files in this journal

		 */

		TInt iBackupFilesCount;

		/**

		 * The filename of this journal

		 */

		TFileName iJournalFileName;

		/**

		 * The drive number this journal file is on

		 */

		TInt iDrive;

	};

} //namespace

#endif