|
1 // Copyright (c) 1998-2009 Nokia Corporation and/or its subsidiary(-ies). |
|
2 // All rights reserved. |
|
3 // This component and the accompanying materials are made available |
|
4 // under the terms of "Eclipse Public License v1.0" |
|
5 // which accompanies this distribution, and is available |
|
6 // at the URL "http://www.eclipse.org/legal/epl-v10.html". |
|
7 // |
|
8 // Initial Contributors: |
|
9 // Nokia Corporation - initial contribution. |
|
10 // |
|
11 // Contributors: |
|
12 // |
|
13 // Description: |
|
14 // Client incremental class |
|
15 // |
|
16 // |
|
17 |
|
18 #include "UD_STD.H" |
|
19 |
|
20 // Class RDbIncremental |
|
21 |
|
22 /** Releases the resources used by the incremental operations object. If the operation |
|
23 is not yet complete, then the operation is abandoned and the database is rolled |
|
24 back to its state before the operation started. */ |
|
25 EXPORT_C void RDbIncremental::Close() |
|
26 { |
|
27 iState.Close(); |
|
28 } |
|
29 |
|
30 /** Performs the next step in the incremental operation, returning when the step |
|
31 is complete. |
|
32 |
|
33 @param aStep Initially, contains the value returned from any of the initiating |
|
34 functions or the last call to perform an operational step. On return, contains |
|
35 a value which is less than or equal to the initial value. If it equals 0, |
|
36 then the operation has completed successfully and the incremental object should |
|
37 be closed. |
|
38 @return KErrNone if successful, or one of the DBMS database error codes. If |
|
39 this indicates an error, then the incremental object should be closed and |
|
40 the operation aborted. */ |
|
41 EXPORT_C TInt RDbIncremental::Next(TInt& aStep) |
|
42 { |
|
43 __ASSERT_ALWAYS(aStep>0,Panic(EDbInvalidIncrementalStep)); |
|
44 TRAPD(r,iState->NextL(aStep)); |
|
45 return r; |
|
46 } |
|
47 |
|
48 /** Performs the next step in the incremental operation, returning immediately |
|
49 and signalling the request status when the step is complete. |
|
50 |
|
51 This function is most effectively used when the incremental operation is packaged |
|
52 as an active object. |
|
53 |
|
54 Note that the step parameter is packaged to enable this API to work for asynchronous |
|
55 calls in client/server implementations of DBMS. |
|
56 |
|
57 @param aStep Initially, contains the value returned from any of the initiating |
|
58 functions or the last call to perform an operational step. On return, contains |
|
59 a value which is less than or equal to the initial value. If it equals 0, |
|
60 then the operation has completed successfully and the incremental object should |
|
61 be closed. |
|
62 @param aStatus The request status used to contain completion information for |
|
63 the function. On completion, contains the completion status or one of the |
|
64 DBMS database error codes. If this indicates an error, then the incremental |
|
65 object should be closed and the operation aborted. |
|
66 @see TPckgBuf */ |
|
67 EXPORT_C void RDbIncremental::Next(TPckgBuf<TInt>& aStep,TRequestStatus& aStatus) |
|
68 { |
|
69 __ASSERT_ALWAYS(aStep.operator()()>0,Panic(EDbInvalidIncrementalStep)); |
|
70 iState->Next(aStep,aStatus); |
|
71 } |
|
72 |
|
73 LOCAL_C TInt Utility(RDbHandle<CDbIncremental>& aInc |
|
74 ,RDbHandle<CDbDatabase>& aDb,TInt& aStep |
|
75 ,CDbDatabase::TUtility aType) |
|
76 { |
|
77 TRAPD(r,aInc=aDb->UtilityL(aType,aStep)); |
|
78 return r; |
|
79 } |
|
80 |
|
81 /** Initiates a database recovery operation. |
|
82 |
|
83 This is the incremental version of RDbDatabase::Recover(). |
|
84 Recover() will try to rebuild database indexes if they are broken. |
|
85 If the database data is corrupted, it cannot be recovered. |
|
86 |
|
87 @param aDatabase The database to recover. |
|
88 @param aStep On return, contains the initial step count for the incremental |
|
89 operation. This value should be passed in to subsequent calls to NextL(). |
|
90 |
|
91 @return KErrNone if successful, or one of the DBMS database error codes. If |
|
92 recovery fails with either KErrNoMemory or KErrDiskFull, then recovery may |
|
93 be attempted again when more memory or disk space is available. |
|
94 |
|
95 @see RDbDatabase::Recover() |
|
96 |
|
97 @capability Note For a secure shared database, the caller must satisfy the schema |
|
98 access policy for the database. |
|
99 */ |
|
100 EXPORT_C TInt RDbIncremental::Recover(RDbDatabase& aDatabase,TInt& aStep) |
|
101 { |
|
102 return Utility(iState,aDatabase.iDatabase,aStep,CDbDatabase::ERecover); |
|
103 } |
|
104 |
|
105 /** Initiates the operation of calculating and updating database statistics. |
|
106 |
|
107 This is the incremental form of RDbDatabase::UpdateStats() |
|
108 |
|
109 @param aDatabase The database whose statistics are to be updated. |
|
110 @param aStep On return, contains the initial step count for the incremental |
|
111 operation. This value should be passed in to subsequent calls to Next() to |
|
112 continue the operation. |
|
113 @return KErrNone if successful, otherwise another of the system-wide error |
|
114 codes. |
|
115 @see RDbDatabase::UpdateStats() |
|
116 |
|
117 @capability Note For a secure shared database, the caller must satisfy the schema |
|
118 access policy for the database. |
|
119 */ |
|
120 EXPORT_C TInt RDbIncremental::UpdateStats(RDbDatabase& aDatabase,TInt& aStep) |
|
121 { |
|
122 return Utility(iState,aDatabase.iDatabase,aStep,CDbDatabase::EStats); |
|
123 } |
|
124 |
|
125 /** Initiates the operation of compacting a database. This is the incremental form |
|
126 of RDbDatabase::Compact(). |
|
127 |
|
128 @param aDatabase The database to compact. |
|
129 @param aStep On return, contains the initial step count for the incremental |
|
130 operation. This value should be passed in to subsequent calls to Next() to |
|
131 continue the operation. |
|
132 @return KErrNone if successful, otherwise another of the system-wide error |
|
133 codes. |
|
134 @see RDbDatabase::Compact() |
|
135 |
|
136 @capability Note For a secure shared database, the caller must satisfy the schema |
|
137 access policy for the database. |
|
138 */ |
|
139 EXPORT_C TInt RDbIncremental::Compact(RDbDatabase& aDatabase,TInt& aStep) |
|
140 { |
|
141 return Utility(iState,aDatabase.iDatabase,aStep,CDbDatabase::ECompact); |
|
142 } |
|
143 |
|
144 /** Initiates a table discard operation on a database. All indexes belonging to |
|
145 the table are also discarded as part of this operation. |
|
146 |
|
147 This is the incremental version of RDbDatabase::DropTable(). |
|
148 |
|
149 @param aDatabase The database from which to drop the table. |
|
150 @param aTable The name of the table to drop. |
|
151 @param aStep On return, contains the initial step count for the incremental |
|
152 operation. This value should be passed in to subsequent calls to NextL(). |
|
153 @return KErrNone if successful, or one of the DBMS database error codes. The |
|
154 Store database always returns KErrNotSupported for this function. |
|
155 @see RDbDatabase::DropTable() |
|
156 |
|
157 @capability Note For a secure shared database, the caller must satisfy the schema |
|
158 access policy for the database. |
|
159 */ |
|
160 EXPORT_C TInt RDbIncremental::DropTable(RDbDatabase& aDatabase,const TDesC& aTable,TInt& aStep) |
|
161 { |
|
162 TRAPD(r,iState=aDatabase.iDatabase->DropTableL(aTable,aStep)); |
|
163 return r; |
|
164 } |
|
165 |
|
166 /** Initiates a table alteration operation on a database. This is the incremental |
|
167 form of RDbDatabase::AlterTable(). |
|
168 |
|
169 @param aDatabase The database which has the table to be altered. |
|
170 @param aTable The name of the table which is to be altered. |
|
171 @param aNewDef A column set describing the new definition for the table. |
|
172 @param aStep On return, contains the initial step count for the incremental |
|
173 operation. This value should be passed in to subsequent calls to NextL(). |
|
174 @return KErrNone if successful, or one of the DBMS database error codes. Specifically, |
|
175 the function returns: KErrNotFound, if the table does not exist in the database. |
|
176 KErrBadName if a column name is invalid. KErrArgument if the new column set |
|
177 is empty, or there are duplicate column names, or if a column's maximum length |
|
178 is non-positive but not KDbUndefinedLength, or a non-numeric column has the |
|
179 auto-increment attribute, or an indexed column has been dropped, or a column |
|
180 has changed its type or attributes, or a not-null or auto-increment column |
|
181 has been added to a table which is not empty. KErrNotSupported if a column |
|
182 type is out of the recognised range, or an unknown attribute bit is set, or |
|
183 the maximum length for a Text8, Text16 or Binary column is more than 255. |
|
184 KErrTooBig if the resulting record size can be larger than 8200 bytes. |
|
185 @see RDbDatabase::AlterTable() |
|
186 |
|
187 @capability Note For a secure shared database, the caller must satisfy the schema |
|
188 access policy for the database. |
|
189 */ |
|
190 EXPORT_C TInt RDbIncremental::AlterTable(RDbDatabase& aDatabase,const TDesC& aTable,const CDbColSet& aNewDef,TInt& aStep) |
|
191 { |
|
192 TRAPD(r,iState=aDatabase.iDatabase->AlterTableL(aTable,aNewDef,aStep)); |
|
193 return r; |
|
194 } |
|
195 |
|
196 /** Initiates an index creation operation on a database. This is the incremental |
|
197 form of RDbDatabase::CreateIndex(). |
|
198 |
|
199 @param aDatabase The database on which to create the index. |
|
200 @param aName A name for the created index. |
|
201 @param aTable The name of the table on which to create the index. |
|
202 @param aKey The key for the new index. |
|
203 @param aStep On return, contains the initial step count for the incremental |
|
204 operation. This value should be passed in to subsequent calls to NextL(). |
|
205 @return KErrNone if successful, or one of the DBMS database error codes. Specifically, |
|
206 the function returns: KErrNotFound if the table does not exist in the database |
|
207 or a key column is not found in the table. KErrAlreadyExists if an index of |
|
208 the same name already exists on table or a duplicate key is present when building |
|
209 an index. Note that it is not possible to tell the difference between the |
|
210 possible causes of this error if index creation is not carried out incrementally. |
|
211 KErrBadName if an index or column name is invalid. KErrArgument if the key |
|
212 has no key columns or a fixed width column has a truncation length specified, |
|
213 or an invalid truncation length has been specified for a key column, or a |
|
214 LongText8 or LongText16 key column has no truncation length specified, or |
|
215 the key contains a Binary or LongBinary column. KErrNotSupported if a truncated |
|
216 key column is not the last one. KErrTooBig if the resulting key size is too |
|
217 big. |
|
218 @see RDbDatabase::CreateIndex() |
|
219 |
|
220 @capability Note For a secure shared database, the caller must satisfy the schema |
|
221 access policy for the database. |
|
222 */ |
|
223 EXPORT_C TInt RDbIncremental::CreateIndex(RDbDatabase& aDatabase,const TDesC& aName,const TDesC& aTable,const CDbKey& aKey,TInt& aStep) |
|
224 { |
|
225 TRAPD(r,iState=aDatabase.iDatabase->CreateIndexL(aName,aTable,aKey,aStep)); |
|
226 return r; |
|
227 } |
|
228 |
|
229 /** Initiates an index discard operation on the database. This is the incremental |
|
230 form of RDbDatabase::DropIndex(). |
|
231 |
|
232 @param aDatabase The database from which to drop the index. |
|
233 @param aName The name of the index to drop. |
|
234 @param aTable The name of the table which has the index. |
|
235 @param aStep On return, contains the initial step count for the incremental |
|
236 operation. This value should be passed in to subsequent calls to NextL(). |
|
237 @return KErrNone if successful, or one of the DBMS database error codes. Specifically, |
|
238 the function returns KErrNotFound if the table or index does not exist |
|
239 @see RDbDatabase::DropIndex() |
|
240 |
|
241 @capability Note For a secure shared database, the caller must satisfy the schema |
|
242 access policy for the database. |
|
243 */ |
|
244 EXPORT_C TInt RDbIncremental::DropIndex(RDbDatabase& aDatabase,const TDesC& aName,const TDesC& aTable,TInt& aStep) |
|
245 { |
|
246 TRAPD(r,iState=aDatabase.iDatabase->DropIndexL(aName,aTable,aStep)); |
|
247 return r; |
|
248 } |
|
249 |
|
250 // |
|
251 // Incremental SQL Data definition execution |
|
252 // |
|
253 LOCAL_C CDbIncremental* ExecuteDDLL(CDbDatabase& aDatabase,const TDesC& aSql,TDbTextComparison aComparison,TInt& aStep) |
|
254 { |
|
255 CDbIncremental* inc=aDatabase.ExecuteL(aSql,aComparison,aStep); |
|
256 if ((inc==NULL)!=(aStep==0)) |
|
257 { |
|
258 CDbObject::Destroy(inc); |
|
259 __LEAVE(KErrArgument); |
|
260 } |
|
261 return inc; |
|
262 } |
|
263 |
|
264 /** Initiates the execution of a DDL (SQL schema update) statement on the database, |
|
265 specifing additional comparison operations for some SQL statements. |
|
266 |
|
267 This is the incremental form of RDbDatabase::Execute(). |
|
268 |
|
269 Note that to begin executing a DML (SQL data update) statement incrementally, |
|
270 use the RDbUpdate class. |
|
271 |
|
272 @param aDatabase The database on which the DDL (SQL schema update) statement |
|
273 is to execute. |
|
274 @param aSql The DDL SQL statement to be executed on the database. |
|
275 @param aComparison This argument is used in the execution of some SQL statements, |
|
276 and is ignored in all other SQL statements. Specifically: in CREATE INDEX |
|
277 statements, it specifies the comparison operation used for text columns in |
|
278 the index key. In UPDATE and DELETE statements, it specifies the comparison |
|
279 operation used to evaluate the WHERE clause. |
|
280 @param aStep On return, contains the initial step count for the incremental |
|
281 operation. This value should be passed in to subsequent calls to Next() to |
|
282 continue the operation. |
|
283 @return KErrNone if successful, otherwise another of the system-wide error |
|
284 codes. |
|
285 @see RDbDatabase::Execute() |
|
286 @see RDbUpdate |
|
287 |
|
288 @capability Note For a secure shared database, the caller must satisfy: |
|
289 - the schema access policy for the database, if the SQL statement is |
|
290 CREATE/DROP/ALTER; |
|
291 - the write access policy for the table in the SQL, if the SQL statement is |
|
292 INSERT/UPDATE/DELETE; |
|
293 */ |
|
294 EXPORT_C TInt RDbIncremental::Execute(RDbDatabase& aDatabase,const TDesC& aSql,TDbTextComparison aComparison,TInt& aStep) |
|
295 { |
|
296 TRAPD(r,iState=ExecuteDDLL(*aDatabase.iDatabase,aSql,aComparison,aStep)); |
|
297 return r; |
|
298 } |
|
299 |
|
300 // Class RDbUpdate |
|
301 |
|
302 // |
|
303 // Incremental SQL Data definition execution |
|
304 // |
|
305 LOCAL_C CDbIncremental* ExecuteDMLL(CDbDatabase& aDatabase,const TDesC& aSql,TDbTextComparison aComparison,TInt& aRows) |
|
306 { |
|
307 CDbIncremental* inc=aDatabase.ExecuteL(aSql,aComparison,aRows); |
|
308 if ((inc==NULL)==(aRows==0)) |
|
309 { |
|
310 CDbObject::Destroy(inc); |
|
311 __LEAVE(KErrArgument); |
|
312 } |
|
313 return inc; |
|
314 } |
|
315 |
|
316 /** Initiates the incremental execution of a DML (SQL data update) statement on |
|
317 the database. This is similar to RDbDatabase::Execute(). |
|
318 |
|
319 Note that to begin executing a DDL (SQL schema update) statement incrementally, |
|
320 use the RDbIncremental class. |
|
321 |
|
322 @param aDatabase The database on which the DML (SQL data update) statement |
|
323 is to execute. |
|
324 @param aSql A reference to a descriptor containing the DML statement to be |
|
325 executed. |
|
326 @param aComparison This argument is only used in the execution of some SQL |
|
327 statements. By default the comparison is EDbCompareNormal. For more information |
|
328 see RDbDatabase::Execute(). |
|
329 @return KErrNone, if the operation is complete or 1, if the operation requires |
|
330 further incremental execution or another of the system-wide error codes. |
|
331 @see RDbIncremental |
|
332 @see RDbDatabase::Execute() |
|
333 |
|
334 @capability Note For a secure shared database, the caller must satisfy: |
|
335 - the schema access policy for the database, if the SQL statement is |
|
336 CREATE/DROP/ALTER; |
|
337 - the write access policy for the table in the SQL, if the SQL statement is |
|
338 INSERT/UPDATE/DELETE; |
|
339 */ |
|
340 EXPORT_C TInt RDbUpdate::Execute(RDbDatabase& aDatabase,const TDesC& aSql,TDbTextComparison aComparison) |
|
341 { |
|
342 TRAPD(r,iUpdate=ExecuteDMLL(*aDatabase.iDatabase,aSql,aComparison,iRows())); |
|
343 return r; |
|
344 } |
|
345 |
|
346 /** Releases the resources used by this incremental operation object. If the operation |
|
347 is not yet complete, then the operation is abandoned and the database is rolled |
|
348 back to its state before the operation started. */ |
|
349 EXPORT_C void RDbUpdate::Close() |
|
350 { |
|
351 iUpdate.Close(); |
|
352 } |
|
353 |
|
354 /** Performs the next step in the incremental execution of the DML (SQL data update) |
|
355 statement synchronously. The function returns when the step is complete. |
|
356 |
|
357 Note that if the incremental step fails, then the incremental object should |
|
358 be closed and the operation abandoned. |
|
359 |
|
360 @return KErrNone if execution of the DML statement is complete or 1 if another |
|
361 step in the execution of the DML statement is needed. or another of the system-wide |
|
362 error codes is returned if the incremental step fails. */ |
|
363 EXPORT_C TInt RDbUpdate::Next() |
|
364 { |
|
365 TRAPD(r,r=iUpdate->NextL(iRows())); |
|
366 return r; |
|
367 } |
|
368 |
|
369 /** Performs the next step in the incremental execution of the DML (SQL data update) |
|
370 statement asynchronously. |
|
371 |
|
372 The function returns immediately and signals when the step is complete. |
|
373 |
|
374 This function is most effectively used when the incremental operation is packaged |
|
375 as an active object. |
|
376 |
|
377 Note that if the incremental step fails, then the incremental object should |
|
378 be closed, and the operation abandoned. |
|
379 |
|
380 @param aStatus The request status used to contain completion information for |
|
381 the operation. On completion, it contains:KErrNone, if execution of the DML |
|
382 statement is complete or 1, if another step in the execution of the DML statement |
|
383 is needed. or another of the system-wide error codes, if the incremental step |
|
384 fails. */ |
|
385 EXPORT_C void RDbUpdate::Next(TRequestStatus& aStatus) |
|
386 { |
|
387 iUpdate->Next(iRows,aStatus); |
|
388 } |
|
389 |
|
390 /** Returns the number of rows currently affected by the execution of the DML (SQL |
|
391 data update) statement on the database. |
|
392 |
|
393 Once execution of the DML statement is complete, the value returned is the |
|
394 final total number of rows affected. |
|
395 |
|
396 @return The current/final number of rows affected by the execution of the |
|
397 DML statement. */ |
|
398 EXPORT_C TInt RDbUpdate::RowCount() const |
|
399 { |
|
400 return CONST_CAST(TPckgBuf<TInt>&,iRows)(); |
|
401 } |
|
402 |
|
403 // Class CDbSyncIncremental |
|
404 |
|
405 // |
|
406 // Implement the asynchronous step in terms of the synchronous form |
|
407 // |
|
408 EXPORT_C void CDbSyncIncremental::Next(TPckgBuf<TInt>& aStep,TRequestStatus& aStatus) |
|
409 { |
|
410 TRequestStatus* pStatus=&aStatus; |
|
411 TRAPD(r,r=NextL(aStep.operator()())); // MSVC issue!!! cannot use aStep() directly |
|
412 User::RequestComplete(pStatus,r); |
|
413 } |
|
414 |
|
415 // Class CDbAsyncIncremental |
|
416 |
|
417 // |
|
418 // Implement the synchronous step in terms of the asynchronous form |
|
419 // |
|
420 EXPORT_C TBool CDbAsyncIncremental::NextL(TInt& aStep) |
|
421 { |
|
422 TRequestStatus status; |
|
423 TPckgBuf<TInt> step=aStep; |
|
424 Next(step,status); |
|
425 User::WaitForRequest(status); |
|
426 aStep=step(); |
|
427 return __LEAVE_IF_ERROR(status.Int()); |
|
428 } |
|
429 |