Show Contents Previous Page Next Page
Chapter 10 - C API Reference Guide, Part I / Major Data Structures
The module Record
In this section...
Introduction Show Contents Go to Top Previous Page Next Page
Our Perl examples have plugged into the various phases of the request cycle via the various Perl*Handler directives. There are no such directives for C modules. Instead, all C modules contain a compiled data structure of type
module. At run-time, all loaded modules are linked together via a linked list rooted at the Apache global
top_module. Apache then consults each
module table in turn to determine what phases of the transaction the module wishes to handle.
module structure is usually defined at the bottom of the
module's C source code file. Most module writers begin by cutting and pasting
this definition from another source code file, filling in the slots that they
NULLing out those that they don't want. In this tradition,
let's revisit the mod_hello module introduced in Chapter 2,
A First Module:
module MODULE_VAR_EXPORT hello_module =
NULL, /* module initializer */
NULL, /* per-directory config creator */
NULL, /* dir config merger */
NULL, /* server config creator */
NULL, /* server config merger */
NULL, /* config directive table */
hello_handlers, /*  content handlers */
NULL, /*  URI-to-filename translation */
NULL, /*  check/validate user_id */
NULL, /*  check user_id is valid *here* */
NULL, /*  check access by host address */
NULL, /*  MIME type checker/setter */
NULL, /*  fixups */
NULL, /*  logger */
NULL, /*  header parser */
NULL, /* process initialization */
NULL, /* process exit/cleanup */
NULL /*  post read_request handling */
module is a typedef, which you will find defined in the Apache source tree under include/http_config.h.
MODULE_VAR_EXPORT is a define that can be found in the platform-specific os.h header files. Its purpose is to export the
module data structure from the module's DLL under Win32 systems so the server core library is able to see it. On other systems,
MODULE_VAR_EXPORT is simply a define which does nothing, as you can see in the file include/ap_config.h.
While you can name the module record and its source file anything you like, you are encouraged to follow the Apache convention of naming the module something_module and its source file mod_something. This will make it easier for you and others to remember the module name and avoids conflict with apxs and the DSO loading system, which sometimes depend on this convention.
STANDARD_MODULE_STUFF Show Contents Go to Top Previous Page Next Page
The first few bits of
module structure consist of boilerplate code that is filled in by the
STANDARD_MODULE_STUFF preprocessor macro. Although you'll probably never have to access these fields yourself, here is a list of what's there in case you're wondering:
The server API version the module was compiled with and is used to make sure that the
module is binary-compatible with the version of the server. This is defined by the macro
MODULE_MAGIC_NUMBER_MAJOR found in the header file ap_mmn.h. The ap_
mmn.h header file also includes a list of the changes which call for a "bump" of the
MODULE_MAGIC_NUMBER_MAJOR version. This value can be used by modules to
provide compatibility between Apache versions.
The server API minor version the module was compiled with. This value is defined by
MODULE_MAGIC_NUMBER_MINOR, found in the header file ap_mmn.h.
This value is not checked by the server, as minor API changes do not break binary compatibility.
Holds a unique index number assigned to the module at runtime and is used for lookups
by the internal configuration system.
The name of the module, derived from the file in which the structure was declared. This
is determined at compile time by taking the basename of the C compiler's
* slot which can be used to hold a handle to the module if it was compiled as a
dynamic shared object (DSO) and loaded with LoadModule.
A pointer to the next module in the internal linked list.
You should never have to worry about these fields. Just include the Show Contents Go to Top Previous Page Next Page
STANDARD_MODULE_STUFF macro at the top of your
module structure and forget about it.
Copyright © 1999 by O'Reilly & Associates, Inc.