📄 api.html
字号:
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<meta http-equiv="Content-Type" content="text/html; charset=gb2312" />
<meta name="keywords" content="Apache, 中文, 手册, 中文版, 中文手册, 中文版手册, 参考手册, 中文参考手册, 金步国" />
<meta name="description" content="Apache 2.2 中文版参考手册" />
<meta name="author" content="金步国" />
<link href="../style/css/manual-zip.css" rel="stylesheet" media="all" type="text/css" title="Main stylesheet" />
<link href="../style/css/manual-zip-100pc.css" rel="alternate stylesheet" media="all" type="text/css" title="No Sidebar - Default font size" />
<link href="../style/css/manual-print.css" rel="stylesheet" media="print" type="text/css" />
<title>Apache 1.3 API 备忘录 － Apache 2.2 中文版参考手册</title>
</head>
<body id="manual-page"><div id="page-header">
<p class="menu"><a href="../mod/index.html">模块索引</a> | <a href="../mod/directives.html">指令索引</a> | <a href="../faq/index.html">常见问题</a> | <a href="../glossary.html">词汇表</a> | <a href="../sitemap.html">站点导航</a></p><p class="apache">Apache HTTP Server 版本2.2</p><img alt="" src="../images/feather.gif" /></div>
<div class="up"><a href="./index.html"><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/">文档</a> > <a href="../index.html">版本2.2</a> > <a href="./index.html">开发者文档</a></div>
<div id="translation-info"> <a href="../translator_announcement.html#thanks">致谢</a> | <a href="../translator_announcement.html#announcement">译者声明</a> | 本篇译者：<<a href="../translator_announcement.html#join">虚位以待</a>> | 本篇译稿完成时间：?年?月?日 | <a href="../translator_announcement.html#last_new">获取最新版本</a></div>
<div id="page-content"><div id="preamble"><h1>Apache 1.3 API notes</h1>
<div class="warning"><h3>Warning</h3>
<p>This document has not been updated to take into account changes made
in the 2.0 version of the Apache HTTP Server. Some of the information may
still be relevant, but please use it with care.</p>
</div>
<p>These are some notes on the Apache API and the data structures you have
to deal with, <em>etc.</em> They are not yet nearly complete, but hopefully,
they will help you get your bearings. Keep in mind that the API is still
subject to change as we gain experience with it. (See the TODO file for
what <em>might</em> be coming). However, it will be easy to adapt modules
to any changes that are made. (We have more modules to adapt than you
do).</p>
<p>A few notes on general pedagogical style here. In the interest of
conciseness, all structure declarations here are incomplete -- the real
ones have more slots that I'm not telling you about. For the most part,
these are reserved to one component of the server core or another, and
should be altered by modules with caution. However, in some cases, they
really are things I just haven't gotten around to yet. Welcome to the
bleeding edge.</p>
<p>Finally, here's an outline, to give you some bare idea of what's coming
up, and in what order:</p>
<ul>
<li>
<a href="#basics">Basic concepts.</a>
<ul>
<li><a href="#HMR">Handlers, Modules, and
Requests</a></li>
<li><a href="#moduletour">A brief tour of a
module</a></li>
</ul>
</li>
<li>
<a href="#handlers">How handlers work</a>
<ul>
<li><a href="#req_tour">A brief tour of the
<code>request_rec</code></a></li>
<li><a href="#req_orig">Where request_rec structures come
from</a></li>
<li><a href="#req_return">Handling requests, declining,
and returning error codes</a></li>
<li><a href="#resp_handlers">Special considerations for
response handlers</a></li>
<li><a href="#auth_handlers">Special considerations for
authentication handlers</a></li>
<li><a href="#log_handlers">Special considerations for
logging handlers</a></li>
</ul>
</li>
<li><a href="#pools">Resource allocation and resource
pools</a></li>
<li>
<a href="#config">Configuration, commands and the like</a>
<ul>
<li><a href="#per-dir">Per-directory configuration
structures</a></li>
<li><a href="#commands">Command handling</a></li>
<li><a href="#servconf">Side notes --- per-server
configuration, virtual servers, <em>etc</em>.</a></li>
</ul>
</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="basics" id="basics">Basic concepts</a></h2>
<p>We begin with an overview of the basic concepts behind the API, and how
they are manifested in the code.</p>
<h3><a name="HMR" id="HMR">Handlers, Modules, and Requests</a></h3>
<p>Apache breaks down request handling into a series of steps, more or
less the same way the Netscape server API does (although this API has a
few more stages than NetSite does, as hooks for stuff I thought might be
useful in the future). These are:</p>
<ul>
<li>URI -> Filename translation</li>
<li>Auth ID checking [is the user who they say they are?]</li>
<li>Auth access checking [is the user authorized <em>here</em>?]</li>
<li>Access checking other than auth</li>
<li>Determining MIME type of the object requested</li>
<li>'Fixups' -- there aren't any of these yet, but the phase is intended
as a hook for possible extensions like <code class="directive"><a href="../mod/mod_env.html#setenv">SetEnv</a></code>, which don't really fit well elsewhere.</li>
<li>Actually sending a response back to the client.</li>
<li>Logging the request</li>
</ul>
<p>These phases are handled by looking at each of a succession of
<em>modules</em>, looking to see if each of them has a handler for the
phase, and attempting invoking it if so. The handler can typically do one
of three things:</p>
<ul>
<li><em>Handle</em> the request, and indicate that it has done so by
returning the magic constant <code>OK</code>.</li>
<li><em>Decline</em> to handle the request, by returning the magic integer
constant <code>DECLINED</code>. In this case, the server behaves in all
respects as if the handler simply hadn't been there.</li>
<li>Signal an error, by returning one of the HTTP error codes. This
terminates normal handling of the request, although an ErrorDocument may
be invoked to try to mop up, and it will be logged in any case.</li>
</ul>
<p>Most phases are terminated by the first module that handles them;
however, for logging, 'fixups', and non-access authentication checking,
all handlers always run (barring an error). Also, the response phase is
unique in that modules may declare multiple handlers for it, via a
dispatch table keyed on the MIME type of the requested object. Modules may
declare a response-phase handler which can handle <em>any</em> request,
by giving it the key <code>*/*</code> (<em>i.e.</em>, a wildcard MIME type
specification). However, wildcard handlers are only invoked if the server
has already tried and failed to find a more specific response handler for
the MIME type of the requested object (either none existed, or they all
declined).</p>
<p>The handlers themselves are functions of one argument (a
<code>request_rec</code> structure. vide infra), which returns an integer,
as above.</p>
<h3><a name="moduletour" id="moduletour">A brief tour of a module</a></h3>
<p>At this point, we need to explain the structure of a module. Our
candidate will be one of the messier ones, the CGI module -- this handles
both CGI scripts and the <code class="directive"><a href="../mod/mod_alias.html#scriptalias">ScriptAlias</a></code> config file command. It's actually a great deal
more complicated than most modules, but if we're going to have only one
example, it might as well be the one with its fingers in every place.</p>
<p>Let's begin with handlers. In order to handle the CGI scripts, the
module declares a response handler for them. Because of <code class="directive"><a href="../mod/mod_alias.html#scriptalias">ScriptAlias</a></code>, it also has handlers for the
name translation phase (to recognize <code class="directive"><a href="../mod/mod_alias.html#scriptalias">ScriptAlias</a></code>ed URIs), the type-checking phase (any
<code class="directive"><a href="../mod/mod_alias.html#scriptalias">ScriptAlias</a></code>ed request is typed
as a CGI script).</p>
<p>The module needs to maintain some per (virtual) server information,
namely, the <code class="directive"><a href="../mod/mod_alias.html#scriptalias">ScriptAlias</a></code>es in
effect; the module structure therefore contains pointers to a functions
which builds these structures, and to another which combines two of them
(in case the main server and a virtual server both have <code class="directive"><a href="../mod/mod_alias.html#scriptalias">ScriptAlias</a></code>es declared).</p>
<p>Finally, this module contains code to handle the <code class="directive"><a href="../mod/mod_alias.html#scriptalias">ScriptAlias</a></code> command itself. This particular
module only declares one command, but there could be more, so modules have
<em>command tables</em> which declare their commands, and describe where
they are permitted, and how they are to be invoked.</p>
<p>A final note on the declared types of the arguments of some of these
commands: a <code>pool</code> is a pointer to a <em>resource pool</em>
structure; these are used by the server to keep track of the memory which
has been allocated, files opened, <em>etc.</em>, either to service a
particular request, or to handle the process of configuring itself. That
way, when the request is over (or, for the configuration pool, when the
server is restarting), the memory can be freed, and the files closed,
<em>en masse</em>, without anyone having to write explicit code to track
them all down and dispose of them. Also, a <code>cmd_parms</code>
structure contains various information about the config file being read,
and other status information, which is sometimes of use to the function
which processes a config-file command (such as <code class="directive"><a href="../mod/mod_alias.html#scriptalias">ScriptAlias</a></code>). With no further ado, the
module itself:</p>
<div class="example"><p><code>
/* Declarations of handlers. */<br />
<br />
int translate_scriptalias (request_rec *);<br />
int type_scriptalias (request_rec *);<br />
int cgi_handler (request_rec *);<br />
<br />
/* Subsidiary dispatch table for response-phase <br />
* handlers, by MIME type */<br />
<br />
handler_rec cgi_handlers[] = {<br />
<span class="indent">
{ "application/x-httpd-cgi", cgi_handler },<br />
{ NULL }<br />
</span>
};<br />
<br />
/* Declarations of routines to manipulate the <br />
* module's configuration info. Note that these are<br />
* returned, and passed in, as void *'s; the server<br />
* core keeps track of them, but it doesn't, and can't,<br />
* know their internal structure.<br />
*/<br />
<br />
void *make_cgi_server_config (pool *);<br />
void *merge_cgi_server_config (pool *, void *, void *);<br />
<br />
/* Declarations of routines to handle config-file commands */<br />
<br />
extern char *script_alias(cmd_parms *, void *per_dir_config, char *fake,
char *real);<br />
<br />
command_rec cgi_cmds[] = {<br />
<span class="indent">
{ "ScriptAlias", script_alias, NULL, RSRC_CONF, TAKE2,<br />
<span class="indent">"a fakename and a realname"},<br /></span>
{ NULL }<br />
</span>
};<br />
<br />
module cgi_module = {
</code></p><pre> STANDARD_MODULE_STUFF,
NULL, /* initializer */
NULL, /* dir config creator */
NULL, /* dir merger */
make_cgi_server_config, /* server config */
⌨️ 快捷键说明
复制代码
Ctrl + C
搜索代码
Ctrl + F
全屏模式
F11
切换主题
Ctrl + Shift + D
显示快捷键
?
增大字号
Ctrl + =
减小字号
Ctrl + -