Web服务器软件Apache模块初步研究总结

1、.Apache模块的初步研究总结作者：徐绿兵日期：2003/2/11Apache作为Web服务器，除了可以写CGI程序完成各种Web应用外，Apache也提供了一套API来扩充服务器的功能。Apache本身就是一个由多个模块（module）拼装而成的程序，它的API就是用来写Apache定义的模块的。通过对Apache模块API的研究，总结如下：一、Apache模块API的特点l 都是C的API：Apache模块API是用标准C语言提供的。l 模块由一系列回调函数组成：所谓的模块，就是实现一系列模块所需要的回调函数和提供符合预定义数据结构的值。回调函数包括模块初始化（init）、配置信息处理（

2、create_config、merge_config）、文件名转换处理（URI -> filename）、内容处理程序（content handler）、专有日志输出（logger）等，回调函数可以根据需要全部或部分实现。内容处理程序可以输出相应结果。l 一个模块可以包含一或多个内容处理程序回调函数：若干个内容处理程序回调函数可以通过一个数据结构（handler_rec）指明。如何激活相应的函数可以通过Apache的配置文件（conf/httpd.conf）指明。内容处理程序可以在访问某个路径时或访问具有某种扩展名的文件时被激活。l 支持多种生命期的内存池（memory pool）：合理

3、的使用可以防止内存泄露，使用内存池申请的动态空间可以在内容处理程序调用后或Apache正常退出时自动释放。二、优点Apache模块是和Apache绑定的，是Apache的一部分，无需每次HTTP请求时都需要加载。三、缺点l API可能会更新，由此会造成模块做相应的修改。l 每次改动模块要重新编译连接Apache（可以通过动态连接方式编译，还没做相应的试验）。l 对模块的健壮性要求高，因为模块是服务器的一部分。l 多了一套规范，推广难度比CGI大。四、参考文档/docs/misc/API.html五、未来研究设想目前的研究还是很初步的。如果可能，未来还

4、可以对以下领域做进一步的研究：1 通过Apache配置文件配置模块的一些参数，如数据库参数；配置命令各种参数传递方式的使用；配置命令放在VirtaulHost内和VirtualHost外的区别和影响。2 模块各阶段回调函数的深入研究，充分利用各种回调函数3 子请求（subrequest）的研究4 Apache源代码提供的各种操作函数六、如何书写Apache模块（本部分代码都可以在模块例子中找到）1定义Apache配置文件命令static const command_rec dump_cmds = "Dump", /* directive name */ cmd_dump,

5、/* config action routine */ NULL, /* argument to include in call */ OR_OPTIONS, /* where available */ RAW_ARGS, /* arguments */ "Dump directive - any arguments" /* directive description */ , NULL;这个结构指明了可以在Apache配置文件（conf/httpd.conf）可使用的配置命令（本例中为“Dump”）、处理该命令的函数名称（本例中为cmd_dump）、传递参数的方式（本例中

6、为RAW_ARGS）。配置命令处理函数的写法参加模块例子。一个模块中可以处理若干个配置命令，结构数组最后一个值为NULL。2定义内容处理函数static const handler_rec dump_handlers = "dump-handler", dump_handler, NULL;这个结构指明了内容处理函数的名称（用于Apache配置文件，本例中为"dump-handler"）和内容处理函数的名称（本例中为dump_handler）。一个模块中可以有若干个内容处理函数，结构数组的最后一个值为NULL。3定义模块结构module MODULE_V

7、AR_EXPORT dump_module = STANDARD_MODULE_STUFF, dump_init, /* module initializer */ dump_create_dir_config,/* per-directory config creator */ dump_merge_dir_config, /* dir config merger */ dump_create_server_config, /* server config creator */ dump_merge_server_config, /* server config merger */ dump

8、_cmds, /* command table */ dump_handlers, /* list of handlers */ dump_translate_handler,/* filename-to-URI translation */ dump_check_user_id, /* check/validate user_id */ dump_auth_checker, /* check user_id is valid *here* */ dump_access_checker, /* check access by host address */ dump_type_checker,

9、 /* MIME type checker/setter */ dump_fixer_upper, /* fixups */ dump_logger /* logger */#if MODULE_MAGIC_NUMBER >= 19970103 ,dump_header_parser /* header parser */#endif#if MODULE_MAGIC_NUMBER >= 19970719 ,dump_child_init /* process initializer */#endif#if MODULE_MAGIC_NUMBER >= 19970728 ,du

10、mp_child_exit /* process exit/cleanup */#endif#if MODULE_MAGIC_NUMBER >= 19970902 ,dump_post_read_request /* post read_request handling */#endif;这个结构指明了模块的各种回调函数。如果不需要某个回调函数，可以填NULL。4实现各种回调函数根据实际需求实现各种回调函数，最重要的是内容处理函数。5写Apache模块重点注意事项 1) 内存的分配(malloc)和释放(free)一定要配对 CGI程序可以对分配的内存不释放，其相应的内存空间会在CGI程

