Writing Apache Modules with Perl and C By:   Lincoln Stein and Doug MacEachern Published:   O'Reilly & Associates, Inc.  - March 1999 Copyright © 1999 by O'Reilly & Associates, Inc.

Chapter 10 - C API Reference Guide, Part I / Major Data Structures
The module Record

In this section...

Introduction STANDARD_MODULE_STUFF Handler and callback slots

Introduction

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.

The 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 need and 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 =
{
  STANDARD_MODULE_STUFF,
  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,     /* [9]  content handlers              */
  NULL,               /* [2]  URI-to-filename translation   */
  NULL,               /* [5]  check/validate user_id        */
  NULL,               /* [6]  check user_id is valid *here* */
  NULL,               /* [4]  check access by host address  */
  NULL,               /* [7]  MIME type checker/setter      */
  NULL,               /* [8]  fixups                        */
  NULL,               /* [10] logger                        */
  NULL,               /* [3]  header parser                 */
  NULL,               /* process initialization             */
  NULL,               /* process exit/cleanup               */
  NULL                /* [1]  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

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:

int version

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.

int minor_version

The server API minor version the module was compiled with. This value is defined by the macro 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.

int module_index

Holds a unique index number assigned to the module at runtime and is used for lookups by the internal configuration system.

const char *name

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 __FILE__ token.

void *dynamic_load_handle

A void * 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.

struct module_struct *next

A pointer to the next module in the internal linked list.

You should never have to worry about these fields. Just include the STANDARD_MODULE_STUFF macro at the top of your module structure and forget about it.