Committing mod_dbd as new.

  [Remove entries to the current 2.0 section below, when backported]

  *) mod_dbd: New additions: mod_dbd.c, mod_dbd.h, mod_dbd.xml

     Provide module hooks for apr_dbd; optimise for httpd

     threaded and non-threaded arch [Nick Kew]

  *) ab: SSL support rewritten, improved, and enabled if SSL is enabled

     during the build; -f and -Z arguments added to specify SSL protocol

     options.  [Masaoki Kobayashi <masaoki techfirm.co.jp>]

<?xml version="1.0"?>

<!DOCTYPE modulesynopsis SYSTEM "../style/modulesynopsis.dtd">

<?xml-stylesheet type="text/xsl" href="../style/manual.en.xsl"?>

<!-- $LastChangedRevision: 151408 $ -->

<!--

 Copyright 2004-2005 The Apache Software Foundation or its licensors, as

 applicable.

 Licensed 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.

-->

<modulesynopsis metafile="mod_dbd.xml.meta">

<name>mod_dbd</name>

<description>Manages SQL database connections</description>

<status>Experimental</status>

<sourcefile>mod_dbd.c</sourcefile>

<identifier>dbd_module</identifier>

<compatibility>Version 2.1 and higher</compatibility>

<summary>

    <p>mod_dbd manages SQL database connections using

    <a href="http://people.apache.org/~niq/dbd.html">apr_dbd</a>.

    It provides database connections on request to modules

    requiring SQL database functions, and takes care of

    managing databases with optimal efficiency and scalability

    for both threaded and non-threaded MPMs.</p>

</summary>

<section id="reslist"><title>Connection Pooling</title>

    <p>This module manages database connections, in a manner

    optimised for the platform.  On non-threaded platforms,

    it provides a persistent connection in the manner of

    classic LAMP (Linux, Apache, Mysql, Perl/PHP/Python).

    On threaded platform, it provides an altogether more

    scalable and efficient <em>connection pool</em>, as

    described in <a href="http://www.apachetutor.org/dev/reslist"

    title="Connection pooling in Apache">this article at ApacheTutor</a>.

    mod_dbd supersedes the modules presented in that article.</p>

</section>

<section id="API"><title>Apache DBD API</title>

    <p>mod_dbd exports three functions for other modules to use.

    The API is as follows:</p>

<pre><code>typedef struct {

    apr_dbd_t *handle;

    apr_dbd_driver_t *driver;

    apr_hash_t *prepared;

} ap_dbd_t;

/* Export functions to access the database */

/* acquire a connection that MUST be explicitly closed.

 * Returns NULL on error

 */

AP_DECLARE(ap_dbd_t*) ap_dbd_open(apr_pool_t*, server_rec*);

/* release a connection acquired with ap_dbd_open */

AP_DECLARE(void) ap_dbd_close(server_rec*, ap_dbd_t*);

/* acquire a connection that will have the lifetime of a request

 * and MUST NOT be explicitly closed.  Return NULL on error.

 * This is the preferred function for most applications.

 */

AP_DECLARE(ap_dbd_t*) ap_dbd_acquire(request_rec*);

/* Also export them as optional functions for modules that prefer it */

APR_DECLARE_OPTIONAL_FN(ap_dbd_t*, ap_dbd_open, (apr_pool_t*, server_rec*));

APR_DECLARE_OPTIONAL_FN(void, ap_dbd_close, (server_rec*, ap_dbd_t*));

APR_DECLARE_OPTIONAL_FN(ap_dbd_t*, ap_dbd_acquire, (request_rec*));

</code></pre>

</section>

<section id="prepared"><title>SQL Prepared Statements</title>

    <p>mod_dbd supports SQL prepared statements on behalf of

    modules that may wish to use them.  Each prepared statement

    must be assigned a name (label), and they are stored in a hash:

    the <code>prepared</code> field of an <code>ap_dbd_t</code>.

    Hash entries are of type <code>apr_dbd_prepared_t</code>

    and can be used in any of the apr_dbd prepared statement

    SQL query or select commands.</p>

    <p>It is up to dbd user modules to use the prepared statements

    and document what statements can be specified in httpd.conf.</p>

</section>

<directivesynopsis>

<name>DBDriver</name>

<description>Specify an SQL driver</description>

<syntax>DBDriver <var>name</var></syntax>

<contextlist><context>server config</context><context>virtual host</context>

