1.1 --- a/epoc32/include/sqldb.h Tue Nov 24 13:55:44 2009 +0000
1.2 +++ b/epoc32/include/sqldb.h Tue Mar 16 16:12:26 2010 +0000
1.3 @@ -1,1 +1,1395 @@
1.4 -sqldb.h
1.5 +// Copyright (c) 2005-2009 Nokia Corporation and/or its subsidiary(-ies).
1.6 +// All rights reserved.
1.7 +// This component and the accompanying materials are made available
1.8 +// under the terms of the License "Symbian Foundation License v1.0" to Symbian Foundation members and "Symbian Foundation End User License Agreement v1.0" to non-members
1.9 +// which accompanies this distribution, and is available
1.10 +// at the URL "http://www.symbianfoundation.org/legal/licencesv10.html".
1.11 +//
1.12 +// Initial Contributors:
1.13 +// Nokia Corporation - initial contribution.
1.14 +//
1.15 +// Contributors:
1.16 +//
1.17 +// Description:
1.18 +// SQL Client side API header
1.19 +//
1.20 +//
1.21 +
1.22 +
1.23 +
1.24 +/**
1.25 + @file
1.26 + @publishedAll
1.27 + @released
1.28 +*/
1.29 +#ifndef __SQLDB_H__
1.30 +#define __SQLDB_H__
1.31 +
1.32 +#ifndef __S32STD_H__
1.33 +#include <s32std.h> //RReadStream, RWriteStream
1.34 +#endif
1.35 +
1.36 +//Forward declarations
1.37 +class CSqlSecurityPolicy;
1.38 +class RSqlDatabase;
1.39 +class CSqlDatabaseImpl;
1.40 +class RSqlStatement;
1.41 +class CSqlStatementImpl;
1.42 +class RSqlColumnReadStream;
1.43 +class RSqlParamWriteStream;
1.44 +class TSqlScalarFullSelectQuery;
1.45 +
1.46 +/**
1.47 +A container for the security policies for a shared SQL database.
1.48 +
1.49 +The container can contain:
1.50 +- security policies that apply to the database.
1.51 +- security policies that apply to individual database objects, i.e. database tables.
1.52 +
1.53 +For the database, you use RSqlSecurityPolicy::SetDbPolicy() to apply a separate
1.54 +security policy to:
1.55 +- the database schema.
1.56 +- read activity on the database.
1.57 +- write activity on the database.
1.58 +
1.59 +For database tables, you use RSqlSecurityPolicy::SetPolicy() to apply a separate
1.60 +security policy to:
1.61 +- write activity on each named database table.
1.62 +- read activity on each named database table.
1.63 +
1.64 +A client uses a RSqlSecurityPolicy object to create a secure database. It does this by:
1.65 +- creating a RSqlSecurityPolicy object.
1.66 +- setting all the appropriate security policies into it.
1.67 +- passing the object as an argument to RSqlDatabase::Create().
1.68 +- closing the RSqlSecurityPolicy object on return from RSqlDatabase::Create().
1.69 +
1.70 +Once a secure shared database has been created with specific security policies,
1.71 +these policies are made persistent and cannot be changed during the life of
1.72 +that database.
1.73 +
1.74 +Security policies are encapsulated by TSecurityPolicy objects.
1.75 +The general usage pattern is to create the security policies container object
1.76 +(RSqlSecurityPolicy) using a default security policy (TSecurityPolicy), and then
1.77 +to assign more specific 'overriding' security policies.
1.78 +
1.79 +The following code fragment shows how you do this:
1.80 +
1.81 +@code
1.82 +TSecurityPolicy defaultPolicy;
1.83 +RSqlSecurityPolicy securityPolicy;
1.84 +RSqlDatabase database;
1.85 +TInt err;
1.86 +
1.87 +// Create security policies container object using a default security policy.
1.88 +securityPolicy.Create(defaultPolicy);
1.89 +
1.90 +// Set up policy to apply to database schema
1.91 +// and assign it
1.92 +TSecurityPolicy schemaPolicy;
1.93 +...
1.94 +err = securityPolicy.SetDbPolicy(RSqlSecurityPolicy::ESchemaPolicy, schemaPolicy);
1.95 +
1.96 +// Set up policy to apply to write activity on the database
1.97 +// and assign it
1.98 +TSecurityPolicy writePolicy;
1.99 +...
1.100 +err = securityPolicy.SetDbPolicy(RSqlSecurityPolicy::EWritePolicy, writePolicy);
1.101 +
1.102 +// Set up policy to apply to write activity to the database table named "Table1"
1.103 +// and assign it
1.104 +TSecurityPolicy tablePolicy1;
1.105 +...
1.106 +err = securityPolicy.SetPolicy(RSqlSecurityPolicy::ETable, _L("Table1"), RSqlSecurityPolicy::EWritePolicy, tablePolicy1);
1.107 +
1.108 +// Set up policy to apply to read activity to the database table named "Table2"
1.109 +TSecurityPolicy tablePolicy2;
1.110 +err = securityPolicy.SetPolicy(RSqlSecurityPolicy::ETable, _L("Table2"), RSqlSecurityPolicy::EReadPolicy, tablePolicy2);
1.111 +
1.112 +// Create the database, passing the security policies
1.113 +err = database.Create(KDatabaseName, securityPolicy);
1.114 +
1.115 +// We can close the RSqlSecurityPolicy object.
1.116 +securityPolicy.Close();
1.117 +@endcode
1.118 +
1.119 +Note that in this example code fragment, the client has not assigned specific
1.120 +overriding policies for all possible cases; for example, no overriding policy
1.121 +has been assigned to control read activity on the database, read activity
1.122 +on "Table1", nor write activity on "Table2".
1.123 +For these cases, the default security policy will apply.
1.124 +
1.125 +A client can also retrieve a database's security policies by calling
1.126 +RSqlDatabase::GetSecurityPolicy(); this returns a RSqlSecurityPolicy object
1.127 +containing the security policies. Note that it is the client's responsibility
1.128 +to close the RSqlSecurityPolicy object when the client no longer needs it. The
1.129 +following code fragment suggests how you might do this:
1.130 +
1.131 +@code
1.132 +RSqlDatabase database;
1.133 +RSqlSecurityPolicy securityPolicy;
1.134 +
1.135 +// Retrieve the security policies; on return from the call to
1.136 +// GetSecurityPolicy(), the RSqlSecurityPolicy object passed
1.137 +// to this function will contain the security policies.
1.138 +database.GetSecurityPolicy(securityPolicy);
1.139 +...
1.140 +// This is the security policy that applies to database schema
1.141 +TSecurityPolicy schemaPolicy = securityPolicy.DbPolicy(RSqlSecurityPolicy::ESchemaPolicy);
1.142 +...
1.143 +// This is the security policy that applies to write activity to the database
1.144 +// table named "Table1".
1.145 +TSecurityPolicy writePolicy = securityPolicy.Policy(RSqlSecurityPolicy::ETable, _L("Table1"), RSqlSecurityPolicy::EWritePolicy);
1.146 +...
1.147 +// Close the RSqlSecurityPolicy object when no longer needed.
1.148 +securityPolicy.Close();
1.149 +@endcode
1.150 +
1.151 +Note that in the cases where an 'overriding' security policy was not originally assigned,
1.152 +then the security policy returned will simply be the default security policy.
1.153 +
1.154 +@see TSecurityPolicy
1.155 +@see RSqlDatabase
1.156 +@see RSqlSecurityPolicy::SetDbPolicy()
1.157 +@see RSqlSecurityPolicy::SetPolicy()
1.158 +
1.159 +@publishedAll
1.160 +@released
1.161 +*/
1.162 +class RSqlSecurityPolicy
1.163 + {
1.164 + friend class RSqlDatabase;
1.165 +
1.166 +public:
1.167 + /**
1.168 + Defines a set of values that represents the database security policy types.
1.169 + Each database security policy type refers to a set of capabilities encapsulated in
1.170 + a TSecurityPolicy object. The TSecurityPolicy object defines what capabilities the calling
1.171 + application must have in order to perform partiqular database operation.
1.172 + @see TSecurityPolicy
1.173 + */
1.174 + enum TPolicyType
1.175 + {
1.176 + /**
1.177 + Schema database security policy. An application with schema database security policy can
1.178 + modify the database schema, write to database, read from database.
1.179 + */
1.180 + ESchemaPolicy,
1.181 + /**
1.182 + Read database security policy. An application with read database security policy can
1.183 + read from database.
1.184 + */
1.185 + EReadPolicy,
1.186 + /**
1.187 + Write database security policy. An application with write database security policy can
1.188 + write to database.
1.189 + */
1.190 + EWritePolicy
1.191 + };
1.192 + /**
1.193 + Not currently supported.
1.194 +
1.195 + Defines a set of values that represents the database objects which can be protected by
1.196 + database security policy types.
1.197 + */
1.198 + enum TObjectType
1.199 + {
1.200 + ETable
1.201 + };
1.202 + IMPORT_C RSqlSecurityPolicy();
1.203 + IMPORT_C TInt Create(const TSecurityPolicy& aDefaultPolicy);
1.204 + IMPORT_C void CreateL(const TSecurityPolicy& aDefaultPolicy);
1.205 + IMPORT_C void Close();
1.206 + IMPORT_C TInt SetDbPolicy(TPolicyType aPolicyType, const TSecurityPolicy& aPolicy);
1.207 + IMPORT_C TInt SetPolicy(TObjectType aObjectType, const TDesC& aObjectName, TPolicyType aPolicyType, const TSecurityPolicy& aPolicy);
1.208 + IMPORT_C TSecurityPolicy DefaultPolicy() const;
1.209 + IMPORT_C TSecurityPolicy DbPolicy(TPolicyType aPolicyType) const;
1.210 + IMPORT_C TSecurityPolicy Policy(TObjectType aObjectType, const TDesC& aObjectName, TPolicyType aPolicyType) const;
1.211 +
1.212 + IMPORT_C void ExternalizeL(RWriteStream& aStream) const;
1.213 + IMPORT_C void InternalizeL(RReadStream& aStream);
1.214 +
1.215 +private:
1.216 + void Set(CSqlSecurityPolicy& aImpl);
1.217 + CSqlSecurityPolicy& Impl() const;
1.218 +
1.219 +private:
1.220 + CSqlSecurityPolicy* iImpl;
1.221 + };
1.222 +
1.223 +/**
1.224 +A handle to a SQL database.
1.225 +
1.226 +A RSqlDatabase object is, in effect, a handle to the SQL database. A client can:
1.227 +- create a SQL database by calling RSqlDatabase::Create().
1.228 +- open an existing SQL database by calling RSqlDatabase::Open().
1.229 +- close a SQL database by calling RSqlDatabase::Close().
1.230 +- copy a SQL database by calling RSqlDatabase::Copy().
1.231 +- delete a SQL database by calling RSqlDatabase::Delete().
1.232 +- attach a SQL database to current database connection by calling RSqlDatabase::Attach().
1.233 +- detach a SQL database from current database connection by calling RSqlDatabase::Detach().
1.234 +
1.235 +A client can create either a non-secure database or a secure database,
1.236 +depending on the variant of RSqlDatabase::Create() that is used.
1.237 +- a non-secure database is created if the RSqlDatabase::Create(const TDesC&) variant is used.
1.238 +- a secure database is created if the RSqlDatabase::Create(const TDesC&, const RSqlSecurityPolicy&)
1.239 +variant is used. In this case, a container containing a collection of security
1.240 +policies needs to be set up first and passed to this Create() function.
1.241 +See references to RSqlSecurityPolicy for more information on security policies.
1.242 +
1.243 +A client can also specify how it wants a transaction to interact with
1.244 +other transactions that may be running concurrently. The various ways in which
1.245 +transactions can interact (i.e. how one transaction can affect another) are
1.246 +referred to as "transaction isolation levels", and are defined by the values
1.247 +of the TIsolationLevel enum. A client specifies this by calling RSqlDatabase::SetIsolationLevel().
1.248 +
1.249 +Each of the various flavours of Open and Create allows the optional provision of a
1.250 +configuration string. It is acceptable for this string to be missing.
1.251 +In the case where the string is missing, the config in the SqlServer.sql file
1.252 +will be used. If that does not exist then the MMH macro definitions will be used.
1.253 +
1.254 +The config string is in the format PARAM=VALUE; PARAM=VALUE;...
1.255 +
1.256 +Allowed parameters are:
1.257 + cache_size=nnnn
1.258 + page_size=nnnn
1.259 + encoding=UTF8|UTF16
1.260 +
1.261 +Badly formed config strings are reported as KErrArgument
1.262 +
1.263 +The string may not exceed 255 characters.
1.264 +
1.265 +Please note that a database can only be accessed within the thread where it has been created. It is then not possible
1.266 +to create a database from thread1 and access it from thread2.
1.267 +
1.268 +A client calls RSqlDatabase::Exec() to execute SQL statements.
1.269 +@see RSqlDatabase::Create()
1.270 +@see RSqlDatabase::Open()
1.271 +@see RSqlDatabase::Close()
1.272 +@see RSqlDatabase::Copy()
1.273 +@see RSqlDatabase::Delete()
1.274 +@see RSqlDatabase::Attach()
1.275 +@see RSqlDatabase::Detach()
1.276 +@see RSqlDatabase::SetIsolationLevel()
1.277 +@see RSqlDatabase::Exec()
1.278 +@see TIsolationLevel
1.279 +@see RSqlSecurityPolicy
1.280 +
1.281 +@publishedAll
1.282 +@released
1.283 +*/
1.284 +class RSqlDatabase
1.285 + {
1.286 + friend class RSqlStatement;
1.287 + friend class TSqlScalarFullSelectQuery;
1.288 +
1.289 +public:
1.290 + /**
1.291 + Defines a set of values that represents the transaction isolation level.
1.292 +
1.293 + A transaction isolation level defines the way in which a transaction
1.294 + interacts with other transactions that may be in progress concurrently.
1.295 +
1.296 + A client sets the transaction isolation level by calling SetIsolationLevel()
1.297 +
1.298 + @see RSqlDatabase::SetIsolationLevel()
1.299 + */
1.300 + enum TIsolationLevel
1.301 + {
1.302 + /**
1.303 + A transaction can read uncommitted data, i.e. data that is being changed
1.304 + by another transaction, which is still in progress.
1.305 +
1.306 + This means that
1.307 + - a 'database read' transaction will not block 'database write' transactions
1.308 + being performed by different database connections on the same shared database.
1.309 + - a 'database read' transaction will not be blocked by 'database write'
1.310 + transactions performed by the same database connection.
1.311 + - concurrent 'database write' transactions are prevented.
1.312 +
1.313 + This transaction isolation level can be set at any time during
1.314 + the lifetime of the database.
1.315 +
1.316 + @see TIsolationLevel
1.317 + @see RSqlDatabase::SetIsolationLevel()
1.318 + */
1.319 + EReadUncommitted,
1.320 +
1.321 + /**
1.322 + Not currently supported.
1.323 +
1.324 + A transaction cannot read uncommitted data. "Dirty reads" are prevented.
1.325 +
1.326 + "Dirty read" is a data inconsistency type which can be described with the following example:
1.327 + - Transaction A updates TableA.Column1 value from 1 to 2;
1.328 + - Transaction B reads TableA.Column1 value;
1.329 + - Transaction A rolls back and restores the original value of TableA.Column1 (1);
1.330 + - Transaction B ends showing that TableA.Column1 value is 2, even though, logically and transactionally,
1.331 + this data never really even existed in the database because Transaction A never committed that change
1.332 + to the database;
1.333 +
1.334 + @see TIsolationLevel
1.335 + @see RSqlDatabase::SetIsolationLevel()
1.336 + */
1.337 + EReadCommitted,
1.338 +
1.339 + /**
1.340 + Not currently supported.
1.341 +
1.342 + A transaction cannot change data that is being read by a different transaction.
1.343 + "Dirty reads" and "non-repeatable reads" are prevented.
1.344 +
1.345 + "Non-repeatable reads" is a data inconsistency type which can be described with the following example:
1.346 + - Transaction A reads TableA.Column1 value which is 1;
1.347 + - Transaction B updates TableA.Column1 value from 1 to 2;
1.348 + - Transaction B commits the chages;
1.349 + - Transaction A reads TableA.Column1 value again. Transaction A has inconsistent data because TableA.Column1
1.350 + value now is 2 instead of 1, all within the scope of the same Transaction A;
1.351 +
1.352 + @see TIsolationLevel
1.353 + @see RSqlDatabase::SetIsolationLevel()
1.354 + */
1.355 + ERepeatableRead,
1.356 +
1.357 + /**
1.358 + Any number of 'database read' transactions can be performed concurrently
1.359 + by different database connections on the same shared database.
1.360 +
1.361 + Only one 'database write' transaction can be performed at any one time. If a
1.362 + 'database write' transaction is in progress, then any attempt to start
1.363 + another 'database read' or 'database write' transaction will be blocked
1.364 + until the first 'database write' transaction has completed.
1.365 +
1.366 + This is the default isolation level, if no isolation level is
1.367 + explicitly set.
1.368 +
1.369 + "Dirty reads", "non-repeatable" reads and "phantom reads" are prevented.
1.370 +
1.371 + "Phantom reads" is a data inconsistency type which can be described with the following example:
1.372 + - Transaction A reads all rows that have Column1 = 1;
1.373 + - Transaction B inserts a new row which has Column1 = 1;
1.374 + - Transaction B commits;
1.375 + - Transaction A updates all rows that have Column1 = 1. This will also update the row that
1.376 + Transaction B inserted, because Transaction A must read the data again in order to update it.
1.377 + - Transaction A commits;
1.378 +
1.379 + @see TIsolationLevel
1.380 + @see RSqlDatabase::SetIsolationLevel()
1.381 + */
1.382 + ESerializable
1.383 + };
1.384 +
1.385 + IMPORT_C RSqlDatabase();
1.386 +
1.387 + IMPORT_C TInt Create(const TDesC& aDbFileName, const TDesC8* aConfig=NULL);
1.388 + IMPORT_C TInt Create(const TDesC& aDbFileName,
1.389 + const RSqlSecurityPolicy& aSecurityPolicy, const TDesC8* aConfig=NULL);
1.390 + IMPORT_C TInt Open(const TDesC& aDbFileName, const TDesC8* aConfig=NULL);
1.391 + IMPORT_C void CreateL(const TDesC& aDbFileName, const TDesC8* aConfig=NULL);
1.392 + IMPORT_C void CreateL(const TDesC& aDbFileName,
1.393 + const RSqlSecurityPolicy& aSecurityPolicy, const TDesC8* aConfig=NULL);
1.394 + IMPORT_C void OpenL(const TDesC& aDbFileName, const TDesC8* aConfig=NULL);
1.395 +
1.396 + IMPORT_C void Close();
1.397 +
1.398 + IMPORT_C TInt Attach(const TDesC& aDbFileName, const TDesC& aDbName);
1.399 + IMPORT_C TInt Detach(const TDesC& aDbName);
1.400 +
1.401 + IMPORT_C static TInt Copy(const TDesC& aSrcDbFileName, const TDesC& aDestDbFileName);
1.402 + IMPORT_C static TInt Delete(const TDesC& aDbFileName);
1.403 +
1.404 + IMPORT_C TInt GetSecurityPolicy(RSqlSecurityPolicy& aSecurityPolicy) const;
1.405 + IMPORT_C void GetSecurityPolicyL(RSqlSecurityPolicy& aSecurityPolicy) const;
1.406 +
1.407 + IMPORT_C TInt SetIsolationLevel(TIsolationLevel aIsolationLevel);
1.408 +
1.409 + IMPORT_C TInt Exec(const TDesC& aSqlStmt);
1.410 + IMPORT_C TInt Exec(const TDesC8& aSqlStmt);
1.411 +
1.412 + IMPORT_C void Exec(const TDesC& aSqlStmt, TRequestStatus& aStatus);
1.413 + IMPORT_C void Exec(const TDesC8& aSqlStmt, TRequestStatus& aStatus);
1.414 +
1.415 + IMPORT_C TPtrC LastErrorMessage() const;
1.416 +
1.417 + IMPORT_C TBool InTransaction() const;
1.418 + IMPORT_C TInt Size() const;
1.419 +
1.420 + IMPORT_C TInt ReserveDriveSpace(TInt aSize);
1.421 + IMPORT_C void FreeReservedSpace();
1.422 + IMPORT_C TInt GetReserveAccess();
1.423 + IMPORT_C void ReleaseReserveAccess();
1.424 +
1.425 +private:
1.426 + CSqlDatabaseImpl& Impl() const;
1.427 +
1.428 +private:
1.429 + CSqlDatabaseImpl* iImpl;
1.430 + };
1.431 +
1.432 +/**
1.433 +TSqlScalarFullSelectQuery interface is used for executing SELECT sql queries, which
1.434 +return a single row consisting of a single column value.
1.435 +
1.436 +Examples.
1.437 +
1.438 +CASE 1 - retrieving records count of a table:
1.439 +@code
1.440 +RSqlDatabase db;
1.441 +//initialize db object....
1.442 +.......
1.443 +TSqlScalarFullSelectQuery fullSelectQuery(db);
1.444 +TInt recCnt = fullSelectQuery.SelectIntL(_L("SELECT COUNT(*) FROM PersonTbl"));
1.445 +@endcode
1.446 +
1.447 +CASE 2 - retrieving specific column value using a condition in the SELECT statement:
1.448 +@code
1.449 +RSqlDatabase db;
1.450 +//initialize db object....
1.451 +.......
1.452 +TSqlScalarFullSelectQuery fullSelectQuery(db);
1.453 +TInt personId = fullSelectQuery.SelectIntL(_L("SELECT ID FROM PersonTbl WHERE Name = 'John'"));
1.454 +@endcode
1.455 +
1.456 +CASE 3 - retrieving a text column value, the receiving buffer is not big enough:
1.457 +@code
1.458 +RSqlDatabase db;
1.459 +//initialize db object....
1.460 +.......
1.461 +TSqlScalarFullSelectQuery fullSelectQuery(db);
1.462 +HBufC* buf = HBufC::NewLC(20);
1.463 +TPtr name = buf->Des();
1.464 +TInt rc = fullSelectQuery.SelectTextL(_L("SELECT Name FROM PersonTbl WHERE Id = 1"), name);
1.465 +TEST(rc >= 0); //the function may return only non-negative values
1.466 +if(rc > 0)
1.467 + {
1.468 + buf = buf->ReAllocL(rc);
1.469 + CleanupStack::Pop();
1.470 + CleanupStack::PushL(buf);
1.471 + name.Set(buf->Des());
1.472 + rc = fullSelectQuery.SelectTextL(_L("SELECT Name FROM PersonTbl WHERE Id = 1"), name);
1.473 + TEST(rc == 0);
1.474 + }
1.475 +CleanupStack::PopAndDestroy();//buf
1.476 +@endcode
1.477 +
1.478 +@see RSqlDatabase
1.479 +
1.480 +@publishedAll
1.481 +@released
1.482 +*/
1.483 +class TSqlScalarFullSelectQuery
1.484 + {
1.485 +public:
1.486 + IMPORT_C TSqlScalarFullSelectQuery();
1.487 + IMPORT_C TSqlScalarFullSelectQuery(RSqlDatabase& aDatabase);
1.488 + IMPORT_C void SetDatabase(RSqlDatabase& aDatabase);
1.489 +
1.490 + IMPORT_C TInt SelectIntL(const TDesC& aSqlStmt);
1.491 + IMPORT_C TInt64 SelectInt64L(const TDesC& aSqlStmt);
1.492 + IMPORT_C TReal SelectRealL(const TDesC& aSqlStmt);
1.493 + IMPORT_C TInt SelectTextL(const TDesC& aSqlStmt, TDes& aDest);
1.494 + IMPORT_C TInt SelectBinaryL(const TDesC& aSqlStmt, TDes8& aDest);
1.495 +
1.496 + IMPORT_C TInt SelectIntL(const TDesC8& aSqlStmt);
1.497 + IMPORT_C TInt64 SelectInt64L(const TDesC8& aSqlStmt);
1.498 + IMPORT_C TReal SelectRealL(const TDesC8& aSqlStmt);
1.499 + IMPORT_C TInt SelectTextL(const TDesC8& aSqlStmt, TDes& aDest);
1.500 + IMPORT_C TInt SelectBinaryL(const TDesC8& aSqlStmt, TDes8& aDest);
1.501 +
1.502 +private:
1.503 + inline CSqlDatabaseImpl& Impl() const;
1.504 +
1.505 +private:
1.506 + CSqlDatabaseImpl* iDatabaseImpl;
1.507 + };
1.508 +
1.509 +/**
1.510 +An enumeration whose values represent the supported database column types.
1.511 +
1.512 +
1.513 +@see RSqlStatement::ColumnType()
1.514 +
1.515 +@publishedAll
1.516 +@released
1.517 +*/
1.518 +enum TSqlColumnType
1.519 + {
1.520 + /**
1.521 + Null column value.
1.522 + */
1.523 + ESqlNull,
1.524 +
1.525 + /**
1.526 + 32-bit integer column value.
1.527 + */
1.528 + ESqlInt,
1.529 +
1.530 + /**
1.531 + 64-bit integer column value.
1.532 + */
1.533 + ESqlInt64,
1.534 +
1.535 + /**
1.536 + 64-bit floating point column value.
1.537 + */
1.538 + ESqlReal,
1.539 +
1.540 + /**
1.541 + Unicode text, a sequence of 16-bit character codes.
1.542 + */
1.543 + ESqlText,
1.544 +
1.545 + /**
1.546 + Binary data, a sequence of bytes.
1.547 + */
1.548 + ESqlBinary
1.549 + };
1.550 +
1.551 +/**
1.552 +Represents an SQL statement.
1.553 +
1.554 +An object of this type can be used to execute all types of SQL statements; this
1.555 +includes SQL statements with parameters.
1.556 +
1.557 +If a SELECT statament is passed to RSqlStatement::Prepare(), then the returned record set
1.558 +is forward only, non-updateable.
1.559 +
1.560 +There are a number of ways that this object is used; here are some examples.
1.561 +
1.562 +CASE 1 - the execution of a SQL statement, which does not return record set:
1.563 +
1.564 +@code
1.565 +RSqlDatabase database;
1.566 +.........
1.567 +RSqlStatement stmt;
1.568 +TInt err = stmt.Prepare(database, _L("INSERT INTO Tbl1(Fld1) VALUES(:Val)"));
1.569 +TInt paramIndex = stmt.ParameterIndex(_L(":Val"));
1.570 +for(TInt i=1;i<=10;++i)
1.571 + {
1.572 + err = stmt.BindInt(paramIndex, i);
1.573 + err = stmt.Exec();
1.574 + err = stmt.Reset();
1.575 + }
1.576 +stmt.Close();
1.577 +@endcode
1.578 +
1.579 +The following pseudo code shows the general pattern:
1.580 +
1.581 +@code
1.582 +<RSqlStatement::Prepare()>
1.583 +[begin:]
1.584 +<RSqlStatement::Bind<param_type>()>
1.585 +<RSqlStatement::Exec()>
1.586 +[<RSqlStatement::Reset()>]
1.587 +[<RSqlStatement::Bind<param_type>()>]
1.588 +[<Goto :begin>]
1.589 +@endcode
1.590 +
1.591 +CASE 2 - the execution of a SQL statement, which returns a record set:
1.592 +
1.593 +@code
1.594 +RSqlDatabase database;
1.595 +.........
1.596 +RSqlStatement stmt;
1.597 +TInt err = stmt.Prepare(database, _L("SELECT Fld1 FROM Tbl1 WHERE Fld1 > :Val"));
1.598 +TInt paramIndex = stmt.ParameterIndex(_L(":Val"));
1.599 +err = stmt.BindInt(paramIndex, 5);
1.600 +TInt columnIndex = stmt.ColumnIndex(_L("Fld1"));
1.601 +while((err = stmt.Next()) == KSqlAtRow)
1.602 + {
1.603 + TInt val = stmt.ColumnInt(columnIndex);
1.604 + RDebug::Print(_L("val=%d\n"), val);
1.605 + }
1.606 +if(err == KSqlAtEnd)
1.607 + <OK - no more records>;
1.608 +else
1.609 + <process the error>;
1.610 +stmt.Close();
1.611 +@endcode
1.612 +
1.613 +The following pseudo code shows the general pattern:
1.614 +
1.615 +@code
1.616 +<RSqlStatement::Prepare()>
1.617 +[begin:]
1.618 +<while (RSqlStatement::Next() == KSqlAtRow)>
1.619 + <do something with the records>
1.620 +if(err == KSqlAtEnd)
1.621 + <OK - no more records>;
1.622 +else
1.623 + <process the error>;
1.624 +[<RSqlStatement::Reset()>]
1.625 +[<RSqlStatement::Bind<param_type>()>]
1.626 +[<Goto begin>]
1.627 +@endcode
1.628 +
1.629 +CASE 3.1 - SELECT statements: large column data processing, where the data is
1.630 +copied into a buffer supplied by the client:
1.631 +
1.632 +@code
1.633 +RSqlDatabase database;
1.634 +.........
1.635 +RSqlStatement stmt;
1.636 +TInt err = stmt.Prepare(database, _L("SELECT BinaryField FROM Tbl1"));
1.637 +TInt columnIndex = stmt.ColumnIndex(_L("BinaryField"));
1.638 +while((err = stmt.Next()) == KSqlAtRow)
1.639 + {
1.640 + TInt size = stmt. ColumnSize(columnIndex);
1.641 + HBufC8* buf = HBufC8::NewL(size);
1.642 + err = stmt.ColumnBinary(columnIndex, buf->Ptr());
1.643 + <do something with the data>;
1.644 + delete buf;
1.645 + }
1.646 +if(err == KSqlAtEnd)
1.647 + <OK - no more records>;
1.648 +else
1.649 + <process the error>;
1.650 +stmt.Close();
1.651 +@endcode
1.652 +
1.653 +CASE 3.2 - SELECT statements: large column data processing, where the data is
1.654 +accessed by the client without copying:
1.655 +
1.656 +@code
1.657 +RSqlDatabase database;
1.658 +.........
1.659 +RSqlStatement stmt;
1.660 +TInt err = stmt.Prepare(database, _L("SELECT BinaryField FROM Tbl1"));
1.661 +TInt columnIndex = stmt.ColumnIndex(_L("BinaryField"));
1.662 +while((err = stmt.Next()) == KSqlAtRow)
1.663 + {
1.664 + TPtrC8 data = stmt.ColumnBinaryL(columnIndex);
1.665 + <do something with the data>;
1.666 + }
1.667 +if(err == KSqlAtEnd)
1.668 + <OK - no more records>;
1.669 +else
1.670 + <process the error>;
1.671 +stmt.Close();
1.672 +@endcode
1.673 +
1.674 +CASE 3.3 - SELECT statements, large column data processing (the data is accessed by
1.675 +the client without copying), leaving-safe processing:
1.676 +
1.677 +@code
1.678 +RSqlDatabase database;
1.679 +.........
1.680 +RSqlStatement stmt;
1.681 +TInt err = stmt.Prepare(database, _L("SELECT BinaryField FROM Tbl1"));
1.682 +TInt columnIndex = stmt.ColumnIndex(_L("BinaryField"));
1.683 +while((err = stmt.Next()) == KSqlAtRow)
1.684 + {
1.685 + TPtrC8 data;
1.686 + TInt err = stmt.ColumnBinary(columnIndex, data);
1.687 + if(err == KErrNone)
1.688 + {
1.689 + <do something with the data>;
1.690 + }
1.691 + }
1.692 +if(err == KSqlAtEnd)
1.693 + <OK - no more records>;
1.694 +else
1.695 + <process the error>;
1.696 +stmt.Close();
1.697 +@endcode
1.698 +
1.699 +CASE 3.4 - SELECT statements: large column data processing, where the data is
1.700 +accessed by the client using a stream:
1.701 +
1.702 +@code
1.703 +RSqlDatabase database;
1.704 +.........
1.705 +RSqlStatement stmt;
1.706 +TInt err = stmt.Prepare(database, _L("SELECT BinaryField FROM Tbl1"));
1.707 +TInt columnIndex = stmt.ColumnIndex(_L("BinaryField"));
1.708 +while((err = stmt.Next()) == KSqlAtRow)
1.709 + {
1.710 + RSqlColumnReadStream stream;
1.711 + err = stream.ColumnBinary(stmt, columnIndex);
1.712 + <do something with the data in the stream>;
1.713 + stream.Close();
1.714 + }
1.715 +if(err == KSqlAtEnd)
1.716 + <OK - no more records>;
1.717 +else
1.718 + <process the error>;
1.719 +stmt.Close();
1.720 +@endcode
1.721 +
1.722 +CASE 4 - the execution of a SQL statement with parameter(s), some of which may
1.723 +be large text or binary values:
1.724 +
1.725 +@code
1.726 +RSqlDatabase database;
1.727 +.........
1.728 +RSqlStatement stmt;
1.729 +TInt err =
1.730 + stmt.Prepare(database, _L("UPDATE Tbl1 SET LargeTextField = :LargeTextVal WHERE IdxField = :KeyVal"));
1.731 +TInt paramIndex1 = stmt.ParameterIndex(_L(":LargeTextVal"));
1.732 +TInt paramIndex2 = stmt.ParameterIndex(_L(":KeyVal"));
1.733 +for(TInt i=1;i<=10;++i)
1.734 + {
1.735 + RSqlParamWriteStream stream;
1.736 + err = stream.BindText(stmt, paramIndex1);
1.737 + <insert large text data into the stream>;
1.738 + stream.Close();
1.739 + err = stmt.BindInt(paramIndex2, i);
1.740 + err = stmt.Exec();
1.741 + stmt.Reset();
1.742 + }
1.743 +stmt.Close();
1.744 +@endcode
1.745 +
1.746 +The following table shows what is returned when the caller uses a specific
1.747 +column data retrieving function on a specific column type.
1.748 +
1.749 +@code
1.750 +--------------------------------------------------------------------------------
1.751 +Column type | ColumnInt() ColumnInt64() ColumnReal() ColumnText() ColumnBinary()
1.752 +--------------------------------------------------------------------------------
1.753 +Null........|.0...........0.............0.0..........KNullDesC....KNullDesC8
1.754 +Int.........|.Int.........Int64.........Real.........KNullDesC....KNullDesC8
1.755 +Int64.......|.clamp.......Int64.........Real.........KNullDesC....KNullDesC8
1.756 +Real........|.round.......round.........Real.........KNullDesC....KNullDesC8
1.757 +Text........|.0...........0.............0.0..........Text.........KNullDesC8
1.758 +Binary......|.0...........0.............0.0..........KNullDesC....Binary
1.759 +--------------------------------------------------------------------------------
1.760 +@endcode
1.761 +Note the following definitions:
1.762 +- "clamp": return KMinTInt or KMaxTInt if the value is outside the range that can be
1.763 +represented by the type returned by the accessor function.
1.764 +- "round": the floating point value will be rounded up to the nearest integer.
1.765 +If the result is outside the range that can be represented by the type returned
1.766 +by the accessor function, then it will be clamped.
1.767 +
1.768 +@see KMinTInt
1.769 +@see KMaxTInt
1.770 +@see KNullDesC
1.771 +@see KNullDesC8
1.772 +
1.773 +@publishedAll
1.774 +@released
1.775 +*/
1.776 +class RSqlStatement
1.777 + {
1.778 + friend class RSqlColumnReadStream;
1.779 + friend class RSqlParamWriteStream;
1.780 +
1.781 +public:
1.782 + IMPORT_C RSqlStatement();
1.783 + IMPORT_C TInt Prepare(RSqlDatabase& aDatabase, const TDesC& aSqlStmt);
1.784 + IMPORT_C TInt Prepare(RSqlDatabase& aDatabase, const TDesC8& aSqlStmt);
1.785 + IMPORT_C void PrepareL(RSqlDatabase& aDatabase, const TDesC& aSqlStmt);
1.786 + IMPORT_C void PrepareL(RSqlDatabase& aDatabase, const TDesC8& aSqlStmt);
1.787 + IMPORT_C void Close();
1.788 + IMPORT_C TBool AtRow() const;
1.789 + IMPORT_C TInt Reset();
1.790 + IMPORT_C TInt Exec();
1.791 + IMPORT_C void Exec(TRequestStatus& aStatus);
1.792 + IMPORT_C TInt Next();
1.793 +
1.794 + IMPORT_C TInt ParameterIndex(const TDesC& aParameterName) const;
1.795 + IMPORT_C TInt ColumnCount() const;
1.796 + IMPORT_C TInt ColumnIndex(const TDesC& aColumnName) const;
1.797 + IMPORT_C TSqlColumnType ColumnType(TInt aColumnIndex) const;
1.798 + IMPORT_C TInt DeclaredColumnType(TInt aColumnIndex, TSqlColumnType& aColumnType) const;
1.799 + IMPORT_C TInt ColumnSize(TInt aColumnIndex) const;
1.800 +
1.801 + IMPORT_C TInt BindNull(TInt aParameterIndex);
1.802 + IMPORT_C TInt BindInt(TInt aParameterIndex, TInt aParameterValue);
1.803 + IMPORT_C TInt BindInt64(TInt aParameterIndex, TInt64 aParameterValue);
1.804 + IMPORT_C TInt BindReal(TInt aParameterIndex, TReal aParameterValue);
1.805 + IMPORT_C TInt BindText(TInt aParameterIndex, const TDesC& aParameterText);
1.806 + IMPORT_C TInt BindBinary(TInt aParameterIndex, const TDesC8& aParameterData);
1.807 +
1.808 + IMPORT_C TBool IsNull(TInt aColumnIndex) const;
1.809 + IMPORT_C TInt ColumnInt(TInt aColumnIndex) const;
1.810 + IMPORT_C TInt64 ColumnInt64(TInt aColumnIndex) const;
1.811 + IMPORT_C TReal ColumnReal(TInt aColumnIndex) const;
1.812 +
1.813 + IMPORT_C TPtrC ColumnTextL(TInt aColumnIndex) const;
1.814 + IMPORT_C TInt ColumnText(TInt aColumnIndex, TPtrC& aPtr) const;
1.815 + IMPORT_C TInt ColumnText(TInt aColumnIndex, TDes& aDest) const;
1.816 +
1.817 + IMPORT_C TPtrC8 ColumnBinaryL(TInt aColumnIndex) const;
1.818 + IMPORT_C TInt ColumnBinary(TInt aColumnIndex, TPtrC8& aPtr) const;
1.819 + IMPORT_C TInt ColumnBinary(TInt aColumnIndex, TDes8& aDest) const;
1.820 +
1.821 +private:
1.822 + CSqlStatementImpl& Impl() const;
1.823 +
1.824 +private:
1.825 + CSqlStatementImpl* iImpl;
1.826 +
1.827 + };
1.828 +
1.829 +/**
1.830 +The read stream interface.
1.831 +
1.832 +The class is used for reading the content of a column containing a large
1.833 +amount of either binary data or text data.
1.834 +
1.835 +The class derives from RReadStream, which means that all RReadStream public
1.836 +member functions and predefined stream operators \>\> can be used to deal
1.837 +with column data.
1.838 +
1.839 +The following two cases are typical:
1.840 +
1.841 +CASE 1 - processing large binary column data.
1.842 +
1.843 +@code
1.844 +RSqlDatabase db;
1.845 +<open/create "db" object>;
1.846 +RSqlStatement stmt;
1.847 +<prepare "stmt" object>;
1.848 +TInt rc = stmt.Next();
1.849 +if(rc == KSqlAtRow)
1.850 + {
1.851 + RSqlColumnReadStream colStream;
1.852 + CleanupClosePushL(colStream);
1.853 + User::LeaveIfError(colStream.ColumnBinary(stmt, <column_number>));
1.854 + TInt size = stmt.ColumnSize(<column_number>);
1.855 + //read the column data in a buffer ("buf" variable).
1.856 + //(or the column data can be retrieved in a smaller portions)
1.857 + colStream.ReadL(buf, size);
1.858 + //Close the stream
1.859 + CleanupStack::PopAndDestroy(&colStream);
1.860 + }
1.861 +else
1.862 + {
1.863 + ...
1.864 + }
1.865 +@endcode
1.866 +
1.867 +CASE 2 - processing large text column data.
1.868 +
1.869 +@code
1.870 +RSqlDatabase db;
1.871 +<open/create "db" object>;
1.872 +RSqlStatement stmt;
1.873 +<prepare "stmt" object>;
1.874 +TInt rc = stmt.Next();
1.875 +if(rc == KSqlAtRow)
1.876 + {
1.877 + RSqlColumnReadStream colStream;
1.878 + CleanupClosePushL(colStream);
1.879 + User::LeaveIfError(colStream.ColumnText(stmt, <column_number>));
1.880 + TInt size = stmt.ColumnSize(<column_number>);
1.881 + //read the column data in a buffer ("buf" variable).
1.882 + //(or the column data can be retrieved in a smaller portions)
1.883 + colStream.ReadL(buf, size);
1.884 + //Close the stream
1.885 + CleanupStack::PopAndDestroy(&colStream);
1.886 + }
1.887 +else
1.888 + {
1.889 + ...
1.890 + }
1.891 +@endcode
1.892 +
1.893 +@publishedAll
1.894 +@released
1.895 +*/
1.896 +class RSqlColumnReadStream : public RReadStream
1.897 + {
1.898 +public:
1.899 + IMPORT_C TInt ColumnText(RSqlStatement& aStmt, TInt aColumnIndex);
1.900 + IMPORT_C TInt ColumnBinary(RSqlStatement& aStmt, TInt aColumnIndex);
1.901 + IMPORT_C void ColumnTextL(RSqlStatement& aStmt, TInt aColumnIndex);
1.902 + IMPORT_C void ColumnBinaryL(RSqlStatement& aStmt, TInt aColumnIndex);
1.903 +
1.904 + };
1.905 +
1.906 +/**
1.907 +The write stream interface.
1.908 +
1.909 +The class is used to set a large amount of either binary data or text data
1.910 +into a parameter. This is a also known as binding a parameter.
1.911 +
1.912 +The class derives from RWriteStream, which means that all RWriteStream public
1.913 +member functions and predefined stream operators \<\< can be used to deal with
1.914 +the parameter data.
1.915 +
1.916 +The following two cases are typical:
1.917 +
1.918 +CASE 1 - binding a large binary parameter.
1.919 +
1.920 +@code
1.921 +RSqlDatabase db;
1.922 +<open/create "db" object>;
1.923 +RSqlStatement stmt;
1.924 +<prepare "stmt" object>;//The SQL statement references large binary parameter
1.925 +RSqlParamWriteStream paramStream;
1.926 +CleanupClosePushL(paramStream);
1.927 +User::LeaveIfError(paramStream.BindBinary(stmt, <parameter_number>));
1.928 +//Write out the parameter data
1.929 +paramStream.WriteL(..);
1.930 +paramStream << <data>;
1.931 +...
1.932 +//Commit the stream
1.933 +paramStream.CommitL();
1.934 +//Continue with the statement processing issuing Next() or Exec().
1.935 +TInt rc = stmt.Next();//rc = stmt.Exec()
1.936 +//Close the stream
1.937 +CleanupStack::PopAndDestroy(¶mStream);
1.938 +@endcode
1.939 +
1.940 +CASE 2 - binding a large text parameter.
1.941 +
1.942 +@code
1.943 +RSqlDatabase db;
1.944 +<open/create "db" object>;
1.945 +RSqlStatement stmt;
1.946 +<prepare "stmt" object>;//The SQL statement references large text parameter
1.947 +RSqlParamWriteStream paramStream;
1.948 +CleanupClosePushL(paramStream);
1.949 +User::LeaveIfError(paramStream.BindText(stmt, <parameter_number>));
1.950 +//Write out the parameter data
1.951 +paramStream.WriteL(..);
1.952 +paramStream << <data>;
1.953 +...
1.954 +//Commit the stream
1.955 +paramStream.CommitL();
1.956 +//Continue with the statement processing issuing Next() or Exec().
1.957 +TInt rc = stmt.Next();//rc = stmt.Exec()
1.958 +//Close the stream
1.959 +CleanupStack::PopAndDestroy(¶mStream);
1.960 +@endcode
1.961 +
1.962 +@publishedAll
1.963 +@released
1.964 +*/
1.965 +class RSqlParamWriteStream : public RWriteStream
1.966 + {
1.967 +public:
1.968 + IMPORT_C TInt BindText(RSqlStatement& aStmt, TInt aParameterIndex);
1.969 + IMPORT_C TInt BindBinary(RSqlStatement& aStmt, TInt aParameterIndex);
1.970 + IMPORT_C void BindTextL(RSqlStatement& aStmt, TInt aParameterIndex);
1.971 + IMPORT_C void BindBinaryL(RSqlStatement& aStmt, TInt aParameterIndex);
1.972 +
1.973 + };
1.974 +
1.975 +/**
1.976 +TSqlResourceTester class is used internally by the SQL server out of memory and resource leaking
1.977 +tests.
1.978 +It provides methods for heap allocation failure simulation and resource checking and counting.
1.979 +
1.980 +@internalAll
1.981 +@released
1.982 +*/
1.983 +class TSqlResourceTester
1.984 + {
1.985 +public:
1.986 + IMPORT_C static void Mark();
1.987 + IMPORT_C static void Check();
1.988 + IMPORT_C static TInt Count();
1.989 + IMPORT_C static void SetDbHeapFailure(TInt aAllocFailType,TInt aRate);
1.990 + IMPORT_C static void SetHeapFailure(TInt aAllocFailType,TInt aRate);
1.991 +
1.992 + };
1.993 +
1.994 +/**
1.995 +Defines a set of categories for the values returned by the SQL API.
1.996 +
1.997 +A call to an SQL API may complete with a non-zero return code indicating that some
1.998 +unexpected behaviour has occurred. This can be categorised in a number of ways,
1.999 +for example, as a Symbian OS error, or as a database error etc.
1.1000 +
1.1001 +Callers to the SQL API may not want to be concerned with the detailed meaning of
1.1002 +a specific return code value, and may find it sufficient just to know the category
1.1003 +of the error.
1.1004 +
1.1005 +The category associated with a specific return code can be found by passing the
1.1006 +return code value to the function SqlRetCodeClass().
1.1007 +
1.1008 +@publishedAll
1.1009 +@released
1.1010 +*/
1.1011 +enum TSqlRetCodeClass
1.1012 + {
1.1013 + /**
1.1014 + Indicates that a return code is just for information.
1.1015 +
1.1016 + This category corresponds to the SQL API return codes: KSqlAtRow and KSqlAtEnd.
1.1017 +
1.1018 + @see SqlRetCodeClass()
1.1019 + @see TSqlRetCodeClass
1.1020 + @see KSqlAtRow
1.1021 + @see KSqlAtEnd
1.1022 + */
1.1023 + ESqlInformation,
1.1024 +
1.1025 + /**
1.1026 + Indicates that a return code represents a database-specific error.
1.1027 +
1.1028 + This category corresponds to SQL API return codes in the range KSqlErrGeneral to KSqlErrStmtExpired.
1.1029 +
1.1030 + @see SqlRetCodeClass()
1.1031 + @see TSqlRetCodeClass
1.1032 + @see KSqlErrGeneral
1.1033 + @see KSqlErrStmtExpired
1.1034 + */
1.1035 + ESqlDbError,
1.1036 +
1.1037 + /**
1.1038 + Indicates that a return code represents a Symbian OS error.
1.1039 +
1.1040 + This category corresponds to SQL API return codes in the range KErrPermissionDenied to KErrNone,
1.1041 +
1.1042 + @see SqlRetCodeClass()
1.1043 + @see TSqlRetCodeClass
1.1044 + @see KErrPermissionDenied
1.1045 + @see KErrNone
1.1046 + */
1.1047 + ESqlOsError
1.1048 + };
1.1049 +
1.1050 +/**
1.1051 +An information type return code from a call to RSqlStatement::Next().
1.1052 +
1.1053 +It means that the RSqlStatement object points to a valid row, and that
1.1054 +the user can access the column data using the appropriate RSqlStatement
1.1055 +member functions.
1.1056 +
1.1057 +@see RSqlStatement::Next()
1.1058 +@see RSqlStatement
1.1059 +@see ESqlInformation
1.1060 +@see TSqlRetCodeClass
1.1061 +
1.1062 +@publishedAll
1.1063 +@released
1.1064 +*/
1.1065 +const TInt KSqlAtRow = 1;
1.1066 +
1.1067 +/**
1.1068 +An information type return code from a call to RSqlStatement::Next().
1.1069 +
1.1070 +It means that the RSqlStatement object does not point to a valid row,
1.1071 +and that column data accessors cannot be used.
1.1072 +
1.1073 +@see RSqlStatement::Next()
1.1074 +@see RSqlStatement
1.1075 +@see ESqlInformation
1.1076 +@see TSqlRetCodeClass
1.1077 +
1.1078 +@publishedAll
1.1079 +@released
1.1080 +*/
1.1081 +const TInt KSqlAtEnd = 2;
1.1082 +
1.1083 +/**
1.1084 +An SQL database-specific error type return code from a call to the SQL API.
1.1085 +
1.1086 +It indicates a general SQL error or a missing database.
1.1087 +
1.1088 +@see RSqlStatement
1.1089 +@see ESqlDbError
1.1090 +@see TSqlRetCodeClass
1.1091 +
1.1092 +@publishedAll
1.1093 +@released
1.1094 +*/
1.1095 +const TInt KSqlErrGeneral = -311;
1.1096 +
1.1097 +/**
1.1098 +An SQL database-specific error type return code from a call to the SQL API.
1.1099 +
1.1100 +It indicates an internal logic error in the SQL database engine, and specifically
1.1101 +that an internal consistency check within the SQL database engine has failed.
1.1102 +
1.1103 +@see RSqlStatement
1.1104 +@see ESqlDbError
1.1105 +@see TSqlRetCodeClass
1.1106 +
1.1107 +@publishedAll
1.1108 +@released
1.1109 +*/
1.1110 +const TInt KSqlErrInternal = -312;
1.1111 +
1.1112 +/**
1.1113 +An SQL database-specific error type return code from a call to the SQL API.
1.1114 +
1.1115 +It indicates that access permission has been denied.
1.1116 +
1.1117 +@see RSqlStatement
1.1118 +@see ESqlDbError
1.1119 +@see TSqlRetCodeClass
1.1120 +
1.1121 +@publishedAll
1.1122 +@released
1.1123 +*/
1.1124 +const TInt KSqlErrPermission = -313;
1.1125 +
1.1126 +/**
1.1127 +An SQL database-specific error type return code from a call to the SQL API.
1.1128 +
1.1129 +It indicates an internal logic error in the SQL database engine, and specifically
1.1130 +that a callback routine requested an abort.
1.1131 +
1.1132 +@publishedAll
1.1133 +@released
1.1134 +*/
1.1135 +const TInt KSqlErrAbort = -314;
1.1136 +
1.1137 +/**
1.1138 +An SQL database-specific error type return code from a call to the SQL API.
1.1139 +
1.1140 +It indicates that the database file is locked.
1.1141 +
1.1142 +@see RSqlStatement
1.1143 +@see ESqlDbError
1.1144 +@see TSqlRetCodeClass
1.1145 +
1.1146 +@publishedAll
1.1147 +@released
1.1148 +*/
1.1149 +const TInt KSqlErrBusy = -315;
1.1150 +
1.1151 +/**
1.1152 +An SQL database-specific error type return code from a call to the SQL API.
1.1153 +
1.1154 +It indicates that a table in the database is locked.
1.1155 +
1.1156 +@see RSqlStatement
1.1157 +@see ESqlDbError
1.1158 +@see TSqlRetCodeClass
1.1159 +
1.1160 +@publishedAll
1.1161 +@released
1.1162 +*/
1.1163 +const TInt KSqlErrLocked = -316;
1.1164 +
1.1165 +/**
1.1166 +An SQL database-specific error type return code from a call to the SQL API.
1.1167 +
1.1168 +It indicates an attempt to write to a database that is read-only.
1.1169 +
1.1170 +@see RSqlStatement
1.1171 +@see ESqlDbError
1.1172 +@see TSqlRetCodeClass
1.1173 +
1.1174 +@publishedAll
1.1175 +@released
1.1176 +*/
1.1177 +const TInt KSqlErrReadOnly = -318;
1.1178 +
1.1179 +/**
1.1180 +SQL database-specific error type. Operation terminated.
1.1181 +
1.1182 +@publishedAll
1.1183 +@released
1.1184 +*/
1.1185 +const TInt KSqlErrInterrupt = -319;
1.1186 +
1.1187 +/**
1.1188 +An SQL database-specific error type return code from a call to the SQL API.
1.1189 +
1.1190 +It indicates that a disk I/O error has occurred.
1.1191 +
1.1192 +@see RSqlStatement
1.1193 +@see ESqlDbError
1.1194 +@see TSqlRetCodeClass
1.1195 +
1.1196 +@publishedAll
1.1197 +@released
1.1198 +*/
1.1199 +const TInt KSqlErrIO = -320;
1.1200 +
1.1201 +/**
1.1202 +An SQL database-specific error type return code from a call to the SQL API.
1.1203 +
1.1204 +It indicates that the database disk image is malformed.
1.1205 +
1.1206 +@see RSqlStatement
1.1207 +@see ESqlDbError
1.1208 +@see TSqlRetCodeClass
1.1209 +
1.1210 +@publishedAll
1.1211 +@released
1.1212 +*/
1.1213 +const TInt KSqlErrCorrupt = -321;
1.1214 +
1.1215 +/**
1.1216 +SQL database-specific error type. Table or record not found.
1.1217 +
1.1218 +@publishedAll
1.1219 +@released
1.1220 +*/
1.1221 +const TInt KSqlErrNotFound = -322;
1.1222 +
1.1223 +/**
1.1224 +An SQL database-specific error type return code from a call to the SQL API.
1.1225 +
1.1226 +It indicates that an insertion operation has failed because an autoincrement column used up
1.1227 +all awailable rowids.
1.1228 +
1.1229 +@see RSqlStatement
1.1230 +@see ESqlDbError
1.1231 +@see TSqlRetCodeClass
1.1232 +
1.1233 +@publishedAll
1.1234 +@released
1.1235 +*/
1.1236 +const TInt KSqlErrFull = -323;
1.1237 +
1.1238 +/**
1.1239 +An SQL database-specific error type return code from a call to the SQL API.
1.1240 +
1.1241 +It indicates a failure to open the database file.
1.1242 +
1.1243 +@see RSqlStatement
1.1244 +@see ESqlDbError
1.1245 +@see TSqlRetCodeClass
1.1246 +
1.1247 +@publishedAll
1.1248 +@released
1.1249 +*/
1.1250 +const TInt KSqlErrCantOpen = -324;
1.1251 +
1.1252 +/**
1.1253 +An SQL database-specific error type return code from a call to the SQL API.
1.1254 +
1.1255 +It indicates a database lock protocol error.
1.1256 +
1.1257 +@see RSqlStatement
1.1258 +@see ESqlDbError
1.1259 +@see TSqlRetCodeClass
1.1260 +
1.1261 +@publishedAll
1.1262 +@released
1.1263 +*/
1.1264 +const TInt KSqlErrProtocol = -325;
1.1265 +
1.1266 +/**
1.1267 +An SQL database-specific error type return code from a call to the SQL API.
1.1268 +
1.1269 +It indicates that the database is empty.
1.1270 +
1.1271 +@see RSqlStatement
1.1272 +@see ESqlDbError
1.1273 +@see TSqlRetCodeClass
1.1274 +
1.1275 +@publishedAll
1.1276 +@released
1.1277 +*/
1.1278 +const TInt KSqlErrEmpty = -326;
1.1279 +
1.1280 +/**
1.1281 +An SQL database-specific error type return code from a call to the SQL API.
1.1282 +
1.1283 +It indicates that a prepared SQL statement is no longer valid
1.1284 +and cannot be executed.
1.1285 +
1.1286 +The most common reason for this return code is that the database schema was modified after
1.1287 +the SQL statement was prepared. The SQL statement must be prepared again
1.1288 +using the RSqlStatement::Prepare() member functions.
1.1289 +
1.1290 +Another possible reason for this return code is a detached database.
1.1291 +
1.1292 +@see RSqlStatement
1.1293 +@see ESqlDbError
1.1294 +@see TSqlRetCodeClass
1.1295 +
1.1296 +@publishedAll
1.1297 +@released
1.1298 +*/
1.1299 +const TInt KSqlErrSchema = -327;
1.1300 +
1.1301 +/**
1.1302 +SQL database-specific error type. Too much data for one row.
1.1303 +
1.1304 +@publishedAll
1.1305 +@released
1.1306 +*/
1.1307 +const TInt KSqlErrTooBig = -328;
1.1308 +
1.1309 +/**
1.1310 +An SQL database-specific error type return code from a call to the SQL API.
1.1311 +
1.1312 +It indicates an abort due to constraint violation.
1.1313 +
1.1314 +"Constraint violation" means violation of one or more column constraints ("NOT NULL", "PRIMARY KEY",
1.1315 +"UNIQUE", "CHECK", "DEFAULT", "COLLATE" SQL keywords) or table constraints ("PRIMARY KEY", "UNIQUE",
1.1316 +"CHECK" SQL keywords).
1.1317 +
1.1318 +@see RSqlStatement
1.1319 +@see ESqlDbError
1.1320 +@see TSqlRetCodeClass
1.1321 +
1.1322 +@publishedAll
1.1323 +@released
1.1324 +*/
1.1325 +const TInt KSqlErrConstraint = -329;
1.1326 +
1.1327 +/**
1.1328 +An SQL database-specific error type return code from a call to the SQL API.
1.1329 +
1.1330 +It indicates a data type mismatch.
1.1331 +
1.1332 +@see RSqlStatement
1.1333 +@see ESqlDbError
1.1334 +@see TSqlRetCodeClass
1.1335 +
1.1336 +@publishedAll
1.1337 +@released
1.1338 +*/
1.1339 +const TInt KSqlErrMismatch = -330;
1.1340 +
1.1341 +/**
1.1342 +An SQL database-specific error type return code from a call to the SQL API.
1.1343 +
1.1344 +It indicates an internal logic error in the SQL database engine.
1.1345 +
1.1346 +@see RSqlStatement
1.1347 +@see ESqlDbError
1.1348 +@see TSqlRetCodeClass
1.1349 +
1.1350 +@publishedAll
1.1351 +@released
1.1352 +*/
1.1353 +const TInt KSqlErrMisuse = -331;
1.1354 +
1.1355 +/**
1.1356 +An SQL database-specific error type return code from a call to the SQL API.
1.1357 +
1.1358 +It indicates that a parameter index value is out of range.
1.1359 +
1.1360 +@see RSqlStatement
1.1361 +@see ESqlDbError
1.1362 +@see TSqlRetCodeClass
1.1363 +
1.1364 +@publishedAll
1.1365 +@released
1.1366 +*/
1.1367 +const TInt KSqlErrRange = -335;
1.1368 +
1.1369 +/**
1.1370 +An SQL database-specific error type return code from a call to the SQL API.
1.1371 +
1.1372 +It indicates that the file that has been opened is not a database file.
1.1373 +
1.1374 +@see RSqlStatement
1.1375 +@see ESqlDbError
1.1376 +@see TSqlRetCodeClass
1.1377 +
1.1378 +@publishedAll
1.1379 +@released
1.1380 +*/
1.1381 +const TInt KSqlErrNotDb = -336;
1.1382 +
1.1383 +/**
1.1384 +An SQL database-specific error type return code from a call to the SQL API.
1.1385 +
1.1386 +It indicates that an SQL statement has expired, and needs to be prepared again.
1.1387 +
1.1388 +@see RSqlStatement
1.1389 +@see ESqlDbError
1.1390 +@see TSqlRetCodeClass
1.1391 +
1.1392 +@publishedAll
1.1393 +@released
1.1394 +*/
1.1395 +const TInt KSqlErrStmtExpired = -360;
1.1396 +
1.1397 +IMPORT_C TSqlRetCodeClass SqlRetCodeClass(TInt aSqlRetCode);
1.1398 +
1.1399 +#endif //__SQLDB_H__