// Copyright (c) 2005-2009 Nokia Corporation and/or its subsidiary(-ies).

// All rights reserved.

// This component and the accompanying materials are made available

// under the terms of "Eclipse Public License v1.0"

// which accompanies this distribution, and is available

// at the URL "http://www.eclipse.org/legal/epl-v10.html".

//

// Initial Contributors:

// Nokia Corporation - initial contribution.

//

// Contributors:

//

// Description:

// SQL Client side API header

// 

//

/**

 @file

 @publishedAll

 @released

*/

#ifndef __SQLDB_H__

#define __SQLDB_H__

#ifndef __S32STD_H__

#include <s32std.h>	//RReadStream, RWriteStream

#endif

#ifndef SYMBIAN_ENABLE_SPLIT_HEADERS 

	#include <sqlresourcetester.h>

#endif

//Forward declarations

class CSqlSecurityPolicy;

class RSqlDatabase;

class CSqlDatabaseImpl;

class RSqlStatement;

class CSqlStatementImpl;

class RSqlColumnReadStream;

class RSqlParamWriteStream;

class TSqlScalarFullSelectQuery;

class RSqlBlob;

class RSqlBlobReadStream;

class RSqlBlobWriteStream;

class TSqlResourceProfiler;

/**

Used to specify that the ROWID of the most recently inserted record

from the specified database connection should be used as the ROWID 

in a call to directly access a blob.

@see RSqlBlobReadStream

@see RSqlBlobWriteStream

@see TSqlBlob

@publishedAll

@released

*/

const TInt KSqlLastInsertedRowId = -1;

/**

A container for the security policies for a shared SQL database.

The container can contain:

- security policies that apply to the database.

- security policies that apply to individual database objects, i.e. database tables.

For the database, you use RSqlSecurityPolicy::SetDbPolicy() to apply a separate

security policy to:

- the database schema.

- read activity on the database.

- write activity on the database.

For database tables, you use RSqlSecurityPolicy::SetPolicy() to apply a separate

security policy to:

- write activity on each named database table.

- read activity on each named database table.

A client uses a RSqlSecurityPolicy object to create a secure database. It does this by:

- creating a RSqlSecurityPolicy object.

- setting all the appropriate security policies into it.

- passing the object as an argument to RSqlDatabase::Create().

- closing the RSqlSecurityPolicy object on return from RSqlDatabase::Create().

Once a secure shared database has been created with specific security policies,

these policies are made persistent and cannot be changed during the life of

that database.

Security policies are encapsulated by TSecurityPolicy objects.

The general usage pattern is to create the security policies container object

(RSqlSecurityPolicy) using a default security policy (TSecurityPolicy), and then

to assign more specific 'overriding' security policies.

The following code fragment shows how you do this:

@code

TSecurityPolicy defaultPolicy;

RSqlSecurityPolicy securityPolicy;

RSqlDatabase database;

TInt err;

// Create security policies container object using a default security policy.

securityPolicy.Create(defaultPolicy); 

// Set up policy to apply to database schema

// and assign it

TSecurityPolicy schemaPolicy;

...

err = securityPolicy.SetDbPolicy(RSqlSecurityPolicy::ESchemaPolicy, schemaPolicy);

// Set up policy to apply to write activity on the database

// and assign it

TSecurityPolicy writePolicy;

...

err = securityPolicy.SetDbPolicy(RSqlSecurityPolicy::EWritePolicy, writePolicy);

// Set up policy to apply to write activity to the database table named "Table1"

// and assign it

TSecurityPolicy tablePolicy1;

...

err = securityPolicy.SetPolicy(RSqlSecurityPolicy::ETable, _L("Table1"), RSqlSecurityPolicy::EWritePolicy, tablePolicy1);

// Set up policy to apply to read activity to the database table named "Table2"

TSecurityPolicy tablePolicy2;

err = securityPolicy.SetPolicy(RSqlSecurityPolicy::ETable, _L("Table2"), RSqlSecurityPolicy::EReadPolicy, tablePolicy2);

// Create the database, passing the security policies

err = database.Create(KDatabaseName, securityPolicy);

// We can close the RSqlSecurityPolicy object.

securityPolicy.Close();

@endcode

Note that in this example code fragment, the client has not assigned specific

overriding policies for all possible cases; for example, no overriding policy

has been assigned to control read activity on the database, read activity

on "Table1", nor write activity on "Table2".

For these cases, the default security policy will apply.

A client can also retrieve a database's security policies by calling

RSqlDatabase::GetSecurityPolicy(); this returns a RSqlSecurityPolicy object

containing the security policies. Note that it is the client's responsibility

to close the RSqlSecurityPolicy object when the client no longer needs it. The

following code fragment suggests how you might do this:

@code

RSqlDatabase database;

RSqlSecurityPolicy securityPolicy;

// Retrieve the security policies; on return from the call to 

// GetSecurityPolicy(), the RSqlSecurityPolicy object passed 

// to this function will contain the security policies.

database.GetSecurityPolicy(securityPolicy);

...

// This is the security policy that applies to database schema

TSecurityPolicy schemaPolicy = securityPolicy.DbPolicy(RSqlSecurityPolicy::ESchemaPolicy);

...

// This is the security policy that applies to write activity to the database

// table named "Table1".

TSecurityPolicy writePolicy = securityPolicy.Policy(RSqlSecurityPolicy::ETable, _L("Table1"), RSqlSecurityPolicy::EWritePolicy);

...

// Close the RSqlSecurityPolicy object when no longer needed.

securityPolicy.Close();

@endcode

Note that in the cases where an 'overriding' security policy was not originally assigned,

then the security policy returned will simply be the default security policy.

@see TSecurityPolicy

@see RSqlDatabase

@see RSqlSecurityPolicy::SetDbPolicy()

@see RSqlSecurityPolicy::SetPolicy()

@publishedAll

@released

*/

