Apache指令范围适用原则和Apache配置钩子

When the server is processing configuration directives and it encounters one defined by your module, it will call from one to three functions listed in your module structure. 当服务器正在处理配置指令并且遇到一个你定义模块里的指令,它会从你的模块结构中调用一到三个函数。

1. Module configuration record creation routine 模块配置记录创建程序
2. Directive handler 指令处理程序
3. Module configuration record merging routine 模块配置记录合并程序

All configuration information in Apache is managed in a set of tree structures, containing module configuration records. When the server encounters one of your module’s directives in its processing of its configuration instructions, it will check to see if it already has a module configuration record for the current scope; if it doesn’t, then it calls your module’s record-creation routine (if you have declared one). The routine in your module that’s responsible for processing the directive (checking to see if it’s valid, and saving its meaning for later) typically stores information about the directive in the module record that’s passed.

在Apache中所有的配置信息在一组树形结构中被管理,包含模块配置记录。当服务器遇到处理的模块指令之一，,它会检查是否有当前范围的模块配置记录，如果没有,那么调用你的模块记录创建程序(如果你已经声明)。你的模块中的程序是负责处理指令（检查，看它是否有效，并保留它供以后使用)通常存储有关指令信息通过该模块的记录

Once Apache has finished processing all of your module’s directives in a particular scope, it calls one of your merge functions to handle the inheritance issues. The merge routine is given pointers to the module record for the current scope and for the closest ancestor scope for which there is a record. It’s up to your
merge routine to figure out the correct settings that apply to the current scope, based upon the directives that were processed specific to it and the inheritance of any settings from a broader scope (e.g., from higher up the directory tree). Your merge routine is responsible for creating a new module record, filling it in with the merged settings, and returning it to the server, which then links it into the chain.

Apache一旦在一个特定的范围中完成模块所有指令的处理,它调用合并函数中的一个来处理继承问题。合并程序得到模块记录指针，记录包含当前范围和最近的已记录的继承范围。这取决于你的合并程序是否找出适用于当前范围内的正确设置，根据特定的指令来处理,并从更广泛的范围中继承(如，从一个更高的目录树)。你的合并程序负责创建一个新的模块记录,在合并设置中填充它,并返回给服务器,然后链接到链。

If the process should happen to occur again at a lower level (a narrower scope), the ‘parent’ module record that will be passed in will be the one created。 here. 如果这个过程偶然在下级(小的范围)中再次发生,“父”模块记录将会被创建并传递。

Per-directory module records are much more common than those created for server scopes. In fact, when your directive handlers are called, they’re given a pointer to the appropriate per-directory module record, but not to any per-server module record. If your directive handler wants to store information in a serverwide
module record, it needs to ask the server for the record explicitly.

每个模块的记录比为服务器创建范围更为常见。事实上,当你的指令处理程序被调用,他们给一个指示到适当的模块记录中，但不是任何一个服务器模块记录。如果你的指令处理程序希望将信息存储在服务器范围模块记录，它需要向服务器明确备案。

Per-server and per-directory module records can have identical layouts, or be completely different; it’sentirely up to your module, since you define the structures. But even if they’re identical, in no case will Apache try to merge them together; they’re on two completely separate lists and the server considers them unrelated.

每台服务器和每个模块记录可以有相同的布局,或者是完全不同的,它完全取决于你的模块,因为你可以定义结构。但是,即使他们是相同的,在任何情况下Apache试着将它们合并在一起是不可能的,他们在两个完全独立的列表中并且服务器认为他们是不相关的。

The routines you declare for the purpose of creating your module configuration records are passed some information about the scope to which the record applies. In the case of a routine tasked with creating a record for a server-wide scope, this is in the form of a pointer to the server’s control record (its server_rec). For a per-directory record creation routine, the argument is a string identifying the directory in question, such as “/” or “/usr/local/apache/htdocs/bar”. What use you make of this information is entirely up to you.

为了创建模块配置记录而声明的函数会接受记录适用范围的信息。在一次例行任务中创建一个服务器范围的记录,这是一个指向服务器的控制记录（其server_rec）的形式。对于每个目录记录创建例程，该参数是一个字符串，标识有问题的目录，比如“/” or “/usr/local/apache/htdocs/bar”。这些信息有什么用是完全取决于你。

Per-directory record creation routines can be passed a ‘magic’ directory string which means “this applies to all directories unless overridden.” This magic value is simply “”, an empty string. Module configuration records are all chained together in a list attached to the appropriate structure (the server_rec or request_rec). In order to find your module’s record, you pass this list pointer to the ap_get_module_config() routine, along with a pointer to your module’s module record. (This overusage of the word ‘module’ is getting rather confusing, isn’t it?) For example, if r is a pointer to a request_rec for a request in progress, you can get both your module’s per-directory and server-wide records as follows (where foo_srec_t and foo_rrec_t are the typedef names for your server and per-directory record structures, and foo_module is the label of your module structure):

