sl@0: // Copyright (c) 2006-2010 Nokia Corporation and/or its subsidiary(-ies).
sl@0: // All rights reserved.
sl@0: // This component and the accompanying materials are made available
sl@0: // under the terms of "Eclipse Public License v1.0"
sl@0: // which accompanies this distribution, and is available
sl@0: // at the URL "http://www.eclipse.org/legal/epl-v10.html".
sl@0: //
sl@0: // Initial Contributors:
sl@0: // Nokia Corporation - initial contribution.
sl@0: //
sl@0: // Contributors:
sl@0: //
sl@0: // Description:
sl@0: // SqlDbSession.inl
sl@0: // 
sl@0: //
sl@0: 
sl@0: /**
sl@0: @panic SqlDb 2 In _DEBUG mode if the statement handle is 0 or the database session is NULL,
sl@0: 			   i.e. Prepare() has not yet been called on this RSqlStatementSession object.
sl@0: 			   
sl@0: @return A reference to the RSqlDbSession instance.
sl@0: */
sl@0: inline RSqlDbSession& RSqlStatementSession::DbSession() const
sl@0: 	{
sl@0: 	__ASSERT_DEBUG(iHandle > 0 && iDbSession != NULL, __SQLPANIC(ESqlPanicInvalidObj));
sl@0: 	return *iDbSession;
sl@0: 	}
sl@0: 
sl@0: /**
sl@0: Creates unitialized RSqlStatementSession object.
sl@0: */
sl@0: inline RSqlStatementSession::RSqlStatementSession() :
sl@0: 	iHandle(-1),
sl@0: 	iDbSession(NULL)
sl@0: 	{
sl@0: 	}
sl@0: 	
sl@0: /**
sl@0: Sends a request to the SQL server to reset the prepared SQL statement.
sl@0: 
sl@0: @return KErrNone The method completed successfully, system-wide error code otherwise.
sl@0: */
sl@0: inline TInt RSqlStatementSession::Reset()
sl@0: 	{
sl@0: 	return DbSession().SendReceive(::MakeMsgCode(ESqlSrvStmtReset, ESqlSrvStatementHandle, iHandle));
sl@0: 	}
sl@0: 
sl@0: /**
sl@0: Sends a request to the SQL server to execute the prepared SQL statement.
sl@0: 
sl@0: 
sl@0: @return >=0, The operation has completed successfully. The number of database rows that were 
sl@0: 			 changed/inserted/deleted by the most recently completed INSERT/UPDATE/DELETE sql statement.
sl@0: 			 Exception: If the executed statement is "DELETE FROM <table>", then the function returns 0 
sl@0: 			 if the operation has completed successfully (disregarding the number of the deleted rows);
sl@0: 	    KSqlErrStmtExpired, statement has expired (if new functions or collating sequences are 
sl@0: 							registered or if an authorizer function is added or changed);
sl@0: 		KErrNoMemory, an out of memory condition has occurred.
sl@0:                       Note that database specific errors categorised as ESqlDbError, and
sl@0:                       other system-wide error codes may also be returned.
sl@0: */
sl@0: inline TInt RSqlStatementSession::Exec()
sl@0: 	{
sl@0: 	return DbSession().SendReceive(::MakeMsgCode(ESqlSrvStmtExec, ESqlSrvStatementHandle, iHandle));
sl@0: 	}
sl@0: 
sl@0: /**
sl@0: Sends a request asynchronously to the SQL server to execute the prepared SQL statement.
sl@0: 
sl@0: @param aStatus Completion status of asynchronous request, one of the following:
sl@0: @code
sl@0: 		- >=0, The operation has completed successfully. The number of database rows that were 
sl@0: 			   changed/inserted/deleted by the most recently completed INSERT/UPDATE/DELETE sql statement.
sl@0: 			 Exception: If the executed statement is "DELETE FROM <table>", then the function returns 0 
sl@0: 			 if the operation has completed successfully (disregarding the number of the deleted rows);
sl@0:         - KSqlErrStmtExpired, the SQL statement has expired (if new functions or
sl@0:                             collating sequences have been registered or if an
sl@0:                             authorizer function has been added or changed);
sl@0:         - KErrNoMemory, an out of memory condition has occurred - the statement
sl@0:                       will be reset.
sl@0:                       Note that aStatus may be set with database specific errors categorised as ESqlDbError, 
sl@0:                       and other system-wide error codes.
sl@0: @endcode
sl@0: */
sl@0: inline void RSqlStatementSession::Exec(TRequestStatus& aStatus)
sl@0: 	{
sl@0: 	DbSession().SendReceive(::MakeMsgCode(ESqlSrvStmtAsyncExec, ESqlSrvStatementHandle, iHandle), aStatus);
sl@0: 	}
sl@0: 
sl@0: /**
sl@0: Sends a request to the SQL server to execute the prepared SQL statement.
sl@0: 
sl@0: Usage of the IPC call arguments:
sl@0: Arg 0: [out]		parameter buffer length in bytes
sl@0: Arg 1: [out]		parameter buffer
sl@0: 
sl@0: @param aParamBuf A buffer with the parameter values
sl@0: 
sl@0: @return >=0, The operation has completed successfully. The number of database rows that were 
sl@0: 			 changed/inserted/deleted by the most recently completed INSERT/UPDATE/DELETE sql statement.
sl@0: 			 Exception: If the executed statement is "DELETE FROM <table>", then the function returns 0 
sl@0: 			 if the operation has completed successfully (disregarding the number of the deleted rows);
sl@0: 	    KSqlErrStmtExpired, statement has expired (if new functions or collating sequences are 
sl@0: 							registered or if an authorizer function is added or changed);
sl@0: 		KErrNoMemory, an out of memory condition has occurred.
sl@0:                       Note that database specific errors categorised as ESqlDbError, and
sl@0:                       other system-wide error codes may also be returned.
sl@0: */
sl@0: inline TInt RSqlStatementSession::BindExec(const RSqlBufFlat& aParamBuf)
sl@0: 	{
sl@0: 	TPtrC8 prmData(aParamBuf.BufDes());
sl@0: 	return DbSession().SendReceive(::MakeMsgCode(ESqlSrvStmtBindExec, ESqlSrvStatementHandle, iHandle), TIpcArgs(prmData.Length(), &prmData));
sl@0: 	}
sl@0: 
sl@0: /**
sl@0: Sends a request asynchronously to the SQL server to execute the prepared SQL statement.
sl@0: 
sl@0: Usage of the IPC call arguments:
sl@0: Arg 0: [out]		parameter buffer length in bytes
sl@0: Arg 1: [out]		parameter buffer
sl@0: 
sl@0: @param aParamBuf A buffer with the parameter values
sl@0: @param aStatus Completion status of asynchronous request, one of the following:
sl@0: @code
sl@0: 		- >=0, The operation has completed successfully. The number of database rows that were 
sl@0: 			   changed/inserted/deleted by the most recently completed INSERT/UPDATE/DELETE sql statement.
sl@0: 			 Exception: If the executed statement is "DELETE FROM <table>", then the function returns 0 
sl@0: 			 if the operation has completed successfully (disregarding the number of the deleted rows);
sl@0:         - KSqlErrStmtExpired, the SQL statement has expired (if new functions or
sl@0:                             collating sequences have been registered or if an
sl@0:                             authorizer function has been added or changed);
sl@0:         - KErrNoMemory, an out of memory condition has occurred - the statement
sl@0:                       will be reset.
sl@0:                       Note that aStatus may be set with database specific errors categorised as ESqlDbError, 
sl@0:                       and other system-wide error codes.
sl@0: @endcode
sl@0: */
sl@0: inline void RSqlStatementSession::BindExec(const RSqlBufFlat& aParamBuf, TRequestStatus& aStatus)
sl@0: 	{
sl@0: 	const TDesC8& bufDes = aParamBuf.BufDes();
sl@0: 	DbSession().SendReceive(::MakeMsgCode(ESqlSrvStmtAsyncBindExec, ESqlSrvStatementHandle, iHandle), TIpcArgs(bufDes.Length(), &bufDes), aStatus);
sl@0: 	}
sl@0: 
sl@0: /**
sl@0: Sends a request to the SQL server to move to the next record which satisfies the 
sl@0: condition of the prepared SQL statement.
sl@0: If there is a valid next record, the method transfers the column values from the server.
sl@0: 
sl@0: @param aColumnBuf It references RSqlBufFlat object where the column values will be stored.
sl@0: 
sl@0: @return KSqlAtRow,      the record data is ready for processing by the caller;
sl@0:         KSqlAtEnd,      there is no more record data;
sl@0:         KSqlErrBusy,    the database file is locked;
sl@0:         KErrNoMemory,   an out of memory condition has occurred - the statement
sl@0:                         will be reset;
sl@0:         KSqlErrGeneral, a run-time error has occured - this function must not
sl@0:                         be called again;        
sl@0:         KSqlErrMisuse,  this function has been called after a previous call
sl@0:                         returned KSqlAtEnd or KSqlErrGeneral.
sl@0:         KSqlErrStmtExpired, the SQL statement has expired (if new functions or
sl@0:                             collating sequences have been registered or if an
sl@0:                             authorizer function has been added or changed);
sl@0: */
sl@0: inline TInt RSqlStatementSession::Next(RSqlBufFlat& aColumnBuf)
sl@0: 	{
sl@0: 	TIpcArgs ipcArgs;
sl@0: 	return DoBindNext(ESqlSrvStmtNext, ipcArgs, aColumnBuf);
sl@0: 	}
sl@0: 
sl@0: /**
sl@0: Sends a command to the server for retrieving a column data.
sl@0: 
sl@0: Usage of the IPC call arguments:
sl@0: Arg 0: [out]		column index
sl@0: Arg 1: [out]		column data buffer length in bytes
sl@0: Arg 2: [in/out]		column data buffer
sl@0: */	
sl@0: inline TInt RSqlStatementSession::ReadColumnValue(TInt aColumnIndex, TDes8& aBuf)
sl@0: 	{
sl@0: 	return DbSession().SendReceive(::MakeMsgCode(ESqlSrvStmtColumnValue, ESqlSrvStatementHandle, iHandle), TIpcArgs(aColumnIndex, aBuf.MaxLength(), &aBuf));
sl@0: 	}
sl@0: 
sl@0: /**
sl@0: The method creates a read-only MStreamBuf derived object which allows the column with aColumnIndex index 
sl@0: to be accessed as a stream of bytes (if the column is a binary column) or characters 
sl@0: (if the column is a text column) and returns it to the caller.
sl@0: 
sl@0: Usage of the IPC call arguments:
sl@0: Arg 0: [out]	column index (0 based)
sl@0: Arg 2: [in]		ipc buffer, column source
sl@0: 
sl@0: The caller is responsible for the destroying of the read-only MStreamBuf derived object.
sl@0: 
sl@0: @param aColumnIndex Column index (starting from 0)
sl@0: @return A pointer to the created read-only memory MStreamBuf derived object.
sl@0: 
sl@0: @leave KErrNoMemory, an out of memory condition has occured;
sl@0: */
sl@0: inline MStreamBuf* RSqlStatementSession::ColumnSourceL(TInt aColumnIndex)
sl@0: 	{
sl@0: 	TIpcArgs args(aColumnIndex);
sl@0: 	HIpcBuf* columnSource = HIpcBuf::NewL(DbSession(), ::MakeMsgCode(ESqlSrvStmtColumnSource, ESqlSrvStatementHandle, iHandle), args);
sl@0: 	return columnSource;
sl@0: 	}
sl@0: 
sl@0: /**
sl@0: The method creates an IPC object with buffering capabilities, allowing to stream out the data of the 
sl@0: parameter with aParameterIndex index and returns this MStreamBuf derived object to the caller.
sl@0: 
sl@0: The caller is responsible for the destroying of the MStreamBuf derived object.
sl@0: 
sl@0: Arg 0: [out]	parameter index (0 based)
sl@0: Arg 2: [in]		ipc buffer, parameter source
sl@0: 
sl@0: @param aParameterIndex Parameter index (starting from 0)
sl@0: 
sl@0: @return A pointer to the created MStreamBuf derived object.
sl@0: 
sl@0: @leave KErrNoMemory, an out of memory condition has occured;
sl@0: */
sl@0: inline MStreamBuf* RSqlStatementSession::ParamSinkL(TSqlSrvFunction aFunction, TInt aParamIndex)
sl@0: 	{
sl@0: 	TIpcArgs args(aParamIndex);
sl@0: 	HIpcBuf* paramSink = HIpcBuf::NewL(DbSession(), ::MakeMsgCode(aFunction, ESqlSrvStatementHandle, iHandle), args);
sl@0: 	return paramSink;
sl@0: 	}