diff -r 5cc91383ab1e -r 7333d7932ef7 installationservices/swtransactionservices/inc/sts.h --- /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 +#include +#include + +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