API.html revision 57fad287a8bc02321dfbb74280dd4d6540482e09
9cb46bc62f22e0104f1b41a423b014c281ef5fc2Jakub Hrozek<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN">
9cb46bc62f22e0104f1b41a423b014c281ef5fc2Jakub Hrozek<!-- Background white, links blue (unvisited), navy (visited), red (active) -->
9cb46bc62f22e0104f1b41a423b014c281ef5fc2Jakub Hrozek BGCOLOR="#FFFFFF"
9cb46bc62f22e0104f1b41a423b014c281ef5fc2Jakub Hrozek TEXT="#000000"
9cb46bc62f22e0104f1b41a423b014c281ef5fc2Jakub Hrozek LINK="#0000FF"
9cb46bc62f22e0104f1b41a423b014c281ef5fc2Jakub Hrozek VLINK="#000080"
9cb46bc62f22e0104f1b41a423b014c281ef5fc2Jakub Hrozek ALINK="#FF0000"
9cb46bc62f22e0104f1b41a423b014c281ef5fc2Jakub Hrozek<!--#include virtual="header.html" -->
9cb46bc62f22e0104f1b41a423b014c281ef5fc2Jakub HrozekThese are some notes on the Apache API and the data structures you
9cb46bc62f22e0104f1b41a423b014c281ef5fc2Jakub Hrozekhave to deal with, <EM>etc.</EM> They are not yet nearly complete, but
9cb46bc62f22e0104f1b41a423b014c281ef5fc2Jakub Hrozekhopefully, they will help you get your bearings. Keep in mind that
9cb46bc62f22e0104f1b41a423b014c281ef5fc2Jakub Hrozekthe API is still subject to change as we gain experience with it.
9cb46bc62f22e0104f1b41a423b014c281ef5fc2Jakub Hrozek(See the TODO file for what <EM>might</EM> be coming). However,
9cb46bc62f22e0104f1b41a423b014c281ef5fc2Jakub Hrozekit will be easy to adapt modules to any changes that are made.
9cb46bc62f22e0104f1b41a423b014c281ef5fc2Jakub Hrozek(We have more modules to adapt than you do).
9cb46bc62f22e0104f1b41a423b014c281ef5fc2Jakub HrozekA few notes on general pedagogical style here. In the interest of
9cb46bc62f22e0104f1b41a423b014c281ef5fc2Jakub Hrozekconciseness, all structure declarations here are incomplete --- the
9cb46bc62f22e0104f1b41a423b014c281ef5fc2Jakub Hrozekreal ones have more slots that I'm not telling you about. For the
9cb46bc62f22e0104f1b41a423b014c281ef5fc2Jakub Hrozekmost part, these are reserved to one component of the server core or
9cb46bc62f22e0104f1b41a423b014c281ef5fc2Jakub Hrozekanother, and should be altered by modules with caution. However, in
9cb46bc62f22e0104f1b41a423b014c281ef5fc2Jakub Hrozeksome cases, they really are things I just haven't gotten around to
9cb46bc62f22e0104f1b41a423b014c281ef5fc2Jakub Hrozekyet. Welcome to the bleeding edge.<P>
9cb46bc62f22e0104f1b41a423b014c281ef5fc2Jakub HrozekFinally, here's an outline, to give you some bare idea of what's
9cb46bc62f22e0104f1b41a423b014c281ef5fc2Jakub Hrozekcoming up, and in what order:
5a4239490c7fb7d732180a9d40f27f0247c56631Jakub Hrozek <LI> <A HREF="#HMR">Handlers, Modules, and Requests</A>
5a4239490c7fb7d732180a9d40f27f0247c56631Jakub Hrozek <LI> <A HREF="#moduletour">A brief tour of a module</A>
9cb46bc62f22e0104f1b41a423b014c281ef5fc2Jakub Hrozek <LI> <A HREF="#req_tour">A brief tour of the <CODE>request_rec</CODE></A>
9cb46bc62f22e0104f1b41a423b014c281ef5fc2Jakub Hrozek <LI> <A HREF="#req_orig">Where request_rec structures come from</A>
9cb46bc62f22e0104f1b41a423b014c281ef5fc2Jakub Hrozek <LI> <A HREF="#req_return">Handling requests, declining, and returning error
9cb46bc62f22e0104f1b41a423b014c281ef5fc2Jakub Hrozek <LI> <A HREF="#resp_handlers">Special considerations for response handlers</A>
9cb46bc62f22e0104f1b41a423b014c281ef5fc2Jakub Hrozek <LI> <A HREF="#auth_handlers">Special considerations for authentication
9cb46bc62f22e0104f1b41a423b014c281ef5fc2Jakub Hrozek handlers</A>
9cb46bc62f22e0104f1b41a423b014c281ef5fc2Jakub Hrozek <LI> <A HREF="#log_handlers">Special considerations for logging handlers</A>
5a4239490c7fb7d732180a9d40f27f0247c56631Jakub Hrozek<LI> <A HREF="#pools">Resource allocation and resource pools</A>
5a4239490c7fb7d732180a9d40f27f0247c56631Jakub Hrozek<LI> <A HREF="#config">Configuration, commands and the like</A>
9cb46bc62f22e0104f1b41a423b014c281ef5fc2Jakub Hrozek <LI> <A HREF="#per-dir">Per-directory configuration structures</A>
9cb46bc62f22e0104f1b41a423b014c281ef5fc2Jakub Hrozek <LI> <A HREF="#servconf">Side notes --- per-server configuration,
9cb46bc62f22e0104f1b41a423b014c281ef5fc2Jakub HrozekWe begin with an overview of the basic concepts behind the
9cb46bc62f22e0104f1b41a423b014c281ef5fc2Jakub HrozekAPI, and how they are manifested in the code.
9cb46bc62f22e0104f1b41a423b014c281ef5fc2Jakub Hrozek<H3><A NAME="HMR">Handlers, Modules, and Requests</A></H3>
9cb46bc62f22e0104f1b41a423b014c281ef5fc2Jakub HrozekApache breaks down request handling into a series of steps, more or
9cb46bc62f22e0104f1b41a423b014c281ef5fc2Jakub Hrozekless the same way the Netscape server API does (although this API has
9cb46bc62f22e0104f1b41a423b014c281ef5fc2Jakub Hrozeka few more stages than NetSite does, as hooks for stuff I thought
a3c8390d19593b1e5277d95bfb4ab206d4785150Nikolai Kondrashovmight be useful in the future). These are:
9cb46bc62f22e0104f1b41a423b014c281ef5fc2Jakub Hrozek <LI> URI -> Filename translation
a3c8390d19593b1e5277d95bfb4ab206d4785150Nikolai Kondrashov <LI> Auth ID checking [is the user who they say they are?]
9cb46bc62f22e0104f1b41a423b014c281ef5fc2Jakub Hrozek <LI> Auth access checking [is the user authorized <EM>here</EM>?]
9cb46bc62f22e0104f1b41a423b014c281ef5fc2Jakub Hrozek <LI> Access checking other than auth
9cb46bc62f22e0104f1b41a423b014c281ef5fc2Jakub Hrozek <LI> Determining MIME type of the object requested
9cb46bc62f22e0104f1b41a423b014c281ef5fc2Jakub Hrozek <LI> `Fixups' --- there aren't any of these yet, but the phase is
a3c8390d19593b1e5277d95bfb4ab206d4785150Nikolai Kondrashov intended as a hook for possible extensions like
9cb46bc62f22e0104f1b41a423b014c281ef5fc2Jakub Hrozek <CODE>SetEnv</CODE>, which don't really fit well elsewhere.
9cb46bc62f22e0104f1b41a423b014c281ef5fc2Jakub Hrozek <LI> Actually sending a response back to the client.
9cb46bc62f22e0104f1b41a423b014c281ef5fc2Jakub Hrozek <LI> Logging the request
9cb46bc62f22e0104f1b41a423b014c281ef5fc2Jakub HrozekThese phases are handled by looking at each of a succession of
9cb46bc62f22e0104f1b41a423b014c281ef5fc2Jakub Hrozek<EM>modules</EM>, looking to see if each of them has a handler for the
9cb46bc62f22e0104f1b41a423b014c281ef5fc2Jakub Hrozekphase, and attempting invoking it if so. The handler can typically do
9cb46bc62f22e0104f1b41a423b014c281ef5fc2Jakub Hrozekone of three things:
9cb46bc62f22e0104f1b41a423b014c281ef5fc2Jakub Hrozek <LI> <EM>Handle</EM> the request, and indicate that it has done so
9cb46bc62f22e0104f1b41a423b014c281ef5fc2Jakub Hrozek by returning the magic constant <CODE>OK</CODE>.
9cb46bc62f22e0104f1b41a423b014c281ef5fc2Jakub Hrozek <LI> <EM>Decline</EM> to handle the request, by returning the magic
9cb46bc62f22e0104f1b41a423b014c281ef5fc2Jakub Hrozek integer constant <CODE>DECLINED</CODE>. In this case, the
4cae8609b513c267af11c0409bfe1d17d3a5da2fMichal Zidek server behaves in all respects as if the handler simply hadn't
9cb46bc62f22e0104f1b41a423b014c281ef5fc2Jakub Hrozek <LI> Signal an error, by returning one of the HTTP error codes.
9cb46bc62f22e0104f1b41a423b014c281ef5fc2Jakub Hrozek This terminates normal handling of the request, although an
9cb46bc62f22e0104f1b41a423b014c281ef5fc2Jakub Hrozek ErrorDocument may be invoked to try to mop up, and it will be
9cb46bc62f22e0104f1b41a423b014c281ef5fc2Jakub Hrozek logged in any case.
9cb46bc62f22e0104f1b41a423b014c281ef5fc2Jakub HrozekMost phases are terminated by the first module that handles them;
9cb46bc62f22e0104f1b41a423b014c281ef5fc2Jakub Hrozekhowever, for logging, `fixups', and non-access authentication
9cb46bc62f22e0104f1b41a423b014c281ef5fc2Jakub Hrozekchecking, all handlers always run (barring an error). Also, the
9cb46bc62f22e0104f1b41a423b014c281ef5fc2Jakub Hrozekresponse phase is unique in that modules may declare multiple handlers
9cb46bc62f22e0104f1b41a423b014c281ef5fc2Jakub Hrozekfor it, via a dispatch table keyed on the MIME type of the requested
9cb46bc62f22e0104f1b41a423b014c281ef5fc2Jakub Hrozekobject. Modules may declare a response-phase handler which can handle
9cb46bc62f22e0104f1b41a423b014c281ef5fc2Jakub Hrozek<EM>any</EM> request, by giving it the key <CODE>*/*</CODE> (<EM>i.e.</EM>, a
9cb46bc62f22e0104f1b41a423b014c281ef5fc2Jakub Hrozekwildcard MIME type specification). However, wildcard handlers are
9cb46bc62f22e0104f1b41a423b014c281ef5fc2Jakub Hrozekonly invoked if the server has already tried and failed to find a more
9cb46bc62f22e0104f1b41a423b014c281ef5fc2Jakub Hrozekspecific response handler for the MIME type of the requested object
9cb46bc62f22e0104f1b41a423b014c281ef5fc2Jakub Hrozek(either none existed, or they all declined).<P>
9cb46bc62f22e0104f1b41a423b014c281ef5fc2Jakub HrozekThe handlers themselves are functions of one argument (a
9cb46bc62f22e0104f1b41a423b014c281ef5fc2Jakub Hrozek<CODE>request_rec</CODE> structure. vide infra), which returns an
9cb46bc62f22e0104f1b41a423b014c281ef5fc2Jakub Hrozekinteger, as above.<P>
9cb46bc62f22e0104f1b41a423b014c281ef5fc2Jakub Hrozek<H3><A NAME="moduletour">A brief tour of a module</A></H3>
9cb46bc62f22e0104f1b41a423b014c281ef5fc2Jakub HrozekAt this point, we need to explain the structure of a module. Our
9cb46bc62f22e0104f1b41a423b014c281ef5fc2Jakub Hrozekcandidate will be one of the messier ones, the CGI module --- this
4cae8609b513c267af11c0409bfe1d17d3a5da2fMichal Zidekhandles both CGI scripts and the <CODE>ScriptAlias</CODE> config file
4cae8609b513c267af11c0409bfe1d17d3a5da2fMichal Zidekcommand. It's actually a great deal more complicated than most
4cae8609b513c267af11c0409bfe1d17d3a5da2fMichal Zidekmodules, but if we're going to have only one example, it might as well
4cae8609b513c267af11c0409bfe1d17d3a5da2fMichal Zidekbe the one with its fingers in every place.<P>
9cb46bc62f22e0104f1b41a423b014c281ef5fc2Jakub HrozekLet's begin with handlers. In order to handle the CGI scripts, the
9cb46bc62f22e0104f1b41a423b014c281ef5fc2Jakub Hrozekmodule declares a response handler for them. Because of
4cae8609b513c267af11c0409bfe1d17d3a5da2fMichal Zidek<CODE>ScriptAlias</CODE>, it also has handlers for the name
9cb46bc62f22e0104f1b41a423b014c281ef5fc2Jakub Hrozektranslation phase (to recognize <CODE>ScriptAlias</CODE>ed URIs), the
9cb46bc62f22e0104f1b41a423b014c281ef5fc2Jakub Hrozektype-checking phase (any <CODE>ScriptAlias</CODE>ed request is typed
4cae8609b513c267af11c0409bfe1d17d3a5da2fMichal Zidekas a CGI script).<P>
9cb46bc62f22e0104f1b41a423b014c281ef5fc2Jakub HrozekThe module needs to maintain some per (virtual)
4cae8609b513c267af11c0409bfe1d17d3a5da2fMichal Zidekserver information, namely, the <CODE>ScriptAlias</CODE>es in effect;
4cae8609b513c267af11c0409bfe1d17d3a5da2fMichal Zidekthe module structure therefore contains pointers to a functions which
9cb46bc62f22e0104f1b41a423b014c281ef5fc2Jakub Hrozekbuilds these structures, and to another which combines two of them (in
9cb46bc62f22e0104f1b41a423b014c281ef5fc2Jakub Hrozekcase the main server and a virtual server both have
9cb46bc62f22e0104f1b41a423b014c281ef5fc2Jakub HrozekFinally, this module contains code to handle the
9cb46bc62f22e0104f1b41a423b014c281ef5fc2Jakub Hrozek<CODE>ScriptAlias</CODE> command itself. This particular module only
9cb46bc62f22e0104f1b41a423b014c281ef5fc2Jakub Hrozekdeclares one command, but there could be more, so modules have
9cb46bc62f22e0104f1b41a423b014c281ef5fc2Jakub Hrozek<EM>command tables</EM> which declare their commands, and describe
9cb46bc62f22e0104f1b41a423b014c281ef5fc2Jakub Hrozekwhere they are permitted, and how they are to be invoked. <P>
9cb46bc62f22e0104f1b41a423b014c281ef5fc2Jakub HrozekA final note on the declared types of the arguments of some of these
9cb46bc62f22e0104f1b41a423b014c281ef5fc2Jakub Hrozekcommands: a <CODE>pool</CODE> is a pointer to a <EM>resource pool</EM>
9cb46bc62f22e0104f1b41a423b014c281ef5fc2Jakub Hrozekstructure; these are used by the server to keep track of the memory
9cb46bc62f22e0104f1b41a423b014c281ef5fc2Jakub Hrozekwhich has been allocated, files opened, <EM>etc.</EM>, either to service a
9cb46bc62f22e0104f1b41a423b014c281ef5fc2Jakub Hrozekparticular request, or to handle the process of configuring itself.
9cb46bc62f22e0104f1b41a423b014c281ef5fc2Jakub HrozekThat way, when the request is over (or, for the configuration pool,
9cb46bc62f22e0104f1b41a423b014c281ef5fc2Jakub Hrozekwhen the server is restarting), the memory can be freed, and the files
9cb46bc62f22e0104f1b41a423b014c281ef5fc2Jakub Hrozekclosed, <EM>en masse</EM>, without anyone having to write explicit code to
9cb46bc62f22e0104f1b41a423b014c281ef5fc2Jakub Hrozektrack them all down and dispose of them. Also, a
9cb46bc62f22e0104f1b41a423b014c281ef5fc2Jakub Hrozek<CODE>cmd_parms</CODE> structure contains various information about
9cb46bc62f22e0104f1b41a423b014c281ef5fc2Jakub Hrozekthe config file being read, and other status information, which is
9cb46bc62f22e0104f1b41a423b014c281ef5fc2Jakub Hrozeksometimes of use to the function which processes a config-file command
9cb46bc62f22e0104f1b41a423b014c281ef5fc2Jakub HrozekWith no further ado, the module itself:
9cb46bc62f22e0104f1b41a423b014c281ef5fc2Jakub Hrozek/* Declarations of handlers. */
9cb46bc62f22e0104f1b41a423b014c281ef5fc2Jakub Hrozekint translate_scriptalias (request_rec *);
9cb46bc62f22e0104f1b41a423b014c281ef5fc2Jakub Hrozekint type_scriptalias (request_rec *);
9cb46bc62f22e0104f1b41a423b014c281ef5fc2Jakub Hrozekint cgi_handler (request_rec *);
9cb46bc62f22e0104f1b41a423b014c281ef5fc2Jakub Hrozek/* Subsidiary dispatch table for response-phase handlers, by MIME type */
9cb46bc62f22e0104f1b41a423b014c281ef5fc2Jakub Hrozekhandler_rec cgi_handlers[] = {
9cb46bc62f22e0104f1b41a423b014c281ef5fc2Jakub Hrozek/* Declarations of routines to manipulate the module's configuration
9cb46bc62f22e0104f1b41a423b014c281ef5fc2Jakub Hrozek * info. Note that these are returned, and passed in, as void *'s;
9cb46bc62f22e0104f1b41a423b014c281ef5fc2Jakub Hrozek * the server core keeps track of them, but it doesn't, and can't,
9cb46bc62f22e0104f1b41a423b014c281ef5fc2Jakub Hrozek * know their internal structure.
9cb46bc62f22e0104f1b41a423b014c281ef5fc2Jakub Hrozekvoid *make_cgi_server_config (pool *);
9cb46bc62f22e0104f1b41a423b014c281ef5fc2Jakub Hrozekvoid *merge_cgi_server_config (pool *, void *, void *);
9cb46bc62f22e0104f1b41a423b014c281ef5fc2Jakub Hrozek/* Declarations of routines to handle config-file commands */
9cb46bc62f22e0104f1b41a423b014c281ef5fc2Jakub Hrozekextern char *script_alias(cmd_parms *, void *per_dir_config, char *fake,
9cb46bc62f22e0104f1b41a423b014c281ef5fc2Jakub Hrozek char *real);
9cb46bc62f22e0104f1b41a423b014c281ef5fc2Jakub Hrozekcommand_rec cgi_cmds[] = {
9cb46bc62f22e0104f1b41a423b014c281ef5fc2Jakub Hrozek{ "ScriptAlias", script_alias, NULL, RSRC_CONF, TAKE2,
9cb46bc62f22e0104f1b41a423b014c281ef5fc2Jakub Hrozek "a fakename and a realname"},
9cb46bc62f22e0104f1b41a423b014c281ef5fc2Jakub Hrozekmodule cgi_module = {
9cb46bc62f22e0104f1b41a423b014c281ef5fc2Jakub Hrozek STANDARD_MODULE_STUFF,
9cb46bc62f22e0104f1b41a423b014c281ef5fc2Jakub Hrozek NULL, /* initializer */
9cb46bc62f22e0104f1b41a423b014c281ef5fc2Jakub Hrozek NULL, /* dir config creator */
9cb46bc62f22e0104f1b41a423b014c281ef5fc2Jakub Hrozek NULL, /* dir merger --- default is to override */
9cb46bc62f22e0104f1b41a423b014c281ef5fc2Jakub Hrozek make_cgi_server_config, /* server config */
9cb46bc62f22e0104f1b41a423b014c281ef5fc2Jakub Hrozek merge_cgi_server_config, /* merge server config */
9cb46bc62f22e0104f1b41a423b014c281ef5fc2Jakub Hrozek cgi_cmds, /* command table */
9cb46bc62f22e0104f1b41a423b014c281ef5fc2Jakub Hrozek cgi_handlers, /* handlers */
9cb46bc62f22e0104f1b41a423b014c281ef5fc2Jakub Hrozek translate_scriptalias, /* filename translation */
9cb46bc62f22e0104f1b41a423b014c281ef5fc2Jakub Hrozek NULL, /* check_user_id */
9cb46bc62f22e0104f1b41a423b014c281ef5fc2Jakub Hrozek NULL, /* check auth */
9cb46bc62f22e0104f1b41a423b014c281ef5fc2Jakub Hrozek NULL, /* check access */
9cb46bc62f22e0104f1b41a423b014c281ef5fc2Jakub Hrozek type_scriptalias, /* type_checker */
9cb46bc62f22e0104f1b41a423b014c281ef5fc2Jakub Hrozek NULL, /* fixups */
9cb46bc62f22e0104f1b41a423b014c281ef5fc2Jakub Hrozek NULL, /* logger */
e15a9f81eb33066937710d7dee6976a3646d119cJakub Hrozek NULL /* header parser */
9cb46bc62f22e0104f1b41a423b014c281ef5fc2Jakub Hrozek<H2><A NAME="handlers">How handlers work</A></H2>
9cb46bc62f22e0104f1b41a423b014c281ef5fc2Jakub HrozekThe sole argument to handlers is a <CODE>request_rec</CODE> structure.
9cb46bc62f22e0104f1b41a423b014c281ef5fc2Jakub HrozekThis structure describes a particular request which has been made to
a3c8390d19593b1e5277d95bfb4ab206d4785150Nikolai Kondrashovthe server, on behalf of a client. In most cases, each connection to
9cb46bc62f22e0104f1b41a423b014c281ef5fc2Jakub Hrozekthe client generates only one <CODE>request_rec</CODE> structure.<P>
9cb46bc62f22e0104f1b41a423b014c281ef5fc2Jakub Hrozek<H3><A NAME="req_tour">A brief tour of the <CODE>request_rec</CODE></A></H3>
9cb46bc62f22e0104f1b41a423b014c281ef5fc2Jakub HrozekThe <CODE>request_rec</CODE> contains pointers to a resource pool
9cb46bc62f22e0104f1b41a423b014c281ef5fc2Jakub Hrozekwhich will be cleared when the server is finished handling the
9cb46bc62f22e0104f1b41a423b014c281ef5fc2Jakub Hrozekrequest; to structures containing per-server and per-connection
9cb46bc62f22e0104f1b41a423b014c281ef5fc2Jakub Hrozekinformation, and most importantly, information on the request itself.<P>
9cb46bc62f22e0104f1b41a423b014c281ef5fc2Jakub HrozekThe most important such information is a small set of character
9cb46bc62f22e0104f1b41a423b014c281ef5fc2Jakub Hrozekstrings describing attributes of the object being requested, including
9cb46bc62f22e0104f1b41a423b014c281ef5fc2Jakub Hrozekits URI, filename, content-type and content-encoding (these being filled
9cb46bc62f22e0104f1b41a423b014c281ef5fc2Jakub Hrozekin by the translation and type-check handlers which handle the
9cb46bc62f22e0104f1b41a423b014c281ef5fc2Jakub Hrozekrequest, respectively). <P>
9cb46bc62f22e0104f1b41a423b014c281ef5fc2Jakub HrozekOther commonly used data items are tables giving the MIME headers on
9cb46bc62f22e0104f1b41a423b014c281ef5fc2Jakub Hrozekthe client's original request, MIME headers to be sent back with the
9cb46bc62f22e0104f1b41a423b014c281ef5fc2Jakub Hrozekresponse (which modules can add to at will), and environment variables
9cb46bc62f22e0104f1b41a423b014c281ef5fc2Jakub Hrozekfor any subprocesses which are spawned off in the course of servicing
9cb46bc62f22e0104f1b41a423b014c281ef5fc2Jakub Hrozekthe request. These tables are manipulated using the
9cb46bc62f22e0104f1b41a423b014c281ef5fc2Jakub Hrozek<CODE>ap_table_get</CODE> and <CODE>ap_table_set</CODE> routines. <P>
e15a9f81eb33066937710d7dee6976a3646d119cJakub Hrozek Note that the <SAMP>Content-type</SAMP> header value <EM>cannot</EM> be
e45b81abe0aafa8a04bd64ac31a2fac63ce675b7Jakub Hrozek set by module content-handlers using the <SAMP>ap_table_*()</SAMP>
9cb46bc62f22e0104f1b41a423b014c281ef5fc2Jakub Hrozek routines. Rather, it is set by pointing the <SAMP>content_type</SAMP>
9cb46bc62f22e0104f1b41a423b014c281ef5fc2Jakub Hrozek field in the <SAMP>request_rec</SAMP> structure to an appropriate
9cb46bc62f22e0104f1b41a423b014c281ef5fc2Jakub HrozekFinally, there are pointers to two data structures which, in turn,
9cb46bc62f22e0104f1b41a423b014c281ef5fc2Jakub Hrozekpoint to per-module configuration structures. Specifically, these
9cb46bc62f22e0104f1b41a423b014c281ef5fc2Jakub Hrozekhold pointers to the data structures which the module has built to
9cb46bc62f22e0104f1b41a423b014c281ef5fc2Jakub Hrozekdescribe the way it has been configured to operate in a given
9cb46bc62f22e0104f1b41a423b014c281ef5fc2Jakub Hrozek<CODE><Directory></CODE> sections), for private data it has
9cb46bc62f22e0104f1b41a423b014c281ef5fc2Jakub Hrozekbuilt in the course of servicing the request (so modules' handlers for
9cb46bc62f22e0104f1b41a423b014c281ef5fc2Jakub Hrozekone phase can pass `notes' to their handlers for other phases). There
9cb46bc62f22e0104f1b41a423b014c281ef5fc2Jakub Hrozekis another such configuration vector in the <CODE>server_rec</CODE>
9cb46bc62f22e0104f1b41a423b014c281ef5fc2Jakub Hrozekdata structure pointed to by the <CODE>request_rec</CODE>, which
9cb46bc62f22e0104f1b41a423b014c281ef5fc2Jakub Hrozekcontains per (virtual) server configuration data.<P>
9cb46bc62f22e0104f1b41a423b014c281ef5fc2Jakub HrozekHere is an abridged declaration, giving the fields most commonly used:<P>
9cb46bc62f22e0104f1b41a423b014c281ef5fc2Jakub Hrozekstruct request_rec {
9cb46bc62f22e0104f1b41a423b014c281ef5fc2Jakub Hrozek conn_rec *connection;
9cb46bc62f22e0104f1b41a423b014c281ef5fc2Jakub Hrozek server_rec *server;
9cb46bc62f22e0104f1b41a423b014c281ef5fc2Jakub Hrozek /* What object is being requested */
9cb46bc62f22e0104f1b41a423b014c281ef5fc2Jakub Hrozek char *filename;
9cb46bc62f22e0104f1b41a423b014c281ef5fc2Jakub Hrozek char *path_info;
9cb46bc62f22e0104f1b41a423b014c281ef5fc2Jakub Hrozek char *args; /* QUERY_ARGS, if any */
9cb46bc62f22e0104f1b41a423b014c281ef5fc2Jakub Hrozek struct stat finfo; /* Set by server core;
9cb46bc62f22e0104f1b41a423b014c281ef5fc2Jakub Hrozek * st_mode set to zero if no such file */
a7401bf72db3a6eb62b1628f9dd141f7118e3510Pavel Březina char *content_type;
a7401bf72db3a6eb62b1628f9dd141f7118e3510Pavel Březina char *content_encoding;
a7401bf72db3a6eb62b1628f9dd141f7118e3510Pavel Březina /* MIME header environments, in and out. Also, an array containing
a7401bf72db3a6eb62b1628f9dd141f7118e3510Pavel Březina * environment variables to be passed to subprocesses, so people can
a7401bf72db3a6eb62b1628f9dd141f7118e3510Pavel Březina * write modules to add to that environment.
a7401bf72db3a6eb62b1628f9dd141f7118e3510Pavel Březina * The difference between headers_out and err_headers_out is that
a7401bf72db3a6eb62b1628f9dd141f7118e3510Pavel Březina * the latter are printed even on error, and persist across internal
a7401bf72db3a6eb62b1628f9dd141f7118e3510Pavel Březina * redirects (so the headers printed for ErrorDocument handlers will
a7401bf72db3a6eb62b1628f9dd141f7118e3510Pavel Březina * have them).
9cb46bc62f22e0104f1b41a423b014c281ef5fc2Jakub Hrozek table *headers_in;
9cb46bc62f22e0104f1b41a423b014c281ef5fc2Jakub Hrozek table *headers_out;
9cb46bc62f22e0104f1b41a423b014c281ef5fc2Jakub Hrozek table *err_headers_out;
9cb46bc62f22e0104f1b41a423b014c281ef5fc2Jakub Hrozek table *subprocess_env;
9cb46bc62f22e0104f1b41a423b014c281ef5fc2Jakub Hrozek /* Info about the request itself... */
5a4239490c7fb7d732180a9d40f27f0247c56631Jakub Hrozek int header_only; /* HEAD request, as opposed to GET */
5a4239490c7fb7d732180a9d40f27f0247c56631Jakub Hrozek char *protocol; /* Protocol, as given to us, or HTTP/0.9 */
5a4239490c7fb7d732180a9d40f27f0247c56631Jakub Hrozek char *method; /* GET, HEAD, POST, <EM>etc.</EM> */
5a4239490c7fb7d732180a9d40f27f0247c56631Jakub Hrozek int method_number; /* M_GET, M_POST, <EM>etc.</EM> */
5a4239490c7fb7d732180a9d40f27f0247c56631Jakub Hrozek /* Info for logging */
5a4239490c7fb7d732180a9d40f27f0247c56631Jakub Hrozek char *the_request;
5a4239490c7fb7d732180a9d40f27f0247c56631Jakub Hrozek int bytes_sent;
5a4239490c7fb7d732180a9d40f27f0247c56631Jakub Hrozek /* A flag which modules can set, to indicate that the data being
5a4239490c7fb7d732180a9d40f27f0247c56631Jakub Hrozek * returned is volatile, and clients should be told not to cache it.
5a4239490c7fb7d732180a9d40f27f0247c56631Jakub Hrozek int no_cache;
5a4239490c7fb7d732180a9d40f27f0247c56631Jakub Hrozek /* Various other config info which may change with .htaccess files
5a4239490c7fb7d732180a9d40f27f0247c56631Jakub Hrozek * These are config vectors, with one void* pointer for each module
5a4239490c7fb7d732180a9d40f27f0247c56631Jakub Hrozek * (the thing pointed to being the module's business).
5a4239490c7fb7d732180a9d40f27f0247c56631Jakub Hrozek void *per_dir_config; /* Options set in config files, <EM>etc.</EM> */
5a4239490c7fb7d732180a9d40f27f0247c56631Jakub Hrozek void *request_config; /* Notes on *this* request */
3bd78eb2faf09635b8d307e4440ccb1420f80716Jakub Hrozek<H3><A NAME="req_orig">Where request_rec structures come from</A></H3>
3bd78eb2faf09635b8d307e4440ccb1420f80716Jakub HrozekMost <CODE>request_rec</CODE> structures are built by reading an HTTP
5a4239490c7fb7d732180a9d40f27f0247c56631Jakub Hrozekrequest from a client, and filling in the fields. However, there are
5a4239490c7fb7d732180a9d40f27f0247c56631Jakub Hrozeka few exceptions:
5a4239490c7fb7d732180a9d40f27f0247c56631Jakub Hrozek <LI> If the request is to an imagemap, a type map (<EM>i.e.</EM>, a
5a4239490c7fb7d732180a9d40f27f0247c56631Jakub Hrozek <CODE>*.var</CODE> file), or a CGI script which returned a
5a4239490c7fb7d732180a9d40f27f0247c56631Jakub Hrozek local `Location:', then the resource which the user requested
5a4239490c7fb7d732180a9d40f27f0247c56631Jakub Hrozek is going to be ultimately located by some URI other than what
5a4239490c7fb7d732180a9d40f27f0247c56631Jakub Hrozek the client originally supplied. In this case, the server does
5a4239490c7fb7d732180a9d40f27f0247c56631Jakub Hrozek an <EM>internal redirect</EM>, constructing a new
5a4239490c7fb7d732180a9d40f27f0247c56631Jakub Hrozek <CODE>request_rec</CODE> for the new URI, and processing it
9cb46bc62f22e0104f1b41a423b014c281ef5fc2Jakub Hrozek almost exactly as if the client had requested the new URI
9cb46bc62f22e0104f1b41a423b014c281ef5fc2Jakub Hrozek directly. <P>
5a4239490c7fb7d732180a9d40f27f0247c56631Jakub Hrozek <LI> If some handler signaled an error, and an
5a4239490c7fb7d732180a9d40f27f0247c56631Jakub Hrozek <CODE>ErrorDocument</CODE> is in scope, the same internal
5a4239490c7fb7d732180a9d40f27f0247c56631Jakub Hrozek redirect machinery comes into play.<P>
5a4239490c7fb7d732180a9d40f27f0247c56631Jakub Hrozek <LI> Finally, a handler occasionally needs to investigate `what
5a4239490c7fb7d732180a9d40f27f0247c56631Jakub Hrozek would happen if' some other request were run. For instance,
9cb46bc62f22e0104f1b41a423b014c281ef5fc2Jakub Hrozek the directory indexing module needs to know what MIME type
9cb46bc62f22e0104f1b41a423b014c281ef5fc2Jakub Hrozek would be assigned to a request for each directory entry, in
9cb46bc62f22e0104f1b41a423b014c281ef5fc2Jakub Hrozek order to figure out what icon to use.<P>
5a4239490c7fb7d732180a9d40f27f0247c56631Jakub Hrozek Such handlers can construct a <EM>sub-request</EM>, using the
a95c006f748fa9df0dd81509b51974133d2786afLukas Slebodnik functions <CODE>ap_sub_req_lookup_file</CODE> and
a95c006f748fa9df0dd81509b51974133d2786afLukas Slebodnik <CODE>ap_sub_req_lookup_uri</CODE>; this constructs a new
9cb46bc62f22e0104f1b41a423b014c281ef5fc2Jakub Hrozek <CODE>request_rec</CODE> structure and processes it as you
5a4239490c7fb7d732180a9d40f27f0247c56631Jakub Hrozek would expect, up to but not including the point of actually
5a4239490c7fb7d732180a9d40f27f0247c56631Jakub Hrozek sending a response. (These functions skip over the access
5a4239490c7fb7d732180a9d40f27f0247c56631Jakub Hrozek checks if the sub-request is for a file in the same directory
5a4239490c7fb7d732180a9d40f27f0247c56631Jakub Hrozek as the original request).<P>
5a4239490c7fb7d732180a9d40f27f0247c56631Jakub Hrozek (Server-side includes work by building sub-requests and then
5a4239490c7fb7d732180a9d40f27f0247c56631Jakub Hrozek actually invoking the response handler for them, via the
9cb46bc62f22e0104f1b41a423b014c281ef5fc2Jakub Hrozek<H3><A NAME="req_return">Handling requests, declining, and returning error
9cb46bc62f22e0104f1b41a423b014c281ef5fc2Jakub HrozekAs discussed above, each handler, when invoked to handle a particular
9cb46bc62f22e0104f1b41a423b014c281ef5fc2Jakub Hrozek<CODE>request_rec</CODE>, has to return an <CODE>int</CODE> to
9cb46bc62f22e0104f1b41a423b014c281ef5fc2Jakub Hrozekindicate what happened. That can either be
9cb46bc62f22e0104f1b41a423b014c281ef5fc2Jakub Hrozek <LI> OK --- the request was handled successfully. This may or may
9cb46bc62f22e0104f1b41a423b014c281ef5fc2Jakub Hrozek not terminate the phase.
9cb46bc62f22e0104f1b41a423b014c281ef5fc2Jakub Hrozek <LI> DECLINED --- no erroneous condition exists, but the module
5a4239490c7fb7d732180a9d40f27f0247c56631Jakub Hrozek declines to handle the phase; the server tries to find another.
9cb46bc62f22e0104f1b41a423b014c281ef5fc2Jakub Hrozek <LI> an HTTP error code, which aborts handling of the request.
9cb46bc62f22e0104f1b41a423b014c281ef5fc2Jakub HrozekNote that if the error code returned is <CODE>REDIRECT</CODE>, then
9cb46bc62f22e0104f1b41a423b014c281ef5fc2Jakub Hrozekthe module should put a <CODE>Location</CODE> in the request's
5a4239490c7fb7d732180a9d40f27f0247c56631Jakub Hrozek<CODE>headers_out</CODE>, to indicate where the client should be
9cb46bc62f22e0104f1b41a423b014c281ef5fc2Jakub Hrozek<H3><A NAME="resp_handlers">Special considerations for response
9cb46bc62f22e0104f1b41a423b014c281ef5fc2Jakub HrozekHandlers for most phases do their work by simply setting a few fields
9cb46bc62f22e0104f1b41a423b014c281ef5fc2Jakub Hrozekin the <CODE>request_rec</CODE> structure (or, in the case of access
9cb46bc62f22e0104f1b41a423b014c281ef5fc2Jakub Hrozekcheckers, simply by returning the correct error code). However,
9cb46bc62f22e0104f1b41a423b014c281ef5fc2Jakub Hrozekresponse handlers have to actually send a request back to the client. <P>
9cb46bc62f22e0104f1b41a423b014c281ef5fc2Jakub HrozekThey should begin by sending an HTTP response header, using the
9cb46bc62f22e0104f1b41a423b014c281ef5fc2Jakub Hrozekfunction <CODE>ap_send_http_header</CODE>. (You don't have to do
9cb46bc62f22e0104f1b41a423b014c281ef5fc2Jakub Hrozekanything special to skip sending the header for HTTP/0.9 requests; the
9cb46bc62f22e0104f1b41a423b014c281ef5fc2Jakub Hrozekfunction figures out on its own that it shouldn't do anything). If
9cb46bc62f22e0104f1b41a423b014c281ef5fc2Jakub Hrozekthe request is marked <CODE>header_only</CODE>, that's all they should
5a4239490c7fb7d732180a9d40f27f0247c56631Jakub Hrozekdo; they should return after that, without attempting any further
9cb46bc62f22e0104f1b41a423b014c281ef5fc2Jakub HrozekOtherwise, they should produce a request body which responds to the
9cb46bc62f22e0104f1b41a423b014c281ef5fc2Jakub Hrozekclient as appropriate. The primitives for this are <CODE>ap_rputc</CODE>
9cb46bc62f22e0104f1b41a423b014c281ef5fc2Jakub Hrozekand <CODE>ap_rprintf</CODE>, for internally generated output, and
9cb46bc62f22e0104f1b41a423b014c281ef5fc2Jakub Hrozek<CODE>ap_send_fd</CODE>, to copy the contents of some <CODE>FILE *</CODE>
9cb46bc62f22e0104f1b41a423b014c281ef5fc2Jakub Hrozekstraight to the client. <P>
9cb46bc62f22e0104f1b41a423b014c281ef5fc2Jakub HrozekAt this point, you should more or less understand the following piece
9cb46bc62f22e0104f1b41a423b014c281ef5fc2Jakub Hrozekof code, which is the handler which handles <CODE>GET</CODE> requests
9cb46bc62f22e0104f1b41a423b014c281ef5fc2Jakub Hrozekwhich have no more specific handler; it also shows how conditional
9cb46bc62f22e0104f1b41a423b014c281ef5fc2Jakub Hrozek<CODE>GET</CODE>s can be handled, if it's desirable to do so in a
9cb46bc62f22e0104f1b41a423b014c281ef5fc2Jakub Hrozekparticular response handler --- <CODE>ap_set_last_modified</CODE> checks
9cb46bc62f22e0104f1b41a423b014c281ef5fc2Jakub Hrozekagainst the <CODE>If-modified-since</CODE> value supplied by the
9cb46bc62f22e0104f1b41a423b014c281ef5fc2Jakub Hrozekclient, if any, and returns an appropriate code (which will, if
9cb46bc62f22e0104f1b41a423b014c281ef5fc2Jakub Hrozeknonzero, be USE_LOCAL_COPY). No similar considerations apply for
9cb46bc62f22e0104f1b41a423b014c281ef5fc2Jakub Hrozek<CODE>ap_set_content_length</CODE>, but it returns an error code for
5a4239490c7fb7d732180a9d40f27f0247c56631Jakub Hrozekint default_handler (request_rec *r)
9cb46bc62f22e0104f1b41a423b014c281ef5fc2Jakub Hrozek int errstatus;
9cb46bc62f22e0104f1b41a423b014c281ef5fc2Jakub Hrozek if (r->method_number != M_GET) return DECLINED;
5a4239490c7fb7d732180a9d40f27f0247c56631Jakub Hrozek if (r->finfo.st_mode == 0) return NOT_FOUND;
5a4239490c7fb7d732180a9d40f27f0247c56631Jakub Hrozek if ((errstatus = ap_set_content_length (r, r->finfo.st_size))
5a4239490c7fb7d732180a9d40f27f0247c56631Jakub Hrozek || (errstatus = ap_set_last_modified (r, r->finfo.st_mtime)))
9cb46bc62f22e0104f1b41a423b014c281ef5fc2Jakub Hrozek return errstatus;
if (S_ISDIR(r->finfo.st_mode)) {
<!--#include virtual="footer.html" -->