Модуль Apache mod_isapi

Краткое описание

Этот модуль реализует API расширений Internet Server. Он позволяет обслуживать расширения Internet Server (например, модули ISAPI .dll) с помощью Apache для Windows с учетом указанных ограничений.

Модули расширений ISAPI (файлы .dll) создаются сторонними разработчиками. Группа Apache не разрабатывает эти модули и поэтому не оказывает поддержку по их использованию. Если у вас возникли проблемы при запуске расширения ISAPI, обратитесь непосредственно к его автору. Пожалуйста, не публикуйте такие проблемы в списках рассылки Apache или на страницах для сообщений об ошибках.

Использование

В файле конфигурации сервера используйте директиву AddHandler, чтобы связать файлы ISAPI с обработчиком isapi-handler, и сопоставьте их по расширениям файлов. Чтобы разрешить обработку любого файла .dll в качестве расширения ISAPI, отредактируйте файл httpd.conf и добавьте следующую строку:

AddHandler isapi-handler .dll

Сервер Apache не позволяет оставлять запрошенный модуль загруженным. Однако можно предварительно загрузить определенный модуль и оставить его загруженным, используя следующий синтаксис в файле httpd.conf:

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

Независимо от того, загружено ли расширение ISAPI предварительно, на все расширения ISAPI распространяются те же разрешения и ограничения, что и на сценарии CGI. То есть для каталога, содержащего файл ISAPI .dll, необходимо задать Options ExecCGI.

Дополнительные сведения и разъяснения об особенностях поддержки ISAPI, предоставляемой mod_isapi, см. в разделах Дополнительные примечания и Заметки программиста.

Дополнительные примечания

Реализация ISAPI в Apache соответствует спецификации ISAPI 2.0, за исключением некоторых «специфичных для Microsoft» расширений, связанных с асинхронным вводом-выводом. Модель ввода-вывода Apache не позволяет выполнять асинхронное чтение и запись способом, доступным для ISAPI. Если ISA пытается обратиться к неподдерживаемым функциям, включая асинхронный ввод-вывод, в журнал ошибок записывается сообщение, помогающее при отладке. Поскольку такие сообщения могут накапливаться в большом количестве, для подавления этого потока предусмотрена директива ISAPILogNotSupported Off.

Некоторые серверы, например Microsoft IIS, загружают расширение ISAPI в сервер и оставляют его загруженным, пока использование памяти не станет слишком высоким или пока не будут заданы соответствующие параметры конфигурации. Apache в настоящее время загружает и выгружает расширение ISAPI при каждом запросе, если не указана директива ISAPICacheFile. Это неэффективно, но с учетом модели памяти Apache такой способ оказывается наиболее действенным. Многие модули ISAPI имеют малозаметные проблемы совместимости с сервером Apache; выгрузка этих модулей помогает обеспечить стабильность сервера.

Также следует помнить: хотя Apache поддерживает расширения ISAPI, он не поддерживает фильтры ISAPI. Поддержка фильтров может быть добавлена позднее, но в настоящее время ее разработка не планируется.

Заметки программиста

При программировании модулей mod_isapi для Apache 2.0 необходимо ограничить вызовы ServerSupportFunction следующими директивами:

HSE_REQ_SEND_URL_REDIRECT_RESP

Перенаправляет пользователя в другое место.
Это должен быть полностью квалифицированный URL (например, http://server/location).

HSE_REQ_SEND_URL

Перенаправляет пользователя в другое место.
Это не может быть полностью квалифицированный URL; передавать протокол или имя сервера нельзя (например, просто /location).
Это перенаправление обрабатывается сервером, а не браузером.

Предупреждение

В своей недавней документации Microsoft, по-видимому, отказалась от различия между двумя функциями 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

Это записанное сообщение может быть сохранено в любом из следующих журналов:

• в компоненте \"%{isapi-parameter}n\" директивы CustomLog
• в компоненте журнала %q с директивой ISAPIAppendLogToQuery On
• в журнале ошибок с директивой ISAPIAppendLogToErrors On

Первый вариант — компонент %{isapi-parameter}n — всегда доступен и является предпочтительным.

HSE_REQ_IS_KEEP_CONN

Возвращает согласованный статус Keep-Alive.

HSE_REQ_SEND_RESPONSE_HEADER_EX

Работает согласно документации, хотя флаг fKeepConn игнорируется.

HSE_REQ_IS_CONNECTED

Возвращает false, если запрос был прерван.

При любом неподдерживаемом вызове ServerSupportFunction Apache возвращает FALSE и устанавливает значение GetLastError в ERROR_INVALID_PARAMETER.

ReadClient получает тело запроса, превышающее размер исходного буфера (определяется ISAPIReadAheadBuffer). В зависимости от значения ISAPIReadAheadBuffer (количества байтов, буферизуемых до вызова обработчика ISAPI) короткие запросы полностью передаются расширению при его вызове. Если запрос длиннее, расширение ISAPI должно использовать ReadClient для получения оставшейся части тела запроса.

WriteClient поддерживается, но только с флагом HSE_IO_SYNC или без флага параметра (значение 0). Любой другой запрос WriteClient будет отклонен с возвращаемым значением FALSE и значением GetLastError, равным ERROR_INVALID_PARAMETER.

GetServerVariable поддерживается, хотя расширенные переменные сервера не существуют (в отличие от других серверов). Все стандартные переменные среды CGI Apache доступны через GetServerVariable, а также значения ALL_HTTP и ALL_RAW.

Начиная с httpd 2.0, mod_isapi поддерживает дополнительные функции, появившиеся в более поздних версиях спецификации ISAPI, а также ограниченную эмуляцию асинхронного ввода-вывода и семантику TransmitFile. Apache httpd также поддерживает предварительную загрузку файлов ISAPI .dll для повышения производительности.

ISAPIAppendLogToErrors on|off

ISAPIAppendLogToErrors off

ISAPIAppendLogToQuery on|off

ISAPIAppendLogToQuery on

ISAPICacheFile file-path [file-path] ...

ISAPIFakeAsync on|off

ISAPIFakeAsync off

ISAPILogNotSupported on|off

ISAPILogNotSupported off

ISAPIReadAheadBuffer size

ISAPIReadAheadBuffer 49152