</contextlist>

<usage>

    <p>Selects an apr_dbd driver by name.  The driver must be installed

    on your system (on most systems, it will be a shared object or dll).

    For example, <samp>DBDriver mysql</samp> will select the MySQL

    driver in apr_dbd_mysql.so.</p>

</usage>

</directivesynopsis>

<directivesynopsis>

<name>DBDParams</name>

<description>Parameters for database connection</description>

<syntax>DBDParams <var>param1=value1,param2=value2</var></syntax>

<contextlist><context>server config</context><context>virtual host</context>

</contextlist>

<usage>

    <p>As required by the underlying driver.  Typically this will be

    used to pass whatever cannot be defaulted amongst username,

    password, database name, hostname and port number for connection.</p>

</usage>

</directivesynopsis>

<directivesynopsis>

<name>DBDPersist</name>

<description>Whether to use persistent connections</description>

<syntax>DBDPersist <var>[0|1]</var></syntax>

<contextlist><context>server config</context><context>virtual host</context>

</contextlist>

<usage>

    <p>If set to 0, persistent and pooled connections are disabled.

    A new database connection is opened when requested by a client,

    and closed immediately on release.  This option is for debugging

    and low-usage servers.</p>

    <p>The default is to enable a pool of persistent connections

    (or a single LAMP-style persistent connection in the case of a

    non-threaded server), and should almost always be used in operation.</p>

</usage>

</directivesynopsis>

<directivesynopsis>

<name>DBDPrepareSQL</name>

<description>Define an SQL prepared statement</description>

<syntax>DBDPrepareSQL <var>"SQL statement"</var> <var>label</var></syntax>

<contextlist><context>server config</context><context>virtual host</context>

</contextlist>

<usage>

    <p>For modules such as authentication that use repeatedly use a

    single SQL statement, optimum performance is achieved by preparing

    the statement at startup rather than every time it is used.

    This directive prepares an SQL statement and assigns it a label.</p>

</usage>

</directivesynopsis>

<directivesynopsis>

<name>DBDMin</name>

<description>Minimum number of connections</description>

<syntax>DBDMin <var>number</var></syntax>

<contextlist><context>server config</context><context>virtual host</context>

</contextlist>

<usage>

    <p>Set the minimum number of connections per process (threaded

    platforms only).</p>

</usage>

</directivesynopsis>

<directivesynopsis>

<name>DBDKeep</name>

<description>Maximum sustainednumber of connections</description>

<syntax>DBDKeep <var>number</var></syntax>

<contextlist><context>server config</context><context>virtual host</context>

</contextlist>

<usage>

    <p>Set the maximum number of connections per process to be

    sustained, other than for handling peak demand (threaded

    platforms only).</p>

</usage>

</directivesynopsis>

<directivesynopsis>

<name>DBDMax</name>

<description>Maximum number of connections</description>

<syntax>DBDMax <var>number</var></syntax>

<contextlist><context>server config</context><context>virtual host</context>

</contextlist>

<usage>

    <p>Set the hard maximum number of connections per process

    (threaded platforms only).</p>

</usage>

</directivesynopsis>

<directivesynopsis>

<name>DBDExptime</name>

<description>Keepalive time for idle connections</description>

<syntax>DBDExptime <var>time-in-seconds</var></syntax>

<contextlist><context>server config</context><context>virtual host</context>

</contextlist>

<usage>

    <p>Set the time to keep idle connections alive where the number

    of connections specified in DBDKeep has been exceeded (threaded

    platforms only).</p>

</usage>

</directivesynopsis>

</modulesynopsis>

<?xml version="1.0" encoding="UTF-8" ?>

<metafile>

  <basename>mod_dbd</basename>

  <path>/mod/</path>

  <relpath>..</relpath>

  <variants>

    <variant>en</variant>

  </variants>

</metafile>

/* Copyright 2003-5 WebThing Ltd

 * Copyright 2005 The Apache Software Foundation or its licensors, as

 * applicable.

 *

 * Licensed 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

 * or

 * http://apache.webthing.com/database/

 */

/* Bump the version for committing to apache svn */

#define VERSION "0.2"

#include <ctype.h>

#include "http_protocol.h"

#include "http_config.h"

#include "http_log.h"

#include "apr_reslist.h"

#include "apr_strings.h"

#include "apr_dbd.h"

#include "mod_dbd.h"

