docs/manual/handler.html - httpd - Git at Google

 <!DOCTYPE HTML PUBLIC "-//IETF//DTD HTML 2.0//EN">
 <HTML>
 <HEAD>
 <TITLE>Apache's Handler Use</TITLE>
 </HEAD>

 <BODY>
 <IMG SRC="../images/apache_sub.gif" ALT="">
 <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"
 seperately. 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_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_asis.html">mod_asis</a>)
 <li><strong>cgi-script</strong>:
     Treat the file as a CGI script.
     (<a href="mod_cgi.html">mod_cgi</a>)
 <li><strong>imap-file</strong>:
     Imagemap rule file.
     (<a href="mod_imap.html">mod_imap</a>)
 <li><strong>server-info</strong>:
     Get the server's configuration information
     (<a href="mod_info.html">mod_info</a>)
 <li><strong>server-parsed</strong>:
     Parse for server-side includes
     (<a href="mod_include.html">mod_include</a>)
 <li><strong>server-status</strong>:
     Get the server's status report
     (<a href="mod_status.html">mod_status</a>)
 <li><strong>type-map</strong>:
     Parse as a type map file for content negotation
     (<a href="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> &lt;AddHandler <em>handler-name extention</em>&gt;<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> &lt;SetHandler <em>handler-name</em>&gt;<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>&lt;Directory&gt;</code> or <code>&lt;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>
     &lt;Location /status&gt;
     SetHandler server-status
     &lt;/Location&gt;
 </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="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-&gt;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, albiet using
 the handler name instead of a content type. While it is not
 neccessary, the naming convention for handlers is to use a
 dash-seperated word, with no slashes, so as to not invade the media
 type namespace.</p>

 <hr>

 <A HREF="../"><IMG SRC="../images/apache_home.gif" ALT="Home"></A>
 <A HREF="./"><IMG SRC="../images/apache_index.gif" ALT="Index"></A>

 </BODY>
 </HTML>
	<!DOCTYPE HTML PUBLIC "-//IETF//DTD HTML 2.0//EN">
	<HTML>
	<HEAD>
	<TITLE>Apache's Handler Use</TITLE>
	</HEAD>

	<BODY>
	<IMG SRC="../images/apache_sub.gif" ALT="">
	<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"
	seperately. 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_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_asis.html">mod_asis</a>)
	<li><strong>cgi-script</strong>:
	Treat the file as a CGI script.
	(<a href="mod_cgi.html">mod_cgi</a>)
	<li><strong>imap-file</strong>:
	Imagemap rule file.
	(<a href="mod_imap.html">mod_imap</a>)
	<li><strong>server-info</strong>:
	Get the server's configuration information
	(<a href="mod_info.html">mod_info</a>)
	<li><strong>server-parsed</strong>:
	Parse for server-side includes
	(<a href="mod_include.html">mod_include</a>)
	<li><strong>server-status</strong>:
	Get the server's status report
	(<a href="mod_status.html">mod_status</a>)
	<li><strong>type-map</strong>:
	Parse as a type map file for content negotation
	(<a href="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 extention</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="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, albiet using
	the handler name instead of a content type. While it is not
	neccessary, the naming convention for handlers is to use a
	dash-seperated word, with no slashes, so as to not invade the media
	type namespace.</p>

	<hr>

	<A HREF="../"><IMG SRC="../images/apache_home.gif" ALT="Home"></A>
	<A HREF="./"><IMG SRC="../images/apache_index.gif" ALT="Index"></A>

	</BODY>
	</HTML>