handler.html revision c8f9b27f3551ad0a3520a0f6246940bf7255828d
5e0ce63bb65db34d7f48b34bbb5545fa791781c4Timo Sirainen<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN">
def516ea503a60f20d510c14d5070b7ff5bbddf4Timo Sirainen<!-- Background white, links blue (unvisited), navy (visited), red (active) -->
b561170c84d19ef1dee3d528939d77fd38047b3fTimo Sirainen BGCOLOR="#FFFFFF"
bad5981f287ff1e4094428e27178062548215a93Timo Sirainen TEXT="#000000"
b561170c84d19ef1dee3d528939d77fd38047b3fTimo Sirainen LINK="#0000FF"
9edba36ef9b2679b0585c345074b1f1d482bfd20Timo Sirainen VLINK="#000080"
b561170c84d19ef1dee3d528939d77fd38047b3fTimo Sirainen ALINK="#FF0000"
4b058f90f9e8a2c6b2eed275de4eb8cc5195a71dTimo Sirainen<!--#include virtual="header.html" -->
def516ea503a60f20d510c14d5070b7ff5bbddf4Timo Sirainen<li><a href="#definition">What is a Handler</a></li>
def516ea503a60f20d510c14d5070b7ff5bbddf4Timo Sirainen<li><a href="#programmer">Programmer's Note</a></li>
9edba36ef9b2679b0585c345074b1f1d482bfd20Timo Sirainen<H2><a name="definition">What is a Handler</a></H2>
fc7b32b6a2a65d604c8070b9b1a204f25c90b391Timo Sirainen<a href="mod/mod_actions.html">mod_actions</a><br>
def516ea503a60f20d510c14d5070b7ff5bbddf4Timo Sirainen<A HREF="mod/mod_include.html">mod_include</A><br>
def516ea503a60f20d510c14d5070b7ff5bbddf4Timo Sirainen<A HREF="mod/mod_negotiation.html">mod_negotiation</A><br>
4b058f90f9e8a2c6b2eed275de4eb8cc5195a71dTimo Sirainen<A HREF="mod/mod_status.html">mod_status</A><br>
4b058f90f9e8a2c6b2eed275de4eb8cc5195a71dTimo Sirainen<a href="mod/mod_actions.html#action">Action</a><br>
4b058f90f9e8a2c6b2eed275de4eb8cc5195a71dTimo Sirainen<A HREF="mod/mod_mime.html#addhandler">AddHandler</A><br>
4b058f90f9e8a2c6b2eed275de4eb8cc5195a71dTimo Sirainen<a href="mod/mod_mime.html#removehandler">RemoveHandler</a><br>
9edba36ef9b2679b0585c345074b1f1d482bfd20Timo Sirainen<A HREF="mod/mod_mime.html#sethandler">SetHandler</A><br>
b3286cc6a70ab6b4c53301aa075b16898b80c880Timo Sirainen<P>A "handler" is an internal Apache representation of the action to be
b3286cc6a70ab6b4c53301aa075b16898b80c880Timo Sirainenperformed when a file is called. Generally, files have implicit
b3286cc6a70ab6b4c53301aa075b16898b80c880Timo Sirainenhandlers, based on the file type. Normally, all files are simply
4b058f90f9e8a2c6b2eed275de4eb8cc5195a71dTimo Sirainenserved by the server, but certain file types are "handled"
156a7c9057782ea8d805c4223082e1dd6041ef21Timo Sirainenseparately.</P>
def516ea503a60f20d510c14d5070b7ff5bbddf4Timo Sirainen<P>Apache 1.1 adds the ability to use handlers explicitly. Based on
def516ea503a60f20d510c14d5070b7ff5bbddf4Timo Siraineneither filename extensions or on location, handlers can be specified
def516ea503a60f20d510c14d5070b7ff5bbddf4Timo Sirainenwithout relation to file type. This is advantageous both because it is
def516ea503a60f20d510c14d5070b7ff5bbddf4Timo Sirainena more elegant solution, and because it also allows for both a type
def516ea503a60f20d510c14d5070b7ff5bbddf4Timo Sirainen<STRONG>and</STRONG> a handler to be associated with a file. (See also
def516ea503a60f20d510c14d5070b7ff5bbddf4Timo Sirainen<A HREF="mod/mod_mime.html#multipleext">Files with Multiple
b561170c84d19ef1dee3d528939d77fd38047b3fTimo Sirainen<P>Handlers can either be built into the server, included in a module,
def516ea503a60f20d510c14d5070b7ff5bbddf4Timo Sirainenor they can be added with the <A
def516ea503a60f20d510c14d5070b7ff5bbddf4Timo SirainenHREF="mod/mod_actions.html#action">Action</A> directive. The built-in
b561170c84d19ef1dee3d528939d77fd38047b3fTimo Sirainenhandlers in the standard distribution are as follows:</P>
def516ea503a60f20d510c14d5070b7ff5bbddf4Timo Sirainen Send the file using the <CODE>default_handler()</CODE>, which is the
b561170c84d19ef1dee3d528939d77fd38047b3fTimo Sirainen handler used by default to handle static content.
def516ea503a60f20d510c14d5070b7ff5bbddf4Timo Sirainen Send file with HTTP headers as is.
b561170c84d19ef1dee3d528939d77fd38047b3fTimo Sirainen Treat the file as a CGI script.
c0435c854a0e7246373b9752d163095cc4fbe985Timo Sirainen Parse as an imagemap rule file.
def516ea503a60f20d510c14d5070b7ff5bbddf4Timo Sirainen Get the server's configuration information.
4b058f90f9e8a2c6b2eed275de4eb8cc5195a71dTimo Sirainen Parse for server-side includes.
def516ea503a60f20d510c14d5070b7ff5bbddf4Timo Sirainen (<A HREF="mod/mod_include.html">mod_include</A>)
def516ea503a60f20d510c14d5070b7ff5bbddf4Timo Sirainen Get the server's status report.
def516ea503a60f20d510c14d5070b7ff5bbddf4Timo Sirainen (<A HREF="mod/mod_status.html">mod_status</A>)
def516ea503a60f20d510c14d5070b7ff5bbddf4Timo Sirainen Parse as a type map file for content negotiation.
b561170c84d19ef1dee3d528939d77fd38047b3fTimo Sirainen (<A HREF="mod/mod_negotiation.html">mod_negotiation</A>)
def516ea503a60f20d510c14d5070b7ff5bbddf4Timo Sirainen<h3>Modifying static content using a CGI script</h3>
b561170c84d19ef1dee3d528939d77fd38047b3fTimo Sirainen<p>The following directives will cause requests for files with the
def516ea503a60f20d510c14d5070b7ff5bbddf4Timo Sirainen<code>html</code> extension to trigger the launch of the
def516ea503a60f20d510c14d5070b7ff5bbddf4Timo Sirainen AddHandler add-footer html
b561170c84d19ef1dee3d528939d77fd38047b3fTimo Sirainen<p>Then the CGI script is responsible for sending the originally
def516ea503a60f20d510c14d5070b7ff5bbddf4Timo Sirainenrequested document (pointed to by the <code>PATH_TRANSLATED</code>
b561170c84d19ef1dee3d528939d77fd38047b3fTimo Sirainenenvironment variable) and making whatever modifications or additions
def516ea503a60f20d510c14d5070b7ff5bbddf4Timo Sirainenare desired.</p>
def516ea503a60f20d510c14d5070b7ff5bbddf4Timo Sirainen<p>The following directives will enable the <code>send-as-is</code>
def516ea503a60f20d510c14d5070b7ff5bbddf4Timo Sirainenhandler, which is used for files which contain their own HTTP headers.
def516ea503a60f20d510c14d5070b7ff5bbddf4Timo SirainenAll files in the <code>/web/htdocs/asis/</code> directory will be
40f114f2e12605483b21e7cf048b7c9bd9568148Timo Sirainenprocessed by the <code>send-as-is</code> handler, regardless of their
40f114f2e12605483b21e7cf048b7c9bd9568148Timo Sirainenfilename extensions.</p>
40f114f2e12605483b21e7cf048b7c9bd9568148Timo Sirainen SetHandler send-as-is
40f114f2e12605483b21e7cf048b7c9bd9568148Timo Sirainen </Directory>
def516ea503a60f20d510c14d5070b7ff5bbddf4Timo Sirainen<H2><a name="programmer">Programmer's Note</a></H2>
b561170c84d19ef1dee3d528939d77fd38047b3fTimo Sirainen<P>In order to implement the handler features, an addition has been
4b058f90f9e8a2c6b2eed275de4eb8cc5195a71dTimo Sirainenmade to the <A HREF="misc/API.html">Apache API</A> that you may wish to
def516ea503a60f20d510c14d5070b7ff5bbddf4Timo Sirainenmake use of. Specifically, a new record has been added to the
4b058f90f9e8a2c6b2eed275de4eb8cc5195a71dTimo Sirainen char *handler
4b058f90f9e8a2c6b2eed275de4eb8cc5195a71dTimo Sirainen<P>If you wish to have your module engage a handler, you need only to
def516ea503a60f20d510c14d5070b7ff5bbddf4Timo Sirainenset <CODE>r->handler</CODE> to the name of the handler at any time
def516ea503a60f20d510c14d5070b7ff5bbddf4Timo Sirainenprior to the <CODE>invoke_handler</CODE> stage of the
4b058f90f9e8a2c6b2eed275de4eb8cc5195a71dTimo Sirainenrequest. Handlers are implemented as they were before, albeit using
2ca64e9cb20ca517a5a0d4ba3b73dccb2a0dd973Timo Sirainenthe handler name instead of a content type. While it is not
4b058f90f9e8a2c6b2eed275de4eb8cc5195a71dTimo Sirainennecessary, the naming convention for handlers is to use a
2ca64e9cb20ca517a5a0d4ba3b73dccb2a0dd973Timo Sirainendash-separated word, with no slashes, so as to not invade the media
2ca64e9cb20ca517a5a0d4ba3b73dccb2a0dd973Timo Sirainentype name-space.</P>
4b058f90f9e8a2c6b2eed275de4eb8cc5195a71dTimo Sirainen<!--#include virtual="footer.html" -->