|
1 /* |
|
2 * Copyright (c) 2008-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 * |
|
16 */ |
|
17 |
|
18 |
|
19 /** |
|
20 @file |
|
21 @publishedAll |
|
22 @released |
|
23 */ |
|
24 |
|
25 |
|
26 #ifndef __STSSESSION_H__ |
|
27 #define __STSSESSION_H__ |
|
28 |
|
29 #include <scs/scsclient.h> |
|
30 #include <f32file.h> |
|
31 #include <usif/sts/stsdefs.h> |
|
32 |
|
33 namespace Usif |
|
34 { |
|
35 /** |
|
36 The RStsSession class provides synchronous interface to the STS server. |
|
37 This class wraps all the details of client-server communication with the STS server |
|
38 residing in a separate process. |
|
39 |
|
40 This class is intended to be used by STS client applications. |
|
41 |
|
42 RStsSession class uses a unique transaction ID to identify operations belonging to different FS management transactions. |
|
43 A transaction is a logical set of file system operations to be executed or rolled back atomically so that either all |
|
44 operations fail or all operations succeed together. |
|
45 |
|
46 Closing the session through RStsSession::Close() rolls back the transaction unless it was explicitly rolled back or committed |
|
47 using the respective methods. |
|
48 |
|
49 @publishedAll |
|
50 @released |
|
51 */ |
|
52 |
|
53 class RStsSession : public RScsClientBase |
|
54 { |
|
55 public: |
|
56 IMPORT_C RStsSession(); |
|
57 |
|
58 /** |
|
59 Opens a session to the STS server and creates a new transaction |
|
60 @pre Neither CreateTransactionL nor OpenTransactionL have been invoked previously on this STS session. |
|
61 @leave system wide error codes |
|
62 @return the newly created transaction's unique ID |
|
63 */ |
|
64 IMPORT_C TStsTransactionId CreateTransactionL(); |
|
65 |
|
66 /** |
|
67 Opens a session to the STS server and joins an existing transaction. |
|
68 This API should not be called throughout a valid session to the STS server |
|
69 (i.e: CreateTransactionL() >> OpenTransactionL() or OpenTransactionL() >> OpenTransactionL()) |
|
70 @pre There is an active transaction with the supplied id. |
|
71 @pre Neither CreateTransactionL nor OpenTransactionL have been invoked previously on this STS session. |
|
72 @leave system wide error codes |
|
73 @param aTransactionID the unique TInt32 transaction ID |
|
74 */ |
|
75 IMPORT_C void OpenTransactionL(TStsTransactionId aTransactionID); |
|
76 |
|
77 public: |
|
78 //journalling related functions |
|
79 |
|
80 /** |
|
81 Notifies the STS server that a file or directory is being added to the file system. |
|
82 Important note: the actual file operation is not executed. It has to be done |
|
83 by the client code AFTER calling this API. |
|
84 On commit the file is kept, on rollback it is removed. |
|
85 @leave system wide error codes |
|
86 @param aFileName - Fully qualified name of file or directory |
|
87 */ |
|
88 IMPORT_C void RegisterNewL(const TDesC& aFileName); |
|
89 |
|
90 /** |
|
91 Instructs the STS server to create a new file. |
|
92 The server creates a file and returns a handle to it. |
|
93 On commit the file is kept, on rollback it is removed. |
|
94 Important note: ownership of the newly created file is transfered from the server |
|
95 to the client, so it is the client's responsibility to make sure that the file is |
|
96 closed properly. |
|
97 On creation the new file is empty. |
|
98 @leave system wide error codes |
|
99 @leave KErrAlreadyExist If the file already exists |
|
100 @param aFileName - Fully qualified name of file |
|
101 @param aFile - Reference of a file handle that is set to the new created file |
|
102 @param aFileMode - File creation mode of the new file (see TFileMode documentation |
|
103 for the possible mode or combination of modes) |
|
104 */ |
|
105 IMPORT_C void CreateNewL(const TDesC& aFileName, RFile &aFile, TUint aCreateMode); |
|
106 |
|
107 /** |
|
108 Instructs the STS server to remove the specified file or directory. |
|
109 Important note: the file is removed by the STS server. The client doesn't have to delete it |
|
110 after a call to this API. |
|
111 If the file does not exist, this function does nothing. |
|
112 On commit the file remains permanently deleted, on rollback it is restored. |
|
113 @leave system wide error codes |
|
114 @param aFileName - Fully qualified name of file or directory |
|
115 */ |
|
116 IMPORT_C void RemoveL(const TDesC& aFileName); |
|
117 |
|
118 /** |
|
119 Notifies the STS server that a temporary file is being added to the file system. |
|
120 Important note: the actual file operation (i.e: creating the file at the target location) is not executed. |
|
121 It has to be done by the client code AFTER calling this API. |
|
122 The temporary file is deleted both on commit and on rollback. |
|
123 @leave system wide error codes |
|
124 @param aFileName - Fully qualified name of file or directory |
|
125 */ |
|
126 IMPORT_C void RegisterTemporaryL(const TDesC& aFileName); |
|
127 |
|
128 /** |
|
129 Instructs the STS server to create a new temporary file. |
|
130 The server creates a file and returns a handle to it. |
|
131 The temporary file is deleted both on commit and on rollback. |
|
132 Important note: ownership of the newly created file is transfered from the server |
|
133 to the client, so it is the client's responsibility to make sure that the file is |
|
134 closed properly. |
|
135 On creation the new file is empty. |
|
136 |
|
137 @leave system wide error codes |
|
138 @leave KErrAlreadyExists A file with this name already exists |
|
139 @param aFileName - Fully qualified name of file |
|
140 @param aFile - Reference of a file handle that is set to the new created file |
|
141 @param aFileMode - File creation mode of the new file (see TFileMode documentation |
|
142 for the possible mode or combination of modes) |
|
143 */ |
|
144 IMPORT_C void CreateTemporaryL(const TDesC& aFileName, RFile &aFile, TUint aCreateMode); |
|
145 |
|
146 /** |
|
147 Instructs the STS server to overwrite the target file. |
|
148 If the file doesn't exist, an empty new file is created. If the file already exists, it is overwritten with an empty one. |
|
149 A file handle to the new file is returned to the client in both cases. |
|
150 Important note: ownership of the newly created file is transfered from the server |
|
151 to the client, so it is the client's responsibility to make sure that the file is |
|
152 closed properly. |
|
153 On creation the new file is empty. |
|
154 On commit the new file is kept. On rollback, the new file is removed and the original one is restored. |
|
155 |
|
156 Please note that this function is recommended whenever the client generates the content for the new file. |
|
157 If the new file's content is not generated (e.g. it is copied), it is recommended to use RemoveL followed by RegisterNewL. |
|
158 |
|
159 @leave system wide error codes |
|
160 @param aFileName - Fully qualified name of file or directory |
|
161 @param aFile - Reference of a file handle that is set to the new created file |
|
162 @param aFileMode - File creation mode of the new file (see TFileMode documentation |
|
163 for the possible mode or combination of modes) |
|
164 */ |
|
165 IMPORT_C void OverwriteL(const TDesC& aFileName, RFile &aFile, TUint aCreateMode); |
|
166 |
|
167 /** |
|
168 Commits the current file system transaction. After commiting a transaction its file |
|
169 operations cannot be reverted. |
|
170 Important note: this function implies closing the session to the server. |
|
171 @leave system wide error codes |
|
172 */ |
|
173 IMPORT_C void CommitL(); |
|
174 |
|
175 /** |
|
176 Starts the recovery process for the transaction. All operations are reverted during roll back restoring |
|
177 the file system to a state that it was in right before starting the transaction. |
|
178 Important note: This function implies closing the session to the server; |
|
179 any affected directories(including pre-existing) which were found empty will be deleted. |
|
180 @leave system wide error codes |
|
181 */ |
|
182 IMPORT_C void RollBackL(); |
|
183 |
|
184 /** |
|
185 Returns the currently active transcation's id. |
|
186 @leave system wide error codes |
|
187 @leave KErrArgument If no transaction is active in this session - either it was not opened, or it has been already committed or rolled back. |
|
188 */ |
|
189 IMPORT_C TStsTransactionId TransactionIdL(); |
|
190 |
|
191 /** |
|
192 Closes this session to the STS server. Also rolls back the transaction in case neither CommitL not RollBackL |
|
193 were invoked previously. |
|
194 NOTE: Any affected directories(including pre-existing) which were found empty will be deleted. |
|
195 */ |
|
196 IMPORT_C void Close(); |
|
197 |
|
198 private: |
|
199 /** |
|
200 Connects to the STS server and starts it if necessary |
|
201 @leave system wide error codes |
|
202 */ |
|
203 void ConnectL(); |
|
204 |
|
205 };//class RStsSession |
|
206 |
|
207 |
|
208 #ifndef SYMBIAN_ENABLE_SPLIT_HEADERS |
|
209 /** |
|
210 This class provides provides synchronous interface to the STS server for rolling back all pending transactions. |
|
211 |
|
212 @internalTechnology |
|
213 @released |
|
214 */ |
|
215 class RStsRecoverySession : public RScsClientBase |
|
216 { |
|
217 public: |
|
218 IMPORT_C RStsRecoverySession(); |
|
219 |
|
220 /** |
|
221 Connects to the STS server and instructs it to roll back all pending transactions. |
|
222 Does nothing if there are no pending transactions. |
|
223 @leave system wide error codes |
|
224 */ |
|
225 IMPORT_C void RollbackAllPendingL(); |
|
226 |
|
227 /** |
|
228 Closes this session to the STS server. |
|
229 */ |
|
230 IMPORT_C void Close(); |
|
231 |
|
232 private: |
|
233 /** |
|
234 Connects to the STS server and starts it if necessary |
|
235 @leave system wide error codes |
|
236 */ |
|
237 void ConnectL(); |
|
238 |
|
239 };//class RStsRecoverySession |
|
240 #endif //SYMBIAN_ENABLE_SPLIT_HEADERS |
|
241 }////namespace Usif |
|
242 |
|
243 #endif |