/* Licensed to the Apache Software Foundation (ASF) under one or more
* contributor license agreements. See the NOTICE file distributed with
* this work for additional information regarding copyright ownership.
* The ASF licenses this file to You under the Apache License, Version 2.0
* (the "License"); you may not use this file except in compliance with
* the License. You may obtain a copy of the License at
*
* http://www.apache.org/licenses/LICENSE-2.0
*
* Unless required by applicable law or agreed to in writing, software
* distributed under the License is distributed on an "AS IS" BASIS,
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
* See the License for the specific language governing permissions and
* limitations under the License.
*/
/* Overview of what this is and does:
* http://www.apache.org/~niq/dbd.html
*/
#ifndef APR_DBD_INTERNAL_H
#define APR_DBD_INTERNAL_H
#include <stdarg.h>
#include "apr_dbd.h"
#ifdef __cplusplus
extern "C" {
#endif
#define TXN_IGNORE_ERRORS(t) \
((t) && ((t)->mode & APR_DBD_TRANSACTION_IGNORE_ERRORS))
#define TXN_NOTICE_ERRORS(t) \
((t) && !((t)->mode & APR_DBD_TRANSACTION_IGNORE_ERRORS))
#define TXN_DO_COMMIT(t) (!((t)->mode & APR_DBD_TRANSACTION_ROLLBACK))
#define TXN_DO_ROLLBACK(t) ((t)->mode & APR_DBD_TRANSACTION_ROLLBACK)
#define TXN_MODE_BITS \
(APR_DBD_TRANSACTION_ROLLBACK|APR_DBD_TRANSACTION_IGNORE_ERRORS)
struct apr_dbd_driver_t {
/** name */
const char *name;
/** init: allow driver to perform once-only initialisation.
* Called once only. May be NULL
*/
void (*init)(apr_pool_t *pool);
/** native_handle: return the native database handle of the underlying db
*
* @param handle - apr_dbd handle
* @return - native handle
*/
void *(*native_handle)(apr_dbd_t *handle);
/** open: obtain a database connection from the server rec.
* Must be explicitly closed when you're finished with it.
* WARNING: only use this when you need a connection with
* a lifetime other than a request
*
* @param pool - a pool to use for error messages (if any).
* @param params - connection parameters.
* @param error - descriptive error.
* @return database handle, or NULL on error.
*/
apr_dbd_t *(*open)(apr_pool_t *pool, const char *params,
const char **error);
/** check_conn: check status of a database connection
*
* @param pool - a pool to use for error messages (if any).
* @param handle - the connection to check
* @return APR_SUCCESS or error
*/
apr_status_t (*check_conn)(apr_pool_t *pool, apr_dbd_t *handle);
/** close: close/release a connection obtained from open()
*
* @param handle - the connection to release
* @return APR_SUCCESS or error
*/
apr_status_t (*close)(apr_dbd_t *handle);
/** set_dbname: select database name. May be a no-op if not supported.
*
* @param pool - working pool
* @param handle - the connection
* @param name - the database to select
* @return 0 for success or error code
*/
int (*set_dbname)(apr_pool_t* pool, apr_dbd_t *handle, const char *name);
/** transaction: start a transaction. May be a no-op.
*
* @param pool - a pool to use for error messages (if any).
* @param handle - the connection
* @param trans - ptr to a transaction. May be null on entry
* @return 0 for success or error code
*/
int (*start_transaction)(apr_pool_t *pool, apr_dbd_t *handle,
apr_dbd_transaction_t **trans);
/** end_transaction: end a transaction
* (commit on success, rollback on error).
* May be a no-op.
*
* @param trans - the transaction.
* @return 0 for success or error code
*/
int (*end_transaction)(apr_dbd_transaction_t *trans);
/** query: execute an SQL query that doesn't return a result set
*
* @param handle - the connection
* @param nrows - number of rows affected.
* @param statement - the SQL statement to execute
* @return 0 for success or error code
*/
int (*query)(apr_dbd_t *handle, int *nrows, const char *statement);
/** select: execute an SQL query that returns a result set
*
* @param pool - pool to allocate the result set
* @param handle - the connection
* @param res - pointer to result set pointer. May point to NULL on entry
* @param statement - the SQL statement to execute
* @param random - 1 to support random access to results (seek any row);
* 0 to support only looping through results in order
* (async access - faster)
* @return 0 for success or error code
*/
int (*select)(apr_pool_t *pool, apr_dbd_t *handle, apr_dbd_results_t **res,
const char *statement, int random);
/** num_cols: get the number of columns in a results set
*
* @param res - result set.
* @return number of columns
*/
int (*num_cols)(apr_dbd_results_t *res);
/** num_tuples: get the number of rows in a results set
* of a synchronous select
*
* @param res - result set.
* @return number of rows, or -1 if the results are asynchronous
*/
int (*num_tuples)(apr_dbd_results_t *res);
/** get_row: get a row from a result set
*
* @param pool - pool to allocate the row
* @param res - result set pointer
* @param row - pointer to row pointer. May point to NULL on entry
* @param rownum - row number, or -1 for "next row". Ignored if random
* access is not supported.
* @return 0 for success, -1 for rownum out of range or data finished
*/
int (*get_row)(apr_pool_t *pool, apr_dbd_results_t *res,
apr_dbd_row_t **row, int rownum);
/** get_entry: get an entry from a row
*
* @param row - row pointer
* @param col - entry number
* @param val - entry to fill
* @return 0 for success, -1 for no data, +1 for general error
*/
const char* (*get_entry)(const apr_dbd_row_t *row, int col);
/** error: get current error message (if any)
*
* @param handle - the connection
* @param errnum - error code from operation that returned an error
* @return the database current error message, or message for errnum
* (implementation-dependent whether errnum is ignored)
*/
const char *(*error)(apr_dbd_t *handle, int errnum);
/** escape: escape a string so it is safe for use in query/select
*
* @param pool - pool to alloc the result from
* @param string - the string to escape
* @param handle - the connection
* @return the escaped, safe string
*/
const char *(*escape)(apr_pool_t *pool, const char *string,
apr_dbd_t *handle);
/** prepare: prepare a statement
*
* @param pool - pool to alloc the result from
* @param handle - the connection
* @param query - the SQL query
* @param label - A label for the prepared statement.
* use NULL for temporary prepared statements
* (eg within a Request in httpd)
* @param nargs - number of parameters in the query
* @param nvals - number of values passed in p[b]query/select
* @param types - pointer to an array with types of parameters
* @param statement - statement to prepare. May point to null on entry.
* @return 0 for success or error code
*/
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);
/** pvquery: query using a prepared statement + args
*
* @param pool - working pool
* @param handle - the connection
* @param nrows - number of rows affected.
* @param statement - the prepared statement to execute
* @param args - args to prepared statement
* @return 0 for success or error code
*/
int (*pvquery)(apr_pool_t *pool, apr_dbd_t *handle, int *nrows,
apr_dbd_prepared_t *statement, va_list args);
/** pvselect: select using a prepared statement + args
*
* @param pool - working pool
* @param handle - the connection
* @param res - pointer to query results. May point to NULL on entry
* @param statement - the prepared statement to execute
* @param random - Whether to support random-access to results
* @param args - args to prepared statement
* @return 0 for success or error code
*/
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);
/** pquery: query using a prepared statement + args
*
* @param pool - working pool
* @param handle - the connection
* @param nrows - number of rows affected.
* @param statement - the prepared statement to execute
* @param args - args to prepared statement
* @return 0 for success or error code
*/
int (*pquery)(apr_pool_t *pool, apr_dbd_t *handle, int *nrows,
apr_dbd_prepared_t *statement, const char **args);
/** pselect: select using a prepared statement + args
*
* @param pool - working pool
* @param handle - the connection
* @param res - pointer to query results. May point to NULL on entry
* @param statement - the prepared statement to execute
* @param random - Whether to support random-access to results
* @param args - args to prepared statement
* @return 0 for success or error code
*/
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);
/** get_name: get a column title from a result set
*
* @param res - result set pointer
* @param col - entry number
* @return param name, or NULL if col is out of bounds.
*/
const char* (*get_name)(const apr_dbd_results_t *res, int col);
/** transaction_mode_get: get the mode of transaction
*
* @param trans - the transaction.
* @return mode of transaction
*/
int (*transaction_mode_get)(apr_dbd_transaction_t *trans);
/** transaction_mode_set: get the mode of transaction
*
* @param trans - the transaction.
* @param mode - new mode of the transaction
* @return the mode of transaction in force after the call
*/
int (*transaction_mode_set)(apr_dbd_transaction_t *trans, int mode);
/** format of prepared statement parameters */
const char *pformat;
/** pvbquery: query using a prepared statement + binary args
*
* @param pool - working pool
* @param handle - the connection
* @param nrows - number of rows affected.
* @param statement - the prepared statement to execute
* @param args - binary args to prepared statement
* @return 0 for success or error code
*/
int (*pvbquery)(apr_pool_t *pool, apr_dbd_t *handle, int *nrows,
apr_dbd_prepared_t *statement, va_list args);
/** pvbselect: select using a prepared statement + binary args
*
* @param pool - working pool
* @param handle - the connection
* @param res - pointer to query results. May point to NULL on entry
* @param statement - the prepared statement to execute
* @param random - Whether to support random-access to results
* @param args - binary args to prepared statement
* @return 0 for success or error code
*/
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);
/** pbquery: query using a prepared statement + binary args
*
* @param pool - working pool
* @param handle - the connection
* @param nrows - number of rows affected.
* @param statement - the prepared statement to execute
* @param args - binary args to prepared statement
* @return 0 for success or error code
*/
int (*pbquery)(apr_pool_t *pool, apr_dbd_t *handle, int *nrows,
apr_dbd_prepared_t *statement,const void **args);
/** pbselect: select using a prepared statement + binary args
*
* @param pool - working pool
* @param handle - the connection
* @param res - pointer to query results. May point to NULL on entry
* @param statement - the prepared statement to execute
* @param random - Whether to support random-access to results
* @param args - binary args to prepared statement
* @return 0 for success or error code
*/
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);
/** datum_get: get a binary entry from a row
*
* @param row - row pointer
* @param col - entry number
* @param type - type of data to get
* @param data - pointer to data, allocated by the caller
* @return APR_SUCCESS, an error code on error or if col is out of bounds
*/
apr_status_t (*datum_get)(const apr_dbd_row_t *row, int col,
apr_dbd_type_e type, void *data);
};
/* Export mutex lock/unlock for drivers that need it
* deprecated; create a per-dbd mutex within the (*init) function
* to avoid blocking other providers running on other threads
*/
APU_DECLARE(apr_status_t) apr_dbd_mutex_lock(void);
APU_DECLARE(apr_status_t) apr_dbd_mutex_unlock(void);
#ifdef __cplusplus
}
#endif
#endif