11、序结束时由Apache回收；Apache模块由于是Apache的一部分，和Apache一起总是驻留在内存中，分配的空间一定要在Apache模块处理完一次请求时完全释放。 2) 文件的打开(fopen)和关闭(fclose)要配对 理由同1) 3) socket的打开(socket)和关闭(close)要配对 理由同1) 4) 不能使用强行退出进程的exit()函数 CGI是以进程为单位的，处理完一次HTTP请求，返回HTTP响应，CGI进程也就结束了；Apache模块是Apache的一部分，处理完一次请求只是内容处理函数的一次调用结束。七、有关Apache API的源代码（以下所有的内容都是基

12、于apache 1.3.26源码的，其它版本大同小异）1主要目录：src/include子目录：可以引用的.h文件，包括一些常用的结构定义、工具函数定义src/modules子目录：Apache模块的总目录，扩充的模块也可以放在这个目录下和Apache程序一起编译src/main子目录：Apache程序的实现2主要文件介绍l src/include/httpd.h包含结构request_rec、conn_rec、server_rec的定义包含时间、字符串处理函数包含HTTP响应返回码定义l src/include/ap_alloc.h包含结构table_entry的定义、table的操作函数包

13、含通过内存池使用内存、文件的函数l src/main/alloc.c包含结构table的定义l src/include/util_uri.h包含结构uri_components的定义l src/include/http_protocol.h包含各种输出的HTTP客户端的函数3主要数据结构介绍l request_rec作用Apache在接收客户端请求时收集的各种信息，是各种回调函数接收的主要参数；内容处理程序的结果也通过这个结构返回给客户端。所在文件src/include/httpd.h主要字段（注意，指针变量有可能是NULL）ap_pool* pool给请求使用的内存池，请求处理后释放conn

14、_rec* connection和请求连接有关的数据信息，如远端IPserver_rec* serverApache服务器的配置信息，对应配置文件char* the_request客户端请求的第一行，如“GET / HTTP/1.1”int header_only是否为HEAD请求标志char* protocol协议信息，例“HTTP/1.1”int proto_num协议版本，以整数表示，1.1表示成1001const char* hostname客户端请求URL中的机器名部分time_t request_time服务器接收到请求的时间（服务器时钟）const char* method请求方

15、法，GET、POST、HEAD等int method_number请求方法整数表示，M_GET、M_POST等，定义在同一文件中long remaining未读取的字节数，读POST数据时可以设置这个值long read_length已读取的字节数table* headers_in客户端请求的头信息，不包括第一行table* headers_out响应输出的头信息，如设置cookieconst char* content_type响应的内容类型，如“text/html”，可直接设置char* unparsed_uri包括参数在内的URI，从the_request中分析得到char* uriUR

16、I中的路径部分，去掉了unparsed_uri中的参数部分char* filenameURI对应服务器端的绝对路径名char* path_infopath_info信息char* argsGET命令的参数部分（QUERY_STRING）void* per_dir_config目录配置信息void* request_config请求配置信息l table_entry作用存储属性，是table结构中的基本元素所在文件src/include/ap_alloc.h定义typedef struct char *key; /* maybe NULL in future; * check when iter

17、ating * thru table_elts */ char *val; table_entry;l command_rec作用定义配置命令，指明相应的函数及参数传送方式。所在文件src/include/http_config.h字段定义const char* name;命令名称const char* (*func) ();命令处理函数指针void *cmd_data;额外数据，供处理多个命令的函数使用int req_override;命令允许出现的位置掩码enum cmd_how args_how;参数传递方式。NO_ARGS表示无参数、TAKE1表示带一个参数，等等。const char

18、* errmsg;使用方法，在出现语法错误时显示l cmd_parms作用Apache调用命令处理时传递的参数所在文件src/include/http_config.h定义typedef struct void *info; /* Argument to command from cmd_table */ int override; /* Which allow-override bits are set */ int limited; /* Which methods are <Limit>ed */ configfile_t *config_file; /* 配置文件结构 */

19、 ap_pool *pool; /* 内存池 */ struct pool *temp_pool; /* 临时内存池 */ server_rec *server; /* 配置文件出现server信息 */ char *path; /* 配置文件中所用的目录*/ const command_rec *cmd; /* configuration command */ const char *end_token; /* end token required to end a nested section */ void *context; /* per_dir_config vector passe

20、d * to handle_command */ cmd_parms;l module作用模块定义。指明各种回调函数。所在文件src/include/ http_config.h定义typedef struct module_struct int version; /* API版本 */ int minor_version; /* API次版本号 */ int module_index; /* config vectors.指向该模块的索引 */ const char *name; void *dynamic_load_handle; struct module_struct *next; u