class RSqlSecurityPolicy

	{

	friend class RSqlDatabase;

public:

	/**

	Defines a set of values that represents the database security policy types.

	Each database security policy type refers to a set of capabilities encapsulated in 

	a TSecurityPolicy object. The TSecurityPolicy object defines what capabilities the calling

	application must have in order to perform partiqular database operation.

	@see TSecurityPolicy

	*/

	enum TPolicyType 

		{

		/**

		Schema database security policy. An application with schema database security policy can 

		modify the database schema, write to database, read from database.

		*/

		ESchemaPolicy, 

		/**

		Read database security policy. An application with read database security policy can 

		read from database.

		*/

		EReadPolicy, 

		/**

		Write database security policy. An application with write database security policy can 

		write to database.

		*/

		EWritePolicy

		};

	/**

	Not currently supported.

	Defines a set of values that represents the database objects which can be protected by 

	database security policy types.

	*/

	enum TObjectType 

		{

		ETable

		};

	IMPORT_C RSqlSecurityPolicy();

	IMPORT_C TInt Create(const TSecurityPolicy& aDefaultPolicy);

	IMPORT_C void CreateL(const TSecurityPolicy& aDefaultPolicy);

	IMPORT_C void Close();

	IMPORT_C TInt SetDbPolicy(TPolicyType aPolicyType, const TSecurityPolicy& aPolicy);

	IMPORT_C TInt SetPolicy(TObjectType aObjectType, const TDesC& aObjectName, TPolicyType aPolicyType, const TSecurityPolicy& aPolicy);

	IMPORT_C TSecurityPolicy DefaultPolicy() const;

	IMPORT_C TSecurityPolicy DbPolicy(TPolicyType aPolicyType) const;

	IMPORT_C TSecurityPolicy Policy(TObjectType aObjectType, const TDesC& aObjectName, TPolicyType aPolicyType) const;

	IMPORT_C void ExternalizeL(RWriteStream& aStream) const;

	IMPORT_C void InternalizeL(RReadStream& aStream);

private:	

	void Set(CSqlSecurityPolicy& aImpl);

	CSqlSecurityPolicy& Impl() const;

private:

	CSqlSecurityPolicy* iImpl;

	};

