Porting to Apache 2.0 (Apache: The Definitive Guide, 3rd Edition)

21.6. Porting to Apache 2.0

In addition to the earlier discussion on how to write a module from scratch for Apache 2.0, which is broadly the same as for 1.x, we'll show how to port one.

First of all, it is probably easiest to compile the module using apxs (although we are not keen on this approach, it is definitely the easiest, sadly). You'll need to have configured Apache like this:

./configure --enable-so

Then compiling mod_reveal is easy:

apxs -c mod_reveal.c

This will, once its working, yield .libs/mod_reveal.so (use the -i option, and apxs will obligingly install it in /usr/local/apache2/lib). However, compiling the Apache 1.x version of mod_reveal produces a large number of errors (note that you might save yourself some agony by adding -Wc,-Wall and -Wc,-Werror to the command line). The first problem is that some headers have been split up and moved around. So, we had to add:

#include "http_request.h"

to get the definition for server_rec.

Also, many data structures and functions in Apache 1.3 had names that could cause conflict with other libraries. So, they have all been prefixed in an attempt to make them unique. The prefixes are ap_, apr_, and apu_ depending on whether they belong to Apache, APR, or APR-util. If they are data structures, they typically have also had _t appended. So, pool has become apr_pool_t. Many functions have also moved from ap_ to apr_; for example, ap_pstrcat( ) has become apr_pstrcat( ) and now needs the header apr_strings.h.

Functions that didn't take pool arguments now do. For example:

ap_add_version_component("Reveal/0.0");

becomes:

ap_add_version_component(pPool,"Reveal/0.0");

The command structure is now typesafe and uses special macros for each type of command, depending on the number of parameters it takes. For example:

static command_rec aCommands[]=
    {
{ "RevealTag", RevealTag, NULL, ACCESS_CONF|OR_ALL, TAKE1, "a tag for this section"},
{ "RevealServerTag", RevealServerTag, NULL, RSRC_CONF, TAKE1, "a tag for this server" },
{ NULL }
    };

becomes:

static command_rec aCommands[]=
    {
    AP_INIT_TAKE1("RevealTag", RevealTag, NULL, ACCESS_CONF|OR_ALL,
                  "a tag for this section"),
    AP_INIT_TAKE1("RevealServerTag", RevealServerTag, NULL, RSRC_CONF,
                  "a tag for this server" ),
    { NULL }
    };

As a consequence of the type-safety, some fast and loose trickery we played is no longer acceptable. For example:

