--- /dev/null Thu Jan 01 00:00:00 1970 +0000
+++ b/installationservices/swtransactionservices/inc/sts.h Tue Aug 31 15:21:33 2010 +0300
@@ -0,0 +1,243 @@
+/*
+* 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:
+*
+*/
+
+
+/**
+ @file
+ @publishedAll
+ @released
+*/
+
+
+#ifndef __STSSESSION_H__
+#define __STSSESSION_H__
+
+#include <scs/scsclient.h>
+#include <f32file.h>
+#include <usif/sts/stsdefs.h>
+
+namespace Usif
+{
+/**
+ The RStsSession class provides synchronous interface to the STS server.
+ This class wraps all the details of client-server communication with the STS server
+ residing in a separate process.
+
+ This class is intended to be used by STS client applications.
+
+ RStsSession class uses a unique transaction ID to identify operations belonging to different FS management transactions.
+ A transaction is a logical set of file system operations to be executed or rolled back atomically so that either all
+ operations fail or all operations succeed together.
+
+ Closing the session through RStsSession::Close() rolls back the transaction unless it was explicitly rolled back or committed
+ using the respective methods.
+
+ @publishedAll
+ @released
+ */
+
+ class RStsSession : public RScsClientBase
+ {
+ public:
+ IMPORT_C RStsSession();
+
+ /**
+ Opens a session to the STS server and creates a new transaction
+ @pre Neither CreateTransactionL nor OpenTransactionL have been invoked previously on this STS session.
+ @leave system wide error codes
+ @return the newly created transaction's unique ID
+ */
+ IMPORT_C TStsTransactionId CreateTransactionL();
+
+ /**
+ Opens a session to the STS server and joins an existing transaction.
+ This API should not be called throughout a valid session to the STS server
+ (i.e: CreateTransactionL() >> OpenTransactionL() or OpenTransactionL() >> OpenTransactionL())
+ @pre There is an active transaction with the supplied id.
+ @pre Neither CreateTransactionL nor OpenTransactionL have been invoked previously on this STS session.
+ @leave system wide error codes
+ @param aTransactionID the unique TInt32 transaction ID
+ */
+ IMPORT_C void OpenTransactionL(TStsTransactionId aTransactionID);
+
+ public:
+ //journalling related functions
+
+ /**
+ Notifies the STS server that a file or directory is being added to the file system.
+ Important note: the actual file operation is not executed. It has to be done
+ by the client code AFTER calling this API.
+ On commit the file is kept, on rollback it is removed.
+ @leave system wide error codes
+ @param aFileName - Fully qualified name of file or directory
+ */
+ IMPORT_C void RegisterNewL(const TDesC& aFileName);
+
+ /**
+ Instructs the STS server to create a new file.
+ The server creates a file and returns a handle to it.
+ On commit the file is kept, on rollback it is removed.
+ Important note: ownership of the newly created file is transfered from the server
+ to the client, so it is the client's responsibility to make sure that the file is
+ closed properly.
+ On creation the new file is empty.
+ @leave system wide error codes
+ @leave KErrAlreadyExist If the file already exists
+ @param aFileName - Fully qualified name of file
+ @param aFile - Reference of a file handle that is set to the new created file
+ @param aFileMode - File creation mode of the new file (see TFileMode documentation
+ for the possible mode or combination of modes)
+ */
+ IMPORT_C void CreateNewL(const TDesC& aFileName, RFile &aFile, TUint aCreateMode);
+
+ /**
+ Instructs the STS server to remove the specified file or directory.
+ Important note: the file is removed by the STS server. The client doesn't have to delete it
+ after a call to this API.
+ If the file does not exist, this function does nothing.
+ On commit the file remains permanently deleted, on rollback it is restored.
+ @leave system wide error codes
+ @param aFileName - Fully qualified name of file or directory
+ */
+ IMPORT_C void RemoveL(const TDesC& aFileName);
+
+ /**
+ Notifies the STS server that a temporary file is being added to the file system.
+ Important note: the actual file operation (i.e: creating the file at the target location) is not executed.
+ It has to be done by the client code AFTER calling this API.
+ The temporary file is deleted both on commit and on rollback.
+ @leave system wide error codes
+ @param aFileName - Fully qualified name of file or directory
+ */
+ IMPORT_C void RegisterTemporaryL(const TDesC& aFileName);
+
+ /**
+ Instructs the STS server to create a new temporary file.
+ The server creates a file and returns a handle to it.
+ The temporary file is deleted both on commit and on rollback.
+ Important note: ownership of the newly created file is transfered from the server
+ to the client, so it is the client's responsibility to make sure that the file is
+ closed properly.
+ On creation the new file is empty.
+
+ @leave system wide error codes
+ @leave KErrAlreadyExists A file with this name already exists
+ @param aFileName - Fully qualified name of file
+ @param aFile - Reference of a file handle that is set to the new created file
+ @param aFileMode - File creation mode of the new file (see TFileMode documentation
+ for the possible mode or combination of modes)
+ */
+ IMPORT_C void CreateTemporaryL(const TDesC& aFileName, RFile &aFile, TUint aCreateMode);
+
+ /**
+ Instructs the STS server to overwrite the target file.
+ If the file doesn't exist, an empty new file is created. If the file already exists, it is overwritten with an empty one.
+ A file handle to the new file is returned to the client in both cases.
+ Important note: ownership of the newly created file is transfered from the server
+ to the client, so it is the client's responsibility to make sure that the file is
+ closed properly.
+ On creation the new file is empty.
+ On commit the new file is kept. On rollback, the new file is removed and the original one is restored.
+
+ Please note that this function is recommended whenever the client generates the content for the new file.
+ If the new file's content is not generated (e.g. it is copied), it is recommended to use RemoveL followed by RegisterNewL.
+
+ @leave system wide error codes
+ @param aFileName - Fully qualified name of file or directory
+ @param aFile - Reference of a file handle that is set to the new created file
+ @param aFileMode - File creation mode of the new file (see TFileMode documentation
+ for the possible mode or combination of modes)
+ */
+ IMPORT_C void OverwriteL(const TDesC& aFileName, RFile &aFile, TUint aCreateMode);
+
+ /**
+ Commits the current file system transaction. After commiting a transaction its file
+ operations cannot be reverted.
+ Important note: this function implies closing the session to the server.
+ @leave system wide error codes
+ */
+ IMPORT_C void CommitL();
+
+ /**
+ Starts the recovery process for the transaction. All operations are reverted during roll back restoring
+ the file system to a state that it was in right before starting the transaction.
+ Important note: This function implies closing the session to the server;
+ any affected directories(including pre-existing) which were found empty will be deleted.
+ @leave system wide error codes
+ */
+ IMPORT_C void RollBackL();
+
+ /**
+ Returns the currently active transcation's id.
+ @leave system wide error codes
+ @leave KErrArgument If no transaction is active in this session - either it was not opened, or it has been already committed or rolled back.
+ */
+ IMPORT_C TStsTransactionId TransactionIdL();
+
+ /**
+ Closes this session to the STS server. Also rolls back the transaction in case neither CommitL not RollBackL
+ were invoked previously.
+ NOTE: Any affected directories(including pre-existing) which were found empty will be deleted.
+ */
+ IMPORT_C void Close();
+
+ private:
+ /**
+ Connects to the STS server and starts it if necessary
+ @leave system wide error codes
+ */
+ void ConnectL();
+
+ };//class RStsSession
+
+
+#ifndef SYMBIAN_ENABLE_SPLIT_HEADERS
+ /**
+ This class provides provides synchronous interface to the STS server for rolling back all pending transactions.
+
+ @internalTechnology
+ @released
+ */
+ class RStsRecoverySession : public RScsClientBase
+ {
+ public:
+ IMPORT_C RStsRecoverySession();
+
+ /**
+ Connects to the STS server and instructs it to roll back all pending transactions.
+ Does nothing if there are no pending transactions.
+ @leave system wide error codes
+ */
+ IMPORT_C void RollbackAllPendingL();
+
+ /**
+ Closes this session to the STS server.
+ */
+ IMPORT_C void Close();
+
+ private:
+ /**
+ Connects to the STS server and starts it if necessary
+ @leave system wide error codes
+ */
+ void ConnectL();
+
+ };//class RStsRecoverySession
+#endif //SYMBIAN_ENABLE_SPLIT_HEADERS
+ }////namespace Usif
+
+#endif