installationservices/swtransactionservices/inc_private/journal.h
changeset 24 84a16765cd86
--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/installationservices/swtransactionservices/inc_private/journal.h	Fri Mar 19 09:33:35 2010 +0200
@@ -0,0 +1,366 @@
+/*
+* 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