handler.html revision 455a5f75c9935108a7ac1d50996f404e0553ac17
0N/A<!DOCTYPE HTML PUBLIC "-//IETF//DTD HTML 2.0//EN">
2362N/A<HTML>
0N/A<HEAD>
0N/A<TITLE>Apache's Handler Use</TITLE>
0N/A</HEAD>
0N/A
0N/A<BODY>
0N/A<IMG SRC="/images/apache_sub.gif" ALT="">
0N/A<h1>Apache's Handler Use</h1>
0N/A
0N/A<h2>What is a Handler</h2>
0N/A
0N/A<p>A "handler" is an internal Apache representation of the action to be
0N/Aperformed when a file is called. Generally, files have implicit
0N/Ahandlers, based on the file type. Normally, all files are simply
0N/Aserved by the server, but certain file typed are "handled"
0N/Aseperately. For example, you may use a type of
0N/A"application/x-httpd-cgi" to invoke CGI scripts.</p>
2362N/A
2362N/A<p>Apache 1.1 adds the additional ability to use handlers
2362N/Aexplicitly. Either based on filename extensions or on location, these
0N/Ahandlers are unrelated to file type. This is advantageous both because
0N/Ait is a more elegant solution, but it also allows for both a type
0N/A<strong>and</strong> a handler to be associated with a file.</p>
0N/A
0N/A<p>Handlers can either be built into the server or to a module, or
0N/Athey can be added with the <a
0N/Ahref="mod_actions.html#action">Action</a> directive. The built-in
0N/Ahandlers in the standard distribution are as follows:</p>
0N/A
0N/A<ul>
0N/A<li><strong>send-as-is</strong>:
0N/A Send file with HTTP headers as is.
0N/A (<a href="mod_asis.html">mod_asis</a>)
0N/A<li><strong>cgi-script</strong>:
0N/A Treat the file as a CGI script.
0N/A (<a href="mod_cgi.html">mod_cgi</a>)
0N/A<li><strong>imap-file</strong>:
0N/A Imagemap rule file.
0N/A (<a href="mod_imap.html">mod_imap</a>)
0N/A<li><strong>server-info</strong>:
0N/A Get the server's configuration information
0N/A (<a href="mod_info.html">mod_info</a>)
0N/A<li><strong>server-parsed</strong>:
0N/A Parse for server-side includes
0N/A (<a href="mod_include.html">mod_include</a>)
0N/A<li><strong>server-status</strong>:
0N/A Get the server's status report
0N/A (<a href="mod_status.html">mod_status</a>)
0N/A<li><strong>type-map</strong>:
0N/A Parse as a type map file for content negotation
0N/A (<a href="mod_negotiation.html">mod_negotiation</a>)
0N/A</ul>
0N/A
0N/A<p>
0N/A
0N/A<h2>Directives</h2>
0N/A<ul>
0N/A<li><A HREF="#addhandler">AddHandler</A>
0N/A<li><A HREF="#sethandler">SetHandler</A>
0N/A</ul>
0N/A
0N/A<hr>
0N/A
0N/A<h2><a name="addhandler">AddHandler</a></h2>
0N/A
0N/A<strong>Syntax:</strong> &lt;AddHandler <em>handler-name extention</em>&gt;<br>
0N/A<strong>Context:</strong> server config, virtual host, directory, .htaccess<br>
0N/A<strong>Status:</strong> Base<br>
0N/A<strong>Module:</strong> mod_mime
0N/A
0N/A<p>AddHandler maps the filename extension <em>extension</em> to the
0N/Ahandler <em>handler-name</em>. For example, to activate CGI scripts
0N/Awith the file extension "<code>.cgi</code>", you might use:
0N/A<pre>
0N/A AddHandler cgi-script cgi
0N/A</pre>
0N/A
0N/A<p>Once that has been put into your srm.conf or httpd.conf file, any
0N/Afile ending with "<code>.cgi</code>" will be treated as a CGI
0N/Aprogram.</p>
0N/A
0N/A<hr>
0N/A
0N/A<h2><a name="sethandler">SetHandler</a></h2>
0N/A
0N/A<strong>Syntax:</strong> &lt;SetHandler <em>handler-name</em>&gt;<br>
0N/A<strong>Context:</strong> directory, .htaccess<br>
0N/A<strong>Status:</strong> Base<br>
0N/A<strong>Module:</strong> mod_mime
0N/A
0N/A<p>When placed into an <code>.htaccess</code> file or a
0N/A<code>&lt;Directory&gt;</code> or <code>&lt;Location</code> section,
0N/Athis directive forces all matching files to be parsed through the
0N/Ahandler given by <em>handler-name</em>. For example, if you had a
0N/Adirectory you wanted to be parsed entirely as imagemap rule files,
0N/Aregardless of extension, you might put the following into an
0N/A<code>.htaccess</code> file in that directory:
0N/A<pre>
0N/A SetHandler imap-file
0N/A</pre>
0N/A<p>Another example: if you wanted to have the server display a status
0N/Areport whenever a URL of <code>http://servername/status</code> was
0N/Acalled, you might put the following into access.conf:
0N/A<pre>
0N/A &lt;Location /status&gt;
0N/A SetHandler server-status
0N/A &lt;/Location&gt;
0N/A</pre>
0N/A
0N/A<p><hr>
0N/A
0N/A<h2>Programmer's Note</h2>
0N/A
0N/A<p>In order to implement the handler features, an addition has been
0N/Amade to the <a href="API.html">Apache API</a> that you may wish to
0N/Amake use of. Specifically, a new record has been added to the
0N/A<code>request_rec</code> structure:</p>
0N/A<pre>
0N/A char *handler
0N/A</pre>
0N/A<p>If you wish to have your module engage a handler, you need only to
0N/Aset <code>r-&gt;handler</code> to the name of the handler at any time
0N/Aprior to the <code>invoke_handler</code> stage of the
0N/Arequest. Handlers are implemented as they were before, albiet using
0N/Athe handler name instead of a content type. While it is not
0N/Aneccessary, the naming convention for handlers is to use a
0N/Adash-seperated word, with no slashes, so as to not invade the media
0N/Atype namespace.</p>
0N/A
0N/A<hr>
0N/A
0N/A<A HREF="../"><IMG SRC="/images/apache_home.gif" ALT="Home"></A>
0N/A<A HREF="./"><IMG SRC="/images/apache_index.gif" ALT="Index"></A>
0N/A
0N/A</BODY>
0N/A</HTML>
0N/A
0N/A