|
1 // Copyright (c) 2006-2009 Nokia Corporation and/or its subsidiary(-ies). |
|
2 // All rights reserved. |
|
3 // This component and the accompanying materials are made available |
|
4 // under the terms of "Eclipse Public License v1.0" |
|
5 // which accompanies this distribution, and is available |
|
6 // at the URL "http://www.eclipse.org/legal/epl-v10.html". |
|
7 // |
|
8 // Initial Contributors: |
|
9 // Nokia Corporation - initial contribution. |
|
10 // |
|
11 // Contributors: |
|
12 // |
|
13 // Description: |
|
14 // SqlDbSession.inl |
|
15 // |
|
16 // |
|
17 |
|
18 /** |
|
19 |
|
20 Sends a request to the SQL server to prepare 16-bit aSqlStmt statement. |
|
21 |
|
22 Usage of the IPC call arguments: |
|
23 Arg 0: [in/out] data buffer for the column and parameter count. |
|
24 Arg 1: [out] statement length in characters |
|
25 Arg 2: [out] 16-bit statement |
|
26 |
|
27 @param aDbSession A reference to RSqlDbSession instance. |
|
28 @param aSqlStmt 16-bit SQL statement. |
|
29 @param aColumnCount Output parameter. Statement column count. |
|
30 @param aParamCount Output parameter. Statement parameter count. |
|
31 |
|
32 @return KErrNoMemory, an out of memory condition has occured; |
|
33 KErrArgument, bad argument, for example - the SQL string contains more than one SQL statements. |
|
34 Note that the function may leave with some database specific errors categorised as |
|
35 ESqlDbError or other system-wide error codes; |
|
36 KErrNone The operation has completed successfully. |
|
37 |
|
38 @panic SqlDb 7 In _DEBUG mode if the statement handle is 0. |
|
39 */ |
|
40 inline TInt RSqlStatementSession::Prepare(RSqlDbSession& aDbSession, const TDesC& aSqlStmt, |
|
41 TInt& aColumnCount, TInt& aParamCount) |
|
42 { |
|
43 iDbSession = &aDbSession; |
|
44 TSqlIpcData data; |
|
45 TPckg<TSqlIpcData> pckg(data); |
|
46 TUint stmtLen = aSqlStmt.Length(); |
|
47 iHandle = iDbSession->SendReceive(ESqlSrvStmtPrepare16, TIpcArgs(&pckg, stmtLen, &aSqlStmt)); |
|
48 __SQLASSERT(iHandle != 0, ESqlPanicInternalError); |
|
49 aColumnCount = static_cast <TInt> (data.iPrm1); |
|
50 aParamCount = static_cast <TInt> (data.iPrm2); |
|
51 return iHandle > 0 ? KErrNone : iHandle; |
|
52 } |
|
53 |
|
54 /** |
|
55 Sends a request to the SQL server to prepare 8-bit aSqlStmt statement. |
|
56 |
|
57 Usage of the IPC call arguments: |
|
58 Arg 0: [in/out] data buffer for the column and parameter count. |
|
59 Arg 1: [out] statement length in characters |
|
60 Arg 2: [out] 8-bit statement |
|
61 |
|
62 @param aDbSession A reference to RSqlDbSession instance. |
|
63 @param aSqlStmt 8-bit SQL statement. |
|
64 @param aColumnCount Output parameter. Statement column count. |
|
65 @param aParamCount Output parameter. Statement parameter count. |
|
66 |
|
67 @return KErrNoMemory, an out of memory condition has occured; |
|
68 KErrArgument, bad argument, for example - the SQL string contains more than one SQL statements. |
|
69 Note that the function may leave with some database specific errors categorised as |
|
70 ESqlDbError or other system-wide error codes; |
|
71 KErrNone The operation has completed successfully. |
|
72 |
|
73 @panic SqlDb 7 In _DEBUG mode if the statement handle is 0. |
|
74 */ |
|
75 inline TInt RSqlStatementSession::Prepare(RSqlDbSession& aDbSession, const TDesC8& aSqlStmt, |
|
76 TInt& aColumnCount, TInt& aParamCount) |
|
77 { |
|
78 iDbSession = &aDbSession; |
|
79 TSqlIpcData data; |
|
80 TPckg<TSqlIpcData> pckg(data); |
|
81 TUint stmtLen = aSqlStmt.Length(); |
|
82 iHandle = iDbSession->SendReceive(ESqlSrvStmtPrepare8, TIpcArgs(&pckg, stmtLen, &aSqlStmt)); |
|
83 __SQLASSERT(iHandle != 0, ESqlPanicInternalError); |
|
84 aColumnCount = static_cast <TInt> (data.iPrm1); |
|
85 aParamCount = static_cast <TInt> (data.iPrm2); |
|
86 return iHandle > 0 ? KErrNone : iHandle; |
|
87 } |
|
88 |
|
89 /** |
|
90 @panic SqlDb 2 In _DEBUG mode if the statement handle is 0 or the database session is NULL, |
|
91 i.e. Prepare() has not yet been called on this RSqlStatementSession object. |
|
92 |
|
93 @return A reference to the RSqlDbSession instance. |
|
94 */ |
|
95 inline RSqlDbSession& RSqlStatementSession::DbSession() const |
|
96 { |
|
97 __SQLASSERT(iHandle > 0 && iDbSession != NULL, ESqlPanicInvalidObj); |
|
98 return *iDbSession; |
|
99 } |
|
100 |
|
101 /** |
|
102 Creates unitialized RSqlStatementSession object. |
|
103 */ |
|
104 inline RSqlStatementSession::RSqlStatementSession() : |
|
105 iHandle(-1), |
|
106 iDbSession(NULL) |
|
107 { |
|
108 } |
|
109 |
|
110 /** |
|
111 Sends a request to the SQL server to reset the prepared SQL statement. |
|
112 |
|
113 @return KErrNone The method completed successfully, system-wide error code otherwise. |
|
114 */ |
|
115 inline TInt RSqlStatementSession::Reset() |
|
116 { |
|
117 return DbSession().SendReceive(::MakeMsgCode(ESqlSrvStmtReset, ESqlSrvStatementHandle, iHandle)); |
|
118 } |
|
119 |
|
120 /** |
|
121 Sends a request to the SQL server to execute the prepared SQL statement. |
|
122 |
|
123 |
|
124 @return >=0, The operation has completed successfully. The number of database rows that were |
|
125 changed/inserted/deleted by the most recently completed INSERT/UPDATE/DELETE sql statement. |
|
126 Exception: If the executed statement is "DELETE FROM <table>", then the function returns 0 |
|
127 if the operation has completed successfully (disregarding the number of the deleted rows); |
|
128 KSqlErrStmtExpired, statement has expired (if new functions or collating sequences are |
|
129 registered or if an authorizer function is added or changed); |
|
130 KErrNoMemory, an out of memory condition has occurred. |
|
131 Note that database specific errors categorised as ESqlDbError, and |
|
132 other system-wide error codes may also be returned. |
|
133 */ |
|
134 inline TInt RSqlStatementSession::Exec() |
|
135 { |
|
136 return DbSession().SendReceive(::MakeMsgCode(ESqlSrvStmtExec, ESqlSrvStatementHandle, iHandle)); |
|
137 } |
|
138 |
|
139 /** |
|
140 Sends a request asynchronously to the SQL server to execute the prepared SQL statement. |
|
141 |
|
142 @param aStatus Completion status of asynchronous request, one of the following: |
|
143 @code |
|
144 - >=0, The operation has completed successfully. The number of database rows that were |
|
145 changed/inserted/deleted by the most recently completed INSERT/UPDATE/DELETE sql statement. |
|
146 Exception: If the executed statement is "DELETE FROM <table>", then the function returns 0 |
|
147 if the operation has completed successfully (disregarding the number of the deleted rows); |
|
148 - KSqlErrStmtExpired, the SQL statement has expired (if new functions or |
|
149 collating sequences have been registered or if an |
|
150 authorizer function has been added or changed); |
|
151 - KErrNoMemory, an out of memory condition has occurred - the statement |
|
152 will be reset. |
|
153 Note that aStatus may be set with database specific errors categorised as ESqlDbError, |
|
154 and other system-wide error codes. |
|
155 @endcode |
|
156 */ |
|
157 inline void RSqlStatementSession::Exec(TRequestStatus& aStatus) |
|
158 { |
|
159 DbSession().SendReceive(::MakeMsgCode(ESqlSrvStmtAsyncExec, ESqlSrvStatementHandle, iHandle), aStatus); |
|
160 } |
|
161 |
|
162 /** |
|
163 Sends a request to the SQL server to execute the prepared SQL statement. |
|
164 |
|
165 Usage of the IPC call arguments: |
|
166 Arg 0: [out] parameter buffer length in bytes |
|
167 Arg 1: [out] parameter buffer |
|
168 |
|
169 @param aParamBuf A buffer with the parameter values |
|
170 |
|
171 @return >=0, The operation has completed successfully. The number of database rows that were |
|
172 changed/inserted/deleted by the most recently completed INSERT/UPDATE/DELETE sql statement. |
|
173 Exception: If the executed statement is "DELETE FROM <table>", then the function returns 0 |
|
174 if the operation has completed successfully (disregarding the number of the deleted rows); |
|
175 KSqlErrStmtExpired, statement has expired (if new functions or collating sequences are |
|
176 registered or if an authorizer function is added or changed); |
|
177 KErrNoMemory, an out of memory condition has occurred. |
|
178 Note that database specific errors categorised as ESqlDbError, and |
|
179 other system-wide error codes may also be returned. |
|
180 */ |
|
181 inline TInt RSqlStatementSession::BindExec(const RSqlBufFlat& aParamBuf) |
|
182 { |
|
183 TPtrC8 prmData(aParamBuf.BufDes()); |
|
184 return DbSession().SendReceive(::MakeMsgCode(ESqlSrvStmtBindExec, ESqlSrvStatementHandle, iHandle), TIpcArgs(prmData.Length(), &prmData)); |
|
185 } |
|
186 |
|
187 /** |
|
188 Sends a request asynchronously to the SQL server to execute the prepared SQL statement. |
|
189 |
|
190 Usage of the IPC call arguments: |
|
191 Arg 0: [out] parameter buffer length in bytes |
|
192 Arg 1: [out] parameter buffer |
|
193 |
|
194 @param aParamBuf A buffer with the parameter values |
|
195 @param aStatus Completion status of asynchronous request, one of the following: |
|
196 @code |
|
197 - >=0, The operation has completed successfully. The number of database rows that were |
|
198 changed/inserted/deleted by the most recently completed INSERT/UPDATE/DELETE sql statement. |
|
199 Exception: If the executed statement is "DELETE FROM <table>", then the function returns 0 |
|
200 if the operation has completed successfully (disregarding the number of the deleted rows); |
|
201 - KSqlErrStmtExpired, the SQL statement has expired (if new functions or |
|
202 collating sequences have been registered or if an |
|
203 authorizer function has been added or changed); |
|
204 - KErrNoMemory, an out of memory condition has occurred - the statement |
|
205 will be reset. |
|
206 Note that aStatus may be set with database specific errors categorised as ESqlDbError, |
|
207 and other system-wide error codes. |
|
208 @endcode |
|
209 */ |
|
210 inline void RSqlStatementSession::BindExec(const RSqlBufFlat& aParamBuf, TRequestStatus& aStatus) |
|
211 { |
|
212 const TDesC8& bufDes = aParamBuf.BufDes(); |
|
213 DbSession().SendReceive(::MakeMsgCode(ESqlSrvStmtAsyncBindExec, ESqlSrvStatementHandle, iHandle), TIpcArgs(bufDes.Length(), &bufDes), aStatus); |
|
214 } |
|
215 |
|
216 /** |
|
217 Sends a request to the SQL server to move to the next record which satisfies the |
|
218 condition of the prepared SQL statement. |
|
219 If there is a valid next record, the method transfers the column values from the server. |
|
220 |
|
221 @param aColumnBuf It references RSqlBufFlat object where the column values will be stored. |
|
222 |
|
223 @return KSqlAtRow, the record data is ready for processing by the caller; |
|
224 KSqlAtEnd, there is no more record data; |
|
225 KSqlErrBusy, the database file is locked; |
|
226 KErrNoMemory, an out of memory condition has occurred - the statement |
|
227 will be reset; |
|
228 KSqlErrGeneral, a run-time error has occured - this function must not |
|
229 be called again; |
|
230 KSqlErrMisuse, this function has been called after a previous call |
|
231 returned KSqlAtEnd or KSqlErrGeneral. |
|
232 KSqlErrStmtExpired, the SQL statement has expired (if new functions or |
|
233 collating sequences have been registered or if an |
|
234 authorizer function has been added or changed); |
|
235 */ |
|
236 inline TInt RSqlStatementSession::Next(RSqlBufFlat& aColumnBuf) |
|
237 { |
|
238 TIpcArgs ipcArgs; |
|
239 return DoBindNext(ESqlSrvStmtNext, ipcArgs, aColumnBuf); |
|
240 } |
|
241 |
|
242 /** |
|
243 Sends a command to the server for retrieving a column data. |
|
244 |
|
245 Usage of the IPC call arguments: |
|
246 Arg 0: [out] column index |
|
247 Arg 1: [out] column data buffer length in bytes |
|
248 Arg 2: [in/out] column data buffer |
|
249 */ |
|
250 inline TInt RSqlStatementSession::ReadColumnValue(TInt aColumnIndex, TDes8& aBuf) |
|
251 { |
|
252 return DbSession().SendReceive(::MakeMsgCode(ESqlSrvStmtColumnValue, ESqlSrvStatementHandle, iHandle), TIpcArgs(aColumnIndex, aBuf.MaxLength(), &aBuf)); |
|
253 } |
|
254 |
|
255 /** |
|
256 The method creates a read-only MStreamBuf derived object which allows the column with aColumnIndex index |
|
257 to be accessed as a stream of bytes (if the column is a binary column) or characters |
|
258 (if the column is a text column) and returns it to the caller. |
|
259 |
|
260 Usage of the IPC call arguments: |
|
261 Arg 0: [out] column index (0 based) |
|
262 Arg 2: [in] ipc buffer, column source |
|
263 |
|
264 The caller is responsible for the destroying of the read-only MStreamBuf derived object. |
|
265 |
|
266 @param aColumnIndex Column index (starting from 0) |
|
267 @return A pointer to the created read-only memory MStreamBuf derived object. |
|
268 |
|
269 @leave KErrNoMemory, an out of memory condition has occured; |
|
270 */ |
|
271 inline MStreamBuf* RSqlStatementSession::ColumnSourceL(TInt aColumnIndex) |
|
272 { |
|
273 TIpcArgs args(aColumnIndex); |
|
274 HIpcBuf* columnSource = HIpcBuf::NewL(DbSession(), ::MakeMsgCode(ESqlSrvStmtColumnSource, ESqlSrvStatementHandle, iHandle), args); |
|
275 return columnSource; |
|
276 } |
|
277 |
|
278 /** |
|
279 The method creates an IPC object with buffering capabilities, allowing to stream out the data of the |
|
280 parameter with aParameterIndex index and returns this MStreamBuf derived object to the caller. |
|
281 |
|
282 The caller is responsible for the destroying of the MStreamBuf derived object. |
|
283 |
|
284 Arg 0: [out] parameter index (0 based) |
|
285 Arg 2: [in] ipc buffer, parameter source |
|
286 |
|
287 @param aParameterIndex Parameter index (starting from 0) |
|
288 |
|
289 @return A pointer to the created MStreamBuf derived object. |
|
290 |
|
291 @leave KErrNoMemory, an out of memory condition has occured; |
|
292 */ |
|
293 inline MStreamBuf* RSqlStatementSession::ParamSinkL(TSqlSrvFunction aFunction, TInt aParamIndex) |
|
294 { |
|
295 TIpcArgs args(aParamIndex); |
|
296 HIpcBuf* paramSink = HIpcBuf::NewL(DbSession(), ::MakeMsgCode(aFunction, ESqlSrvStatementHandle, iHandle), args); |
|
297 return paramSink; |
|
298 } |