1.1 --- /dev/null Thu Jan 01 00:00:00 1970 +0000
1.2 +++ b/os/persistentdata/persistentstorage/sql/SRC/Server/SqlSrvStatement.h Fri Jun 15 03:10:57 2012 +0200
1.3 @@ -0,0 +1,256 @@
1.4 +// Copyright (c) 2005-2010 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 +// NTT DOCOMO, INC - Fix for defect 1915 "SQL server panics when using long column type strings"
1.16 +//
1.17 +// Description:
1.18 +//
1.19 +
1.20 +#ifndef __SQLSRVSTATEMENT_H__
1.21 +#define __SQLSRVSTATEMENT_H__
1.22 +
1.23 +#include <e32base.h>
1.24 +#include <s32mem.h> //TBufBuf
1.25 +#include "SqlUtil.h" //Sql2OsErrCode()
1.26 +#include "SqlBufFlat.h" //RSqlBufFlat
1.27 +#include "SqlSrvStatementUtil.h" //Global SQL statement related functions
1.28 +
1.29 +//Forward declarations
1.30 +struct sqlite3;
1.31 +struct sqlite3_stmt;
1.32 +class RWriteStream;
1.33 +class CSqlSrvStatement;
1.34 +
1.35 +/////////////////////////////////////////////////////////////////////////////////////////////////////////
1.36 +////////////////////// HSqlSrvStmtParamBuf //////////////////////////////////
1.37 +/////////////////////////////////////////////////////////////////////////////////////////////////////////
1.38 +
1.39 +/**
1.40 +Buffer for storing binary/text parameter values (an input from client side write stream objects or bound text/binary parameters).
1.41 +Every CSqlSrvStatement object maintains a collection of HSqlSrvStmtParamBuf objects.
1.42 +
1.43 +Please, note that:
1.44 +
1.45 + - The life-time of the HSqlSrvStmtParamBuf objects is controlled by a set of flags:
1.46 + = iStatementFinalized - False by default, set to true if the bound statement has been finalized.
1.47 + When DoRelease() is called, the method checks this poreperty and if the statement has been finalized,
1.48 + then obviously no more parameter binding operations can be performed and it is safe to destroy the
1.49 + current HSqlSrvStmtParamBuf object. Otherwise the HSqlSrvStmtParamBuf object won't be destroyed,
1.50 + it will be marked as "dead" - see the "iAlive" property;
1.51 + = iAlive - True by default, set to false by the DoRelease() call, if the object cannot be destroyed because
1.52 + the bound statement is not finalized yet;
1.53 + = iBufType - EBufIpcStream if the current HSqlSrvStmtParamBuf object is an IPC stream buffer, EBufSimpleBind
1.54 + if the object holds a parameter value, that has been bound not using an IPC stream. This property
1.55 + is checked when the bound statement gets finalized - inside the NotifyStatementFinalized() function.
1.56 + If the current object is not an IPC stream buffer, then it is safe to destroy the object because
1.57 + the bound statement is finalized;
1.58 +
1.59 + All these checks allow keeping the buffer object alive when it is needed and code like the code bellow should work without problems:
1.60 +@code
1.61 + RSqlStatement stmt; //Prepare a statement with a binary/text parameter
1.62 + ....
1.63 + RSqlParamWriteStream strm;
1.64 + strm.BindBinary(stmt,...); //Use a stream object to bind the parameter value
1.65 + strm.WriteL(...);
1.66 + strm.CommitL(); //The stream commit call will bind the streamed parameter value to the statement
1.67 + strm.Close(); //The stream close operation should not destroy the HSqlSrvStmtParamBuf object, because the parameter
1.68 + //value is kept in the buffer, and when that value was bound to the statement, the
1.69 + //SQLITE_STATIC constant was used, which means - SQLite won't make a copy of the parameter value,
1.70 + //SQLite will keep a pointer to the parameter value and use it for the Exec() operation.
1.71 + stmt.Exec(); //At this point the SQLite library should be able to get the parameter data and use it.
1.72 +@endcode
1.73 +
1.74 + - Another reason for keeping the HSqlSrvStmtParamBuf object alive during the life-time of the CSqlSrvStatement object is that
1.75 + the RSqlStatement::Reset() call should not destroy the buffer. The client should be able to resuse
1.76 + the buffered parameter data for the next RSqlStatement::Exec() call. For example:
1.77 +@code
1.78 + RSqlStatement stmt; //Prepare a statement with two binary parameters
1.79 + ....
1.80 + RSqlParamWriteStream strm1, strm2;
1.81 +
1.82 + strm1.BindBinary(stmt,...); //Use a stream object to bind the 1st parameter value
1.83 + strm1.WriteL(...);
1.84 + strm1.CommitL();
1.85 + strm1.Close();
1.86 +
1.87 + strm2.BindBinary(stmt,...); //Use a stream object to bind the 2nd parameter value
1.88 + strm2.WriteL(...);
1.89 + strm2.CommitL();
1.90 + strm2.Close();
1.91 +
1.92 + stmt.Exec(); //Do the operation using the bound parameter values
1.93 + stmt.Reset(); //This call should not destroy the HSqlSrvStmtParamBuf objects that keep the parameter values
1.94 +
1.95 + strm2.BindBinary(stmt,...); //Use a stream object to bind the 2nd parameter value
1.96 + strm2.WriteL(...);
1.97 + strm2.CommitL();
1.98 + strm2.Close();
1.99 +
1.100 + stmt.Exec(); //Do the operation using the bound parameter values.
1.101 + //The operation should be able to use the old 1st parameter value without any problems,
1.102 + //and also the new 2nd parameter value.
1.103 +@endcode
1.104 +
1.105 + - The HSqlSrvStmtParamBuf object can be synch-ed just once. The reason for that is to prevent the double commit-s,
1.106 + that will occur as a result of MStreamBuf::Close() calls on the client side, where the Close() method will try to sync the buffer.
1.107 + The single sync will prevent the SQL server from crashing, if the order of the RSqlStatement::Close() and
1.108 + RSqlParamWriteStream::Close() calls is reversed, e.g.:
1.109 +@code
1.110 + RSqlStatement stmt;
1.111 + ....
1.112 + RSqlParamWriteStream strm;
1.113 + strm.BindBinary(stmt,...);
1.114 + strm.WriteL(...);
1.115 + strm.CommitL();
1.116 + stmt.Exec();
1.117 + stmt.Close();
1.118 + strm.Close();
1.119 +@endcode
1.120 +
1.121 + - For BC reasons, even though the HSqlSrvStmtParamBuf object can be synch-ed just once (the operation is controlled by the iSynchDone
1.122 + flag), the client side still will be able to update the buffer content, because the related HIpcStream stream object keeps a copy
1.123 + of the buffer's base address. Since the parameter is bound using the SQLITE_STATIC constant (SQLite won't make a copy of the
1.124 + parameter value), at the moment of the Exec() call, SQLite will use the give pointer to the parameter value and will pick up
1.125 + the updated buffer even without a commit call;
1.126 +
1.127 +@endcode
1.128 +
1.129 + - The iSynchDone flag controls the number of buffer commit operations. It is false by default,
1.130 + set to true by the DoSynchL() call. The HSqlSrvStmtParamBuf object can be synch-ed just once, because DoSynchL()
1.131 + calls sqlite3_bind_text/binary() and the expectation is that the whole buffer with the parameter data is ready for binding;
1.132 + If the buffer is not commited by calling DoSynchL(), the buffer still will be commited by the DoSynchL() call performed from
1.133 + MStreamBuf::Close(). But in a case of a sync failure, no error will be reported to the client side;
1.134 +
1.135 +@see HIpcStream
1.136 +@see CSqlSrvStatement
1.137 +
1.138 +@internalComponent
1.139 +*/
1.140 +NONSHARABLE_CLASS(HSqlSrvStmtParamBuf) : public TBufBuf
1.141 + {
1.142 +public:
1.143 + enum TDataType {EBinary, EText16};
1.144 + enum TBufType {EBufSimpleBind, EBufIpcStream};
1.145 +
1.146 + static inline HSqlSrvStmtParamBuf* NewL(CSqlSrvStatement& aStatement, TInt aParamIndex, HSqlSrvStmtParamBuf::TDataType aDataType,
1.147 + HSqlSrvStmtParamBuf::TBufType aBufType);
1.148 + inline void Reset(HSqlSrvStmtParamBuf::TDataType aDataType, HSqlSrvStmtParamBuf::TBufType aBufType);
1.149 +
1.150 + inline const TPtrC8 SetDataL(const TDesC8& aData);
1.151 + inline const TPtrC8 Data() const;
1.152 + inline HSqlSrvStmtParamBuf::TDataType DataType() const;
1.153 +
1.154 + void NotifyStatementFinalized();
1.155 + inline TInt ParamIndex() const;
1.156 +
1.157 +private:
1.158 + inline HSqlSrvStmtParamBuf(CSqlSrvStatement& aStatement, TInt aParamIndex, HSqlSrvStmtParamBuf::TDataType aDataType,
1.159 + HSqlSrvStmtParamBuf::TBufType aBufType);
1.160 + virtual ~HSqlSrvStmtParamBuf();
1.161 + inline void ConstructL();
1.162 + virtual void DoSynchL();
1.163 + virtual void DoRelease();
1.164 +
1.165 +private:
1.166 + enum {EExpandSize = 512};
1.167 +
1.168 + CSqlSrvStatement& iStatement; //The bound CSqlSrvStatement object
1.169 + CBufFlat* iBuf; //Parameter buffer - not owned by HSqlSrvStmtParamBuf
1.170 + TInt iParamIndex; //The parameter index
1.171 + TBool iStatementFinalized;//True if the bound statement object has been finalized
1.172 + TBool iAlive; //True if DoRelease() has not been called yet
1.173 + HSqlSrvStmtParamBuf::TDataType iDataType;//The parameter type
1.174 + HSqlSrvStmtParamBuf::TBufType iBufType; //IPC stream buf or a simple "bind param" buf
1.175 + TBool iSynchDone; //True if the buffer data has been bound to the statement
1.176 + };
1.177 +
1.178 +/////////////////////////////////////////////////////////////////////////////////////////////////////////
1.179 +////////////////// CSqlSrvStatement //////////////////////////////////
1.180 +/////////////////////////////////////////////////////////////////////////////////////////////////////////
1.181 +
1.182 +/**
1.183 +SQL statement handle.
1.184 +
1.185 +CSqlSrvStatement is a server side class which processes the client side requests for:
1.186 + - preparing 16-bit and 8-bit SQL statements;
1.187 + - executing prepared SQL statement;
1.188 + - retrieving parameter names and column names;
1.189 + - binding SQL parameters;
1.190 + - retrieving column values;
1.191 + - reseting the prepared SQL statement;
1.192 + - moving the cursor to the next record;
1.193 +
1.194 +@see CSqlSrvStatement::NewLC()
1.195 +@see CSqlSrvStatement::NewLC()
1.196 +@see CSqlSrvStatement::BindL()
1.197 +@see CSqlSrvStatement::Next()
1.198 +@see CSqlSrvStatement::Reset()
1.199 +@see CSqlSrvStatement::Exec()
1.200 +@see CSqlSrvStatement::ColumnNamesL()
1.201 +@see CSqlSrvStatement::ParamNamesL()
1.202 +@see CSqlSrvStatement::ColumnValuesL()
1.203 +@see CSqlSrvStatement::ColumnSource()
1.204 +
1.205 +@see HSqlSrvStmtParamBuf
1.206 +
1.207 +@internalComponent
1.208 +*/
1.209 +NONSHARABLE_CLASS(CSqlSrvStatement) : public CBase
1.210 + {
1.211 +public:
1.212 + static CSqlSrvStatement* NewLC(sqlite3* aDbHandle, const TDesC16& aSqlStmt, TInt& aColumnCount, TInt& aParamCount);
1.213 + static CSqlSrvStatement* NewLC(sqlite3* aDbHandle, const TDesC8& aSqlStmt, TInt& aColumnCount, TInt& aParamCount);
1.214 + virtual ~CSqlSrvStatement();
1.215 +
1.216 + void BindL(const RSqlBufFlat& aParamBuf);
1.217 + inline TInt Next();
1.218 + inline TInt Reset();
1.219 + inline TInt Exec();
1.220 +
1.221 + inline const RSqlBufFlat& BufFlatL(TSqlBufFlatType aWhat) const;
1.222 + const RSqlBufFlat& ColumnNamesL();
1.223 + const RSqlBufFlat& ParamNamesL();
1.224 + const RSqlBufFlat& ColumnValuesL();
1.225 + TInt ColumnSource(TInt aColumnIndex, TPtrC8& aColumnSource) const;
1.226 +
1.227 + TInt ColumnInt(TInt aColIdx) const;
1.228 + TInt64 ColumnInt64(TInt aColIdx) const;
1.229 + TReal ColumnReal(TInt aColIdx) const;
1.230 + TPtrC ColumnTextL(TInt aColIdx) const;
1.231 + TPtrC8 ColumnBinary(TInt aColIdx) const;
1.232 +
1.233 + const RSqlBufFlat& GetDeclColumnTypesL();
1.234 +
1.235 + HSqlSrvStmtParamBuf* GetParamBufL(TInt aParamIndex, HSqlSrvStmtParamBuf::TDataType aDataType, HSqlSrvStmtParamBuf::TBufType aBufType);
1.236 + void BindParamBufL(TInt aParamIndex);
1.237 +
1.238 +private:
1.239 + inline CSqlSrvStatement();
1.240 + inline void ConstructL(sqlite3* aDbHandle, const TDesC16& aSqlStmt);
1.241 + inline void ConstructL(sqlite3* aDbHandle, const TDesC8& aSqlStmt);
1.242 + void DoCommonConstructL();
1.243 + void DestroyParamBufArray();
1.244 + void ExtendParamBufArrayL(TInt aParamIndex);
1.245 + TPtrC8 CopyAndStoreParamL(TInt aParamIndex, HSqlSrvStmtParamBuf::TDataType aDataType, const TDesC8& aParamValue);
1.246 +
1.247 +private:
1.248 + sqlite3_stmt* iStmtHandle; //SQL statement handle
1.249 + TInt iColumnCount;
1.250 + TInt iParamCount;
1.251 + TSqlBufFlatType iBufFlatType; //What is in iFlatBuf data member
1.252 + RSqlBufFlat iBufFlat; //Flat buffer used for: column names, parameter names, column values
1.253 + RArray<HSqlSrvStmtParamBuf*> iParamBufArray;//An array with pointers to HSqlSrvStmtParamBuf buffers for the text/binary parameters
1.254 +
1.255 + };
1.256 +
1.257 +#include "SqlSrvStatement.inl"
1.258 +
1.259 +#endif//__SQLSRVSTATEMENT_H__