// 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:

//

#include "SqlStatementImpl.h"		//CSqlStatementImpl

/////////////////////////////////////////////////////////////////////////////////////////////////////////////

/**

Initialises the pointer to the implementation object to NULL.

@capability None

*/

EXPORT_C RSqlStatement::RSqlStatement() :

	iImpl(NULL)

	{

	}

/**

Prepares the supplied 16-bit SQL statement for execution.

An RSqlStatement object can prepare and execute a parameterised SQL statement or

an SQL statement without parameters.

The function can only deal with one SQL statement at a time, i.e. if you

supply more than one SQL statement, each separated by a ";" character, then

the function returns an error.

Note that when the statement is to be used to retrieve or write blob or text data

that is over 2Mb in size then 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.

@param aDatabase     A reference to the RSqlDatabase object that represents 

                     the database for which the SQL statement is being prepared.

@param aSqlStmt      A string of 16-bit wide characters containing the

                     SQL statement to be prepared.

@return KErrNone,     the SQL statement has been prepared for execution successfully;

        KErrNoMemory, an out of memory condition has occurred;

        KErrArgument, the SQL statement is invalid, for example, the supplied

                      string contains more than one SQL statement, or it

                      contains an empty SQL statement.

                      Note that database specific errors categorised as ESqlDbError

                      can also be returned;

        KSqlErrGeneral, a syntax error has occurred - text describing the problem

                        can be obtained by calling 	RSqlDatabase::LastErrorMessage().

		KErrPermissionDenied, the calling application does not satisfy the relevant database security policies.

                      Note that database specific errors categorised as ESqlDbError, and

                      other system-wide error codes may also be returned.

@capability None, if current RSqlStatement object represents a handle which operates on a non-secure database;

            RSqlSecurityPolicy::ESchemaPolicy database policy type, if the SQL statement modifies a secure database schema; 

            RSqlSecurityPolicy::EReadPolicy or 

            RSqlSecurityPolicy::ESchemaPolicy database policy type, if the SQL statement reads from a secure database; 

            RSqlSecurityPolicy::EWritePolicy or

            RSqlSecurityPolicy::ESchemaPolicy database policy type, if the SQL statement writes to a secure database;

@see TSqlRetCodeClass::ESqlDbError

@see RSqlDatabase

@see RSqlDatabase::LastErrorMessage()

@see RSqlSecurityPolicy

@see RSqlSecurityPolicy::TPolicyType

@see RSqlBlobReadStream

@see RSqlBlobWriteStream

@see TSqlBlob

*/	

EXPORT_C TInt RSqlStatement::Prepare(RSqlDatabase& aDatabase, const TDesC& aSqlStmt)

	{

	SQLUTRACE_PROFILER(this);

	SYMBIAN_TRACE_SQL_EVENTS_ONLY(UTF::Printf(UTF::TTraceContext(UTF::EInternals), KHexStrParam16, &aDatabase, &aSqlStmt));

	return CSqlStatementImpl::New(iImpl, aDatabase.Impl(), aSqlStmt);

	}

