1.1 --- /dev/null Thu Jan 01 00:00:00 1970 +0000
1.2 +++ b/os/persistentdata/persistentstorage/sql/INC/SqlDb.h Fri Jun 15 03:10:57 2012 +0200
1.3 @@ -0,0 +1,1762 @@
1.4 +// Copyright (c) 2005-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 +// SQL Client side API header
1.18 +//
1.19 +//
1.20 +
1.21 +/**
1.22 + @file
1.23 + @publishedAll
1.24 + @released
1.25 +*/
1.26 +#ifndef __SQLDB_H__
1.27 +#define __SQLDB_H__
1.28 +
1.29 +#ifndef __S32STD_H__
1.30 +#include <s32std.h> //RReadStream, RWriteStream
1.31 +#endif
1.32 +
1.33 +#ifndef SYMBIAN_ENABLE_SPLIT_HEADERS
1.34 + #include <sqlresourcetester.h>
1.35 +#endif
1.36 +
1.37 +//Forward declarations
1.38 +class CSqlSecurityPolicy;
1.39 +class RSqlDatabase;
1.40 +class CSqlDatabaseImpl;
1.41 +class RSqlStatement;
1.42 +class CSqlStatementImpl;
1.43 +class RSqlColumnReadStream;
1.44 +class RSqlParamWriteStream;
1.45 +class TSqlScalarFullSelectQuery;
1.46 +class RSqlBlob;
1.47 +class RSqlBlobReadStream;
1.48 +class RSqlBlobWriteStream;
1.49 +class TSqlResourceProfiler;
1.50 +
1.51 +/**
1.52 +Used to specify that the ROWID of the most recently inserted record
1.53 +from the specified database connection should be used as the ROWID
1.54 +in a call to directly access a blob.
1.55 +
1.56 +@see RSqlBlobReadStream
1.57 +@see RSqlBlobWriteStream
1.58 +@see TSqlBlob
1.59 +
1.60 +@publishedAll
1.61 +@released
1.62 +*/
1.63 +const TInt KSqlLastInsertedRowId = -1;
1.64 +
1.65 +/**
1.66 +A container for the security policies for a shared SQL database.
1.67 +
1.68 +The container can contain:
1.69 +- security policies that apply to the database.
1.70 +- security policies that apply to individual database objects, i.e. database tables.
1.71 +
1.72 +For the database, you use RSqlSecurityPolicy::SetDbPolicy() to apply a separate
1.73 +security policy to:
1.74 +- the database schema.
1.75 +- read activity on the database.
1.76 +- write activity on the database.
1.77 +
1.78 +For database tables, you use RSqlSecurityPolicy::SetPolicy() to apply a separate
1.79 +security policy to:
1.80 +- write activity on each named database table.
1.81 +- read activity on each named database table.
1.82 +
1.83 +A client uses a RSqlSecurityPolicy object to create a secure database. It does this by:
1.84 +- creating a RSqlSecurityPolicy object.
1.85 +- setting all the appropriate security policies into it.
1.86 +- passing the object as an argument to RSqlDatabase::Create().
1.87 +- closing the RSqlSecurityPolicy object on return from RSqlDatabase::Create().
1.88 +
1.89 +Once a secure shared database has been created with specific security policies,
1.90 +these policies are made persistent and cannot be changed during the life of
1.91 +that database.
1.92 +
1.93 +Security policies are encapsulated by TSecurityPolicy objects.
1.94 +The general usage pattern is to create the security policies container object
1.95 +(RSqlSecurityPolicy) using a default security policy (TSecurityPolicy), and then
1.96 +to assign more specific 'overriding' security policies.
1.97 +
1.98 +The following code fragment shows how you do this:
1.99 +
1.100 +@code
1.101 +TSecurityPolicy defaultPolicy;
1.102 +RSqlSecurityPolicy securityPolicy;
1.103 +RSqlDatabase database;
1.104 +TInt err;
1.105 +
1.106 +// Create security policies container object using a default security policy.
1.107 +securityPolicy.Create(defaultPolicy);
1.108 +
1.109 +// Set up policy to apply to database schema
1.110 +// and assign it
1.111 +TSecurityPolicy schemaPolicy;
1.112 +...
1.113 +err = securityPolicy.SetDbPolicy(RSqlSecurityPolicy::ESchemaPolicy, schemaPolicy);
1.114 +
1.115 +// Set up policy to apply to write activity on the database
1.116 +// and assign it
1.117 +TSecurityPolicy writePolicy;
1.118 +...
1.119 +err = securityPolicy.SetDbPolicy(RSqlSecurityPolicy::EWritePolicy, writePolicy);
1.120 +
1.121 +// Set up policy to apply to write activity to the database table named "Table1"
1.122 +// and assign it
1.123 +TSecurityPolicy tablePolicy1;
1.124 +...
1.125 +err = securityPolicy.SetPolicy(RSqlSecurityPolicy::ETable, _L("Table1"), RSqlSecurityPolicy::EWritePolicy, tablePolicy1);
1.126 +
1.127 +// Set up policy to apply to read activity to the database table named "Table2"
1.128 +TSecurityPolicy tablePolicy2;
1.129 +err = securityPolicy.SetPolicy(RSqlSecurityPolicy::ETable, _L("Table2"), RSqlSecurityPolicy::EReadPolicy, tablePolicy2);
1.130 +
1.131 +// Create the database, passing the security policies
1.132 +err = database.Create(KDatabaseName, securityPolicy);
1.133 +
1.134 +// We can close the RSqlSecurityPolicy object.
1.135 +securityPolicy.Close();
1.136 +@endcode
1.137 +
1.138 +Note that in this example code fragment, the client has not assigned specific
1.139 +overriding policies for all possible cases; for example, no overriding policy
1.140 +has been assigned to control read activity on the database, read activity
1.141 +on "Table1", nor write activity on "Table2".
1.142 +For these cases, the default security policy will apply.
1.143 +
1.144 +A client can also retrieve a database's security policies by calling
1.145 +RSqlDatabase::GetSecurityPolicy(); this returns a RSqlSecurityPolicy object
1.146 +containing the security policies. Note that it is the client's responsibility
1.147 +to close the RSqlSecurityPolicy object when the client no longer needs it. The
1.148 +following code fragment suggests how you might do this:
1.149 +
1.150 +@code
1.151 +RSqlDatabase database;
1.152 +RSqlSecurityPolicy securityPolicy;
1.153 +
1.154 +// Retrieve the security policies; on return from the call to
1.155 +// GetSecurityPolicy(), the RSqlSecurityPolicy object passed
1.156 +// to this function will contain the security policies.
1.157 +database.GetSecurityPolicy(securityPolicy);
1.158 +...
1.159 +// This is the security policy that applies to database schema
1.160 +TSecurityPolicy schemaPolicy = securityPolicy.DbPolicy(RSqlSecurityPolicy::ESchemaPolicy);
1.161 +...
1.162 +// This is the security policy that applies to write activity to the database
1.163 +// table named "Table1".
1.164 +TSecurityPolicy writePolicy = securityPolicy.Policy(RSqlSecurityPolicy::ETable, _L("Table1"), RSqlSecurityPolicy::EWritePolicy);
1.165 +...
1.166 +// Close the RSqlSecurityPolicy object when no longer needed.
1.167 +securityPolicy.Close();
1.168 +@endcode
1.169 +
1.170 +Note that in the cases where an 'overriding' security policy was not originally assigned,
1.171 +then the security policy returned will simply be the default security policy.
1.172 +
1.173 +Note: The database security policies are used to control the access to the objects (tables, indexes, triggers, views)
1.174 +in the main database. The access to the temporary tables, indexes, etc. is not a subject of any restrictions, e.g.
1.175 +a client with "read" database security policy only can create and use temporary tables, views, indexes, triggers.
1.176 +
1.177 +@see TSecurityPolicy
1.178 +@see RSqlDatabase
1.179 +@see RSqlSecurityPolicy::SetDbPolicy()
1.180 +@see RSqlSecurityPolicy::SetPolicy()
1.181 +
1.182 +@publishedAll
1.183 +@released
1.184 +*/
1.185 +class RSqlSecurityPolicy
1.186 + {
1.187 + friend class RSqlDatabase;
1.188 +
1.189 +public:
1.190 + /**
1.191 + Defines a set of values that represents the database security policy types.
1.192 + Each database security policy type refers to a set of capabilities encapsulated in
1.193 + a TSecurityPolicy object. The TSecurityPolicy object defines what capabilities the calling
1.194 + application must have in order to perform partiqular database operation.
1.195 + @see TSecurityPolicy
1.196 + */
1.197 + enum TPolicyType
1.198 + {
1.199 + /**
1.200 + Schema database security policy. An application with schema database security policy can
1.201 + modify the database schema, write to database, read from database.
1.202 + */
1.203 + ESchemaPolicy,
1.204 + /**
1.205 + Read database security policy. An application with read database security policy can
1.206 + read from database.
1.207 + */
1.208 + EReadPolicy,
1.209 + /**
1.210 + Write database security policy. An application with write database security policy can
1.211 + write to database.
1.212 + */
1.213 + EWritePolicy
1.214 + };
1.215 + /**
1.216 + Not currently supported.
1.217 +
1.218 + Defines a set of values that represents the database objects which can be protected by
1.219 + database security policy types.
1.220 + */
1.221 + enum TObjectType
1.222 + {
1.223 + ETable
1.224 + };
1.225 + IMPORT_C RSqlSecurityPolicy();
1.226 + IMPORT_C TInt Create(const TSecurityPolicy& aDefaultPolicy);
1.227 + IMPORT_C void CreateL(const TSecurityPolicy& aDefaultPolicy);
1.228 + IMPORT_C void Close();
1.229 + IMPORT_C TInt SetDbPolicy(TPolicyType aPolicyType, const TSecurityPolicy& aPolicy);
1.230 + IMPORT_C TInt SetPolicy(TObjectType aObjectType, const TDesC& aObjectName, TPolicyType aPolicyType, const TSecurityPolicy& aPolicy);
1.231 + IMPORT_C TSecurityPolicy DefaultPolicy() const;
1.232 + IMPORT_C TSecurityPolicy DbPolicy(TPolicyType aPolicyType) const;
1.233 + IMPORT_C TSecurityPolicy Policy(TObjectType aObjectType, const TDesC& aObjectName, TPolicyType aPolicyType) const;
1.234 +
1.235 + IMPORT_C void ExternalizeL(RWriteStream& aStream) const;
1.236 + IMPORT_C void InternalizeL(RReadStream& aStream);
1.237 +
1.238 +private:
1.239 + void Set(CSqlSecurityPolicy& aImpl);
1.240 + CSqlSecurityPolicy& Impl() const;
1.241 +
1.242 +private:
1.243 + CSqlSecurityPolicy* iImpl;
1.244 + };
1.245 +
1.246 +/**
1.247 +A handle to a SQL database.
1.248 +
1.249 +A RSqlDatabase object is, in effect, a handle to the SQL database. A client can:
1.250 +- create a SQL database by calling RSqlDatabase::Create().
1.251 +- open an existing SQL database by calling RSqlDatabase::Open().
1.252 +- close a SQL database by calling RSqlDatabase::Close().
1.253 +- copy a SQL database by calling RSqlDatabase::Copy().
1.254 +- delete a SQL database by calling RSqlDatabase::Delete().
1.255 +- attach a SQL database to current database connection by calling RSqlDatabase::Attach().
1.256 +- detach a SQL database from current database connection by calling RSqlDatabase::Detach().
1.257 +
1.258 +The RSqlDatabase handles are not thread-safe.
1.259 +
1.260 +A client can create either a non-secure database or a secure database,
1.261 +depending on the variant of RSqlDatabase::Create() that is used.
1.262 +- a non-secure database is created if the RSqlDatabase::Create(const TDesC&) variant is used.
1.263 +- a secure database is created if the RSqlDatabase::Create(const TDesC&, const RSqlSecurityPolicy&)
1.264 +variant is used. In this case, a container containing a collection of security
1.265 +policies needs to be set up first and passed to this Create() function.
1.266 +See references to RSqlSecurityPolicy for more information on security policies.
1.267 +
1.268 +A client can also specify how it wants a transaction to interact with
1.269 +other transactions that may be running concurrently. The various ways in which
1.270 +transactions can interact (i.e. how one transaction can affect another) are
1.271 +referred to as "transaction isolation levels", and are defined by the values
1.272 +of the TIsolationLevel enum. A client specifies this by calling RSqlDatabase::SetIsolationLevel().
1.273 +
1.274 +Each of the various flavours of Open and Create allows the optional provision of a
1.275 +configuration string. It is acceptable for this string to be missing.
1.276 +In the case where the string is missing, the config in the SqlServer.sql file
1.277 +will be used. If that does not exist then the MMH macro definitions will be used.
1.278 +
1.279 +The config string is in the format PARAM=VALUE; PARAM=VALUE;...
1.280 +
1.281 +Allowed parameters are:
1.282 + cache_size=nnnn
1.283 + page_size=nnnn
1.284 + encoding=UTF8|UTF16
1.285 +
1.286 +Badly formed config strings are reported as KErrArgument
1.287 +
1.288 +The string may not exceed 255 characters.
1.289 +
1.290 +Please note that a database can only be accessed within the thread where it has been created. It is then not possible
1.291 +to create a database from thread1 and access it from thread2.
1.292 +
1.293 +A client calls RSqlDatabase::Exec() to execute SQL statements.
1.294 +@see RSqlDatabase::Create()
1.295 +@see RSqlDatabase::Open()
1.296 +@see RSqlDatabase::Close()
1.297 +@see RSqlDatabase::Copy()
1.298 +@see RSqlDatabase::Delete()
1.299 +@see RSqlDatabase::Attach()
1.300 +@see RSqlDatabase::Detach()
1.301 +@see RSqlDatabase::SetIsolationLevel()
1.302 +@see RSqlDatabase::Exec()
1.303 +@see TIsolationLevel
1.304 +@see RSqlSecurityPolicy
1.305 +
1.306 +@publishedAll
1.307 +@released
1.308 +*/
1.309 +class RSqlDatabase
1.310 + {
1.311 + friend class RSqlStatement;
1.312 + friend class TSqlScalarFullSelectQuery;
1.313 + friend class RSqlBlob;
1.314 + friend class RSqlBlobReadStream;
1.315 + friend class RSqlBlobWriteStream;
1.316 + friend class TSqlResourceProfiler;
1.317 +
1.318 +public:
1.319 + /**
1.320 + Defines a set of values that represents the transaction isolation level.
1.321 +
1.322 + A transaction isolation level defines the way in which a transaction
1.323 + interacts with other transactions that may be in progress concurrently.
1.324 +
1.325 + A client sets the transaction isolation level by calling SetIsolationLevel()
1.326 +
1.327 + @see RSqlDatabase::SetIsolationLevel()
1.328 + */
1.329 + enum TIsolationLevel
1.330 + {
1.331 + /**
1.332 + A transaction can read uncommitted data, i.e. data that is being changed
1.333 + by another transaction, which is still in progress.
1.334 +
1.335 + This means that
1.336 + - a 'database read' transaction will not block 'database write' transactions
1.337 + being performed by different database connections on the same shared database.
1.338 + - a 'database read' transaction will not be blocked by 'database write'
1.339 + transactions performed by the same database connection.
1.340 + - concurrent 'database write' transactions are prevented.
1.341 +
1.342 + This transaction isolation level can be set at any time during
1.343 + the lifetime of the database.
1.344 +
1.345 + @see TIsolationLevel
1.346 + @see RSqlDatabase::SetIsolationLevel()
1.347 + */
1.348 + EReadUncommitted,
1.349 +
1.350 + /**
1.351 + Not currently supported.
1.352 +
1.353 + A transaction cannot read uncommitted data. "Dirty reads" are prevented.
1.354 +
1.355 + "Dirty read" is a data inconsistency type which can be described with the following example:
1.356 + - Transaction A updates TableA.Column1 value from 1 to 2;
1.357 + - Transaction B reads TableA.Column1 value;
1.358 + - Transaction A rolls back and restores the original value of TableA.Column1 (1);
1.359 + - Transaction B ends showing that TableA.Column1 value is 2, even though, logically and transactionally,
1.360 + this data never really even existed in the database because Transaction A never committed that change
1.361 + to the database;
1.362 +
1.363 + @see TIsolationLevel
1.364 + @see RSqlDatabase::SetIsolationLevel()
1.365 + */
1.366 + EReadCommitted,
1.367 +
1.368 + /**
1.369 + Not currently supported.
1.370 +
1.371 + A transaction cannot change data that is being read by a different transaction.
1.372 + "Dirty reads" and "non-repeatable reads" are prevented.
1.373 +
1.374 + "Non-repeatable reads" is a data inconsistency type which can be described with the following example:
1.375 + - Transaction A reads TableA.Column1 value which is 1;
1.376 + - Transaction B updates TableA.Column1 value from 1 to 2;
1.377 + - Transaction B commits the chages;
1.378 + - Transaction A reads TableA.Column1 value again. Transaction A has inconsistent data because TableA.Column1
1.379 + value now is 2 instead of 1, all within the scope of the same Transaction A;
1.380 +
1.381 + @see TIsolationLevel
1.382 + @see RSqlDatabase::SetIsolationLevel()
1.383 + */
1.384 + ERepeatableRead,
1.385 +
1.386 + /**
1.387 + Any number of 'database read' transactions can be performed concurrently
1.388 + by different database connections on the same shared database.
1.389 +
1.390 + Only one 'database write' transaction can be performed at any one time. If a
1.391 + 'database write' transaction is in progress, then any attempt to start
1.392 + another 'database read' or 'database write' transaction will be blocked
1.393 + until the first 'database write' transaction has completed.
1.394 +
1.395 + This is the default isolation level, if no isolation level is
1.396 + explicitly set.
1.397 +
1.398 + "Dirty reads", "non-repeatable" reads and "phantom reads" are prevented.
1.399 +
1.400 + "Phantom reads" is a data inconsistency type which can be described with the following example:
1.401 + - Transaction A reads all rows that have Column1 = 1;
1.402 + - Transaction B inserts a new row which has Column1 = 1;
1.403 + - Transaction B commits;
1.404 + - Transaction A updates all rows that have Column1 = 1. This will also update the row that
1.405 + Transaction B inserted, because Transaction A must read the data again in order to update it.
1.406 + - Transaction A commits;
1.407 +
1.408 + @see TIsolationLevel
1.409 + @see RSqlDatabase::SetIsolationLevel()
1.410 + */
1.411 + ESerializable
1.412 + };
1.413 + /**
1.414 + This structure is used for retrieving the database size and database free space.
1.415 + @see RSqlDatabase::Size(TSize&)
1.416 + */
1.417 + struct TSize
1.418 + {
1.419 + /** The database size in bytes*/
1.420 + TInt64 iSize;
1.421 + /** The database free space in bytes*/
1.422 + TInt64 iFree;
1.423 + };
1.424 +
1.425 + /** If this value is used as an argument of RSqlDatabase::Compact() (aSize argument), then all free space will be removed */
1.426 + enum {EMaxCompaction = -1};
1.427 +
1.428 + IMPORT_C RSqlDatabase();
1.429 +
1.430 + IMPORT_C TInt Create(const TDesC& aDbFileName, const TDesC8* aConfig=NULL);
1.431 + IMPORT_C TInt Create(const TDesC& aDbFileName,
1.432 + const RSqlSecurityPolicy& aSecurityPolicy, const TDesC8* aConfig=NULL);
1.433 + IMPORT_C TInt Open(const TDesC& aDbFileName, const TDesC8* aConfig=NULL);
1.434 + IMPORT_C void CreateL(const TDesC& aDbFileName, const TDesC8* aConfig=NULL);
1.435 + IMPORT_C void CreateL(const TDesC& aDbFileName,
1.436 + const RSqlSecurityPolicy& aSecurityPolicy, const TDesC8* aConfig=NULL);
1.437 + IMPORT_C void OpenL(const TDesC& aDbFileName, const TDesC8* aConfig=NULL);
1.438 +
1.439 + IMPORT_C void Close();
1.440 +
1.441 + IMPORT_C TInt Attach(const TDesC& aDbFileName, const TDesC& aDbName);
1.442 + IMPORT_C TInt Detach(const TDesC& aDbName);
1.443 +
1.444 + IMPORT_C static TInt Copy(const TDesC& aSrcDbFileName, const TDesC& aDestDbFileName);
1.445 + IMPORT_C static TInt Delete(const TDesC& aDbFileName);
1.446 +
1.447 + IMPORT_C TInt GetSecurityPolicy(RSqlSecurityPolicy& aSecurityPolicy) const;
1.448 + IMPORT_C void GetSecurityPolicyL(RSqlSecurityPolicy& aSecurityPolicy) const;
1.449 +
1.450 + IMPORT_C TInt SetIsolationLevel(TIsolationLevel aIsolationLevel);
1.451 +
1.452 + IMPORT_C TInt Exec(const TDesC& aSqlStmt);
1.453 + IMPORT_C TInt Exec(const TDesC8& aSqlStmt);
1.454 +
1.455 + IMPORT_C void Exec(const TDesC& aSqlStmt, TRequestStatus& aStatus);
1.456 + IMPORT_C void Exec(const TDesC8& aSqlStmt, TRequestStatus& aStatus);
1.457 +
1.458 + IMPORT_C TPtrC LastErrorMessage() const;
1.459 + IMPORT_C TInt64 LastInsertedRowId() const;
1.460 +
1.461 + IMPORT_C TBool InTransaction() const;
1.462 + IMPORT_C TInt Size() const;
1.463 + IMPORT_C TInt Size(TSize& aSize, const TDesC& aDbName = KNullDesC) const;
1.464 +
1.465 + IMPORT_C TInt Compact(TInt64 aSize, const TDesC& aDbName = KNullDesC);
1.466 + IMPORT_C void Compact(TInt64 aSize, TRequestStatus& aStatus, const TDesC& aDbName = KNullDesC);
1.467 +
1.468 + IMPORT_C TInt ReserveDriveSpace(TInt aSize);
1.469 + IMPORT_C void FreeReservedSpace();
1.470 + IMPORT_C TInt GetReserveAccess();
1.471 + IMPORT_C void ReleaseReserveAccess();
1.472 +
1.473 +private:
1.474 + CSqlDatabaseImpl& Impl() const;
1.475 +
1.476 +private:
1.477 + CSqlDatabaseImpl* iImpl;
1.478 + };
1.479 +
1.480 +/**
1.481 +TSqlScalarFullSelectQuery interface is used for executing SELECT sql queries, which
1.482 +return a single row consisting of a single column value.
1.483 +
1.484 +Examples.
1.485 +
1.486 +CASE 1 - retrieving records count of a table:
1.487 +@code
1.488 +RSqlDatabase db;
1.489 +//initialize db object....
1.490 +.......
1.491 +TSqlScalarFullSelectQuery fullSelectQuery(db);
1.492 +TInt recCnt = fullSelectQuery.SelectIntL(_L("SELECT COUNT(*) FROM PersonTbl"));
1.493 +@endcode
1.494 +
1.495 +CASE 2 - retrieving specific column value using a condition in the SELECT statement:
1.496 +@code
1.497 +RSqlDatabase db;
1.498 +//initialize db object....
1.499 +.......
1.500 +TSqlScalarFullSelectQuery fullSelectQuery(db);
1.501 +TInt personId = fullSelectQuery.SelectIntL(_L("SELECT ID FROM PersonTbl WHERE Name = 'John'"));
1.502 +@endcode
1.503 +
1.504 +CASE 3 - retrieving a text column value, the receiving buffer is not big enough:
1.505 +@code
1.506 +RSqlDatabase db;
1.507 +//initialize db object....
1.508 +.......
1.509 +TSqlScalarFullSelectQuery fullSelectQuery(db);
1.510 +HBufC* buf = HBufC::NewLC(20);
1.511 +TPtr name = buf->Des();
1.512 +TInt rc = fullSelectQuery.SelectTextL(_L("SELECT Name FROM PersonTbl WHERE Id = 1"), name);
1.513 +TEST(rc >= 0); //the function may return only non-negative values
1.514 +if(rc > 0)
1.515 + {
1.516 + buf = buf->ReAllocL(rc);
1.517 + CleanupStack::Pop();
1.518 + CleanupStack::PushL(buf);
1.519 + name.Set(buf->Des());
1.520 + rc = fullSelectQuery.SelectTextL(_L("SELECT Name FROM PersonTbl WHERE Id = 1"), name);
1.521 + TEST(rc == 0);
1.522 + }
1.523 +CleanupStack::PopAndDestroy();//buf
1.524 +@endcode
1.525 +
1.526 +@see RSqlDatabase
1.527 +
1.528 +@publishedAll
1.529 +@released
1.530 +*/
1.531 +class TSqlScalarFullSelectQuery
1.532 + {
1.533 +public:
1.534 + IMPORT_C TSqlScalarFullSelectQuery();
1.535 + IMPORT_C TSqlScalarFullSelectQuery(RSqlDatabase& aDatabase);
1.536 + IMPORT_C void SetDatabase(RSqlDatabase& aDatabase);
1.537 +
1.538 + IMPORT_C TInt SelectIntL(const TDesC& aSqlStmt);
1.539 + IMPORT_C TInt64 SelectInt64L(const TDesC& aSqlStmt);
1.540 + IMPORT_C TReal SelectRealL(const TDesC& aSqlStmt);
1.541 + IMPORT_C TInt SelectTextL(const TDesC& aSqlStmt, TDes& aDest);
1.542 + IMPORT_C TInt SelectBinaryL(const TDesC& aSqlStmt, TDes8& aDest);
1.543 +
1.544 + IMPORT_C TInt SelectIntL(const TDesC8& aSqlStmt);
1.545 + IMPORT_C TInt64 SelectInt64L(const TDesC8& aSqlStmt);
1.546 + IMPORT_C TReal SelectRealL(const TDesC8& aSqlStmt);
1.547 + IMPORT_C TInt SelectTextL(const TDesC8& aSqlStmt, TDes& aDest);
1.548 + IMPORT_C TInt SelectBinaryL(const TDesC8& aSqlStmt, TDes8& aDest);
1.549 +
1.550 +private:
1.551 + inline CSqlDatabaseImpl& Impl() const;
1.552 +
1.553 +private:
1.554 + CSqlDatabaseImpl* iDatabaseImpl;
1.555 + };
1.556 +
1.557 +/**
1.558 +An enumeration whose values represent the supported database column types.
1.559 +
1.560 +
1.561 +@see RSqlStatement::ColumnType()
1.562 +
1.563 +@publishedAll
1.564 +@released
1.565 +*/
1.566 +enum TSqlColumnType
1.567 + {
1.568 + /**
1.569 + Null column value.
1.570 + */
1.571 + ESqlNull,
1.572 +
1.573 + /**
1.574 + 32-bit integer column value.
1.575 + */
1.576 + ESqlInt,
1.577 +
1.578 + /**
1.579 + 64-bit integer column value.
1.580 + */
1.581 + ESqlInt64,
1.582 +
1.583 + /**
1.584 + 64-bit floating point column value.
1.585 + */
1.586 + ESqlReal,
1.587 +
1.588 + /**
1.589 + Unicode text, a sequence of 16-bit character codes.
1.590 + */
1.591 + ESqlText,
1.592 +
1.593 + /**
1.594 + Binary data, a sequence of bytes.
1.595 + */
1.596 + ESqlBinary
1.597 + };
1.598 +
1.599 +/**
1.600 +Represents an SQL statement.
1.601 +
1.602 +An object of this type can be used to execute all types of SQL statements; this
1.603 +includes SQL statements with parameters.
1.604 +
1.605 +If a SELECT statament is passed to RSqlStatement::Prepare(), then the returned record set
1.606 +is forward only, non-updateable.
1.607 +
1.608 +There are a number of ways that this object is used; here are some examples.
1.609 +
1.610 +CASE 1 - the execution of a SQL statement, which does not return record set:
1.611 +
1.612 +@code
1.613 +RSqlDatabase database;
1.614 +.........
1.615 +RSqlStatement stmt;
1.616 +TInt err = stmt.Prepare(database, _L("INSERT INTO Tbl1(Fld1) VALUES(:Val)"));
1.617 +TInt paramIndex = stmt.ParameterIndex(_L(":Val"));
1.618 +for(TInt i=1;i<=10;++i)
1.619 + {
1.620 + err = stmt.BindInt(paramIndex, i);
1.621 + err = stmt.Exec();
1.622 + err = stmt.Reset();
1.623 + }
1.624 +stmt.Close();
1.625 +@endcode
1.626 +
1.627 +The following pseudo code shows the general pattern:
1.628 +
1.629 +@code
1.630 +<RSqlStatement::Prepare()>
1.631 +[begin:]
1.632 +<RSqlStatement::Bind<param_type>()>
1.633 +<RSqlStatement::Exec()>
1.634 +[<RSqlStatement::Reset()>]
1.635 +[<RSqlStatement::Bind<param_type>()>]
1.636 +[<Goto :begin>]
1.637 +@endcode
1.638 +
1.639 +CASE 2 - the execution of a SQL statement, which returns a record set:
1.640 +
1.641 +@code
1.642 +RSqlDatabase database;
1.643 +.........
1.644 +RSqlStatement stmt;
1.645 +TInt err = stmt.Prepare(database, _L("SELECT Fld1 FROM Tbl1 WHERE Fld1 > :Val"));
1.646 +TInt paramIndex = stmt.ParameterIndex(_L(":Val"));
1.647 +err = stmt.BindInt(paramIndex, 5);
1.648 +TInt columnIndex = stmt.ColumnIndex(_L("Fld1"));
1.649 +while((err = stmt.Next()) == KSqlAtRow)
1.650 + {
1.651 + TInt val = stmt.ColumnInt(columnIndex);
1.652 + RDebug::Print(_L("val=%d\n"), val);
1.653 + }
1.654 +if(err == KSqlAtEnd)
1.655 + <OK - no more records>;
1.656 +else
1.657 + <process the error>;
1.658 +stmt.Close();
1.659 +@endcode
1.660 +
1.661 +The following pseudo code shows the general pattern:
1.662 +
1.663 +@code
1.664 +<RSqlStatement::Prepare()>
1.665 +[begin:]
1.666 +<while (RSqlStatement::Next() == KSqlAtRow)>
1.667 + <do something with the records>
1.668 +if(err == KSqlAtEnd)
1.669 + <OK - no more records>;
1.670 +else
1.671 + <process the error>;
1.672 +[<RSqlStatement::Reset()>]
1.673 +[<RSqlStatement::Bind<param_type>()>]
1.674 +[<Goto begin>]
1.675 +@endcode
1.676 +
1.677 +CASE 3.1 - SELECT statements: large column data processing, where the data is
1.678 +copied into a buffer supplied by the client:
1.679 +
1.680 +@code
1.681 +RSqlDatabase database;
1.682 +.........
1.683 +RSqlStatement stmt;
1.684 +TInt err = stmt.Prepare(database, _L("SELECT BinaryField FROM Tbl1"));
1.685 +TInt columnIndex = stmt.ColumnIndex(_L("BinaryField"));
1.686 +while((err = stmt.Next()) == KSqlAtRow)
1.687 + {
1.688 + TInt size = stmt. ColumnSize(columnIndex);
1.689 + HBufC8* buf = HBufC8::NewL(size);
1.690 + err = stmt.ColumnBinary(columnIndex, buf->Ptr());
1.691 + <do something with the data>;
1.692 + delete buf;
1.693 + }
1.694 +if(err == KSqlAtEnd)
1.695 + <OK - no more records>;
1.696 +else
1.697 + <process the error>;
1.698 +stmt.Close();
1.699 +@endcode
1.700 +
1.701 +CASE 3.2 - SELECT statements: large column data processing, where the data is
1.702 +accessed by the client without copying:
1.703 +
1.704 +@code
1.705 +RSqlDatabase database;
1.706 +.........
1.707 +RSqlStatement stmt;
1.708 +TInt err = stmt.Prepare(database, _L("SELECT BinaryField FROM Tbl1"));
1.709 +TInt columnIndex = stmt.ColumnIndex(_L("BinaryField"));
1.710 +while((err = stmt.Next()) == KSqlAtRow)
1.711 + {
1.712 + TPtrC8 data = stmt.ColumnBinaryL(columnIndex);
1.713 + <do something with the data>;
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 3.3 - SELECT statements, large column data processing (the data is accessed by
1.723 +the client without copying), leaving-safe processing:
1.724 +
1.725 +@code
1.726 +RSqlDatabase database;
1.727 +.........
1.728 +RSqlStatement stmt;
1.729 +TInt err = stmt.Prepare(database, _L("SELECT BinaryField FROM Tbl1"));
1.730 +TInt columnIndex = stmt.ColumnIndex(_L("BinaryField"));
1.731 +while((err = stmt.Next()) == KSqlAtRow)
1.732 + {
1.733 + TPtrC8 data;
1.734 + TInt err = stmt.ColumnBinary(columnIndex, data);
1.735 + if(err == KErrNone)
1.736 + {
1.737 + <do something with the data>;
1.738 + }
1.739 + }
1.740 +if(err == KSqlAtEnd)
1.741 + <OK - no more records>;
1.742 +else
1.743 + <process the error>;
1.744 +stmt.Close();
1.745 +@endcode
1.746 +
1.747 +CASE 3.4 - SELECT statements: large column data processing, where the data is
1.748 +accessed by the client using a stream:
1.749 +
1.750 +@code
1.751 +RSqlDatabase database;
1.752 +.........
1.753 +RSqlStatement stmt;
1.754 +TInt err = stmt.Prepare(database, _L("SELECT BinaryField FROM Tbl1"));
1.755 +TInt columnIndex = stmt.ColumnIndex(_L("BinaryField"));
1.756 +while((err = stmt.Next()) == KSqlAtRow)
1.757 + {
1.758 + RSqlColumnReadStream stream;
1.759 + err = stream.ColumnBinary(stmt, columnIndex);
1.760 + <do something with the data in the stream>;
1.761 + stream.Close();
1.762 + }
1.763 +if(err == KSqlAtEnd)
1.764 + <OK - no more records>;
1.765 +else
1.766 + <process the error>;
1.767 +stmt.Close();
1.768 +@endcode
1.769 +
1.770 +CASE 4 - the execution of a SQL statement with parameter(s), some of which may
1.771 +be large text or binary values:
1.772 +
1.773 +@code
1.774 +RSqlDatabase database;
1.775 +.........
1.776 +RSqlStatement stmt;
1.777 +TInt err =
1.778 + stmt.Prepare(database, _L("UPDATE Tbl1 SET LargeTextField = :LargeTextVal WHERE IdxField = :KeyVal"));
1.779 +TInt paramIndex1 = stmt.ParameterIndex(_L(":LargeTextVal"));
1.780 +TInt paramIndex2 = stmt.ParameterIndex(_L(":KeyVal"));
1.781 +for(TInt i=1;i<=10;++i)
1.782 + {
1.783 + RSqlParamWriteStream stream;
1.784 + err = stream.BindText(stmt, paramIndex1);
1.785 + <insert large text data into the stream>;
1.786 + stream.Close();
1.787 + err = stmt.BindInt(paramIndex2, i);
1.788 + err = stmt.Exec();
1.789 + stmt.Reset();
1.790 + }
1.791 +stmt.Close();
1.792 +@endcode
1.793 +
1.794 +The following table shows what is returned when the caller uses a specific
1.795 +column data retrieving function on a specific column type.
1.796 +
1.797 +@code
1.798 +--------------------------------------------------------------------------------
1.799 +Column type | ColumnInt() ColumnInt64() ColumnReal() ColumnText() ColumnBinary()
1.800 +--------------------------------------------------------------------------------
1.801 +Null........|.0...........0.............0.0..........KNullDesC....KNullDesC8
1.802 +Int.........|.Int.........Int64.........Real.........KNullDesC....KNullDesC8
1.803 +Int64.......|.clamp.......Int64.........Real.........KNullDesC....KNullDesC8
1.804 +Real........|.round.......round.........Real.........KNullDesC....KNullDesC8
1.805 +Text........|.0...........0.............0.0..........Text.........KNullDesC8
1.806 +Binary......|.0...........0.............0.0..........KNullDesC....Binary
1.807 +--------------------------------------------------------------------------------
1.808 +@endcode
1.809 +Note the following definitions:
1.810 +- "clamp": return KMinTInt or KMaxTInt if the value is outside the range that can be
1.811 +represented by the type returned by the accessor function.
1.812 +- "round": the floating point value will be rounded up to the nearest integer.
1.813 +If the result is outside the range that can be represented by the type returned
1.814 +by the accessor function, then it will be clamped.
1.815 +
1.816 +Note that when handling blob and text data over 2Mb in size it is recommended that the
1.817 +RSqlBlobReadStream and RSqlBlobWriteStream classes or the TSqlBlob class is used instead.
1.818 +These classes provide a more RAM-efficient way of reading and writing large amounts of
1.819 +blob or text data from a database.
1.820 +
1.821 +@see KMinTInt
1.822 +@see KMaxTInt
1.823 +@see KNullDesC
1.824 +@see KNullDesC8
1.825 +@see RSqlBlobReadStream
1.826 +@see RSqlBlobWriteStream
1.827 +@see TSqlBlob
1.828 +
1.829 +@publishedAll
1.830 +@released
1.831 +*/
1.832 +class RSqlStatement
1.833 + {
1.834 + friend class RSqlColumnReadStream;
1.835 + friend class RSqlParamWriteStream;
1.836 +
1.837 +public:
1.838 + IMPORT_C RSqlStatement();
1.839 + IMPORT_C TInt Prepare(RSqlDatabase& aDatabase, const TDesC& aSqlStmt);
1.840 + IMPORT_C TInt Prepare(RSqlDatabase& aDatabase, const TDesC8& aSqlStmt);
1.841 + IMPORT_C void PrepareL(RSqlDatabase& aDatabase, const TDesC& aSqlStmt);
1.842 + IMPORT_C void PrepareL(RSqlDatabase& aDatabase, const TDesC8& aSqlStmt);
1.843 + IMPORT_C void Close();
1.844 + IMPORT_C TBool AtRow() const;
1.845 + IMPORT_C TInt Reset();
1.846 + IMPORT_C TInt Exec();
1.847 + IMPORT_C void Exec(TRequestStatus& aStatus);
1.848 + IMPORT_C TInt Next();
1.849 +
1.850 + IMPORT_C TInt ParameterIndex(const TDesC& aParameterName) const;
1.851 + IMPORT_C TInt ColumnCount() const;
1.852 + IMPORT_C TInt ColumnIndex(const TDesC& aColumnName) const;
1.853 + IMPORT_C TSqlColumnType ColumnType(TInt aColumnIndex) const;
1.854 + IMPORT_C TInt DeclaredColumnType(TInt aColumnIndex, TSqlColumnType& aColumnType) const;
1.855 + IMPORT_C TInt ColumnSize(TInt aColumnIndex) const;
1.856 +
1.857 + IMPORT_C TInt BindNull(TInt aParameterIndex);
1.858 + IMPORT_C TInt BindInt(TInt aParameterIndex, TInt aParameterValue);
1.859 + IMPORT_C TInt BindInt64(TInt aParameterIndex, TInt64 aParameterValue);
1.860 + IMPORT_C TInt BindReal(TInt aParameterIndex, TReal aParameterValue);
1.861 + IMPORT_C TInt BindText(TInt aParameterIndex, const TDesC& aParameterText);
1.862 + IMPORT_C TInt BindBinary(TInt aParameterIndex, const TDesC8& aParameterData);
1.863 + IMPORT_C TInt BindZeroBlob(TInt aParameterIndex, TInt aBlobSize);
1.864 +
1.865 + IMPORT_C TBool IsNull(TInt aColumnIndex) const;
1.866 + IMPORT_C TInt ColumnInt(TInt aColumnIndex) const;
1.867 + IMPORT_C TInt64 ColumnInt64(TInt aColumnIndex) const;
1.868 + IMPORT_C TReal ColumnReal(TInt aColumnIndex) const;
1.869 +
1.870 + IMPORT_C TPtrC ColumnTextL(TInt aColumnIndex) const;
1.871 + IMPORT_C TInt ColumnText(TInt aColumnIndex, TPtrC& aPtr) const;
1.872 + IMPORT_C TInt ColumnText(TInt aColumnIndex, TDes& aDest) const;
1.873 +
1.874 + IMPORT_C TPtrC8 ColumnBinaryL(TInt aColumnIndex) const;
1.875 + IMPORT_C TInt ColumnBinary(TInt aColumnIndex, TPtrC8& aPtr) const;
1.876 + IMPORT_C TInt ColumnBinary(TInt aColumnIndex, TDes8& aDest) const;
1.877 +
1.878 + IMPORT_C TInt ColumnName(TInt aColumnIndex, TPtrC& aNameDest);
1.879 + IMPORT_C TInt ParameterName(TInt aParameterIndex, TPtrC& aNameDest);
1.880 + IMPORT_C TInt ParamName(TInt aParameterIndex, TPtrC& aNameDest);
1.881 +private:
1.882 + CSqlStatementImpl& Impl() const;
1.883 +
1.884 +private:
1.885 + CSqlStatementImpl* iImpl;
1.886 +
1.887 + };
1.888 +
1.889 +/**
1.890 +The read stream interface.
1.891 +
1.892 +The class is used for reading the content of a column containing either
1.893 +binary data or text data.
1.894 +
1.895 +The class derives from RReadStream, which means that all RReadStream public
1.896 +member functions and predefined stream operators \>\> can be used to deal
1.897 +with column data.
1.898 +
1.899 +If the blob or text data is over 2Mb in size then it is recommended that the
1.900 +RSqlBlobReadStream or TSqlBlob class is used instead. These classes provide
1.901 +a more RAM-efficient way of reading large amounts of blob or text data from
1.902 +a database.
1.903 +
1.904 +The following two cases are typical:
1.905 +
1.906 +CASE 1 - processing large binary column data.
1.907 +
1.908 +@code
1.909 +RSqlDatabase db;
1.910 +<open/create "db" object>;
1.911 +RSqlStatement stmt;
1.912 +<prepare "stmt" object>;
1.913 +TInt rc = stmt.Next();
1.914 +if(rc == KSqlAtRow)
1.915 + {
1.916 + RSqlColumnReadStream colStream;
1.917 + CleanupClosePushL(colStream);
1.918 + User::LeaveIfError(colStream.ColumnBinary(stmt, <column_number>));
1.919 + TInt size = stmt.ColumnSize(<column_number>);
1.920 + //read the column data in a buffer ("buf" variable).
1.921 + //(or the column data can be retrieved in a smaller portions)
1.922 + colStream.ReadL(buf, size);
1.923 + //Close the stream
1.924 + CleanupStack::PopAndDestroy(&colStream);
1.925 + }
1.926 +else
1.927 + {
1.928 + ...
1.929 + }
1.930 +@endcode
1.931 +
1.932 +CASE 2 - processing large text column data.
1.933 +
1.934 +@code
1.935 +RSqlDatabase db;
1.936 +<open/create "db" object>;
1.937 +RSqlStatement stmt;
1.938 +<prepare "stmt" object>;
1.939 +TInt rc = stmt.Next();
1.940 +if(rc == KSqlAtRow)
1.941 + {
1.942 + RSqlColumnReadStream colStream;
1.943 + CleanupClosePushL(colStream);
1.944 + User::LeaveIfError(colStream.ColumnText(stmt, <column_number>));
1.945 + TInt size = stmt.ColumnSize(<column_number>);
1.946 + //read the column data in a buffer ("buf" variable).
1.947 + //(or the column data can be retrieved in a smaller portions)
1.948 + colStream.ReadL(buf, size);
1.949 + //Close the stream
1.950 + CleanupStack::PopAndDestroy(&colStream);
1.951 + }
1.952 +else
1.953 + {
1.954 + ...
1.955 + }
1.956 +@endcode
1.957 +
1.958 +@see RSqlBlobReadStream
1.959 +@see TSqlBlob
1.960 +
1.961 +@publishedAll
1.962 +@released
1.963 +*/
1.964 +class RSqlColumnReadStream : public RReadStream
1.965 + {
1.966 +public:
1.967 + IMPORT_C TInt ColumnText(RSqlStatement& aStmt, TInt aColumnIndex);
1.968 + IMPORT_C TInt ColumnBinary(RSqlStatement& aStmt, TInt aColumnIndex);
1.969 + IMPORT_C void ColumnTextL(RSqlStatement& aStmt, TInt aColumnIndex);
1.970 + IMPORT_C void ColumnBinaryL(RSqlStatement& aStmt, TInt aColumnIndex);
1.971 +
1.972 + };
1.973 +
1.974 +/**
1.975 +The write stream interface.
1.976 +
1.977 +The class is used to set binary data or text data into a parameter.
1.978 +This is a also known as binding a parameter.
1.979 +
1.980 +The class derives from RWriteStream, which means that all RWriteStream public
1.981 +member functions and predefined stream operators \<\< can be used to deal with
1.982 +the parameter data.
1.983 +
1.984 +If the blob or text data is over 2Mb in size then it is recommended that the
1.985 +RSqlBlobWriteStream or TSqlBlob class is used instead. These classes provide
1.986 +a more RAM-efficient way of writing large amounts of blob or text data to
1.987 +a database.
1.988 +
1.989 +The following two cases are typical:
1.990 +
1.991 +CASE 1 - binding a large binary parameter.
1.992 +
1.993 +@code
1.994 +RSqlDatabase db;
1.995 +<open/create "db" object>;
1.996 +RSqlStatement stmt;
1.997 +<prepare "stmt" object>;//The SQL statement references large binary parameter
1.998 +RSqlParamWriteStream paramStream;
1.999 +CleanupClosePushL(paramStream);
1.1000 +User::LeaveIfError(paramStream.BindBinary(stmt, <parameter_number>));
1.1001 +//Write out the parameter data
1.1002 +paramStream.WriteL(..);
1.1003 +paramStream << <data>;
1.1004 +...
1.1005 +//Commit the stream
1.1006 +paramStream.CommitL();
1.1007 +//Continue with the statement processing issuing Next() or Exec().
1.1008 +TInt rc = stmt.Next();//rc = stmt.Exec()
1.1009 +//Close the stream
1.1010 +CleanupStack::PopAndDestroy(¶mStream);
1.1011 +@endcode
1.1012 +
1.1013 +CASE 2 - binding a large text parameter.
1.1014 +
1.1015 +@code
1.1016 +RSqlDatabase db;
1.1017 +<open/create "db" object>;
1.1018 +RSqlStatement stmt;
1.1019 +<prepare "stmt" object>;//The SQL statement references large text parameter
1.1020 +RSqlParamWriteStream paramStream;
1.1021 +CleanupClosePushL(paramStream);
1.1022 +User::LeaveIfError(paramStream.BindText(stmt, <parameter_number>));
1.1023 +//Write out the parameter data
1.1024 +paramStream.WriteL(..);
1.1025 +paramStream << <data>;
1.1026 +...
1.1027 +//Commit the stream
1.1028 +paramStream.CommitL();
1.1029 +//Continue with the statement processing issuing Next() or Exec().
1.1030 +TInt rc = stmt.Next();//rc = stmt.Exec()
1.1031 +//Close the stream
1.1032 +CleanupStack::PopAndDestroy(¶mStream);
1.1033 +@endcode
1.1034 +
1.1035 +@see RSqlBlobWriteStream
1.1036 +@see TSqlBlob
1.1037 +
1.1038 +@publishedAll
1.1039 +@released
1.1040 +*/
1.1041 +class RSqlParamWriteStream : public RWriteStream
1.1042 + {
1.1043 +public:
1.1044 + IMPORT_C TInt BindText(RSqlStatement& aStmt, TInt aParameterIndex);
1.1045 + IMPORT_C TInt BindBinary(RSqlStatement& aStmt, TInt aParameterIndex);
1.1046 + IMPORT_C void BindTextL(RSqlStatement& aStmt, TInt aParameterIndex);
1.1047 + IMPORT_C void BindBinaryL(RSqlStatement& aStmt, TInt aParameterIndex);
1.1048 +
1.1049 + };
1.1050 +
1.1051 +/**
1.1052 +A direct handle to a blob, used for reading the content of the blob via a streaming interface.
1.1053 +
1.1054 +The target blob is identified using the relevant database connection, table name,
1.1055 +column name and ROWID of the record to which the blob belongs (also the attached
1.1056 +database name if the blob is contained in an attached database).
1.1057 +
1.1058 +A blob in this context refers to the content of a BLOB or TEXT column,
1.1059 +and a read handle can be opened on both types of column.
1.1060 +For TEXT columns it is important to note that no conversions are performed on
1.1061 +data retrieved using this class - the data is returned as a stream of bytes.
1.1062 +
1.1063 +The class derives from RReadStream and provides all of its streaming methods.
1.1064 +The SizeL() method can be used to check the total size of the blob, in bytes.
1.1065 +
1.1066 +It is strongly recommended to use this class for reading the content of large blobs
1.1067 +because it significantly reduces the amount of RAM that is used when compared to using the
1.1068 +RSqlColumnReadStream, RSqlStatement::ColumnBinary(L) or RSqlStatement::ColumnText(L) APIs.
1.1069 +
1.1070 +Specifically, it is recommended to use this class for blobs over 2Mb in size.
1.1071 +Indeed, in some circumstances where very large blobs are in use it may be impossible
1.1072 +to read the blob content using the legacy APIs (due to the server's finite RAM capacity),
1.1073 +and this class may provide the only way to access the data.
1.1074 +
1.1075 +The following code illustrates typical use cases of this class:
1.1076 +
1.1077 +CASE 1 - reading large blob data from the last inserted record.
1.1078 +
1.1079 +@code
1.1080 +RSqlDatabase db;
1.1081 +CleanupClosePushL(db);
1.1082 +<open/create "db" object>;
1.1083 +RSqlBlobReadStream rdStrm;
1.1084 +CleanupClosePushL(rdStrm);
1.1085 +rdStrm.OpenL(db, <table_name>, <column_name>);
1.1086 +HBufC8* buffer = HBufC8::NewLC(KBlockSize);
1.1087 +TPtr8 bufPtr(buffer->Des());
1.1088 +TInt size = rdStrm.SizeL();
1.1089 +while(size)
1.1090 + {
1.1091 + TInt bytesToRead = (size >= KBlockSize) ? KBlockSize : size ;
1.1092 + rdStrm.ReadL(bufPtr, bytesToRead); // read the next block of data
1.1093 + <do something with the block of data>
1.1094 + size =- bytesToRead;
1.1095 + }
1.1096 +CleanupStack::PopAndDestroy(3); // buffer, rdStrm, db
1.1097 +@endcode
1.1098 +
1.1099 +CASE 2 - reading large blob data from a selection of records.
1.1100 +
1.1101 +@code
1.1102 +RSqlDatabase db;
1.1103 +CleanupClosePushL(db);
1.1104 +<open/create "db" object>;
1.1105 +RSqlStatement stmt;
1.1106 +CleanupClosePushL(stmt);
1.1107 +<prepare "stmt" object to SELECT the ROWIDs of a collection of blob objects>;
1.1108 +TInt rc = 0;
1.1109 +while((rc = stmt.Next()) == KSqlAtRow)
1.1110 + {
1.1111 + TInt64 rowid = stmt.ColumnInt64(0);
1.1112 + RSqlBlobReadStream rdStrm;
1.1113 + CleanupClosePushL(rdStrm);
1.1114 + rdStrm.OpenL(db, <table_name>, <column_name>, rowid);
1.1115 +
1.1116 + HBufC8* buffer = HBufC8::NewLC(KBlockSize);
1.1117 + TPtr8 bufPtr(buffer->Des());
1.1118 + TInt size = rdStrm.SizeL();
1.1119 + while(size)
1.1120 + {
1.1121 + TInt bytesToRead = (size >= KBlockSize) ? KBlockSize : size ;
1.1122 + rdStrm.ReadL(bufPtr, bytesToRead); // read the next block of data
1.1123 + <do something with the block of data>
1.1124 + size =- bytesToRead;
1.1125 + }
1.1126 + CleanupStack::PopAndDestroy(2); // buffer, rdStrm
1.1127 + }
1.1128 +CleanupStack::PopAndDestroy(2); // stmt, db
1.1129 +@endcode
1.1130 +
1.1131 +@see RSqlBlobWriteStream
1.1132 +@see RSqlDatabase::LastInsertedRowId()
1.1133 +
1.1134 +@publishedAll
1.1135 +@released
1.1136 +*/
1.1137 +class RSqlBlobReadStream : public RReadStream
1.1138 + {
1.1139 +public:
1.1140 + IMPORT_C void OpenL(RSqlDatabase& aDb, const TDesC& aTableName, const TDesC& aColumnName,
1.1141 + TInt64 aRowId = KSqlLastInsertedRowId, const TDesC& aDbName = KNullDesC);
1.1142 + IMPORT_C TInt SizeL();
1.1143 + };
1.1144 +
1.1145 +/**
1.1146 +A direct handle to a blob, used for writing the content of the blob via a streaming interface.
1.1147 +
1.1148 +The target blob is identified using the relevant database connection, table name,
1.1149 +column name and ROWID of the record to which the blob belongs (also the attached
1.1150 +database name if the blob is contained in an attached database).
1.1151 +
1.1152 +A blob in this context refers to the content of a BLOB or TEXT column,
1.1153 +and a write handle can be opened on both types of column, except if the
1.1154 +column is indexed, in which case the open call will fail with KSqlErrGeneral.
1.1155 +For TEXT columns it is important to note that no conversions are performed on data
1.1156 +that is stored using this class - the data is simply stored as a stream of bytes.
1.1157 +
1.1158 +The class derives from RWriteStream and provides all of its streaming methods.
1.1159 +The SizeL() method can be used to check the total size of the blob, in bytes.
1.1160 +Note that this class cannot be used to increase the size of a blob, only to modify
1.1161 +the existing contents of a blob. An attempt to write beyond the end of a blob will
1.1162 +fail with KErrEof.
1.1163 +
1.1164 +It is strongly recommended to use this class for writing the content of large blobs
1.1165 +because it significantly reduces the amount of RAM that is used when compared to using
1.1166 +the RSqlParamWriteStream, RSqlStatement::BindBinary or RSqlStatement::BindText APIs.
1.1167 +
1.1168 +Specifically, it is recommended to use this class for blobs over 2Mb in size.
1.1169 +Indeed, in some circumstances where very large blobs are required it may be impossible
1.1170 +to create a blob or update its content using the legacy APIs (due to the server's finite
1.1171 +RAM capacity), and this class may provide the only way to achieve this.
1.1172 +
1.1173 +Using this class in combination with zeroblobs it is possible to create and manipulate
1.1174 +blobs that are gigabytes in size. A zeroblob acts as a place-holder for a blob whose
1.1175 +content is later written using this class and one can be created using an INSERT
1.1176 +statement that either contains the SQLite 'zeroblob()' function or on which
1.1177 +RSqlStatement::BindZeroBlob() has been executed.
1.1178 +Note that a zeroblob should be created in a column after which there are no columns
1.1179 +that contain anything other than zeroblobs or NULLs, otherwise the zeroblob must be
1.1180 +allocated in full in RAM.
1.1181 +
1.1182 +When creating a zeroblob it is recommended, where possible, to create the zeroblob and
1.1183 +then write the blob content within the same transaction. Otherwise the zeroblob will
1.1184 +have to be journalled before being written to.
1.1185 +
1.1186 +It is also strongly recommended to execute calls to WriteL() within a transaction.
1.1187 +If a leave occurs during a call to WriteL() then the current state of the blob object is
1.1188 +undefined and a ROLLBACK should be executed to return the blob object to its previous state.
1.1189 +Note that in order for a ROLLBACK to execute successfully all open RSqlBlobReadStream
1.1190 +and RSqlBlobWriteStream handles and all open RSqlStatement objects must be closed
1.1191 +before the ROLLBACK is executed.
1.1192 +
1.1193 +The following code illustrates typical use cases of this class:
1.1194 +
1.1195 +CASE 1 - creating a 5Mb blob.
1.1196 +
1.1197 +@code
1.1198 +RSqlDatabase db;
1.1199 +CleanupClosePushL(db);
1.1200 +<open/create "db" object>;
1.1201 +CleanupStack::PushL(TCleanupItem(&DoRollback, &db)); // rollback function
1.1202 +TInt err = db.Exec(_L("BEGIN"));
1.1203 +<check err>
1.1204 +err = db.Exec(_L("INSERT INTO table1 VALUES(35, zeroblob(5242880))"));
1.1205 +<check err>
1.1206 +RSqlBlobWriteStream wrStrm;
1.1207 +CleanupClosePushL(wrStrm);
1.1208 +wrStrm.OpenL(db, <table_name>, <column_name>);
1.1209 +TInt size = wrStrm.SizeL();
1.1210 +while(size)
1.1211 + {
1.1212 + TInt bytesToWrite = (size >= KBlockSize) ? KBlockSize : size ;
1.1213 + <fill a buffer 'buf' with this amount of the blob data>
1.1214 + wrStrm.WriteL(buf); // write the next block of data
1.1215 + size =- bytesToWrite;
1.1216 + }
1.1217 +CleanupStack::PopAndDestroy(&wrStrm);
1.1218 +CleanupStack::Pop(); // TCleanupItem
1.1219 +err = db.Exec(_L("COMMIT")); // blob data committed to disk
1.1220 +<check err>
1.1221 +CleanupStack::PopAndDestroy(&db);
1.1222 +@endcode
1.1223 +
1.1224 +CASE 2 - updating a large blob in the last inserted record.
1.1225 +
1.1226 +@code
1.1227 +RSqlDatabase db;
1.1228 +CleanupClosePushL(db);
1.1229 +<open/create "db" object>;
1.1230 +CleanupStack::PushL(TCleanupItem(&DoRollback, &db)); // rollback function
1.1231 +TInt err = db.Exec(_L("BEGIN"));
1.1232 +<check err>
1.1233 +RSqlBlobWriteStream wrStrm;
1.1234 +CleanupClosePushL(wrStrm);
1.1235 +wrStrm.OpenL(db, <table_name>, <column_name>);
1.1236 +<fill a buffer 'buf' with the changed blob data>
1.1237 +wrStrm.WriteL(buf); // update the blob
1.1238 +CleanupStack::PopAndDestroy(&wrStrm);
1.1239 +CleanupStack::Pop(); // TCleanupItem
1.1240 +err = db.Exec(_L("COMMIT")); // blob data committed to disk
1.1241 +<check err>
1.1242 +CleanupStack::PopAndDestroy(&db);
1.1243 +@endcode
1.1244 +
1.1245 +@see RSqlBlobReadStream
1.1246 +@see RSqlDatabase::LastInsertedRowId()
1.1247 +@see RSqlStatement::BindZeroBlob()
1.1248 +
1.1249 +@publishedAll
1.1250 +@released
1.1251 +*/
1.1252 +class RSqlBlobWriteStream : public RWriteStream
1.1253 + {
1.1254 +public:
1.1255 + IMPORT_C void OpenL(RSqlDatabase& aDb, const TDesC& aTableName, const TDesC& aColumnName,
1.1256 + TInt64 aRowId = KSqlLastInsertedRowId, const TDesC& aDbName = KNullDesC);
1.1257 + IMPORT_C TInt SizeL();
1.1258 + };
1.1259 +
1.1260 +/**
1.1261 +Utility class that provides methods for reading and writing the entire content of
1.1262 +a blob in a single call.
1.1263 +
1.1264 +The target blob is identified using the relevant database connection, table name,
1.1265 +column name and ROWID of the record to which the blob belongs (also the attached
1.1266 +database name if the blob is contained in an attached database).
1.1267 +
1.1268 +The behaviour of the RSqlBlobReadStream class and the recommendations for using
1.1269 +it exist for the Get() and GetLC() methods of this class. Similarly, the behaviour
1.1270 +of the RSqlBlobWriteStream class and the recommendations for using it exist for the
1.1271 +SetL() method of this class.
1.1272 +
1.1273 +In particular, it is strongly recommended to use this class or the RSqlBlobReadStream
1.1274 +and RSqlBlobWriteStream classes for reading and writing the content of large blobs
1.1275 +because it significantly reduces the amount of RAM that is used when compared to using
1.1276 +the legacy streaming and RSqlStatement APIs.
1.1277 +
1.1278 +Specifically, it is recommended to use this class for blobs over 2Mb in size.
1.1279 +Indeed, in some circumstances where very large blobs are in use it may be impossible
1.1280 +to read or write to a blob using the legacy APIs (due to the server's finite
1.1281 +RAM capacity), and this class or the RSqlBlobReadStream and RSqlBlobWriteStream classes
1.1282 +may provide the only way to achieve this.
1.1283 +
1.1284 +It is strongly recommended to execute calls to the SetL() method within a transaction.
1.1285 +If a leave occurs during a call to SetL() then the current state of the blob object is
1.1286 +undefined and a ROLLBACK should be executed to return the blob object to its previous state.
1.1287 +Note that in order for a ROLLBACK to execute successfully all open RSqlBlobReadStream
1.1288 +and RSqlBlobWriteStream handles and all open RSqlStatement objects must be closed
1.1289 +before the ROLLBACK is executed.
1.1290 +
1.1291 +When using SetL() to update the content of a zeroblob it is recommended, where possible,
1.1292 +to create the zeroblob and then call SetL() within the same transaction.
1.1293 +Otherwise the zeroblob will have to be journalled before being written to.
1.1294 +
1.1295 +The following code illustrates typical use cases of this class:
1.1296 +
1.1297 +CASE 1 - retrieving the entire content of a large blob.
1.1298 +
1.1299 +@code
1.1300 +RSqlDatabase db;
1.1301 +CleanupClosePushL(db);
1.1302 +<open/create "db" object>;
1.1303 +HBufC8* wholeBlob = TSqlBlob::GetLC(db, <table_name>, <column_name>, <rowid>);
1.1304 +<do something with the blob data>
1.1305 +CleanupStack::PopAndDestroy(2); // wholeBlob, db
1.1306 +@endcode
1.1307 +
1.1308 +
1.1309 +CASE 2 - creating a 4Mb blob.
1.1310 +
1.1311 +@code
1.1312 +RSqlDatabase db;
1.1313 +CleanupClosePushL(db);
1.1314 +<open/create "db" object>;
1.1315 +CleanupStack::PushL(TCleanupItem(&DoRollback, &db)); // rollback function
1.1316 +TInt err = db.Exec(_L("BEGIN"));
1.1317 +<check err>
1.1318 +err = db.Exec(_L("INSERT INTO table1 VALUES(99, zeroblob(4194304))"));
1.1319 +<check err>
1.1320 +<fill a buffer 'buf' with 4Mb of blob data>
1.1321 +TSqlBlob::SetL(db, <table_name>, <column_name>, buf);
1.1322 +CleanupStack::Pop(); // TCleanupItem
1.1323 +err = db.Exec(_L("COMMIT")); // blob data committed to disk
1.1324 +<check err>
1.1325 +CleanupStack::PopAndDestroy(&db);
1.1326 +@endcode
1.1327 +
1.1328 +@see RSqlBlobReadStream
1.1329 +@see RSqlBlobWriteStream
1.1330 +@see RSqlDatabase::LastInsertedRowId()
1.1331 +@see RSqlStatement::BindZeroBlob()
1.1332 +
1.1333 +@publishedAll
1.1334 +@released
1.1335 +*/
1.1336 +class TSqlBlob
1.1337 + {
1.1338 +public:
1.1339 + IMPORT_C static HBufC8* GetLC(RSqlDatabase& aDb,
1.1340 + const TDesC& aTableName,
1.1341 + const TDesC& aColumnName,
1.1342 + TInt64 aRowId = KSqlLastInsertedRowId,
1.1343 + const TDesC& aDbName = KNullDesC);
1.1344 +
1.1345 + IMPORT_C static TInt Get(RSqlDatabase& aDb,
1.1346 + const TDesC& aTableName,
1.1347 + const TDesC& aColumnName,
1.1348 + TDes8& aBuffer,
1.1349 + TInt64 aRowId = KSqlLastInsertedRowId,
1.1350 + const TDesC& aDbName = KNullDesC);
1.1351 +
1.1352 + IMPORT_C static void SetL(RSqlDatabase& aDb,
1.1353 + const TDesC& aTableName,
1.1354 + const TDesC& aColumnName,
1.1355 + const TDesC8& aData,
1.1356 + TInt64 aRowId = KSqlLastInsertedRowId,
1.1357 + const TDesC& aDbName = KNullDesC);
1.1358 + };
1.1359 +
1.1360 +/**
1.1361 +Defines a set of categories for the values returned by the SQL API.
1.1362 +
1.1363 +A call to an SQL API may complete with a non-zero return code indicating that some
1.1364 +unexpected behaviour has occurred. This can be categorised in a number of ways,
1.1365 +for example, as a Symbian OS error, or as a database error etc.
1.1366 +
1.1367 +Callers to the SQL API may not want to be concerned with the detailed meaning of
1.1368 +a specific return code value, and may find it sufficient just to know the category
1.1369 +of the error.
1.1370 +
1.1371 +The category associated with a specific return code can be found by passing the
1.1372 +return code value to the function SqlRetCodeClass().
1.1373 +
1.1374 +@publishedAll
1.1375 +@released
1.1376 +*/
1.1377 +enum TSqlRetCodeClass
1.1378 + {
1.1379 + /**
1.1380 + Indicates that a return code is just for information.
1.1381 +
1.1382 + This category corresponds to the SQL API return codes: KSqlAtRow and KSqlAtEnd.
1.1383 +
1.1384 + @see SqlRetCodeClass()
1.1385 + @see TSqlRetCodeClass
1.1386 + @see KSqlAtRow
1.1387 + @see KSqlAtEnd
1.1388 + */
1.1389 + ESqlInformation,
1.1390 +
1.1391 + /**
1.1392 + Indicates that a return code represents a database-specific error.
1.1393 +
1.1394 + This category corresponds to SQL API return codes in the range KSqlErrGeneral to KSqlErrStmtExpired.
1.1395 +
1.1396 + @see SqlRetCodeClass()
1.1397 + @see TSqlRetCodeClass
1.1398 + @see KSqlErrGeneral
1.1399 + @see KSqlErrStmtExpired
1.1400 + */
1.1401 + ESqlDbError,
1.1402 +
1.1403 + /**
1.1404 + Indicates that a return code represents a Symbian OS error.
1.1405 +
1.1406 + This category corresponds to SQL API return codes in the range KErrPermissionDenied to KErrNone,
1.1407 +
1.1408 + @see SqlRetCodeClass()
1.1409 + @see TSqlRetCodeClass
1.1410 + @see KErrPermissionDenied
1.1411 + @see KErrNone
1.1412 + */
1.1413 + ESqlOsError
1.1414 + };
1.1415 +
1.1416 +/**
1.1417 +An information type return code from a call to RSqlStatement::Next().
1.1418 +
1.1419 +It means that the RSqlStatement object points to a valid row, and that
1.1420 +the user can access the column data using the appropriate RSqlStatement
1.1421 +member functions.
1.1422 +
1.1423 +@see RSqlStatement::Next()
1.1424 +@see RSqlStatement
1.1425 +@see ESqlInformation
1.1426 +@see TSqlRetCodeClass
1.1427 +
1.1428 +@publishedAll
1.1429 +@released
1.1430 +*/
1.1431 +const TInt KSqlAtRow = 1;
1.1432 +
1.1433 +/**
1.1434 +An information type return code from a call to RSqlStatement::Next().
1.1435 +
1.1436 +It means that the RSqlStatement object does not point to a valid row,
1.1437 +and that column data accessors cannot be used.
1.1438 +
1.1439 +@see RSqlStatement::Next()
1.1440 +@see RSqlStatement
1.1441 +@see ESqlInformation
1.1442 +@see TSqlRetCodeClass
1.1443 +
1.1444 +@publishedAll
1.1445 +@released
1.1446 +*/
1.1447 +const TInt KSqlAtEnd = 2;
1.1448 +
1.1449 +/**
1.1450 +An SQL database-specific error type return code from a call to the SQL API.
1.1451 +
1.1452 +It indicates a general SQL error or a missing database.
1.1453 +
1.1454 +@see RSqlStatement
1.1455 +@see ESqlDbError
1.1456 +@see TSqlRetCodeClass
1.1457 +
1.1458 +@publishedAll
1.1459 +@released
1.1460 +*/
1.1461 +const TInt KSqlErrGeneral = -311;
1.1462 +
1.1463 +/**
1.1464 +An SQL database-specific error type return code from a call to the SQL API.
1.1465 +
1.1466 +It indicates an internal logic error in the SQL database engine, and specifically
1.1467 +that an internal consistency check within the SQL database engine has failed.
1.1468 +
1.1469 +@see RSqlStatement
1.1470 +@see ESqlDbError
1.1471 +@see TSqlRetCodeClass
1.1472 +
1.1473 +@publishedAll
1.1474 +@released
1.1475 +*/
1.1476 +const TInt KSqlErrInternal = -312;
1.1477 +
1.1478 +/**
1.1479 +An SQL database-specific error type return code from a call to the SQL API.
1.1480 +
1.1481 +It indicates that access permission has been denied.
1.1482 +
1.1483 +@see RSqlStatement
1.1484 +@see ESqlDbError
1.1485 +@see TSqlRetCodeClass
1.1486 +
1.1487 +@publishedAll
1.1488 +@released
1.1489 +*/
1.1490 +const TInt KSqlErrPermission = -313;
1.1491 +
1.1492 +/**
1.1493 +An SQL database-specific error type return code from a call to the SQL API.
1.1494 +
1.1495 +It indicates an internal logic error in the SQL database engine, and specifically
1.1496 +that a callback routine requested an abort.
1.1497 +
1.1498 +@publishedAll
1.1499 +@released
1.1500 +*/
1.1501 +const TInt KSqlErrAbort = -314;
1.1502 +
1.1503 +/**
1.1504 +An SQL database-specific error type return code from a call to the SQL API.
1.1505 +
1.1506 +It indicates that the database file is locked.
1.1507 +
1.1508 +@see RSqlStatement
1.1509 +@see ESqlDbError
1.1510 +@see TSqlRetCodeClass
1.1511 +
1.1512 +@publishedAll
1.1513 +@released
1.1514 +*/
1.1515 +const TInt KSqlErrBusy = -315;
1.1516 +
1.1517 +/**
1.1518 +An SQL database-specific error type return code from a call to the SQL API.
1.1519 +
1.1520 +It indicates that a table in the database is locked.
1.1521 +
1.1522 +@see RSqlStatement
1.1523 +@see ESqlDbError
1.1524 +@see TSqlRetCodeClass
1.1525 +
1.1526 +@publishedAll
1.1527 +@released
1.1528 +*/
1.1529 +const TInt KSqlErrLocked = -316;
1.1530 +
1.1531 +/**
1.1532 +An SQL database-specific error type return code from a call to the SQL API.
1.1533 +
1.1534 +It indicates an attempt to write to a database that is read-only.
1.1535 +
1.1536 +@see RSqlStatement
1.1537 +@see ESqlDbError
1.1538 +@see TSqlRetCodeClass
1.1539 +
1.1540 +@publishedAll
1.1541 +@released
1.1542 +*/
1.1543 +const TInt KSqlErrReadOnly = -318;
1.1544 +
1.1545 +/**
1.1546 +SQL database-specific error type. Operation terminated.
1.1547 +
1.1548 +@publishedAll
1.1549 +@released
1.1550 +*/
1.1551 +const TInt KSqlErrInterrupt = -319;
1.1552 +
1.1553 +/**
1.1554 +An SQL database-specific error type return code from a call to the SQL API.
1.1555 +
1.1556 +It indicates that a disk I/O error has occurred.
1.1557 +
1.1558 +@see RSqlStatement
1.1559 +@see ESqlDbError
1.1560 +@see TSqlRetCodeClass
1.1561 +
1.1562 +@publishedAll
1.1563 +@released
1.1564 +*/
1.1565 +const TInt KSqlErrIO = -320;
1.1566 +
1.1567 +/**
1.1568 +An SQL database-specific error type return code from a call to the SQL API.
1.1569 +
1.1570 +It indicates that the database disk image is malformed.
1.1571 +
1.1572 +@see RSqlStatement
1.1573 +@see ESqlDbError
1.1574 +@see TSqlRetCodeClass
1.1575 +
1.1576 +@publishedAll
1.1577 +@released
1.1578 +*/
1.1579 +const TInt KSqlErrCorrupt = -321;
1.1580 +
1.1581 +/**
1.1582 +SQL database-specific error type. Table or record not found.
1.1583 +
1.1584 +@publishedAll
1.1585 +@released
1.1586 +*/
1.1587 +const TInt KSqlErrNotFound = -322;
1.1588 +
1.1589 +/**
1.1590 +An SQL database-specific error type return code from a call to the SQL API.
1.1591 +
1.1592 +It indicates that an insertion operation has failed because an autoincrement column used up
1.1593 +all awailable rowids.
1.1594 +
1.1595 +@see RSqlStatement
1.1596 +@see ESqlDbError
1.1597 +@see TSqlRetCodeClass
1.1598 +
1.1599 +@publishedAll
1.1600 +@released
1.1601 +*/
1.1602 +const TInt KSqlErrFull = -323;
1.1603 +
1.1604 +/**
1.1605 +An SQL database-specific error type return code from a call to the SQL API.
1.1606 +
1.1607 +It indicates a failure to open the database file.
1.1608 +
1.1609 +@see RSqlStatement
1.1610 +@see ESqlDbError
1.1611 +@see TSqlRetCodeClass
1.1612 +
1.1613 +@publishedAll
1.1614 +@released
1.1615 +*/
1.1616 +const TInt KSqlErrCantOpen = -324;
1.1617 +
1.1618 +/**
1.1619 +An SQL database-specific error type return code from a call to the SQL API.
1.1620 +
1.1621 +It indicates a database lock protocol error.
1.1622 +
1.1623 +@see RSqlStatement
1.1624 +@see ESqlDbError
1.1625 +@see TSqlRetCodeClass
1.1626 +
1.1627 +@publishedAll
1.1628 +@released
1.1629 +*/
1.1630 +const TInt KSqlErrProtocol = -325;
1.1631 +
1.1632 +/**
1.1633 +An SQL database-specific error type return code from a call to the SQL API.
1.1634 +
1.1635 +It indicates that the database is empty.
1.1636 +
1.1637 +@see RSqlStatement
1.1638 +@see ESqlDbError
1.1639 +@see TSqlRetCodeClass
1.1640 +
1.1641 +@publishedAll
1.1642 +@released
1.1643 +*/
1.1644 +const TInt KSqlErrEmpty = -326;
1.1645 +
1.1646 +/**
1.1647 +An SQL database-specific error type return code from a call to the SQL API.
1.1648 +
1.1649 +It indicates that a prepared SQL statement is no longer valid
1.1650 +and cannot be executed.
1.1651 +
1.1652 +The most common reason for this return code is that the database schema was modified after
1.1653 +the SQL statement was prepared. The SQL statement must be prepared again
1.1654 +using the RSqlStatement::Prepare() member functions.
1.1655 +
1.1656 +Another possible reason for this return code is a detached database.
1.1657 +
1.1658 +@see RSqlStatement
1.1659 +@see ESqlDbError
1.1660 +@see TSqlRetCodeClass
1.1661 +
1.1662 +@publishedAll
1.1663 +@released
1.1664 +*/
1.1665 +const TInt KSqlErrSchema = -327;
1.1666 +
1.1667 +/**
1.1668 +SQL database-specific error type. Too much data for one row.
1.1669 +
1.1670 +@publishedAll
1.1671 +@released
1.1672 +*/
1.1673 +const TInt KSqlErrTooBig = -328;
1.1674 +
1.1675 +/**
1.1676 +An SQL database-specific error type return code from a call to the SQL API.
1.1677 +
1.1678 +It indicates an abort due to constraint violation.
1.1679 +
1.1680 +"Constraint violation" means violation of one or more column constraints ("NOT NULL", "PRIMARY KEY",
1.1681 +"UNIQUE", "CHECK", "DEFAULT", "COLLATE" SQL keywords) or table constraints ("PRIMARY KEY", "UNIQUE",
1.1682 +"CHECK" SQL keywords).
1.1683 +
1.1684 +@see RSqlStatement
1.1685 +@see ESqlDbError
1.1686 +@see TSqlRetCodeClass
1.1687 +
1.1688 +@publishedAll
1.1689 +@released
1.1690 +*/
1.1691 +const TInt KSqlErrConstraint = -329;
1.1692 +
1.1693 +/**
1.1694 +An SQL database-specific error type return code from a call to the SQL API.
1.1695 +
1.1696 +It indicates a data type mismatch.
1.1697 +
1.1698 +@see RSqlStatement
1.1699 +@see ESqlDbError
1.1700 +@see TSqlRetCodeClass
1.1701 +
1.1702 +@publishedAll
1.1703 +@released
1.1704 +*/
1.1705 +const TInt KSqlErrMismatch = -330;
1.1706 +
1.1707 +/**
1.1708 +An SQL database-specific error type return code from a call to the SQL API.
1.1709 +
1.1710 +It indicates an internal logic error in the SQL database engine.
1.1711 +
1.1712 +@see RSqlStatement
1.1713 +@see ESqlDbError
1.1714 +@see TSqlRetCodeClass
1.1715 +
1.1716 +@publishedAll
1.1717 +@released
1.1718 +*/
1.1719 +const TInt KSqlErrMisuse = -331;
1.1720 +
1.1721 +/**
1.1722 +An SQL database-specific error type return code from a call to the SQL API.
1.1723 +
1.1724 +It indicates that a parameter index value is out of range.
1.1725 +
1.1726 +@see RSqlStatement
1.1727 +@see ESqlDbError
1.1728 +@see TSqlRetCodeClass
1.1729 +
1.1730 +@publishedAll
1.1731 +@released
1.1732 +*/
1.1733 +const TInt KSqlErrRange = -335;
1.1734 +
1.1735 +/**
1.1736 +An SQL database-specific error type return code from a call to the SQL API.
1.1737 +
1.1738 +It indicates that the file that has been opened is not a database file.
1.1739 +
1.1740 +@see RSqlStatement
1.1741 +@see ESqlDbError
1.1742 +@see TSqlRetCodeClass
1.1743 +
1.1744 +@publishedAll
1.1745 +@released
1.1746 +*/
1.1747 +const TInt KSqlErrNotDb = -336;
1.1748 +
1.1749 +/**
1.1750 +An SQL database-specific error type return code from a call to the SQL API.
1.1751 +
1.1752 +It indicates that an SQL statement has expired, and needs to be prepared again.
1.1753 +
1.1754 +@see RSqlStatement
1.1755 +@see ESqlDbError
1.1756 +@see TSqlRetCodeClass
1.1757 +
1.1758 +@publishedAll
1.1759 +@released
1.1760 +*/
1.1761 +const TInt KSqlErrStmtExpired = -360;
1.1762 +
1.1763 +IMPORT_C TSqlRetCodeClass SqlRetCodeClass(TInt aSqlRetCode);
1.1764 +
1.1765 +#endif //__SQLDB_H__