从 2.2 开始的 Apache HTTP Server 2.4 中的 API 更改

本文档介绍了 Apache HTTPD API 从 2.2 版到 2.4 版的更改，这些更改可能是模块/应用程序开发人员和核心黑客所感兴趣的。从 2.4 分支的第一个 GA 版本开始，API 的兼容性一直保留到 2.4 分支的生命周期中。 (2.4 版的VERSIONING描述提供了有关 API 兼容性的更多信息。)

API 更改分为两类：全新的 API 和已扩展或更改的现有 API。后者又分为所有更改都是向后兼容的(因此现有模块可以忽略它们)，以及可能需要维护人员注意的更改。与从 HTTPD 2.0 到 2.2 的过渡一样，现有的模块和应用程序将需要重新编译，并且可能需要引起注意，但是大多数模块和应用程序都不需要进行任何实质性的更新(尽管某些组件和应用程序可以利用 API 的更改来提供显着的改进)。

就本文档而言，API 是根据公共头文件拆分的。这些 Headers 本身就是参考文档，可用于生成带有make docs的可浏览 HTML 参考。

Changed APIs

ap_expr (NEW!)

引入了一种新的 API，用于解析和评估布尔表达式和代数表达式，包括提供标准语法和自定义变体。

ap_listen(已更改；向后兼容)

引入了一个新的 API，以使 httpd 子进程能够满足不同的目的。

ap_mpm (changed)

ap_mpm_run替换为新的mpm钩子。 ap_graceful_stop_signalled也丢失了，ap_mpm_register_timed_callback是新的。

ap_regex (changed)

除了现有的 regexp 包装器之外，现在还提供了新的更高级别的 API ap_rxplus。这提供了编译 Perl 样式的表达式(如s/regexp/replacement/flags)并针对任意字符串执行它们的功能。还添加了对正则表达式反向引用的支持。

ap_slotmem (NEW!)

为模块分配和 Management 内存插槽(通常用于共享内存)引入 API。

ap_socache (NEW!)

用于 Management 共享对象缓存的 API。

heartbeat (NEW!)

心跳模块的通用结构

ap_parse_htaccess (changed)

ap_parse_htaccess的功能签名已更改。现在必须传递apr_table_t允许覆盖的各个指令(保留覆盖)。

http_config (changed)

http_core (changed)

httpd (changed)

http_log (changed)

http_request (changed)

如果可能，建议使用AP_AUTH_INTERNAL_PER_CONF注册所有访问控制钩子(包括身份验证和授权钩子)。如果所有模块的访问控制钩都使用此标志注册，则每当服务器处理与初始请求相同的访问控制配置指令集匹配的内部子请求时(这是常见的情况)，就可以避免调用访问控制钩另一个时间。

如果您的模块要求使用旧行为，并且必须使用与初始请求不同的 URI 对每个子请求执行访问控制检查，即使该 URI 与相同的访问控制配置指令集匹配，也请使用AP_AUTH_INTERNAL_PER_URI。

mod_auth (NEW!)

介绍用于 authn 和 authz 的新提供程序框架

mod_cache (changed)

向缓存提供程序接口引入commit_entity()函数，从而允许对缓存进行原子写入。添加一个cache_status()钩子以报告缓存决定。所有私有结构和功能均被删除。

mod_core (NEW!)

这引入了低级 API 来发送任意 Headers，并公开了用于处理 HTTP OPTIONS 和 TRACE 的函数。

mod_cache_disk (changed)

更改磁盘高速缓存的磁盘格式，以支持原子高速缓存更新而不进行锁定。主体文件的设备/节点对嵌入在头文件中，从而允许确认头和主体属于彼此。

mod_disk_cache (renamed)

为了与服务器中其他模块的命名保持一致，已将 mod_disk_cache 模块重命名为 mod_cache_disk。

mod_request (NEW!)

mod_request的 API，可在需要时使 Importing 数据可用于多个应用程序/处理程序模块，并解析 HTML 表单数据。

mpm_common (changed)

scoreboard (changed)

引入了替代版本后，ap_get_scoreboard_worker已向后兼容。额外的 proxy_balancer 支持。child 状态的东西进行了修改。

util_cookies (NEW!)

引入了用于 Management HTTP Cookies 的新 API。

util_ldap (changed)

没有可用的描述

util_mutex (NEW!)

httpd 中的 APR proc 和全局互斥的包装，为底层机制和锁定文件的位置提供通用配置。

util_script (changed)

新：ap_args_to_table

util_time (changed)

新：ap_recent_ctime_ex

有关从 2.2 升级模块的特定信息

Logging

为了利用按模块日志级别的配置，任何调用ap_log_*函数的源文件都应声明其属于哪个模块。如果模块的 module_struct 称为foo_module，则可以使用以下代码保持与 HTTPD 2.0 和 2.2 的向后兼容性：

#include <http_log.h> #ifdef APLOG_USE_MODULE APLOG_USE_MODULE(foo); #endif

注意：这对于 C 语言模块是绝对必需的。可以跳过 C 语言模块，尽管这样会破坏没有该模块的文件的特定于日志级别的支持。

ap_log_*函数的参数数量和APLOG_MARK的定义已更改。通常，更改是完全透明的。但是，如果模块使用APLOG_MARK作为其自身功能的参数，或者模块在不传递APLOG_MARK的情况下调用ap_log_*，则需要进行更改。在ap_log_*周围使用包装器的模块通常同时使用这两种构造。

更改将APLOG_MARK传递到其自身函数的代码的最简单方法是定义并使用另一个扩展为这些函数所需参数的宏，因为APLOG_MARK仅应在直接调用ap_log_*时使用。这样，代码将保持与 HTTPD 2.0 和 2.2 的兼容性。

在 2.4 和早期发行版之间，调用ap_log_*而不传递APLOG_MARK的代码必然有所不同，因为 2.4 需要新的第三个参数APLOG_MODULE_INDEX。

/* code for httpd 2.0/2.2 */ ap_log_perror(file, line, APLOG_ERR, 0, p, "Failed to allocate dynamic lock structure"); /* code for httpd 2.4 */ ap_log_perror(file, line, APLOG_MODULE_INDEX, APLOG_ERR, 0, p, "Failed to allocate dynamic lock structure");

ap_log_*error现在被实现为宏。这意味着不再可以在ap_log_*error的参数列表中使用#ifdef，因为根据 C99，这将导致不确定的行为。

启动后调用时，必须将server_rec指针传递给ap_log_error()。这总是很合适，但是 2.4 中NULL server_rec的限制比以前的版本还要多。从 2.3.12 开始，全局变量ap_server_conf始终可以用作server_rec参数，因为只有在将NULL传递给ap_log_error()时才是NULL。仅当没有更合适的server_rec时才应使用ap_server_conf。

考虑以下更改以利用新的APLOG_TRACE1..8日志级别：

模块有时会在其日志消息中添加进程 ID 和/或线程 ID。现在默认情况下会记录这些 ID，因此模块可能无需显式记录它们。 (用户可以将其从错误日志格式中删除，但是可以指示他们在必要时将其重新添加以进行问题诊断.)

如果您的模块使用这些现有的 API ...

如果您的模块具有此功能，则...

您的模块是否...

首页