| <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN"> |
| <HTML> |
| <HEAD> |
| <TITLE>Apache's Handler Use</TITLE> |
| </HEAD> |
| |
| <!-- Background white, links blue (unvisited), navy (visited), red (active) --> |
| <BODY |
| BGCOLOR="#FFFFFF" |
| TEXT="#000000" |
| LINK="#0000FF" |
| VLINK="#000080" |
| ALINK="#FF0000" |
| > |
| <!--#include virtual="header.html" --> |
| <H1 ALIGN="CENTER">Apache's Handler Use</H1> |
| |
| <ul> |
| <li><a href="#definition">What is a Handler</a></li> |
| <li><a href="#examples">Examples</a></li> |
| <li><a href="#programmer">Programmer's Note</a></li> |
| </ul> |
| |
| <hr> |
| <H2><a name="definition">What is a Handler</a></H2> |
| |
| <table border="1"> |
| <tr><td valign="top"> |
| <strong>Related Modules</strong><br><br> |
| |
| <a href="mod/mod_actions.html">mod_actions</a><br> |
| <A HREF="mod/mod_asis.html">mod_asis</A><br> |
| <A HREF="mod/mod_cgi.html">mod_cgi</A><br> |
| <A HREF="mod/mod_imap.html">mod_imap</A><br> |
| <A HREF="mod/mod_info.html">mod_info</A><br> |
| <a href="mod/mod_mime.html">mod_mime</a><br> |
| <A HREF="mod/mod_negotiation.html">mod_negotiation</A><br> |
| <A HREF="mod/mod_status.html">mod_status</A><br> |
| </td> |
| <td valign="top"> |
| <strong>Related Directives</strong><br><br> |
| |
| <a href="mod/mod_actions.html#action">Action</a><br> |
| <A HREF="mod/mod_mime.html#addhandler">AddHandler</A><br> |
| <a href="mod/mod_mime.html#removehandler">RemoveHandler</a><br> |
| <A HREF="mod/mod_mime.html#sethandler">SetHandler</A><br> |
| </td> |
| </tr></table> |
| |
| |
| <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 types are "handled" |
| separately.</P> |
| |
| <P>Apache 1.1 adds the ability to use handlers explicitly. Based on |
| either filename extensions or on location, handlers can be specified |
| without relation to file type. This is advantageous both because it is |
| a more elegant solution, and because it also allows for both a type |
| <STRONG>and</STRONG> a handler to be associated with a file. (See also |
| <A HREF="mod/mod_mime.html#multipleext">Files with Multiple |
| Extensions</A>.)</p> |
| |
| <P>Handlers can either be built into the server or included in 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>default-handler</STRONG>: |
| Send the file using the <CODE>default_handler()</CODE>, which is the |
| handler used by default to handle static content. |
| (core) |
| <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>: |
| Parse as an 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-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> |
| |
| <hr> |
| |
| <h2><a name="examples">Examples</a></h2> |
| |
| <h3>Modifying static content using a CGI script</h3> |
| |
| <p>The following directives will cause requests for files with the |
| <code>html</code> extension to trigger the launch of the |
| <code>footer.pl</code> CGI script.</p> |
| |
| <pre> |
| Action add-footer /cgi-bin/footer.pl |
| AddHandler add-footer .html |
| </pre> |
| |
| <p>Then the CGI script is responsible for sending the originally |
| requested document (pointed to by the <code>PATH_TRANSLATED</code> |
| environment variable) and making whatever modifications or additions |
| are desired.</p> |
| |
| <h3>Files with HTTP headers</h3> |
| |
| <p>The following directives will enable the <code>send-as-is</code> |
| handler, which is used for files which contain their own HTTP headers. |
| All files in the <code>/web/htdocs/asis/</code> directory will be |
| processed by the <code>send-as-is</code> handler, regardless of their |
| filename extensions.</p> |
| |
| <pre> |
| <Directory /web/htdocs/asis> |
| SetHandler send-as-is |
| </Directory> |
| </pre> |
| |
| <hr> |
| |
| <H2><a name="programmer">Programmer's Note</a></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> |
| |
