Now that we have an overview of request processing in Apache, we can
proceed to show how a module hooks into it to play a part.
The apache module structure declares several (optional) data and function
members:
module AP_MODULE_DECLARE_DATA my_module = {
STANDARD20_MODULE_STUFF,
my_dir_conf,
my_dir_merge,
my_server_conf,
my_server_merge,
my_cmds,
my_hooks
} ;
The relevant function for the module to create request processing hooks
is the final member:
static void my_hooks(apr_pool_t* pool) {
/* create request processing hooks as required */
}
What hooks we need to create here depend on what part or parts of the
request our module is interested in. For example, a module that
implements a content generator (handler) will need a handler hook,
looking something like:
ap_hook_handler(my_handler, NULL, NULL, APR_HOOK_MIDDLE) ;
Now my_handler will be called when a request reaches the content
generation phase. Hooks for other request phases are similar;
a few commonly used ones are:
ap_hook_post_read_request
- First chance to look at the request after accepting it.
ap_hook_fixups
- Last chance to look at the request before content generation.
ap_hook_log_transaction
- Logging hook.
Between the general post_read_request
and fixups
hooks are several
other hooks designated for specific purposes: for example
access and authentication modules have specific hooks for checking
permissions. All these hooks take exactly the same form as the
handler hook. For further details, see http_config.h
.
The prototype for a handler for any of these phases is:
static int my_handler(request_rec* r) {
/* do something with the request */
}
The request_rec is the main apache data structure representing all aspects
of an HTTP request.
The return value of my_handler is one of:
- OK
- my_handler has handled the request successfully. The handler phase
is finished.
- DECLINED
- my_handler is not interested in this request. Let some other handler
deal with it.
- Any HTTP response code
- An error condition occurred while processing the request. This
diverts the request processing path: normal processing is aborted,
and the server instead returns an ErrorDocument.
Implementation of the handlers will be discussed in other articles.