handler.html.en revision cb741b51bbf3d6e58ee4196096af81fcb055aba4
1b05bdb88b90d3c947351f262d7ae7d68f0a4a6fTill Mossakowski<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
1b05bdb88b90d3c947351f262d7ae7d68f0a4a6fTill Mossakowski<html xmlns="http://www.w3.org/1999/xhtml" lang="en" xml:lang="en"><head><!--
c06dd8856a03b72f6b3f69e874f8700f10cb8522Christian Maeder XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
75a6279dbae159d018ef812185416cf6df386c10Till Mossakowski This file is generated from xml source: DO NOT EDIT
75a6279dbae159d018ef812185416cf6df386c10Till Mossakowski XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
c06dd8856a03b72f6b3f69e874f8700f10cb8522Christian Maeder --><title>Apache's Handler Use - Apache HTTP Server</title><link href="/style/css/manual.css" rel="stylesheet" media="all" type="text/css" title="Main stylesheet" /><link href="/style/css/manual-loose-100pc.css" rel="alternate stylesheet" media="all" type="text/css" title="No Sidebar - Default font size" /><link href="/images/favicon.ico" rel="shortcut icon" /></head><body id="manual-page"><div id="page-header"><p class="menu"><a href="/mod/">Modules</a> | <a href="/mod/directives.html">Directives</a> | <a href="/faq/">FAQ</a> | <a href="/glossary.html">Glossary</a> | <a href="/sitemap.html">Sitemap</a></p><p class="apache">Apache HTTP Server Version 2.0</p><img alt="" src="/images/feather.gif" /></div><div class="up"><a href="./"><img title="<-" alt="<-" src="/images/left.gif" /></a></div><div id="path"><a href="http://www.apache.org/">Apache</a> > <a href="http://httpd.apache.org/">HTTP Server</a> > <a href="http://httpd.apache.org/docs-project/">Documentation</a> > <a href="./">Version 2.0</a></div><div id="page-content"><div id="preamble"><h1>Apache's Handler Use</h1>
1b05bdb88b90d3c947351f262d7ae7d68f0a4a6fTill Mossakowski <p>This document describes the use of Apache's Handlers.</p>
1b05bdb88b90d3c947351f262d7ae7d68f0a4a6fTill Mossakowski </div><div id="quickview"><ul id="toc"><li><img alt="" src="/images/down.gif" /> <a href="#definition">What is a Handler</a></li><li><img alt="" src="/images/down.gif" /> <a href="#examples">Examples</a></li><li><img alt="" src="/images/down.gif" /> <a href="#programmer">Programmer's Note</a></li></ul></div><div class="top"><a href="#page-header"><img alt="top" src="/images/up.gif" /></a></div><div class="section"><h2><a name="definition" id="definition">What is a Handler</a></h2>
95c3e5d11dcee331dc3876a9bf0c1d6daa38e2caChristian Maeder <table class="related"><tr><th>Related Modules</th><th>Related Directives</th></tr><tr><td><ul><li><code class="module"><a href="/mod/mod_actions.html">mod_actions</a></code></li><li><code class="module"><a href="/mod/mod_asis.html">mod_asis</a></code></li><li><code class="module"><a href="/mod/mod_cgi.html">mod_cgi</a></code></li><li><code class="module"><a href="/mod/mod_imap.html">mod_imap</a></code></li><li><code class="module"><a href="/mod/mod_info.html">mod_info</a></code></li><li><code class="module"><a href="/mod/mod_mime.html">mod_mime</a></code></li><li><code class="module"><a href="/mod/mod_negotiation.html">mod_negotiation</a></code></li><li><code class="module"><a href="/mod/mod_status.html">mod_status</a></code></li></ul></td><td><ul><li><code class="directive"><a href="/mod/mod_actions.html#action">Action</a></code></li><li><code class="directive"><a href="/mod/mod_mime.html#addhandler">AddHandler</a></code></li><li><code class="directive"><a href="/mod/mod_mime.html#removehandler">RemoveHandler</a></code></li><li><code class="directive"><a href="/mod/mod_mime.html#sethandler">SetHandler</a></code></li></ul></td></tr></table>
95c3e5d11dcee331dc3876a9bf0c1d6daa38e2caChristian Maeder <p>A "handler" is an internal Apache representation of the
95c3e5d11dcee331dc3876a9bf0c1d6daa38e2caChristian Maeder action to be performed when a file is called. Generally, files
95c3e5d11dcee331dc3876a9bf0c1d6daa38e2caChristian Maeder have implicit handlers, based on the file type. Normally, all
95c3e5d11dcee331dc3876a9bf0c1d6daa38e2caChristian Maeder files are simply served by the server, but certain file types
c06dd8856a03b72f6b3f69e874f8700f10cb8522Christian Maeder are "handled" separately.</p>
95c3e5d11dcee331dc3876a9bf0c1d6daa38e2caChristian Maeder <p>Apache 1.1 adds the ability to use handlers explicitly.
95c3e5d11dcee331dc3876a9bf0c1d6daa38e2caChristian Maeder Based on either filename extensions or on location, handlers
c0ba7121c93e4f9292f2d95a0ac7460a7b9e5aeaTill Mossakowski can be specified without relation to file type. This is
e3c9174a782e90f965a0b080c22861c3ef5af12dTill Mossakowski advantageous both because it is a more elegant solution, and
95c3e5d11dcee331dc3876a9bf0c1d6daa38e2caChristian Maeder because it also allows for both a type <strong>and</strong> a
95c3e5d11dcee331dc3876a9bf0c1d6daa38e2caChristian Maeder handler to be associated with a file. (See also <a href="mod/mod_mime.html#multipleext">Files with Multiple
95c3e5d11dcee331dc3876a9bf0c1d6daa38e2caChristian Maeder <p>Handlers can either be built into the server or included in
95c3e5d11dcee331dc3876a9bf0c1d6daa38e2caChristian Maeder a module, or they can be added with the <code class="directive"><a href="/mod/mod_actions.html#action">Action</a></code> directive. The
95c3e5d11dcee331dc3876a9bf0c1d6daa38e2caChristian Maeder built-in handlers in the standard distribution are as
95c3e5d11dcee331dc3876a9bf0c1d6daa38e2caChristian Maeder <li><strong>default-handler</strong>: Send the file using the
95c3e5d11dcee331dc3876a9bf0c1d6daa38e2caChristian Maeder <code>default_handler()</code>, which is the handler used by
95c3e5d11dcee331dc3876a9bf0c1d6daa38e2caChristian Maeder default to handle static content. (core)</li>
95c3e5d11dcee331dc3876a9bf0c1d6daa38e2caChristian Maeder <li><strong>send-as-is</strong>: Send file with HTTP headers
95c3e5d11dcee331dc3876a9bf0c1d6daa38e2caChristian Maeder as is. (<code class="module"><a href="/mod/mod_asis.html">mod_asis</a></code>)</li>
95c3e5d11dcee331dc3876a9bf0c1d6daa38e2caChristian Maeder <li><strong>cgi-script</strong>: Treat the file as a CGI
95c3e5d11dcee331dc3876a9bf0c1d6daa38e2caChristian Maeder script. (<code class="module"><a href="/mod/mod_cgi.html">mod_cgi</a></code>)</li>
95c3e5d11dcee331dc3876a9bf0c1d6daa38e2caChristian Maeder <li><strong>imap-file</strong>: Parse as an imagemap rule
95c3e5d11dcee331dc3876a9bf0c1d6daa38e2caChristian Maeder file. (<code class="module"><a href="/mod/mod_imap.html">mod_imap</a></code>)</li>
95c3e5d11dcee331dc3876a9bf0c1d6daa38e2caChristian Maeder <li><strong>server-info</strong>: Get the server's
95c3e5d11dcee331dc3876a9bf0c1d6daa38e2caChristian Maeder configuration information. (<code class="module"><a href="/mod/mod_info.html">mod_info</a></code>)</li>
95c3e5d11dcee331dc3876a9bf0c1d6daa38e2caChristian Maeder <li><strong>server-status</strong>: Get the server's status
95c3e5d11dcee331dc3876a9bf0c1d6daa38e2caChristian Maeder report. (<code class="module"><a href="/mod/mod_status.html">mod_status</a></code>)</li>
95c3e5d11dcee331dc3876a9bf0c1d6daa38e2caChristian Maeder <li><strong>type-map</strong>: Parse as a type map file for
95c3e5d11dcee331dc3876a9bf0c1d6daa38e2caChristian Maeder content negotiation. (<code class="module"><a href="/mod/mod_negotiation.html">mod_negotiation</a></code>)</li>
95c3e5d11dcee331dc3876a9bf0c1d6daa38e2caChristian Maeder </div><div class="top"><a href="#page-header"><img alt="top" src="/images/up.gif" /></a></div><div class="section"><h2><a name="examples" id="examples">Examples</a></h2>
e3c9174a782e90f965a0b080c22861c3ef5af12dTill Mossakowski <h3><a name="example1" id="example1">Modifying static content using a CGI script</a></h3>
95c3e5d11dcee331dc3876a9bf0c1d6daa38e2caChristian Maeder <p>The following directives will cause requests for files with
95c3e5d11dcee331dc3876a9bf0c1d6daa38e2caChristian Maeder the <code>html</code> extension to trigger the launch of the
ba904a15082557e939db689fcfba0c68c9a4f740Christian Maeder AddHandler add-footer .html
95c3e5d11dcee331dc3876a9bf0c1d6daa38e2caChristian Maeder <p>Then the CGI script is responsible for sending the
ba904a15082557e939db689fcfba0c68c9a4f740Christian Maeder originally requested document (pointed to by the
ba904a15082557e939db689fcfba0c68c9a4f740Christian Maeder <code>PATH_TRANSLATED</code> environment variable) and making
ba904a15082557e939db689fcfba0c68c9a4f740Christian Maeder whatever modifications or additions are desired.</p>
95c3e5d11dcee331dc3876a9bf0c1d6daa38e2caChristian Maeder <h3><a name="example2" id="example2">Files with HTTP headers</a></h3>
ba904a15082557e939db689fcfba0c68c9a4f740Christian Maeder <p>The following directives will enable the
95c3e5d11dcee331dc3876a9bf0c1d6daa38e2caChristian Maeder <code>send-as-is</code> handler, which is used for files which
e379124f467e5d0ef7d3c0ca238bff0521f70831Till Mossakowski contain their own HTTP headers. All files in the
95c3e5d11dcee331dc3876a9bf0c1d6daa38e2caChristian Maeder <code>/web/htdocs/asis/</code> directory will be processed by
e18f5e61d29064a427ca7bef421e250a9a4c9701Till Mossakowski the <code>send-as-is</code> handler, regardless of their
95c3e5d11dcee331dc3876a9bf0c1d6daa38e2caChristian Maeder filename extensions.</p>
95c3e5d11dcee331dc3876a9bf0c1d6daa38e2caChristian Maeder SetHandler send-as-is<br />
95c3e5d11dcee331dc3876a9bf0c1d6daa38e2caChristian Maeder </Directory>
1b05bdb88b90d3c947351f262d7ae7d68f0a4a6fTill Mossakowski </div><div class="top"><a href="#page-header"><img alt="top" src="/images/up.gif" /></a></div><div class="section"><h2><a name="programmer" id="programmer">Programmer's Note</a></h2>
1b05bdb88b90d3c947351f262d7ae7d68f0a4a6fTill Mossakowski <p>In order to implement the handler features, an addition has
1b05bdb88b90d3c947351f262d7ae7d68f0a4a6fTill Mossakowski been made to the <a href="developer/API.html">Apache API</a> that
e379124f467e5d0ef7d3c0ca238bff0521f70831Till Mossakowski you may wish to make use of. Specifically, a new record has
95c3e5d11dcee331dc3876a9bf0c1d6daa38e2caChristian Maeder been added to the <code>request_rec</code> structure:</p>
95c3e5d11dcee331dc3876a9bf0c1d6daa38e2caChristian Maeder char *handler
95c3e5d11dcee331dc3876a9bf0c1d6daa38e2caChristian Maeder <p>If you wish to have your module engage a handler, you need
95c3e5d11dcee331dc3876a9bf0c1d6daa38e2caChristian Maeder only to set <code>r->handler</code> to the name of the
e379124f467e5d0ef7d3c0ca238bff0521f70831Till Mossakowski handler at any time prior to the <code>invoke_handler</code>
1b05bdb88b90d3c947351f262d7ae7d68f0a4a6fTill Mossakowski stage of the request. Handlers are implemented as they were
e379124f467e5d0ef7d3c0ca238bff0521f70831Till Mossakowski before, albeit using the handler name instead of a content
1b05bdb88b90d3c947351f262d7ae7d68f0a4a6fTill Mossakowski type. While it is not necessary, the naming convention for
1b05bdb88b90d3c947351f262d7ae7d68f0a4a6fTill Mossakowski handlers is to use a dash-separated word, with no slashes, so
1b05bdb88b90d3c947351f262d7ae7d68f0a4a6fTill Mossakowski as to not invade the media type name-space.</p>
1b05bdb88b90d3c947351f262d7ae7d68f0a4a6fTill Mossakowski </div></div><div id="footer"><p class="apache">Maintained by the <a href="http://httpd.apache.org/docs-project/">Apache HTTP Server Documentation Project</a></p><p class="menu"><a href="/mod/">Modules</a> | <a href="/mod/directives.html">Directives</a> | <a href="/faq/">FAQ</a> | <a href="/glossary.html">Glossary</a> | <a href="/sitemap.html">Sitemap</a></p></div></body></html>