/**

A handle to a SQL database.

A RSqlDatabase object is, in effect, a handle to the SQL database. A client can:

- create a SQL database by calling RSqlDatabase::Create().

- open an existing SQL database by calling RSqlDatabase::Open().

- close a SQL database by calling RSqlDatabase::Close().

- copy a SQL database by calling RSqlDatabase::Copy().

- delete a SQL database by calling RSqlDatabase::Delete().

- attach a SQL database to current database connection by calling RSqlDatabase::Attach().

- detach a SQL database from current database connection by calling RSqlDatabase::Detach().

The RSqlDatabase handles are not thread-safe.

A client can create either a non-secure database or a secure database,

depending on the variant of RSqlDatabase::Create() that is used.

- a non-secure database is created if the RSqlDatabase::Create(const TDesC&) variant is used.

- a secure database is created if the RSqlDatabase::Create(const TDesC&, const RSqlSecurityPolicy&)

variant is used. In this case, a container containing a collection of security

policies needs to be set up first and passed to this Create() function.

See references to RSqlSecurityPolicy for more information on security policies.

A client can also specify how it wants a transaction to interact with

other transactions that may be running concurrently. The various ways in which

transactions can interact (i.e. how one transaction can affect another) are

referred to as "transaction isolation levels", and are defined by the values

of the TIsolationLevel enum. A client specifies this by calling RSqlDatabase::SetIsolationLevel().

Each of the various flavours of Open and Create allows the optional provision of a

configuration string. It is acceptable for this string to be missing.

In the case where the string is missing, the config in the SqlServer.sql file

will be used. If that does not exist then the MMH macro definitions will be used.

The config string is in the format PARAM=VALUE; PARAM=VALUE;...

Allowed parameters are:

	cache_size=nnnn

	page_size=nnnn

	encoding=UTF8|UTF16

Badly formed config strings are reported as KErrArgument

The string may not exceed 255 characters.

Please note that a database can only be accessed within the thread where it has been created. It is then not possible

to create a database from thread1 and access it from thread2.

A client calls RSqlDatabase::Exec() to execute SQL statements.

@see RSqlDatabase::Create()

@see RSqlDatabase::Open()

@see RSqlDatabase::Close()

@see RSqlDatabase::Copy()

@see RSqlDatabase::Delete()

@see RSqlDatabase::Attach()

@see RSqlDatabase::Detach()

@see RSqlDatabase::SetIsolationLevel()

@see RSqlDatabase::Exec()

@see TIsolationLevel

@see RSqlSecurityPolicy

@publishedAll

@released

*/