/**

Prepares the supplied 8-bit SQL statement for execution.

An RSqlStatement object can prepare and execute a parameterised SQL statement or

an SQL statement without parameters.

The function can only deal with one SQL statement at a time, i.e. if you

supply more than one SQL statement, each separated by a ";" character, then

the function returns an error.

Note that when the statement is to be used to retrieve or write blob or text data

that is over 2Mb in size then 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.

@param aDatabase     A reference to the RSqlDatabase object that represents 

                     the database for which the SQL statement is being prepared.

@param aSqlStmt      A string of 8-bit wide characters containing the

                     SQL statement to be prepared.

@return KErrNone,     the SQL statement has been prepared for execution successfully;

        KErrNoMemory, an out of memory condition has occurred;

        KErrArgument, the SQL statement is invalid, for example, the supplied

                      string contains more than one SQL statement, or it

                      contains an empty SQL statement.

                      Note that database specific errors categorised as ESqlDbError

                      can also be returned;

        KSqlErrGeneral, a syntax error has occurred - text describing the problem

                        can be obtained by calling 	RSqlDatabase::LastErrorMessage().

		KErrPermissionDenied, the calling application does not satisfy the relevant database security policies.

                      Note that database specific errors categorised as ESqlDbError, and

                      other system-wide error codes may also be returned.

@capability None, if current RSqlStatement object represents a handle which operates on a non-secure database;

            RSqlSecurityPolicy::ESchemaPolicy database policy type, if the SQL statement modifies a secure database schema; 

            RSqlSecurityPolicy::EReadPolicy or 

            RSqlSecurityPolicy::ESchemaPolicy database policy type, if the SQL statement reads from a secure database; 

            RSqlSecurityPolicy::EWritePolicy or

            RSqlSecurityPolicy::ESchemaPolicy database policy type, if the SQL statement writes to a secure database;

@see TSqlRetCodeClass::ESqlDbError

@see RSqlDatabase

@see RSqlDatabase::LastErrorMessage()

@see RSqlSecurityPolicy

@see RSqlSecurityPolicy::TPolicyType

@see RSqlBlobReadStream

@see RSqlBlobWriteStream

@see TSqlBlob

*/	

EXPORT_C TInt RSqlStatement::Prepare(RSqlDatabase& aDatabase, const TDesC8& aSqlStmt)

	{

	SQLUTRACE_PROFILER(this);

	SYMBIAN_TRACE_SQL_EVENTS_ONLY(UTF::Printf(UTF::TTraceContext(UTF::EInternals), KHexStrParam, 

			&aDatabase, &aSqlStmt));

	return CSqlStatementImpl::New(iImpl, aDatabase.Impl(), aSqlStmt);

	}

/**

Prepares the supplied 16-bit SQL statement for execution.

An RSqlStatement object can prepare and execute a parameterised SQL statement or

an SQL statement without parameters.

The function can only deal with one SQL statement at a time, i.e. if you

supply more than one SQL statement, each separated by a ";" character, then

the function returns an error.

Note that when the statement is to be used to retrieve or write blob or text data

that is over 2Mb in size then 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.

@param aDatabase     A reference to the RSqlDatabase object that represents 

                     the database for which the SQL statement is being prepared.

@param aSqlStmt      A string of 16-bit wide characters containing the

                     SQL statement to be prepared.

@leave  KErrNoMemory, an out of memory condition has occurred;

        KErrArgument, the SQL statement is invalid, for example, the supplied

                      string contains more than one SQL statement, or it

                      contains an empty SQL statement.

                      Note that database specific errors categorised as ESqlDbError

                      can also be returned;

        KSqlErrGeneral, a syntax error has occurred - text describing the problem

                        can be obtained by calling 	RSqlDatabase::LastErrorMessage().

		KErrPermissionDenied, the calling application does not satisfy the relevant database security policies.

                      Note that the function may leave with database specific errors categorised as ESqlDbError and

                      other system-wide error codes.

@capability None, if current RSqlStatement object represents a handle which operates on a non-secure database;

            RSqlSecurityPolicy::ESchemaPolicy database policy type, if the SQL statement modifies a secure database schema; 

            RSqlSecurityPolicy::EReadPolicy or 

            RSqlSecurityPolicy::ESchemaPolicy database policy type, if the SQL statement reads from a secure database; 

            RSqlSecurityPolicy::EWritePolicy or

            RSqlSecurityPolicy::ESchemaPolicy database policy type, if the SQL statement writes to a secure database;

@see TSqlRetCodeClass::ESqlDbError

@see RSqlDatabase

@see RSqlDatabase::LastErrorMessage()

@see RSqlSecurityPolicy

@see RSqlSecurityPolicy::TPolicyType

@see RSqlBlobReadStream

@see RSqlBlobWriteStream

@see TSqlBlob

*/

