mirror of
https://github.com/apache/httpd.git
synced 2025-10-30 08:05:39 +03:00
e3489b6948
git-svn-id: https://svn.apache.org/repos/asf/httpd/httpd/trunk@87273 13f79535-47bb-0310-9956-ffa450edef68
377 lines
13 KiB
HTML
377 lines
13 KiB
HTML
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN">
|
|
<HTML>
|
|
<HEAD>
|
|
<TITLE>Apache module mod_isapi</TITLE>
|
|
</HEAD>
|
|
|
|
<!-- Background white, links blue (unvisited), navy (visited), red (active) -->
|
|
<BODY
|
|
BGCOLOR="#FFFFFF"
|
|
TEXT="#000000"
|
|
LINK="#0000FF"
|
|
VLINK="#000080"
|
|
ALINK="#FF0000"
|
|
>
|
|
<!--#include virtual="header.html" -->
|
|
|
|
<H1 ALIGN="CENTER">Module mod_isapi</H1>
|
|
|
|
<P>This module supports ISAPI Extensions within Apache for Windows.</P>
|
|
|
|
<P><A
|
|
HREF="module-dict.html#Status"
|
|
REL="Help"
|
|
><STRONG>Status:</STRONG></A> Base
|
|
<BR>
|
|
<A
|
|
HREF="module-dict.html#SourceFile"
|
|
REL="Help"
|
|
><STRONG>Source File:</STRONG></A> mod_isapi.c
|
|
<BR>
|
|
<A
|
|
HREF="module-dict.html#ModuleIdentifier"
|
|
REL="Help"
|
|
><STRONG>Module Identifier:</STRONG></A> isapi_module
|
|
<BR>
|
|
<A
|
|
HREF="module-dict.html#Compatibility"
|
|
REL="Help"
|
|
><STRONG>Compatibility:</STRONG></A> WIN32 only
|
|
</P>
|
|
|
|
<H2>Summary</H2>
|
|
|
|
<P>This module implements the Internet Server extension API. It allows
|
|
Internet Server extensions (<EM>e.g.</EM> ISAPI .dll modules) to be
|
|
served by Apache for Windows, subject to the noted restrictions.</P>
|
|
|
|
<P>ISAPI extension modules (.dll files) are written by third parties. The
|
|
Apache Group does not author these modules, so we provide no support for
|
|
them. Please contact the ISAPI's author directly if you are experiencing
|
|
problems running their ISAPI extention. <STRONG>Please <EM>do not</EM>
|
|
post such problems to Apache's lists or bug reporting pages.</STRONG></P>
|
|
|
|
<H2>Directives</H2>
|
|
<UL>
|
|
<LI><A HREF="#isapifilecache">ISAPIFileCache</A>
|
|
<LI><A HREF="#isapireadaheadbuffer">ISAPIReadAheadBuffer</A>
|
|
<LI><A HREF="#isapilognotsupported">ISAPILogNotSupported</A>
|
|
<LI><A HREF="#isapiappendlogtoerrors">ISAPIAppendLogToErrors</A>
|
|
<LI><A HREF="#isapiappendlogtoquery">ISAPIAppendLogToQuery</A>
|
|
</UL>
|
|
|
|
<H2>Usage</H2>
|
|
|
|
<P>In the server configuration file, use the AddHandler directive to
|
|
associate ISAPI files with the <CODE>isapi-isa</CODE> handler, and map
|
|
it to the with their file extensions. To enable any .dll file to be
|
|
processed as an ISAPI extention, edit the httpd.conf file and add the
|
|
following line:</P>
|
|
|
|
<PRE>
|
|
AddHandler isapi-isa .dll
|
|
</PRE>
|
|
|
|
<P>There is no capability within the Apache server to leave a requested
|
|
module loaded. However, you may preload and keep a specific module loaded
|
|
by using the following syntax in your httpd.conf:
|
|
|
|
<PRE>
|
|
ISAPICacheFile c:/WebWork/Scripts/ISAPI/mytest.dll
|
|
</PRE>
|
|
|
|
<P>Whether or not you have preloaded an ISAPI extension, all ISAPI
|
|
extensions are governed by the same permissions and restrictions
|
|
as CGI scripts. That is, <CODE>Options ExecCGI</CODE> must be set for
|
|
the directory that contains the ISAPI .dll file.</P>
|
|
|
|
<P>Review the <A HREF="#notes">Additional Notes</A> and the
|
|
<A HREF="#journal">Programmer's Journal</A> for additional details and
|
|
clarification of the specific ISAPI support offered by mod_isapi.</P>
|
|
|
|
<H2><A NAME="notes">Additional Notes</A></H2>
|
|
|
|
<P>Apache's ISAPI implementation conforms to all of the ISAPI 2.0
|
|
specification, except for some "Microsoft-specific" extensions dealing
|
|
with asynchronous I/O. Apache's I/O model does not allow asynchronous
|
|
reading and writing in a manner that the ISAPI could access. If an ISA
|
|
tries to access unsupported features, including async I/O, a message is
|
|
placed in the error log to help with debugging. Since these messages
|
|
can become a flood, the directive <CODE>ISAPILogNotSupported Off</CODE>
|
|
exists to quiet this noise.</P>
|
|
|
|
<P>Some servers, like Microsoft IIS, load the ISAPI extension into the server
|
|
and keep it loaded until memory usage is too high, or unless configuration
|
|
options are specified. Apache currently loads and unloads the ISAPI
|
|
extension each time it is requested, unless the ISAPICacheFile directive
|
|
is specified. This is inefficient, but Apache's memory model makes this
|
|
the most effective method. Many ISAPI modules are subtly incompatible
|
|
with the Apache server, and unloading these modules helps to ensure the
|
|
stability of the server.</P>
|
|
|
|
<P>Also, remember that while Apache supports ISAPI Extensions, it
|
|
<STRONG>does not support ISAPI Filters.</STRONG> Support for filters may
|
|
be added at a later date, but no support is planned at this time.</P>
|
|
|
|
<H2><A NAME="journal">Programmer's Journal</A></H2>
|
|
|
|
<P>If you are programming Apache 2.0 mod_isapi modules, you must limit your
|
|
calls to ServerSupportFunction to the following directives:</P>
|
|
|
|
<DL>
|
|
<DT>HSE_REQ_SEND_URL_REDIRECT_RESP
|
|
<DD>Redirect the user to another location.<BR>
|
|
This must be a fully qualified URL (e.g. http://server/location).
|
|
<DT>HSE_REQ_SEND_URL
|
|
<DD>Redirect the user to another location.<BR>
|
|
This cannot be a fully qualified URL, you are not allowed
|
|
to pass the protocol or a server name (e.g. simply /location).<BR>
|
|
This redirection is handled by the server, not the browser.<BR>
|
|
<STRONG>Warning:</STRONG> in their recent documentation, Microsoft
|
|
appears to have abandoned the distinction between the two
|
|
HSE_REQ_SEND_URL functions. Apache continues to treat them as two
|
|
distinct functions with different requirements and behaviors.
|
|
<DT>HSE_REQ_SEND_RESPONSE_HEADER
|
|
<DD>Apache accepts a response body following the header if it follows
|
|
the blank line (two consecutive newlines) in the headers string
|
|
argument. This body cannot contain NULLs, since the headers
|
|
argument is NULL terminated.
|
|
<DT>HSE_REQ_DONE_WITH_SESSION
|
|
<DD>Apache considers this a no-op, since the session will be finished
|
|
when the ISAPI returns from processing.
|
|
<DT>HSE_REQ_MAP_URL_TO_PATH
|
|
<DD>Apache will translate a virtual name to a physical name.
|
|
<DT>HSE_APPEND_LOG_PARAMETER
|
|
<DD>This logged message may be captured in any of the following logs:
|
|
<UL>
|
|
<LI>in the \"%{isapi-parameter}n\" component in a CustomLog directive
|
|
<LI>in the %q log component with the ISAPIAppendLogToQuery On directive
|
|
<LI>in the error log with the ISAPIAppendLogToErrors On directive
|
|
</UL>
|
|
The first option, the %{isapi-parameter}n component, is always available
|
|
and prefered.
|
|
<DT>HSE_REQ_IS_KEEP_CONN
|
|
<DD>Will return the negotiated Keep-Alive status.
|
|
<DT>HSE_REQ_SEND_RESPONSE_HEADER_EX
|
|
<DD>Will behave as documented, although the fKeepConn flag is ignored.
|
|
<DT>HSE_REQ_IS_CONNECTED
|
|
<DD>Will report false if the request has been aborted.
|
|
</DL>
|
|
|
|
<P>Apache returns FALSE to any unsupported call to ServerSupportFunction, and
|
|
sets the GetLastError value to ERROR_INVALID_PARAMETER.</P>
|
|
|
|
<P>ReadClient retrieves the request body exceeding the initial buffer
|
|
(defined by ISAPIReadAheadBuffer). Based on the ISAPIReadAheadBuffer
|
|
setting (number of bytes to buffer prior to calling the ISAPI handler)
|
|
shorter requests are sent complete to the extension when it is invoked.
|
|
If the request is longer, the ISAPI extension must use ReadClient to
|
|
retrieve the remaining request body.</P>
|
|
|
|
<P>WriteClient is supported, but only with the HSE_IO_SYNC flag or
|
|
no option flag (value of 0). Any other WriteClient request will
|
|
be rejected with a return value of FALSE, and a GetLastError
|
|
value of ERROR_INVALID_PARAMETER.</P>
|
|
|
|
<P>GetServerVariable is supported, although extended server variables do not
|
|
exist (as defined by other servers.) All the usual Apache CGI environment
|
|
variables are available from GetServerVariable, as well as the ALL_HTTP
|
|
and ALL_RAW values.</P>
|
|
|
|
<P>Apache 2.0 mod_isapi supports additional features introduced in later
|
|
versions of the ISAPI specification, as well as limited emulation of
|
|
async I/O and the TransmitFile semantics. Apache also supports preloading
|
|
ISAPI .dlls for performance, neither of which were not available under
|
|
Apache 1.3 mod_isapi.</P>
|
|
|
|
<HR>
|
|
|
|
<H2><A NAME="isapifilecache">ISAPIFileCache directive</A></H2>
|
|
<!--%plaintext <?INDEX {\tt ISAPIFileCache} directive> -->
|
|
<A
|
|
HREF="directive-dict.html#Syntax"
|
|
REL="Help"
|
|
><STRONG>Syntax:</STRONG></A> ISAPIFileCache <EM>file</em> [<em>file</em>] ...<BR>
|
|
<A
|
|
HREF="directive-dict.html#Context"
|
|
REL="Help"
|
|
><STRONG>Context:</STRONG></A> server config<BR>
|
|
<A
|
|
HREF="directive-dict.html#Override"
|
|
REL="Help"
|
|
><STRONG>Override:</STRONG></A> None<BR>
|
|
<A
|
|
HREF="directive-dict.html#Status"
|
|
REL="Help"
|
|
><STRONG>Status:</STRONG></A> Base<BR>
|
|
<A
|
|
HREF="directive-dict.html#Module"
|
|
REL="Help"
|
|
><STRONG>Module:</STRONG></A> mod_isapi<BR>
|
|
<A
|
|
HREF="module-dict.html#Compatibility"
|
|
REL="Help"
|
|
><STRONG>Compatibility:</STRONG></A> Apache 2.0 and later, Win32 only<P>
|
|
|
|
Specifies a space-separated list of file names to be loaded
|
|
when the Apache server is launched, and remain loaded until
|
|
the server is shut down. This directive may be repeated
|
|
for every ISAPI .dll file desired. The full path name of
|
|
each file should be specified.
|
|
<P>
|
|
<HR>
|
|
|
|
<H2><A NAME="isapireadaheadbuffer">ISAPIReadAheadBuffer directive</A></H2>
|
|
<!--%plaintext <?INDEX {\tt ISAPIReadAheadBuffer} directive> -->
|
|
<A
|
|
HREF="directive-dict.html#Syntax"
|
|
REL="Help"
|
|
><STRONG>Syntax:</STRONG></A> ISAPIReadAheadBuffer <EM>size</EM><BR>
|
|
<A
|
|
HREF="directive-dict.html#Default"
|
|
REL="Help"
|
|
><STRONG>Default:</STRONG></A> 49152<BR>
|
|
<A
|
|
HREF="directive-dict.html#Context"
|
|
REL="Help"
|
|
><STRONG>Context:</STRONG></A> server config<BR>
|
|
<A
|
|
HREF="directive-dict.html#Override"
|
|
REL="Help"
|
|
><STRONG>Override:</STRONG></A> None<BR>
|
|
<A
|
|
HREF="directive-dict.html#Status"
|
|
REL="Help"
|
|
><STRONG>Status:</STRONG></A> Base<BR>
|
|
<A
|
|
HREF="directive-dict.html#Module"
|
|
REL="Help"
|
|
><STRONG>Module:</STRONG></A> mod_isapi<BR>
|
|
<A
|
|
HREF="module-dict.html#Compatibility"
|
|
REL="Help"
|
|
><STRONG>Compatibility:</STRONG></A> Apache 1.3.13 and later, Win32 only<P>
|
|
|
|
|
|
Defines the maximum size of the Read Ahead Buffer sent to
|
|
ISAPI extentions when they are initally invoked. All
|
|
remaining data must be retrieved using the ReadClient
|
|
callback; some ISAPI extensions may not support the
|
|
ReadClient function. Refer questions to the ISAPI extention's
|
|
author.
|
|
<P>
|
|
<HR>
|
|
|
|
<H2><A NAME="isapilognotsupported">ISAPILogNotSupported directive</A></H2>
|
|
<!--%plaintext <?INDEX {\tt ISAPILogNotSupported} directive> -->
|
|
<A
|
|
HREF="directive-dict.html#Syntax"
|
|
REL="Help"
|
|
><STRONG>Syntax:</STRONG></A> ISAPILogNotSupported on|off<BR>
|
|
<A
|
|
HREF="directive-dict.html#Default"
|
|
REL="Help"
|
|
><STRONG>Default:</STRONG></A> on<BR>
|
|
<A
|
|
HREF="directive-dict.html#Context"
|
|
REL="Help"
|
|
><STRONG>Context:</STRONG></A> server config<BR>
|
|
<A
|
|
HREF="directive-dict.html#Override"
|
|
REL="Help"
|
|
><STRONG>Override:</STRONG></A> None<BR>
|
|
<A
|
|
HREF="directive-dict.html#Status"
|
|
REL="Help"
|
|
><STRONG>Status:</STRONG></A> Base<BR>
|
|
<A
|
|
HREF="directive-dict.html#Module"
|
|
REL="Help"
|
|
><STRONG>Module:</STRONG></A> mod_isapi<BR>
|
|
<A
|
|
HREF="module-dict.html#Compatibility"
|
|
REL="Help"
|
|
><STRONG>Compatibility:</STRONG></A> Apache 1.3.13 and later, Win32 only<P>
|
|
|
|
Logs all requests for unsupported features from ISAPI extentions
|
|
in the server error log. While this should be turned off once
|
|
all desired ISAPI modules are functioning, it defaults to on
|
|
to help administrators track down problems.
|
|
<P>
|
|
<HR>
|
|
|
|
<H2><A NAME="isapiappendlogtoerrors">ISAPIAppendLogToErrors directive</A></H2>
|
|
<!--%plaintext <?INDEX {\tt ISAPIAppendLogToErrors} directive> -->
|
|
<A
|
|
HREF="directive-dict.html#Syntax"
|
|
REL="Help"
|
|
><STRONG>Syntax:</STRONG></A> ISAPIAppendLogToErrors on|off<BR>
|
|
<A
|
|
HREF="directive-dict.html#Default"
|
|
REL="Help"
|
|
><STRONG>Default:</STRONG></A> off<BR>
|
|
<A
|
|
HREF="directive-dict.html#Context"
|
|
REL="Help"
|
|
><STRONG>Context:</STRONG></A> server config<BR>
|
|
<A
|
|
HREF="directive-dict.html#Override"
|
|
REL="Help"
|
|
><STRONG>Override:</STRONG></A> None<BR>
|
|
<A
|
|
HREF="directive-dict.html#Status"
|
|
REL="Help"
|
|
><STRONG>Status:</STRONG></A> Base<BR>
|
|
<A
|
|
HREF="directive-dict.html#Module"
|
|
REL="Help"
|
|
><STRONG>Module:</STRONG></A> mod_isapi<BR>
|
|
<A
|
|
HREF="module-dict.html#Compatibility"
|
|
REL="Help"
|
|
><STRONG>Compatibility:</STRONG></A> Apache 1.3.13 and later, Win32 only<P>
|
|
|
|
Record HSE_APPEND_LOG_PARAMETER requests from ISAPI extentions
|
|
to the server error log.
|
|
<P>
|
|
<HR>
|
|
|
|
<H2><A NAME="isapiappendlogtoquery">ISAPIAppendLogToQuery directive</A></H2>
|
|
<!--%plaintext <?INDEX {\tt ISAPIAppendLogToQuery} directive> -->
|
|
<A
|
|
HREF="directive-dict.html#Syntax"
|
|
REL="Help"
|
|
><STRONG>Syntax:</STRONG></A> ISAPIAppendLogToQuery on|off<BR>
|
|
<A
|
|
HREF="directive-dict.html#Default"
|
|
REL="Help"
|
|
><STRONG>Default:</STRONG></A> off<BR>
|
|
<A
|
|
HREF="directive-dict.html#Context"
|
|
REL="Help"
|
|
><STRONG>Context:</STRONG></A> server config<BR>
|
|
<A
|
|
HREF="directive-dict.html#Override"
|
|
REL="Help"
|
|
><STRONG>Override:</STRONG></A> None<BR>
|
|
<A
|
|
HREF="directive-dict.html#Status"
|
|
REL="Help"
|
|
><STRONG>Status:</STRONG></A> Base<BR>
|
|
<A
|
|
HREF="directive-dict.html#Module"
|
|
REL="Help"
|
|
><STRONG>Module:</STRONG></A> mod_isapi<BR>
|
|
<A
|
|
HREF="module-dict.html#Compatibility"
|
|
REL="Help"
|
|
><STRONG>Compatibility:</STRONG></A> Apache 1.3.13 and later, Win32 only<P>
|
|
|
|
Record HSE_APPEND_LOG_PARAMETER requests from ISAPI extentions
|
|
to the query field (appended to the CustomLog %q component).
|
|
<P>
|
|
|
|
<!--#include virtual="footer.html" -->
|
|
</BODY>
|
|
</HTML>
|