mod_example.html revision 57a38b7eede40bb757254e46f58900c6b87dd3df
2N/A<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN">
2N/A<HTML>
2N/A <HEAD>
2N/A <TITLE>Apache module mod_example</TITLE>
2N/A </HEAD>
2N/A <!-- Background white, links blue (unvisited), navy (visited), red (active) -->
2N/A <BODY
2N/A BGCOLOR="#FFFFFF"
2N/A TEXT="#000000"
2N/A LINK="#0000FF"
2N/A VLINK="#000080"
2N/A ALINK="#FF0000"
2N/A >
2N/A <!--#include virtual="header.html" -->
2N/A <H1 ALIGN="CENTER">Module mod_example</h1>
2N/A <P>
2N/A This module is contained in the <CODE>modules/mod_example.c</CODE> file, and
2N/A <STRONG>is not</STRONG> compiled in by default. It illustrates many of
2N/A the aspects of the
2N/A <A
2N/A HREF="/misc/API.html"
2N/A REL="Help"
2N/A >Apache 1.2 API</A>
2N/A and, when used, demonstrates the manner in which module callbacks are
2N/A triggered by the server.
2N/A </P>
2N/A <H2>Summary</H2>
2N/A <P>
2N/A The files in the <CODE>src/modules/example directory</CODE> under the
2N/A Apache distribution directory tree are provided as an example to those
2N/A that wish to write modules that use the Apache API.
2N/A </P>
2N/A <P>
2N/A The main file is <CODE>mod_example.c</CODE>, which illustrates all
2N/A the different callback mechanisms and call syntaxes. By no means does
2N/A an add-on module need to include routines for all of the callbacks -
2N/A 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&nbsp;src;&nbsp;/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>
&lt;Location /example-info&gt;
SetHandler example-handler
&lt;/Location&gt;
</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 &quot;test.example&quot; 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 activates the example module's
content handler
for a particular location or file type. 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.
</P>
<!--#include virtual="footer.html" -->
</BODY>
</HTML>