每个记录创建程序可以使用一个“magic”字符串，意思是“这适用于所有的目录,除非被覆盖。“magic“值是一个简单的空字符串。合适的结构列表模块配置记录都链接在一起（在server_rec或的request_rec）。为了找到你的模块的记录,你通过这个列表指针ap_get_module_config()函数,以及一个指向你的模块的模块记录。(“模块”这个词变得相当混乱,不是吗?)例如,如果r是一个指向request_rec进展的一个请求,你可以得到你的每个模块记录和服务器范围如下{其中foo_srec_t和foo_rrec_t是为您的服务器和每目录记录结构的typedef名称，以及foo_module是你的模块结构的标签）：

  foo_srec_t *srec;
  foo_rrec_t *rrec;

  rrec = (foo_rrec_t *) ap_get_module_config(r->per_dir_config,
  &foo_module);

  srec = (foo_srec_t *) ap_get_module_config(r->server->module_config,
  &foo_module);

Server Config Hooks 服务器配置钩子

As mentioned earlier, there are two slots in the module structure for dealing with server-wide module records, one for creating a new record and one for merging two existing records into a new combined one.

正如前面提到的,在模块结构里两个插槽用于处理服务器范围的模块记录,一个用于创建新记录和一个用于合并两个现有记录到一个新的组合。

The creation routine tends to be very simple, 创建程序往往是非常简单的
along the lines of 类似这样：

 static void *foo_new_server_rec(pool *p, server_rec *s)

  {

 foo_srec_t *srec;

 srec = (foo_srec_t *) ap_pcalloc(p, sizeof(foo_srec_t));

 return (void *) srec;

   }

It may do additional things like setting default values into the various fields, but the above is the function reduced to its most basic. 它可能做的额外的事情就是，设置默认值到各个领域,但上述的函数是最基本的。

Similarly, the per-server module record merging routine might look like this: 同样,每台服务器模块记录合并程序可能看起来像这样:

 static void *foo_merg_server_rec(pool *p, void *p_srec_p, void *c_srec_p)

  {

  foo_srec_t *p_srec, *c_srec; /* parent and current records */

  foo_srec_t *new_srec;

  p_srec = (foo_srec_t *) p_srec_p;

  c_srec = (foo_srec_t *) c_srec_p

  new_srec = (foo_srec_t *) ap_pcalloc(p, sizeof(foo_srec_t));

  /*

  * foo and bar are *always* inherited from the current record.

  */

  new_srec->foo = c_srec->foo;

  new_srec->bar = c_srec->bar;

  /*

  * zed is inherited from the current directory if there’s

  * a non-default setting there, otherwise from the parent

  */

  new_srec->zed = (c_srec->zed == 0) ? p_srec->zed : c_srec->zed;

  return (void *) new_srec;

   }

As you can see, these routines are really quite simple. 正如你所看到的,这些程序是非常简单的。

Per-server module records are not used very often, since they don’t lend themselves to being customisable at different levels and locations in the server’s URI space. Examples of their use include the Alias, Port, ServerName, and MaxRequestsPerChild directives – none of which have anything to do with where the server might end up finding the requested resource.

服务器模块记录并不经常使用,因为他们本身固定在不同级别和服务器的URI空间的不同位置。他们使用的例子包括别名,Port,ServerNam和,MaxRequestsPerChild指令——没有一个和服务器最终找到的请求资源有关系。

When it comes to scoping for this type of record, there are only two levels: the global server environment (i.e., anything that isn’t inside a <VirtualHost> container block), and <VirtualHost> container definitions. 当涉及到范围记录这种类型时,只有两个级别:全球服务器环境(即,任何一个不在<虚拟主机>容器块内),和<虚拟主机>容器定义。

Per-directory Config 单独目录配置

The per-directory callbacks are identical to the per-server ones described in the previous section – save that they are used to deal with information about locations in the underlying document filesystem, rather than to server-wide settings. Since this is by far the more common environment for directives, the Apache
architecture makes things a little easier, such as by looking up and providing a pointer to the module’s perdirectory configuration record as part of the directive handler argument list.

每个目录回调与上一节中描述的每台服务器的回调是相同的——保存他们是用来处理底层文件系统中的位置信息,而不是务器范围的设置。因为这是到目前为止,最常见的环境指示,Apache架构使事情更容易一些,比如通过查找和提供一个指向每个目录配置记录模块，作为该指令的处理程序的参数列表的一部分。

Examples of functionality that is better suited to per-directory scoping than server-wide include 这是比服务器范围更适合单独目录功能的例子
· labeling file types as indicating specific contents (e.g., defining “.html” as meaning HTML) 标签指示具体内容(如文件类型。,定义”。html”意味着html)
· applying access control 应用访问控制
· controlling whether directory listings are allowed

控制是否允许目录清单