21、nsigned long magic; /* 标识模块的Cookie，用于DSO */ #ifdef ULTRIX_BRAIN_DEATH void (*init) (); void *(*create_dir_config) (); void *(*merge_dir_config) (); void *(*create_server_config) (); void *(*merge_server_config) ();#else void (*init) (server_rec *, pool *); void *(*create_dir_config) (pool *p, char *

22、dir); void *(*merge_dir_config) (pool *p, void *base_conf, void *new_conf); void *(*create_server_config) (pool *p, server_rec *s); void *(*merge_server_config) (pool *p, void *base_conf, void *new_conf);#endif const command_rec *cmds; const handler_rec *handlers; /* 各种回调函数定义 * translate_handler - 把

23、URI转成文件名 * access_checker - 检查访问权限 * check_user_id - 检查来自HTTP 请求的user id合法性 * auth_checker - check_user_id提供 user是否OK * type_checker - 决定响应的MIME类型，设置 * content_type、_encoding和_language。 * logger - 写模块专用日志 * post_read_request - 在read_request * 和 internal_redirect后马上执行的函数，不会在 * 任何subrequests后执行 */ int

24、 (*translate_handler) (request_rec *); int (*ap_check_user_id) (request_rec *); int (*auth_checker) (request_rec *); int (*access_checker) (request_rec *); int (*type_checker) (request_rec *); int (*fixer_upper) (request_rec *); int (*logger) (request_rec *); int (*header_parser) (request_rec *);#if

25、def ULTRIX_BRAIN_DEATH void (*child_init) (); void (*child_exit) ();#else void (*child_init) (server_rec *, pool *); void (*child_exit) (server_rec *, pool *);#endif int (*post_read_request) (request_rec *); module;4主要函数介绍l ap_table_set作用设置table中的一个属性所在文件src/include/ap_alloc.h定义API_EXPORT(void) ap_t

26、able_set(table *, const char *name, const char *val);例子/* 设置Cookie */ap_table_set(r->headers_out, "Set-Cookie", "module=dump;path=/");l ap_table_get作用取table中的一个属性值所在文件src/include/ap_alloc.h定义API_EXPORT(const char *) ap_table_get(const table *, const char *);例子/* 取Content-Lengt

27、h */char* cl = ap_table_get(r->headers_in, "Content-Length");l ap_palloc作用申请指定字节的内存空间，放在内存池中。类似malloc所在文件src/include/ap_alloc.h定义API_EXPORT(void *) ap_palloc(struct pool *, int nbytes);例子char* buf = (char*)ap_palloc(r->pool, len+1);if (buf = NULL) .l ap_pfopen/ ap_pfclose作用在内存池中打开/关闭

28、一个文件。类似fopen/fclose所在文件src/include/ap_alloc.h定义API_EXPORT(FILE *) ap_pfopen(struct pool *, const char *name, const char *fmode);API_EXPORT(int) ap_pfclose(struct pool *, FILE *);例子FILE* fp = ap_pfopen(r->pool, "filename", "r");fclose(r->pool, fp);l ap_rputs作用往请求结构中输出一个字符串。类

29、似puts所在文件src/include/http_protocol.h定义API_EXPORT(int) ap_rputs(const char *str, request_rec *r);例子ap_rputs("字符串内容n", r);l ap_rprintf作用往请求结构中格式化输出数据。类似printf所在文件src/include/http_protocol.h定义API_EXPORT_NONSTD(int) ap_rprintf(request_rec *r, const char *fmt,.) _attribute_(format(printf,2,3);例

30、子ap_rprintf(r, "the_request (请求第一行)： %sn", r->the_request);l ap_send_fd作用往请求结构中输出一个文件的内容所在文件src/include/http_protocol.h定义API_EXPORT(long) ap_send_fd(FILE *f, request_rec *r);例子FILE *fLogo = fopen("/path/to/logo.gif", "r");if (fLogo != NULL)ap_send_fd(fLogo, r);fclose

31、(fLogo);l ap_get_client_block作用从请求结构中读取一个数据块，如读POST数据所在文件src/include/http_protocol.h定义API_EXPORT(long) ap_get_client_block(request_rec *r, char *buffer, int bufsiz);例子/* 取Content-Length */char* cl = ap_table_get(r->headers_in, "Content-Length");int len = r->remaining = atoi(cl);char* buf = (char*)ap_palloc(r->pool, len+1);ap_get_client_block(r, buf, len+1);buflen = '0'l ap_discard_request_body作用是否请求结构中的一个数据块，如POST数据所在文件src/include/http_protocol.h定义API_EXPORT(int) ap_discard_request_body(request_rec *r);说明POST请求数据一定要处理，如果抛弃不用，可以调用这个函数。如果客户端连接中留有数据，可能会影响下一次请求处