1.1 --- /dev/null Thu Jan 01 00:00:00 1970 +0000
1.2 +++ b/os/persistentdata/persistentstorage/sql/SRC/Client/SqlStmtSession.inl Fri Jun 15 03:10:57 2012 +0200
1.3 @@ -0,0 +1,227 @@
1.4 +// Copyright (c) 2006-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 +//
1.16 +// Description:
1.17 +// SqlDbSession.inl
1.18 +//
1.19 +//
1.20 +
1.21 +/**
1.22 +@panic SqlDb 2 In _DEBUG mode if the statement handle is 0 or the database session is NULL,
1.23 + i.e. Prepare() has not yet been called on this RSqlStatementSession object.
1.24 +
1.25 +@return A reference to the RSqlDbSession instance.
1.26 +*/
1.27 +inline RSqlDbSession& RSqlStatementSession::DbSession() const
1.28 + {
1.29 + __ASSERT_DEBUG(iHandle > 0 && iDbSession != NULL, __SQLPANIC(ESqlPanicInvalidObj));
1.30 + return *iDbSession;
1.31 + }
1.32 +
1.33 +/**
1.34 +Creates unitialized RSqlStatementSession object.
1.35 +*/
1.36 +inline RSqlStatementSession::RSqlStatementSession() :
1.37 + iHandle(-1),
1.38 + iDbSession(NULL)
1.39 + {
1.40 + }
1.41 +
1.42 +/**
1.43 +Sends a request to the SQL server to reset the prepared SQL statement.
1.44 +
1.45 +@return KErrNone The method completed successfully, system-wide error code otherwise.
1.46 +*/
1.47 +inline TInt RSqlStatementSession::Reset()
1.48 + {
1.49 + return DbSession().SendReceive(::MakeMsgCode(ESqlSrvStmtReset, ESqlSrvStatementHandle, iHandle));
1.50 + }
1.51 +
1.52 +/**
1.53 +Sends a request to the SQL server to execute the prepared SQL statement.
1.54 +
1.55 +
1.56 +@return >=0, The operation has completed successfully. The number of database rows that were
1.57 + changed/inserted/deleted by the most recently completed INSERT/UPDATE/DELETE sql statement.
1.58 + Exception: If the executed statement is "DELETE FROM <table>", then the function returns 0
1.59 + if the operation has completed successfully (disregarding the number of the deleted rows);
1.60 + KSqlErrStmtExpired, statement has expired (if new functions or collating sequences are
1.61 + registered or if an authorizer function is added or changed);
1.62 + KErrNoMemory, an out of memory condition has occurred.
1.63 + Note that database specific errors categorised as ESqlDbError, and
1.64 + other system-wide error codes may also be returned.
1.65 +*/
1.66 +inline TInt RSqlStatementSession::Exec()
1.67 + {
1.68 + return DbSession().SendReceive(::MakeMsgCode(ESqlSrvStmtExec, ESqlSrvStatementHandle, iHandle));
1.69 + }
1.70 +
1.71 +/**
1.72 +Sends a request asynchronously to the SQL server to execute the prepared SQL statement.
1.73 +
1.74 +@param aStatus Completion status of asynchronous request, one of the following:
1.75 +@code
1.76 + - >=0, The operation has completed successfully. The number of database rows that were
1.77 + changed/inserted/deleted by the most recently completed INSERT/UPDATE/DELETE sql statement.
1.78 + Exception: If the executed statement is "DELETE FROM <table>", then the function returns 0
1.79 + if the operation has completed successfully (disregarding the number of the deleted rows);
1.80 + - KSqlErrStmtExpired, the SQL statement has expired (if new functions or
1.81 + collating sequences have been registered or if an
1.82 + authorizer function has been added or changed);
1.83 + - KErrNoMemory, an out of memory condition has occurred - the statement
1.84 + will be reset.
1.85 + Note that aStatus may be set with database specific errors categorised as ESqlDbError,
1.86 + and other system-wide error codes.
1.87 +@endcode
1.88 +*/
1.89 +inline void RSqlStatementSession::Exec(TRequestStatus& aStatus)
1.90 + {
1.91 + DbSession().SendReceive(::MakeMsgCode(ESqlSrvStmtAsyncExec, ESqlSrvStatementHandle, iHandle), aStatus);
1.92 + }
1.93 +
1.94 +/**
1.95 +Sends a request to the SQL server to execute the prepared SQL statement.
1.96 +
1.97 +Usage of the IPC call arguments:
1.98 +Arg 0: [out] parameter buffer length in bytes
1.99 +Arg 1: [out] parameter buffer
1.100 +
1.101 +@param aParamBuf A buffer with the parameter values
1.102 +
1.103 +@return >=0, The operation has completed successfully. The number of database rows that were
1.104 + changed/inserted/deleted by the most recently completed INSERT/UPDATE/DELETE sql statement.
1.105 + Exception: If the executed statement is "DELETE FROM <table>", then the function returns 0
1.106 + if the operation has completed successfully (disregarding the number of the deleted rows);
1.107 + KSqlErrStmtExpired, statement has expired (if new functions or collating sequences are
1.108 + registered or if an authorizer function is added or changed);
1.109 + KErrNoMemory, an out of memory condition has occurred.
1.110 + Note that database specific errors categorised as ESqlDbError, and
1.111 + other system-wide error codes may also be returned.
1.112 +*/
1.113 +inline TInt RSqlStatementSession::BindExec(const RSqlBufFlat& aParamBuf)
1.114 + {
1.115 + TPtrC8 prmData(aParamBuf.BufDes());
1.116 + return DbSession().SendReceive(::MakeMsgCode(ESqlSrvStmtBindExec, ESqlSrvStatementHandle, iHandle), TIpcArgs(prmData.Length(), &prmData));
1.117 + }
1.118 +
1.119 +/**
1.120 +Sends a request asynchronously to the SQL server to execute the prepared SQL statement.
1.121 +
1.122 +Usage of the IPC call arguments:
1.123 +Arg 0: [out] parameter buffer length in bytes
1.124 +Arg 1: [out] parameter buffer
1.125 +
1.126 +@param aParamBuf A buffer with the parameter values
1.127 +@param aStatus Completion status of asynchronous request, one of the following:
1.128 +@code
1.129 + - >=0, The operation has completed successfully. The number of database rows that were
1.130 + changed/inserted/deleted by the most recently completed INSERT/UPDATE/DELETE sql statement.
1.131 + Exception: If the executed statement is "DELETE FROM <table>", then the function returns 0
1.132 + if the operation has completed successfully (disregarding the number of the deleted rows);
1.133 + - KSqlErrStmtExpired, the SQL statement has expired (if new functions or
1.134 + collating sequences have been registered or if an
1.135 + authorizer function has been added or changed);
1.136 + - KErrNoMemory, an out of memory condition has occurred - the statement
1.137 + will be reset.
1.138 + Note that aStatus may be set with database specific errors categorised as ESqlDbError,
1.139 + and other system-wide error codes.
1.140 +@endcode
1.141 +*/
1.142 +inline void RSqlStatementSession::BindExec(const RSqlBufFlat& aParamBuf, TRequestStatus& aStatus)
1.143 + {
1.144 + const TDesC8& bufDes = aParamBuf.BufDes();
1.145 + DbSession().SendReceive(::MakeMsgCode(ESqlSrvStmtAsyncBindExec, ESqlSrvStatementHandle, iHandle), TIpcArgs(bufDes.Length(), &bufDes), aStatus);
1.146 + }
1.147 +
1.148 +/**
1.149 +Sends a request to the SQL server to move to the next record which satisfies the
1.150 +condition of the prepared SQL statement.
1.151 +If there is a valid next record, the method transfers the column values from the server.
1.152 +
1.153 +@param aColumnBuf It references RSqlBufFlat object where the column values will be stored.
1.154 +
1.155 +@return KSqlAtRow, the record data is ready for processing by the caller;
1.156 + KSqlAtEnd, there is no more record data;
1.157 + KSqlErrBusy, the database file is locked;
1.158 + KErrNoMemory, an out of memory condition has occurred - the statement
1.159 + will be reset;
1.160 + KSqlErrGeneral, a run-time error has occured - this function must not
1.161 + be called again;
1.162 + KSqlErrMisuse, this function has been called after a previous call
1.163 + returned KSqlAtEnd or KSqlErrGeneral.
1.164 + KSqlErrStmtExpired, the SQL statement has expired (if new functions or
1.165 + collating sequences have been registered or if an
1.166 + authorizer function has been added or changed);
1.167 +*/
1.168 +inline TInt RSqlStatementSession::Next(RSqlBufFlat& aColumnBuf)
1.169 + {
1.170 + TIpcArgs ipcArgs;
1.171 + return DoBindNext(ESqlSrvStmtNext, ipcArgs, aColumnBuf);
1.172 + }
1.173 +
1.174 +/**
1.175 +Sends a command to the server for retrieving a column data.
1.176 +
1.177 +Usage of the IPC call arguments:
1.178 +Arg 0: [out] column index
1.179 +Arg 1: [out] column data buffer length in bytes
1.180 +Arg 2: [in/out] column data buffer
1.181 +*/
1.182 +inline TInt RSqlStatementSession::ReadColumnValue(TInt aColumnIndex, TDes8& aBuf)
1.183 + {
1.184 + return DbSession().SendReceive(::MakeMsgCode(ESqlSrvStmtColumnValue, ESqlSrvStatementHandle, iHandle), TIpcArgs(aColumnIndex, aBuf.MaxLength(), &aBuf));
1.185 + }
1.186 +
1.187 +/**
1.188 +The method creates a read-only MStreamBuf derived object which allows the column with aColumnIndex index
1.189 +to be accessed as a stream of bytes (if the column is a binary column) or characters
1.190 +(if the column is a text column) and returns it to the caller.
1.191 +
1.192 +Usage of the IPC call arguments:
1.193 +Arg 0: [out] column index (0 based)
1.194 +Arg 2: [in] ipc buffer, column source
1.195 +
1.196 +The caller is responsible for the destroying of the read-only MStreamBuf derived object.
1.197 +
1.198 +@param aColumnIndex Column index (starting from 0)
1.199 +@return A pointer to the created read-only memory MStreamBuf derived object.
1.200 +
1.201 +@leave KErrNoMemory, an out of memory condition has occured;
1.202 +*/
1.203 +inline MStreamBuf* RSqlStatementSession::ColumnSourceL(TInt aColumnIndex)
1.204 + {
1.205 + TIpcArgs args(aColumnIndex);
1.206 + HIpcBuf* columnSource = HIpcBuf::NewL(DbSession(), ::MakeMsgCode(ESqlSrvStmtColumnSource, ESqlSrvStatementHandle, iHandle), args);
1.207 + return columnSource;
1.208 + }
1.209 +
1.210 +/**
1.211 +The method creates an IPC object with buffering capabilities, allowing to stream out the data of the
1.212 +parameter with aParameterIndex index and returns this MStreamBuf derived object to the caller.
1.213 +
1.214 +The caller is responsible for the destroying of the MStreamBuf derived object.
1.215 +
1.216 +Arg 0: [out] parameter index (0 based)
1.217 +Arg 2: [in] ipc buffer, parameter source
1.218 +
1.219 +@param aParameterIndex Parameter index (starting from 0)
1.220 +
1.221 +@return A pointer to the created MStreamBuf derived object.
1.222 +
1.223 +@leave KErrNoMemory, an out of memory condition has occured;
1.224 +*/
1.225 +inline MStreamBuf* RSqlStatementSession::ParamSinkL(TSqlSrvFunction aFunction, TInt aParamIndex)
1.226 + {
1.227 + TIpcArgs args(aParamIndex);
1.228 + HIpcBuf* paramSink = HIpcBuf::NewL(DbSession(), ::MakeMsgCode(aFunction, ESqlSrvStatementHandle, iHandle), args);
1.229 + return paramSink;
1.230 + }