static const char *RevealServerTag(cmd_parms *cmd, SPerDir *pPerDir,
                                   char *arg)
    {

becomes:

static const char *RevealServerTag(cmd_parms *cmd, void *_pPerDir,
                                   const char *arg)
    {
    SPerDir *pPerDir=_pPerDir;

Handlers have changed completely and are now done via hooks. So, instead of:

static int RevealHandler(request_rec *pReq)
    {
    SPerDir *pPerDir=ap_get_module_config(pReq->per_dir_config,
               &reveal_module);
    SPerServer *pPerServer=ap_get_module_config(pReq->server->
               module_config,&reveal_module);
.
.
.
static handler_rec aHandlers[]=
    {
    { "reveal", RevealHandler },
    { NULL },
    };

we now have:

static int RevealHandler(request_rec *pReq)
    {
    SPerDir *pPerDir;
    SPerServer *pPerServer;

    if(strcmp(pReq->handler,"reveal"))
        return DECLINED;

    pPerDir=ap_get_module_config(pReq->per_dir_config, &reveal_module);
    pPerServer=ap_get_module_config(pReq->server->module_config, &reveal_module);
.
.
.

and an ap_hook_handler( ) entry in the RegisterHooks( ) function mentioned later in this section.

Obviously, we haven't covered all the API changes. But Apache 2.0 API, unlike the 1.x API, is thoroughly documented, both in the headers and, using the doxygen documentation tool, on the Web (and, of course, in the distribution). The web-based documentation for APR and APR-util can be found here: http://apr.apache.org/. Documentation for everything that's documented can also be generated by typing:

make dox

at the top of the httpd-2.0 tree, though at the time of writing you do have to tweak docs/doxygen.conf slightly by hand. Sadly, there is no better way, at the moment, to figure out API changes than to dredge through these. The grep utility is extremely useful.

Once the API changes have been dealt with, the next problem is to switch to the new hooking scheme. In 1.3, we had this:

 module reveal_module = {
   STANDARD_MODULE_STUFF,
   RevealInit,                  /* initializer */
   RevealCreateDir,             /* dir config creater */
   RevealMergeDir,              /* dir merger --- default is to override */
   RevealCreateServer,          /* server config */
   RevealMergeServer,           /* merge server configs */
   aCommands,                   /* command table */
   aHandlers,                   /* handlers */
   RevealTranslate,             /* filename translation */
   RevealCheckUserID,           /* check_user_id */
   RevealCheckAuth,             /* check auth */
   RevealCheckAccess,           /* check access */
   RevealTypeChecker,           /* type_checker */
   RevealFixups,                /* fixups */
   RevealLogger,                /* logger */
   RevealHeaderParser,          /* header parser */
   RevealChildInit,             /* child init */
   RevealChildExit,             /* child exit */
   RevealPostReadRequest,       /* post read request */
};

In 2.0, this gets a lot shorter, as all the hooks are now initialized in a single function. All this is explained in more detail in the previous chapter, but here's what this becomes:

static void RegisterHooks(apr_pool_t *pPool)
    {
    ap_hook_post_config(RevealInit,NULL,NULL,APR_HOOK_MIDDLE);
    ap_hook_handler(RevealHandler,NULL,NULL,APR_HOOK_MIDDLE);
    ap_hook_translate_name(RevealTranslate,NULL,NULL,APR_HOOK_MIDDLE);
    ap_hook_check_user_id(RevealCheckUserID,NULL,NULL,APR_HOOK_MIDDLE);
    ap_hook_auth_checker(RevealCheckAuth,NULL,NULL,APR_HOOK_MIDDLE);
    ap_hook_access_checker(RevealCheckAccess,NULL,NULL,APR_HOOK_MIDDLE);
    ap_hook_type_checker(RevealTypeChecker,NULL,NULL,APR_HOOK_MIDDLE);
    ap_hook_fixups(RevealFixups,NULL,NULL,APR_HOOK_MIDDLE);
    ap_hook_log_transaction(RevealLogger,NULL,NULL,APR_HOOK_MIDDLE);
    ap_hook_header_parser(RevealHeaderParser,NULL,NULL,APR_HOOK_MIDDLE);
    ap_hook_child_init(RevealChildInit,NULL,NULL,APR_HOOK_MIDDLE);
    ap_hook_post_read_request(RevealPostReadRequest,NULL,NULL,APR_HOOK_MIDDLE);
    }

 module reveal_module = {
   STANDARD20_MODULE_STUFF,
   RevealCreateDir,             /* dir config creater */
   RevealMergeDir,              /* dir merger --- default is to override */
   RevealCreateServer,          /* server config */
   RevealMergeServer,           /* merge server configs */
   aCommands,                   /* command table */
   RegisterHooks                /* hook registration */
};

One minor glitch this revealed was that:

static void RevealChildInit(server_rec *pServer,apr_pool_t *pPool)

should now be:

static void RevealChildInit(apr_pool_t *pPool,server_rec *pServer)

And rather more frighteningly:

static void RevealInit(server_rec *pServer,apr_pool_t *pPool)

becomes:

static int RevealInit(apr_pool_t *pPool,apr_pool_t *pLog,apr_pool_t *pTemp,
      server_rec *pServer)

returning a value of OK, which is fine in our case. Also note that we no longer have a child_exit hook — that can be done with a pool-cleanup function.

For this module at least, that's it! All that has to be done now is to load it with an appropriate AddModule:

LoadModule reveal_module .../mod_reveal.so

and it behaves just like the Apache 1.3 version.