Apache Portable Runtime
apr_dbd_internal.h
1 /* Licensed to the Apache Software Foundation (ASF) under one or more
2  * contributor license agreements. See the NOTICE file distributed with
3  * this work for additional information regarding copyright ownership.
4  * The ASF licenses this file to You under the Apache License, Version 2.0
5  * (the "License"); you may not use this file except in compliance with
6  * the License. You may obtain a copy of the License at
7  *
8  * http://www.apache.org/licenses/LICENSE-2.0
9  *
10  * Unless required by applicable law or agreed to in writing, software
11  * distributed under the License is distributed on an "AS IS" BASIS,
12  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13  * See the License for the specific language governing permissions and
14  * limitations under the License.
15  */
16 
17 /* Overview of what this is and does:
18  * http://www.apache.org/~niq/dbd.html
19  */
20 
21 #ifndef APR_DBD_INTERNAL_H
22 #define APR_DBD_INTERNAL_H
23 
24 #include <stdarg.h>
25 
26 #include "apr_dbd.h"
27 
28 #ifdef __cplusplus
29 extern "C" {
30 #endif
31 
32 #define TXN_IGNORE_ERRORS(t) \
33  ((t) && ((t)->mode & APR_DBD_TRANSACTION_IGNORE_ERRORS))
34 #define TXN_NOTICE_ERRORS(t) \
35  ((t) && !((t)->mode & APR_DBD_TRANSACTION_IGNORE_ERRORS))
36 
37 #define TXN_DO_COMMIT(t) (!((t)->mode & APR_DBD_TRANSACTION_ROLLBACK))
38 #define TXN_DO_ROLLBACK(t) ((t)->mode & APR_DBD_TRANSACTION_ROLLBACK)
39 
40 #define TXN_MODE_BITS \
41  (APR_DBD_TRANSACTION_ROLLBACK|APR_DBD_TRANSACTION_IGNORE_ERRORS)
42 
44  /** name */
45  const char *name;
46 
47  /** init: allow driver to perform once-only initialisation.
48  * Called once only. May be NULL
49  */
50  void (*init)(apr_pool_t *pool);
51 
52  /** native_handle: return the native database handle of the underlying db
53  *
54  * @param handle - apr_dbd handle
55  * @return - native handle
56  */
57  void *(*native_handle)(apr_dbd_t *handle);
58 
59  /** open: obtain a database connection from the server rec.
60  * Must be explicitly closed when you're finished with it.
61  * WARNING: only use this when you need a connection with
62  * a lifetime other than a request
63  *
64  * @param pool - a pool to use for error messages (if any).
65  * @param params - connection parameters.
66  * @param error - descriptive error.
67  * @return database handle, or NULL on error.
68  */
69  apr_dbd_t *(*open)(apr_pool_t *pool, const char *params,
70  const char **error);
71 
72  /** check_conn: check status of a database connection
73  *
74  * @param pool - a pool to use for error messages (if any).
75  * @param handle - the connection to check
76  * @return APR_SUCCESS or error
77  */
78  apr_status_t (*check_conn)(apr_pool_t *pool, apr_dbd_t *handle);
79 
80  /** close: close/release a connection obtained from open()
81  *
82  * @param handle - the connection to release
83  * @return APR_SUCCESS or error
84  */
85  apr_status_t (*close)(apr_dbd_t *handle);
86 
87  /** set_dbname: select database name. May be a no-op if not supported.
88  *
89  * @param pool - working pool
90  * @param handle - the connection
91  * @param name - the database to select
92  * @return 0 for success or error code
93  */
94  int (*set_dbname)(apr_pool_t* pool, apr_dbd_t *handle, const char *name);
95 
96  /** transaction: start a transaction. May be a no-op.
97  *
98  * @param pool - a pool to use for error messages (if any).
99  * @param handle - the connection
100  * @param trans - ptr to a transaction. May be null on entry
101  * @return 0 for success or error code
102  */
103  int (*start_transaction)(apr_pool_t *pool, apr_dbd_t *handle,
104  apr_dbd_transaction_t **trans);
105 
106  /** end_transaction: end a transaction
107  * (commit on success, rollback on error).
108  * May be a no-op.
109  *
110  * @param trans - the transaction.
111  * @return 0 for success or error code
112  */
113  int (*end_transaction)(apr_dbd_transaction_t *trans);
114 
115  /** query: execute an SQL query that doesn't return a result set
116  *
117  * @param handle - the connection
118  * @param nrows - number of rows affected.
119  * @param statement - the SQL statement to execute
120  * @return 0 for success or error code
121  */
122  int (*query)(apr_dbd_t *handle, int *nrows, const char *statement);
123 
124  /** select: execute an SQL query that returns a result set
125  *
126  * @param pool - pool to allocate the result set
127  * @param handle - the connection
128  * @param res - pointer to result set pointer. May point to NULL on entry
129  * @param statement - the SQL statement to execute
130  * @param random - 1 to support random access to results (seek any row);
131  * 0 to support only looping through results in order
132  * (async access - faster)
133  * @return 0 for success or error code
134  */
135  int (*select)(apr_pool_t *pool, apr_dbd_t *handle, apr_dbd_results_t **res,
136  const char *statement, int random);
137 
138  /** num_cols: get the number of columns in a results set
139  *
140  * @param res - result set.
141  * @return number of columns
142  */
143  int (*num_cols)(apr_dbd_results_t *res);
144 
145  /** num_tuples: get the number of rows in a results set
146  * of a synchronous select
147  *
148  * @param res - result set.
149  * @return number of rows, or -1 if the results are asynchronous
150  */
151  int (*num_tuples)(apr_dbd_results_t *res);
152 
153  /** get_row: get a row from a result set
154  *
155  * @param pool - pool to allocate the row
156  * @param res - result set pointer
157  * @param row - pointer to row pointer. May point to NULL on entry
158  * @param rownum - row number, or -1 for "next row". Ignored if random
159  * access is not supported.
160  * @return 0 for success, -1 for rownum out of range or data finished
161  */
162  int (*get_row)(apr_pool_t *pool, apr_dbd_results_t *res,
163  apr_dbd_row_t **row, int rownum);
164 
165  /** get_entry: get an entry from a row
166  *
167  * @param row - row pointer
168  * @param col - entry number
169  * @param val - entry to fill
170  * @return 0 for success, -1 for no data, +1 for general error
171  */
172  const char* (*get_entry)(const apr_dbd_row_t *row, int col);
173 
174  /** error: get current error message (if any)
175  *
176  * @param handle - the connection
177  * @param errnum - error code from operation that returned an error
178  * @return the database current error message, or message for errnum
179  * (implementation-dependent whether errnum is ignored)
180  */
181  const char *(*error)(apr_dbd_t *handle, int errnum);
182 
183  /** escape: escape a string so it is safe for use in query/select
184  *
185  * @param pool - pool to alloc the result from
186  * @param string - the string to escape
187  * @param handle - the connection
188  * @return the escaped, safe string
189  */
190  const char *(*escape)(apr_pool_t *pool, const char *string,
191  apr_dbd_t *handle);
192 
193  /** prepare: prepare a statement
194  *
195  * @param pool - pool to alloc the result from
196  * @param handle - the connection
197  * @param query - the SQL query
198  * @param label - A label for the prepared statement.
199  * use NULL for temporary prepared statements
200  * (eg within a Request in httpd)
201  * @param nargs - number of parameters in the query
202  * @param nvals - number of values passed in p[b]query/select
203  * @param types - pointer to an array with types of parameters
204  * @param statement - statement to prepare. May point to null on entry.
205  * @return 0 for success or error code
206  */
207  int (*prepare)(apr_pool_t *pool, apr_dbd_t *handle, const char *query,
208  const char *label, int nargs, int nvals,
209  apr_dbd_type_e *types, apr_dbd_prepared_t **statement);
210 
211  /** pvquery: query using a prepared statement + args
212  *
213  * @param pool - working pool
214  * @param handle - the connection
215  * @param nrows - number of rows affected.
216  * @param statement - the prepared statement to execute
217  * @param args - args to prepared statement
218  * @return 0 for success or error code
219  */
220  int (*pvquery)(apr_pool_t *pool, apr_dbd_t *handle, int *nrows,
221  apr_dbd_prepared_t *statement, va_list args);
222 
223  /** pvselect: select using a prepared statement + args
224  *
225  * @param pool - working pool
226  * @param handle - the connection
227  * @param res - pointer to query results. May point to NULL on entry
228  * @param statement - the prepared statement to execute
229  * @param random - Whether to support random-access to results
230  * @param args - args to prepared statement
231  * @return 0 for success or error code
232  */
233  int (*pvselect)(apr_pool_t *pool, apr_dbd_t *handle,
234  apr_dbd_results_t **res,
235  apr_dbd_prepared_t *statement, int random, va_list args);
236 
237  /** pquery: query using a prepared statement + args
238  *
239  * @param pool - working pool
240  * @param handle - the connection
241  * @param nrows - number of rows affected.
242  * @param statement - the prepared statement to execute
243  * @param args - args to prepared statement
244  * @return 0 for success or error code
245  */
246  int (*pquery)(apr_pool_t *pool, apr_dbd_t *handle, int *nrows,
247  apr_dbd_prepared_t *statement, const char **args);
248 
249  /** pselect: select using a prepared statement + args
250  *
251  * @param pool - working pool
252  * @param handle - the connection
253  * @param res - pointer to query results. May point to NULL on entry
254  * @param statement - the prepared statement to execute
255  * @param random - Whether to support random-access to results
256  * @param args - args to prepared statement
257  * @return 0 for success or error code
258  */
259  int (*pselect)(apr_pool_t *pool, apr_dbd_t *handle,
260  apr_dbd_results_t **res, apr_dbd_prepared_t *statement,
261  int random, const char **args);
262 
263 
264  /** get_name: get a column title from a result set
265  *
266  * @param res - result set pointer
267  * @param col - entry number
268  * @return param name, or NULL if col is out of bounds.
269  */
270  const char* (*get_name)(const apr_dbd_results_t *res, int col);
271 
272  /** transaction_mode_get: get the mode of transaction
273  *
274  * @param trans - the transaction.
275  * @return mode of transaction
276  */
277  int (*transaction_mode_get)(apr_dbd_transaction_t *trans);
278 
279  /** transaction_mode_set: get the mode of transaction
280  *
281  * @param trans - the transaction.
282  * @param mode - new mode of the transaction
283  * @return the mode of transaction in force after the call
284  */
285  int (*transaction_mode_set)(apr_dbd_transaction_t *trans, int mode);
286 
287  /** format of prepared statement parameters */
288  const char *pformat;
289 
290  /** pvbquery: query using a prepared statement + binary args
291  *
292  * @param pool - working pool
293  * @param handle - the connection
294  * @param nrows - number of rows affected.
295  * @param statement - the prepared statement to execute
296  * @param args - binary args to prepared statement
297  * @return 0 for success or error code
298  */
299  int (*pvbquery)(apr_pool_t *pool, apr_dbd_t *handle, int *nrows,
300  apr_dbd_prepared_t *statement, va_list args);
301 
302  /** pvbselect: select using a prepared statement + binary args
303  *
304  * @param pool - working pool
305  * @param handle - the connection
306  * @param res - pointer to query results. May point to NULL on entry
307  * @param statement - the prepared statement to execute
308  * @param random - Whether to support random-access to results
309  * @param args - binary args to prepared statement
310  * @return 0 for success or error code
311  */
312  int (*pvbselect)(apr_pool_t *pool, apr_dbd_t *handle,
313  apr_dbd_results_t **res,
314  apr_dbd_prepared_t *statement, int random, va_list args);
315 
316  /** pbquery: query using a prepared statement + binary args
317  *
318  * @param pool - working pool
319  * @param handle - the connection
320  * @param nrows - number of rows affected.
321  * @param statement - the prepared statement to execute
322  * @param args - binary args to prepared statement
323  * @return 0 for success or error code
324  */
325  int (*pbquery)(apr_pool_t *pool, apr_dbd_t *handle, int *nrows,
326  apr_dbd_prepared_t *statement,const void **args);
327 
328  /** pbselect: select using a prepared statement + binary args
329  *
330  * @param pool - working pool
331  * @param handle - the connection
332  * @param res - pointer to query results. May point to NULL on entry
333  * @param statement - the prepared statement to execute
334  * @param random - Whether to support random-access to results
335  * @param args - binary args to prepared statement
336  * @return 0 for success or error code
337  */
338  int (*pbselect)(apr_pool_t *pool, apr_dbd_t *handle,
339  apr_dbd_results_t **res, apr_dbd_prepared_t *statement,
340  int random, const void **args);
341 
342  /** datum_get: get a binary entry from a row
343  *
344  * @param row - row pointer
345  * @param col - entry number
346  * @param type - type of data to get
347  * @param data - pointer to data, allocated by the caller
348  * @return APR_SUCCESS, an error code on error or if col is out of bounds
349  */
350  apr_status_t (*datum_get)(const apr_dbd_row_t *row, int col,
351  apr_dbd_type_e type, void *data);
352 };
353 
354 /* Export mutex lock/unlock for drivers that need it
355  * deprecated; create a per-dbd mutex within the (*init) function
356  * to avoid blocking other providers running on other threads
357  */
358 APR_DECLARE(apr_status_t) apr_dbd_mutex_lock(void);
359 APR_DECLARE(apr_status_t) apr_dbd_mutex_unlock(void);
360 
361 #ifdef __cplusplus
362 }
363 #endif
364 
365 #endif
int(* transaction_mode_set)(apr_dbd_transaction_t *trans, int mode)
Definition: apr_dbd_internal.h:285
int(* start_transaction)(apr_pool_t *pool, apr_dbd_t *handle, apr_dbd_transaction_t **trans)
Definition: apr_dbd_internal.h:103
apr_status_t(* datum_get)(const apr_dbd_row_t *row, int col, apr_dbd_type_e type, void *data)
Definition: apr_dbd_internal.h:350
apr_status_t(* check_conn)(apr_pool_t *pool, apr_dbd_t *handle)
Definition: apr_dbd_internal.h:78
int(* pvbselect)(apr_pool_t *pool, apr_dbd_t *handle, apr_dbd_results_t **res, apr_dbd_prepared_t *statement, int random, va_list args)
Definition: apr_dbd_internal.h:312
apr_status_t(* close)(apr_dbd_t *handle)
Definition: apr_dbd_internal.h:85
int(* set_dbname)(apr_pool_t *pool, apr_dbd_t *handle, const char *name)
Definition: apr_dbd_internal.h:94
int(* num_tuples)(apr_dbd_results_t *res)
Definition: apr_dbd_internal.h:151
int(* pvquery)(apr_pool_t *pool, apr_dbd_t *handle, int *nrows, apr_dbd_prepared_t *statement, va_list args)
Definition: apr_dbd_internal.h:220
int(* pvbquery)(apr_pool_t *pool, apr_dbd_t *handle, int *nrows, apr_dbd_prepared_t *statement, va_list args)
Definition: apr_dbd_internal.h:299
void(* init)(apr_pool_t *pool)
Definition: apr_dbd_internal.h:50
int(* query)(apr_dbd_t *handle, int *nrows, const char *statement)
Definition: apr_dbd_internal.h:122
APR-UTIL DBD library.
const char * pformat
Definition: apr_dbd_internal.h:288
int(* pbquery)(apr_pool_t *pool, apr_dbd_t *handle, int *nrows, apr_dbd_prepared_t *statement, const void **args)
Definition: apr_dbd_internal.h:325
const char *(* error)(apr_dbd_t *handle, int errnum)
Definition: apr_dbd_internal.h:181
#define APR_DECLARE(type)
Definition: apr.h:500
apr_dbd_type_e
Definition: apr_dbd.h:55
const char * name
Definition: apr_dbd_internal.h:45
int(* get_row)(apr_pool_t *pool, apr_dbd_results_t *res, apr_dbd_row_t **row, int rownum)
Definition: apr_dbd_internal.h:162
int(* prepare)(apr_pool_t *pool, apr_dbd_t *handle, const char *query, const char *label, int nargs, int nvals, apr_dbd_type_e *types, apr_dbd_prepared_t **statement)
Definition: apr_dbd_internal.h:207
int(* end_transaction)(apr_dbd_transaction_t *trans)
Definition: apr_dbd_internal.h:113
Definition: apr_dbd_internal.h:43
int(* select)(apr_pool_t *pool, apr_dbd_t *handle, apr_dbd_results_t **res, const char *statement, int random)
Definition: apr_dbd_internal.h:135
struct apr_pool_t apr_pool_t
Definition: apr_pools.h:60
int(* transaction_mode_get)(apr_dbd_transaction_t *trans)
Definition: apr_dbd_internal.h:277
int apr_status_t
Definition: apr_errno.h:44
int(* num_cols)(apr_dbd_results_t *res)
Definition: apr_dbd_internal.h:143
int(* pvselect)(apr_pool_t *pool, apr_dbd_t *handle, apr_dbd_results_t **res, apr_dbd_prepared_t *statement, int random, va_list args)
Definition: apr_dbd_internal.h:233
int(* pbselect)(apr_pool_t *pool, apr_dbd_t *handle, apr_dbd_results_t **res, apr_dbd_prepared_t *statement, int random, const void **args)
Definition: apr_dbd_internal.h:338
int(* pquery)(apr_pool_t *pool, apr_dbd_t *handle, int *nrows, apr_dbd_prepared_t *statement, const char **args)
Definition: apr_dbd_internal.h:246
int(* pselect)(apr_pool_t *pool, apr_dbd_t *handle, apr_dbd_results_t **res, apr_dbd_prepared_t *statement, int random, const char **args)
Definition: apr_dbd_internal.h:259