wrowe 00/09/26 08:23:16
Modified: htdocs/manual/mod mod_isapi.html
Log:
Some corrections, clarifications and new directives.
Hopefully in the new 'proper' form, but feel free to correct me.
Revision Changes Path
1.7 +258 -51 httpd-docs-1.3/htdocs/manual/mod/mod_isapi.html
Index: mod_isapi.html
===================================================================
RCS file: /home/cvs/httpd-docs-1.3/htdocs/manual/mod/mod_isapi.html,v
retrieving revision 1.6
retrieving revision 1.7
diff -u -r1.6 -r1.7
--- mod_isapi.html 2000/07/28 22:58:29 1.6
+++ mod_isapi.html 2000/09/26 15:23:14 1.7
@@ -16,58 +16,249 @@
<H1 ALIGN="CENTER">Module mod_isapi</H1>
-<P>This module is contained in the <CODE>mod_isapi.c</CODE> file, and is
- compiled into the Windows distribution by default. It provides support
for
- ISAPI Extensions when running under Microsoft Windows. Any document with
- a handler of <CODE>isapi-isa</CODE> will be processed by this module.</P>
-
-<H2>Purpose</H2>
-
-<P>This module implements the Internet Server Extension API. It allows
- Internet Server Applications (<EM>i.e.</EM>, ISAPI .dll handler modules)
- to be used with Apache for Windows, subject to the noted restrictions.</P>
+<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>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>
-<P>In the server configuration file, add a handler called
- <CODE>isapi-isa</CODE>, and map it to files with a <CODE>.DLL</CODE>
- extension. In other words:</P>
<PRE>
AddHandler isapi-isa dll
</PRE>
-<P>Now simply place the ISA DLLs into your document root, and they will
- be loaded when their URLs are accessed.</P>
-<P>ISAPI Extensions are governed by the same restrictions as CGI
- scripts. That is, <CODE>Options ExecCGI</CODE> must be active in the
- directory that contains the ISA.</P>
+<P>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>Now place an ISAPI .dll file into this web directory, with the
+ <CODE>Options ExecCGI</CODE> set properly, and it will be loaded and
+ executed when requested by its URL.</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>Directives</H2>
+<UL>
+<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>
+<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 <EM>on|off</EM><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 <EM>on|off</EM><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 <EM>on|off</EM><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>
+<HR>
-<H2>Notes</H2>
+<H2><A NAME="notes">Additional Notes</A></H2>
<P>Apache's ISAPI implementation conforms to all of the ISAPI 2.0
specification, except for the "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 async I/O, a message will be place in the error log,
- to help with debugging.
+ 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, a new directive;
+ <CODE>ISAPILogNotSupported Off</CODE>, is introduced in Apache 1.3.13.</P>
<P>Some servers, like Microsoft IIS, load the ISA into the server, and
- keep it loaded until memory usage is too high, and it is
- unloaded. Apache currently loads and unloads the ISA for each
- request. This is inefficient, but Apache's request model makes this
- method the only method that currently works. A future release may use
- a more effective loading method.
-
-<P>Apache 1.3a1 currently limits POST and PUT input to 48k per
- request. This is to work around a problem with the ISAPI implementation
- that could result in a denial of service attack. It is expected that
- support for larger uploads will be added soon.
-
-<P>Also, remember that while Apache supports ISAPI Extensions, it does
- not support ISAPI Filters. Support for filters may be added at a later
- date, but no support is planned at this time.</P>
+ keep it loaded until memory usage is too high, or specific configuration
+ options are used. Apache currently loads and unloads the ISA for each
+ request. This is inefficient, but Apache's request model makes this
+ method the only method that currently works. Apache 2.0 is expected to
+ support more effective loading and caching methods, with more precise
+ control over individual ISAPI modules and directories.</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>Programmer's Journal</H2>
+<H2><A NAME="journal">Programmer's Journal</A></H2>
<P>If you are programming Apache 1.3 mod_isapi modules, you must limit your
calls to ServerSupportFunction to the following directives:</P>
@@ -90,35 +281,51 @@
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_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)
- <DT>HSE_REQ_MAP_URL_TO_PATH
- <DD>Apache will translate a virtual name to a physical name.
<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 <EM>Apache 1.3.13 and later</EM>
+ <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 <EM>Apache 1.3.13 and later</EM>
+ <DD>Will return the negotiated Keep-Alive status.
+ <DT>HSE_REQ_SEND_RESPONSE_HEADER_EX <EM>Apache 1.3.13 and later</EM>
+ <DD>Will behave as documented, although the fKeepConn flag is ignored.
+ <DT>HSE_REQ_IS_CONNECTED <EM>Apache 1.3.13 and later</EM>
+ <DD>Will report false if the request has been aborted.
</DL>
-<P>Apache returns FALSE to any other call to ServerSupportFunction, and
+<P>Apache returns FALSE to any unsupported call to ServerSupportFunction, and
sets the GetLastError value to ERROR_INVALID_PARAMETER.</P>
-<P>ReadClient is not truly supported. The entire body of the message,
- up to 49152 bytes, is sent to the client in the initial request.
- If the request is longer, the ISAPI extension is never called.
- Calling ReadClient, however, does no harm.</P>
+<P>Prior to Apache 1.3.13, ReadClient was a noop, and any request with a
request
+ body greater than 48kb was rejected by mod_isapi. As of Apache 1.3.13,
+ ReadClient now 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.) In general, all CGI
- environment variables are available through GetServerVariable.</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 of Apache 1.3.13,
+ the ALL_HTTP and ALL_RAW and variables are now available.</P>
-<P>Apache 2.0 mod_isapi will support additional features introduced in later
+<P>Apache 2.0 mod_isapi may support additional features introduced in later
versions of the ISAPI specification, as well as limited emulation of
async I/O and the TransmitFile semantics. Apache 2.0 may also support
caching of ISAPI .dlls for performance. No further enhancements to the
