granicus.if.org Git - apache/blob - docs/manual/handler.html

   1 <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN">
   2 <HTML>
   3 <HEAD>
   4 <TITLE>Apache's Handler Use</TITLE>
   5 </HEAD>
   6
   7 <!-- Background white, links blue (unvisited), navy (visited), red (active) -->
   8 <BODY
   9  BGCOLOR="#FFFFFF"
  10  TEXT="#000000"
  11  LINK="#0000FF"
  12  VLINK="#000080"
  13  ALINK="#FF0000"
  14 >
  15 <!--#include virtual="header.html" -->
  16 <H1 ALIGN="CENTER">Apache's Handler Use</H1>
  17
  18 <H2>What is a Handler</H2>
  19
  20 <P>A "handler" is an internal Apache representation of the action to be
  21 performed when a file is called. Generally, files have implicit
  22 handlers, based on the file type. Normally, all files are simply
  23 served by the server, but certain file typed are "handled"
  24 separately. For example, you may use a type of
  25 "application/x-httpd-cgi" to invoke CGI scripts.</P>
  26
  27 <P>Apache 1.1 adds the additional ability to use handlers
  28 explicitly. Either based on filename extensions or on location, these
  29 handlers are unrelated to file type. This is advantageous both because
  30 it is a more elegant solution, but it also allows for both a type
  31 <STRONG>and</STRONG> a handler to be associated with a file (See also
  32 <A HREF="mod/mod_mime.html#multipleext">Files with Multiple Extensions</A>)
  33
  34 </P>
  35
  36 <P>Handlers can either be built into the server or to a module, or
  37 they can be added with the <A
  38 HREF="mod/mod_actions.html#action">Action</A> directive. The built-in
  39 handlers in the standard distribution are as follows:</P>
  40
  41 <UL>
  42 <LI><STRONG>default-handler</STRONG>:
  43     Send the file using the <CODE>default_handler()</CODE>, which is the
  44     handler used by default to handle static content.
  45     (core)
  46 <LI><STRONG>send-as-is</STRONG>:
  47     Send file with HTTP headers as is.
  48     (<A HREF="mod/mod_asis.html">mod_asis</A>)
  49 <LI><STRONG>cgi-script</STRONG>:
  50     Treat the file as a CGI script.
  51     (<A HREF="mod/mod_cgi.html">mod_cgi</A>)
  52 <LI><STRONG>imap-file</STRONG>:
  53     Imagemap rule file.
  54     (<A HREF="mod/mod_imap.html">mod_imap</A>)
  55 <LI><STRONG>server-info</STRONG>:
  56     Get the server's configuration information
  57     (<A HREF="mod/mod_info.html">mod_info</A>)
  58 <LI><STRONG>server-parsed</STRONG>:
  59     Parse for server-side includes
  60     (<A HREF="mod/mod_include.html">mod_include</A>)
  61 <LI><STRONG>server-status</STRONG>:
  62     Get the server's status report
  63     (<A HREF="mod/mod_status.html">mod_status</A>)
  64 <LI><STRONG>type-map</STRONG>:
  65     Parse as a type map file for content negotiation
  66     (<A HREF="mod/mod_negotiation.html">mod_negotiation</A>)
  67 </UL>
  68
  69 <P>
  70
  71 <H2>Directives</H2>
  72 <UL>
  73 <LI><A HREF="#addhandler">AddHandler</A>
  74 <LI><A HREF="#sethandler">SetHandler</A>
  75 </UL>
  76
  77 <HR>
  78
  79 <H2><A NAME="addhandler">AddHandler</A></H2>
  80
  81 <A
  82  HREF="mod/directive-dict.html#Syntax"
  83  REL="Help"
  84 ><STRONG>Syntax:</STRONG></A> AddHandler <EM>handler-name extension extension...</EM><BR>
  85 <A
  86  HREF="mod/directive-dict.html#Context"
  87  REL="Help"
  88 ><STRONG>Context:</STRONG></A> server config, virtual host, directory, .htaccess<BR>
  89 <A
  90  HREF="mod/directive-dict.html#Override"
  91  REL="Help"
  92 ><STRONG>Override:</STRONG></A> FileInfo<BR>
  93 <A
  94  HREF="mod/directive-dict.html#Status"
  95  REL="Help"
  96 ><STRONG>Status:</STRONG></A> Base<BR>
  97 <A
  98  HREF="mod/directive-dict.html#Module"
  99  REL="Help"
 100 ><STRONG>Module:</STRONG></A> mod_mime<BR>
 101 <A
 102  HREF="mod/directive-dict.html#Compatibility"
 103  REL="Help"
 104 ><STRONG>Compatibility:</STRONG></A> AddHandler is only available in Apache
 105 1.1 and later<P>
 106
 107 <P>AddHandler maps the filename extensions <EM>extension</EM> to the
 108 handler <EM>handler-name</EM>.  This mapping is added to any already
 109 in force, overriding any mappings that already exist for the same
 110 <EM>extension</EM>.
 111
 112 For example, to activate CGI scripts
 113 with the file extension "<CODE>.cgi</CODE>", you might use:
 114 <PRE>
 115     AddHandler cgi-script cgi
 116 </PRE>
 117
 118 <P>Once that has been put into your srm.conf or httpd.conf file, any
 119 file containing the "<CODE>.cgi</CODE>" extension will be treated as a
 120 CGI program.</P>
 121
 122 <P>
 123
 124 <STRONG>See also</STRONG>: <A HREF="mod/mod_mime.html#multipleext">Files with
 125 multiple extensions</A>
 126
 127 <HR>
 128
 129 <H2><A NAME="sethandler">SetHandler</A></H2>
 130
 131 <A
 132  HREF="mod/directive-dict.html#Syntax"
 133  REL="Help"
 134 ><STRONG>Syntax:</STRONG></A> SetHandler <EM>handler-name</EM><BR>
 135 <A
 136  HREF="mod/directive-dict.html#Context"
 137  REL="Help"
 138 ><STRONG>Context:</STRONG></A> directory, .htaccess<BR>
 139 <A
 140  HREF="mod/directive-dict.html#Status"
 141  REL="Help"
 142 ><STRONG>Status:</STRONG></A> Base<BR>
 143 <A
 144  HREF="mod/directive-dict.html#Module"
 145  REL="Help"
 146 ><STRONG>Module:</STRONG></A> mod_mime<BR>
 147 <A
 148  HREF="mod/directive-dict.html#Compatibility"
 149  REL="Help"
 150 ><STRONG>Compatibility:</STRONG></A> SetHandler is only available in Apache
 151 1.1 and later.<P>
 152
 153 <P>When placed into an <CODE>.htaccess</CODE> file or a
 154 <CODE>&lt;Directory&gt;</CODE> or <CODE>&lt;Location&gt;</CODE>
 155 section, this directive forces all matching files to be parsed through
 156 the handler given by <EM>handler-name</EM>. For example, if you had a
 157 directory you wanted to be parsed entirely as imagemap rule files,
 158 regardless of extension, you might put the following into an
 159 <CODE>.htaccess</CODE> file in that directory:
 160 <PRE>
 161     SetHandler imap-file
 162 </PRE>
 163
 164 <P>Another example: if you wanted to have the server display a status
 165 report whenever a URL of <CODE>http://servername/status</CODE> was
 166 called, you might put the following into access.conf:
 167 <PRE>
 168     &lt;Location /status&gt;
 169     SetHandler server-status
 170     &lt;/Location&gt;
 171 </PRE>
 172 <HR>
 173
 174 <H2>Programmer's Note</H2>
 175
 176 <P>In order to implement the handler features, an addition has been
 177 made to the <A HREF="misc/API.html">Apache API</A> that you may wish to
 178 make use of. Specifically, a new record has been added to the
 179 <CODE>request_rec</CODE> structure:</P>
 180 <PRE>
 181     char *handler
 182 </PRE>
 183 <P>If you wish to have your module engage a handler, you need only to
 184 set <CODE>r-&gt;handler</CODE> to the name of the handler at any time
 185 prior to the <CODE>invoke_handler</CODE> stage of the
 186 request. Handlers are implemented as they were before, albeit using
 187 the handler name instead of a content type. While it is not
 188 necessary, the naming convention for handlers is to use a
 189 dash-separated word, with no slashes, so as to not invade the media
 190 type name-space.</P>
 191
 192 <!--#include virtual="footer.html" -->
 193 </BODY>
 194 </HTML>
 195