1 // Copyright (c) 2006-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".
8 // Initial Contributors:
9 // Nokia Corporation - initial contribution.
18 inline CSqlDatabaseImpl::CSqlDatabaseImpl()
23 Attaches a secure or non-secure database.
25 Implements RSqlDatabase::Attach().
27 @param aDbFileName The name of the file that hosts the database. If this is
28 a secure database, then the format of the name must be:
29 \<drive\>:\<[SID]database file name excluding the path\>.
30 If this is a private or shared non-secure database, then aDbFileName has to be the full
31 database file name. "[SID]" refers to SID of the application which created the attached database.
32 @param aDbName Logical database name. It must be unique (per database connection). This is the name which can
33 be used for accessing tables in the attached database. The syntax is "database-name.table-name".
35 @return KErrNone, the operation has completed successfully;
36 KErrNoMemory, an out of memory condition has occurred;
37 KErrBadName, the file name is invalid - it has either a zero length or it is the name of a directory;
38 KErrNotReady, the drive does not exist or is not ready;
39 KErrInUse, the file is already open;
40 KErrNotFound, database file not found;
41 KErrGeneral, missing or invalid security policies (if the database to be opened is a secure database);
42 KErrPermissionDenied, the caller does not satisfy the relevant database security policies;
43 KErrNotSupported, incompatible SQL security version (if the database to be opened is a secure database).
44 Note that database specific errors categorised as ESqlDbError, and
45 other system-wide error codes may also be returned.
48 @see RSqlDatabase::Attach()
50 inline TInt CSqlDatabaseImpl::Attach(const TDesC& aDbFileName, const TDesC& aDbName)
52 return Session().Attach(aDbFileName, aDbName);
56 Detaches previously attached database.
58 Implements RSqlDatabase::Detach().
60 @param aDbName Logical database name. The logical name of the database to be detached.
62 @return KErrNone, the operation has completed successfully;
63 KErrNotFound, no attached database with aDbName name;
64 Note that database specific errors categorised as ESqlDbError, and
65 other system-wide error codes may also be returned.
68 @see RSqlDatabase::Detach()
70 inline TInt CSqlDatabaseImpl::Detach(const TDesC& aDbName)
72 return Session().Detach(aDbName);
76 Copies a database file to the specified location.
78 Implements RSqlDatabase::Copy().
80 @param aSrcDbFileName Source database file name.
81 If this is a secure database, then the format of the name must be:
82 \<drive\>:\<[SID]database file name excluding the path\>.
83 If this is a non-secure database, then aDbFileName has to be the full database file name.
84 "[SID]" refers to SID of the application which created the database.
85 @param aDestDbFileName Destination database file name.
86 If this is a secure database, then the format of the name must be:
87 \<drive\>:\<[SID]database file name excluding the path\>.
88 If this is a non-secure database, then aDbFileName has to be the full database file name.
89 "[SID]" refers to SID of the application which performs the copying operation.
91 The allowed copying operations are:
92 - secure to secure database. Only the application created the database is allowed to copy it.
93 - non-secure to non-secure database. No restrictions apply to this operation.
95 @return KErrNone, the operation completed has successfully;
96 KErrBadName, the file name is invalid - it has either a zero length or it is the name of a directory;
97 KErrNotReady, the drive does not exist or is not ready;
98 KErrInUse, the file is already open;
99 KErrNotFound, database file not found;
100 KErrPermissionDenied, the SID of the calling application does not match the SID of source or destination database.
101 Note that other system-wide error codes may also be returned.
104 @see RSqlDatabase::Copy()
106 inline TInt CSqlDatabaseImpl::Copy(const TDesC& aSrcDbFileName, const TDesC& aDestDbFileName)
108 return RSqlDbSession::CopyDatabase(aSrcDbFileName, aDestDbFileName);
112 Deletes the specified database file.
114 Implements RSqlDatabase::Delete().
116 @param aDbFileName The name of the database file.
117 If this is a secure database, then the format of the name must be:
118 \<drive\>:\<[SID]database file name excluding the path\>.
119 If this is a private or shared non-secure database, then aDbFileName has to be the
120 full database file name. "[SID]" refers to SID of the application which created the database.
122 @return KErrNone, the operation has completed successfully;
123 KErrBadName, the file name is invalid - it has either a zero length or it is the name of a directory;
124 KErrNotReady, the drive does not exist or is not ready;
125 KErrInUse, the database file is in use;
126 KErrNotFound, the database file cannot be found;
127 KErrAccessDenied, access to the database file is denied (e.g. it might be a read-only file);
128 KErrPermissionDenied, the SID of the calling application does not match the SID of the database;
129 Note that other system-wide error codes may also be returned.
132 @see RSqlDatabase::Delete()
134 inline TInt CSqlDatabaseImpl::Delete(const TDesC& aDbFileName)
136 return RSqlDbSession::DeleteDatabase(aDbFileName);
140 Sets the transaction isolation level for the database.
142 Implements RSqlDatabase::SetIsolationLevel().
144 @param aIsolationLevel The isolation level to be set.
145 Allowed isolation level values are:
146 - RSqlDatabase::EReadUncommitted;
147 - RSqlDatabase::ESerializable;
149 @return KErrNone, if the operation has completed successfully;
150 KErrNotSupported, invalid (not supported) transaction isolation level;
153 @see RSqlDatabase::SetIsolationLevel()
155 inline TInt CSqlDatabaseImpl::SetIsolationLevel(RSqlDatabase::TIsolationLevel aIsolationLevel)
157 return Session().SetIsolationLevel(aIsolationLevel);
161 Executes one or more 16-bit DDL/DML SQL statements.
163 Implements RSqlDatabase::Exec().
165 @param aSqlStmt A string of 16-bit wide characters containing one or more DDL/DML SQL statements;
166 each statement is separated by a ';' character.
168 @return >=0, The operation has completed successfully. The number of database rows that were
169 changed/inserted/deleted by the most recently completed DDL/DML sql statement.
170 Exception: If the executed statement is "DELETE FROM <table>", then the function returns 0
171 if the operation has completed successfully (disregarding the number of the deleted rows);
172 KErrNoMemory, an out of memory condition has occured;
173 KSqlErrGeneral, a syntax error has occurred - text describing the problem
174 can be obtained by calling RSqlDatabase::LastErrorMessage();
175 KErrPermissionDenied, the caller does not satisfy the relevant database security policies.
176 Note that database specific errors categorised as ESqlDbError, and
177 other system-wide error codes may also be returned.
180 @see RSqlDatabase::Exec()
182 inline TInt CSqlDatabaseImpl::Exec(const TDesC16& aSqlStmt)
184 return Session().Exec(aSqlStmt);
188 Executes one or more 8-bit DDL/DML SQL statements.
190 Implements RSqlDatabase::Exec().
192 @param aSqlStmt A string of 8-bit wide characters containing one or more DDL/DML SQL statements;
193 each statement is separated by a ';' character.
195 @return >=0, The operation has completed successfully. The number of database rows that were
196 changed/inserted/deleted by the most recently completed DDL/DML sql statement.
197 Exception: If the executed statement is "DELETE FROM <table>", then the function returns 0
198 if the operation has completed successfully (disregarding the number of the deleted rows);
199 KErrNoMemory, an out of memory condition has occured;
200 KSqlErrGeneral, a syntax error has occurred - text describing the problem
201 can be obtained by calling RSqlDatabase::LastErrorMessage();
202 KErrPermissionDenied, the caller does not satisfy the relevant database security policies.
203 Note that database specific errors categorised as ESqlDbError, and
204 other system-wide error codes may also be returned.
207 @see RSqlDatabase::Exec()
209 inline TInt CSqlDatabaseImpl::Exec(const TDesC8& aSqlStmt)
211 return Session().Exec(aSqlStmt);
215 Executes one or more 16-bit DDL/DML SQL statements asynchronously.
217 Implements RSqlDatabase::Exec().
219 @param aSqlStmt A string of 16-bit wide characters containing one or more DDL/DML SQL statements;
220 each statement is separated by a ';' character.
221 @param aStatus Completion status of asynchronous request, one of the following:
223 - >=0, The operation has completed successfully. The number of database rows that were
224 changed/inserted/deleted by the most recently completed DDL/DML sql statement.
225 Exception: If the executed statement is "DELETE FROM <table>", then the function returns 0
226 if the operation has completed successfully (disregarding the number of the deleted rows);
227 - KErrNoMemory, an out of memory condition has occured;
228 - KSqlErrGeneral, a syntax error has occurred - text describing the problem
229 can be obtained by calling RSqlDatabase::LastErrorMessage();
230 - KErrPermissionDenied, the caller does not satisfy the relevant database security policies;
231 Note that aStatus may be set with database specific errors categorised as ESqlDbError,
232 and other system-wide error codes.
236 @see RSqlDatabase::Exec()
238 inline void CSqlDatabaseImpl::Exec(const TDesC16& aSqlStmt, TRequestStatus& aStatus)
240 Session().Exec(aSqlStmt, aStatus);
244 Executes one or more 8-bit DDL/DML SQL statements asynchronously.
246 Implements RSqlDatabase::Exec().
248 @param aSqlStmt A string of 8-bit wide characters containing one or more DDL/DML SQL statements;
249 each statement is separated by a ';' character.
250 @param aStatus Completion status of asynchronous request, one of the following:
252 - >=0, The operation has completed successfully. The number of database rows that were
253 changed/inserted/deleted by the most recently completed DDL/DML sql statement.
254 Exception: If the executed statement is "DELETE FROM <table>", then the function returns 0
255 if the operation has completed successfully (disregarding the number of the deleted rows);
256 - KErrNoMemory, an out of memory condition has occured;
257 - KSqlErrGeneral, a syntax error has occurred - text describing the problem
258 can be obtained by calling RSqlDatabase::LastErrorMessage();
259 - KErrPermissionDenied, the caller does not satisfy the relevant database security policies;
260 Note that aStatus may be set with database specific errors categorised as ESqlDbError,
261 and other system-wide error codes.
265 @see RSqlDatabase::Exec()
267 inline void CSqlDatabaseImpl::Exec(const TDesC8& aSqlStmt, TRequestStatus& aStatus)
269 Session().Exec(aSqlStmt, aStatus);
273 Retrieves a reference to the textual description of the error returned by the
276 Implements RSqlDatabase::LastErrorMessage().
278 @return A non-modifiable pointer descriptor representing the most recent error
279 message. Note that message may be NULL, i.e. the descriptor may have
283 @see RSqlDatabase::LastErrorMessage()
285 inline TPtrC CSqlDatabaseImpl::LastErrorMessage()
287 return Session().LastErrorMessage();
291 Returns the ROWID of the most recent successful INSERT into the database
292 from this database connection.
294 Implements RSqlDatabase::LastInsertedRowId().
296 @return >0, the ROWID of the most recent successful INSERT into the database
297 from this database connection;
298 0, if no successful INSERTs have ever occurred from this database connection
299 <0, if one of the system-wide error codes is returned
301 @see RSqlDatabase::LastInsertedRowId()
303 inline TInt64 CSqlDatabaseImpl::LastInsertedRowId()
305 return Session().LastInsertedRowId();
309 @return A reference to RSqlDbSession instance.
311 inline RSqlDbSession& CSqlDatabaseImpl::Session()
317 Sends a command to the server to Execute a SELECT query which is expected to return a single row consisting of
318 a single column value and copies that value to the place refered by aRes parameter.
320 @param aSqlStmt 16-bit SELECT sql query
321 @param aType The expected column type
322 @param aRes Output parameter. Refers to the place where the result must be copied
324 @return KErrNone, if the function completes successfully,
325 Positive value, The column value length, in case if the receiving buffer
326 is not big enough. This return result is possible only with text or binary columns.
328 @leave The function may leave with database specific errors categorised as ESqlDbError and
329 other system-wide error codes.
331 inline TInt CSqlDatabaseImpl::ExecScalarFullSelectL(const TDesC16& aSqlStmt, TSqlColumnType aType, TDes8& aRes)
333 TInt rc = Session().ExecScalarFullSelect(aSqlStmt, aType, aRes);
334 __SQLLEAVE_IF_ERROR(rc);
339 Sends a command to the server to Execute a SELECT query which is expected to return a single row consisting of
340 a single column value and copies that value to the place refered by aRes parameter.
342 @param aSqlStmt 8-bit SELECT sql query
343 @param aType The expected column type
344 @param aRes Output parameter. Refers to the place where the result must be copied
346 @return KErrNone, if the function completes successfully,
347 Positive value, The column value length, in case if the receiving buffer
348 is not big enough. This return result is possible only with text or binary columns.
350 @leave The function may leave with database specific errors categorised as ESqlDbError and
351 other system-wide error codes.
353 inline TInt CSqlDatabaseImpl::ExecScalarFullSelectL(const TDesC8& aSqlStmt, TSqlColumnType aType, TDes8& aRes)
355 TInt rc = Session().ExecScalarFullSelect(aSqlStmt, aType, aRes);
356 __SQLLEAVE_IF_ERROR(rc);
361 @return True, if the database is in transaction, false otherwise.
363 inline TBool CSqlDatabaseImpl::InTransaction()
365 return Session().SendReceive(ESqlSrvDbInTransaction) != 0;
369 @return >= 0, the operation has completed successfully. The number is the size of the main
371 KErrNoMemory, an out of memory condition has occurred;
372 KErrTooBig, the database is too big and the size cannot fit into 32-bit signed integer;
373 Note that database specific errors categorised as ESqlDbError, and
374 other system-wide error codes may also be returned.
376 inline TInt CSqlDatabaseImpl::Size()
378 return Session().SendReceive(ESqlSrvDbSize);
382 Returns the database file size and free space, in bytes.
384 @param aSize An output parameter. If the call was successfull the aSize object will contain information
385 about the database size and database free space.
386 @param aDbName The attached database name or KNullDesC for the main database
388 @return KErrNone, The operation has completed succesfully;
389 Note that database specific errors categorised as ESqlDbError, and
390 other system-wide error codes may also be returned.
392 Usage of the IPC call arguments:
393 Arg 0: [in/out] Points to a RSqldatabase::TSize object, where the database size and free space values
395 Arg 1: [out] The database name length in characters
396 Arg 2: [out] The attached database name or KNullDesC for the main database
398 inline TInt CSqlDatabaseImpl::Size(RSqlDatabase::TSize& aSize, const TDesC& aDbName)
400 TPtr8 ptr(reinterpret_cast <TUint8*> (&aSize), sizeof(aSize));
401 return Session().SendReceive(ESqlSrvDbSize2, TIpcArgs(&ptr, aDbName.Length(), &aDbName));