Apache Module mod_example_hooks

Description:	Illustrates the Apache module API
Status:	Experimental
ModuleIdentifier:	example_hooks_module
SourceFile:	mod_example_hooks.c

Summary

The files in the modules/examples directory under the Apache distribution directory tree are provided as an example to those that wish to write modules that use the Apache API.

The main file is mod_example_hooks.c, which illustrates all the different callback mechanisms and call syntaxes. By no means does an add-on module need to include routines for all of the callbacks - quite the contrary!

The example module is an actual working module. If you link it into your server, enable the "example-hooks-handler" handler for a location, and then browse to that location, you will see a display of some of the tracing the example module did as the various callbacks were made.

Compiling the example_hooks module

To include the example_hooks module in your server, follow the steps below:

1. Run configure with --enable-example-hooks option.
2. Make the server (run "make").

To add another module of your own:

1. cp modules/examples/mod_example_hooks.c modules/new_module/mod_myexample.c
2. Modify the file.
3. Create modules/new_module/config.m4.
   1. Add APACHE_MODPATH_INIT(new_module).
   2. Copy APACHE_MODULE line with "example_hooks" from modules/examples/config.m4.
   3. Replace the first argument "example_hooks" with myexample.
   4. Replace the second argument with brief description of your module. It will be used in configure --help.
   5. If your module needs additional C compiler flags, linker flags or libraries, add them to CFLAGS, LDFLAGS and LIBS accordingly. See other config.m4 files in modules directory for examples.
   6. Add APACHE_MODPATH_FINISH.
4. Create module/new_module/Makefile.in. If your module doesn't need special build instructions, all you need to have in that file is include $(top_srcdir)/build/special.mk.
5. Run ./buildconf from the top-level directory.
6. Build the server with --enable-myexample

Using the mod_example_hooks Module

To activate the example_hooks module, include a block similar to the following in your httpd.conf file:

<Location "/example-hooks-info">
   SetHandler example-hooks-handler
</Location>

As an alternative, you can put the following into a .htaccess file and then request the file "test.example" from that location:

AddHandler example-hooks-handler ".example"

After reloading/restarting your server, you should be able to browse to this location and see the brief display mentioned earlier.