EXPORT_C void RSqlStatement::PrepareL(RSqlDatabase& aDatabase, const TDesC& aSqlStmt)

	{

	SQLUTRACE_PROFILER(this);

	SYMBIAN_TRACE_SQL_EVENTS_ONLY(UTF::Printf(UTF::TTraceContext(UTF::EInternals), KHexStrParam16, 

			&aDatabase, &aSqlStmt));

	__SQLLEAVE_IF_ERROR(Prepare(aDatabase, aSqlStmt));

	}

/**

Prepares the supplied 8-bit SQL statement for execution.

An RSqlStatement object can prepare and execute a parameterised SQL statement or

an SQL statement without parameters.

The function can only deal with one SQL statement at a time, i.e. if you

supply more than one SQL statement, each separated by a ";" character, then

the function returns an error.

Note that when the statement is to be used to retrieve or write blob or text data

that is over 2Mb in size then 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.

@param aDatabase     A reference to the RSqlDatabase object that represents 

                     the database for which the SQL statement is being prepared.

@param aSqlStmt      A string of 8-bit wide characters containing the

                     SQL statement to be prepared.

@leave  KErrNoMemory, an out of memory condition has occurred;

        KErrArgument, the SQL statement is invalid, for example, the supplied

                      string contains more than one SQL statement, or it

                      contains an empty SQL statement.

                      Note that database specific errors categorised as ESqlDbError

                      can also be returned;

        KSqlErrGeneral, a syntax error has occurred - text describing the problem

                        can be obtained by calling 	RSqlDatabase::LastErrorMessage().

		KErrPermissionDenied, the calling application does not satisfy the relevant database security policies.

                      Note that the function may leave with database specific errors categorised as ESqlDbError and

                      other system-wide error codes.

@capability None, if current RSqlStatement object represents a handle which operates on a non-secure database;

            RSqlSecurityPolicy::ESchemaPolicy database policy type, if the SQL statement modifies a secure database schema; 

            RSqlSecurityPolicy::EReadPolicy or 

            RSqlSecurityPolicy::ESchemaPolicy database policy type, if the SQL statement reads from a secure database; 

            RSqlSecurityPolicy::EWritePolicy or

            RSqlSecurityPolicy::ESchemaPolicy database policy type, if the SQL statement writes to a secure database;

@see TSqlRetCodeClass::ESqlDbError

@see RSqlDatabase

@see RSqlDatabase::LastErrorMessage()

@see RSqlSecurityPolicy

@see RSqlSecurityPolicy::TPolicyType

@see RSqlBlobReadStream

@see RSqlBlobWriteStream

@see TSqlBlob

*/

EXPORT_C void RSqlStatement::PrepareL(RSqlDatabase& aDatabase, const TDesC8& aSqlStmt)

	{

	SQLUTRACE_PROFILER(this);

	SYMBIAN_TRACE_SQL_EVENTS_ONLY(UTF::Printf(UTF::TTraceContext(UTF::EInternals), KHexStrParam, 

			&aDatabase, &aSqlStmt));

	__SQLLEAVE_IF_ERROR(Prepare(aDatabase, aSqlStmt));

	}

/**

Closes this SQL statement object.

The function frees memory and any allocated resources.

@see RSqlStatement::Prepare()

@capability None

*/	

EXPORT_C void RSqlStatement::Close()

	{

	SQLUTRACE_PROFILER(this);

	delete iImpl;

	iImpl = NULL;

	}

/**

Tests whether the SQL statement points to a valid record.

@return True, if the SQL statement points to a valid record, false otherwise.

@capability None

*/

EXPORT_C TBool RSqlStatement::AtRow() const

	{

	SQLUTRACE_PROFILER(this);

	return Impl().AtRow();

	}