extern module AP_MODULE_DECLARE_DATA dbd_module;

/************ svr cfg: manage db connection pool ****************/

typedef struct dbd_prepared {

    const char *label;

    const char *query;

    struct dbd_prepared *next;

} dbd_prepared;

typedef struct svr_cfg {

    const char *name;

    const char *params;

    int persist;

    dbd_prepared *prepared;

#if APR_HAS_THREADS

    apr_reslist_t *dbpool;

    int nmin;

    int nkeep;

    int nmax;

    int exptime;

#else

    ap_dbd_t *conn;

#endif

} svr_cfg;

typedef enum { cmd_name, cmd_params, cmd_persist,

               cmd_min, cmd_keep, cmd_max, cmd_exp

} cmd_parts;

#define ISINT(val) \

        for (p = val; *p; ++p)        \

                if (!isdigit(*p))        \

                        return "Argument must be numeric!"

static const char *dbd_param(cmd_parms *cmd, void *cfg, const char *val)

{

    const char *p;

    apr_dbd_driver_t *driver = NULL;

    svr_cfg *svr = (svr_cfg*) ap_get_module_config

        (cmd->server->module_config, &dbd_module);

    switch ((int) cmd->info) {

    case cmd_name:

        svr->name = val;

        /* loading the driver involves once-only dlloading that is

         * best done at server startup.  This also guarantees that

         * load_driver won't return an error later.

         */

        switch (apr_dbd_get_driver(cmd->pool, svr->name, &driver)) {

        case APR_ENOTIMPL:

            return apr_psprintf(cmd->pool, "DBD: No driver for %s", svr->name);

        case APR_EDSOOPEN:

            return apr_psprintf(cmd->pool,

                                "DBD: Can't load driver file apr_dbd_%s.so",

                                svr->name);

        case APR_ESYMNOTFOUND:

            return apr_psprintf(cmd->pool,

                                "DBD: Failed to load driver apr_dbd_%s_driver",

                                svr->name);

        }

        break;

    case cmd_params:

        svr->params = val;

        break;

    case cmd_persist:

        ISINT(val);

        svr->persist = atoi(val);

        break;

#if APR_HAS_THREADS

    case cmd_min:

        ISINT(val);

        svr->nmin = atoi(val);

        break;

    case cmd_keep:

        ISINT(val);

        svr->nkeep = atoi(val);

        break;

    case cmd_max:

        ISINT(val);

        svr->nmax = atoi(val);

        break;

    case cmd_exp:

        ISINT(val);

        svr->exptime = atoi(val);

        break;

#endif

    }

    return NULL;

}

static const char *dbd_prepare(cmd_parms *cmd, void *cfg, const char *query,

                               const char *label)

{

    svr_cfg *svr = (svr_cfg*) ap_get_module_config

        (cmd->server->module_config, &dbd_module);

    dbd_prepared *prepared = apr_pcalloc(cmd->pool, sizeof(dbd_prepared));

    prepared->label = label;

    prepared->query = query;

    prepared->next = svr->prepared;

    svr->prepared = prepared;

    return NULL;

}

static const command_rec dbd_cmds[] = {

    AP_INIT_TAKE1("DBDriver", dbd_param, (void*)cmd_name, RSRC_CONF,

                  "SQL Driver"),

    AP_INIT_TAKE1("DBDParams", dbd_param, (void*)cmd_params, RSRC_CONF,

                  "SQL Driver Params"),

    AP_INIT_TAKE1("DBDPersist", dbd_param, (void*)cmd_persist, RSRC_CONF,

                  "Use persistent connection/pool"),

    AP_INIT_TAKE2("DBDPrepareSQL", dbd_prepare, NULL, RSRC_CONF,

                  "Prepared SQL statement, label"),

#if APR_HAS_THREADS

    AP_INIT_TAKE1("DBDMin", dbd_param, (void*)cmd_min, RSRC_CONF,

                  "Minimum number of connections"),

    AP_INIT_TAKE1("DBDKeep", dbd_param, (void*)cmd_keep, RSRC_CONF,

                  "Maximum number of sustained connections"),

    AP_INIT_TAKE1("DBDMax", dbd_param, (void*)cmd_max, RSRC_CONF,

                  "Maximum number of connections"),

    AP_INIT_TAKE1("DBDExptime", dbd_param, (void*)cmd_exp, RSRC_CONF,

                  "Keepalive time for idle connections"),

#endif

    {NULL}

};