class RSqlDatabase

	{

	friend class RSqlStatement;

	friend class TSqlScalarFullSelectQuery;

	friend class RSqlBlob;

	friend class RSqlBlobReadStream;

	friend class RSqlBlobWriteStream;

	friend class TSqlResourceProfiler;

public:

	/**

	Defines a set of values that represents the transaction isolation level.

	A transaction isolation level defines the way in which a transaction

	interacts with other transactions that may be in progress concurrently.

	A client sets the transaction isolation level by calling SetIsolationLevel()

	@see RSqlDatabase::SetIsolationLevel()

	*/

	enum TIsolationLevel 

		{

		/**

		A transaction can read uncommitted data, i.e. data that is being changed

		by another transaction, which is still in progress.

		This means that

		- a 'database read' transaction will not block 'database write' transactions

		being performed by different database connections on the same shared database.

		- a 'database read' transaction will not be blocked by 'database write'

		transactions performed by the same database connection.

		- concurrent 'database write' transactions are prevented.

		This transaction isolation level can be set at any time during

		the lifetime of the database.

		@see TIsolationLevel

		@see RSqlDatabase::SetIsolationLevel()

		*/

		EReadUncommitted, 

		/**

		Not currently supported.

		A transaction cannot read uncommitted data. "Dirty reads" are prevented.

		"Dirty read" is a data inconsistency type which can be described with the following example:

		- Transaction A updates TableA.Column1 value from 1 to 2;

		- Transaction B reads TableA.Column1 value;

		- Transaction A rolls back and restores the original value of TableA.Column1 (1);

		- Transaction B ends showing that TableA.Column1 value is 2, even though, logically and transactionally, 

		  this data never really even existed in the database because Transaction A never committed that change 

		  to the database;

		@see TIsolationLevel

		@see RSqlDatabase::SetIsolationLevel()

		*/

		EReadCommitted, 

		/**

		Not currently supported.

		A transaction cannot change data that is being read by a different transaction. 

		"Dirty reads" and "non-repeatable reads" are prevented.

		"Non-repeatable reads" is a data inconsistency type which can be described with the following example:

		- Transaction A reads TableA.Column1 value which is 1;

		- Transaction B updates TableA.Column1 value from 1 to 2;

		- Transaction B commits the chages;

		- Transaction A reads TableA.Column1 value again. Transaction A has inconsistent data because TableA.Column1 

		  value now is 2 instead of 1, all within the scope of the same Transaction A;

		@see TIsolationLevel

		@see RSqlDatabase::SetIsolationLevel()

		*/

		ERepeatableRead, 

		/**

		Any number of 'database read' transactions can be performed concurrently

		by different database connections on the same shared database.

		Only one 'database write' transaction can be performed at any one time. If a

		'database write' transaction is in progress, then any attempt to start

		another 'database read' or 'database write' transaction will be blocked

		until the first 'database write' transaction has completed.

		This is the default isolation level, if no isolation level is

		explicitly set.

		"Dirty reads", "non-repeatable" reads and "phantom reads" are prevented.

		"Phantom reads" is a data inconsistency type which can be described with the following example:

		- Transaction A reads all rows that have Column1 = 1;

		- Transaction B inserts a new row which has Column1 = 1;

		- Transaction B commits;

		- Transaction A updates all rows that have Column1 = 1. This will also update the row that 

		  Transaction B inserted, because Transaction A must read the data again in order to update it.

		- Transaction A commits;

		@see TIsolationLevel

		@see RSqlDatabase::SetIsolationLevel()

		*/

		ESerializable

		};

	/**

	This structure is used for retrieving the database size and database free space.

	@see RSqlDatabase::Size(TSize&)

	*/

	struct TSize

		{

		/** The database size in bytes*/

		TInt64	iSize;

		/** The database free space in bytes*/

		TInt64	iFree;

		};

	/** If this value is used as an argument of RSqlDatabase::Compact() (aSize argument), then all free space will be removed */

	enum {EMaxCompaction = -1};

	IMPORT_C RSqlDatabase();

	IMPORT_C TInt Create(const TDesC& aDbFileName, const TDesC8* aConfig=NULL);

	IMPORT_C TInt Create(const TDesC& aDbFileName,

			const RSqlSecurityPolicy& aSecurityPolicy, const TDesC8* aConfig=NULL);

	IMPORT_C TInt Open(const TDesC& aDbFileName, const TDesC8* aConfig=NULL);

	IMPORT_C void CreateL(const TDesC& aDbFileName, const TDesC8* aConfig=NULL);

	IMPORT_C void CreateL(const TDesC& aDbFileName,

			const RSqlSecurityPolicy& aSecurityPolicy, const TDesC8* aConfig=NULL);

	IMPORT_C void OpenL(const TDesC& aDbFileName, const TDesC8* aConfig=NULL);

	IMPORT_C void Close();

	IMPORT_C TInt Attach(const TDesC& aDbFileName, const TDesC& aDbName);

	IMPORT_C TInt Detach(const TDesC& aDbName);

	IMPORT_C static TInt Copy(const TDesC& aSrcDbFileName, const TDesC& aDestDbFileName);

	IMPORT_C static TInt Delete(const TDesC& aDbFileName);

	IMPORT_C TInt GetSecurityPolicy(RSqlSecurityPolicy& aSecurityPolicy) const;

	IMPORT_C void GetSecurityPolicyL(RSqlSecurityPolicy& aSecurityPolicy) const;

	IMPORT_C TInt SetIsolationLevel(TIsolationLevel aIsolationLevel);

	IMPORT_C TInt Exec(const TDesC& aSqlStmt);

	IMPORT_C TInt Exec(const TDesC8& aSqlStmt);

	IMPORT_C void Exec(const TDesC& aSqlStmt, TRequestStatus& aStatus);

	IMPORT_C void Exec(const TDesC8& aSqlStmt, TRequestStatus& aStatus);

	IMPORT_C TPtrC LastErrorMessage() const;

	IMPORT_C TInt64 LastInsertedRowId() const; 

	IMPORT_C TBool InTransaction() const;

	IMPORT_C TInt Size() const;

	IMPORT_C TInt Size(TSize& aSize, const TDesC& aDbName = KNullDesC) const;

	IMPORT_C TInt Compact(TInt64 aSize, const TDesC& aDbName = KNullDesC);

	IMPORT_C void Compact(TInt64 aSize, TRequestStatus& aStatus, const TDesC& aDbName = KNullDesC);

	IMPORT_C TInt ReserveDriveSpace(TInt aSize);

	IMPORT_C void FreeReservedSpace();

	IMPORT_C TInt GetReserveAccess();

	IMPORT_C void ReleaseReserveAccess();

private:

	CSqlDatabaseImpl& Impl() const;

private:

	CSqlDatabaseImpl* iImpl;

	};

