Apache 模块 mod_isapi

Summary

此模块实现 Internet 服务器扩展 API。它允许 Apache for Windows 为 Internet 提供 Internet 服务器扩展(例如 ISAPI .dll 模块)，但要遵守上述限制。

ISAPI 扩展模块(.dll 文件)由第三方编写。 Apache Group 不编写这些模块，因此我们不为它们提供支持。如果您在运行 ISAPI 扩展时遇到问题，请直接与 ISAPI 的作者联系。 请不要将此类问题发布到 Apache 的列表或错误报告页面.

Usage

在服务器配置文件中，使用AddHandler指令将 ISAPI 文件与isapi-handler处理程序相关联，并将其与文件 extensionsMap 到它们。要使任何.dll 文件都可以作为 ISAPI extensions 进行处理，请编辑 httpd.conf 文件并添加以下行：

AddHandler isapi-handler .dll

Apache 服务器中没有能力保持请求的模块加载。但是，您可以通过在 httpd.conf 中使用以下语法来预加载并保持特定模块的加载：

ISAPICacheFile c:/WebWork/Scripts/ISAPI/mytest.dll

不管您是否已预加载 ISAPI 扩展，所有 ISAPI 扩展均受与 CGI 脚本相同的权限和限制的约束。即，必须为包含 ISAPI .dll 文件的目录设置Options ExecCGI。

查看Additional Notes和Programmer's Journal以获得更多详细信息，并阐明mod_isapi提供的特定 ISAPI 支持。

Additional Notes

Apache 的 ISAPI 实现符合所有 ISAPI 2.0 规范，除了一些处理异步 I/O 的“ Microsoft 特定”扩展之外。 Apache 的 I/O 模型不允许以 ISAPI 可以访问的方式进行异步读写。如果 ISA 尝试访问不支持的功能(包括异步 I/O)，则会在错误日志中放置一条消息，以帮助进行调试。由于这些消息可能会泛滥成灾，因此存在指令ISAPILogNotSupported Off来消除这种噪音。

某些服务器(例如 Microsoft IIS)将 ISAPI 扩展加载到服务器中并保持加载状态，直到内存使用率过高或除非指定了配置选项。除非指定了ISAPICacheFile指令，否则 Apache 当前每次都会在请求时加载和卸载 ISAPI 扩展。这效率低下，但是 Apache 的内存模型使之成为最有效的方法。许多 ISAPI 模块与 Apache 服务器都有一定的不兼容，卸载这些模块有助于确保服务器的稳定性。

另外，请记住，虽然 Apache 支持 ISAPI 扩展，但它“不支持 ISAPI 过滤器” **。以后可能会增加对过滤器的支持，但是目前不计划支持。

Programmer's Journal

如果您正在编程 Apache 2.0 mod_isapi模块，则必须将对ServerSupportFunction的调用限制为以下指令：

• HSE_REQ_SEND_URL_REDIRECT_RESP

  • 将用户重定向到另一个位置。
    这必须是完全限定的网址(例如 http://server/location)。

• HSE_REQ_SEND_URL

  • 将用户重定向到另一个位置。
    该网址不能是完全限定的网址，不允许您传递协议或服务器名称(例如只是/location)。
    此重定向由服务器而非浏览器处理。

• HSE_REQ_SEND_RESPONSE_HEADER

  • 如果 Apache 接受 Headers 字符串参数中的空行(两个连续的换行符)，则在 Headers 后接受 Apache 响应主体。该主体不能包含 NULL，因为 headers 参数以 NULL 终止。

• HSE_REQ_DONE_WITH_SESSION

  • Apache 将此视为无操作，因为当 ISAPI 从处理返回时，会话将结束。

• HSE_REQ_MAP_URL_TO_PATH

  • Apache 将虚拟名称转换为物理名称。

• HSE_APPEND_LOG_PARAMETER

  • 可以在以下任何日志中捕获此记录的消息：

• 在CustomLog指令中的\"%{isapi-parameter}n\"组件中

• 使用ISAPIAppendLogToQuery On指令在%q日志组件中

• 在带有ISAPIAppendLogToErrors On指令的错误日志中

第一个选项%{isapi-parameter}n组件始终可用，并且是首选。

• HSE_REQ_IS_KEEP_CONN

  • 将返回协商的 Keep-Alive 状态。

• HSE_REQ_SEND_RESPONSE_HEADER_EX

  • 尽管会忽略fKeepConn标志，但其行为将与文档中所述相同。

• HSE_REQ_IS_CONNECTED

  • 如果请求已中止，将报告 false。

Apache 返回FALSE到任何不受支持的ServerSupportFunction调用，并将GetLastError的值设置为ERROR_INVALID_PARAMETER。

ReadClient检索超出初始缓冲区(由ISAPIReadAheadBuffer定义)的请求正文。基于ISAPIReadAheadBuffer设置(调用 ISAPI 处理程序之前要缓冲的字节数)，较短的请求将在调用扩展时完整发送到扩展。如果请求更长，则 ISAPI 扩展必须使用ReadClient来检索剩余的请求正文。

支持WriteClient，但仅带有HSE_IO_SYNC标志或没有选项标志(值0)。其他任何WriteClient请求将被拒绝，返回值为FALSE，而GetLastError值为ERROR_INVALID_PARAMETER。

尽管扩展服务器变量不存在(由其他服务器定义)，但支持GetServerVariable。GetServerVariable以及ALL_HTTP和ALL_RAW值都可以使用所有常用的 Apache CGI 环境变量。

从 httpd 2.0 开始，mod_isapi支持 ISAPI 规范的更高版本中引入的其他功能，以及异步 I/O 和TransmitFile语义的有限仿真。 Apache httpd 还支持预加载 ISAPI .dll 以提高性能。

ISAPIAppendLogToErrors Directive

将来自 ISAPI 扩展的HSE_APPEND_LOG_PARAMETER请求记录到服务器错误日志中。

ISAPIAppendLogToQuery Directive

将来自 ISAPI 扩展的HSE_APPEND_LOG_PARAMETER请求记录到查询字段(附加到CustomLog %q组件)中。

ISAPICacheFile Directive

指定以空格分隔的文件名列表，该文件名将在启动 Apache 服务器时加载，并保持加载状态，直到服务器关闭为止。可以为每个 ISAPI .dll 文件重复此指令。应该指定每个文件的完整路径名。如果路径名不是绝对的，则相对于ServerRoot对待。

ISAPIFakeAsync Directive

设置为 on 时，将模拟对 ISAPI 回调的异步支持。

ISAPILogNotSupported Directive

将来自 ISAPI 扩展的所有不支持功能的请求记录在服务器错误日志中。这可以帮助 Management 员查找问题。设置为打开并且所有所需的 ISAPI 模块都可以运行后，应将其重新设置为关闭。

ISAPIReadAheadBuffer Directive

定义在初始调用时发送给 ISAPI 扩展的预读缓冲区的最大大小。必须使用ReadClient回调检索所有剩余数据；某些 ISAPI 扩展可能不支持ReadClient函数。将问题转给 ISAPI 扩展的作者。