1251876Speter/* Licensed to the Apache Software Foundation (ASF) under one or more 2251876Speter * contributor license agreements. See the NOTICE file distributed with 3251876Speter * this work for additional information regarding copyright ownership. 4251876Speter * The ASF licenses this file to You under the Apache License, Version 2.0 5251876Speter * (the "License"); you may not use this file except in compliance with 6251876Speter * the License. You may obtain a copy of the License at 7251876Speter * 8251876Speter * http://www.apache.org/licenses/LICENSE-2.0 9251876Speter * 10251876Speter * Unless required by applicable law or agreed to in writing, software 11251876Speter * distributed under the License is distributed on an "AS IS" BASIS, 12251876Speter * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 13251876Speter * See the License for the specific language governing permissions and 14251876Speter * limitations under the License. 15251876Speter */ 16251876Speter 17251876Speter/* Overview of what this is and does: 18251876Speter * http://www.apache.org/~niq/dbd.html 19251876Speter */ 20251876Speter 21251876Speter#ifndef APR_DBD_INTERNAL_H 22251876Speter#define APR_DBD_INTERNAL_H 23251876Speter 24251876Speter#include <stdarg.h> 25251876Speter 26251876Speter#include "apr_dbd.h" 27251876Speter 28251876Speter#ifdef __cplusplus 29251876Speterextern "C" { 30251876Speter#endif 31251876Speter 32251876Speter#define TXN_IGNORE_ERRORS(t) \ 33251876Speter ((t) && ((t)->mode & APR_DBD_TRANSACTION_IGNORE_ERRORS)) 34251876Speter#define TXN_NOTICE_ERRORS(t) \ 35251876Speter ((t) && !((t)->mode & APR_DBD_TRANSACTION_IGNORE_ERRORS)) 36251876Speter 37251876Speter#define TXN_DO_COMMIT(t) (!((t)->mode & APR_DBD_TRANSACTION_ROLLBACK)) 38251876Speter#define TXN_DO_ROLLBACK(t) ((t)->mode & APR_DBD_TRANSACTION_ROLLBACK) 39251876Speter 40251876Speter#define TXN_MODE_BITS \ 41251876Speter (APR_DBD_TRANSACTION_ROLLBACK|APR_DBD_TRANSACTION_IGNORE_ERRORS) 42251876Speter 43251876Speterstruct apr_dbd_driver_t { 44251876Speter /** name */ 45251876Speter const char *name; 46251876Speter 47251876Speter /** init: allow driver to perform once-only initialisation. 48251876Speter * Called once only. May be NULL 49251876Speter */ 50251876Speter void (*init)(apr_pool_t *pool); 51251876Speter 52251876Speter /** native_handle: return the native database handle of the underlying db 53251876Speter * 54251876Speter * @param handle - apr_dbd handle 55251876Speter * @return - native handle 56251876Speter */ 57251876Speter void *(*native_handle)(apr_dbd_t *handle); 58251876Speter 59251876Speter /** open: obtain a database connection from the server rec. 60251876Speter * Must be explicitly closed when you're finished with it. 61251876Speter * WARNING: only use this when you need a connection with 62251876Speter * a lifetime other than a request 63251876Speter * 64251876Speter * @param pool - a pool to use for error messages (if any). 65251876Speter * @param params - connection parameters. 66251876Speter * @param error - descriptive error. 67251876Speter * @return database handle, or NULL on error. 68251876Speter */ 69251876Speter apr_dbd_t *(*open)(apr_pool_t *pool, const char *params, 70251876Speter const char **error); 71251876Speter 72251876Speter /** check_conn: check status of a database connection 73251876Speter * 74251876Speter * @param pool - a pool to use for error messages (if any). 75251876Speter * @param handle - the connection to check 76251876Speter * @return APR_SUCCESS or error 77251876Speter */ 78251876Speter apr_status_t (*check_conn)(apr_pool_t *pool, apr_dbd_t *handle); 79251876Speter 80251876Speter /** close: close/release a connection obtained from open() 81251876Speter * 82251876Speter * @param handle - the connection to release 83251876Speter * @return APR_SUCCESS or error 84251876Speter */ 85251876Speter apr_status_t (*close)(apr_dbd_t *handle); 86251876Speter 87251876Speter /** set_dbname: select database name. May be a no-op if not supported. 88251876Speter * 89251876Speter * @param pool - working pool 90251876Speter * @param handle - the connection 91251876Speter * @param name - the database to select 92251876Speter * @return 0 for success or error code 93251876Speter */ 94251876Speter int (*set_dbname)(apr_pool_t* pool, apr_dbd_t *handle, const char *name); 95251876Speter 96251876Speter /** transaction: start a transaction. May be a no-op. 97251876Speter * 98251876Speter * @param pool - a pool to use for error messages (if any). 99251876Speter * @param handle - the connection 100251876Speter * @param trans - ptr to a transaction. May be null on entry 101251876Speter * @return 0 for success or error code 102251876Speter */ 103251876Speter int (*start_transaction)(apr_pool_t *pool, apr_dbd_t *handle, 104251876Speter apr_dbd_transaction_t **trans); 105251876Speter 106251876Speter /** end_transaction: end a transaction 107251876Speter * (commit on success, rollback on error). 108251876Speter * May be a no-op. 109251876Speter * 110251876Speter * @param trans - the transaction. 111251876Speter * @return 0 for success or error code 112251876Speter */ 113251876Speter int (*end_transaction)(apr_dbd_transaction_t *trans); 114251876Speter 115251876Speter /** query: execute an SQL query that doesn't return a result set 116251876Speter * 117251876Speter * @param handle - the connection 118251876Speter * @param nrows - number of rows affected. 119251876Speter * @param statement - the SQL statement to execute 120251876Speter * @return 0 for success or error code 121251876Speter */ 122251876Speter int (*query)(apr_dbd_t *handle, int *nrows, const char *statement); 123251876Speter 124251876Speter /** select: execute an SQL query that returns a result set 125251876Speter * 126251876Speter * @param pool - pool to allocate the result set 127251876Speter * @param handle - the connection 128251876Speter * @param res - pointer to result set pointer. May point to NULL on entry 129251876Speter * @param statement - the SQL statement to execute 130251876Speter * @param random - 1 to support random access to results (seek any row); 131251876Speter * 0 to support only looping through results in order 132251876Speter * (async access - faster) 133251876Speter * @return 0 for success or error code 134251876Speter */ 135251876Speter int (*select)(apr_pool_t *pool, apr_dbd_t *handle, apr_dbd_results_t **res, 136251876Speter const char *statement, int random); 137251876Speter 138251876Speter /** num_cols: get the number of columns in a results set 139251876Speter * 140251876Speter * @param res - result set. 141251876Speter * @return number of columns 142251876Speter */ 143251876Speter int (*num_cols)(apr_dbd_results_t *res); 144251876Speter 145251876Speter /** num_tuples: get the number of rows in a results set 146251876Speter * of a synchronous select 147251876Speter * 148251876Speter * @param res - result set. 149251876Speter * @return number of rows, or -1 if the results are asynchronous 150251876Speter */ 151251876Speter int (*num_tuples)(apr_dbd_results_t *res); 152251876Speter 153251876Speter /** get_row: get a row from a result set 154251876Speter * 155251876Speter * @param pool - pool to allocate the row 156251876Speter * @param res - result set pointer 157251876Speter * @param row - pointer to row pointer. May point to NULL on entry 158251876Speter * @param rownum - row number, or -1 for "next row". Ignored if random 159251876Speter * access is not supported. 160251876Speter * @return 0 for success, -1 for rownum out of range or data finished 161251876Speter */ 162251876Speter int (*get_row)(apr_pool_t *pool, apr_dbd_results_t *res, 163251876Speter apr_dbd_row_t **row, int rownum); 164251876Speter 165251876Speter /** get_entry: get an entry from a row 166251876Speter * 167251876Speter * @param row - row pointer 168251876Speter * @param col - entry number 169251876Speter * @param val - entry to fill 170251876Speter * @return 0 for success, -1 for no data, +1 for general error 171251876Speter */ 172251876Speter const char* (*get_entry)(const apr_dbd_row_t *row, int col); 173251876Speter 174251876Speter /** error: get current error message (if any) 175251876Speter * 176251876Speter * @param handle - the connection 177251876Speter * @param errnum - error code from operation that returned an error 178251876Speter * @return the database current error message, or message for errnum 179251876Speter * (implementation-dependent whether errnum is ignored) 180251876Speter */ 181251876Speter const char *(*error)(apr_dbd_t *handle, int errnum); 182251876Speter 183251876Speter /** escape: escape a string so it is safe for use in query/select 184251876Speter * 185251876Speter * @param pool - pool to alloc the result from 186251876Speter * @param string - the string to escape 187251876Speter * @param handle - the connection 188251876Speter * @return the escaped, safe string 189251876Speter */ 190251876Speter const char *(*escape)(apr_pool_t *pool, const char *string, 191251876Speter apr_dbd_t *handle); 192251876Speter 193251876Speter /** prepare: prepare a statement 194251876Speter * 195251876Speter * @param pool - pool to alloc the result from 196251876Speter * @param handle - the connection 197251876Speter * @param query - the SQL query 198251876Speter * @param label - A label for the prepared statement. 199251876Speter * use NULL for temporary prepared statements 200251876Speter * (eg within a Request in httpd) 201251876Speter * @param nargs - number of parameters in the query 202251876Speter * @param nvals - number of values passed in p[b]query/select 203251876Speter * @param types - pointer to an array with types of parameters 204251876Speter * @param statement - statement to prepare. May point to null on entry. 205251876Speter * @return 0 for success or error code 206251876Speter */ 207251876Speter int (*prepare)(apr_pool_t *pool, apr_dbd_t *handle, const char *query, 208251876Speter const char *label, int nargs, int nvals, 209251876Speter apr_dbd_type_e *types, apr_dbd_prepared_t **statement); 210251876Speter 211251876Speter /** pvquery: query using a prepared statement + args 212251876Speter * 213251876Speter * @param pool - working pool 214251876Speter * @param handle - the connection 215251876Speter * @param nrows - number of rows affected. 216251876Speter * @param statement - the prepared statement to execute 217251876Speter * @param args - args to prepared statement 218251876Speter * @return 0 for success or error code 219251876Speter */ 220251876Speter int (*pvquery)(apr_pool_t *pool, apr_dbd_t *handle, int *nrows, 221251876Speter apr_dbd_prepared_t *statement, va_list args); 222251876Speter 223251876Speter /** pvselect: select using a prepared statement + args 224251876Speter * 225251876Speter * @param pool - working pool 226251876Speter * @param handle - the connection 227251876Speter * @param res - pointer to query results. May point to NULL on entry 228251876Speter * @param statement - the prepared statement to execute 229251876Speter * @param random - Whether to support random-access to results 230251876Speter * @param args - args to prepared statement 231251876Speter * @return 0 for success or error code 232251876Speter */ 233251876Speter int (*pvselect)(apr_pool_t *pool, apr_dbd_t *handle, 234251876Speter apr_dbd_results_t **res, 235251876Speter apr_dbd_prepared_t *statement, int random, va_list args); 236251876Speter 237251876Speter /** pquery: query using a prepared statement + args 238251876Speter * 239251876Speter * @param pool - working pool 240251876Speter * @param handle - the connection 241251876Speter * @param nrows - number of rows affected. 242251876Speter * @param statement - the prepared statement to execute 243251876Speter * @param args - args to prepared statement 244251876Speter * @return 0 for success or error code 245251876Speter */ 246251876Speter int (*pquery)(apr_pool_t *pool, apr_dbd_t *handle, int *nrows, 247251876Speter apr_dbd_prepared_t *statement, const char **args); 248251876Speter 249251876Speter /** pselect: select using a prepared statement + args 250251876Speter * 251251876Speter * @param pool - working pool 252251876Speter * @param handle - the connection 253251876Speter * @param res - pointer to query results. May point to NULL on entry 254251876Speter * @param statement - the prepared statement to execute 255251876Speter * @param random - Whether to support random-access to results 256251876Speter * @param args - args to prepared statement 257251876Speter * @return 0 for success or error code 258251876Speter */ 259251876Speter int (*pselect)(apr_pool_t *pool, apr_dbd_t *handle, 260251876Speter apr_dbd_results_t **res, apr_dbd_prepared_t *statement, 261251876Speter int random, const char **args); 262251876Speter 263251876Speter 264251876Speter /** get_name: get a column title from a result set 265251876Speter * 266251876Speter * @param res - result set pointer 267251876Speter * @param col - entry number 268251876Speter * @return param name, or NULL if col is out of bounds. 269251876Speter */ 270251876Speter const char* (*get_name)(const apr_dbd_results_t *res, int col); 271251876Speter 272251876Speter /** transaction_mode_get: get the mode of transaction 273251876Speter * 274251876Speter * @param trans - the transaction. 275251876Speter * @return mode of transaction 276251876Speter */ 277251876Speter int (*transaction_mode_get)(apr_dbd_transaction_t *trans); 278251876Speter 279251876Speter /** transaction_mode_set: get the mode of transaction 280251876Speter * 281251876Speter * @param trans - the transaction. 282251876Speter * @param mode - new mode of the transaction 283251876Speter * @return the mode of transaction in force after the call 284251876Speter */ 285251876Speter int (*transaction_mode_set)(apr_dbd_transaction_t *trans, int mode); 286251876Speter 287251876Speter /** format of prepared statement parameters */ 288251876Speter const char *pformat; 289251876Speter 290251876Speter /** pvbquery: query using a prepared statement + binary args 291251876Speter * 292251876Speter * @param pool - working pool 293251876Speter * @param handle - the connection 294251876Speter * @param nrows - number of rows affected. 295251876Speter * @param statement - the prepared statement to execute 296251876Speter * @param args - binary args to prepared statement 297251876Speter * @return 0 for success or error code 298251876Speter */ 299251876Speter int (*pvbquery)(apr_pool_t *pool, apr_dbd_t *handle, int *nrows, 300251876Speter apr_dbd_prepared_t *statement, va_list args); 301251876Speter 302251876Speter /** pvbselect: select using a prepared statement + binary args 303251876Speter * 304251876Speter * @param pool - working pool 305251876Speter * @param handle - the connection 306251876Speter * @param res - pointer to query results. May point to NULL on entry 307251876Speter * @param statement - the prepared statement to execute 308251876Speter * @param random - Whether to support random-access to results 309251876Speter * @param args - binary args to prepared statement 310251876Speter * @return 0 for success or error code 311251876Speter */ 312251876Speter int (*pvbselect)(apr_pool_t *pool, apr_dbd_t *handle, 313251876Speter apr_dbd_results_t **res, 314251876Speter apr_dbd_prepared_t *statement, int random, va_list args); 315251876Speter 316251876Speter /** pbquery: query using a prepared statement + binary args 317251876Speter * 318251876Speter * @param pool - working pool 319251876Speter * @param handle - the connection 320251876Speter * @param nrows - number of rows affected. 321251876Speter * @param statement - the prepared statement to execute 322251876Speter * @param args - binary args to prepared statement 323251876Speter * @return 0 for success or error code 324251876Speter */ 325251876Speter int (*pbquery)(apr_pool_t *pool, apr_dbd_t *handle, int *nrows, 326251876Speter apr_dbd_prepared_t *statement,const void **args); 327251876Speter 328251876Speter /** pbselect: select using a prepared statement + binary args 329251876Speter * 330251876Speter * @param pool - working pool 331251876Speter * @param handle - the connection 332251876Speter * @param res - pointer to query results. May point to NULL on entry 333251876Speter * @param statement - the prepared statement to execute 334251876Speter * @param random - Whether to support random-access to results 335251876Speter * @param args - binary args to prepared statement 336251876Speter * @return 0 for success or error code 337251876Speter */ 338251876Speter int (*pbselect)(apr_pool_t *pool, apr_dbd_t *handle, 339251876Speter apr_dbd_results_t **res, apr_dbd_prepared_t *statement, 340251876Speter int random, const void **args); 341251876Speter 342251876Speter /** datum_get: get a binary entry from a row 343251876Speter * 344251876Speter * @param row - row pointer 345251876Speter * @param col - entry number 346251876Speter * @param type - type of data to get 347251876Speter * @param data - pointer to data, allocated by the caller 348251876Speter * @return APR_SUCCESS, an error code on error or if col is out of bounds 349251876Speter */ 350251876Speter apr_status_t (*datum_get)(const apr_dbd_row_t *row, int col, 351251876Speter apr_dbd_type_e type, void *data); 352251876Speter}; 353251876Speter 354251876Speter/* Export mutex lock/unlock for drivers that need it 355251876Speter * deprecated; create a per-dbd mutex within the (*init) function 356251876Speter * to avoid blocking other providers running on other threads 357251876Speter */ 358251876SpeterAPU_DECLARE(apr_status_t) apr_dbd_mutex_lock(void); 359251876SpeterAPU_DECLARE(apr_status_t) apr_dbd_mutex_unlock(void); 360251876Speter 361251876Speter#ifdef __cplusplus 362251876Speter} 363251876Speter#endif 364251876Speter 365251876Speter#endif 366