#define COND_PARAM(x,val) \

    if (cfg->x == val) {              \

        cfg->x = ((svr_cfg*)base)->x; \

    }

#define COND_PARAM0(x) COND_PARAM(x,0)

#define COND_PARAM1(x) COND_PARAM(x,-1)

static void *dbd_merge(apr_pool_t *pool, void *base, void *add) {

    svr_cfg *cfg = apr_pmemdup(pool, add, sizeof(svr_cfg));

    COND_PARAM0(name);

    COND_PARAM0(params);

    COND_PARAM1(persist);

#if APR_HAS_THREADS

    COND_PARAM0(nmin);

    COND_PARAM0(nkeep);

    COND_PARAM0(nmax);

    COND_PARAM0(exptime);

#endif

    return cfg;

}

#undef COND_PARAM

#undef COND_PARAM0

#undef COND_PARAM1

static void *dbd_cfg(apr_pool_t *p, server_rec *x)

{

    svr_cfg *svr = (svr_cfg*) apr_pcalloc(p, sizeof(svr_cfg));

    svr->persist = -1;

    return svr;

}

static apr_status_t dbd_prepared_init(apr_pool_t *pool, svr_cfg *svr,

                                      ap_dbd_t *dbd)

{

    dbd_prepared *p;

    apr_status_t ret = APR_SUCCESS;

    apr_dbd_prepared_t *stmt = NULL;

    dbd->prepared = apr_hash_make(pool);

    for (p = svr->prepared; p; p = p->next) {

        if (apr_dbd_prepare(dbd->driver, pool, dbd->handle, p->query,

                            p->label, &stmt) == 0) {

            apr_hash_set(dbd->prepared, p->label, APR_HASH_KEY_STRING, stmt);

        }

        else {

            ret = APR_EGENERAL;

        }

    }

    return ret;

}

#if APR_HAS_THREADS

/************ svr cfg: manage db connection pool ****************/

/* an apr_reslist_constructor for SQL connections */

static apr_status_t dbd_construct(void **db, void *params, apr_pool_t *pool)

{

    svr_cfg *svr = (svr_cfg*) params;

    ap_dbd_t *rec = apr_pcalloc(pool, sizeof(ap_dbd_t));

    apr_status_t rv = apr_dbd_get_driver(pool, svr->name, &rec->driver);

    rv = apr_dbd_open(rec->driver, pool, svr->params, &rec->handle);

    switch (rv) {

    case APR_EGENERAL:

        ap_log_perror(APLOG_MARK, APLOG_CRIT, 0, pool,

                      "DBD: Can't connect to %s[%s]", svr->name, svr->params);

        return rv;

    }

    *db = rec;

    dbd_prepared_init(pool, svr, rec);

    return rv;

}

static apr_status_t dbd_destruct(void *sql, void *params, apr_pool_t *pool)

{

    ap_dbd_t *rec = sql;

    return apr_dbd_close(rec->driver, rec->handle);

}

static apr_status_t dbd_setup(apr_pool_t *pool, server_rec *s)

{

    svr_cfg *svr = ap_get_module_config(s->module_config, &dbd_module);

    apr_status_t rv = apr_reslist_create(&svr->dbpool, svr->nmin, svr->nkeep,

                                         svr->nmax, svr->exptime,

                                         dbd_construct, dbd_destruct,

                                         svr, pool);

    if (rv == APR_SUCCESS) {

        apr_pool_cleanup_register(pool, svr->dbpool,

                                  (void*)apr_reslist_destroy,

                                  apr_pool_cleanup_null);

    }

    else {

        ap_log_perror(APLOG_MARK, APLOG_CRIT, 0, pool,

                      "DBD Pool: failed to initialise");

    }

    return rv;

}

#endif

/* Functions we export for modules to use:

        - open acquires a connection from the pool (opens one if necessary)

        - close releases it back in to the pool

*/

#if APR_HAS_THREADS

ap_dbd_t* ap_dbd_open(apr_pool_t *pool, server_rec *s)

