# Apache模塊 mod_isapi | [說明](#calibre_link-11) | 僅限于在Windows平臺上實現ISAPI擴展 | | --- | --- | | [狀態](#calibre_link-12) | 基本(B) | | [模塊名](#calibre_link-13) | isapi_module | | [源文件](#calibre_link-14) | mod_isapi.c | | [兼容性](#calibre_link-58) | 僅用于Win32 | ### 概述 本模塊實現了互聯網服務擴展應用程序編程接口(Internet Server extension API)。本模塊使得Windows上的Apache能有限地實現互聯網服務擴展(比如調用ISAPI的動態連接庫)。 ISAPI擴展模塊(.dll文件)是由第三方開發的。Apache開發組沒有編寫這些模塊，因此我們也不對它們提供支持。如果在運行ISAPI擴展過程中發生問題，請直接與ISAPI的作者聯系。**請_不要_將此類問題貼在Apache的郵件列表或錯誤反饋頁面上**。 ## 用法 在服務器配置文件中，使用`AddHandler`指令將`isapi-isa`處理器與ISAPI文件關聯起來，并通過文件擴展名來建議對應關系。要將任何一個.dll文件作為ISAPI擴展來處理，需要編輯httpd.conf文件，并加入以下行： ``` AddHandler isapi-isa .dll ``` Apache服務器不允許將服務于請求的模塊動態地加載，但可以通過在httpd.conf文件中，加入以下語句使一個模塊在Apache啟動時預先載入系統，并使其駐留在系統中： ``` ISAPICacheFile c:/WebWork/Scripts/ISAPI/mytest.dll ``` 無論是否預載一個ISAPI擴展，所有的ISAPI擴展都使用與CGI腳本相同的許可限制來管理。也就是說，包含ISAPI動態連接庫的目錄必須要設置"`Options` `ExecCGI`"。 請參閱[附加注釋](#calibre_link-154)和[程序員注記](#calibre_link-155)以得到關于`mod_isapi`所提供的特定的ISAPI支持的細節內容。 ## 附加注釋 Apache的ISAPI實現了除部分用來處理異步I/O的微軟特定(Microsoft-specific)擴展以外的所有ISAPI 2.0規范。Apache的I/O模型不允許使用ISAPI可能用到的異步讀寫方式。如果ISAPI試圖調用不支持的功能，包括異步I/O，在錯誤日志中會顯示一條錯誤信息以方便系統的調試。由于這類錯誤信息可能會大量地產生，指令"`ISAPILogNotSupported Off`"可以使這類錯誤信息不被記錄。 在某些服務器上，比如微軟的IIS，ISAPI擴展在載入后將駐留在服務器上，直到內存占用過高，或是指定了不同的配置選項。Apache目前在每次請求時，都會加載和卸載特定的ISAPI擴展，除非指定了`ISAPICacheFile`指令。雖然這樣看來是效率很低的一種做法，但根據Apache的內存模式使用這種方式是最有效的。許多ISAPI模塊與Apache服務器有細微的兼容性問題，卸載這些模塊可以保證服務器的穩定運行。 同時請記住Apache支持ISAPI擴展，但它**不支持ISAPI過濾器**。對于ISAPI過濾器的支持可能會在晚些時候加入，但目前沒有支持這一功能的計劃。 ## 程序員注記 如果你正在開發 Apache 2.0 `mod_isapi`模塊，你必須嚴格按照以下指令的限制來調用`ServerSupportFunction` ： `HSE_REQ_SEND_URL_REDIRECT_RESP` 重定向用戶到其它的位置。必須使用完整的、合法的URL(比如：`http://server/location`)。 `HSE_REQ_SEND_URL` 重定向用戶到其它的位置。這里不能使用一個完整的URL，你不可以傳入協議或服務器名(例如：`/location`)。這類重定向由服務器來處理，不是瀏覽器。 ### 警告 在最近發布的文檔中，微軟已經試圖放棄這兩個`HSE_REQ_SEND_URL`函數的差別。但Apache還是將它們視為兩個不同的函數加以不同的實現。 `HSE_REQ_SEND_RESPONSE_HEADER` 如果在請求頭字符串變量中，請求頭的內容后面緊跟一個空行(兩個連續的換行)，然后再加上請求體的內容，Apache能接受這一相應的請求體。因為請求頭變量是以NULL結束的，這個請求體里不能包含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` 如果請求退出則報告錯誤。 對于所有不支持的`ServerSupportFunction`調用，Apache返回`FALSE` ，同時將`GetLastError`的值置為`ERROR_INVALID_PARAMETER` 。 `ReadClient`越過初始緩沖區(由`ISAPIReadAheadBuffer`指令定義)得到請求的數據包。根據`ISAPIReadAheadBuffer`(在調用ISAPI處理前緩沖的數據字節數)的設定，較小的請求包當請求被調用時，直接完全地傳送到ISAPI擴展。如果請求包很長，ISAPI擴展必須使用`ReadClient`得到剩下的請求數據。 支持`WriteClient` ，但只能使用`HSE_IO_SYNC`標志或不帶標志("`0`"值)。任何其它的`WriteClient`請求會被拒絕，并且返回`FALSE` ，同時`GetLastError`的值被置為`ERROR_INVALID_PARAMETER` 。 支持`GetServerVariable` ，雖然擴展服務變量不存在(定義在其它服務器上)。包括`ALL_HTTP`和`ALL_RAW` ，所有的常規Apache CGI環境變量都可以通過`GetServerVariable`得到。 Apache 2.0 `mod_isapi`支持后來版本的ISAPI規范中的新增功能，比如對異步I/O的有限仿真及`TransmitFile`語義。Apache同時也支持ISAPI .dlls 的預載入以提高性能，以上這些在 Apache1.3 `mod_isapi`都沒有實現。 ## ISAPIAppendLogToErrors 指令 | [說明](#calibre_link-18) | 把ISAPI擴展的`HSE_APPEND_LOG_PARAMETER`請求記錄在錯誤日志中 | | --- | --- | | [語法](#calibre_link-19) | `ISAPIAppendLogToErrors on|off` | | [默認值](#calibre_link-24) | `ISAPIAppendLogToErrors off` | | [作用域](#calibre_link-20) | server config, virtual host, directory, .htaccess | | [覆蓋項](#calibre_link-66) | FileInfo | | [狀態](#calibre_link-21) | 基本(B) | | [模塊](#calibre_link-22) | mod_isapi | 把ISAPI擴展的`HSE_APPEND_LOG_PARAMETER`請求記錄在錯誤日志中 ## ISAPIAppendLogToQuery 指令 | [說明](#calibre_link-18) | 把ISAPI擴展的`HSE_APPEND_LOG_PARAMETER`請求記錄在查詢域中 | | --- | --- | | [語法](#calibre_link-19) | `ISAPIAppendLogToQuery on|off` | | [默認值](#calibre_link-24) | `ISAPIAppendLogToQuery on` | | [作用域](#calibre_link-20) | server config, virtual host, directory, .htaccess | | [覆蓋項](#calibre_link-66) | FileInfo | | [狀態](#calibre_link-21) | 基本(B) | | [模塊](#calibre_link-22) | mod_isapi | 把ISAPI擴展的`HSE_APPEND_LOG_PARAMETER`請求記錄在查詢域中(追加在`CustomLog` `%q`元素后面)。 ## ISAPICacheFile 指令 | [說明](#calibre_link-18) | 啟動時載入的ISAPI動態連接庫 | | --- | --- | | [語法](#calibre_link-19) | `ISAPICacheFile file-path [file-path] ...` | | [作用域](#calibre_link-20) | server config, virtual host | | [狀態](#calibre_link-21) | 基本(B) | | [模塊](#calibre_link-22) | mod_isapi | 指定一個需在Apache服務啟動的時候載入的以空格分隔的文件列表，這些文件駐留在系統中直至服務器關閉。本指令可以為每個需要的ISAPI動態連接庫文件所重復。應指定每個文件的路徑。如果不是絕對路徑，則會基于`ServerRoot`來處理相對路徑。 ## ISAPIFakeAsync 指令 | [說明](#calibre_link-18) | 為ISAPI回調模擬異步支持 | | --- | --- | | [語法](#calibre_link-19) | `ISAPIFakeAsync on|off` | | [默認值](#calibre_link-24) | `ISAPIFakeAsync off` | | [作用域](#calibre_link-20) | server config, virtual host, directory, .htaccess | | [覆蓋項](#calibre_link-66) | FileInfo | | [狀態](#calibre_link-21) | 基本(B) | | [模塊](#calibre_link-22) | mod_isapi | 當設為on時，模擬ISAPI回調的異步支持。 ## ISAPILogNotSupported 指令 | [說明](#calibre_link-18) | 記錄ISAPI不支持的功能調用 | | --- | --- | | [語法](#calibre_link-19) | `ISAPILogNotSupported on|off` | | [默認值](#calibre_link-24) | `ISAPILogNotSupported off` | | [作用域](#calibre_link-20) | server config, virtual host, directory, .htaccess | | [覆蓋項](#calibre_link-66) | FileInfo | | [狀態](#calibre_link-21) | 基本(B) | | [模塊](#calibre_link-22) | mod_isapi | 在服務錯誤日志中記錄所有ISAPI擴展不支持的請求。本指令可以幫助系統管理員跟蹤錯誤。把這個指令定義為on以后，如果所有的ISAPI模塊都工作良好，應該把它設回為Off。 ## ISAPIReadAheadBuffer 指令 | [說明](#calibre_link-18) | 傳送到ISAPI擴展的預讀緩沖區大小 | | --- | --- | | [語法](#calibre_link-19) | `ISAPIReadAheadBuffer size` | | [默認值](#calibre_link-24) | `ISAPIReadAheadBuffer 49152` | | [作用域](#calibre_link-20) | server config, virtual host, directory, .htaccess | | [覆蓋項](#calibre_link-66) | FileInfo | | [狀態](#calibre_link-21) | 基本(B) | | [模塊](#calibre_link-22) | mod_isapi | 定義初始調用時傳送到ISAPI擴展的最大預讀緩沖區大小。所有其它的數據必須通過`ReadClient`回調功能得到；部分ISAPI擴展可能不支持`ReadClient`功能。請參考ISAPI擴展本身對相關問題描述。