manual/mod/mod_example.html

	mod_example.html revision eb3e63593a2f2ec26386769e782ce9e77536a779
2426N/A<!DOCTYPE HTML PUBLIC "-//IETF//DTD HTML 2.0//EN">
2426N/A<HTML>
2426N/A <HEAD>
2426N/A  <TITLE>Apache module mod_example</TITLE>
2426N/A </HEAD>
2426N/A <BODY>
2426N/A  <!--#include virtual="header.html" -->
2426N/A  <H1>Module mod_example</h1>
2426N/A  <P>
2426N/A  This module is contained in the <CODE>modules/mod_example.c</CODE> file, and
2426N/A  <STRONG>is not</STRONG> compiled in by default.  It illustrates many of
2426N/A  the aspects of the
2426N/A  <A
2426N/A   HREF="/misc/API.html"
2426N/A   REL="Help"
2426N/A  >Apache 1.2 API</A>
2426N/A  and, when used, demonstrates the manner in which module callbacks are
2426N/A  triggered by the server.
2426N/A  </P>
2426N/A  <H2>Summary</H2>
2426N/A  <P>
2426N/A  The files in the <CODE>src/modules/example directory</CODE> under the
2426N/A  Apache distribution directory tree are provided as an example to those
2426N/A  that wish to write modules that use the Apache API.
2426N/A  </P>
2426N/A  <P>
2426N/A  The main file is <CODE>mod_example.c</CODE>, which illustrates all
2426N/A  the different callback mechanisms and call syntaces.  By no means does
2426N/A  an add-on module need to include routines for all of the callbacks -
2426N/A  quite the contrary!
2426N/A  </P>
2426N/A  <P>
2426N/A  The example module is an actual working module.  If you link it into
2426N/A  your server, enable the "example-handler" handler for a location, and
2426N/A  then browse to that location, you will see a display of
2426N/A  some of the tracing the example module did as the various callbacks
2426N/A  were made.
2426N/A  </P>
2426N/A  <P>
2426N/A  To include the example module in your server, follow the steps below:
2426N/A  </P>
2426N/A  <OL>
2426N/A   <LI>Uncomment the "Module example_module" line near the bottom of
2426N/A    the <CODE>src/Configuration</CODE> file.  If there isn't one, add
2426N/A    it; it should look like this:
2426N/A    <PRE>
2426N/A     Module example_module        modules/example/mod_example.o
2426N/A    </PRE>
2426N/A   </LI>
2426N/A   <LI>Run the <CODE>src/Configure</CODE> script
2426N/A    ("<SAMP>cd&nbsp;src;&nbsp;/Configure</SAMP>").  This will
2426N/A    build the Makefile for the server itself, and update the
2426N/A    <CODE>src/modules/Makefile</CODE> for any additional modules you
2426N/A    have requested from beneath that subdirectory.
2426N/A   </LI>
2426N/A   <LI>Make the server (run "<SAMP>make</SAMP>" in the <CODE>src</CODE>
2426N/A    directory).
2426N/A   </LI>
2426N/A  </OL>
2426N/A  <P>
2426N/A  To add another module of your own:
2426N/A  </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>
  <A NAME="example">
   <H2>Example</H2>
  </A>
  <P>
  <STRONG>Syntax:</STRONG> Example
  <BR>
  <STRONG>Default:</STRONG> None
  <BR>
  <STRONG>Context:</STRONG> server config, virtual host, directory, .htaccess
  <BR>
  <STRONG>Override:</STRONG> Options
  <BR>
  <STRONG>Status:</STRONG> Extension
  <BR>
  <STRONG>Module:</STRONG> mod_example
  </P>
  <P>
  The Example 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>