{

    ap_dbd_t *rec = NULL;

    svr_cfg *svr = ap_get_module_config(s->module_config, &dbd_module);

    apr_status_t rv;

    const char *errmsg;

    if (!svr->persist) {

        rec = apr_pcalloc(pool, sizeof(ap_dbd_t));

        rv = apr_dbd_get_driver(pool, svr->name, &rec->driver);

        rv = apr_dbd_open(rec->driver, pool, svr->params, &rec->handle);

        switch (rv) {

        case APR_EGENERAL:

            ap_log_perror(APLOG_MARK, APLOG_CRIT, 0, pool,

                          "DBD: Can't connect to %s[%s]",

                          svr->name, svr->params);

            return NULL;

        }

        dbd_prepared_init(pool, svr, rec);

        return rec;

    }

    if (!svr->dbpool) {

        if (dbd_setup(s->process->pool, s) != APR_SUCCESS) {

            return NULL;

        }

    }

    if (apr_reslist_acquire(svr->dbpool, (void**)&rec) != APR_SUCCESS) {

        ap_log_perror(APLOG_MARK, APLOG_ERR, 0, pool,

                      "Failed to acquire DBD connection from pool!");

        return NULL;

    }

    if (apr_dbd_check_conn(rec->driver, pool, rec->handle) != APR_SUCCESS) {

        errmsg = apr_dbd_error(rec->driver, rec->handle, rv);

        if (!errmsg) {

            errmsg = "(unknown)";

        }

        ap_log_perror(APLOG_MARK, APLOG_ERR, 0, pool,

                      "DBD[%s] Error: %s", svr->name, errmsg );

        apr_reslist_invalidate(svr->dbpool, rec);

        return NULL;

    }

    return rec;

}

#else

ap_dbd_t* ap_dbd_open(apr_pool_t *pool, server_rec *s)

{

    apr_status_t rv;

    const char *errmsg;

    ap_dbd_t *rec = NULL;

    svr_cfg *svr = ap_get_module_config(s->module_config, &dbd_module);

    if (!svr->persist) {

        rec = apr_pcalloc(pool, sizeof(ap_dbd_t));

        rv = apr_dbd_get_driver(pool, svr->name, &rec->driver);

        rv = apr_dbd_open(rec->driver, pool, svr->params, &rec->handle);

        switch (rv) {

        case APR_EGENERAL:

            ap_log_perror(APLOG_MARK, APLOG_CRIT, 0, pool,

                          "DBD: Can't connect to %s[%s]",

                          svr->name, svr->params);

            return NULL;

        }

        dbd_prepared_init(pool, svr, rec);

        return rec;

    }

/* since we're in nothread-land, we can mess with svr->conn with impunity */

    if (svr->conn) {

        if (apr_dbd_check_conn(svr->conn->driver, pool, svr->conn->handle) != 0){

            errmsg = apr_dbd_error(rec->driver, rec->handle, rv);

            if (!errmsg) {

                errmsg = "(unknown)";

            }

            ap_log_perror(APLOG_MARK, APLOG_ERR, 0, pool,

                          "DBD[%s] Error: %s", svr->name, errmsg);

            svr->conn = NULL;

        }

    }

    if (!svr->conn) {

        svr->conn = apr_pcalloc(pool, sizeof(ap_dbd_t));

        rv = apr_dbd_get_driver(pool, svr->name, &svr->conn->driver);

        rv = apr_dbd_open(svr->conn->driver, pool, svr->params,

                          &svr->conn->handle);

        switch (rv) {

        case APR_EGENERAL:

            ap_log_perror(APLOG_MARK, APLOG_CRIT, 0, pool,

                          "DBD: Can't connect to %s[%s]",

                          svr->name, svr->params);

            return NULL;

        }

        dbd_prepared_init(pool, svr, rec);

    }

    return svr->conn;

}

#endif

void ap_dbd_close(server_rec *s, ap_dbd_t *sql)

{

    svr_cfg *svr = ap_get_module_config(s->module_config, &dbd_module);

    if (!svr->persist) {

        apr_dbd_close(sql->driver, sql->handle);

    }

#if APR_HAS_THREADS

    else {

        apr_reslist_release(svr->dbpool, sql);

    }

#endif

}

#if APR_HAS_THREADS

typedef struct {

    ap_dbd_t *conn;

    apr_reslist_t *dbpool;

} dbd_pool_rec;

static apr_status_t dbd_release(void *REQ)

{

    dbd_pool_rec *req = REQ;

    apr_reslist_release(req->dbpool, req->conn);

    return APR_SUCCESS;

}

ap_dbd_t *ap_dbd_acquire(request_rec *r)