/**

TSqlScalarFullSelectQuery interface is used for executing SELECT sql queries, which 

return a single row consisting of a single column value.

Examples.

CASE 1 - retrieving records count of a table:

@code

RSqlDatabase db;

//initialize db object....

.......

TSqlScalarFullSelectQuery fullSelectQuery(db);

TInt recCnt = fullSelectQuery.SelectIntL(_L("SELECT COUNT(*) FROM PersonTbl"));

@endcode

CASE 2 - retrieving specific column value using a condition in the SELECT statement:

@code

RSqlDatabase db;

//initialize db object....

.......

TSqlScalarFullSelectQuery fullSelectQuery(db);

TInt personId = fullSelectQuery.SelectIntL(_L("SELECT ID FROM PersonTbl WHERE Name = 'John'"));

@endcode

CASE 3 - retrieving a text column value, the receiving buffer is not big enough:

@code

RSqlDatabase db;

//initialize db object....

.......

TSqlScalarFullSelectQuery fullSelectQuery(db);

HBufC* buf = HBufC::NewLC(20);

TPtr name = buf->Des();

TInt rc = fullSelectQuery.SelectTextL(_L("SELECT Name FROM PersonTbl WHERE Id = 1"), name);

TEST(rc >= 0); //the function may return only non-negative values

if(rc > 0)

	{

	buf = buf->ReAllocL(rc);

	CleanupStack::Pop();	

	CleanupStack::PushL(buf);

	name.Set(buf->Des());

	rc = fullSelectQuery.SelectTextL(_L("SELECT Name FROM PersonTbl WHERE Id = 1"), name);

	TEST(rc == 0);

	}

CleanupStack::PopAndDestroy();//buf

@endcode

@see RSqlDatabase

@publishedAll

@released

*/

class TSqlScalarFullSelectQuery

	{

public:

	IMPORT_C TSqlScalarFullSelectQuery();

	IMPORT_C TSqlScalarFullSelectQuery(RSqlDatabase& aDatabase);

	IMPORT_C void SetDatabase(RSqlDatabase& aDatabase);

	IMPORT_C TInt SelectIntL(const TDesC& aSqlStmt);

	IMPORT_C TInt64 SelectInt64L(const TDesC& aSqlStmt);

	IMPORT_C TReal SelectRealL(const TDesC& aSqlStmt);

	IMPORT_C TInt SelectTextL(const TDesC& aSqlStmt, TDes& aDest);

	IMPORT_C TInt SelectBinaryL(const TDesC& aSqlStmt, TDes8& aDest);

	IMPORT_C TInt SelectIntL(const TDesC8& aSqlStmt);

	IMPORT_C TInt64 SelectInt64L(const TDesC8& aSqlStmt);

	IMPORT_C TReal SelectRealL(const TDesC8& aSqlStmt);

	IMPORT_C TInt SelectTextL(const TDesC8& aSqlStmt, TDes& aDest);

	IMPORT_C TInt SelectBinaryL(const TDesC8& aSqlStmt, TDes8& aDest);

private:

	inline CSqlDatabaseImpl& Impl() const;

private:	

	CSqlDatabaseImpl* iDatabaseImpl;

	};

/**

An enumeration whose values represent the supported database column types.

@see RSqlStatement::ColumnType()

@publishedAll

@released

*/

enum TSqlColumnType 

	{

	/**

	Null column value.

	*/

	ESqlNull,

 	/**

 	32-bit integer column value.

 	*/  

	ESqlInt, 

 	/**

 	64-bit integer column value.

 	*/

	ESqlInt64, 

	/**

	64-bit floating point column value.

	*/

	ESqlReal, 

	/**

	Unicode text, a sequence of 16-bit character codes.

	*/

	ESqlText, 

	/**

	Binary data, a sequence of bytes.

	*/

	ESqlBinary

	};

