Chapter 15. Writing Apache Modules
One
of the great things about Apache is that if you don't like what
it does, you can change it. Now, this is true for any package with
source code available, but Apache is different. It has a generalized
interface to modules that extends the functionality of the base
package. In fact, when you download Apache you get far more than just
the base package, which is barely capable of serving files at all.
You get all the modules the Apache Group considers vital to a web
server. You also get modules that are useful enough to most people to
be worth the effort of the Group to maintain them.
In this chapter, we explore the intricacies of programming modules
for Apache.[79] We expect you to be thoroughly
conversant in C and Unix (or Win32), because we are not going to
explain anything about them. Refer to Chapter 14, "The Apache API",
or your Unix/Win32 manuals for information about functions used in
the examples. We also assume that you are familiar with the HTTP/1.1
specification, where relevant. Fortunately, for many purposes, you
don't have to know much about HTTP/1.1.
[79]For more on Apache modules, see
Writing Apache Modules with Perl and C, by
Lincoln Stein and Doug MacEachern (O'Reilly &
Associates).
15.1. Overview
Perhaps the most important part of an Apache module is the
module
structure. This is defined in
http_config.h, so all modules should start
(apart from copyright notices, etc.) with the following lines:
#include "httpd.h"
#include "http_config.h"
Note that httpd.h is required for all Apache
source code.
What is the module structure for? Simple: It
provides the glue between the Apache core and the module's
code. It contains pointers (to functions, lists, and so on) that are
used by components of the core at the correct moments. The core knows
about the various module structures because they
are listed in modules.c, which is generated by
the Configure script from the
Configuration file.[80]
[80]Which means,
of course, that one should not edit modules.c by
hand. Rather, the Configuration file should be
edited; see Chapter 1, "Getting Started".
Traditionally, each module ends with its module
structure. Here is a particularly trivial example, from
mod_asis.c:
module asis_module = {
STANDARD_MODULE_STUFF,
NULL, /* initializer */
NULL, /* create per-directory config structure */
NULL, /* merge per-directory config structures */
NULL, /* create per-server config structure */
NULL, /* merge per-server config structures */
NULL, /* command table */
asis_handlers, /* handlers */
NULL, /* translate_handler */
NULL, /* check_user_id */
NULL, /* check auth */
NULL, /* check access */
NULL, /* type_checker */
NULL, /* prerun fixups */
NULL /* logger */
NULL, /* header parser */
NULL, /* child_init */
NULL, /* child_exit */
NULL /* post read request */
};
The first entry, STANDARD_MODULE_STUFF, must
appear in all module structures. It initializes
some structure elements that the core uses to manage modules.
Currently, these are the API version number,[81] the index of the module
in various vectors, the name of the module (actually its filename),
and a pointer to the next module structure in a
linked list of all modules.[82]
[81]Used, in
theory, to adapt to old precompiled modules that used an earlier
version of the API. We say "in theory" because it is not
used this way in practice.
[82]The head of this list is
top_module. This is occasionally useful to know.
The list is actually set up at runtime.
The only other
entry is for handlers. We will look at this in
more detail further on. Suffice it to say, for now, that this entry
points to a list of strings and functions that define the
relationship between MIME or handler types and the functions that
handle them. All the other entries are defined to
NULL, which simply means that the module does not
use those particular hooks.
![Previous](../gifs/txtpreva.gif) | ![Home](../gifs/txthome.gif) | ![Next](../gifs/txtnexta.gif) | 14.6. Functions | ![Book Index](../gifs/index.gif) | 15.2. Status Codes |
Copyright © 2001 O'Reilly & Associates. All rights reserved.
|
|