1.1 --- /dev/null Thu Jan 01 00:00:00 1970 +0000
1.2 +++ b/os/persistentdata/persistentstorage/sql/SRC/Client/SqlDatabaseImpl.inl Fri Jun 15 03:10:57 2012 +0200
1.3 @@ -0,0 +1,402 @@
1.4 +// Copyright (c) 2006-2009 Nokia Corporation and/or its subsidiary(-ies).
1.5 +// All rights reserved.
1.6 +// This component and the accompanying materials are made available
1.7 +// under the terms of "Eclipse Public License v1.0"
1.8 +// which accompanies this distribution, and is available
1.9 +// at the URL "http://www.eclipse.org/legal/epl-v10.html".
1.10 +//
1.11 +// Initial Contributors:
1.12 +// Nokia Corporation - initial contribution.
1.13 +//
1.14 +// Contributors:
1.15 +//
1.16 +// Description:
1.17 +//
1.18 +
1.19 +/**
1.20 +*/
1.21 +inline CSqlDatabaseImpl::CSqlDatabaseImpl()
1.22 + {
1.23 + }
1.24 +
1.25 +/**
1.26 +Attaches a secure or non-secure database.
1.27 +
1.28 +Implements RSqlDatabase::Attach().
1.29 +
1.30 +@param aDbFileName The name of the file that hosts the database. If this is
1.31 + a secure database, then the format of the name must be:
1.32 + \<drive\>:\<[SID]database file name excluding the path\>.
1.33 + If this is a private or shared non-secure database, then aDbFileName has to be the full
1.34 + database file name. "[SID]" refers to SID of the application which created the attached database.
1.35 +@param aDbName Logical database name. It must be unique (per database connection). This is the name which can
1.36 + be used for accessing tables in the attached database. The syntax is "database-name.table-name".
1.37 +
1.38 +@return KErrNone, the operation has completed successfully;
1.39 + KErrNoMemory, an out of memory condition has occurred;
1.40 + KErrBadName, the file name is invalid - it has either a zero length or it is the name of a directory;
1.41 + KErrNotReady, the drive does not exist or is not ready;
1.42 + KErrInUse, the file is already open;
1.43 + KErrNotFound, database file not found;
1.44 + KErrGeneral, missing or invalid security policies (if the database to be opened is a secure database);
1.45 + KErrPermissionDenied, the caller does not satisfy the relevant database security policies;
1.46 + KErrNotSupported, incompatible SQL security version (if the database to be opened is a secure database).
1.47 + Note that database specific errors categorised as ESqlDbError, and
1.48 + other system-wide error codes may also be returned.
1.49 +
1.50 +@see RSqlDatabase
1.51 +@see RSqlDatabase::Attach()
1.52 +*/
1.53 +inline TInt CSqlDatabaseImpl::Attach(const TDesC& aDbFileName, const TDesC& aDbName)
1.54 + {
1.55 + return Session().Attach(aDbFileName, aDbName);
1.56 + }
1.57 +
1.58 +/**
1.59 +Detaches previously attached database.
1.60 +
1.61 +Implements RSqlDatabase::Detach().
1.62 +
1.63 +@param aDbName Logical database name. The logical name of the database to be detached.
1.64 +
1.65 +@return KErrNone, the operation has completed successfully;
1.66 + KErrNotFound, no attached database with aDbName name;
1.67 + Note that database specific errors categorised as ESqlDbError, and
1.68 + other system-wide error codes may also be returned.
1.69 +
1.70 +@see RSqlDatabase
1.71 +@see RSqlDatabase::Detach()
1.72 +*/
1.73 +inline TInt CSqlDatabaseImpl::Detach(const TDesC& aDbName)
1.74 + {
1.75 + return Session().Detach(aDbName);
1.76 + }
1.77 +
1.78 +/**
1.79 +Copies a database file to the specified location.
1.80 +
1.81 +Implements RSqlDatabase::Copy().
1.82 +
1.83 +@param aSrcDbFileName Source database file name.
1.84 + If this is a secure database, then the format of the name must be:
1.85 + \<drive\>:\<[SID]database file name excluding the path\>.
1.86 + If this is a non-secure database, then aDbFileName has to be the full database file name.
1.87 + "[SID]" refers to SID of the application which created the database.
1.88 +@param aDestDbFileName Destination database file name.
1.89 + If this is a secure database, then the format of the name must be:
1.90 + \<drive\>:\<[SID]database file name excluding the path\>.
1.91 + If this is a non-secure database, then aDbFileName has to be the full database file name.
1.92 + "[SID]" refers to SID of the application which performs the copying operation.
1.93 +
1.94 +The allowed copying operations are:
1.95 +- secure to secure database. Only the application created the database is allowed to copy it.
1.96 +- non-secure to non-secure database. No restrictions apply to this operation.
1.97 +
1.98 +@return KErrNone, the operation completed has successfully;
1.99 + KErrBadName, the file name is invalid - it has either a zero length or it is the name of a directory;
1.100 + KErrNotReady, the drive does not exist or is not ready;
1.101 + KErrInUse, the file is already open;
1.102 + KErrNotFound, database file not found;
1.103 + KErrPermissionDenied, the SID of the calling application does not match the SID of source or destination database.
1.104 + Note that other system-wide error codes may also be returned.
1.105 +
1.106 +@see RSqlDatabase
1.107 +@see RSqlDatabase::Copy()
1.108 +*/
1.109 +inline TInt CSqlDatabaseImpl::Copy(const TDesC& aSrcDbFileName, const TDesC& aDestDbFileName)
1.110 + {
1.111 + return RSqlDbSession::CopyDatabase(aSrcDbFileName, aDestDbFileName);
1.112 + }
1.113 +
1.114 +/**
1.115 +Deletes the specified database file.
1.116 +
1.117 +Implements RSqlDatabase::Delete().
1.118 +
1.119 +@param aDbFileName The name of the database file.
1.120 + If this is a secure database, then the format of the name must be:
1.121 + \<drive\>:\<[SID]database file name excluding the path\>.
1.122 + If this is a private or shared non-secure database, then aDbFileName has to be the
1.123 + full database file name. "[SID]" refers to SID of the application which created the database.
1.124 +
1.125 +@return KErrNone, the operation has completed successfully;
1.126 + KErrBadName, the file name is invalid - it has either a zero length or it is the name of a directory;
1.127 + KErrNotReady, the drive does not exist or is not ready;
1.128 + KErrInUse, the database file is in use;
1.129 + KErrNotFound, the database file cannot be found;
1.130 + KErrAccessDenied, access to the database file is denied (e.g. it might be a read-only file);
1.131 + KErrPermissionDenied, the SID of the calling application does not match the SID of the database;
1.132 + Note that other system-wide error codes may also be returned.
1.133 +
1.134 +@see RSqlDatabase
1.135 +@see RSqlDatabase::Delete()
1.136 +*/
1.137 +inline TInt CSqlDatabaseImpl::Delete(const TDesC& aDbFileName)
1.138 + {
1.139 + return RSqlDbSession::DeleteDatabase(aDbFileName);
1.140 + }
1.141 +
1.142 +/**
1.143 +Sets the transaction isolation level for the database.
1.144 +
1.145 +Implements RSqlDatabase::SetIsolationLevel().
1.146 +
1.147 +@param aIsolationLevel The isolation level to be set.
1.148 + Allowed isolation level values are:
1.149 + - RSqlDatabase::EReadUncommitted;
1.150 + - RSqlDatabase::ESerializable;
1.151 +
1.152 +@return KErrNone, if the operation has completed successfully;
1.153 + KErrNotSupported, invalid (not supported) transaction isolation level;
1.154 +
1.155 +@see RSqlDatabase
1.156 +@see RSqlDatabase::SetIsolationLevel()
1.157 +*/
1.158 +inline TInt CSqlDatabaseImpl::SetIsolationLevel(RSqlDatabase::TIsolationLevel aIsolationLevel)
1.159 + {
1.160 + return Session().SetIsolationLevel(aIsolationLevel);
1.161 + }
1.162 +
1.163 +/**
1.164 +Executes one or more 16-bit DDL/DML SQL statements.
1.165 +
1.166 +Implements RSqlDatabase::Exec().
1.167 +
1.168 +@param aSqlStmt A string of 16-bit wide characters containing one or more DDL/DML SQL statements;
1.169 + each statement is separated by a ';' character.
1.170 +
1.171 +@return >=0, The operation has completed successfully. The number of database rows that were
1.172 + changed/inserted/deleted by the most recently completed DDL/DML sql statement.
1.173 + Exception: If the executed statement is "DELETE FROM <table>", then the function returns 0
1.174 + if the operation has completed successfully (disregarding the number of the deleted rows);
1.175 + KErrNoMemory, an out of memory condition has occured;
1.176 + KSqlErrGeneral, a syntax error has occurred - text describing the problem
1.177 + can be obtained by calling RSqlDatabase::LastErrorMessage();
1.178 + KErrPermissionDenied, the caller does not satisfy the relevant database security policies.
1.179 + Note that database specific errors categorised as ESqlDbError, and
1.180 + other system-wide error codes may also be returned.
1.181 +
1.182 +@see RSqlDatabase
1.183 +@see RSqlDatabase::Exec()
1.184 +*/
1.185 +inline TInt CSqlDatabaseImpl::Exec(const TDesC16& aSqlStmt)
1.186 + {
1.187 + return Session().Exec(aSqlStmt);
1.188 + }
1.189 +
1.190 +/**
1.191 +Executes one or more 8-bit DDL/DML SQL statements.
1.192 +
1.193 +Implements RSqlDatabase::Exec().
1.194 +
1.195 +@param aSqlStmt A string of 8-bit wide characters containing one or more DDL/DML SQL statements;
1.196 + each statement is separated by a ';' character.
1.197 +
1.198 +@return >=0, The operation has completed successfully. The number of database rows that were
1.199 + changed/inserted/deleted by the most recently completed DDL/DML sql statement.
1.200 + Exception: If the executed statement is "DELETE FROM <table>", then the function returns 0
1.201 + if the operation has completed successfully (disregarding the number of the deleted rows);
1.202 + KErrNoMemory, an out of memory condition has occured;
1.203 + KSqlErrGeneral, a syntax error has occurred - text describing the problem
1.204 + can be obtained by calling RSqlDatabase::LastErrorMessage();
1.205 + KErrPermissionDenied, the caller does not satisfy the relevant database security policies.
1.206 + Note that database specific errors categorised as ESqlDbError, and
1.207 + other system-wide error codes may also be returned.
1.208 +
1.209 +@see RSqlDatabase
1.210 +@see RSqlDatabase::Exec()
1.211 +*/
1.212 +inline TInt CSqlDatabaseImpl::Exec(const TDesC8& aSqlStmt)
1.213 + {
1.214 + return Session().Exec(aSqlStmt);
1.215 + }
1.216 +
1.217 +/**
1.218 +Executes one or more 16-bit DDL/DML SQL statements asynchronously.
1.219 +
1.220 +Implements RSqlDatabase::Exec().
1.221 +
1.222 +@param aSqlStmt A string of 16-bit wide characters containing one or more DDL/DML SQL statements;
1.223 + each statement is separated by a ';' character.
1.224 +@param aStatus Completion status of asynchronous request, one of the following:
1.225 +@code
1.226 + - >=0, The operation has completed successfully. The number of database rows that were
1.227 + changed/inserted/deleted by the most recently completed DDL/DML sql statement.
1.228 + Exception: If the executed statement is "DELETE FROM <table>", then the function returns 0
1.229 + if the operation has completed successfully (disregarding the number of the deleted rows);
1.230 + - KErrNoMemory, an out of memory condition has occured;
1.231 + - KSqlErrGeneral, a syntax error has occurred - text describing the problem
1.232 + can be obtained by calling RSqlDatabase::LastErrorMessage();
1.233 + - KErrPermissionDenied, the caller does not satisfy the relevant database security policies;
1.234 + Note that aStatus may be set with database specific errors categorised as ESqlDbError,
1.235 + and other system-wide error codes.
1.236 +@endcode
1.237 +
1.238 +@see RSqlDatabase
1.239 +@see RSqlDatabase::Exec()
1.240 +*/
1.241 +inline void CSqlDatabaseImpl::Exec(const TDesC16& aSqlStmt, TRequestStatus& aStatus)
1.242 + {
1.243 + Session().Exec(aSqlStmt, aStatus);
1.244 + }
1.245 +
1.246 +/**
1.247 +Executes one or more 8-bit DDL/DML SQL statements asynchronously.
1.248 +
1.249 +Implements RSqlDatabase::Exec().
1.250 +
1.251 +@param aSqlStmt A string of 8-bit wide characters containing one or more DDL/DML SQL statements;
1.252 + each statement is separated by a ';' character.
1.253 +@param aStatus Completion status of asynchronous request, one of the following:
1.254 +@code
1.255 + - >=0, The operation has completed successfully. The number of database rows that were
1.256 + changed/inserted/deleted by the most recently completed DDL/DML sql statement.
1.257 + Exception: If the executed statement is "DELETE FROM <table>", then the function returns 0
1.258 + if the operation has completed successfully (disregarding the number of the deleted rows);
1.259 + - KErrNoMemory, an out of memory condition has occured;
1.260 + - KSqlErrGeneral, a syntax error has occurred - text describing the problem
1.261 + can be obtained by calling RSqlDatabase::LastErrorMessage();
1.262 + - KErrPermissionDenied, the caller does not satisfy the relevant database security policies;
1.263 + Note that aStatus may be set with database specific errors categorised as ESqlDbError,
1.264 + and other system-wide error codes.
1.265 +@endcode
1.266 +
1.267 +@see RSqlDatabase
1.268 +@see RSqlDatabase::Exec()
1.269 +*/
1.270 +inline void CSqlDatabaseImpl::Exec(const TDesC8& aSqlStmt, TRequestStatus& aStatus)
1.271 + {
1.272 + Session().Exec(aSqlStmt, aStatus);
1.273 + }
1.274 +
1.275 +/**
1.276 +Retrieves a reference to the textual description of the error returned by the
1.277 +most recent call.
1.278 +
1.279 +Implements RSqlDatabase::LastErrorMessage().
1.280 +
1.281 +@return A non-modifiable pointer descriptor representing the most recent error
1.282 + message. Note that message may be NULL, i.e. the descriptor may have
1.283 + zero length.
1.284 +
1.285 +@see RSqlDatabase
1.286 +@see RSqlDatabase::LastErrorMessage()
1.287 +*/
1.288 +inline TPtrC CSqlDatabaseImpl::LastErrorMessage()
1.289 + {
1.290 + return Session().LastErrorMessage();
1.291 + }
1.292 +
1.293 +/**
1.294 +Returns the ROWID of the most recent successful INSERT into the database
1.295 +from this database connection.
1.296 +
1.297 +Implements RSqlDatabase::LastInsertedRowId().
1.298 +
1.299 +@return >0, the ROWID of the most recent successful INSERT into the database
1.300 + from this database connection;
1.301 + 0, if no successful INSERTs have ever occurred from this database connection
1.302 + <0, if one of the system-wide error codes is returned
1.303 +
1.304 +@see RSqlDatabase::LastInsertedRowId()
1.305 +*/
1.306 +inline TInt64 CSqlDatabaseImpl::LastInsertedRowId()
1.307 + {
1.308 + return Session().LastInsertedRowId();
1.309 + }
1.310 +
1.311 +/**
1.312 +@return A reference to RSqlDbSession instance.
1.313 +*/
1.314 +inline RSqlDbSession& CSqlDatabaseImpl::Session()
1.315 + {
1.316 + return iDbSession;
1.317 + }
1.318 +
1.319 +/**
1.320 +Sends a command to the server to Execute a SELECT query which is expected to return a single row consisting of
1.321 +a single column value and copies that value to the place refered by aRes parameter.
1.322 +
1.323 +@param aSqlStmt 16-bit SELECT sql query
1.324 +@param aType The expected column type
1.325 +@param aRes Output parameter. Refers to the place where the result must be copied
1.326 +
1.327 +@return KErrNone, if the function completes successfully,
1.328 + Positive value, The column value length, in case if the receiving buffer
1.329 + is not big enough. This return result is possible only with text or binary columns.
1.330 +
1.331 +@leave The function may leave with database specific errors categorised as ESqlDbError and
1.332 + other system-wide error codes.
1.333 +*/
1.334 +inline TInt CSqlDatabaseImpl::ExecScalarFullSelectL(const TDesC16& aSqlStmt, TSqlColumnType aType, TDes8& aRes)
1.335 + {
1.336 + TInt rc = Session().ExecScalarFullSelect(aSqlStmt, aType, aRes);
1.337 + __SQLLEAVE_IF_ERROR(rc);
1.338 + return rc;
1.339 + }
1.340 +
1.341 +/**
1.342 +Sends a command to the server to Execute a SELECT query which is expected to return a single row consisting of
1.343 +a single column value and copies that value to the place refered by aRes parameter.
1.344 +
1.345 +@param aSqlStmt 8-bit SELECT sql query
1.346 +@param aType The expected column type
1.347 +@param aRes Output parameter. Refers to the place where the result must be copied
1.348 +
1.349 +@return KErrNone, if the function completes successfully,
1.350 + Positive value, The column value length, in case if the receiving buffer
1.351 + is not big enough. This return result is possible only with text or binary columns.
1.352 +
1.353 +@leave The function may leave with database specific errors categorised as ESqlDbError and
1.354 + other system-wide error codes.
1.355 +*/
1.356 +inline TInt CSqlDatabaseImpl::ExecScalarFullSelectL(const TDesC8& aSqlStmt, TSqlColumnType aType, TDes8& aRes)
1.357 + {
1.358 + TInt rc = Session().ExecScalarFullSelect(aSqlStmt, aType, aRes);
1.359 + __SQLLEAVE_IF_ERROR(rc);
1.360 + return rc;
1.361 + }
1.362 +
1.363 +/**
1.364 +@return True, if the database is in transaction, false otherwise.
1.365 +*/
1.366 +inline TBool CSqlDatabaseImpl::InTransaction()
1.367 + {
1.368 + return Session().SendReceive(ESqlSrvDbInTransaction) != 0;
1.369 + }
1.370 +
1.371 +/**
1.372 +@return >= 0, the operation has completed successfully. The number is the size of the main
1.373 + database file,
1.374 + KErrNoMemory, an out of memory condition has occurred;
1.375 + KErrTooBig, the database is too big and the size cannot fit into 32-bit signed integer;
1.376 + Note that database specific errors categorised as ESqlDbError, and
1.377 + other system-wide error codes may also be returned.
1.378 +*/
1.379 +inline TInt CSqlDatabaseImpl::Size()
1.380 + {
1.381 + return Session().SendReceive(ESqlSrvDbSize);
1.382 + }
1.383 +
1.384 +/**
1.385 +Returns the database file size and free space, in bytes.
1.386 +
1.387 +@param aSize An output parameter. If the call was successfull the aSize object will contain information
1.388 + about the database size and database free space.
1.389 +@param aDbName The attached database name or KNullDesC for the main database
1.390 +
1.391 +@return KErrNone, The operation has completed succesfully;
1.392 + Note that database specific errors categorised as ESqlDbError, and
1.393 + other system-wide error codes may also be returned.
1.394 +
1.395 +Usage of the IPC call arguments:
1.396 +Arg 0: [in/out] Points to a RSqldatabase::TSize object, where the database size and free space values
1.397 + will be copied.
1.398 +Arg 1: [out] The database name length in characters
1.399 +Arg 2: [out] The attached database name or KNullDesC for the main database
1.400 +*/
1.401 +inline TInt CSqlDatabaseImpl::Size(RSqlDatabase::TSize& aSize, const TDesC& aDbName)
1.402 + {
1.403 + TPtr8 ptr(reinterpret_cast <TUint8*> (&aSize), sizeof(aSize));
1.404 + return Session().SendReceive(ESqlSrvDbSize2, TIpcArgs(&ptr, aDbName.Length(), &aDbName));
1.405 + }