apr_dbd.h

Go to the documentation of this file.
00001 /* Copyright 2000-2005 The Apache Software Foundation or its licensors, as
00002  * applicable.
00003  *
00004  * Licensed under the Apache License, Version 2.0 (the "License");
00005  * you may not use this file except in compliance with the License.
00006  * 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" and "fldsz" keys, each followed by an equal sign
00083  *  and a value. Such key/value pairs can be delimited by space, CR, LF, tab,
00084  *  semicolon, vertical bar or comma. For now, "flags" can only recognise
00085  *  CLIENT_FOUND_ROWS (check MySQL manual for details). The value associated
00086  *  with "fldsz" determines maximum amount of memory (in bytes) for each of
00087  *  the fields in the result set of prepared statements. By default, this
00088  *  value is 1 MB.
00089  */
00090 APU_DECLARE(apr_status_t) apr_dbd_open(const apr_dbd_driver_t *driver,
00091                                        apr_pool_t *pool, const char *params,
00092                                        apr_dbd_t **handle);
00093 
00094 /** apr_dbd_close: close a connection to a backend
00095  *
00096  *  @param handle - handle to close
00097  *  @param driver - driver struct.
00098  *  @return APR_SUCCESS for success or error status
00099  */
00100 APU_DECLARE(apr_status_t) apr_dbd_close(const apr_dbd_driver_t *driver,
00101                                         apr_dbd_t *handle);
00102 
00103 /* apr-function-shaped versions of things */
00104 
00105 /** apr_dbd_name: get the name of the driver
00106  *
00107  *  @param driver - the driver
00108  *  @return - name
00109  */
00110 APU_DECLARE(const char*) apr_dbd_name(const apr_dbd_driver_t *driver);
00111 
00112 /** apr_dbd_native_handle: get native database handle of the underlying db
00113  *
00114  *  @param driver - the driver
00115  *  @param handle - apr_dbd handle
00116  *  @return - native handle
00117  */
00118 APU_DECLARE(void*) apr_dbd_native_handle(const apr_dbd_driver_t *driver,
00119                                          apr_dbd_t *handle);
00120 
00121 /** check_conn: check status of a database connection
00122  *
00123  *  @param driver - the driver
00124  *  @param pool - working pool
00125  *  @param handle - the connection to check
00126  *  @return APR_SUCCESS or error
00127  */
00128 APU_DECLARE(int) apr_dbd_check_conn(const apr_dbd_driver_t *driver, apr_pool_t *pool,
00129                                     apr_dbd_t *handle);
00130 
00131 /** apr_dbd_set_dbname: select database name.  May be a no-op if not supported.
00132  *
00133  *  @param driver - the driver
00134  *  @param pool - working pool
00135  *  @param handle - the connection
00136  *  @param name - the database to select
00137  *  @return 0 for success or error code
00138  */
00139 APU_DECLARE(int) apr_dbd_set_dbname(const apr_dbd_driver_t *driver, apr_pool_t *pool,
00140                                     apr_dbd_t *handle, const char *name);
00141 
00142 /** apr_dbd_transaction_start: start a transaction.  May be a no-op.
00143  *
00144  *  @param driver - the driver
00145  *  @param pool - a pool to use for error messages (if any).
00146  *  @param handle - the db connection
00147  *  @param trans - ptr to a transaction.  May be null on entry
00148  *  @return 0 for success or error code
00149  *  @remarks If any of the query/select calls during a transaction return
00150  *  non-zero status code, the transaction will inherit this code and any
00151  *  further query/select calls will fail immediately.
00152  */
00153 APU_DECLARE(int) apr_dbd_transaction_start(const apr_dbd_driver_t *driver,
00154                                            apr_pool_t *pool,
00155                                            apr_dbd_t *handle,
00156                                            apr_dbd_transaction_t **trans);
00157 
00158 /** apr_dbd_transaction_end: end a transaction
00159  *  (commit on success, rollback on error).
00160  *  May be a no-op.
00161  *
00162  *  @param driver - the driver
00163  *  @param handle - the db connection
00164  *  @param trans - the transaction.
00165  *  @return 0 for success or error code
00166  */
00167 APU_DECLARE(int) apr_dbd_transaction_end(const apr_dbd_driver_t *driver,
00168                                          apr_pool_t *pool,
00169                                          apr_dbd_transaction_t *trans);
00170 
00171 /** apr_dbd_query: execute an SQL query that doesn't return a result set
00172  *
00173  *  @param driver - the driver
00174  *  @param handle - the connection
00175  *  @param nrows - number of rows affected.
00176  *  @param statement - the SQL statement to execute
00177  *  @return 0 for success or error code
00178  */
00179 APU_DECLARE(int) apr_dbd_query(const apr_dbd_driver_t *driver, apr_dbd_t *handle,
00180                                int *nrows, const char *statement);
00181 
00182 /** apr_dbd_select: execute an SQL query that returns a result set
00183  *
00184  *  @param driver - the driver
00185  *  @param pool - pool to allocate the result set
00186  *  @param handle - the connection
00187  *  @param res - pointer to result set pointer.  May point to NULL on entry
00188  *  @param statement - the SQL statement to execute
00189  *  @param random - 1 to support random access to results (seek any row);
00190  *                  0 to support only looping through results in order
00191  *                    (async access - faster)
00192  *  @return 0 for success or error code
00193  */
00194 APU_DECLARE(int) apr_dbd_select(const apr_dbd_driver_t *driver, apr_pool_t *pool,
00195                                 apr_dbd_t *handle, apr_dbd_results_t **res,
00196                                 const char *statement, int random);
00197 
00198 /** apr_dbd_num_cols: get the number of columns in a results set
00199  *
00200  *  @param driver - the driver
00201  *  @param res - result set.
00202  *  @return number of columns
00203  */
00204 APU_DECLARE(int) apr_dbd_num_cols(const apr_dbd_driver_t *driver,
00205                                   apr_dbd_results_t *res);
00206 
00207 /** apr_dbd_num_tuples: get the number of rows in a results set
00208  *  of a synchronous select
00209  *
00210  *  @param driver - the driver
00211  *  @param res - result set.
00212  *  @return number of rows, or -1 if the results are asynchronous
00213  */
00214 APU_DECLARE(int) apr_dbd_num_tuples(const apr_dbd_driver_t *driver,
00215                                     apr_dbd_results_t *res);
00216 
00217 /** apr_dbd_get_row: get a row from a result set
00218  *
00219  *  @param driver - the driver
00220  *  @param pool - pool to allocate the row
00221  *  @param res - result set pointer
00222  *  @param row - pointer to row pointer.  May point to NULL on entry
00223  *  @param rownum - row number, or -1 for "next row".  Ignored if random
00224  *                  access is not supported.
00225  *  @return 0 for success, -1 for rownum out of range or data finished
00226  */
00227 APU_DECLARE(int) apr_dbd_get_row(const apr_dbd_driver_t *driver, apr_pool_t *pool,
00228                                  apr_dbd_results_t *res, apr_dbd_row_t **row,
00229                                  int rownum);
00230 
00231 /** apr_dbd_get_entry: get an entry from a row
00232  *
00233  *  @param driver - the driver
00234  *  @param row - row pointer
00235  *  @param col - entry number
00236  *  @return value from the row, or NULL if col is out of bounds.
00237  */
00238 APU_DECLARE(const char*) apr_dbd_get_entry(const apr_dbd_driver_t *driver,
00239                                            apr_dbd_row_t *row, int col);
00240 
00241 /** apr_dbd_error: get current error message (if any)
00242  *
00243  *  @param driver - the driver
00244  *  @param handle - the connection
00245  *  @param errnum - error code from operation that returned an error
00246  *  @return the database current error message, or message for errnum
00247  *          (implementation-dependent whether errnum is ignored)
00248  */
00249 APU_DECLARE(const char*) apr_dbd_error(const apr_dbd_driver_t *driver,
00250                                        apr_dbd_t *handle, int errnum);
00251 
00252 /** apr_dbd_escape: escape a string so it is safe for use in query/select
00253  *
00254  *  @param driver - the driver
00255  *  @param pool - pool to alloc the result from
00256  *  @param string - the string to escape
00257  *  @param handle - the connection
00258  *  @return the escaped, safe string
00259  */
00260 APU_DECLARE(const char*) apr_dbd_escape(const apr_dbd_driver_t *driver,
00261                                         apr_pool_t *pool, const char *string,
00262                                         apr_dbd_t *handle);
00263 
00264 /** apr_dbd_prepare: prepare a statement
00265  *
00266  *  @param driver - the driver
00267  *  @param pool - pool to alloc the result from
00268  *  @param handle - the connection
00269  *  @param query - the SQL query
00270  *  @param label - A label for the prepared statement.
00271  *                 use NULL for temporary prepared statements
00272  *                 (eg within a Request in httpd)
00273  *  @param statement - statement to prepare.  May point to null on entry.
00274  *  @return 0 for success or error code
00275  *  @remarks To specify parameters of the prepared query, use %s in place of
00276  *  database specific parameter syntax (e.g. for PostgreSQL, this would be $1,
00277  *  $2, for SQLite3 this would be ? etc.). For instance: "SELECT name FROM
00278  *  customers WHERE name=%s" would be a query that this function understands.
00279  *  Some drivers may support different data types using printf-like format:
00280  *  for example %d (e.g. PostgreSQL) or %f for numeric data.
00281  */
00282 APU_DECLARE(int) apr_dbd_prepare(const apr_dbd_driver_t *driver, apr_pool_t *pool,
00283                                  apr_dbd_t *handle, const char *query,
00284                                  const char *label,
00285                                  apr_dbd_prepared_t **statement);
00286 
00287 
00288 /** apr_dbd_pquery: query using a prepared statement + args
00289  *
00290  *  @param driver - the driver
00291  *  @param pool - working pool
00292  *  @param handle - the connection
00293  *  @param nrows - number of rows affected.
00294  *  @param statement - the prepared statement to execute
00295  *  @param nargs - number of args to prepared statement
00296  *  @param args - args to prepared statement
00297  *  @return 0 for success or error code
00298  */
00299 APU_DECLARE(int) apr_dbd_pquery(const apr_dbd_driver_t *driver, apr_pool_t *pool,
00300                                 apr_dbd_t *handle, int *nrows,
00301                                 apr_dbd_prepared_t *statement, int nargs,
00302                                 const char **args);
00303 
00304 /** apr_dbd_pselect: select using a prepared statement + args
00305  *
00306  *  @param driver - the driver
00307  *  @param pool - working pool
00308  *  @param handle - the connection
00309  *  @param res - pointer to query results.  May point to NULL on entry
00310  *  @param statement - the prepared statement to execute
00311  *  @param random - Whether to support random-access to results
00312  *  @param nargs - number of args to prepared statement
00313  *  @param args - args to prepared statement
00314  *  @return 0 for success or error code
00315  */
00316 APU_DECLARE(int) apr_dbd_pselect(const apr_dbd_driver_t *driver, apr_pool_t *pool,
00317                                  apr_dbd_t *handle, apr_dbd_results_t **res,
00318                                  apr_dbd_prepared_t *statement, int random,
00319                                  int nargs, const char **args);
00320 
00321 /** apr_dbd_pvquery: query using a prepared statement + args
00322  *
00323  *  @param driver - the driver
00324  *  @param pool - working pool
00325  *  @param handle - the connection
00326  *  @param nrows - number of rows affected.
00327  *  @param statement - the prepared statement to execute
00328  *  @param ... - varargs list
00329  *  @return 0 for success or error code
00330  */
00331 APU_DECLARE(int) apr_dbd_pvquery(const apr_dbd_driver_t *driver, apr_pool_t *pool,
00332                                  apr_dbd_t *handle, int *nrows,
00333                                  apr_dbd_prepared_t *statement, ...);
00334 
00335 /** apr_dbd_pvselect: select using a prepared statement + args
00336  *
00337  *  @param driver - the driver
00338  *  @param pool - working pool
00339  *  @param handle - the connection
00340  *  @param res - pointer to query results.  May point to NULL on entry
00341  *  @param statement - the prepared statement to execute
00342  *  @param random - Whether to support random-access to results
00343  *  @param ... - varargs list
00344  *  @return 0 for success or error code
00345  */
00346 APU_DECLARE(int) apr_dbd_pvselect(const apr_dbd_driver_t *driver, apr_pool_t *pool,
00347                                   apr_dbd_t *handle, apr_dbd_results_t **res,
00348                                   apr_dbd_prepared_t *statement, int random,
00349                                   ...);
00350 
00351 /** @} */
00352 
00353 #ifdef __cplusplus
00354 }
00355 #endif
00356 
00357 #endif

Generated on Tue Nov 6 14:40:16 2007 for Apache Portable Runtime by  doxygen 1.5.2