/**

Represents an SQL statement.

An object of this type can be used to execute all types of SQL statements; this

includes SQL statements with parameters.

If a SELECT statament is passed to RSqlStatement::Prepare(), then the returned record set 

is forward only, non-updateable.

There are a number of ways that this object is used; here are some examples.

CASE 1 - the execution of a SQL statement, which does not return record set:

@code

RSqlDatabase database;

.........

RSqlStatement stmt;

TInt err = stmt.Prepare(database, _L("INSERT INTO Tbl1(Fld1) VALUES(:Val)"));

TInt paramIndex = stmt.ParameterIndex(_L(":Val"));

for(TInt i=1;i<=10;++i)

	{

	err = stmt.BindInt(paramIndex, i);

	err = stmt.Exec();

	err = stmt.Reset();

	}

stmt.Close();

@endcode

The following pseudo code shows the general pattern:

@code

<RSqlStatement::Prepare()>

[begin:]

<RSqlStatement::Bind<param_type>()>

<RSqlStatement::Exec()>

[<RSqlStatement::Reset()>]

[<RSqlStatement::Bind<param_type>()>]

[<Goto :begin>]

@endcode

CASE 2 - the execution of a SQL statement, which returns a record set:

@code

RSqlDatabase database;

.........

RSqlStatement stmt;

TInt err = stmt.Prepare(database, _L("SELECT Fld1 FROM Tbl1 WHERE Fld1 > :Val"));

TInt paramIndex = stmt.ParameterIndex(_L(":Val"));

err = stmt.BindInt(paramIndex, 5);

TInt columnIndex = stmt.ColumnIndex(_L("Fld1"));

while((err = stmt.Next()) == KSqlAtRow)

	{

	TInt val = stmt.ColumnInt(columnIndex);

	RDebug::Print(_L("val=%d\n"), val);

	}

if(err == KSqlAtEnd)

	<OK - no more records>;

else

	<process the error>;

stmt.Close();

@endcode

The following pseudo code shows the general pattern:

@code

<RSqlStatement::Prepare()>

[begin:]

<while (RSqlStatement::Next() == KSqlAtRow)>

	<do something with the records>

if(err == KSqlAtEnd)

	<OK - no more records>;

else

	<process the error>;

[<RSqlStatement::Reset()>]

[<RSqlStatement::Bind<param_type>()>]

[<Goto begin>]

@endcode

CASE 3.1 - SELECT statements: large column data processing, where the data is

copied into a buffer supplied by the client:

@code

RSqlDatabase database;

.........

RSqlStatement stmt;

TInt err = stmt.Prepare(database, _L("SELECT BinaryField FROM Tbl1"));

TInt columnIndex = stmt.ColumnIndex(_L("BinaryField"));

while((err = stmt.Next()) == KSqlAtRow)

	{

	TInt size = stmt. ColumnSize(columnIndex);

	HBufC8* buf = HBufC8::NewL(size);

	err = stmt.ColumnBinary(columnIndex, buf->Ptr());

	<do something with the data>;

	delete buf;

	}

if(err == KSqlAtEnd)

	<OK - no more records>;

else

	<process the error>;

stmt.Close();

@endcode

CASE 3.2 - SELECT statements: large column data processing, where the data is

accessed by the client without copying:

@code

RSqlDatabase database;

.........

RSqlStatement stmt;

TInt err = stmt.Prepare(database, _L("SELECT BinaryField FROM Tbl1"));

TInt columnIndex = stmt.ColumnIndex(_L("BinaryField"));

while((err = stmt.Next()) == KSqlAtRow)

	{

	TPtrC8 data = stmt.ColumnBinaryL(columnIndex);

	<do something with the data>;

	}

if(err == KSqlAtEnd)

	<OK - no more records>;

else

	<process the error>;

stmt.Close();

@endcode

CASE 3.3 - SELECT statements, large column data processing (the data is accessed by 

the client without copying), leaving-safe processing:

@code

RSqlDatabase database;

.........

RSqlStatement stmt;

TInt err = stmt.Prepare(database, _L("SELECT BinaryField FROM Tbl1"));

TInt columnIndex = stmt.ColumnIndex(_L("BinaryField"));

while((err = stmt.Next()) == KSqlAtRow)

	{

	TPtrC8 data;

	TInt err = stmt.ColumnBinary(columnIndex, data);

	if(err == KErrNone)

		{

		<do something with the data>;

		}

	}

if(err == KSqlAtEnd)

	<OK - no more records>;

else

	<process the error>;

stmt.Close();

@endcode

CASE 3.4 - SELECT statements: large column data processing, where the data is

accessed by the client using a stream:

@code

RSqlDatabase database;

.........

RSqlStatement stmt;

TInt err = stmt.Prepare(database, _L("SELECT BinaryField FROM Tbl1"));

TInt columnIndex = stmt.ColumnIndex(_L("BinaryField"));

while((err = stmt.Next()) == KSqlAtRow)

	{

	RSqlColumnReadStream stream;

	err = stream.ColumnBinary(stmt, columnIndex);

	<do something with the data in the stream>;

	stream.Close();

	}

if(err == KSqlAtEnd)

	<OK - no more records>;

else

	<process the error>;

stmt.Close();

@endcode

CASE 4 - the execution of a SQL statement with parameter(s), some of which may

be large text or binary values:

@code

RSqlDatabase database;

.........

RSqlStatement stmt;

TInt err = 

	stmt.Prepare(database, _L("UPDATE Tbl1 SET LargeTextField = :LargeTextVal WHERE IdxField = :KeyVal"));

TInt paramIndex1 = stmt.ParameterIndex(_L(":LargeTextVal"));

TInt paramIndex2 = stmt.ParameterIndex(_L(":KeyVal"));

for(TInt i=1;i<=10;++i)

	{

	RSqlParamWriteStream stream;

	err = stream.BindText(stmt, paramIndex1);

	<insert large text data into the stream>;

	stream.Close();

	err = stmt.BindInt(paramIndex2, i);

	err = stmt.Exec();

	stmt.Reset();

	}

stmt.Close();

@endcode

The following table shows what is returned when the caller uses a specific

column data retrieving function on a specific column type.

@code

--------------------------------------------------------------------------------

Column type | ColumnInt() ColumnInt64() ColumnReal() ColumnText() ColumnBinary()

--------------------------------------------------------------------------------

Null........|.0...........0.............0.0..........KNullDesC....KNullDesC8

Int.........|.Int.........Int64.........Real.........KNullDesC....KNullDesC8 

Int64.......|.clamp.......Int64.........Real.........KNullDesC....KNullDesC8 

Real........|.round.......round.........Real.........KNullDesC....KNullDesC8 

Text........|.0...........0.............0.0..........Text.........KNullDesC8   

Binary......|.0...........0.............0.0..........KNullDesC....Binary

--------------------------------------------------------------------------------

@endcode

Note the following definitions:

- "clamp": return KMinTInt or KMaxTInt if the value is outside the range that can be 

represented by the type returned by the accessor function.

- "round": the floating point value will be rounded up to the nearest integer.

If the result is outside the range that can be represented by the type returned

by the accessor function, then it will be clamped.

Note that when handling blob and text data over 2Mb in size it is recommended that the 

RSqlBlobReadStream and RSqlBlobWriteStream classes or the TSqlBlob class is used instead. 

These classes provide a more RAM-efficient way of reading and writing large amounts of 

blob or text data from a database.

@see KMinTInt

@see KMaxTInt

@see KNullDesC

@see KNullDesC8

@see RSqlBlobReadStream

@see RSqlBlobWriteStream

@see TSqlBlob

@publishedAll

@released

*/

