Annotation of win32/apache22/srclib/apr-util/include/private/apr_dbd_internal.h, revision 1.1
1.1 ! moko 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:
! 43: struct apr_dbd_driver_t {
! 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: APU_DECLARE(apr_status_t) apr_dbd_mutex_lock(void);
! 359: APU_DECLARE(apr_status_t) apr_dbd_mutex_unlock(void);
! 360:
! 361: #ifdef __cplusplus
! 362: }
! 363: #endif
! 364:
! 365: #endif
E-mail:
![[BACK]](/cvsweb/icons/back.gif){kind=icon}
Return to apr_dbd_internal.h CVS log ![[TXT]](/cvsweb/icons/text.gif){kind=icon}
![[DIR]](/cvsweb/icons/dir.gif){kind=icon}
Up to [parser3project] / win32 / apache22 / srclib / apr-util / include / private