// Copyright (c) 2005-2010 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:

 // NTT DOCOMO, INC - Fix for defect 1915 "SQL server panics when using long column type strings"

 //

 // Description:

 //

 #ifndef __SQLSRVSTATEMENT_H__

 #define __SQLSRVSTATEMENT_H__

 #include <e32base.h>

 #include <s32mem.h>					//TBufBuf

 #include "SqlUtil.h"				//Sql2OsErrCode()

 #include "SqlBufFlat.h"				//RSqlBufFlat

 #include "SqlSrvStatementUtil.h"	//Global SQL statement related functions

 //Forward declarations

 struct sqlite3;

 struct sqlite3_stmt;

 class RWriteStream;

 class CSqlSrvStatement;

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

 //////////////////////                HSqlSrvStmtParamBuf              //////////////////////////////////

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

 /**

 Buffer for storing binary/text parameter values (an input from client side write stream objects or bound text/binary parameters).

 Every CSqlSrvStatement object maintains a collection of HSqlSrvStmtParamBuf objects.

 Please, note that:

  - The life-time of the HSqlSrvStmtParamBuf objects is controlled by a set of flags:

 	 = iStatementFinalized - False by default, set to true if the bound statement has been finalized.

 	                         When DoRelease() is called, the method checks this poreperty and if the statement has been finalized,

 	                         then obviously no more parameter binding operations can be performed and it is safe to destroy the 

 	                         current HSqlSrvStmtParamBuf object. Otherwise the HSqlSrvStmtParamBuf object won't be destroyed, 

 	                         it will be marked as "dead" - see the "iAlive" property;

 	 = iAlive			   - True by default, set to false by the DoRelease() call, if the object cannot be destroyed because 

 	 					     the bound statement is not finalized yet;

 	 = iBufType		       - EBufIpcStream if the current HSqlSrvStmtParamBuf object is an IPC stream buffer, EBufSimpleBind 

 	 						 if the  object holds a parameter value, that has been bound not using an IPC stream. This property 

 	 						 is checked when the bound statement gets finalized - inside the NotifyStatementFinalized() function. 

 	 						 If the current object is not an IPC stream buffer, then it is safe to destroy the object because

 	 						 the bound statement is finalized;

    All these checks allow keeping the buffer object alive when it is needed and code like the code bellow should work without problems:

 @code

 	RSqlStatement stmt;			//Prepare a statement with a binary/text parameter

 	....

 	RSqlParamWriteStream strm;

 	strm.BindBinary(stmt,...);	//Use a stream object to bind the parameter value

 	strm.WriteL(...);

 	strm.CommitL();				//The stream commit call will bind the streamed parameter value to the statement

 	strm.Close();				//The stream close operation should not destroy the HSqlSrvStmtParamBuf object, because the parameter

 								//value is kept in the buffer, and when that value was bound to the statement, the

 								//SQLITE_STATIC constant was used, which means - SQLite won't make a copy of the parameter value,

 								//SQLite will keep a pointer to the parameter value and use it for the Exec() operation.

 	stmt.Exec();				//At this point the SQLite library should be able to get the parameter data and use it.

 @endcode

  - Another reason for keeping the HSqlSrvStmtParamBuf object alive during the life-time of the CSqlSrvStatement object is that

    the RSqlStatement::Reset() call should not destroy the buffer. The client should be able to resuse

    the buffered parameter data for the next RSqlStatement::Exec() call. For example:

 @code

 	RSqlStatement stmt;			//Prepare a statement with two  binary parameters

 	....

 	RSqlParamWriteStream strm1, strm2;

 	strm1.BindBinary(stmt,...);	//Use a stream object to bind the 1st parameter value

 	strm1.WriteL(...);

 	strm1.CommitL();			

 	strm1.Close();				

 	strm2.BindBinary(stmt,...);	//Use a stream object to bind the 2nd parameter value

 	strm2.WriteL(...);

 	strm2.CommitL();			

 	strm2.Close();				

 	stmt.Exec();				//Do the operation using the bound parameter values

 	stmt.Reset();				//This call should not destroy the HSqlSrvStmtParamBuf objects that keep the parameter values

 	strm2.BindBinary(stmt,...);	//Use a stream object to bind the 2nd parameter value

 	strm2.WriteL(...);

 	strm2.CommitL();			

 	strm2.Close();				

 	stmt.Exec();				//Do the operation using the bound parameter values. 

 								//The operation should be able to use the old 1st parameter value without any problems,

 								//and also the new 2nd parameter value.

 @endcode

  - The HSqlSrvStmtParamBuf object can be synch-ed just once. The reason for that is to prevent the double commit-s, 

    that will occur as a result of MStreamBuf::Close() calls on the client side, where the Close() method will try to sync the buffer.

    The single sync will prevent the SQL server from crashing, if the order of the RSqlStatement::Close() and

    RSqlParamWriteStream::Close() calls is reversed, e.g.:

 @code

 	RSqlStatement stmt;		

 	....

 	RSqlParamWriteStream strm;

 	strm.BindBinary(stmt,...);

 	strm.WriteL(...);

 	strm.CommitL();		

 	stmt.Exec();

 	stmt.Close();

 	strm.Close();		

 @endcode

  - For BC reasons, even though the HSqlSrvStmtParamBuf object can be synch-ed just once (the operation is controlled by the iSynchDone

    flag), the client side still will be able to update the buffer content, because the related HIpcStream stream object keeps a copy

    of the buffer's base address. Since the parameter is bound using the SQLITE_STATIC constant (SQLite won't make a copy of the 

    parameter value), at the moment of the Exec() call, SQLite will use the give pointer to the parameter value and will pick up

    the updated buffer even without a commit call;

 @endcode

  - The iSynchDone flag controls the number of buffer commit operations. It is false by default, 

    set to true by the DoSynchL() call. The HSqlSrvStmtParamBuf object can be synch-ed just once, because DoSynchL() 

    calls sqlite3_bind_text/binary() and the expectation is that the whole buffer with the parameter data is ready for binding;

    If the buffer is not commited by calling DoSynchL(), the buffer still will be commited by the DoSynchL() call performed from

    MStreamBuf::Close(). But in a case of a sync failure, no error will be reported to the client side;

 @see HIpcStream 

 @see CSqlSrvStatement

 @internalComponent

 */

 NONSHARABLE_CLASS(HSqlSrvStmtParamBuf) : public TBufBuf

 	{

 public:

 	enum TDataType {EBinary, EText16};

 	enum TBufType {EBufSimpleBind, EBufIpcStream};

 	static inline HSqlSrvStmtParamBuf* NewL(CSqlSrvStatement& aStatement, TInt aParamIndex, HSqlSrvStmtParamBuf::TDataType aDataType, 

 										    HSqlSrvStmtParamBuf::TBufType aBufType);

 	inline void Reset(HSqlSrvStmtParamBuf::TDataType aDataType, HSqlSrvStmtParamBuf::TBufType aBufType);

 	inline const TPtrC8 SetDataL(const TDesC8& aData);

 	inline const TPtrC8 Data() const;

 	inline HSqlSrvStmtParamBuf::TDataType DataType() const;

 	void NotifyStatementFinalized();

 	inline TInt ParamIndex() const;

 private:

 	inline HSqlSrvStmtParamBuf(CSqlSrvStatement& aStatement, TInt aParamIndex, HSqlSrvStmtParamBuf::TDataType aDataType, 

 							   HSqlSrvStmtParamBuf::TBufType aBufType);

 	virtual ~HSqlSrvStmtParamBuf();

 	inline void ConstructL();

 	virtual void DoSynchL();

 	virtual void DoRelease();

 private:

 	enum {EExpandSize = 512};

 	CSqlSrvStatement&	iStatement;			//The bound CSqlSrvStatement object

 	CBufFlat* 			iBuf;				//Parameter buffer - not owned by HSqlSrvStmtParamBuf

 	TInt 				iParamIndex;		//The parameter index

 	TBool				iStatementFinalized;//True if the bound statement object has been finalized

 	TBool				iAlive;				//True if DoRelease() has not been called yet

 	HSqlSrvStmtParamBuf::TDataType iDataType;//The parameter type

 	HSqlSrvStmtParamBuf::TBufType iBufType;	//IPC stream buf or a simple "bind param" buf

 	TBool				iSynchDone;			//True if the buffer data has been bound to the statement

 	};

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

 //////////////////                CSqlSrvStatement                	   //////////////////////////////////

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

 /**

 SQL statement handle.

 CSqlSrvStatement is a server side class which processes the client side requests for:

  - preparing 16-bit and 8-bit SQL statements;

  - executing prepared SQL statement;

  - retrieving parameter names and column names;

  - binding SQL parameters;

  - retrieving column values;

  - reseting the prepared SQL statement;

  - moving the cursor to the next record;

 @see CSqlSrvStatement::NewLC()

 @see CSqlSrvStatement::NewLC()

 @see CSqlSrvStatement::BindL()

 @see CSqlSrvStatement::Next()

 @see CSqlSrvStatement::Reset()

 @see CSqlSrvStatement::Exec()

 @see CSqlSrvStatement::ColumnNamesL()

 @see CSqlSrvStatement::ParamNamesL()

 @see CSqlSrvStatement::ColumnValuesL()

 @see CSqlSrvStatement::ColumnSource()

 @see HSqlSrvStmtParamBuf

 @internalComponent

 */

 NONSHARABLE_CLASS(CSqlSrvStatement) : public CBase

 	{

 public:

 	static CSqlSrvStatement* NewLC(sqlite3* aDbHandle, const TDesC16& aSqlStmt, TInt& aColumnCount, TInt& aParamCount);

 	static CSqlSrvStatement* NewLC(sqlite3* aDbHandle, const TDesC8& aSqlStmt, TInt& aColumnCount, TInt& aParamCount);

 	virtual ~CSqlSrvStatement();

 	void BindL(const RSqlBufFlat& aParamBuf);	

 	inline TInt Next();

 	inline TInt Reset();

 	inline TInt Exec();

 	inline const RSqlBufFlat& BufFlatL(TSqlBufFlatType aWhat) const;

 	const RSqlBufFlat& ColumnNamesL();

 	const RSqlBufFlat& ParamNamesL();

 	const RSqlBufFlat& ColumnValuesL();

 	TInt ColumnSource(TInt aColumnIndex, TPtrC8& aColumnSource) const;

 	TInt ColumnInt(TInt aColIdx) const;

 	TInt64 ColumnInt64(TInt aColIdx) const;

 	TReal ColumnReal(TInt aColIdx) const;

 	TPtrC ColumnTextL(TInt aColIdx) const;

 	TPtrC8 ColumnBinary(TInt aColIdx) const;

 	const RSqlBufFlat& GetDeclColumnTypesL();

 	HSqlSrvStmtParamBuf* GetParamBufL(TInt aParamIndex, HSqlSrvStmtParamBuf::TDataType aDataType, HSqlSrvStmtParamBuf::TBufType aBufType);

 	void BindParamBufL(TInt aParamIndex);

 private:

 	inline CSqlSrvStatement();

 	inline void ConstructL(sqlite3* aDbHandle, const TDesC16& aSqlStmt);

 	inline void ConstructL(sqlite3* aDbHandle, const TDesC8& aSqlStmt);

 	void DoCommonConstructL();

 	void DestroyParamBufArray();

 	void ExtendParamBufArrayL(TInt aParamIndex);

 	TPtrC8 CopyAndStoreParamL(TInt aParamIndex, HSqlSrvStmtParamBuf::TDataType aDataType, const TDesC8& aParamValue);

 private:

 	sqlite3_stmt*		iStmtHandle;		//SQL statement handle

 	TInt 				iColumnCount;		

 	TInt 				iParamCount;		

 	TSqlBufFlatType		iBufFlatType;		//What is in iFlatBuf data member

 	RSqlBufFlat  		iBufFlat;			//Flat buffer used for: column names, parameter names, column values

 	RArray<HSqlSrvStmtParamBuf*> iParamBufArray;//An array with pointers to HSqlSrvStmtParamBuf buffers for the text/binary parameters

 	};

 #include "SqlSrvStatement.inl"

 #endif//__SQLSRVSTATEMENT_H__