handler.html.en revision d24a0de52f0ae769a6c0ae18177a05a378314e19
13b501825bce68e7e49b4bc775da93e38d9bd9f3fuankg<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN">
13b501825bce68e7e49b4bc775da93e38d9bd9f3fuankg<HTML>
13b501825bce68e7e49b4bc775da93e38d9bd9f3fuankg<HEAD>
13b501825bce68e7e49b4bc775da93e38d9bd9f3fuankg<TITLE>Apache's Handler Use</TITLE>
13b501825bce68e7e49b4bc775da93e38d9bd9f3fuankg</HEAD>
13b501825bce68e7e49b4bc775da93e38d9bd9f3fuankg
13b501825bce68e7e49b4bc775da93e38d9bd9f3fuankg<!-- Background white, links blue (unvisited), navy (visited), red (active) -->
13b501825bce68e7e49b4bc775da93e38d9bd9f3fuankg<BODY
13b501825bce68e7e49b4bc775da93e38d9bd9f3fuankg BGCOLOR="#FFFFFF"
13b501825bce68e7e49b4bc775da93e38d9bd9f3fuankg TEXT="#000000"
0662ed52e814f8f08ef0e09956413a792584eddffuankg LINK="#0000FF"
13b501825bce68e7e49b4bc775da93e38d9bd9f3fuankg VLINK="#000080"
13b501825bce68e7e49b4bc775da93e38d9bd9f3fuankg ALINK="#FF0000"
13b501825bce68e7e49b4bc775da93e38d9bd9f3fuankg>
13b501825bce68e7e49b4bc775da93e38d9bd9f3fuankg<!--#include virtual="header.html" -->
13b501825bce68e7e49b4bc775da93e38d9bd9f3fuankg<H1 ALIGN="CENTER">Apache's Handler Use</H1>
13b501825bce68e7e49b4bc775da93e38d9bd9f3fuankg
13b501825bce68e7e49b4bc775da93e38d9bd9f3fuankg<H2>What is a Handler</H2>
16b55a35cff91315d261d1baa776138af465c4e4fuankg
16b55a35cff91315d261d1baa776138af465c4e4fuankg<P>A "handler" is an internal Apache representation of the action to be
13b501825bce68e7e49b4bc775da93e38d9bd9f3fuankgperformed when a file is called. Generally, files have implicit
13b501825bce68e7e49b4bc775da93e38d9bd9f3fuankghandlers, based on the file type. Normally, all files are simply
13b501825bce68e7e49b4bc775da93e38d9bd9f3fuankgserved by the server, but certain file typed are "handled"
13b501825bce68e7e49b4bc775da93e38d9bd9f3fuankgseparately. For example, you may use a type of
16b55a35cff91315d261d1baa776138af465c4e4fuankg"application/x-httpd-cgi" to invoke CGI scripts.</P>
13b501825bce68e7e49b4bc775da93e38d9bd9f3fuankg
16b55a35cff91315d261d1baa776138af465c4e4fuankg<P>Apache 1.1 adds the additional ability to use handlers
13b501825bce68e7e49b4bc775da93e38d9bd9f3fuankgexplicitly. Either based on filename extensions or on location, these
13b501825bce68e7e49b4bc775da93e38d9bd9f3fuankghandlers are unrelated to file type. This is advantageous both because
13b501825bce68e7e49b4bc775da93e38d9bd9f3fuankgit is a more elegant solution, but it also allows for both a type
13b501825bce68e7e49b4bc775da93e38d9bd9f3fuankg<STRONG>and</STRONG> a handler to be associated with a file.</P>
13b501825bce68e7e49b4bc775da93e38d9bd9f3fuankg
13b501825bce68e7e49b4bc775da93e38d9bd9f3fuankg<P>Handlers can either be built into the server or to a module, or
13b501825bce68e7e49b4bc775da93e38d9bd9f3fuankgthey can be added with the <A
13b501825bce68e7e49b4bc775da93e38d9bd9f3fuankgHREF="mod/mod_actions.html#action">Action</A> directive. The built-in
13b501825bce68e7e49b4bc775da93e38d9bd9f3fuankghandlers in the standard distribution are as follows:</P>
13b501825bce68e7e49b4bc775da93e38d9bd9f3fuankg
13b501825bce68e7e49b4bc775da93e38d9bd9f3fuankg<UL>
13b501825bce68e7e49b4bc775da93e38d9bd9f3fuankg<LI><STRONG>send-as-is</STRONG>:
13b501825bce68e7e49b4bc775da93e38d9bd9f3fuankg Send file with HTTP headers as is.
13b501825bce68e7e49b4bc775da93e38d9bd9f3fuankg (<A HREF="mod/mod_asis.html">mod_asis</A>)
13b501825bce68e7e49b4bc775da93e38d9bd9f3fuankg<LI><STRONG>cgi-script</STRONG>:
13b501825bce68e7e49b4bc775da93e38d9bd9f3fuankg Treat the file as a CGI script.
13b501825bce68e7e49b4bc775da93e38d9bd9f3fuankg (<A HREF="mod/mod_cgi.html">mod_cgi</A>)
13b501825bce68e7e49b4bc775da93e38d9bd9f3fuankg<LI><STRONG>imap-file</STRONG>:
13b501825bce68e7e49b4bc775da93e38d9bd9f3fuankg Imagemap rule file.
13b501825bce68e7e49b4bc775da93e38d9bd9f3fuankg (<A HREF="mod/mod_imap.html">mod_imap</A>)
13b501825bce68e7e49b4bc775da93e38d9bd9f3fuankg<LI><STRONG>server-info</STRONG>:
13b501825bce68e7e49b4bc775da93e38d9bd9f3fuankg Get the server's configuration information
13b501825bce68e7e49b4bc775da93e38d9bd9f3fuankg (<A HREF="mod/mod_info.html">mod_info</A>)
13b501825bce68e7e49b4bc775da93e38d9bd9f3fuankg<LI><STRONG>server-parsed</STRONG>:
13b501825bce68e7e49b4bc775da93e38d9bd9f3fuankg Parse for server-side includes
13b501825bce68e7e49b4bc775da93e38d9bd9f3fuankg (<A HREF="mod/mod_include.html">mod_include</A>)
13b501825bce68e7e49b4bc775da93e38d9bd9f3fuankg<LI><STRONG>server-status</STRONG>:
13b501825bce68e7e49b4bc775da93e38d9bd9f3fuankg Get the server's status report
13b501825bce68e7e49b4bc775da93e38d9bd9f3fuankg (<A HREF="mod/mod_status.html">mod_status</A>)
13b501825bce68e7e49b4bc775da93e38d9bd9f3fuankg<LI><STRONG>type-map</STRONG>:
13b501825bce68e7e49b4bc775da93e38d9bd9f3fuankg Parse as a type map file for content negotiation
13b501825bce68e7e49b4bc775da93e38d9bd9f3fuankg (<A HREF="mod/mod_negotiation.html">mod_negotiation</A>)
13b501825bce68e7e49b4bc775da93e38d9bd9f3fuankg</UL>
13b501825bce68e7e49b4bc775da93e38d9bd9f3fuankg
13b501825bce68e7e49b4bc775da93e38d9bd9f3fuankg<P>
13b501825bce68e7e49b4bc775da93e38d9bd9f3fuankg
13b501825bce68e7e49b4bc775da93e38d9bd9f3fuankg<H2>Directives</H2>
13b501825bce68e7e49b4bc775da93e38d9bd9f3fuankg<UL>
13b501825bce68e7e49b4bc775da93e38d9bd9f3fuankg<LI><A HREF="#addhandler">AddHandler</A>
13b501825bce68e7e49b4bc775da93e38d9bd9f3fuankg<LI><A HREF="#sethandler">SetHandler</A>
13b501825bce68e7e49b4bc775da93e38d9bd9f3fuankg</UL>
13b501825bce68e7e49b4bc775da93e38d9bd9f3fuankg
13b501825bce68e7e49b4bc775da93e38d9bd9f3fuankg<HR>
13b501825bce68e7e49b4bc775da93e38d9bd9f3fuankg
13b501825bce68e7e49b4bc775da93e38d9bd9f3fuankg<H2><A name="addhandler">AddHandler</A></H2>
13b501825bce68e7e49b4bc775da93e38d9bd9f3fuankg
13b501825bce68e7e49b4bc775da93e38d9bd9f3fuankg<A
13b501825bce68e7e49b4bc775da93e38d9bd9f3fuankg HREF="mod/directive-dict.html#Syntax"
13b501825bce68e7e49b4bc775da93e38d9bd9f3fuankg REL="Help"
13b501825bce68e7e49b4bc775da93e38d9bd9f3fuankg><STRONG>Syntax:</STRONG></A> &lt;AddHandler <EM>handler-name extension</EM>&gt;<BR>
13b501825bce68e7e49b4bc775da93e38d9bd9f3fuankg<A
13b501825bce68e7e49b4bc775da93e38d9bd9f3fuankg HREF="mod/directive-dict.html#Context"
13b501825bce68e7e49b4bc775da93e38d9bd9f3fuankg REL="Help"
13b501825bce68e7e49b4bc775da93e38d9bd9f3fuankg><STRONG>Context:</STRONG></A> server config, virtual host, directory, .htaccess<BR>
13b501825bce68e7e49b4bc775da93e38d9bd9f3fuankg<A
13b501825bce68e7e49b4bc775da93e38d9bd9f3fuankg HREF="mod/directive-dict.html#Status"
13b501825bce68e7e49b4bc775da93e38d9bd9f3fuankg REL="Help"
13b501825bce68e7e49b4bc775da93e38d9bd9f3fuankg><STRONG>Status:</STRONG></A> Base<BR>
13b501825bce68e7e49b4bc775da93e38d9bd9f3fuankg<A
13b501825bce68e7e49b4bc775da93e38d9bd9f3fuankg HREF="mod/directive-dict.html#Module"
13b501825bce68e7e49b4bc775da93e38d9bd9f3fuankg REL="Help"
13b501825bce68e7e49b4bc775da93e38d9bd9f3fuankg><STRONG>Module:</STRONG></A> mod_mime
13b501825bce68e7e49b4bc775da93e38d9bd9f3fuankg
13b501825bce68e7e49b4bc775da93e38d9bd9f3fuankg<P>AddHandler maps the filename extension <EM>extension</EM> to the
13b501825bce68e7e49b4bc775da93e38d9bd9f3fuankghandler <EM>handler-name</EM>. For example, to activate CGI scripts
13b501825bce68e7e49b4bc775da93e38d9bd9f3fuankgwith the file extension "<CODE>.cgi</CODE>", you might use:
13b501825bce68e7e49b4bc775da93e38d9bd9f3fuankg<PRE>
13b501825bce68e7e49b4bc775da93e38d9bd9f3fuankg AddHandler cgi-script cgi
13b501825bce68e7e49b4bc775da93e38d9bd9f3fuankg</PRE>
13b501825bce68e7e49b4bc775da93e38d9bd9f3fuankg
13b501825bce68e7e49b4bc775da93e38d9bd9f3fuankg<P>Once that has been put into your srm.conf or httpd.conf file, any
13b501825bce68e7e49b4bc775da93e38d9bd9f3fuankgfile ending with "<CODE>.cgi</CODE>" will be treated as a CGI
13b501825bce68e7e49b4bc775da93e38d9bd9f3fuankgprogram.</P>
13b501825bce68e7e49b4bc775da93e38d9bd9f3fuankg
13b501825bce68e7e49b4bc775da93e38d9bd9f3fuankg<HR>
13b501825bce68e7e49b4bc775da93e38d9bd9f3fuankg
13b501825bce68e7e49b4bc775da93e38d9bd9f3fuankg<H2><A name="sethandler">SetHandler</A></H2>
13b501825bce68e7e49b4bc775da93e38d9bd9f3fuankg
13b501825bce68e7e49b4bc775da93e38d9bd9f3fuankg<A
13b501825bce68e7e49b4bc775da93e38d9bd9f3fuankg HREF="mod/directive-dict.html#Syntax"
13b501825bce68e7e49b4bc775da93e38d9bd9f3fuankg REL="Help"
13b501825bce68e7e49b4bc775da93e38d9bd9f3fuankg><STRONG>Syntax:</STRONG></A> &lt;SetHandler <EM>handler-name</EM>&gt;<BR>
13b501825bce68e7e49b4bc775da93e38d9bd9f3fuankg<A
13b501825bce68e7e49b4bc775da93e38d9bd9f3fuankg HREF="mod/directive-dict.html#Context"
13b501825bce68e7e49b4bc775da93e38d9bd9f3fuankg REL="Help"
13b501825bce68e7e49b4bc775da93e38d9bd9f3fuankg><STRONG>Context:</STRONG></A> directory, .htaccess<BR>
0662ed52e814f8f08ef0e09956413a792584eddffuankg<A
13b501825bce68e7e49b4bc775da93e38d9bd9f3fuankg HREF="mod/directive-dict.html#Status"
13b501825bce68e7e49b4bc775da93e38d9bd9f3fuankg REL="Help"
13b501825bce68e7e49b4bc775da93e38d9bd9f3fuankg><STRONG>Status:</STRONG></A> Base<BR>
13b501825bce68e7e49b4bc775da93e38d9bd9f3fuankg<A
13b501825bce68e7e49b4bc775da93e38d9bd9f3fuankg HREF="mod/directive-dict.html#Module"
13b501825bce68e7e49b4bc775da93e38d9bd9f3fuankg REL="Help"
13b501825bce68e7e49b4bc775da93e38d9bd9f3fuankg><STRONG>Module:</STRONG></A> mod_mime
13b501825bce68e7e49b4bc775da93e38d9bd9f3fuankg
13b501825bce68e7e49b4bc775da93e38d9bd9f3fuankg<P>When placed into an <CODE>.htaccess</CODE> file or a
13b501825bce68e7e49b4bc775da93e38d9bd9f3fuankg<CODE>&lt;Directory&gt;</CODE> or <CODE>&lt;Location&gt;</CODE> section,
13b501825bce68e7e49b4bc775da93e38d9bd9f3fuankgthis directive forces all matching files to be parsed through the
13b501825bce68e7e49b4bc775da93e38d9bd9f3fuankghandler given by <EM>handler-name</EM>. For example, if you had a
0662ed52e814f8f08ef0e09956413a792584eddffuankgdirectory you wanted to be parsed entirely as imagemap rule files,
13b501825bce68e7e49b4bc775da93e38d9bd9f3fuankgregardless of extension, you might put the following into an
13b501825bce68e7e49b4bc775da93e38d9bd9f3fuankg<CODE>.htaccess</CODE> file in that directory:
13b501825bce68e7e49b4bc775da93e38d9bd9f3fuankg<PRE>
13b501825bce68e7e49b4bc775da93e38d9bd9f3fuankg SetHandler imap-file
0662ed52e814f8f08ef0e09956413a792584eddffuankg</PRE>
13b501825bce68e7e49b4bc775da93e38d9bd9f3fuankg<P>Another example: if you wanted to have the server display a status
13b501825bce68e7e49b4bc775da93e38d9bd9f3fuankgreport whenever a URL of <CODE>http://servername/status</CODE> was
13b501825bce68e7e49b4bc775da93e38d9bd9f3fuankgcalled, you might put the following into access.conf:
13b501825bce68e7e49b4bc775da93e38d9bd9f3fuankg<PRE>
13b501825bce68e7e49b4bc775da93e38d9bd9f3fuankg &lt;Location /status&gt;
13b501825bce68e7e49b4bc775da93e38d9bd9f3fuankg SetHandler server-status
13b501825bce68e7e49b4bc775da93e38d9bd9f3fuankg &lt;/Location&gt;
13b501825bce68e7e49b4bc775da93e38d9bd9f3fuankg</PRE>
13b501825bce68e7e49b4bc775da93e38d9bd9f3fuankg
0662ed52e814f8f08ef0e09956413a792584eddffuankg<P><HR>
13b501825bce68e7e49b4bc775da93e38d9bd9f3fuankg
13b501825bce68e7e49b4bc775da93e38d9bd9f3fuankg<H2>Programmer's Note</H2>
13b501825bce68e7e49b4bc775da93e38d9bd9f3fuankg
13b501825bce68e7e49b4bc775da93e38d9bd9f3fuankg<P>In order to implement the handler features, an addition has been
13b501825bce68e7e49b4bc775da93e38d9bd9f3fuankgmade to the <A HREF="misc/API.html">Apache API</A> that you may wish to
13b501825bce68e7e49b4bc775da93e38d9bd9f3fuankgmake use of. Specifically, a new record has been added to the
13b501825bce68e7e49b4bc775da93e38d9bd9f3fuankg<CODE>request_rec</CODE> structure:</P>
13b501825bce68e7e49b4bc775da93e38d9bd9f3fuankg<PRE>
13b501825bce68e7e49b4bc775da93e38d9bd9f3fuankg char *handler
13b501825bce68e7e49b4bc775da93e38d9bd9f3fuankg</PRE>
13b501825bce68e7e49b4bc775da93e38d9bd9f3fuankg<P>If you wish to have your module engage a handler, you need only to
13b501825bce68e7e49b4bc775da93e38d9bd9f3fuankgset <CODE>r-&gt;handler</CODE> to the name of the handler at any time
fd7c287b8fcccc3e1e7834bf8daf8fe7fd6cd49dfuankgprior to the <CODE>invoke_handler</CODE> stage of the
13b501825bce68e7e49b4bc775da93e38d9bd9f3fuankgrequest. Handlers are implemented as they were before, albeit using
13b501825bce68e7e49b4bc775da93e38d9bd9f3fuankgthe handler name instead of a content type. While it is not
13b501825bce68e7e49b4bc775da93e38d9bd9f3fuankgnecessary, the naming convention for handlers is to use a
13b501825bce68e7e49b4bc775da93e38d9bd9f3fuankgdash-separated word, with no slashes, so as to not invade the media
13b501825bce68e7e49b4bc775da93e38d9bd9f3fuankgtype name-space.</P>
13b501825bce68e7e49b4bc775da93e38d9bd9f3fuankg
13b501825bce68e7e49b4bc775da93e38d9bd9f3fuankg<!--#include virtual="footer.html" -->
13b501825bce68e7e49b4bc775da93e38d9bd9f3fuankg</BODY>
13b501825bce68e7e49b4bc775da93e38d9bd9f3fuankg</HTML>
13b501825bce68e7e49b4bc775da93e38d9bd9f3fuankg
13b501825bce68e7e49b4bc775da93e38d9bd9f3fuankg