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 * SCR Data Layer API which performs all interaction with the underlying database. |
|
16 * |
|
17 */ |
|
18 |
|
19 |
|
20 /** |
|
21 @file |
|
22 @internalComponent |
|
23 @released |
|
24 */ |
|
25 |
|
26 #ifndef SCRSCRDATABASE_H |
|
27 #define SCRSCRDATABASE_H |
|
28 |
|
29 #include <e32base.h> |
|
30 #include <f32file.h> |
|
31 |
|
32 namespace Usif |
|
33 { |
|
34 // Forward declarations |
|
35 class CDatabaseImplementation; |
|
36 class CStatementImplementation; |
|
37 class CStatement; |
|
38 |
|
39 NONSHARABLE_CLASS(CDatabase) : public CBase |
|
40 /** |
|
41 This class provides the means to connect the SCR database and execute all SQL statements. |
|
42 It is intended to be used as a singleton instance by the SCR sessions. |
|
43 */ |
|
44 { |
|
45 friend class CStatement; // CStatement class needs to access CheckSqlErrCodeL |
|
46 public: |
|
47 /** |
|
48 Creates a new database object with an handle to the given database file. |
|
49 |
|
50 @param aDatabaseFile The database file handle. |
|
51 @param aJournalNameZ The journal file handle. |
|
52 @leave KErrNotFound The file opened is not a database file. |
|
53 @leave KErrUnknown The database file is missing. |
|
54 @leave KErrCorrupt The database disk image is malformed. |
|
55 @leave KErrNoMemory An attempt to allocate memory has failed. |
|
56 @leave KErrInUse The database file is locked by another thread. |
|
57 @leave KErrAccessDenied Unable to open the database file. Access permission may be denied. |
|
58 @leave Or other system wide error codes |
|
59 */ |
|
60 IMPORT_C static CDatabase* NewL(RFile& aDatabaseFile, RFile& aJournalFile); |
|
61 |
|
62 /** |
|
63 Creates a new database object with an handle to the given database file and leaves |
|
64 the newly created object on the cleanup stack. |
|
65 |
|
66 @param aDatabaseFile The database file handle. |
|
67 @param aJournalNameZ The journal file handle. |
|
68 @see CDatabase::NewL |
|
69 */ |
|
70 IMPORT_C static CDatabase* NewLC(RFile& aDatabaseFile, RFile& aJournalFile); |
|
71 |
|
72 /** |
|
73 Destructor. The handle to the database file is closed. |
|
74 */ |
|
75 IMPORT_C ~CDatabase(); |
|
76 |
|
77 /** |
|
78 Prepares the provided SQL statement for execution and returns |
|
79 the prepared statement object which can be executed later. |
|
80 |
|
81 The SQL statement must contain a single statement and end with semicolon(;). |
|
82 |
|
83 @param aStatementStr The satement which will be prepared. |
|
84 @return A pointer to the statement object which has got a handle to the result rows set. |
|
85 The returned object is left on the cleanup stack. |
|
86 @leave KErrNotFound The database file could not be opened for some reason OR the table |
|
87 or the requested record could not be found OR the database is empty. |
|
88 @leave KErrCorrupt The database schema has changed. |
|
89 @leave KErrNoMemory An attempt to allocate memory has failed OR some kind of disk I/O |
|
90 operation couldn't be performed (probably no space left on the disk) |
|
91 OR the database is too big (larger than 2GB in size). |
|
92 @leave KErrInUse A table in the database is locked. |
|
93 @leave KErrOverflow Too much data(probably more than 1 megabyte in a single row). |
|
94 @leave KErrCancel The operation in progress has been terminated externally. |
|
95 @leave KErrNotSupported The library has been used incorrectly, |
|
96 @leave KErrAbort Abort due to constraint violation. |
|
97 @leave KErrArgument This error value indicates that there was an error in the SQL |
|
98 statement that was passed into. Data type mismatch may have been |
|
99 occurred OR the provided SQL was badly constructed OR contains |
|
100 more than one statement. |
|
101 @leave KErrUnknown An internal error in the underlaying database engine occurred. |
|
102 @leave KErrGeneral An unspecified error ocurred in the database engine. |
|
103 */ |
|
104 IMPORT_C CStatement* PrepareStatementLC(const TDesC& aStatementStr); |
|
105 |
|
106 /** |
|
107 @return The row id of the most recent successful insert into the database from this connection. |
|
108 @leave KErrNotFound If no successful inserts have ever occurred on this database connection. |
|
109 */ |
|
110 IMPORT_C TInt LastInsertedIdL(); |
|
111 |
|
112 private: |
|
113 CDatabase(); |
|
114 void ConstructL(RFile& aDatabaseFile, RFile& aJournalFile); |
|
115 void CheckSqlErrCodeL(TInt aErr); |
|
116 |
|
117 private: |
|
118 CDatabaseImplementation* iDbImpl; ///< Pointer to the database implementation object. |
|
119 }; |
|
120 |
|
121 |
|
122 |
|
123 NONSHARABLE_CLASS(CStatement) : public CBase |
|
124 /** |
|
125 An instance of this class is used to execute all types of SQL statements with or without |
|
126 parameters. |
|
127 */ |
|
128 { |
|
129 friend class CDatabase; // Only CDatabase can construct an object of this class. |
|
130 public: |
|
131 IMPORT_C ~CStatement(); |
|
132 |
|
133 /** |
|
134 If the SQL statement being executed returns any data, this function makes |
|
135 a new row of data ready for processing. The values may be accessed using |
|
136 the column access functions (@see CStatement::StrColumnL and @see CStatement::IntColumnL). |
|
137 |
|
138 When this function is called again to retrieve the next row of data, the previous row data |
|
139 is not accessible any more. |
|
140 |
|
141 If the caller wants to close the statement before retrieving all the rows, it needs to |
|
142 just destroy the CStatement object. |
|
143 |
|
144 @return Returns EFalse if no more rows are available. |
|
145 @leave Leaves with one of the error codes listed in @see CDatabase::PerformStatementLC |
|
146 */ |
|
147 IMPORT_C TBool ProcessNextRowL(); |
|
148 |
|
149 /** |
|
150 Eexecutes the prepared SQL statement. This function is appropriate to execute |
|
151 SQL statements which do NOT return a result row set (e.g. INSERT and UPDATE). |
|
152 If the SQL satetement contains parameters, the prepared statement can be bound |
|
153 and executed many times. |
|
154 |
|
155 @param aStatement The satement which will be executed. |
|
156 @leave Leaves with one of the leave codes given in @see CStatement::PrepareStatementLC. |
|
157 */ |
|
158 IMPORT_C void ExecuteStatementL(); |
|
159 |
|
160 /** |
|
161 Sets the parameter given with the index value to the specified 32-bit integer value. |
|
162 A parameter value can be set: |
|
163 - immediately after this object has been created |
|
164 - after a call to @see CStatement::Reset |
|
165 @param aParameterIndex The index value identifying the parameter; the first parameter |
|
166 has an index of 1. |
|
167 @param The 32-bit integer value to be assigned to the parameter. |
|
168 @leave Leaves with one of the error codes listed in @see CDatabase::PerformStatementLC |
|
169 */ |
|
170 IMPORT_C void BindIntL(TInt aParameterIndex, TInt aParameterValue); |
|
171 |
|
172 /** |
|
173 Sets the parameter given with the index value to the specified 64-bit integer value. |
|
174 A parameter value can be set: |
|
175 - immediately after this object has been created |
|
176 - after a call to @see CStatement::Reset |
|
177 @param aParameterIndex The index value identifying the parameter; the first parameter |
|
178 has an index of 1. |
|
179 @param The 64-bit integer value to be assigned to the parameter. |
|
180 @leave Leaves with one of the error codes listed in @see CDatabase::PerformStatementLC |
|
181 */ |
|
182 IMPORT_C void BindInt64L(TInt aParameterIndex, TInt64 aParameterValue); |
|
183 |
|
184 /** |
|
185 Sets the parameter given with the index value to the specified 16-bit descriptor. |
|
186 A parameter value can be set: |
|
187 - immediately after this object has been created |
|
188 - after a call to @see CStatement::Reset |
|
189 @param aParameterIndex The index value identifying the parameter; the first parameter |
|
190 has an index of 1. |
|
191 @param aParameterStr The 16-bit descriptor whose content is to be assigned to the parameter. |
|
192 @leave KErrArgument If the input string's length is more than 512 characters |
|
193 @leave Leaves with one of the error codes listed in @see CDatabase::PerformStatementLC |
|
194 */ |
|
195 IMPORT_C void BindStrL(TInt aParameterIndex, const TDesC &aParameterStr); |
|
196 |
|
197 /** |
|
198 Sets the parameter given with the index value to the specified 8-bit descriptor. |
|
199 A parameter value can be set: |
|
200 - immediately after this object has been created |
|
201 - after a call to @see CStatement::Reset |
|
202 @param aParameterIndex The index value identifying the parameter; the first parameter |
|
203 has an index of 1. |
|
204 @param aParameterStr The 8-bit descriptor whose content is to be assigned to the parameter. |
|
205 @leave KErrArgument If the input string's length is more than 512 characters |
|
206 @leave Leaves with one of the error codes listed in @see CDatabase::PerformStatementLC |
|
207 */ |
|
208 IMPORT_C void BindBinaryL(TInt aParameterIndex, const TDesC8 &aParameterStr); |
|
209 |
|
210 /** |
|
211 Sets the parameter given with the index value to the specified 8-bit descriptor. |
|
212 A parameter value can be set: |
|
213 - immediately after this object has been created |
|
214 - after a call to @see CStatement::Reset |
|
215 |
|
216 @param aParameterIndex The index value identifying the parameter; the first parameter |
|
217 has an index of 1. |
|
218 @param aParameterStr The 8-bit descriptor whose content is to be assigned to the parameter. |
|
219 @param aCustomLength The maximum characters allowed |
|
220 |
|
221 @leave KErrArgument If the input string's length is more than aCustomLength |
|
222 @leave Leaves with one of the error codes listed in @see CDatabase::PerformStatementLC |
|
223 */ |
|
224 IMPORT_C void BindBinaryL(TInt aParameterIndex, const TDesC8 &aParameterStr, TUint aCustomLength); |
|
225 |
|
226 /** |
|
227 Retrieves the value of a string column. The caller must know the string column index. |
|
228 In addition, the caller must make the copy if they want to process multiple rows at once. |
|
229 |
|
230 @param aColIdx The index of the column in the result set. |
|
231 @return The string value of the column given. |
|
232 @leave KErrArgument The supplied column index is not valid or its type is not string. |
|
233 @leave Or one of the error codes listed in @see CDatabase::PerformStatementLC |
|
234 */ |
|
235 IMPORT_C TPtrC StrColumnL(TInt aColIdx) const; |
|
236 |
|
237 /** |
|
238 Retrieves the value of a raw binary data column. The caller must know the column index. |
|
239 In addition, the caller must make the copy if they want to process multiple rows at once. |
|
240 |
|
241 @param aColIdx The index of the column in the result set. |
|
242 @return The binary value of the column given. |
|
243 @leave KErrArgument The supplied column index is not valid or its type is not string. |
|
244 @leave Or one of the error codes listed in @see CDatabase::PerformStatementLC |
|
245 */ |
|
246 IMPORT_C TPtrC8 BinaryColumnL(TInt aColIdx) const; |
|
247 |
|
248 /** |
|
249 Retrieves the value of a integer column. The caller must know the integer column index. |
|
250 The return value is 64-bit integer. |
|
251 |
|
252 @param aColIdx The index of the column in the result set. |
|
253 @return The integer value of the column given. |
|
254 @leave KErrArgument The supplied column index is not valid or its type is not integer. |
|
255 @leave Or one of the error codes listed in @see CDatabase::PerformStatementLC |
|
256 */ |
|
257 IMPORT_C TInt64 Int64ColumnL(TInt aColIdx) const; |
|
258 |
|
259 /** |
|
260 Retrieves the value of an integer column. The caller must know the integer column index. |
|
261 The return value is 32-bit integer. |
|
262 |
|
263 @param aColIdx The index of the column in the result set. |
|
264 @return The integer value of the column given. |
|
265 @leave KErrArgument The supplied column index is not valid or its type is not integer. |
|
266 @leave Or one of the error codes listed in @see CDatabase::PerformStatementLC |
|
267 */ |
|
268 IMPORT_C TInt IntColumnL(TInt aColIdx) const; |
|
269 |
|
270 /** |
|
271 Resets this SQL statement object to its initial state and makes it ready to be executed again. |
|
272 Any SQL statement parameters that had values bound to them, retain their values. |
|
273 If this object processes a parameterised SQL statement, then the parameter values |
|
274 can be bound after the call to Reset(). |
|
275 @leave Leaves with one of the error codes listed in @see CDatabase::PerformStatementLC |
|
276 */ |
|
277 IMPORT_C void ResetL(); |
|
278 |
|
279 /** |
|
280 Returns whether the specified field (column) of a row is NULL. |
|
281 Note that if the field is NULL, it does NOT mean that the corresponding fields of |
|
282 other rows are NULL as well. |
|
283 @param aColIdx The index of the column in the result set. |
|
284 @return ETrue, if the field is NULL, otherwise EFalse. |
|
285 @leave KErrArgument The supplied column index is not valid. |
|
286 */ |
|
287 IMPORT_C TBool IsFieldNullL(TInt aColIdx) const; |
|
288 |
|
289 private: |
|
290 /** |
|
291 Creates a new CStatement object on the heap. |
|
292 |
|
293 @param aDb Refrence to the database object. |
|
294 @param aStmtImpl Pointer to the statement implementation. The ownership is also passed |
|
295 to the CStatement object. |
|
296 @return The newly created CStatement object. |
|
297 |
|
298 */ |
|
299 static CStatement* NewL(const CDatabase& aDb, CStatementImplementation* aStmtImpl); |
|
300 |
|
301 CStatement(const CDatabase& aDb, CStatementImplementation* aStmtImpl); |
|
302 void ValidateRequestedColumnL(TInt aColIdx, TInt& aColumnType) const; |
|
303 |
|
304 private: |
|
305 const CDatabase& iDb; ///< Reference to the database object which creates this statement object. |
|
306 CStatementImplementation* iStmtImpl; ///< Pointer to the SQL statement implementation |
|
307 }; |
|
308 } // namespace Usif |
|
309 |
|
310 #endif // SCRSCRDATABASE_H |
|