home *** CD-ROM | disk | FTP | other *** search
/ Cricao de Sites - 650 Layouts Prontos / WebMasters.iso / Servidores / apache_2.2.8-win32-x86-no_ssl.msi / Data1.cab / _EAA768CE9EDD0A0470C44F5EF3AC5104 < prev    next >
Text File  |  2007-11-01  |  15KB  |  360 lines
  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_H
  22. #define APR_DBD_H
  23.  
  24. #ifdef __cplusplus
  25. extern "C" {
  26. #endif
  27.  
  28. /**
  29.  * @file apr_dbd.h
  30.  * @brief APR-UTIL DBD library
  31.  */
  32. /**
  33.  * @defgroup APR_Util_DBD DBD routines
  34.  * @ingroup APR_Util
  35.  * @{
  36.  */
  37.  
  38. /* These are opaque structs.  Instantiation is up to each backend */
  39. typedef struct apr_dbd_driver_t apr_dbd_driver_t;
  40. typedef struct apr_dbd_t apr_dbd_t;
  41. typedef struct apr_dbd_transaction_t apr_dbd_transaction_t;
  42. typedef struct apr_dbd_results_t apr_dbd_results_t;
  43. typedef struct apr_dbd_row_t apr_dbd_row_t;
  44. typedef struct apr_dbd_prepared_t apr_dbd_prepared_t;
  45.  
  46. /** apr_dbd_init: perform once-only initialisation.  Call once only.
  47.  *
  48.  *  @param pool - pool to register any shutdown cleanups, etc
  49.  */
  50. APU_DECLARE(apr_status_t) apr_dbd_init(apr_pool_t *pool);
  51.  
  52. /** apr_dbd_get_driver: get the driver struct for a name
  53.  *
  54.  *  @param pool - (process) pool to register cleanup
  55.  *  @param name - driver name
  56.  *  @param driver - pointer to driver struct.
  57.  *  @return APR_SUCCESS for success
  58.  *  @return APR_ENOTIMPL for no driver (when DSO not enabled)
  59.  *  @return APR_EDSOOPEN if DSO driver file can't be opened
  60.  *  @return APR_ESYMNOTFOUND if the driver file doesn't contain a driver
  61.  */
  62. APU_DECLARE(apr_status_t) apr_dbd_get_driver(apr_pool_t *pool, const char *name,
  63.                                              const apr_dbd_driver_t **driver);
  64.  
  65. /** apr_dbd_open: open a connection to a backend
  66.  *
  67.  *  @param pool - working pool
  68.  *  @param params - arguments to driver (implementation-dependent)
  69.  *  @param handle - pointer to handle to return
  70.  *  @param driver - driver struct.
  71.  *  @return APR_SUCCESS for success
  72.  *  @return APR_EGENERAL if driver exists but connection failed
  73.  *  @remarks PostgreSQL: the params is passed directly to the PQconnectdb()
  74.  *  function (check PostgreSQL documentation for more details on the syntax).
  75.  *  @remarks SQLite2: the params is split on a colon, with the first part used
  76.  *  as the filename and second part converted to an integer and used as file
  77.  *  mode.
  78.  *  @remarks SQLite3: the params is passed directly to the sqlite3_open()
  79.  *  function as a filename to be opened (check SQLite3 documentation for more
  80.  *  details).
  81.  *  @remarks MySQL: the params can have "host", "port", "user", "pass",
  82.  *  "dbname", "sock", "flags" "fldsz" and "group" keys, each followed by an
  83.  *  equal sign and a value. Such key/value pairs can be delimited by space,
  84.  *  CR, LF, tab, semicolon, vertical bar or comma. For now, "flags" can only
  85.  *  recognise CLIENT_FOUND_ROWS (check MySQL manual for details). The value
  86.  *  associated with "fldsz" determines maximum amount of memory (in bytes) for
  87.  *  each of the fields in the result set of prepared statements. By default,
  88.  *  this value is 1 MB. The value associated with "group" determines which
  89.  *  group from configuration file to use (see MYSQL_READ_DEFAULT_GROUP option
  90.  *  of mysql_options() in MySQL manual).
  91.  */
  92. APU_DECLARE(apr_status_t) apr_dbd_open(const apr_dbd_driver_t *driver,
  93.                                        apr_pool_t *pool, const char *params,
  94.                                        apr_dbd_t **handle);
  95.  
  96. /** apr_dbd_close: close a connection to a backend
  97.  *
  98.  *  @param handle - handle to close
  99.  *  @param driver - driver struct.
  100.  *  @return APR_SUCCESS for success or error status
  101.  */
  102. APU_DECLARE(apr_status_t) apr_dbd_close(const apr_dbd_driver_t *driver,
  103.                                         apr_dbd_t *handle);
  104.  
  105. /* apr-function-shaped versions of things */
  106.  
  107. /** apr_dbd_name: get the name of the driver
  108.  *
  109.  *  @param driver - the driver
  110.  *  @return - name
  111.  */
  112. APU_DECLARE(const char*) apr_dbd_name(const apr_dbd_driver_t *driver);
  113.  
  114. /** apr_dbd_native_handle: get native database handle of the underlying db
  115.  *
  116.  *  @param driver - the driver
  117.  *  @param handle - apr_dbd handle
  118.  *  @return - native handle
  119.  */
  120. APU_DECLARE(void*) apr_dbd_native_handle(const apr_dbd_driver_t *driver,
  121.                                          apr_dbd_t *handle);
  122.  
  123. /** check_conn: check status of a database connection
  124.  *
  125.  *  @param driver - the driver
  126.  *  @param pool - working pool
  127.  *  @param handle - the connection to check
  128.  *  @return APR_SUCCESS or error
  129.  */
  130. APU_DECLARE(int) apr_dbd_check_conn(const apr_dbd_driver_t *driver, apr_pool_t *pool,
  131.                                     apr_dbd_t *handle);
  132.  
  133. /** apr_dbd_set_dbname: select database name.  May be a no-op if not supported.
  134.  *
  135.  *  @param driver - the driver
  136.  *  @param pool - working pool
  137.  *  @param handle - the connection
  138.  *  @param name - the database to select
  139.  *  @return 0 for success or error code
  140.  */
  141. APU_DECLARE(int) apr_dbd_set_dbname(const apr_dbd_driver_t *driver, apr_pool_t *pool,
  142.                                     apr_dbd_t *handle, const char *name);
  143.  
  144. /** apr_dbd_transaction_start: start a transaction.  May be a no-op.
  145.  *
  146.  *  @param driver - the driver
  147.  *  @param pool - a pool to use for error messages (if any).
  148.  *  @param handle - the db connection
  149.  *  @param trans - ptr to a transaction.  May be null on entry
  150.  *  @return 0 for success or error code
  151.  *  @remarks If any of the query/select calls during a transaction return
  152.  *  non-zero status code, the transaction will inherit this code and any
  153.  *  further query/select calls will fail immediately.
  154.  */
  155. APU_DECLARE(int) apr_dbd_transaction_start(const apr_dbd_driver_t *driver,
  156.                                            apr_pool_t *pool,
  157.                                            apr_dbd_t *handle,
  158.                                            apr_dbd_transaction_t **trans);
  159.  
  160. /** apr_dbd_transaction_end: end a transaction
  161.  *  (commit on success, rollback on error).
  162.  *  May be a no-op.
  163.  *
  164.  *  @param driver - the driver
  165.  *  @param handle - the db connection
  166.  *  @param trans - the transaction.
  167.  *  @return 0 for success or error code
  168.  */
  169. APU_DECLARE(int) apr_dbd_transaction_end(const apr_dbd_driver_t *driver,
  170.                                          apr_pool_t *pool,
  171.                                          apr_dbd_transaction_t *trans);
  172.  
  173. /** apr_dbd_query: execute an SQL query that doesn't return a result set
  174.  *
  175.  *  @param driver - the driver
  176.  *  @param handle - the connection
  177.  *  @param nrows - number of rows affected.
  178.  *  @param statement - the SQL statement to execute
  179.  *  @return 0 for success or error code
  180.  */
  181. APU_DECLARE(int) apr_dbd_query(const apr_dbd_driver_t *driver, apr_dbd_t *handle,
  182.                                int *nrows, const char *statement);
  183.  
  184. /** apr_dbd_select: execute an SQL query that returns a result set
  185.  *
  186.  *  @param driver - the driver
  187.  *  @param pool - pool to allocate the result set
  188.  *  @param handle - the connection
  189.  *  @param res - pointer to result set pointer.  May point to NULL on entry
  190.  *  @param statement - the SQL statement to execute
  191.  *  @param random - 1 to support random access to results (seek any row);
  192.  *                  0 to support only looping through results in order
  193.  *                    (async access - faster)
  194.  *  @return 0 for success or error code
  195.  */
  196. APU_DECLARE(int) apr_dbd_select(const apr_dbd_driver_t *driver, apr_pool_t *pool,
  197.                                 apr_dbd_t *handle, apr_dbd_results_t **res,
  198.                                 const char *statement, int random);
  199.  
  200. /** apr_dbd_num_cols: get the number of columns in a results set
  201.  *
  202.  *  @param driver - the driver
  203.  *  @param res - result set.
  204.  *  @return number of columns
  205.  */
  206. APU_DECLARE(int) apr_dbd_num_cols(const apr_dbd_driver_t *driver,
  207.                                   apr_dbd_results_t *res);
  208.  
  209. /** apr_dbd_num_tuples: get the number of rows in a results set
  210.  *  of a synchronous select
  211.  *
  212.  *  @param driver - the driver
  213.  *  @param res - result set.
  214.  *  @return number of rows, or -1 if the results are asynchronous
  215.  */
  216. APU_DECLARE(int) apr_dbd_num_tuples(const apr_dbd_driver_t *driver,
  217.                                     apr_dbd_results_t *res);
  218.  
  219. /** apr_dbd_get_row: get a row from a result set
  220.  *
  221.  *  @param driver - the driver
  222.  *  @param pool - pool to allocate the row
  223.  *  @param res - result set pointer
  224.  *  @param row - pointer to row pointer.  May point to NULL on entry
  225.  *  @param rownum - row number, or -1 for "next row".  Ignored if random
  226.  *                  access is not supported.
  227.  *  @return 0 for success, -1 for rownum out of range or data finished
  228.  */
  229. APU_DECLARE(int) apr_dbd_get_row(const apr_dbd_driver_t *driver, apr_pool_t *pool,
  230.                                  apr_dbd_results_t *res, apr_dbd_row_t **row,
  231.                                  int rownum);
  232.  
  233. /** apr_dbd_get_entry: get an entry from a row
  234.  *
  235.  *  @param driver - the driver
  236.  *  @param row - row pointer
  237.  *  @param col - entry number
  238.  *  @return value from the row, or NULL if col is out of bounds.
  239.  */
  240. APU_DECLARE(const char*) apr_dbd_get_entry(const apr_dbd_driver_t *driver,
  241.                                            apr_dbd_row_t *row, int col);
  242.  
  243. /** apr_dbd_error: get current error message (if any)
  244.  *
  245.  *  @param driver - the driver
  246.  *  @param handle - the connection
  247.  *  @param errnum - error code from operation that returned an error
  248.  *  @return the database current error message, or message for errnum
  249.  *          (implementation-dependent whether errnum is ignored)
  250.  */
  251. APU_DECLARE(const char*) apr_dbd_error(const apr_dbd_driver_t *driver,
  252.                                        apr_dbd_t *handle, int errnum);
  253.  
  254. /** apr_dbd_escape: escape a string so it is safe for use in query/select
  255.  *
  256.  *  @param driver - the driver
  257.  *  @param pool - pool to alloc the result from
  258.  *  @param string - the string to escape
  259.  *  @param handle - the connection
  260.  *  @return the escaped, safe string
  261.  */
  262. APU_DECLARE(const char*) apr_dbd_escape(const apr_dbd_driver_t *driver,
  263.                                         apr_pool_t *pool, const char *string,
  264.                                         apr_dbd_t *handle);
  265.  
  266. /** apr_dbd_prepare: prepare a statement
  267.  *
  268.  *  @param driver - the driver
  269.  *  @param pool - pool to alloc the result from
  270.  *  @param handle - the connection
  271.  *  @param query - the SQL query
  272.  *  @param label - A label for the prepared statement.
  273.  *                 use NULL for temporary prepared statements
  274.  *                 (eg within a Request in httpd)
  275.  *  @param statement - statement to prepare.  May point to null on entry.
  276.  *  @return 0 for success or error code
  277.  *  @remarks To specify parameters of the prepared query, use %s in place of
  278.  *  database specific parameter syntax (e.g. for PostgreSQL, this would be $1,
  279.  *  $2, for SQLite3 this would be ? etc.). For instance: "SELECT name FROM
  280.  *  customers WHERE name=%s" would be a query that this function understands.
  281.  *  Some drivers may support different data types using printf-like format:
  282.  *  for example %d (e.g. PostgreSQL) or %f for numeric data.
  283.  */
  284. APU_DECLARE(int) apr_dbd_prepare(const apr_dbd_driver_t *driver, apr_pool_t *pool,
  285.                                  apr_dbd_t *handle, const char *query,
  286.                                  const char *label,
  287.                                  apr_dbd_prepared_t **statement);
  288.  
  289.  
  290. /** apr_dbd_pquery: query using a prepared statement + args
  291.  *
  292.  *  @param driver - the driver
  293.  *  @param pool - working pool
  294.  *  @param handle - the connection
  295.  *  @param nrows - number of rows affected.
  296.  *  @param statement - the prepared statement to execute
  297.  *  @param nargs - number of args to prepared statement
  298.  *  @param args - args to prepared statement
  299.  *  @return 0 for success or error code
  300.  */
  301. APU_DECLARE(int) apr_dbd_pquery(const apr_dbd_driver_t *driver, apr_pool_t *pool,
  302.                                 apr_dbd_t *handle, int *nrows,
  303.                                 apr_dbd_prepared_t *statement, int nargs,
  304.                                 const char **args);
  305.  
  306. /** apr_dbd_pselect: select using a prepared statement + args
  307.  *
  308.  *  @param driver - the driver
  309.  *  @param pool - working pool
  310.  *  @param handle - the connection
  311.  *  @param res - pointer to query results.  May point to NULL on entry
  312.  *  @param statement - the prepared statement to execute
  313.  *  @param random - Whether to support random-access to results
  314.  *  @param nargs - number of args to prepared statement
  315.  *  @param args - args to prepared statement
  316.  *  @return 0 for success or error code
  317.  */
  318. APU_DECLARE(int) apr_dbd_pselect(const apr_dbd_driver_t *driver, apr_pool_t *pool,
  319.                                  apr_dbd_t *handle, apr_dbd_results_t **res,
  320.                                  apr_dbd_prepared_t *statement, int random,
  321.                                  int nargs, const char **args);
  322.  
  323. /** apr_dbd_pvquery: query using a prepared statement + args
  324.  *
  325.  *  @param driver - the driver
  326.  *  @param pool - working pool
  327.  *  @param handle - the connection
  328.  *  @param nrows - number of rows affected.
  329.  *  @param statement - the prepared statement to execute
  330.  *  @param ... - varargs list
  331.  *  @return 0 for success or error code
  332.  */
  333. APU_DECLARE(int) apr_dbd_pvquery(const apr_dbd_driver_t *driver, apr_pool_t *pool,
  334.                                  apr_dbd_t *handle, int *nrows,
  335.                                  apr_dbd_prepared_t *statement, ...);
  336.  
  337. /** apr_dbd_pvselect: select using a prepared statement + args
  338.  *
  339.  *  @param driver - the driver
  340.  *  @param pool - working pool
  341.  *  @param handle - the connection
  342.  *  @param res - pointer to query results.  May point to NULL on entry
  343.  *  @param statement - the prepared statement to execute
  344.  *  @param random - Whether to support random-access to results
  345.  *  @param ... - varargs list
  346.  *  @return 0 for success or error code
  347.  */
  348. APU_DECLARE(int) apr_dbd_pvselect(const apr_dbd_driver_t *driver, apr_pool_t *pool,
  349.                                   apr_dbd_t *handle, apr_dbd_results_t **res,
  350.                                   apr_dbd_prepared_t *statement, int random,
  351.                                   ...);
  352.  
  353. /** @} */
  354.  
  355. #ifdef __cplusplus
  356. }
  357. #endif
  358.  
  359. #endif
  360.