/**

Resets the prepared SQL statement to its initial state and makes it ready to be

executed again.

Any SQL statement parameters that had values bound to them, retain their values.

If this object processes a parameterised SQL statement, then the parameter

values can be bound after the call to Reset().

If the call to this function fails because of a database-specific type error 

(i.e. the error is categorised as of type ESqlDbError), then a textual description of

the error can be obtained calling RSqlDatabase::LastErrorMessage().

Usage pattern 1:

@code

RSqlStatement stmt;

TInt err = stmt.Prepare(<database>, <SQL statement>);

while(<condition>)

	{

	err = stmt.Bind<parameter type>(<parameter index>, <value>);

	...

	err = stmt.Exec();

	....

	err = stmt.Reset();

	}

stmt.Close();

@endcode

Usage pattern 2:

@code

RSqlStatement stmt;

TInt err = stmt.Prepare(<database>, <SQL statement>);

while(<condition>)

	{

	err = stmt.Bind<parameter type>(<parameter index>, <value>);

	...

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

		{

		....

		}

	err = stmt.Reset();

	}

stmt.Close();

@endcode

@return KErrNone, the reset operation has completed successfully;			

        KSqlErrStmtExpired, the SQL statement has expired (if new functions or

                            collating sequences have been registered or if an

                            authorizer function has been added or changed)

@see TSqlRetCodeClass::ESqlDbError

@see RSqlDatabase::LastErrorMessage()

@capability None

*/	

EXPORT_C TInt RSqlStatement::Reset()

	{

	SQLUTRACE_PROFILER(this);

	return Impl().Reset();

	}

/**

Executes the prepared DDL/DML SQL statement. 

The function is very useful when the SQL statement contains parameters, because

the statement can be prepared once using RSqlStatement::Prepare(), and then

bound and executed many times.

Note that:

- parameter values must be bound before calling Exec().

- SQL statements that do not have parameters should use RSqlDatabase::Exec() instead.

If the call to this function fails because of a database-specific type error 

(i.e. the error is categorised as of type ESqlDbError), then a textual description of

the error can be obtained calling RSqlDatabase::LastErrorMessage().

Usage pattern:

@code

RSqlStatement stmt;

TInt err = stmt.Prepare(<database>, <SQL statement>);

while(<condition>)

	{

	err = stmt.Bind<parameter type>(<parameter index>, <value>);

	...

	err = stmt.Exec();

	....

	err = stmt.Reset();

	}

stmt.Close();

@endcode

@return >=0, The operation has completed successfully. The number of database rows that were 

			 changed/inserted/deleted by the most recently completed DDL/DML sql statement.

			 Exception: If the executed statement is "DELETE FROM <table>", then the function returns 0 

			 if the operation has completed successfully (disregarding the number of the deleted rows);

        KSqlErrStmtExpired, the SQL statement has expired (if new functions or

                            collating sequences have been registered or if an

                            authorizer function has been added or changed);

    	KErrDiskFull, There is no available disk space to complete the operation. If the executed statement is a DELETE

    			  statement, try to use the reserved disk space (if there is a reserved disk space) to complete the operation.

    			  In all other cases the statement and database connection should be closed and some disk space freed 

    			  before reopening the database; 

        KErrNoMemory, an out of memory condition has occurred - the statement

                      will be reset.

                      Note that database specific errors categorised as ESqlDbError

                      can also be returned.

@see TSqlRetCodeClass::ESqlDbError

@see RSqlStatement::Prepare()

@see RSqlDatabase::Exec()

@see RSqlDatabase::LastErrorMessage()

@capability None

*/	

EXPORT_C TInt RSqlStatement::Exec()

	{

	SQLUTRACE_PROFILER(this);

	return Impl().Exec();

	}

