Apache Portable Runtime
apr_dbd_internal.h
00001 /* Licensed to the Apache Software Foundation (ASF) under one or more
00002  * contributor license agreements.  See the NOTICE file distributed with
00003  * this work for additional information regarding copyright ownership.
00004  * The ASF licenses this file to You under the Apache License, Version 2.0
00005  * (the "License"); you may not use this file except in compliance with
00006  * the License.  You may obtain a copy of the License at
00007  *
00008  *     http://www.apache.org/licenses/LICENSE-2.0
00009  *
00010  * Unless required by applicable law or agreed to in writing, software
00011  * distributed under the License is distributed on an "AS IS" BASIS,
00012  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
00013  * See the License for the specific language governing permissions and
00014  * limitations under the License.
00015  */
00016 
00017 /* Overview of what this is and does:
00018  * http://www.apache.org/~niq/dbd.html
00019  */
00020 
00021 #ifndef APR_DBD_INTERNAL_H
00022 #define APR_DBD_INTERNAL_H
00023 
00024 #include <stdarg.h>
00025 
00026 #include "apr_dbd.h"
00027 
00028 #ifdef __cplusplus
00029 extern "C" {
00030 #endif
00031 
00032 #define TXN_IGNORE_ERRORS(t) \
00033   ((t) && ((t)->mode & APR_DBD_TRANSACTION_IGNORE_ERRORS))
00034 #define TXN_NOTICE_ERRORS(t) \
00035   ((t) && !((t)->mode & APR_DBD_TRANSACTION_IGNORE_ERRORS))
00036 
00037 #define TXN_DO_COMMIT(t)   (!((t)->mode & APR_DBD_TRANSACTION_ROLLBACK))
00038 #define TXN_DO_ROLLBACK(t) ((t)->mode & APR_DBD_TRANSACTION_ROLLBACK)
00039 
00040 #define TXN_MODE_BITS \
00041   (APR_DBD_TRANSACTION_ROLLBACK|APR_DBD_TRANSACTION_IGNORE_ERRORS)
00042 
00043 struct apr_dbd_driver_t {
00044     /** name */
00045     const char *name;
00046 
00047     /** init: allow driver to perform once-only initialisation.
00048      *  Called once only.  May be NULL
00049      */
00050     void (*init)(apr_pool_t *pool);
00051 
00052     /** native_handle: return the native database handle of the underlying db
00053      *
00054      * @param handle - apr_dbd handle
00055      * @return - native handle
00056      */
00057     void *(*native_handle)(apr_dbd_t *handle);
00058 
00059     /** open: obtain a database connection from the server rec.
00060      *  Must be explicitly closed when you're finished with it.
00061      *  WARNING: only use this when you need a connection with
00062      *  a lifetime other than a request
00063      *
00064      *  @param pool - a pool to use for error messages (if any).
00065      *  @param params - connection parameters.
00066      *  @param error - descriptive error.
00067      *  @return database handle, or NULL on error.
00068      */
00069     apr_dbd_t *(*open)(apr_pool_t *pool, const char *params,
00070                        const char **error);
00071 
00072     /** check_conn: check status of a database connection
00073      *
00074      *  @param pool - a pool to use for error messages (if any).
00075      *  @param handle - the connection to check
00076      *  @return APR_SUCCESS or error
00077      */
00078     apr_status_t (*check_conn)(apr_pool_t *pool, apr_dbd_t *handle);
00079 
00080     /** close: close/release a connection obtained from open()
00081      *
00082      *  @param handle - the connection to release
00083      *  @return APR_SUCCESS or error
00084      */
00085     apr_status_t (*close)(apr_dbd_t *handle);
00086 
00087     /** set_dbname: select database name.  May be a no-op if not supported.
00088      *
00089      *  @param pool - working pool
00090      *  @param handle - the connection
00091      *  @param name - the database to select
00092      *  @return 0 for success or error code
00093      */
00094     int (*set_dbname)(apr_pool_t* pool, apr_dbd_t *handle, const char *name);
00095 
00096     /** transaction: start a transaction.  May be a no-op.
00097      *
00098      *  @param pool   - a pool to use for error messages (if any).
00099      *  @param handle - the connection
00100      *  @param trans  - ptr to a transaction.  May be null on entry
00101      *  @return 0 for success or error code
00102      */
00103     int (*start_transaction)(apr_pool_t *pool, apr_dbd_t *handle,
00104                              apr_dbd_transaction_t **trans);
00105 
00106     /** end_transaction: end a transaction
00107      *  (commit on success, rollback on error).
00108      *  May be a no-op.
00109      *
00110      *  @param trans - the transaction.
00111      *  @return 0 for success or error code
00112      */
00113     int (*end_transaction)(apr_dbd_transaction_t *trans);
00114 
00115     /** query: execute an SQL query that doesn't return a result set
00116      *
00117      *  @param handle - the connection
00118      *  @param nrows - number of rows affected.
00119      *  @param statement - the SQL statement to execute
00120      *  @return 0 for success or error code
00121      */
00122     int (*query)(apr_dbd_t *handle, int *nrows, const char *statement);
00123 
00124     /** select: execute an SQL query that returns a result set
00125      *
00126      *  @param pool - pool to allocate the result set
00127      *  @param handle - the connection
00128      *  @param res - pointer to result set pointer.  May point to NULL on entry
00129      *  @param statement - the SQL statement to execute
00130      *  @param random - 1 to support random access to results (seek any row);
00131      *                  0 to support only looping through results in order
00132      *                    (async access - faster)
00133      *  @return 0 for success or error code
00134      */
00135     int (*select)(apr_pool_t *pool, apr_dbd_t *handle, apr_dbd_results_t **res,
00136                   const char *statement, int random);
00137 
00138     /** num_cols: get the number of columns in a results set
00139      *
00140      *  @param res - result set.
00141      *  @return number of columns
00142      */
00143     int (*num_cols)(apr_dbd_results_t *res);
00144 
00145     /** num_tuples: get the number of rows in a results set
00146      *  of a synchronous select
00147      *
00148      *  @param res - result set.
00149      *  @return number of rows, or -1 if the results are asynchronous
00150      */
00151     int (*num_tuples)(apr_dbd_results_t *res);
00152 
00153     /** get_row: get a row from a result set
00154      *
00155      *  @param pool - pool to allocate the row
00156      *  @param res - result set pointer
00157      *  @param row - pointer to row pointer.  May point to NULL on entry
00158      *  @param rownum - row number, or -1 for "next row".  Ignored if random
00159      *                  access is not supported.
00160      *  @return 0 for success, -1 for rownum out of range or data finished
00161      */
00162     int (*get_row)(apr_pool_t *pool, apr_dbd_results_t *res,
00163                    apr_dbd_row_t **row, int rownum);
00164   
00165     /** get_entry: get an entry from a row
00166      *
00167      *  @param row - row pointer
00168      *  @param col - entry number
00169      *  @param val - entry to fill
00170      *  @return 0 for success, -1 for no data, +1 for general error
00171      */
00172     const char* (*get_entry)(const apr_dbd_row_t *row, int col);
00173   
00174     /** error: get current error message (if any)
00175      *
00176      *  @param handle - the connection
00177      *  @param errnum - error code from operation that returned an error
00178      *  @return the database current error message, or message for errnum
00179      *          (implementation-dependent whether errnum is ignored)
00180      */
00181     const char *(*error)(apr_dbd_t *handle, int errnum);
00182   
00183     /** escape: escape a string so it is safe for use in query/select
00184      *
00185      *  @param pool - pool to alloc the result from
00186      *  @param string - the string to escape
00187      *  @param handle - the connection
00188      *  @return the escaped, safe string
00189      */
00190     const char *(*escape)(apr_pool_t *pool, const char *string,
00191                           apr_dbd_t *handle);
00192   
00193     /** prepare: prepare a statement
00194      *
00195      *  @param pool - pool to alloc the result from
00196      *  @param handle - the connection
00197      *  @param query - the SQL query
00198      *  @param label - A label for the prepared statement.
00199      *                 use NULL for temporary prepared statements
00200      *                 (eg within a Request in httpd)
00201      *  @param nargs - number of parameters in the query
00202      *  @param nvals - number of values passed in p[b]query/select
00203      *  @param types - pointer to an array with types of parameters
00204      *  @param statement - statement to prepare.  May point to null on entry.
00205      *  @return 0 for success or error code
00206      */
00207     int (*prepare)(apr_pool_t *pool, apr_dbd_t *handle, const char *query,
00208                    const char *label, int nargs, int nvals,
00209                    apr_dbd_type_e *types, apr_dbd_prepared_t **statement);
00210 
00211     /** pvquery: query using a prepared statement + args
00212      *
00213      *  @param pool - working pool
00214      *  @param handle - the connection
00215      *  @param nrows - number of rows affected.
00216      *  @param statement - the prepared statement to execute
00217      *  @param args - args to prepared statement
00218      *  @return 0 for success or error code
00219      */
00220     int (*pvquery)(apr_pool_t *pool, apr_dbd_t *handle, int *nrows,
00221                    apr_dbd_prepared_t *statement, va_list args);
00222 
00223     /** pvselect: select using a prepared statement + args
00224      *
00225      *  @param pool - working pool
00226      *  @param handle - the connection
00227      *  @param res - pointer to query results.  May point to NULL on entry
00228      *  @param statement - the prepared statement to execute
00229      *  @param random - Whether to support random-access to results
00230      *  @param args - args to prepared statement
00231      *  @return 0 for success or error code
00232      */
00233     int (*pvselect)(apr_pool_t *pool, apr_dbd_t *handle,
00234                     apr_dbd_results_t **res,
00235                     apr_dbd_prepared_t *statement, int random, va_list args);
00236 
00237     /** pquery: query using a prepared statement + args
00238      *
00239      *  @param pool - working pool
00240      *  @param handle - the connection
00241      *  @param nrows - number of rows affected.
00242      *  @param statement - the prepared statement to execute
00243      *  @param args - args to prepared statement
00244      *  @return 0 for success or error code
00245      */
00246     int (*pquery)(apr_pool_t *pool, apr_dbd_t *handle, int *nrows,
00247                   apr_dbd_prepared_t *statement, const char **args);
00248 
00249     /** pselect: select using a prepared statement + args
00250      *
00251      *  @param pool - working pool
00252      *  @param handle - the connection
00253      *  @param res - pointer to query results.  May point to NULL on entry
00254      *  @param statement - the prepared statement to execute
00255      *  @param random - Whether to support random-access to results
00256      *  @param args - args to prepared statement
00257      *  @return 0 for success or error code
00258      */
00259     int (*pselect)(apr_pool_t *pool, apr_dbd_t *handle,
00260                    apr_dbd_results_t **res, apr_dbd_prepared_t *statement,
00261                    int random, const char **args);
00262 
00263   
00264     /** get_name: get a column title from a result set
00265      *
00266      *  @param res - result set pointer
00267      *  @param col - entry number
00268      *  @return param name, or NULL if col is out of bounds.
00269      */
00270     const char* (*get_name)(const apr_dbd_results_t *res, int col);
00271 
00272     /** transaction_mode_get: get the mode of transaction
00273      *
00274      *  @param trans - the transaction.
00275      *  @return mode of transaction
00276      */
00277     int (*transaction_mode_get)(apr_dbd_transaction_t *trans);
00278 
00279     /** transaction_mode_set: get the mode of transaction
00280      *
00281      *  @param trans - the transaction.
00282      *  @param mode  - new mode of the transaction
00283      *  @return the mode of transaction in force after the call
00284      */
00285     int (*transaction_mode_set)(apr_dbd_transaction_t *trans, int mode);
00286 
00287     /** format of prepared statement parameters */
00288     const char *pformat;
00289 
00290     /** pvbquery: query using a prepared statement + binary args
00291      *
00292      *  @param pool - working pool
00293      *  @param handle - the connection
00294      *  @param nrows - number of rows affected.
00295      *  @param statement - the prepared statement to execute
00296      *  @param args - binary args to prepared statement
00297      *  @return 0 for success or error code
00298      */
00299     int (*pvbquery)(apr_pool_t *pool, apr_dbd_t *handle, int *nrows,
00300                     apr_dbd_prepared_t *statement, va_list args);
00301 
00302     /** pvbselect: select using a prepared statement + binary args
00303      *
00304      *  @param pool - working pool
00305      *  @param handle - the connection
00306      *  @param res - pointer to query results.  May point to NULL on entry
00307      *  @param statement - the prepared statement to execute
00308      *  @param random - Whether to support random-access to results
00309      *  @param args - binary args to prepared statement
00310      *  @return 0 for success or error code
00311      */
00312     int (*pvbselect)(apr_pool_t *pool, apr_dbd_t *handle,
00313                      apr_dbd_results_t **res,
00314                      apr_dbd_prepared_t *statement, int random, va_list args);
00315 
00316     /** pbquery: query using a prepared statement + binary args
00317      *
00318      *  @param pool - working pool
00319      *  @param handle - the connection
00320      *  @param nrows - number of rows affected.
00321      *  @param statement - the prepared statement to execute
00322      *  @param args - binary args to prepared statement
00323      *  @return 0 for success or error code
00324      */
00325     int (*pbquery)(apr_pool_t *pool, apr_dbd_t *handle, int *nrows,
00326                    apr_dbd_prepared_t *statement,const void **args);
00327 
00328     /** pbselect: select using a prepared statement + binary args
00329      *
00330      *  @param pool - working pool
00331      *  @param handle - the connection
00332      *  @param res - pointer to query results.  May point to NULL on entry
00333      *  @param statement - the prepared statement to execute
00334      *  @param random - Whether to support random-access to results
00335      *  @param args - binary args to prepared statement
00336      *  @return 0 for success or error code
00337      */
00338     int (*pbselect)(apr_pool_t *pool, apr_dbd_t *handle,
00339                     apr_dbd_results_t **res, apr_dbd_prepared_t *statement,
00340                     int random, const void **args);
00341   
00342     /** datum_get: get a binary entry from a row
00343      *
00344      *  @param row - row pointer
00345      *  @param col - entry number
00346      *  @param type - type of data to get
00347      *  @param data - pointer to data, allocated by the caller
00348      *  @return APR_SUCCESS, an error code on error or if col is out of bounds
00349      */
00350     apr_status_t (*datum_get)(const apr_dbd_row_t *row, int col,
00351                               apr_dbd_type_e type, void *data);
00352 };
00353 
00354 /* Export mutex lock/unlock for drivers that need it 
00355  * deprecated; create a per-dbd mutex within the (*init) function
00356  * to avoid blocking other providers running on other threads
00357  */
00358 APR_DECLARE(apr_status_t) apr_dbd_mutex_lock(void);
00359 APR_DECLARE(apr_status_t) apr_dbd_mutex_unlock(void);
00360 
00361 #ifdef __cplusplus
00362 }
00363 #endif
00364 
00365 #endif
 All Data Structures Namespaces Files Functions Variables Typedefs Enumerations Enumerator Defines