--- /dev/null Thu Jan 01 00:00:00 1970 +0000
+++ b/installationservices/swtransactionservices/inc_private/integrityservices.h Fri Mar 19 09:33:35 2010 +0200
@@ -0,0 +1,331 @@
+/*
+* 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 CIntegrityServices
+*
+*/
+
+
+/**
+ @file
+ @released
+ @internalTechnology
+*/
+
+#ifndef __INTEGRITYSERVICES_H__
+#define __INTEGRITYSERVICES_H__
+
+#include <e32base.h>
+#include <f32file.h>
+#include <usif/sts/stsdefs.h>
+#include "integrityservicesevent.h"
+
+
+class RFs;
+
+namespace Usif
+{
+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.
+ */
+ static CIntegrityServices* NewL(TStsTransactionId aTransactionID);
+
+ /**
+ * Constructs a new CIntegrityServices object specifying a path for
+ * the journal files and puts it on the cleanup stack
+ * @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.
+ */
+ static CIntegrityServices* NewLC(TStsTransactionId aTransactionID);
+
+ ~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
+ */
+ void RegisterNewL(const TDesC& aFileName);
+
+ /**
+ * Instructs Integrity Services to create a new file.
+ * It is 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
+ * @param newFile - Reference of a file handle that is set to the newly created file
+ * @param aFileMode - File creation mode of the new file (see TFileMode documentation
+ * for the possible mode or combination of modes)
+ */
+ void CreateNewL(const TDesC& aFileName, RFile &newFile, TUint aFileMode);
+
+ /**
+ * 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
+ */
+ 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 including path
+ */
+ void RegisterTemporaryL(const TDesC& aFileName);
+
+ /**
+ * Instructs Integrity Services to create a new temporary file.
+ * It is removed if a rollback occurs. A record is created
+ * in the journal file on the appropriate drive.
+ *
+ * @param aFileName - Name of file including path
+ * @param newFile - Reference of a file handle that is set to the newly created file
+ * @param aFileMode - File creation mode of the new file (see TFileMode documentation
+ * for the possible mode or combination of modes)
+ */
+ void CreateTemporaryL(const TDesC& aFileName, RFile &newFile, TUint aFileMode);
+
+ /**
+ * Instructs Integrity Services to create a new file.
+ * If the file already exists it's removed to a backup location first before the new file is created.
+ * The newly created file is removed if a rollback occurs and the old one is restored.
+ * A record is created in the journal file on the appropriate drive.
+ * @param aFileName - Name of file or directory including path
+ * @param newFile - Reference of a file handle that is set to the newly created file
+ * @param aFileMode - File creation mode of the new file (see TFileMode documentation
+ * for the possible mode or combination of modes)
+ */
+ void OverwriteL(const TDesC& aFileName, RFile &newFile, TUint aFileMode);
+
+ /**
+ * 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.
+ */
+ 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 aRecordAllRollbackEvents- This parameter specifies whether we should record events during the rollback.
+ * This allows continuing the rollback in case it has been interrupted. In most cases, this flag should be "on", however
+ * if we failed a previous roll back due to low space or low memory, it can prevent any roll back due to lack of resources for recording
+ * the rollback events. In these cases, it should be set to "off".
+ *
+ */
+ void RollBackL(TBool aRecordAllRollbackEvents = ETrue);
+
+ /**
+ * Returns the TransactionID
+ *
+ * @return a TStsTransactionId representing the transaction
+ */
+ inline TStsTransactionId TransactionId() const;
+
+ /**
+ * Scans through the transaction path and returns a list if transaction ids that have been found.
+ *
+ * @param idArray - an array of TStsTransactionId in which the found ids are returned to the caller
+ */
+ static void GetListOfTransactionsL(RArray<TStsTransactionId>& aIdArray);
+
+ /**
+ * Roll back all transactions that it can find in the transaction path in the filesystem
+ * Important note: The function tries the best effort to roll back all transactions found.
+ * Failing to roll back one transaction doesn't influence the roll back of others,
+ * however if any of the transactions fail to roll back properly the function finally
+ * will leave with the latest error encountered. (After it has tried to roll back all!)
+ */
+ static void RollbackAllL();
+
+
+ /**
+ * 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);
+
+ /**
+ * 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
+ };
+
+ private:
+ /**
+ * 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.
+ */
+ CIntegrityServices(TStsTransactionId aTransactionID);
+
+ /**
+ * Second phase constructor for CIntegrityServices
+ *
+ */
+ void ConstructL();
+
+ /**
+ * 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);
+
+ 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.
+ */
+ TStsTransactionId iTransactionID;
+
+ /**
+ * The supplied path in which to read and write journal files.
+ */
+ TPath iJournalPath;
+
+ /**
+ The drive number for the system drive.
+ */
+ TDriveNumber iSystemDrive;
+
+ private:
+
+ RFs iFs;
+
+ RLoader iLoader;
+
+ public:
+ /**
+ * Failure type (used only by test code)
+ */
+ static TFailType iFailType;
+
+ /**
+ * Failure position (used only by test code)
+ */
+ static TFailPosition iFailPosition;
+
+ /**
+ * Specify the name of the file to fail on (used only in test code)
+ */
+ static TFileName iFailFileName;
+ static TBool iIsFailureTestingEnabled;
+
+ /**
+ * Test utility function
+ *
+ * @param aFailType The operation on which to fail
+ * @param aFailPosition The position at which to fail
+ * @param aFailFileName The filename on which to fail
+ */
+ static void SimulatePowerFailureL(TFailType aFailType, TFailPosition aPosition, const TDesC& aFailFileName);
+ };
+
+inline TStsTransactionId CIntegrityServices::TransactionId() const
+ {
+ return iTransactionID;
+ }
+
+} //namespace
+#endif