1 <?xml version="1.0" encoding="UTF-8" ?>
2 <!DOCTYPE manualpage SYSTEM "./style/manualpage.dtd">
3 <?xml-stylesheet type="text/xsl" href="./style/manual.en.xsl"?>
5 <manualpage metafile="handler.xml.meta">
7 <title>Apache's Handler Use</title>
10 <p>This document describes the use of Apache's Handlers.</p>
13 <section id="definition">
14 <title>What is a Handler</title>
17 <module>mod_actions</module>
18 <module>mod_asis</module>
19 <module>mod_cgi</module>
20 <module>mod_imap</module>
21 <module>mod_info</module>
22 <module>mod_mime</module>
23 <module>mod_negotiation</module>
24 <module>mod_status</module>
27 <directive module="mod_actions">Action</directive>
28 <directive module="mod_mime">AddHandler</directive>
29 <directive module="mod_mime">RemoveHandler</directive>
30 <directive module="core">SetHandler</directive>
35 <p>A "handler" is an internal Apache representation of the
36 action to be performed when a file is called. Generally, files
37 have implicit handlers, based on the file type. Normally, all
38 files are simply served by the server, but certain file types
39 are "handled" separately.</p>
41 <p>Apache 1.1 adds the ability to use handlers explicitly.
42 Based on either filename extensions or on location, handlers
43 can be specified without relation to file type. This is
44 advantageous both because it is a more elegant solution, and
45 because it also allows for both a type <strong>and</strong> a
46 handler to be associated with a file. (See also <a
47 href="mod/mod_mime.html#multipleext">Files with Multiple
50 <p>Handlers can either be built into the server or included in
51 a module, or they can be added with the <directive
52 module="mod_actions">Action</directive> directive. The
53 built-in handlers in the standard distribution are as
57 <li><strong>default-handler</strong>: Send the file using the
58 <code>default_handler()</code>, which is the handler used by
59 default to handle static content. (core)</li>
61 <li><strong>send-as-is</strong>: Send file with HTTP headers
62 as is. (<module>mod_asis</module>)</li>
64 <li><strong>cgi-script</strong>: Treat the file as a CGI
65 script. (<module>mod_cgi</module>)</li>
67 <li><strong>imap-file</strong>: Parse as an imagemap rule
68 file. (<module>mod_imap</module>)</li>
70 <li><strong>server-info</strong>: Get the server's
71 configuration information. (<module>mod_info</module>)</li>
73 <li><strong>server-status</strong>: Get the server's status
74 report. (<module>mod_status</module>)</li>
76 <li><strong>type-map</strong>: Parse as a type map file for
77 content negotiation. (<module>mod_negotiation</module>)</li>
80 <section id="examples">
81 <title>Examples</title>
83 <section id="example1">
84 <title>Modifying static content using a CGI script</title>
86 <p>The following directives will cause requests for files with
87 the <code>html</code> extension to trigger the launch of the
88 <code>footer.pl</code> CGI script.</p>
91 Action add-footer /cgi-bin/footer.pl<br/>
92 AddHandler add-footer .html
95 <p>Then the CGI script is responsible for sending the
96 originally requested document (pointed to by the
97 <code>PATH_TRANSLATED</code> environment variable) and making
98 whatever modifications or additions are desired.</p>
101 <section id="example2">
102 <title>Files with HTTP headers</title>
104 <p>The following directives will enable the
105 <code>send-as-is</code> handler, which is used for files which
106 contain their own HTTP headers. All files in the
107 <code>/web/htdocs/asis/</code> directory will be processed by
108 the <code>send-as-is</code> handler, regardless of their
109 filename extensions.</p>
112 <Directory /web/htdocs/asis><br/>
113 SetHandler send-as-is<br/>
119 <section id="programmer">
120 <title>Programmer's Note</title>
122 <p>In order to implement the handler features, an addition has
123 been made to the <a href="developer/API.html">Apache API</a> that
124 you may wish to make use of. Specifically, a new record has
125 been added to the <code>request_rec</code> structure:</p>
131 <p>If you wish to have your module engage a handler, you need
132 only to set <code>r->handler</code> to the name of the
133 handler at any time prior to the <code>invoke_handler</code>
134 stage of the request. Handlers are implemented as they were
135 before, albeit using the handler name instead of a content
136 type. While it is not necessary, the naming convention for
137 handlers is to use a dash-separated word, with no slashes, so
138 as to not invade the media type name-space.</p>