diff -r 000000000000 -r ba25891c3a9e installationservices/swi/inc/integrityservices.h --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/installationservices/swi/inc/integrityservices.h Thu Dec 17 08:51:10 2009 +0200 @@ -0,0 +1,349 @@ +/* +* 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 CIntegrityServices +* +*/ + + +/** + @file + @released + @internalTechnology +*/ + +#ifndef __INTEGRITYSERVICES_H__ +#define __INTEGRITYSERVICES_H__ + +#include +#include + +#include "integrityservicesevent.h" + + + +namespace Swi +{ +class CJournal; +class CIntegrityTreeNode; + +/** + * This class maintains the integrity of installed software by ensuring that + * the device is always left in a consistent state. If a software modification + * process (install, upgrade or uninstall) is interrupted then that process is + * reverted, returning the device to its original state with no orphaned or + * missing files. + * + * @released + * @internalTechnology + */ +class CIntegrityServices : public CBase + { + public: + + /** + * Constructs a new CIntegrityServices object specifying a path for + * the journal files + * + * @code + * + * TTime currentTime; + * currentTime.UniversalTime(); + * _LIT(KIntegrityServicesPath, "\\private\\SID\\"); + * iIntegrityServices = CIntegrityServices::NewL(currentTime.Int64(), + * KIntegrityServicesPath); + * + * @endcode + * + * @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\\" + */ + IMPORT_C static CIntegrityServices* NewL(TInt64 aTransactionID, const TDesC& aPath); + + /** + * Constructs a new CIntegrityServices object specifying a path for + * the journal files and puts it on the cleanup stack + * + * @code + * + * TTime currentTime; + * currentTime.UniversalTime(); + * _LIT(KIntegrityServicesPath, "\\private\\SID\\"); + * iIntegrityServices = CIntegrityServices::NewL(currentTime.Int64(), + * KIntegrityServicesPath); + * + * @endcode + * + * @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\\" + */ + IMPORT_C static CIntegrityServices* NewLC(TInt64 aTransactionID, const TDesC& aPath); + + IMPORT_C virtual ~CIntegrityServices(); + + /** + * 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 + */ + IMPORT_C 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 + */ + IMPORT_C void RemoveL(const TDesC& aFileName); + + /** + * 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 + */ + IMPORT_C void TemporaryL(const TDesC& aFileName); + + /** + * Commits the current transaction by deleting backup, temporary and + * journal files. The journal files are first refreshed so that + * operations shared between processes and spread across multiple + * drives are committed at the same time. If any journal file from this + * transaction is not present or has already been rolledback the + * commit will fail. + */ + IMPORT_C void CommitL(); + + /** + * Starts the recovery process for all drives. + * Drive are rolled back independantly since removable media may be at + * a different state to internal drives (which may have already been + * rolled back). + * + * @param aAllTransactions if ETrue all transactions in the current + * path are rolled back otherwise only this + * transaction. + */ + IMPORT_C void RollBackL(TBool aAllTransactions); + + /** + * Returns the TransactionID + * + * @return a TInt64 representing the transaction + */ + inline TInt64 TransactionId() const; + + + /** + * Test if any journal files have started being rolled back. + * + * @return ETrue if any journal files have started being rolled back + * or EFalse otherwise. + */ + inline TBool StartedJournalRollback() const; + + /** + * Failure types - indicate when to simulate power failure during + * testing + */ + enum TFailType + { + EFailNone, + EFailAddingNewFile, + EFailRemovingFile, + EFailAddingTempFile, + EFailRestoringFile, + EFailDeletingFile, + EFailInstallComplete, + EFailNewFilesRemoved, + EFailOldFilesRestored, + EFailTempFilesRemoved, + EFailBackupFilesRemoved, + }; + + /** + * Failure position - indicate when to simulate power failure during + * testing + */ + enum TFailPosition + { + EBeforeJournal, + EAfterJournal, + EBeforeAction, + EAfterAction + }; + + protected: + /** + * Constructor for 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. + */ + IMPORT_C CIntegrityServices(TInt64 aTransactionID); + + /** + * Second phase constructor for CIntegrityServices + * + * @param aPath The path in which to read and write journal + * files. eg "\\private\\SID\\" + */ + IMPORT_C void ConstructL(const TDesC& aPath); + + /** + * Function only implemented in derived test class. + * + * @param aFailType The operation on which to fail + * @param aFailPosition The position at which to fail + * @param aFailFileName The filename on which to fail + */ + virtual void SimulatePowerFailureL(TFailType aFailType, TFailPosition aPosition, const TDesC& aFailFileName); + + private: + + /** + * Recovers the specified journal by either rolling back a failed + * installation or completing it if past the point of no return + * (ie backup files deleted). Processes the journal file on each drive + * used by this transaction one after the other. + * + * @param aJournal The journal to rollback + * + */ + void RollBackJournalL(CJournal& aJournal); + + /** + * Performs recovery of the journal for a particular drive. + * + * @param aJournal The journal to rollback + * @param aDrive The drive to rollback + */ + void RollBackDriveL(CJournal& aJournal, TInt aDrive); + + /** + * Restores backup files to their original location + * + * @param aJournal The journal for which files are to be restored + */ + void RestoreFilesL(CJournal& aJournal, TInt aDrive = -1); + + /** + * Function deletes all files in the list but does NOT fail + * if a file cannot be found + * + * @param aJournal The journal for which files are to be deleted + * @param aEvent Files corresponding to this event are deleted. + */ + void DeleteFilesL(CJournal& aJournal, TIntegrityServicesEvent aEvent, TInt aDrive = -1); + + /** + * Removes a trailing slash from directory name, if needed. + * + * @param aFileName the filename to modify. If the filename does not represent a directory, it is not modified + */ + static void NormalizeDirectoryName(TDes& aFileName); + + /** + Creates a backup file by copying the source to a defined backup name. This MUST be used for executables. + The source files will then be deleted by invoking RLoader::Delete + @param aSource the file to backup + @param aBackup the name of the backup file + */ + void CopyToBackupL(const TDesC& aSource, const TDesC& aBackup); + + private: + + /** + * Pointer to the journal - uses log file(s) for persistant storage + * A log file is created on each drive involved so that they can be + * recovered independantly. + */ + CJournal* iJournal; + + /** + * Provided by the client to identify this transaction. + */ + TInt64 iTransactionID; + + /** + * The supplied path in which to read and write journal files. + */ + TPath iJournalPath; + + /** + * True if rollback has been started on at least one journal file. + */ + TBool iStartedJournalRollback; + + /** + The drive number for the system drive. + */ + TDriveNumber iSystemDrive; + + protected: + + RFs iFs; + + RLoader iLoader; + + /** + * Failure type (used only by test code) + */ + TFailType iFailType; + + /** + * Failure position (used only by test code) + */ + TFailPosition iFailPosition; + + /** + * Specify the name of the file to fail on (used only in test code) + */ + TFileName iFailFileName; + + friend class CIntegrityTreeNode; + }; + +inline TInt64 CIntegrityServices::TransactionId() const + { + return iTransactionID; + } + +inline TBool CIntegrityServices::StartedJournalRollback() const + { + return iStartedJournalRollback; + } + +} //namespace +#endif