Show Contents Previous Page Next Page
Chapter 10 - C API Reference Guide, Part I / Major Data Structures / The module Record
Handler and callback slots
The rest of the
module structure is mostly function pointers.
Each field holds the address of a routine to invoke during the server's various
initialization, transaction, and cleanup phases, or
NULL if there
is no routine to call. Because the Apache API was developed over time, the order
of handlers in the
module table does not correspond to the order
in which they are called during the request cycle. We will describe them in
the order in which they appear in the data structure. See Chapter 3,
The Apache Module Architecture and API, for the correct
Module initialization handler
void module_init(server_rec *s, pool *p);
This handler is called during the module initialization phase immediately after the server is started. This is where modules initialize data, consult configuration files, or do other preparatory work in the parent server before any children are forked off or threads spawned.
Under Unix and other process forking systems, each child process will inherit its own
copy of any data structures created during this phase. Under threading systems, module
authors will need to take care of maintaining per-thread instances of such data if
The initialization function will be called with two arguments: a pointer to the current
server_rec structure (described in detail below) and a pointer to a resource pool whose
lifetime ends only when the server is finally shut down.
For an example of a module that steps in during this phase, see mod_mime, which builds
its MIME types hash table from the mime.types file once during initialization.
Configuration creation and merging routines (four of them!)
void *create_dir_config (pool *p, char *dir)
void *merge_dir_config (pool *p, void *base_conf, void *new_conf)
void *create_server_config (pool *p, server_rec *s)
void *merge_server_config (pool *p, void *base_conf, void *new_conf)
Modules may add their own configuration directives to the server, which
will then act just like built-in configuration directives. However, the server
core knows nothing about what to do with these directives, and instead passes
back the preparsed directives to the module for processing.
These four slots contain pointers to optional routines for handling module-specific
configuration data blocks. You are not obliged to fill in all of them, or
indeed any at all. See "Implementing Configuration Directives in C" in Chapter 11,
C API Reference Guide, Part II, for details.
Configuration directive (command) table
command_table field holds a pointer to a
command_rec structure, which describes each of the module's configuration directives in detail and points back to configuration callbacks to process the directives.
command_rec structure is described in detail in Chapter 11
under "Implementing Configuration Directives in C."
Response handlers table
The next field contains the module dispatch table for the response phase of the request. It can be used to map one or more MIME content types to content handlers defined within the module or to map symbolic handler names to handler functions.
Here is a slightly expanded version of our Chapter 2mod_hello example:
static handler_rec hello_handlers =
The handler table is an array of
handler_rec structures. The
last entry in the array must be a
NULL record. Each
entry in the array has the following simple structure:
The first element is the content type or the symbolic handler name. As described
in the introduction to Chapter 4, Content
Handlers, Apache will dispatch on the handler name or the MIME type,
depending on the current directory's configuration. In this example, the hello_handler()
content-handling subroutine is associated both with the symbolic handler name
hello-handler and a magic MIME type of application/x-hello.
This means that you can arrange for the content handler to be invoked either
by setting the handler explicitly in a <Directory> or <Location>
hello-handler, or by setting
the handler implicitly by requesting a document of MIME type application/x-hello
(since there is no default MIME file extension mapping for this type of document,
you'll have to make one up using AddType).
It is perfectly valid for several modules to register their interest in handling
the same MIME type. Apache will call them from most recent to least recent until
one returns a status code other than
DECLINED. It is also possible
to use wildcards in the MIME type. For example, the http_core default
*/*, indicating that it will handle a request
of any type that is not handled by a more specific module.
This is a pointer to the content handler subroutine that will be invoked to
process the request at response time. As with the other HTTP request time callbacks,
the function is passed a
* structure and
is expected to return an integer status value. The list of symbolic status code
constants can be found in the header file httpd.h. The constants are
identical to the list given in Table 3-1.
The content handler is something of an oddball among the various handlers
because it is registered indirectly through the
structure allows modules to register multiple handlers for the response phase,
leaving Apache to select one of them based on the content_type for
a given request. As we are about to see, handlers for the other phases are plugged
directly into the
URI translation handler
int translate_handler(request_rec *r)
This is the slot where a pointer to the URI translation handler, if any,
is plugged in. It receives an argument consisting of a
pointer and is expected to return an integer status code. Unless explicitly
stated otherwise, the other phase handlers have similar calling conventions.
int check_user_id(request_rec *r)
This is the slot where a pointer to the authentication handler, if any,
int auth_checker(request_rec *r)
This is the slot where the authorization handler subroutine, if any,
int access_checker(request_rec *r)
This is the slot where the access control handler subroutine, if any,
MIME type handler
int type_checker(request_rec *r)
This is the slot where the MIME type checker subroutine, if any,
int fixer_upper(request_rec *r)
This is the slot where the fixup handler, if any, is registered.
int logger(request_rec *r)
This is the slot where the logging handler, if any, is registered.
Header parser handler
int header_parser(request_rec *r)
This is the slot where the header parser handler subroutine,
if any, is registered.
Child initialization handler
void child_init(server_rec *s, pool *p)
This is where the child initialization subroutine is registered.
Unlike other handlers, this subroutine is not called with
a request record (there is no request at this stage). Instead,
it is called with two arguments consisting of a
pointer and a resource pool. It can do any processing or initialization
it needs. If the routine needs to allocate some private storage,
it can allocate memory from the resource pool and store a
pointer to the returned structure in a static variable. The
memory contained in the pool will not be released until the
child process exits.
The child_init function should return no result.
Child exit handler
void child_exit(server_rec *r, pool *p)
This is the slot where the child exit handler is called.
The exit handler should undo everything that the child init
handler did. The handler is called with a
pointer and a resource pool and should return no function
Post read request handler
int post_read_request(request_rec *r)
Show Contents Previous Page Next Page
This is the slot where the post read request handler subroutine, if any,
Copyright © 1999 by O'Reilly & Associates, Inc.