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 CIntegrityServices

    16 *

    17 */

    18 

    19 

    20 /**

    21  @file 

    22  @released

    23  @internalTechnology 

    24 */

    25 

    26 #ifndef __INTEGRITYSERVICES_H__

    27 #define __INTEGRITYSERVICES_H__

    28 

    29 #include <e32base.h>

    30 #include <f32file.h>

    31 

    32 #include "integrityservicesevent.h"

    33 

    34 

    35 

    36 namespace Swi

    37 {

    38 class CJournal;

    39 class CIntegrityTreeNode;

    40 

    41 /**

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

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

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

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

    46  * missing files.

    47  *

    48  * @released

    49  * @internalTechnology 

    50  */

    51 class CIntegrityServices : public CBase

    52 	{

    53 	public:

    54 

    55 		/**

    56 		 * Constructs a new CIntegrityServices object specifying a path for

    57 		 * the journal files

    58 		 *

    59 		 * @code

    60 		 *

    61 		 *	TTime currentTime;

    62 		 *	currentTime.UniversalTime();

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

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

    65 		 *											KIntegrityServicesPath);

    66 		 *

    67 		 * @endcode

    68 		 *

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

    70 		 *						 identify this transaction. It is suggested

    71 		 *						 that the client use the current time as the

    72 		 *						 unique ID. This value can then be shared

    73 		 *						 between different processes so that they use

    74 		 *						 the same journal.

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

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

    77 		 */

    78 		IMPORT_C static CIntegrityServices* NewL(TInt64 aTransactionID, const TDesC& aPath);

    79 		

    80 		/**

    81 		 * Constructs a new CIntegrityServices object specifying a path for

    82 		 * the journal files and puts it on the cleanup stack

    83 		 *

    84 		 * @code

    85 		 *

    86 		 *	TTime currentTime;

    87 		 *	currentTime.UniversalTime();

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

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

    90 		 *											KIntegrityServicesPath);

    91 		 *

    92 		 * @endcode

    93 		 *

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

    95 		 *						 identify this transaction. It is suggested

    96 		 *						 that the client use the current time as the

    97 		 *						 unique ID. This value can then be shared

    98 		 *						 between different processes so that they use

    99 		 *						 the same journal.

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

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

   102 		 */

   103 		IMPORT_C static CIntegrityServices* NewLC(TInt64 aTransactionID, const TDesC& aPath);

   104 		

   105 		IMPORT_C virtual ~CIntegrityServices();

   106 		

   107 		/**

   108 		 * Notifies Integrity Services that a file or directory is being added

   109 		 * so that it can be removed if a rollback occurs. A record is created

   110 		 * in the journal file on the appropriate drive.

   111 		 *

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

   113 		 */

   114 		IMPORT_C void AddL(const TDesC& aFileName);

   115 		

   116 		/**

   117 		 * Removes the specified file or directory, first backing it up before

   118 		 * deleting it. A record is created in the journal file on the

   119 		 * appropriate drive.

   120 		 *

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

   122 		 */

   123 		IMPORT_C void RemoveL(const TDesC& aFileName);

   124 		

   125 		/**

   126 		 * Notifies Integrity Services that a file or directory is being added

   127 		 * that must later be removed. A record is created in the journal file

   128 		 * on the appropriate drive.

   129 		 *

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

   131 		 */

   132 		IMPORT_C void TemporaryL(const TDesC& aFileName);

   133 

   134 		/**

   135 		 * Commits the current transaction by deleting backup, temporary and

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

   137 		 * operations shared between processes and spread across multiple

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

   139 		 * transaction is not present or has already been rolledback the

   140 		 * commit will fail.

   141 		 */

   142 		IMPORT_C void CommitL();

   143 		

   144 		/**

   145 		 * Starts the recovery process for all drives.

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

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

   148 		 * rolled back).

   149 		 *

   150 		 * @param aAllTransactions if ETrue all transactions in the current

   151 		 * 						   path are rolled back otherwise only this

   152 		 *						   transaction.

   153 		 */

   154 		IMPORT_C void RollBackL(TBool aAllTransactions);

   155 		

   156 		/**

   157 		 * Returns the TransactionID

   158 		 *

   159 		 * @return a TInt64 representing the transaction

   160 		 */

   161 		inline TInt64 TransactionId() const;

   162 

   163 

   164 		/**

   165 		 * Test if any journal files have started being rolled back.

   166 		 *

   167 		 * @return ETrue if any journal files have started being rolled back

   168 		 *         or EFalse otherwise.

   169 		 */

   170 		inline TBool StartedJournalRollback() const;

   171 	

   172 		/**

   173 		 * Failure types - indicate when to simulate power failure during

   174 		 * testing

   175 		 */

   176 		enum TFailType

   177 			{

   178 			EFailNone,

   179 			EFailAddingNewFile,

   180 			EFailRemovingFile,

   181 			EFailAddingTempFile,

   182 			EFailRestoringFile,

   183 			EFailDeletingFile,

   184 			EFailInstallComplete,

   185 			EFailNewFilesRemoved,

   186 			EFailOldFilesRestored,

   187 			EFailTempFilesRemoved,

   188 			EFailBackupFilesRemoved,

   189 			};

   190 		

   191 		/**

   192 		 * Failure position - indicate when to simulate power failure during

   193 		 * testing

   194 		 */	

   195 		enum TFailPosition

   196 			{

   197 			EBeforeJournal,

   198 			EAfterJournal,

   199 			EBeforeAction,

   200 			EAfterAction

   201 			};

   202 		

   203 	protected:

   204 		/**

   205 		 * Constructor for CIntegrityServices

   206 		 *

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

   208 		 *						 identify this transaction. It is suggested

   209 		 *						 that the client use the current time as the

   210 		 *						 unique ID. This value can then be shared

   211 		 *						 between different processes so that they use

   212 		 *						 the same journal.

   213 		 */

   214 		IMPORT_C CIntegrityServices(TInt64 aTransactionID);

   215 		

   216 		/**

   217 		 * Second phase constructor for CIntegrityServices

   218 		 *

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

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

   221 		 */

   222 		IMPORT_C void ConstructL(const TDesC& aPath);

   223 		

   224 		/**

   225 		 * Function only implemented in derived test class.

   226 		 *

   227 		 * @param aFailType		 The operation on which to fail

   228 		 * @param aFailPosition	 The position at which to fail

   229 		 * @param aFailFileName	 The filename on which to fail

   230 		 */

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

   232 				

   233 	private:

   234 

   235 		/**

   236 		 * Recovers the specified journal by either rolling back a failed

   237 		 * installation or completing it if past the point of no return

   238 		 * (ie backup files deleted). Processes the journal file on each drive

   239 		 * used by this transaction one after the other.

   240 		 *

   241 		 * @param aJournal	The journal to rollback

   242 		 *

   243 		 */

   244 		void RollBackJournalL(CJournal& aJournal);

   245 

   246   		/**

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

   248   		 * 

   249   		 * @param aJournal	The journal to rollback

   250   		 * @param aDrive	The drive to rollback

   251   		 */

   252   		void RollBackDriveL(CJournal& aJournal, TInt aDrive);

   253 

   254 		/**

   255 		 * Restores backup files to their original location

   256 		 *

   257 		 * @param aJournal	The journal for which files are to be restored

   258 		 */

   259 		void RestoreFilesL(CJournal& aJournal, TInt aDrive = -1);

   260 

   261 		/**

   262 		 * Function deletes all files in the list but does NOT fail 

   263 		 * if a file cannot be found

   264 		 *

   265 		 * @param aJournal	The journal for which files are to be deleted

   266 		 * @param aEvent	Files corresponding to this event are deleted.

   267 		 */

   268 		void DeleteFilesL(CJournal& aJournal, TIntegrityServicesEvent aEvent, TInt aDrive = -1);

   269 

   270 		/**

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

   272 		 * 

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

   274 		 */

   275 		static void NormalizeDirectoryName(TDes& aFileName);

   276 		

   277 		/**

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

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

   280 		@param aSource	the file to backup

   281 		@param aBackup	the name of the backup file

   282 		*/

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

   284 

   285 	private:

   286 	

   287 	    /**

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

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

   290 		 * recovered independantly.

   291 		 */

   292 		CJournal* iJournal;

   293 		

   294 		/**

   295 		 * Provided by the client to identify this transaction.

   296 		 */

   297 		TInt64 iTransactionID;

   298 		

   299 		/**

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

   301 		 */

   302 		TPath iJournalPath;

   303 

   304 		/**

   305 		 * True if rollback has been started on at least one journal file.

   306 		 */

   307 		 TBool iStartedJournalRollback;

   308 		 

   309 		 /**

   310 		 The drive number for the system drive.

   311 		 */

   312 		 TDriveNumber iSystemDrive;

   313 		 

   314 	protected:

   315 	

   316 		RFs iFs;

   317 		

   318 		RLoader iLoader;

   319 			

   320 	    /** 

   321 		 * Failure type (used only by test code)

   322 		 */

   323 		TFailType iFailType;

   324 		

   325 		/** 

   326 		 * Failure position (used only by test code)

   327 		 */

   328 		TFailPosition iFailPosition;

   329 		

   330 		/** 

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

   332 		 */

   333 		TFileName iFailFileName;

   334 		

   335 		friend class CIntegrityTreeNode;

   336 	};

   337 

   338 inline TInt64 CIntegrityServices::TransactionId() const

   339 	{

   340 	return iTransactionID;

   341 	}

   342 

   343 inline TBool CIntegrityServices::StartedJournalRollback() const

   344 	{

   345 	return iStartedJournalRollback;

   346 	}

   347 

   348 } //namespace

   349 #endif