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 11 - C API Reference Guide, Part II / Implementing Configuration Directives in C
The command_rec Structure

A module defines custom configuration directives using the config directive table slot of its module structure. This table is a pointer to an array of command_rec records having the structure shown in Example 11-1. Usually this array of command_rec data is created as a static data structure in the module source code. The last element of the array must be NULL. As a concrete example, here's a short command_rec definition borrowed from mod_actions.c:

static const command_rec action_cmds[] =
{
   {"Action", add_action, NULL, OR_FILEINFO, TAKE2,
    "a media type followed by a script name"},
   {"Script", set_script, NULL, ACCESS_CONF | RSRC_CONF, TAKE2,
    "a method followed by a script name"},
   {NULL}
};

The action_cmds array declares two directives: Action, which is processed by a handler routine named add_action(), and Script, processed by set_script().

Example 11-1. The command_rec Struct (from http_config.h)

typedef struct command_struct {
  const char *name;           /* Name of this command */
  const char *(*func) ();     /* Function invoked */
  void *cmd_data;             /* Extra data, for functions which
                               * implement multiple commands...*/
  int req_override;           /* What overrides need to be allowed to
                               * enable this command.*/
  enum cmd_how args_how;      /* What the command expects as arguments */
  const char *errmsg;         /* 'usage' message, in case of syntax errors */
} command_rec;

The various fields of the command_rec should look familiar to the Perl API covered in Chapter 8, Customizing the Apache Configuration Process:

char *name

This is the configuration directive's name, used within httpd.conf and the other configuration files. The name may not contain whitespace but is otherwise unrestricted in its contents. However, for consistency, you should stick to the Apache convention of making directives short phrases with the initial letter of each word capitalized. Apache processes directives in a case-insensitive manner.

While processing configuration files, Apache employs a general parsing algorithm. Whenever it hits what appears to be a configuration directive, it searches through the internal module list and peeks into each module's command table until it finds the definition it's looking for. At this point, the server parses the directive's arguments and passes the information to the module's designated configuration processing routine.

const char *(*func) ()

This is a pointer to a directive handler that Apache will call at runtime to process the directive. The prototype for the callback is determined by the args_how field described later in this section. Usually the callback simply sets a value in a module-specific data structure.

void *cmd_data

If the module needs to share common information among multiple directive handlers, the cmd_data field allows you to pass this information around as a void* block. If non- NULL, Apache will pass the contents of cmd_data to the directive handler at runtime in the cmd_parms argument. One use for this would be a situation in which a single directive handler is responsible for processing multiple directives. In order for the handler to determine which directive it's responsible for, the module can leave the address of a distinguishing flag in the cmd_data slot.

For an example of this technique, see how mod_autoindex implements the various AddIcon* and AddAlt* directives.

int override

This field indicates the scope of a directive. The scope is used by Apache to determine what parts of the various configuration files and .htaccess files the directive is allowed to appear in. override is a bit mask constructed from the bitwise OR of a set of constants which we list presently.

enum cmd_how args_how

This field tells the server how it should parse the directive's arguments. It is any of 12 constants that specify the number of mandatory and optional arguments the directive takes. We explain the possibilities later in this section.

char *errmsg

This field contains a short usage message that is displayed when the configuration parser encounters a syntax error in the directive. The usage message is also put to good use by mod_info to display modules' current configurations.

Constants for the override Field

Directives vary in their scope. Some affect low-level processes such as URI translation or the proxy mechanism and therefore belong outside of <Directory> and <Location> sections. Others control access to particular files and directories and only make sense when located within a <Directory> or <Location> section. In other cases, you might want the directive to be available to the webmaster but not allow it to appear in .htaccess files where it would be available to HTML authors.

The override field of the command_rec controls the scope. It is the bitwise combination of the following constants defined in http_config.h:

RSRC_CONF

The directive can only be present in the server .conf files, outside of <Directory>, <Location> , and <Files> containers. Not allowed in any .htaccess files or other files defined by the AccessFileName directive.

ACCESS_CONF

The directive can only be present in the server .conf files, inside <Directory>, <Location>, and <Files> sections. It is not allowed in .htaccess files.

OR_AUTHCFG

The directive has the same scope as ACCESS_CONF, but it is also allowed in .htaccess if AllowOverride AuthConfig is configured for the current directory.

OR_LIMIT

The directive has the same scope as ACCESS_CONF, but it is also allowed in .htaccess if AllowOverride Limit is configured for the current directory.

OR_OPTIONS

The directive is allowed anywhere in the .conf files, and it is also allowed in .htaccess if AllowOverride Options is configured for the current directory.

OR_FILEINFO

The directive is allowed anywhere in the .conf files, and it is also allowed in .htaccess if AllowOverride FileInfo is configured for the current directory.

OR_INDEXES

The directive is allowed anywhere in the .conf files, and it is also allowed in .htaccess if AllowOverride Indexes is configured for the current directory.

OR_ALL

The directive can be just about anywhere it wants to be.

OR_NONE

The directive cannot be overridden by any of the AllowOverride options.