class RSqlStatement

	{

	friend class RSqlColumnReadStream;

	friend class RSqlParamWriteStream;

public:

	IMPORT_C RSqlStatement();

	IMPORT_C TInt Prepare(RSqlDatabase& aDatabase, const TDesC& aSqlStmt);

	IMPORT_C TInt Prepare(RSqlDatabase& aDatabase, const TDesC8& aSqlStmt);

	IMPORT_C void PrepareL(RSqlDatabase& aDatabase, const TDesC& aSqlStmt);

	IMPORT_C void PrepareL(RSqlDatabase& aDatabase, const TDesC8& aSqlStmt);

	IMPORT_C void Close();

	IMPORT_C TBool AtRow() const;

	IMPORT_C TInt Reset();

	IMPORT_C TInt Exec();

	IMPORT_C void Exec(TRequestStatus& aStatus);

	IMPORT_C TInt Next();

	IMPORT_C TInt ParameterIndex(const TDesC& aParameterName) const;

	IMPORT_C TInt ColumnCount() const;

	IMPORT_C TInt ColumnIndex(const TDesC& aColumnName) const;

	IMPORT_C TSqlColumnType ColumnType(TInt aColumnIndex) const;

	IMPORT_C TInt DeclaredColumnType(TInt aColumnIndex, TSqlColumnType& aColumnType) const;

	IMPORT_C TInt ColumnSize(TInt aColumnIndex) const;

	IMPORT_C TInt BindNull(TInt aParameterIndex);

	IMPORT_C TInt BindInt(TInt aParameterIndex, TInt aParameterValue);

	IMPORT_C TInt BindInt64(TInt aParameterIndex, TInt64 aParameterValue);

	IMPORT_C TInt BindReal(TInt aParameterIndex, TReal aParameterValue);

	IMPORT_C TInt BindText(TInt aParameterIndex, const TDesC& aParameterText);

	IMPORT_C TInt BindBinary(TInt aParameterIndex, const TDesC8& aParameterData);

	IMPORT_C TInt BindZeroBlob(TInt aParameterIndex, TInt aBlobSize);

	IMPORT_C TBool IsNull(TInt aColumnIndex) const;

	IMPORT_C TInt ColumnInt(TInt aColumnIndex) const;

	IMPORT_C TInt64 ColumnInt64(TInt aColumnIndex) const;

	IMPORT_C TReal ColumnReal(TInt aColumnIndex) const;

	IMPORT_C TPtrC ColumnTextL(TInt aColumnIndex) const;

	IMPORT_C TInt ColumnText(TInt aColumnIndex, TPtrC& aPtr) const;

	IMPORT_C TInt ColumnText(TInt aColumnIndex, TDes& aDest) const;

	IMPORT_C TPtrC8 ColumnBinaryL(TInt aColumnIndex) const;

	IMPORT_C TInt ColumnBinary(TInt aColumnIndex, TPtrC8& aPtr) const;

	IMPORT_C TInt ColumnBinary(TInt aColumnIndex, TDes8& aDest) const;

	IMPORT_C TInt ColumnName(TInt aColumnIndex, TPtrC& aNameDest);

	IMPORT_C TInt ParameterName(TInt aParameterIndex, TPtrC& aNameDest);

	IMPORT_C TInt ParamName(TInt aParameterIndex, TPtrC& aNameDest);

private:

	CSqlStatementImpl& Impl() const;

private:

	CSqlStatementImpl* 	iImpl;

	};

