* Further clarify hook callback return convention

 *  DECLINED    Handler took no action.                                     *

 *  HTTP_mumble Handler looked at request and found it wanting.             *

 *                                                                          *

 * Handlers that are not declared as int return a valid pointer, or NULL if *

 * they DECLINE to handle their phase for that specific request.            *

 * Exceptions, if any, are noted with each routine.                         *

 * See include/httpd.h for a list of HTTP_mumble status codes.  Handlers    *

 * that are not declared as int return a valid pointer, or NULL if they     *

 * DECLINE to handle their phase for that specific request.  Exceptions, if *

 * any, are noted with each routine.                                        *

 *--------------------------------------------------------------------------*/

/*

    /*

     * Log the call and exit.

     */

    trace_add(NULL, NULL, NULL, "x_check_config()");

    trace_add(s, NULL, NULL, "x_check_config()");

    return OK;

}

 * It executes only once, in the startup process, after the check_config

 * phase and just before the process exits.  At this point the module

 * may output any information useful in configuration testing.

 *

 * This is a VOID hook: all defined handlers get called. 

 */

static void x_test_config(apr_pool_t *pconf, server_rec *s)

{

    apr_file_open_stderr(&out, pconf);

    apr_file_printf(out, "Example module configuration test routine\n");

    trace_add(s, NULL, NULL, "x_test_config()");

}

/*

    /*

     * Log the call and exit.

     */

    trace_add(NULL, NULL, NULL, "x_post_config()");

    trace_add(s, NULL, NULL, "x_post_config()");

    return OK;

}

/*

 * All our process initialiser does is add its trace to the log.

 *

 * This is a VOID hook: all defined handlers get called. 

 */

static void x_child_init(apr_pool_t *p, server_rec *s)

{

}

/*

 * XXX: This routine is called XXX

 * The hook runner for ap_hook_http_scheme is aliased to ap_http_scheme(), 

 * a routine that the core and other modules call when they need to know 

 * the URL scheme for the request.  For instance, mod_ssl returns "https"

 * if the server_rec associated with the request has SSL enabled. 

 *

 * The return value is OK, DECLINED, or HTTP_mumble.  If we return OK, the

 * server will still call any remaining modules with an handler for this

 * phase.

 * This hook was named 'ap_hook_http_method' in httpd 2.0. 

 *

 * This is a RUN_FIRST hook: the first handler to return a non NULL 

 * value aborts the handler chain.  The http_core module inserts a 

 * fallback handler (with APR_HOOK_REALLY_LAST preference) that returns

 * "http". 

 */

static const char *x_http_scheme(const request_rec *r)

{

    /*

     * Log the call and exit.

     */

    trace_add(r->server, NULL, cfg, "x_http_scheme()");

    trace_add(r->server, (request_rec *) r, cfg, "x_http_scheme()");

    /* We have no claims to make about the request scheme */

    return NULL;

}

/*

 * XXX: This routine is called XXX

 * The runner for this hook is aliased to ap_default_port(), which the

 * core and other modules call when they need to know the default port

 * for a particular server.  This is used for instance to omit the 

 * port number from a Redirect response Location header URL if the port

 * number is equal to the default port for the service (like 80 for http). 

 *

 * The return value is OK, DECLINED, or HTTP_mumble.  If we return OK, the

 * server will still call any remaining modules with an handler for this

 * phase.

 * This is a RUN_FIRST hook: the first handler to return a non-zero 

 * value is the last one executed.  The http_core module inserts a 

 * fallback handler (with APR_HOOK_REALLY_LAST order specifier) that

 * returns 80. 

 */

static apr_port_t x_default_port(const request_rec *r)

{

    /*

     * Log the call and exit.

     */

    trace_add(r->server, NULL, cfg, "x_default_port()");

    trace_add(r->server, (request_rec *) r, cfg, "x_default_port()");

    return 0;

}