/**

Executes the prepared DDL/DML SQL statement asynchronously to allow client to avoid being blocked 

by server activity.

No other operations can be performed on current RSqlStatement object 

until the asynchronous operation completes.

The function is very useful when the SQL statement contains parameters, because

the statement can be prepared once using RSqlStatement::Prepare(), and then

bound and executed many times.

Note that:

- parameter values must be bound before calling Exec().

- SQL statements that do not have parameters should use RSqlDatabase::Exec() instead.

If the call to this function fails because of a database-specific type error 

(i.e. the error is categorised as of type ESqlDbError), then a textual description of

the error can be obtained calling RSqlDatabase::LastErrorMessage().

@param aStatus Completion status of asynchronous request, one of the following:

	>=0, The operation has completed successfully. The number of database rows that were 

		changed/inserted/deleted by the most recently completed DDL/DML sql statement.

		Exception: If the executed statement is "DELETE FROM <table>", then the function returns 0 

		if the operation has completed successfully (disregarding the number of the deleted rows);

	KSqlErrStmtExpired, the SQL statement has expired (if new functions or 

						collating sequences have been registered or if an 

						authorizer function has been added or changed);

	KErrDiskFull, There is no available disk space to complete the operation. If the executed statement is a DELETE 

				statement, try to use the reserved disk space (if there is a reserved disk space) 

				to complete the operation.

				In all other cases the statement and database connection should be closed and some disk space freed 

				before reopening the database; 

	KErrNoMemory, an out of memory condition has occurred - the statement 

	will be reset.

	Note that aStatus may be set with database specific errors categorised as ESqlDbError,

	and other system-wide error codes.

@see TSqlRetCodeClass::ESqlDbError

@see RSqlStatement::Prepare()

@see RSqlDatabase::Exec()

@see RSqlDatabase::LastErrorMessage()

@capability None

*/	

EXPORT_C void RSqlStatement::Exec(TRequestStatus& aStatus)

	{

	SQLUTRACE_PROFILER(this);

	Impl().Exec(aStatus);

	}

/**

Retrieves a record.

If the prepared SQL statement is a "SELECT" statement, and is expected to

return a set of records, then this function can be used to retrieve that record data.

If the SQL statement contains parameters, then their values must be bound before

this function is called.

If the call to this function completes successfully, i.e. it returns

with KSqlAtRow, then this RSqlStatement object contains the record data, and 

this data will remain valid for access until another call is made to any

RSqlStatement function.

The record data can be accessed using the following functions:

- RSqlStatement::ColumnType()

- RSqlStatement::ColumnSize()

- RSqlStatement::ColumnInt()

- RSqlStatement::ColumnInt64()

- RSqlStatement::ColumnReal()

- RSqlStatement::ColumnTextL()

- RSqlStatement::ColumnText()

- RSqlStatement::ColumnBinary()

- RSqlStatement::ColumnBinaryL()

Note that if this call to Next() fails, as indicated by a return code value

other than KSqlAtRow, then calls to these RSqlStatement::Column...() functions

will raise a panic.

@return KSqlAtRow,      the record data is ready for processing by the caller;

        KSqlAtEnd,      there is no more record data;

        KSqlErrBusy,    the database file is locked;

        KErrNoMemory,   an out of memory condition has occurred - the statement

                        will be reset;

        KSqlErrGeneral, a run-time error has occured - this function must not

                        be called again;        

        KSqlErrMisuse,  this function has been called after a previous call

                        returned KSqlAtEnd or KSqlErrGeneral.

        KSqlErrStmtExpired, the SQL statement has expired (if new functions or

                            collating sequences have been registered or if an

                            authorizer function has been added or changed);

@capability None

*/	

EXPORT_C TInt RSqlStatement::Next()

	{

	SQLUTRACE_PROFILER(this);

	return Impl().Next();

	}

/**

Gets the index (starting from 0) of the parameter with the given name.

The function does a case insensitive parameter name search.

For example, if the parameter name is ":Prm", then the ":" prefix cannot

be omitted when you call ParameterIndex().

This function can be called at any time after the SQL statement has been prepared.