{

    svr_cfg *svr;

    dbd_pool_rec *req = ap_get_module_config(r->request_config, &dbd_module);

    if (!req) {

        req = apr_palloc(r->pool, sizeof(dbd_pool_rec));

        req->conn = ap_dbd_open(r->pool, r->server);

        if (req->conn) {

            svr = ap_get_module_config(r->server->module_config, &dbd_module);

            ap_set_module_config(r->request_config, &dbd_module, req);

            if (svr->persist) {

                req->dbpool = svr->dbpool;

                apr_pool_cleanup_register(r->pool, req, dbd_release,

                                          apr_pool_cleanup_null);

            }

            else {

                apr_pool_cleanup_register(r->pool, req->conn->handle,

                                          (void*)req->conn->driver->close,

                                          apr_pool_cleanup_null);

            }

        }

    }

    return req->conn;

}

#else

ap_dbd_t *ap_dbd_acquire(request_rec *r)

{

    svr_cfg *svr;

    ap_dbd_t *ret = ap_get_module_config(r->request_config, &dbd_module);

    if (!ret) {

        svr = ap_get_module_config(r->server->module_config, &dbd_module);

        ret = ap_dbd_open(r->pool, r->server);

        if ( ret ) {

            ap_set_module_config(r->request_config, &dbd_module, ret);

            if (!svr->persist) {

                apr_pool_cleanup_register(r->pool, svr->conn->handle,

                                          (void*)svr->conn->driver->close,

                                          apr_pool_cleanup_null);

            }

            /* if persist then dbd_open registered cleanup on proc pool */

        }

    }

    return ret;

}

#endif

static int dbd_token(apr_pool_t *pool,  apr_pool_t *p0,

                     apr_pool_t *p1, server_rec *s)

{

    svr_cfg *svr = ap_get_module_config(s->module_config, &dbd_module);

    if (svr && svr->name) {

        ap_add_version_component(pool, apr_psprintf(pool, "DBD:%s/%s",

                                                    svr->name, VERSION));

    }

    else {

        ap_add_version_component(pool, "DBD/" VERSION);

    }

    return OK;

}

static void dbd_hooks(apr_pool_t *pool)

{

#if APR_HAS_THREADS

    ap_hook_child_init((void*)dbd_setup, NULL, NULL, APR_HOOK_MIDDLE);

#endif

    ap_hook_post_config(dbd_token, NULL, NULL, APR_HOOK_MIDDLE);

    APR_REGISTER_OPTIONAL_FN(ap_dbd_open);

    APR_REGISTER_OPTIONAL_FN(ap_dbd_close);

    APR_REGISTER_OPTIONAL_FN(ap_dbd_acquire);

    apr_dbd_init(pool);

}

module AP_MODULE_DECLARE_DATA dbd_module = {

    STANDARD20_MODULE_STUFF,

    NULL,

    NULL,

    dbd_cfg,

    dbd_merge,

    dbd_cmds,

    dbd_hooks

};

/*        Copyright (c) 2004, Nick Kew.  All rights reserved.

        If this is accepted by ASF for inclusion in APR-UTIL,

        I will assign copyright to ASF and license under ASF terms.

        Otherwise I will retain copyright and license under

        terms of my choice.

*/

#ifndef DBD_H

#define DBD_H

#include <httpd.h>

#include <apr_optional.h>

#include <apr_hash.h>

typedef struct {

    apr_dbd_t *handle;

    apr_dbd_driver_t *driver;

    apr_hash_t *prepared;

} ap_dbd_t;

/* Export functions to access the database */

/* acquire a connection that MUST be explicitly closed.  Returns NULL on error */

AP_DECLARE(ap_dbd_t*) ap_dbd_open(apr_pool_t*, server_rec*);

/* release a connection acquired with ap_dbd_open */

AP_DECLARE(void) ap_dbd_close(server_rec*, ap_dbd_t*);

/* acquire a connection that will have the lifetime of a request

   and MUST NOT be explicitly closed.  Return NULL on error.

   This is the preferred function for most applications.

*/

AP_DECLARE(ap_dbd_t*) ap_dbd_acquire(request_rec*);

/* Also export them as optional functions for modules that prefer it */

APR_DECLARE_OPTIONAL_FN(ap_dbd_t*, ap_dbd_open, (apr_pool_t*, server_rec*));

APR_DECLARE_OPTIONAL_FN(void, ap_dbd_close, (server_rec*, ap_dbd_t*));