/**

The read stream interface.

The class is used for reading the content of a column containing either 

binary data or text data.

The class derives from RReadStream, which means that all RReadStream public

member functions and predefined stream operators \>\> can be used to deal

with column data.

If the blob or text data is over 2Mb in size then it is recommended that the 

RSqlBlobReadStream or TSqlBlob class is used instead. These classes provide 

a more RAM-efficient way of reading large amounts of blob or text data from

a database.

The following two cases are typical:

CASE 1 - processing large binary column data.

@code

RSqlDatabase db;

<open/create "db" object>;

RSqlStatement stmt;

<prepare "stmt" object>;

TInt rc = stmt.Next();

if(rc == KSqlAtRow)

	{

	RSqlColumnReadStream colStream;

	CleanupClosePushL(colStream);

	User::LeaveIfError(colStream.ColumnBinary(stmt, <column_number>));

	TInt size = stmt.ColumnSize(<column_number>);

	//read the column data in a buffer ("buf" variable).

	//(or the column data can be retrieved in a smaller portions)

	colStream.ReadL(buf, size);

	//Close the stream

	CleanupStack::PopAndDestroy(&colStream);

	}

else

	{

	...

	}

@endcode

CASE 2 - processing large text column data.

@code

RSqlDatabase db;

<open/create "db" object>;

RSqlStatement stmt;

<prepare "stmt" object>;

TInt rc = stmt.Next();

if(rc == KSqlAtRow)

	{

	RSqlColumnReadStream colStream;

	CleanupClosePushL(colStream);

	User::LeaveIfError(colStream.ColumnText(stmt, <column_number>));

	TInt size = stmt.ColumnSize(<column_number>);

	//read the column data in a buffer ("buf" variable).

	//(or the column data can be retrieved in a smaller portions)

	colStream.ReadL(buf, size);

	//Close the stream

	CleanupStack::PopAndDestroy(&colStream);

	}

else

	{

	...

	}

@endcode

@see RSqlBlobReadStream

@see TSqlBlob

@publishedAll

@released

*/

class RSqlColumnReadStream : public RReadStream

	{

public:	

	IMPORT_C TInt ColumnText(RSqlStatement& aStmt, TInt aColumnIndex);

	IMPORT_C TInt ColumnBinary(RSqlStatement& aStmt, TInt aColumnIndex);

	IMPORT_C void ColumnTextL(RSqlStatement& aStmt, TInt aColumnIndex);

	IMPORT_C void ColumnBinaryL(RSqlStatement& aStmt, TInt aColumnIndex);

	};

/**

The write stream interface.

The class is used to set binary data or text data into a parameter. 

This is a also known as binding a parameter.

The class derives from RWriteStream, which means that all RWriteStream public

member functions and predefined stream operators \<\< can be used to deal with

the parameter data.

If the blob or text data is over 2Mb in size then it is recommended that the 

RSqlBlobWriteStream or TSqlBlob class is used instead. These classes provide 

a more RAM-efficient way of writing large amounts of blob or text data to

a database.

The following two cases are typical:

CASE 1 - binding a large binary parameter.

@code

RSqlDatabase db;

<open/create "db" object>;

RSqlStatement stmt;

<prepare "stmt" object>;//The SQL statement references large binary parameter

RSqlParamWriteStream paramStream;

CleanupClosePushL(paramStream);

User::LeaveIfError(paramStream.BindBinary(stmt, <parameter_number>));