| <!DOCTYPE HTML PUBLIC "-//IETF//DTD HTML 2.0//EN"> |
| <HTML> |
| <HEAD> |
| <TITLE>Apache's Handler Use</TITLE> |
| </HEAD> |
| |
| <BODY> |
| <!--#include virtual="header.html" --> |
| <h1>Apache's Handler Use</h1> |
| |
| <h2>What is a Handler</h2> |
| |
| <p>A "handler" is an internal Apache representation of the action to be |
| performed when a file is called. Generally, files have implicit |
| handlers, based on the file type. Normally, all files are simply |
| served by the server, but certain file typed are "handled" |
| separately. For example, you may use a type of |
| "application/x-httpd-cgi" to invoke CGI scripts.</p> |
| |
| <p>Apache 1.1 adds the additional ability to use handlers |
| explicitly. Either based on filename extensions or on location, these |
| handlers are unrelated to file type. This is advantageous both because |
| it is a more elegant solution, but it also allows for both a type |
| <strong>and</strong> a handler to be associated with a file.</p> |
| |
| <p>Handlers can either be built into the server or to a module, or |
| they can be added with the <a |
| href="mod/mod_actions.html#action">Action</a> directive. The built-in |
| handlers in the standard distribution are as follows:</p> |
| |
| <ul> |
| <li><strong>send-as-is</strong>: |
| Send file with HTTP headers as is. |
| (<a href="mod/mod_asis.html">mod_asis</a>) |
| <li><strong>cgi-script</strong>: |
| Treat the file as a CGI script. |
| (<a href="mod/mod_cgi.html">mod_cgi</a>) |
| <li><strong>imap-file</strong>: |
| Imagemap rule file. |
| (<a href="mod/mod_imap.html">mod_imap</a>) |
| <li><strong>server-info</strong>: |
| Get the server's configuration information |
| (<a href="mod/mod_info.html">mod_info</a>) |
| <li><strong>server-parsed</strong>: |
| Parse for server-side includes |
| (<a href="mod/mod_include.html">mod_include</a>) |
| <li><strong>server-status</strong>: |
| Get the server's status report |
| (<a href="mod/mod_status.html">mod_status</a>) |
| <li><strong>type-map</strong>: |
| Parse as a type map file for content negotiation |
| (<a href="mod/mod_negotiation.html">mod_negotiation</a>) |
| </ul> |
| |
| <p> |
| |
| <h2>Directives</h2> |
| <ul> |
| <li><A HREF="#addhandler">AddHandler</A> |
| <li><A HREF="#sethandler">SetHandler</A> |
| </ul> |
| |
| <hr> |
| |
| <h2><a name="addhandler">AddHandler</a></h2> |
| |
| <strong>Syntax:</strong> <AddHandler <em>handler-name extension</em>><br> |
| <strong>Context:</strong> server config, virtual host, directory, .htaccess<br> |
| <strong>Status:</strong> Base<br> |
| <strong>Module:</strong> mod_mime |
| |
| <p>AddHandler maps the filename extension <em>extension</em> to the |
| handler <em>handler-name</em>. For example, to activate CGI scripts |
| with the file extension "<code>.cgi</code>", you might use: |
| <pre> |
| AddHandler cgi-script cgi |
| </pre> |
| |
| <p>Once that has been put into your srm.conf or httpd.conf file, any |
| file ending with "<code>.cgi</code>" will be treated as a CGI |
| program.</p> |
| |
| <hr> |
| |
| <h2><a name="sethandler">SetHandler</a></h2> |
| |
| <strong>Syntax:</strong> <SetHandler <em>handler-name</em>><br> |
| <strong>Context:</strong> directory, .htaccess<br> |
| <strong>Status:</strong> Base<br> |
| <strong>Module:</strong> mod_mime |
| |
| <p>When placed into an <code>.htaccess</code> file or a |
| <code><Directory></code> or <code><Location</code> section, |
| this directive forces all matching files to be parsed through the |
| handler given by <em>handler-name</em>. For example, if you had a |
| directory you wanted to be parsed entirely as imagemap rule files, |
| regardless of extension, you might put the following into an |
| <code>.htaccess</code> file in that directory: |
| <pre> |
| SetHandler imap-file |
| </pre> |
| <p>Another example: if you wanted to have the server display a status |
| report whenever a URL of <code>http://servername/status</code> was |
| called, you might put the following into access.conf: |
| <pre> |
| <Location /status> |
| SetHandler server-status |
| </Location> |
| </pre> |
| |
| <p><hr> |
| |
| <h2>Programmer's Note</h2> |
| |
| <p>In order to implement the handler features, an addition has been |
| made to the <a href="misc/API.html">Apache API</a> that you may wish to |
| make use of. Specifically, a new record has been added to the |
| <code>request_rec</code> structure:</p> |
| <pre> |
| char *handler |
| </pre> |
| <p>If you wish to have your module engage a handler, you need only to |
| set <code>r->handler</code> to the name of the handler at any time |
| prior to the <code>invoke_handler</code> stage of the |
| request. Handlers are implemented as they were before, albeit using |
| the handler name instead of a content type. While it is not |
| necessary, the naming convention for handlers is to use a |
| dash-separated word, with no slashes, so as to not invade the media |
| type name-space.</p> |
| |
| <!--#include virtual="footer.html" --> |
| </BODY> |
| </HTML> |
| |