“Apache源代码全景分析”之“指令定义”
在了解了指令的数据结构后，我们应该继续了解如何定义一个指令。定义一个指令非常简单，无非就是将一个指令的各个要素填充到command_rec结构中。按照正常的思维，通常情况下，我们会首先声明一个command_rec结构，然后逐一赋值，就像下面的一样：
command_rec newcommand;
newcommand.name = …
newcommand.func = …
newcommand.req_override = …
如果指令数目少，这种定义还可以将就；如果需要定义的指令数目很大，这种定义的方法就非常繁琐，因此Apache使用了专门的宏来定义一个指令结构。
Apache中定义了12种指令，为此Apache中也定义了相应的配置处理指令。Apache中定义的12个处理宏定义如下：
typedef const char *(*cmd_func) ();
# define AP_NO_ARGS func
# define AP_RAW_ARGS func
# define AP_TAKE_ARGV func
# define AP_TAKE1 func
# define AP_TAKE2 func
# define AP_TAKE3 func
# define AP_FLAG func
# define AP_INIT_NO_ARGS(directive, func, mconfig, where, help) \
{ directive, func, mconfig, where, RAW_ARGS, help }
# define AP_INIT_RAW_ARGS(directive, func, mconfig, where, help) \
{ directive, func, mconfig, where, RAW_ARGS, help }
# define AP_INIT_TAKE_ARGV(directive, func, mconfig, where, help) \
{ directive, func, mconfig, where, TAKE_ARGV, help }
# define AP_INIT_TAKE1(directive, func, mconfig, where, help) \
{ directive, func, mconfig, where, TAKE1, help }
# define AP_INIT_ITERATE(directive, func, mconfig, where, help) \
{ directive, func, mconfig, where, ITERATE, help }
# define AP_INIT_TAKE2(directive, func, mconfig, where, help) \
{ directive, func, mconfig, where, TAKE2, help }
# define AP_INIT_TAKE12(directive, func, mconfig, where, help) \
{ directive, func, mconfig, where, TAKE12, help }
# define AP_INIT_ITERATE2(directive, func, mconfig, where, help) \
{ directive, func, mconfig, where, ITERATE2, help }
# define AP_INIT_TAKE13(directive, func, mconfig, where, help) \
{ directive, func, mconfig, where, TAKE13, help }
# define AP_INIT_TAKE23(directive, func, mconfig, where, help) \
{ directive, func, mconfig, where, TAKE23, help }
# define AP_INIT_TAKE123(directive, func, mconfig, where, help) \
{ directive, func, mconfig, where, TAKE123, help }
# define AP_INIT_TAKE3(directive, func, mconfig, where, help) \
{ directive, func, mconfig, where, TAKE3, help }
# define AP_INIT_FLAG(directive, func, mconfig, where, help) \
{ directive, func, mconfig, where, FLAG, help }
从上面的定义可以看出，12个宏中每个宏都具有相同的格式，唯一不同的就是其传入的指令类型。宏的第一个参数是指令名称，第二个参数是指令处理函数，mconfig则是指令处理函数需要的额外参数，where则是位置上下文信息，help是错误提示信息。指令类型信息不同的宏会自动赋值。正常的情况下，在模块的command_rec表格中增加一个新的指令有两种方法：一种是直接填充command_rec结构中的各个成员变量，另一种就是使用宏填充。如果使用宏，那么代码编译时就不会产生警告消息。但是，如果直接填充结构，那么在采用维护模式进行编译时，代码就会产生警告。
下面我们来看AP_INIT_TAKE1的一个具体实现：
AP_INIT_TAKE1(“AuthType”,ap_set_string_slot,
(void*)APR_OFFSETOF (core_dir_config,ap_auth_type),
OR_AUTHCFG,
“An Http authorization(e.g,\”Basic\”)”
);
该宏的第一个字段AuthType是指令的名称。该名称可以是任何合法的内容，但是不应该包含空格字符，Apache在处理指令时以空格作为结束符，一旦遇到空格即停止。当服务器读取配置文件的时候，它就会读入各行代码，并且搜索所有已经激活模块中的指令。如果找不到指令，服务器就终止。
该宏的第二个字段是该模块中对该指令的处理函数。在上面的示例中，模块中处理AuthType指令的处理函数为ap_set_string_slog。尽管所有声明函数的原型都相同，但是这个函数的原型会根据所定义的指令类型而改变。不同类型指令的原型在前文中我们已经介绍过。
第三个字段是应该向函数传递的附加数据。不同的函数附加数据不同。如果没有附加数据，则此处为NULL通过该字段的设置，Apache 可以用一个函数来处理多个指令。比如在core模块中，dirsection函数方法可以同时处理Directory和DirectoryMatch两个指令，那么该字段设置为0（NULL）和1就可以分开处理：
AP_INIT_RAW_ARGS("<Directory", dirsection, NULL, RSRC_CONF,
"Container for directives affecting resources located in the specified "
"directories")
AP_INIT_RAW_ARGS("<DirectoryMatch", dirsection, (void*)1, RSRC_CONF,
"Container for directives affecting resources located in the "
"specified directories")
通过读取实际的参数，就可以知道dirsection到底处理的是哪一个指令。
在该示例中，附加数据为(void*)APR_XtOffsetOf(core_dir_config,ap_auth_type)。核心服务器会使用ap_set_string_slot函数来设置结构中的字符串。因为这个函数可以用于设置任何结构中的任何字符串，所以服务器必须要传递结构中正确字段的偏移量，以便函数能够知道所要改变的内容。APR_XtOffsetOf宏能够计算这个偏移量，通过将这个宏放入到指令定义的第三个字段中，就可以根据第二个字段中规定的函数得到这个偏移量。
第四个字段将会描述指令可以放置到配置文件的哪些位置。配置文件解析器能够确定指令是在目录中找到还是在虚拟主机区间找到。通过在这里规定这个值，核心服务器就能够进行基本的错误检查以确保没有在不合理的位置中规定指令。
最后一个字段就是在管理员不正确配置服务器时输出的错误字符串。这个错误的消息不应该解释指令所进行的工作。相反，它应该解释怎样使用指令。这样就可以帮助管理员改正可能存在的配置错误。
该宏最终的产生效果类似于下面的语句：
command_rec.name = “AuthType”;
command_rec.func = ap_set_string_slot;
command_rec.cmd_data = (void*)APR_OFFSETOF (core_dir_config,ap_auth_type);
command_rec.req_override = OR_AUTHCFG;
command_rec.args_how = TAKE1;
command_rec.errmsg = “An Http authorization(e.g,\”Basic\”);
节选自《Apache源代码全景分析第1卷：体系结构与核心模块》第3章3.4.2节“指令定义”。本书即将上市，互动网预定请访问http://www.china-pub.com/195492。