/*

 * XXX: This routine is called XXX

 * This routine is called just before the handler gets invoked. It allows

 * a module to insert a previously defined filter into the filter chain. 

 * 

 * The return value is OK, DECLINED, or HTTP_mumble.  If we return OK, the

 * server will still call any remaining modules with an handler for this

 * phase.

 * No filter has been defined by this module, so we just log the call

 * and exit. 

 *

 * This is a VOID hook: all defined handlers get called. 

 */

static void x_insert_filter(request_rec *r)

{

    /*

     * Log the call and exit.

     */

    trace_add(r->server, NULL, cfg, "x_insert_filter()");

    trace_add(r->server, r, cfg, "x_insert_filter()");

}

/* 

 * This routine is called to insert a previously defined error filter into 

 * the filter chain as the request is being processed. 

 * 

 * For the purpose of this example, we don't have a filter to insert, 

 * so just add to the trace and exit. 

 * 

 * This is a VOID hook: all defined handlers get called. 

 */

static void x_insert_error_filter(request_rec *r)

{

    x_cfg *cfg;

    cfg = our_dconfig(r);

    trace_add(r->server, r, cfg, "x_insert_error_filter()");

}

/*--------------------------------------------------------------------------*/

 * Sample content handler.  All this does is display the call list that has

 * been built up so far.

 * 

 * The return value instructs the caller concerning what happened and what to

 * do next:

 *  OK ("we did our thing")

 *  DECLINED ("this isn't something with which we want to get involved")

 *  HTTP_mumble ("an error status should be reported")

 * This routine gets called for every request, unless another handler earlier

 * in the callback chain has already handled the request. It is up to us to 

 * test the request_rec->handler field and see whether we are meant to handle 

 * this request. 

 *

 * The content handler gets to write directly to the client using calls like 

 * ap_rputs() and ap_rprintf()

 *

 * This is a RUN_FIRST hook. 

 */

static int x_handler(request_rec *r)

