apr_dbd.h

Go to the documentation of this file.
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_H
00022 #define APR_DBD_H
00023 
00024 #ifdef __cplusplus
00025 extern "C" {
00026 #endif
00027 
00028 /**
00029  * @file apr_dbd.h
00030  * @brief APR-UTIL DBD library
00031  */
00032 /**
00033  * @defgroup APR_Util_DBD DBD routines
00034  * @ingroup APR_Util
00035  * @{
00036  */
00037 
00038 /* These are opaque structs.  Instantiation is up to each backend */
00039 typedef struct apr_dbd_driver_t apr_dbd_driver_t;
00040 typedef struct apr_dbd_t apr_dbd_t;
00041 typedef struct apr_dbd_transaction_t apr_dbd_transaction_t;
00042 typedef struct apr_dbd_results_t apr_dbd_results_t;
00043 typedef struct apr_dbd_row_t apr_dbd_row_t;
00044 typedef struct apr_dbd_prepared_t apr_dbd_prepared_t;
00045 
00046 /** apr_dbd_init: perform once-only initialisation.  Call once only.
00047  *
00048  *  @param pool - pool to register any shutdown cleanups, etc
00049  */
00050 APU_DECLARE(apr_status_t) apr_dbd_init(apr_pool_t *pool);
00051 
00052 /** apr_dbd_get_driver: get the driver struct for a name
00053  *
00054  *  @param pool - (process) pool to register cleanup
00055  *  @param name - driver name
00056  *  @param driver - pointer to driver struct.
00057  *  @return APR_SUCCESS for success
00058  *  @return APR_ENOTIMPL for no driver (when DSO not enabled)
00059  *  @return APR_EDSOOPEN if DSO driver file can't be opened
00060  *  @return APR_ESYMNOTFOUND if the driver file doesn't contain a driver
00061  */
00062 APU_DECLARE(apr_status_t) apr_dbd_get_driver(apr_pool_t *pool, const char *name,
00063                                              const apr_dbd_driver_t **driver);
00064 
00065 /** apr_dbd_open: open a connection to a backend
00066  *
00067  *  @param pool - working pool
00068  *  @param params - arguments to driver (implementation-dependent)
00069  *  @param handle - pointer to handle to return
00070  *  @param driver - driver struct.
00071  *  @return APR_SUCCESS for success
00072  *  @return APR_EGENERAL if driver exists but connection failed
00073  *  @remarks PostgreSQL: the params is passed directly to the PQconnectdb()
00074  *  function (check PostgreSQL documentation for more details on the syntax).
00075  *  @remarks SQLite2: the params is split on a colon, with the first part used
00076  *  as the filename and second part converted to an integer and used as file
00077  *  mode.
00078  *  @remarks SQLite3: the params is passed directly to the sqlite3_open()
00079  *  function as a filename to be opened (check SQLite3 documentation for more
00080  *  details).
00081  *  @remarks MySQL: the params can have "host", "port", "user", "pass",
00082  *  "dbname", "sock", "flags" "fldsz" and "group" keys, each followed by an
00083  *  equal sign and a value. Such key/value pairs can be delimited by space,
00084  *  CR, LF, tab, semicolon, vertical bar or comma. For now, "flags" can only
00085  *  recognise CLIENT_FOUND_ROWS (check MySQL manual for details). The value
00086  *  associated with "fldsz" determines maximum amount of memory (in bytes) for
00087  *  each of the fields in the result set of prepared statements. By default,
00088  *  this value is 1 MB. The value associated with "group" determines which
00089  *  group from configuration file to use (see MYSQL_READ_DEFAULT_GROUP option
00090  *  of mysql_options() in MySQL manual).
00091  */
00092 APU_DECLARE(apr_status_t) apr_dbd_open(const apr_dbd_driver_t *driver,
00093                                        apr_pool_t *pool, const char *params,
00094                                        apr_dbd_t **handle);
00095 
00096 /** apr_dbd_close: close a connection to a backend
00097  *
00098  *  @param handle - handle to close
00099  *  @param driver - driver struct.
00100  *  @return APR_SUCCESS for success or error status
00101  */
00102 APU_DECLARE(apr_status_t) apr_dbd_close(const apr_dbd_driver_t *driver,
00103                                         apr_dbd_t *handle);
00104 
00105 /* apr-function-shaped versions of things */
00106 
00107 /** apr_dbd_name: get the name of the driver
00108  *
00109  *  @param driver - the driver
00110  *  @return - name
00111  */
00112 APU_DECLARE(const char*) apr_dbd_name(const apr_dbd_driver_t *driver);
00113 
00114 /** apr_dbd_native_handle: get native database handle of the underlying db
00115  *
00116  *  @param driver - the driver
00117  *  @param handle - apr_dbd handle
00118  *  @return - native handle
00119  */
00120 APU_DECLARE(void*) apr_dbd_native_handle(const apr_dbd_driver_t *driver,
00121                                          apr_dbd_t *handle);
00122 
00123 /** check_conn: check status of a database connection
00124  *
00125  *  @param driver - the driver
00126  *  @param pool - working pool
00127  *  @param handle - the connection to check
00128  *  @return APR_SUCCESS or error
00129  */
00130 APU_DECLARE(int) apr_dbd_check_conn(const apr_dbd_driver_t *driver, apr_pool_t *pool,
00131                                     apr_dbd_t *handle);
00132 
00133 /** apr_dbd_set_dbname: select database name.  May be a no-op if not supported.
00134  *
00135  *  @param driver - the driver
00136  *  @param pool - working pool
00137  *  @param handle - the connection
00138  *  @param name - the database to select
00139  *  @return 0 for success or error code
00140  */
00141 APU_DECLARE(int) apr_dbd_set_dbname(const apr_dbd_driver_t *driver, apr_pool_t *pool,
00142                                     apr_dbd_t *handle, const char *name);
00143 
00144 /** apr_dbd_transaction_start: start a transaction.  May be a no-op.
00145  *
00146  *  @param driver - the driver
00147  *  @param pool - a pool to use for error messages (if any).
00148  *  @param handle - the db connection
00149  *  @param trans - ptr to a transaction.  May be null on entry
00150  *  @return 0 for success or error code
00151  *  @remarks If any of the query/select calls during a transaction return
00152  *  non-zero status code, the transaction will inherit this code and any
00153  *  further query/select calls will fail immediately.
00154  */
00155 APU_DECLARE(int) apr_dbd_transaction_start(const apr_dbd_driver_t *driver,
00156                                            apr_pool_t *pool,
00157                                            apr_dbd_t *handle,
00158                                            apr_dbd_transaction_t **trans);
00159 
00160 /** apr_dbd_transaction_end: end a transaction
00161  *  (commit on success, rollback on error).
00162  *  May be a no-op.
00163  *
00164  *  @param driver - the driver
00165  *  @param handle - the db connection
00166  *  @param trans - the transaction.
00167  *  @return 0 for success or error code
00168  */
00169 APU_DECLARE(int) apr_dbd_transaction_end(const apr_dbd_driver_t *driver,
00170                                          apr_pool_t *pool,
00171                                          apr_dbd_transaction_t *trans);
00172 
00173 /** apr_dbd_query: execute an SQL query that doesn't return a result set
00174  *
00175  *  @param driver - the driver
00176  *  @param handle - the connection
00177  *  @param nrows - number of rows affected.
00178  *  @param statement - the SQL statement to execute
00179  *  @return 0 for success or error code
00180  */
00181 APU_DECLARE(int) apr_dbd_query(const apr_dbd_driver_t *driver, apr_dbd_t *handle,
00182                                int *nrows, const char *statement);
00183 
00184 /** apr_dbd_select: execute an SQL query that returns a result set
00185  *
00186  *  @param driver - the driver
00187  *  @param pool - pool to allocate the result set
00188  *  @param handle - the connection
00189  *  @param res - pointer to result set pointer.  May point to NULL on entry
00190  *  @param statement - the SQL statement to execute
00191  *  @param random - 1 to support random access to results (seek any row);
00192  *                  0 to support only looping through results in order
00193  *                    (async access - faster)
00194  *  @return 0 for success or error code
00195  */
00196 APU_DECLARE(int) apr_dbd_select(const apr_dbd_driver_t *driver, apr_pool_t *pool,
00197                                 apr_dbd_t *handle, apr_dbd_results_t **res,
00198                                 const char *statement, int random);
00199 
00200 /** apr_dbd_num_cols: get the number of columns in a results set
00201  *
00202  *  @param driver - the driver
00203  *  @param res - result set.
00204  *  @return number of columns
00205  */
00206 APU_DECLARE(int) apr_dbd_num_cols(const apr_dbd_driver_t *driver,
00207                                   apr_dbd_results_t *res);
00208 
00209 /** apr_dbd_num_tuples: get the number of rows in a results set
00210  *  of a synchronous select
00211  *
00212  *  @param driver - the driver
00213  *  @param res - result set.
00214  *  @return number of rows, or -1 if the results are asynchronous
00215  */
00216 APU_DECLARE(int) apr_dbd_num_tuples(const apr_dbd_driver_t *driver,
00217                                     apr_dbd_results_t *res);
00218 
00219 /** apr_dbd_get_row: get a row from a result set
00220  *
00221  *  @param driver - the driver
00222  *  @param pool - pool to allocate the row
00223  *  @param res - result set pointer
00224  *  @param row - pointer to row pointer.  May point to NULL on entry
00225  *  @param rownum - row number, or -1 for "next row".  Ignored if random
00226  *                  access is not supported.
00227  *  @return 0 for success, -1 for rownum out of range or data finished
00228  */
00229 APU_DECLARE(int) apr_dbd_get_row(const apr_dbd_driver_t *driver, apr_pool_t *pool,
00230                                  apr_dbd_results_t *res, apr_dbd_row_t **row,
00231                                  int rownum);
00232 
00233 /** apr_dbd_get_entry: get an entry from a row
00234  *
00235  *  @param driver - the driver
00236  *  @param row - row pointer
00237  *  @param col - entry number
00238  *  @return value from the row, or NULL if col is out of bounds.
00239  */
00240 APU_DECLARE(const char*) apr_dbd_get_entry(const apr_dbd_driver_t *driver,
00241                                            apr_dbd_row_t *row, int col);
00242 
00243 /** apr_dbd_error: get current error message (if any)
00244  *
00245  *  @param driver - the driver
00246  *  @param handle - the connection
00247  *  @param errnum - error code from operation that returned an error
00248  *  @return the database current error message, or message for errnum
00249  *          (implementation-dependent whether errnum is ignored)
00250  */
00251 APU_DECLARE(const char*) apr_dbd_error(const apr_dbd_driver_t *driver,
00252                                        apr_dbd_t *handle, int errnum);
00253 
00254 /** apr_dbd_escape: escape a string so it is safe for use in query/select
00255  *
00256  *  @param driver - the driver
00257  *  @param pool - pool to alloc the result from
00258  *  @param string - the string to escape
00259  *  @param handle - the connection
00260  *  @return the escaped, safe string
00261  */
00262 APU_DECLARE(const char*) apr_dbd_escape(const apr_dbd_driver_t *driver,
00263                                         apr_pool_t *pool, const char *string,
00264                                         apr_dbd_t *handle);
00265 
00266 /** apr_dbd_prepare: prepare a statement
00267  *
00268  *  @param driver - the driver
00269  *  @param pool - pool to alloc the result from
00270  *  @param handle - the connection
00271  *  @param query - the SQL query
00272  *  @param label - A label for the prepared statement.
00273  *                 use NULL for temporary prepared statements
00274  *                 (eg within a Request in httpd)
00275  *  @param statement - statement to prepare.  May point to null on entry.
00276  *  @return 0 for success or error code
00277  *  @remarks To specify parameters of the prepared query, use %s in place of
00278  *  database specific parameter syntax (e.g. for PostgreSQL, this would be $1,
00279  *  $2, for SQLite3 this would be ? etc.). For instance: "SELECT name FROM
00280  *  customers WHERE name=%s" would be a query that this function understands.
00281  *  Some drivers may support different data types using printf-like format:
00282  *  for example %d (e.g. PostgreSQL) or %f for numeric data.
00283  */
00284 APU_DECLARE(int) apr_dbd_prepare(const apr_dbd_driver_t *driver, apr_pool_t *pool,
00285                                  apr_dbd_t *handle, const char *query,
00286                                  const char *label,
00287                                  apr_dbd_prepared_t **statement);
00288 
00289 
00290 /** apr_dbd_pquery: query using a prepared statement + args
00291  *
00292  *  @param driver - the driver
00293  *  @param pool - working pool
00294  *  @param handle - the connection
00295  *  @param nrows - number of rows affected.
00296  *  @param statement - the prepared statement to execute
00297  *  @param nargs - number of args to prepared statement
00298  *  @param args - args to prepared statement
00299  *  @return 0 for success or error code
00300  */
00301 APU_DECLARE(int) apr_dbd_pquery(const apr_dbd_driver_t *driver, apr_pool_t *pool,
00302                                 apr_dbd_t *handle, int *nrows,
00303                                 apr_dbd_prepared_t *statement, int nargs,
00304                                 const char **args);
00305 
00306 /** apr_dbd_pselect: select using a prepared statement + args
00307  *
00308  *  @param driver - the driver
00309  *  @param pool - working pool
00310  *  @param handle - the connection
00311  *  @param res - pointer to query results.  May point to NULL on entry
00312  *  @param statement - the prepared statement to execute
00313  *  @param random - Whether to support random-access to results
00314  *  @param nargs - number of args to prepared statement
00315  *  @param args - args to prepared statement
00316  *  @return 0 for success or error code
00317  */
00318 APU_DECLARE(int) apr_dbd_pselect(const apr_dbd_driver_t *driver, apr_pool_t *pool,
00319                                  apr_dbd_t *handle, apr_dbd_results_t **res,
00320                                  apr_dbd_prepared_t *statement, int random,
00321                                  int nargs, const char **args);
00322 
00323 /** apr_dbd_pvquery: query using a prepared statement + args
00324  *
00325  *  @param driver - the driver
00326  *  @param pool - working pool
00327  *  @param handle - the connection
00328  *  @param nrows - number of rows affected.
00329  *  @param statement - the prepared statement to execute
00330  *  @param ... - varargs list
00331  *  @return 0 for success or error code
00332  */
00333 APU_DECLARE(int) apr_dbd_pvquery(const apr_dbd_driver_t *driver, apr_pool_t *pool,
00334                                  apr_dbd_t *handle, int *nrows,
00335                                  apr_dbd_prepared_t *statement, ...);
00336 
00337 /** apr_dbd_pvselect: select using a prepared statement + args
00338  *
00339  *  @param driver - the driver
00340  *  @param pool - working pool
00341  *  @param handle - the connection
00342  *  @param res - pointer to query results.  May point to NULL on entry
00343  *  @param statement - the prepared statement to execute
00344  *  @param random - Whether to support random-access to results
00345  *  @param ... - varargs list
00346  *  @return 0 for success or error code
00347  */
00348 APU_DECLARE(int) apr_dbd_pvselect(const apr_dbd_driver_t *driver, apr_pool_t *pool,
00349                                   apr_dbd_t *handle, apr_dbd_results_t **res,
00350                                   apr_dbd_prepared_t *statement, int random,
00351                                   ...);
00352 
00353 /** @} */
00354 
00355 #ifdef __cplusplus
00356 }
00357 #endif
00358 
00359 #endif

Generated on Sat Jan 19 01:49:04 2008 for Apache Portable Runtime by  doxygen 1.5.4