home *** CD-ROM | disk | FTP | other *** search
/ Chip 2004 November / CMCD1104.ISO / Software / Complet / Apache / apache_2.0.52-win32-x86-no_ssl.msi / Data.Cab / F278293_mod_example.xml < prev    next >
Extensible Markup Language  |  2004-04-17  |  5KB  |  139 lines
  1. <?xml version="1.0"?>
  2. <!DOCTYPE modulesynopsis SYSTEM "../style/modulesynopsis.dtd">
  3. <?xml-stylesheet type="text/xsl" href="../style/manual.en.xsl"?>
  4. <!-- $Revision: 1.2.2.5 $ -->
  5.  
  6. <!--
  7.  Copyright 2002-2004 The Apache Software Foundation
  8.  
  9.  Licensed under the Apache License, Version 2.0 (the "License");
  10.  you may not use this file except in compliance with the License.
  11.  You may obtain a copy of the License at
  12.  
  13.      http://www.apache.org/licenses/LICENSE-2.0
  14.  
  15.  Unless required by applicable law or agreed to in writing, software
  16.  distributed under the License is distributed on an "AS IS" BASIS,
  17.  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  18.  See the License for the specific language governing permissions and
  19.  limitations under the License.
  20. -->
  21.  
  22. <modulesynopsis metafile="mod_example.xml.meta">
  23.  
  24. <name>mod_example</name>
  25. <description>Illustrates the Apache module API</description>
  26. <status>Experimental</status>
  27. <sourcefile>mod_example.c</sourcefile>
  28. <identifier>example_module</identifier>
  29.  
  30. <summary>
  31. <note type="warning">
  32.       This document has not been updated
  33.       to take into account changes made in the 2.0 version of the
  34.       Apache HTTP Server. Some of the information may still be
  35.       relevant, but please use it with care.
  36. </note>
  37.  
  38.     <p>The files in the <code>src/modules/example directory</code>
  39.     under the Apache distribution directory tree are provided as an
  40.     example to those that wish to write modules that use the Apache
  41.     API.</p>
  42.  
  43.     <p>The main file is <code>mod_example.c</code>, which
  44.     illustrates all the different callback mechanisms and call
  45.     syntaxes. By no means does an add-on module need to include
  46.     routines for all of the callbacks - quite the contrary!</p>
  47.  
  48.     <p>The example module is an actual working module. If you link
  49.     it into your server, enable the "example-handler" handler for a
  50.     location, and then browse to that location, you will see a
  51.     display of some of the tracing the example module did as the
  52.     various callbacks were made.</p>
  53. </summary>
  54.  
  55. <section id="compiling"><title>Compiling the example module</title>
  56.  
  57.     <p>To include the example module in your server, follow the
  58.     steps below:</p>
  59.  
  60.     <ol>
  61.       <li>
  62.         Uncomment the "AddModule modules/example/mod_example" line
  63.         near the bottom of the <code>src/Configuration</code> file.
  64.         If there isn't one, add it; it should look like this: 
  65. <example>
  66.      AddModule modules/example/mod_example.o
  67. </example>
  68.       </li>
  69.  
  70.       <li>Run the <code>src/Configure</code> script
  71.       ("<code>cd src; ./Configure</code>"). This will
  72.       build the Makefile for the server itself, and update the
  73.       <code>src/modules/Makefile</code> for any additional modules
  74.       you have requested from beneath that subdirectory.</li>
  75.  
  76.       <li>Make the server (run "<code>make</code>" in the
  77.       <code>src</code> directory).</li>
  78.     </ol>
  79.  
  80.     <p>To add another module of your own:</p>
  81.  
  82.     <ol type="A">
  83.       <li><code>mkdir src/modules/<em>mymodule</em></code></li>
  84.  
  85.       <li><code>cp src/modules/example/*
  86.       src/modules/<em>mymodule</em></code></li>
  87.  
  88.       <li>Modify the files in the new directory.</li>
  89.  
  90.       <li>Follow steps [1] through [3] above, with appropriate
  91.       changes.</li>
  92.     </ol>
  93. </section>
  94.  
  95. <section id="using"><title>Using the <code>mod_example</code> Module</title>
  96.  
  97.     <p>To activate the example module, include a block similar to
  98.     the following in your <code>srm.conf</code> file:</p>
  99. <example>
  100.    <Location /example-info><br />
  101.        SetHandler example-handler<br />
  102.    </Location>
  103. </example>
  104.  
  105.     <p>As an alternative, you can put the following into a <a
  106.     href="core.html#accessfilename"><code>.htaccess</code></a> file
  107.     and then request the file "test.example" from that location:</p>
  108. <example>
  109.    AddHandler example-handler .example
  110. </example>
  111.  
  112.     <p>After reloading/restarting your server, you should be able
  113.     to browse to this location and see the brief display mentioned
  114.     earlier.</p>
  115. </section>
  116.  
  117. <directivesynopsis>
  118. <name>Example</name>
  119. <description>Demonstration directive to illustrate the Apache module
  120. API</description>
  121. <syntax>Example</syntax>
  122. <contextlist><context>server config</context>
  123. <context>virtual host</context><context>directory</context>
  124. <context>.htaccess</context></contextlist>
  125.  
  126. <usage>
  127.     <p>The <directive>Example</directive> directive just sets a demonstration
  128.     flag which the example module's content handler displays. It
  129.     takes no arguments. If you browse to an URL to which the
  130.     example content-handler applies, you will get a display of the
  131.     routines within the module and how and in what order they were
  132.     called to service the document request. The effect of this
  133.     directive one can observe under the point "<code>Example
  134.     directive declared here: YES/NO</code>".</p>
  135. </usage>
  136. </directivesynopsis>
  137.  
  138. </modulesynopsis>
  139.