{

    x_cfg *dcfg;

    int result;

    char *note;

    dcfg = our_dconfig(r);

    /* 

     * Add our trace to the log, and whether we get to write 

     * content for this request. 

     */

    note = apr_pstrcat(r->pool, "x_handler(), handler is \"", 

                      r->handler, "\"", NULL);

    trace_add(r->server, r, dcfg, note);

    /* If it's not for us, get out as soon as possible. */

    if (strcmp(r->handler, "example-handler")) {

        return DECLINED;

    }

    dcfg = our_dconfig(r);

    trace_add(r->server, r, dcfg, "x_handler()");

    /*

     * We're about to start sending content, so we need to force the HTTP

     * headers to be sent at this point.  Otherwise, no headers will be sent

     * at all.  We can set any we like first, of course.  **NOTE** Here's

     * where you set the "Content-type" header, and you do so by putting it in

     * r->content_type, *not* r->headers_out("Content-type").  If you don't

     * set it, it will be filled in with the server's default type (typically

     * "text/plain").  You *must* also ensure that r->content_type is lower

     * case.

     *

     * We also need to start a timer so the server can know if the connexion

     * is broken.

     * Set the Content-type header. Note that we do not actually have to send 

     * the headers: this is done by the http core. 

     */

    ap_set_content_type(r, "text/html");

    /*

}

/*

 * XXX: This routine is called XXX

 * The quick_handler hook presents modules with a very powerful opportunity to 

 * serve their content in a very early request phase.  Note that this handler 

 * can not serve any requests from the file system because hooks like 

 * map_to_storage have not run.  The quick_handler hook also runs before any 

 * authentication and access control. 

 *

 * The return value is OK, DECLINED, or HTTP_mumble.  If we return OK, the

 * server will still call any remaining modules with an handler for this

 * phase.

 * This hook is used by mod_cache to serve cached content.  

 *

 * This is a RUN_FIRST hook. Return OK if you have served the request, DECLINED 

 * if you want processing to continue, or a HTTP_* error code to stop processing 

 * the request. 

 */

static int x_quick_handler(request_rec *r, int lookup_uri)

{

 * as soon as possible. The core server uses this phase to setup the

 * connection record based on the type of connection that is being used.

 *

 * The return value is OK, DECLINED, or HTTP_mumble.  If we return OK, the

 * server will still call any remaining modules with an handler for this

 * phase.

 * This is a RUN_ALL hook.

 */

static int x_pre_connection(conn_rec *c, void *csd)

{

    x_cfg *cfg;

    cfg = our_cconfig(c);

#if 0

    /*

     * Log the call and exit.

     */

    trace_add(r->server, NULL, cfg, "x_pre_connection()");

#endif

    trace_add(NULL, NULL, cfg, "x_pre_connection()");

    return OK;

}

 * some other protocol.  Both echo and POP3 modules are available as

 * examples.

 *

 * The return VALUE is OK, DECLINED, or HTTP_mumble.  If we return OK, no

 * further modules are called for this phase.

 * This is a RUN_FIRST hook.

 */

static int x_process_connection(conn_rec *c)

{

    x_cfg *cfg;

    cfg = our_cconfig(c);

    trace_add(NULL, NULL, cfg, "x_process_connection()");

    return DECLINED;

}

 * phases have been processed.  This allows us to make decisions based upon

 * the input header fields.

 *

 * The return value is OK, DECLINED, or HTTP_mumble.  If we return OK, no

 * further modules are called for this phase.

 * This is a RUN_ALL hook.

 */

static int x_post_read_request(request_rec *r)

{

 * actual filename.  If we don't do anything special, the server's default

 * rules (Alias directives and the like) will continue to be followed.

 *

 * The return value is OK, DECLINED, or HTTP_mumble.  If we return OK, no

 * further modules are called for this phase.

 * This is a RUN_FIRST hook.

 */

static int x_translate_handler(request_rec *r)

static int x_translate_name(request_rec *r)

{

    x_cfg *cfg;

     * We don't actually *do* anything here, except note the fact that we were

     * called.

     */

    trace_add(r->server, r, cfg, "x_translate_handler()");

    trace_add(r->server, r, cfg, "x_translate_name()");

    return DECLINED;

}

 * overriding default core behavior, including skipping mapping for

 * requests that are not file based.

 *

 * The return value is OK, DECLINED, or HTTP_mumble.  If we return OK, no

 * further modules are called for this phase.

 * This is a RUN_FIRST hook.

 */

static int x_map_to_storage_handler(request_rec *r)

static int x_map_to_storage(request_rec *r)

{

    x_cfg *cfg;

     * We don't actually *do* anything here, except note the fact that we were

     * called.

     */

    trace_add(r->server, r, cfg, "x_map_to_storage_handler()");

    trace_add(r->server, r, cfg, "x_map_to_storage()");

    return DECLINED;

}

 * to the filename. For example this phase can be used to block evil

 * clients, while little resources were wasted on these.

 *

 * The return value is OK, DECLINED, or HTTP_mumble.  If we return OK,

 * the server will still call any remaining modules with an handler

 * for this phase.

 * This is a RUN_ALL hook. 

 */

static int x_header_parser_handler(request_rec *r)

static int x_header_parser(request_rec *r)

{

    x_cfg *cfg;

     * We don't actually *do* anything here, except note the fact that we were

     * called.

     */

    trace_add(r->server, r, cfg, "header_parser_handler()");

    trace_add(r->server, r, cfg, "x_header_parser()");

    return DECLINED;

}

 * the request (such as looking up the user in a database and verifying that

 * the [encrypted] password sent matches the one in the database).

 *

 * The return value is OK, DECLINED, or some HTTP_mumble error (typically

 * HTTP_UNAUTHORIZED).  If we return OK, no other modules are given a chance

 * at the request during this phase.

 * This is a RUN_FIRST hook. The return value is OK, DECLINED, or some 

 * HTTP_mumble error (typically HTTP_UNAUTHORIZED).  

 */

static int x_check_user_id(request_rec *r)

{

 * This routine is called to check to see if the resource being requested

 * requires authorisation.

 *

 * The return value is OK, DECLINED, or HTTP_mumble.  If we return OK, no

 * other modules are called during this phase.

 * This is a RUN_FIRST hook. The return value is OK, DECLINED, or HTTP_mumble.  

 * If we return OK, no other modules are called during this phase.

 *

 * If *all* modules return DECLINED, the request is aborted with a server

 * error.

 * This routine is called to check for any module-specific restrictions placed

 * upon the requested resource.  (See the mod_access module for an example.)

 *

 * The return value is OK, DECLINED, or HTTP_mumble.  All modules with an

 * handler for this phase are called regardless of whether their predecessors

 * return OK or DECLINED.  The first one to return any other status, however,

 * will abort the sequence (and the request) as usual.

 * This is a RUN_ALL hook. The first handler to return a status other than OK

 * or DECLINED (for instance, HTTP_FORBIDDEN) aborts the callback chain. 

 */

static int x_access_checker(request_rec *r)

{

 * information bits, like Content-type (via r->content_type), language, et

 * cetera.

 *

 * The return value is OK, DECLINED, or HTTP_mumble.  If we return OK, no

 * further modules are given a chance at the request for this phase.

 * This is a RUN_FIRST hook.

 */

static int x_type_checker(request_rec *r)

{

 * This routine is called to perform any module-specific fixing of header

 * fields, et cetera.  It is invoked just before any content-handler.

 *

 * The return value is OK, DECLINED, or HTTP_mumble.  If we return OK, the

 * server will still call any remaining modules with an handler for this

 * phase.

 * This is a RUN_ALL HOOK.

 */

static int x_fixer_upper(request_rec *r)

static int x_fixups(request_rec *r)

{

    x_cfg *cfg;

    /*

     * Log the call and exit.

     */

    trace_add(r->server, r, cfg, "x_fixer_upper()");

    trace_add(r->server, r, cfg, "x_fixups()");

    return OK;

}

 * This routine is called to perform any module-specific logging activities

 * over and above the normal server things.

 *

 * The return value is OK, DECLINED, or HTTP_mumble.  If we return OK, any

 * remaining modules with an handler for this phase will still be called.

 * This is a RUN_ALL hook. 

 */

static int x_logger(request_rec *r)

static int x_log_transaction(request_rec *r)

{

    x_cfg *cfg;

    cfg = our_dconfig(r);

    trace_add(r->server, r, cfg, "x_logger()");

    trace_add(r->server, r, cfg, "x_log_transaction()");

    return DECLINED;

}

/* 

 * This routine is called to insert a previously defined error filter into 

 * the filter chain as the request is being processed. 

 * 

 * For the purpose of this example, we don't have a filter to insert, 

 * so just add to the trace and exit. 

 * 

 * There is no return code. 

 */

static void x_insert_error_filter(request_rec *r)

{

    x_cfg *cfg;

    cfg = our_dconfig(r);

    trace_add(r->server, r, cfg, "x_insert_error_filter()");

}

/*

 * This routine is called to find out under which user id to run suexec

 * Unless our module runs CGI programs, there is no reason for us to 

 * mess with this information. 

 * 

 * The return value is a pointer to an ap_unix_identity_t or NULL. If we 

 * return a non-NULL pointer, no further callbacks in the chain for this

 * hook will be called. 

 * This is a RUN_FIRST hook. The return value is a pointer to an 

 * ap_unix_identity_t or NULL. 

 */

static ap_unix_identity_t *x_get_suexec_identity(const request_rec *r) 

{

 * This hook is defined in server/core.c, but it is not actually called 

 * or documented. 

 * 

 * This is a RUN_ALL hook: all routines in the chain will be called. If 

 * one of the routines on the chain returns OK, the hook run will return OK. 

 * Otherwise the result will be DECLINED. 

 * This is a RUN_ALL hook. 

 */

static int x_get_mgmt_items(apr_pool_t *p, const char *val, apr_hash_t *ht)

{

 * is created. It provides the opportunity to manipulae the request 

 * at a very early stage. 

 *

 * This is a RUN_ALL hook. The return value can be OK, DECLINED or 

 * HTTP_mumble.

 * This is a RUN_ALL hook. 

 */

static int x_create_request(request_rec *r)

{

 * This routine gets called during the startup of the MPM. 

 * No known existing module implements this hook. 

 * 

 * This is a RUN_ALL hook. The return value can be OK, DECLINED or

 * HTTP_mumble. 

 * This is a RUN_ALL hook. 

 */

static int x_pre_mpm(apr_pool_t *p, ap_scoreboard_e sb_type)

{

    return DECLINED;

}

/*

 * This hook gets run periodically by a maintenance function inside

 * the MPM. Its exact purpose is unknown and undocumented at this time. 

 * 

 * This is a RUN_ALL hook. 

 */

static int x_monitor(apr_pool_t *p)

{

    apr_file_t *out = NULL;

    apr_file_open_stderr(&out, p);

    apr_file_printf(out, "Example module monitor hook handler\n");

    trace_add(NULL, NULL, NULL, "x_monitor()");

    return DECLINED;

}

/*--------------------------------------------------------------------------*/

/*                                                                          */

/* Which functions are responsible for which hooks in the server.           */

    /* [1] post read_request handling */

    ap_hook_post_read_request(x_post_read_request, NULL, NULL,

                              APR_HOOK_MIDDLE);

    ap_hook_log_transaction(x_logger, NULL, NULL, APR_HOOK_MIDDLE);

    ap_hook_log_transaction(x_log_transaction, NULL, NULL, APR_HOOK_MIDDLE);

    ap_hook_http_scheme(x_http_scheme, NULL, NULL, APR_HOOK_MIDDLE);

    ap_hook_default_port(x_default_port, NULL, NULL, APR_HOOK_MIDDLE);

    ap_hook_translate_name(x_translate_handler, NULL, NULL, APR_HOOK_MIDDLE);

    ap_hook_map_to_storage(x_map_to_storage_handler, NULL,NULL, APR_HOOK_MIDDLE);

    ap_hook_header_parser(x_header_parser_handler, NULL, NULL, APR_HOOK_MIDDLE);

    ap_hook_translate_name(x_translate_name, NULL, NULL, APR_HOOK_MIDDLE);

    ap_hook_map_to_storage(x_map_to_storage, NULL,NULL, APR_HOOK_MIDDLE);

    ap_hook_header_parser(x_header_parser, NULL, NULL, APR_HOOK_MIDDLE);

    ap_hook_check_user_id(x_check_user_id, NULL, NULL, APR_HOOK_MIDDLE);

    ap_hook_fixups(x_fixer_upper, NULL, NULL, APR_HOOK_MIDDLE);

    ap_hook_fixups(x_fixups, NULL, NULL, APR_HOOK_MIDDLE);

    ap_hook_type_checker(x_type_checker, NULL, NULL, APR_HOOK_MIDDLE);

    ap_hook_access_checker(x_access_checker, NULL, NULL, APR_HOOK_MIDDLE);

    ap_hook_auth_checker(x_auth_checker, NULL, NULL, APR_HOOK_MIDDLE);

    ap_hook_get_mgmt_items(x_get_mgmt_items, NULL, NULL, APR_HOOK_MIDDLE);

    ap_hook_create_request(x_create_request, NULL, NULL, APR_HOOK_MIDDLE);

    ap_hook_pre_mpm(x_pre_mpm, NULL, NULL, APR_HOOK_MIDDLE);

    ap_hook_monitor(x_monitor, NULL, NULL, APR_HOOK_MIDDLE); 

}

/*--------------------------------------------------------------------------*/