installationservices/swi/source/integrityservices/journal.h
changeset 0 ba25891c3a9e
equal deleted inserted replaced
-1:000000000000 0:ba25891c3a9e
       
     1 /*
       
     2 * Copyright (c) 2004-2009 Nokia Corporation and/or its subsidiary(-ies).
       
     3 * All rights reserved.
       
     4 * This component and the accompanying materials are made available
       
     5 * under the terms of the License "Eclipse Public License v1.0"
       
     6 * which accompanies this distribution, and is available
       
     7 * at the URL "http://www.eclipse.org/legal/epl-v10.html".
       
     8 *
       
     9 * Initial Contributors:
       
    10 * Nokia Corporation - initial contribution.
       
    11 *
       
    12 * Contributors:
       
    13 *
       
    14 * Description: 
       
    15 * Definition of CJournal
       
    16 *
       
    17 */
       
    18 
       
    19 
       
    20 /**
       
    21  @file 
       
    22  @released
       
    23  @internalTechnology 
       
    24 */
       
    25 
       
    26 #ifndef __JOURNAL_H__
       
    27 #define __JOURNAL_H__
       
    28 
       
    29 #include <e32base.h>
       
    30 #include "journalfile.h"
       
    31 
       
    32 #include "integrityservicesevent.h"
       
    33 
       
    34 class RFs;
       
    35 
       
    36 namespace Swi
       
    37 {
       
    38 
       
    39 _LIT(KJournalExt, "log"); // extension for journal files on each drive
       
    40 _LIT(KDriveExt, "drv"); // extension for this transaction's drive array
       
    41 
       
    42 /**
       
    43  * The journal stores integrity services events and their related filenames
       
    44  * in files spread across several drives. Each drive has its own journal file
       
    45  * so that recovery of drives can occur independantly. This class handles both
       
    46  * the reading and writing of these files. The filename of each journal is:
       
    47  *
       
    48  * JournalPath|TransactionID
       
    49  *   |--------|--------|
       
    50  * ?:\????????\00000000.log
       
    51  *
       
    52  * @released
       
    53  * @internalTechnology 
       
    54  */
       
    55 class CJournal : public CBase
       
    56 	{
       
    57 	public:
       
    58 
       
    59 		/**
       
    60 		 * Constructs a new CJournal
       
    61 		 *
       
    62 		 * @code
       
    63 		 *
       
    64 		 *	TTime currentTime;
       
    65 		 *	currentTime.UniversalTime();
       
    66 		 *	_LIT(KIntegrityServicesPath, "\\private\\SID\\");
       
    67 		 *	iIntegrityServices = CIntegrityServices::NewL(currentTime.Int64(), 
       
    68 		 *											KIntegrityServicesPath);
       
    69 		 *
       
    70 		 * @endcode
       
    71 		 *
       
    72 		 * @param aFs reference to the file system provided by CIntegrityServices
       
    73 		 * @param aLoader reference to the RLoader provided by CIntegrityServices
       
    74 		 * @param aTransactionID A unique ID provided by the client to
       
    75 		 *						 identify this transaction. It is suggested
       
    76 		 *						 that the client use the current time as the
       
    77 		 *						 unique ID. This value can then be shared
       
    78 		 *						 between different processes so that they use
       
    79 		 *						 the same journal.
       
    80 		 * @param aPath			 The path in which to read and write journal
       
    81 		 *						 files. eg "\\private\\SID\\"
       
    82 		 */
       
    83 		static CJournal* NewL(RFs& aFs, RLoader& aLoader, TInt64 aTransactionID, const TDesC& aPath);
       
    84 		
       
    85 		/**
       
    86 		 * Constructs a new CJournal and places it on the cleanup stack
       
    87 		 *
       
    88 		 * @code
       
    89 		 *
       
    90 		 *	TTime currentTime;
       
    91 		 *	currentTime.UniversalTime();
       
    92 		 *	_LIT(KIntegrityServicesPath, "\\private\\SID\\");
       
    93 		 *	iIntegrityServices = CIntegrityServices::NewL(currentTime.Int64(), 
       
    94 		 *											KIntegrityServicesPath);
       
    95 		 *
       
    96 		 * @endcode
       
    97 		 *
       
    98 		 * @param aFs reference to the file system provided by CIntegrityServices
       
    99 		 * @param aLoader reference to the RLoader provided by CIntegrityServices
       
   100 		 * @param aTransactionID A unique ID provided by the client to
       
   101 		 *						 identify this transaction. It is suggested
       
   102 		 *						 that the client use the current time as the
       
   103 		 *						 unique ID. This value can then be shared
       
   104 		 *						 between different processes so that they use
       
   105 		 *						 the same journal.
       
   106 		 * @param aPath			 The path in which to read and write journal
       
   107 		 *						 files. eg "\\private\\SID\\"
       
   108 		 */
       
   109 		static CJournal* NewLC(RFs& aFs, RLoader& aLoader, TInt64 aTransactionID, const TDesC& aPath);
       
   110 		
       
   111 		virtual ~CJournal();
       
   112 
       
   113 		/**
       
   114 		 * Notifies Integrity Services that a file or directory is being added
       
   115 		 * so that it can be removed if a rollback occurs. A record is created
       
   116 		 * in the journal file on the appropriate drive.
       
   117 		 *
       
   118 		 * @param aFileName - Name of file or directory including path
       
   119 		 */
       
   120 		void AddL(const TDesC& aFileName);
       
   121 		
       
   122 		/**
       
   123 		 * Removes the specified file or directory, first backing it up before
       
   124 		 * deleting it. A record is created in the journal file on the
       
   125 		 * appropriate drive.
       
   126 		 *
       
   127 		 * @param aFileName - Name of file or directory including path
       
   128 		 * @param aFileName - the generated backup filename to return
       
   129 		 */
       
   130 		void RemoveL(const TDesC& aFileName, TDes& aBackupFileName);
       
   131 		
       
   132 		/**
       
   133 		 * Notifies Integrity Services that a file or directory is being added
       
   134 		 * that must later be removed. A record is created in the journal file
       
   135 		 * on the appropriate drive.
       
   136 		 *
       
   137 		 * @param aFileName - Name of file or directory including path
       
   138 		 */
       
   139 		void TemporaryL(const TDesC& aFileName);
       
   140 		
       
   141 		/**
       
   142 		 * Opens all journal file(s) belonging to this transaction, first
       
   143 		 * reading and verifying the existing contents. The files remain
       
   144 		 * open (and therefore locked) until FinishCommitL() is called.
       
   145 		 */
       
   146 		void StartCommitL();
       
   147 		
       
   148 		/*
       
   149 		 * Closes, then deletes the journal file(s) opened with StartCommitL().
       
   150 		 */
       
   151 		void FinishCommitL();
       
   152 		
       
   153 		/**
       
   154 		 * Opens the journal file on the specified drive, first reading and
       
   155 		 * verifying the existing contents. The files remain open (and
       
   156 		 * therefore locked) until FinishRollbackL() is called.
       
   157 		 *
       
   158 		 * @param aDrive the drive to rollback
       
   159 		 */
       
   160 		void StartRollbackL(TInt aDrive);
       
   161 		
       
   162 		/*
       
   163 		 * Closes, then deletes the journal file opened with StartRollbackL().
       
   164 		 */
       
   165 		void FinishRollbackL(TInt aDrive);
       
   166 		
       
   167 		/**
       
   168 		 * Writes the event to all journal files
       
   169 		 *
       
   170 		 * @param aEvent the TEvent describing the current operation
       
   171 		 */
       
   172 		void WriteJournalEventL(TIntegrityServicesEvent aEvent);
       
   173 		
       
   174 		/**
       
   175 		 * Write a journal event to a specific drive
       
   176 		 *
       
   177 		 * @param aEvent the TEvent describing the current operation
       
   178 		 * @param aDrive The drive to write the event to
       
   179 		 */
       
   180 		 
       
   181 		void WriteJournalEventL(TIntegrityServicesEvent aEvent, TInt aDrive);
       
   182 
       
   183 		/**
       
   184 		 * Performs a file restore operation on all drives referenced by this journal
       
   185 		 * 
       
   186 		 * @param aTypeFilter The type of file to apply this operation to
       
   187 		 * @param aIntegrityServices The parent class for this operation, used for test purposes only
       
   188 		 * @param aFailType The type of test failure to induce during testing
       
   189 		 */
       
   190 		
       
   191 		void RestoreFilesL(TIntegrityServicesEvent aTypeFilter, CIntegrityServices& aIntegrityServices, CIntegrityServices::TFailType aFailType);
       
   192 	
       
   193 		/**
       
   194 		 * Performs a file delete operation on all drives referenced by this journal
       
   195 		 * 
       
   196 		 * @param aTypeFilter The type of file to apply this operation to
       
   197 		 * @param aIntegrityServices The parent class for this operation, used for test purposes only
       
   198 		 * @param aFailType The type of test failure to induce during testing
       
   199 		 */
       
   200 	
       
   201 		void DeleteFilesL(TIntegrityServicesEvent aTypeFilter, CIntegrityServices& aIntegrityServices, CIntegrityServices::TFailType aFailType);
       
   202 
       
   203 		/**
       
   204 		 * Performs a file restore operation on a single drive
       
   205 		 * 
       
   206 		 * @param aTypeFilter The type of file to apply this operation to
       
   207 		 * @param aDrive The drive to apply this operation to
       
   208 		 * @param aIntegrityServices The parent class for this operation, used for test purposes only
       
   209 		 * @param aFailType The type of test failure to induce during testing
       
   210 		 */
       
   211 		
       
   212 		void RestoreFilesL(TIntegrityServicesEvent aTypeFilter, TInt aDrive,
       
   213 			CIntegrityServices& aIntegrityServices, CIntegrityServices::TFailType aFailType);
       
   214 	
       
   215 		/**
       
   216 		 * Performs a file delete operation on a single drive
       
   217 		 * 
       
   218 		 * @param aTypeFilter The type of file to apply this operation to
       
   219 		 * @param aDrive The drive to apply this operation to
       
   220 		 * @param aIntegrityServices The parent class for this operation, used for test purposes only
       
   221 		 * @param aFailType The type of test failure to induce during testing
       
   222 		 */
       
   223 		
       
   224 		void DeleteFilesL(TIntegrityServicesEvent aTypeFilter, TInt aDrive,
       
   225 			CIntegrityServices& aIntegrityServices, CIntegrityServices::TFailType aFailType);
       
   226 		
       
   227 		/**
       
   228 		 * Returns the last event found in the journal files.
       
   229 		 * (used to determine how far the installation progressed)
       
   230 		 *
       
   231 		 * @return TIntegrityServicesEvent representing the last event in the journal
       
   232 		 */
       
   233 		TIntegrityServicesEvent LastEvent() const;
       
   234 		
       
   235 		/**
       
   236 		 * Retrieves the last event from the journal on a specific drive
       
   237 		 *
       
   238 		 * @param aDrive The drive for which to retrieve the last event
       
   239 		 * @return TIntegrityServicesEvent representing the last event in the journal
       
   240 		 */
       
   241 		
       
   242 		TIntegrityServicesEvent LastEventL(TInt aDrive) const;
       
   243 
       
   244 		/**
       
   245 		 * @return a reference to the array of drives used by this journal
       
   246 		 */
       
   247 		inline const RArray<TInt>& Drives() const;
       
   248 		
       
   249 		/**
       
   250 		 * @return a reference to the array of completed journal drives
       
   251 		 */
       
   252 		inline const RArray<TInt>& CompletedDrives() const;
       
   253 
       
   254 		/**
       
   255 		 * Ensures the drives are up to date with the underlying media.
       
   256 		 */
       
   257 		 void SynchL();
       
   258 			
       
   259 	private:
       
   260 	
       
   261 		CJournal(RFs& aFs, RLoader& aLoader);
       
   262 		
       
   263 		/**
       
   264 		 * Second phase constructor for CJournal
       
   265 		 *
       
   266 		 * @param aTransactionID A unique ID provided by the client to
       
   267 		 *						 identify this transaction. It is suggested
       
   268 		 *						 that the client use the current time as the
       
   269 		 *						 unique ID. This value can then be shared
       
   270 		 *						 between different processes so that they use
       
   271 		 *						 the same journal.
       
   272 		 * @param aPath			 The path in which to read and write journal
       
   273 		 *						 files. eg "\\private\\SID\\"
       
   274 		 */
       
   275 		void ConstructL(TInt64 aTransactionID, const TDesC& aPath);
       
   276 
       
   277 		/**
       
   278 		 * Closes then deletes all files used by this journal. Records completed
       
   279 		 * drives to the drives array.
       
   280 		 */
       
   281 		void DeleteJournalFilesL();
       
   282 		
       
   283 		/**
       
   284 		 * Removes the journal file from the indicated drive if possible.
       
   285 		 *
       
   286 		 */
       
   287 		
       
   288 		void DeleteJournalFileL(TInt aDrive);
       
   289 		
       
   290 		/**
       
   291 		 * Removes the drives file from the system drive for this journal.
       
   292 		 *
       
   293 		 */
       
   294 		
       
   295 		void DeleteDrivesFileL();
       
   296 		
       
   297 		/**
       
   298 		 * Reads the array of drives used by this transaction from a file.
       
   299 		 */
       
   300 		void RefreshDrivesArrayL();
       
   301 		
       
   302 		/**
       
   303 		 * Opens a CJournalFile object on this drive, locking the journal file
       
   304 		 * and preventing use by other instances of CIntegrityServices using
       
   305 		 * the same Transaction ID. If a journal file does not exist it will
       
   306 		 * be created.
       
   307 		 *
       
   308 		 * @param aDrive the drive on which to open the journal file
       
   309 		 */
       
   310 		TInt PrepareToWriteL(TInt aDrive);
       
   311 		
       
   312 		/**
       
   313 		 * Adds the specified drive to the drives array used by this
       
   314 		 * transaction an records it in a file.
       
   315 		 *
       
   316 		 * @param aDrive the drive to add
       
   317 		 */
       
   318 		void UpdateDrivesArrayL(TInt aDrive);
       
   319 		
       
   320 		/**
       
   321 		 * Performs the initial read of the drives file, and creates journal file
       
   322 		 * objects for every present drive already used in this transaction.
       
   323 		 */
       
   324 		void InitJournalsL();
       
   325 		
       
   326 	    /**
       
   327 		 * Reference to opened file server session
       
   328 		 */
       
   329 		RFs& iFs;
       
   330 		
       
   331 		/**
       
   332 		 * Reference to RLoader server session
       
   333 		 */
       
   334 		RLoader& iLoader;
       
   335 		/**
       
   336 		 * The generic journal filename (does not include a drive)
       
   337 		 */
       
   338 		TFileName iJournalFileName;
       
   339 		
       
   340 		/**
       
   341 		 * The filename for the drives array (located on the system drive)
       
   342 		 * This file stores the drives used, and drives completed for this
       
   343 		 * transaction.
       
   344 		 */
       
   345 		TFileName iDriveArrayFileName;
       
   346 
       
   347 		/**
       
   348 		 * The array of all drives used by this transaction
       
   349 		 */
       
   350 		RArray<TInt> iJournalDrives;
       
   351 
       
   352 		/**
       
   353 		 * The array of completed drives for this transaction
       
   354 		 */
       
   355 		RArray<TInt> iCompletedDrives;
       
   356 		 
       
   357 		RArray<TInt> iAllDrives;
       
   358 		
       
   359 		/**
       
   360 		 * Array of CJournalFile objects
       
   361 		 */
       
   362 		RPointerArray<CJournalFile> iJournalFiles;
       
   363 	};
       
   364 
       
   365 inline const RArray<TInt>& CJournal::Drives() const
       
   366 	{
       
   367 	return iJournalDrives;
       
   368 	}
       
   369 
       
   370 inline const RArray<TInt>& CJournal::CompletedDrives() const
       
   371 	{
       
   372 	return iCompletedDrives;
       
   373 	}
       
   374 
       
   375 } ///namespace
       
   376 #endif