1 /*

     2 * Copyright (c) 2008-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 <usif/sts/stsdefs.h>

    31 #include "journalfile.h"

    32 #include "integrityservicesevent.h"

    33 

    34 class RFs;

    35 

    36 namespace Usif

    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, TStsTransactionId 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, TStsTransactionId 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 		 * Commits all journals for this transaction 

   143 		 * */

   144 		void CommitL();		

   145 				

   146 		/**

   147 		 * Performs a file restore operation on a single drive

   148 		 * 

   149 		 * @param aDrive The drive to apply this operation to

   150 		 */

   151 		

   152 		void RestoreFilesL(TInt aDrive);

   153 			

   154 		/**

   155 		 * Rolls back the journal on all drives

   156 		 @see CIntegrityServices::RollbackL on explanation for aRecordAllRollbackEvents

   157 		 */

   158 		void RollBackL(TBool aRecordAllRollbackEvents = ETrue);

   159 		

   160 		/**

   161 		 * Creates the <sysdrive>:\<journal path>\<transactionID>.drv file's name 

   162 		 * This file is used by the journal to keep track of affected drives.

   163 		 * @param aTransactionID The transaction id for which the filename is to be assembled

   164 		 * @param aPath The journal path to be used when assembling the filename.

   165 		 * @param aDrvFileName The assembled fully qualfied filename is returned in this descriptor

   166 		 */

   167 		 static void CreateDrvFileNameL(TStsTransactionId aTransactionID, const TDesC& aPath, TDes& aDrvFileName);

   168 			

   169 		/**

   170 		 * Creates drive independent journal file name eg: \<journal path>\<transactionID>.<journalfileextension> and appends to aJournalFileName  

   171 		 * @param aTransactionID The transaction id for which the filename is to be assembled

   172 		 * @param aPath The journal path to be used when assembling the filename.

   173 		 * @param aJournalFileName The assembled drive independent filename is appended to the end of this descriptor

   174 		 */

   175 		 static void CreateJournalFileNameL(TStsTransactionId aTransactionID, const TDesC& aPath, TDes& aJournalFileName);

   176 		 

   177 		 static TInt RecoverTransactionIdFromDrvFileName(const TDesC& aDrvFileName, TStsTransactionId& aTransactionID);

   178 		 

   179 	private:

   180 	

   181 		CJournal(RFs& aFs, RLoader& aLoader);

   182 		

   183 		/**

   184 		 * Second phase constructor for CJournal

   185 		 *

   186 		 * @param aTransactionID A unique ID provided by the client to

   187 		 *						 identify this transaction. It is suggested

   188 		 *						 that the client use the current time as the

   189 		 *						 unique ID. This value can then be shared

   190 		 *						 between different processes so that they use

   191 		 *						 the same journal.

   192 		 * @param aPath			 The path in which to read and write journal

   193 		 *						 files. eg "\\private\\SID\\"

   194 		 */

   195 		void ConstructL(TStsTransactionId aTransactionID, const TDesC& aPath);

   196 

   197 		/**

   198 		 * Closes then deletes all files used by this journal. Records completed

   199 		 * drives to the drives array.

   200 		 */

   201 		void DeleteJournalFilesL();

   202 		

   203 		/**

   204 		 * Removes the journal file from the indicated drive if possible.

   205 		 * @see CIntegrityServices::RollbackL on explanation for aRecordAllRollbackEvents		 

   206 		 *

   207 		 */

   208 

   209 		void DeleteJournalFileL(TInt aDrive, TBool aRecordAllRollbackEvents = ETrue );

   210 		

   211 		/**

   212 		 * Removes the drives file from the system drive for this journal.

   213 		 *

   214 		 */

   215 		

   216 		void DeleteDrivesFileL();

   217 		

   218 		/**

   219 		 * Reads the array of drives used by this transaction from a file.

   220 		 */

   221 		void RefreshDrivesArrayL();

   222 		

   223 		/**

   224 		 * Opens a CJournalFile object on this drive, locking the journal file

   225 		 * and preventing use by other instances of CIntegrityServices using

   226 		 * the same Transaction ID. If a journal file does not exist it will

   227 		 * be created.

   228 		 *

   229 		 * @param aDrive the drive on which to open the journal file

   230 		 */

   231 		TInt PrepareToWriteL(TInt aDrive);

   232 		

   233 		/**

   234 		 * Adds the specified drive to the drives array used by this

   235 		 * transaction an records it in a file.

   236 		 *

   237 		 * @param aDrive the drive to add

   238 		 */

   239 		void UpdateDrivesFileL(TInt aDrive);

   240 		

   241 		/**

   242 		 * Performs the initial read of the drives file, and creates journal file

   243 		 * objects for every present drive already used in this transaction.

   244 		 */

   245 		void InitJournalsL();

   246 		

   247 		/**

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

   249 		@see CIntegrityServices::RollbackL on explanation for aRecordAllRollbackEvents		 

   250 		 */

   251 		void FinishRollbackL(TInt aDrive, TBool aRecordAllRollbackEvents = ETrue );

   252 		

   253 		/**

   254 		 * Returns the last event found in the journal files.

   255 		 * (used to determine how far the installation progressed)

   256 		 *

   257 		 * @return TIntegrityServicesEvent representing the last event in the journal

   258 		 */

   259 		TIntegrityServicesEvent LastEventL() const;

   260 				

   261 		/**

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

   263 		 * 

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

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

   266 		 */	

   267 		void DeleteFilesL(TIntegrityServicesEvent aTypeFilter);

   268 

   269 		/**

   270 		 * Performs a file delete operation on a single drive

   271 		 * 

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

   273 		 * @param aDrive The drive to apply this operation to

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

   275 		 */

   276 		

   277 		void DeleteFilesL(TIntegrityServicesEvent aTypeFilter, TInt aDrive);		

   278 		

   279 		/**

   280 		 * Write a journal event to a specific drive

   281 		 *

   282 		 * @param aEvent the TEvent describing the current operation

   283 		 * @param aDrive The drive to write the event to

   284 		 * @param aSerializeEventToJournal Specifies whether the journal event should be serialized

   285 		 */

   286 		 

   287 		void WriteJournalEventL(TIntegrityServicesEvent aEvent, TInt aDrive, TBool aSerializeEventToJournal);

   288 		

   289   		/**

   290   		 * Performs recovery of the journal for a particular drive.

   291   		 * 

   292   		 * @param aDrive	The drive to rollback

   293 		 * @param aRecordAllRollbackEvents @see CIntegrityServices::RollbackL

   294   		 */

   295   		void RollBackDriveL(TInt aDrive, TBool aRecordAllRollbackEvents);

   296   		

   297 		/**

   298 		 * Writes the event to all journal files

   299 		 *

   300 		 * @param aEvent the TEvent describing the current operation

   301 		 */

   302 		void WriteJournalEventL(TIntegrityServicesEvent aEvent);

   303 		

   304 		/**

   305 		 * Opens all journal file(s) belonging to this transaction, first

   306 		 * reading and verifying the existing contents. The files remain

   307 		 * open (and therefore locked) until FinishCommitL() is called.

   308 		 */

   309 		void StartCommitL();

   310 		

   311 		/*

   312 		 * Closes, then deletes the journal file(s) opened with StartCommitL().

   313 		 */

   314 		void FinishCommitL();

   315 

   316 		/**

   317 		 * Retrieves the last event from the journal on a specific drive

   318 		 *

   319 		 * @param aDrive The drive for which to retrieve the last event

   320 		 * @return TIntegrityServicesEvent representing the last event in the journal

   321 		 */

   322 		

   323 		TIntegrityServicesEvent LastEventL(TInt aDrive) const;		

   324 

   325 		/**

   326 		 * Retrieves the matching index in iJournalFiles for a journal which matches aDrive. Returns KErrNotFound if there's no journal for the drive

   327 		 */

   328 

   329 		TInt FindJournalFileIndexL(TInt aDrive) const;

   330 		

   331 	    /**

   332 		 * Reference to opened file server session

   333 		 */

   334 		RFs& iFs;

   335 		

   336 		/**

   337 		 * Reference to RLoader server session

   338 		 */

   339 		RLoader& iLoader;

   340 		/**

   341 		 * The generic journal filename (does not include a drive)

   342 		 */

   343 		TFileName iJournalFileName;

   344 		

   345 		/**

   346 		 * The filename for the drives array (located on the system drive)

   347 		 * This file stores the drives used, and drives completed for this

   348 		 * transaction.

   349 		 */

   350 		TFileName iDriveArrayFileName;

   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 } ///namespace

   366 #endif