| <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN"> |
| <HTML> |
| <HEAD> |
| <TITLE>Apache module mod_example</TITLE> |
| </HEAD> |
| <!-- Background white, links blue (unvisited), navy (visited), red (active) --> |
| <BODY |
| BGCOLOR="#FFFFFF" |
| TEXT="#000000" |
| LINK="#0000FF" |
| VLINK="#000080" |
| ALINK="#FF0000" |
| > |
| <!--#include virtual="header.html" --> |
| <H1 ALIGN="CENTER">Module mod_example</H1> |
| <P> |
| This module is contained in the <CODE>modules/mod_example.c</CODE> file, and |
| <STRONG>is not</STRONG> compiled in by default. It illustrates many of |
| the aspects of the |
| <A |
| HREF="../misc/API.html" |
| REL="Help" |
| >Apache 1.2 API</A> |
| and, when used, demonstrates the manner in which module callbacks are |
| triggered by the server. |
| </P> |
| <H2>Summary</H2> |
| <P> |
| The files in the <CODE>src/modules/example directory</CODE> under the |
| Apache distribution directory tree are provided as an example to those |
| that wish to write modules that use the Apache API. |
| </P> |
| <P> |
| The main file is <CODE>mod_example.c</CODE>, 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! |
| </P> |
| <P> |
| The example module is an actual working module. If you link it into |
| your server, enable the "example-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. |
| </P> |
| <P> |
| To include the example module in your server, follow the steps below: |
| </P> |
| <OL> |
| <LI>Uncomment the "AddModule modules/example/mod_example" line near |
| the bottom of |
| the <CODE>src/Configuration</CODE> file. If there isn't one, add |
| it; it should look like this: |
| <PRE> |
| AddModule modules/example/mod_example.o |
| </PRE> |
| </LI> |
| <LI>Run the <CODE>src/Configure</CODE> script |
| ("<SAMP>cd src; ./Configure</SAMP>"). This will |
| build the Makefile for the server itself, and update the |
| <CODE>src/modules/Makefile</CODE> for any additional modules you |
| have requested from beneath that subdirectory. |
| </LI> |
| <LI>Make the server (run "<SAMP>make</SAMP>" in the <CODE>src</CODE> |
| directory). |
| </LI> |
| </OL> |
| <P> |
| To add another module of your own: |
| </P> |
| <OL TYPE="A"> |
| <LI><SAMP>mkdir src/modules/<EM>mymodule</EM></SAMP> |
| </LI> |
| <LI><SAMP>cp src/modules/example/* src/modules/<EM>mymodule</EM></SAMP> |
| </LI> |
| <LI>Modify the files in the new directory. |
| </LI> |
| <LI>Follow steps [1] through [3] above, with appropriate changes. |
| </LI> |
| </OL> |
| <H3> |
| Using the <SAMP>mod_example</SAMP> Module |
| </H3> |
| <P> |
| To activate the example module, include a block similar to the |
| following in your <SAMP>srm.conf</SAMP> file: |
| </P> |
| <PRE> |
| <Location /example-info> |
| SetHandler example-handler |
| </Location> |
| </PRE> |
| <P> |
| As an alternative, you can put the following into a |
| <A |
| HREF="core.html#accessfilename" |
| ><SAMP>.htaccess</SAMP></A> |
| file and then request the file "test.example" from that |
| location: |
| </P> |
| <PRE> |
| AddHandler example-handler .example |
| </PRE> |
| <P> |
| After reloading/restarting your server, you should be able to browse |
| to this location and see the brief display mentioned earlier. |
| </P> |
| <H2>Directives</H2> |
| <P> |
| <UL> |
| <LI><A HREF="#example">Example</A> |
| </LI> |
| </UL> |
| </P> |
| <HR> |
| <H2><A NAME="example"> |
| Example |
| </A></H2> |
| <P> |
| <A |
| HREF="directive-dict.html#Syntax" |
| REL="Help" |
| ><STRONG>Syntax:</STRONG></A> Example |
| <BR> |
| <A |
| HREF="directive-dict.html#Default" |
| REL="Help" |
| ><STRONG>Default:</STRONG></A> None |
| <BR> |
| <A |
| HREF="directive-dict.html#Context" |
| REL="Help" |
| ><STRONG>Context:</STRONG></A> server config, virtual host, directory, |
| .htaccess |
| <BR> |
| <A |
| HREF="directive-dict.html#Override" |
| REL="Help" |
| ><STRONG>Override:</STRONG></A> Options |
| <BR> |
| <A |
| HREF="directive-dict.html#Status" |
| REL="Help" |
| ><STRONG>Status:</STRONG></A> Extension |
| <BR> |
| <A |
| HREF="directive-dict.html#Module" |
| REL="Help" |
| ><STRONG>Module:</STRONG></A> mod_example |
| <BR> |
| <A |
| HREF="directive-dict.html#Compatibility" |
| REL="Help" |
| ><STRONG>Compatibility:</STRONG></A> <SAMP>Example</SAMP> is only |
| available in Apache 1.2 and later. |
| </P> |
| <P> |
| The <SAMP>Example</SAMP> directive just sets a demonstration flag which the |
| example module's content handler displays. It takes no arguments. If you |
| browse to an URL to which the example content-handler applies, you will get |
| a display of the routines within the module and how and in what order they |
| were called to service the document request. The effect of this directive |
| one can observe under the point "<SAMP>Example directive declared |
| here: YES/NO</SAMP>". |
| </P> |
| <!--#include virtual="footer.html" --> |
| </BODY> |
| </HTML> |
