Mailing List Archive: cvs commit: httpd-docs-1.3/htdocs/manual/mod mod

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>

-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.
-
-<H2>Purpose</H2>
-
-This module implements the Internet Server Extension API. It allows
- Internet Server Applications (i.e., ISAPI .dll handler modules)
- to be used with Apache for Windows, subject to the noted restrictions.
+This module supports ISAPI Extensions within Apache for Windows.

+<A
+HREF="module-dict.html#Status"
+REL="Help"
+>Status:</A> Base
+ 
+<A
+HREF="module-dict.html#SourceFile"
+REL="Help"
+>Source File:</A> mod_isapi.c
+ 
+<A
+HREF="module-dict.html#ModuleIdentifier"
+REL="Help"
+>Module Identifier:</A> isapi_module
+ 
+<A
+HREF="module-dict.html#Compatibility"
+REL="Help"
+>Compatibility:</A> WIN32 only
+
+
+<H2>Summary</H2>
+
+This module implements the Internet Server extension API. It allows
+ Internet Server extensions (e.g. ISAPI .dll modules) to be
+ served by Apache for Windows, subject to the noted restrictions.
+
+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. Please do not
+ post such problems to Apache's lists or bug reporting pages.
+
<H2>Usage</H2>
+
+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:

-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:
<PRE>
AddHandler isapi-isa dll
</PRE>
-Now simply place the ISA DLLs into your document root, and they will
- be loaded when their URLs are accessed.

-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.
+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.
+
+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.
+
+ 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.
+
+<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>
+
+<A
+ HREF="directive-dict.html#Syntax"
+ REL="Help"
+>Syntax:</A> ISAPIReadAheadBuffer size 
+<A
+ HREF="directive-dict.html#Default"
+ REL="Help"
+>Default:</A> 49152 
+<A
+ HREF="directive-dict.html#Context"
+ REL="Help"
+>Context:</A> server config 
+<A
+ HREF="directive-dict.html#Override"
+ REL="Help"
+>Override:</A> None 
+<A
+ HREF="directive-dict.html#Status"
+ REL="Help"
+>Status:</A> Base 
+<A
+ HREF="directive-dict.html#Module"
+ REL="Help"
+>Module:</A> mod_isapi 
+<A
+HREF="module-dict.html#Compatibility"
+REL="Help"
+>Compatibility:</A> Apache 1.3.13 and later, Win32 only
+
+
+ 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.
+ 
+<HR>
+
+<H2><A NAME="ISAPILogNotSupported">ISAPILogNotSupported directive</A></H2>
+
+<A
+ HREF="directive-dict.html#Syntax"
+ REL="Help"
+>Syntax:</A> ISAPILogNotSupported on|off 
+<A
+ HREF="directive-dict.html#Default"
+ REL="Help"
+>Default:</A> on 
+<A
+ HREF="directive-dict.html#Context"
+ REL="Help"
+>Context:</A> server config 
+<A
+ HREF="directive-dict.html#Override"
+ REL="Help"
+>Override:</A> None 
+<A
+ HREF="directive-dict.html#Status"
+ REL="Help"
+>Status:</A> Base 
+<A
+ HREF="directive-dict.html#Module"
+ REL="Help"
+>Module:</A> mod_isapi 
+<A
+HREF="module-dict.html#Compatibility"
+REL="Help"
+>Compatibility:</A> Apache 1.3.13 and later, Win32 only
+
+ 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.
+ 
+<HR>
+
+<H2><A NAME="ISAPIAppendLogToErrors">ISAPIAppendLogToErrors directive</A></H2>
+
+<A
+ HREF="directive-dict.html#Syntax"
+ REL="Help"
+>Syntax:</A> ISAPIAppendLogToErrors on|off 
+<A
+ HREF="directive-dict.html#Default"
+ REL="Help"
+>Default:</A> off 
+<A
+ HREF="directive-dict.html#Context"
+ REL="Help"
+>Context:</A> server config 
+<A
+ HREF="directive-dict.html#Override"
+ REL="Help"
+>Override:</A> None 
+<A
+ HREF="directive-dict.html#Status"
+ REL="Help"
+>Status:</A> Base 
+<A
+ HREF="directive-dict.html#Module"
+ REL="Help"
+>Module:</A> mod_isapi 
+<A
+HREF="module-dict.html#Compatibility"
+REL="Help"
+>Compatibility:</A> Apache 1.3.13 and later, Win32 only
+
+ Record HSE_APPEND_LOG_PARAMETER requests from ISAPI extentions
+ to the server error log.
+ 
+<HR>
+
+<H2><A NAME="ISAPIAppendLogToQuery">ISAPIAppendLogToQuery directive</A></H2>
+
+<A
+ HREF="directive-dict.html#Syntax"
+ REL="Help"
+>Syntax:</A> ISAPIAppendLogToQuery on|off 
+<A
+ HREF="directive-dict.html#Default"
+ REL="Help"
+>Default:</A> off 
+<A
+ HREF="directive-dict.html#Context"
+ REL="Help"
+>Context:</A> server config 
+<A
+ HREF="directive-dict.html#Override"
+ REL="Help"
+>Override:</A> None 
+<A
+ HREF="directive-dict.html#Status"
+ REL="Help"
+>Status:</A> Base 
+<A
+ HREF="directive-dict.html#Module"
+ REL="Help"
+>Module:</A> mod_isapi 
+<A
+HREF="module-dict.html#Compatibility"
+REL="Help"
+>Compatibility:</A> Apache 1.3.13 and later, Win32 only
+
+ Record HSE_APPEND_LOG_PARAMETER requests from ISAPI extentions
+ to the query field (appended to the CustomLog %q component).
+ 
+<HR>

-<H2>Notes</H2>
+<H2><A NAME="notes">Additional Notes</A></H2>

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.

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.
-
-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.
-
-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.
+ 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.
+
+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.

-<H2>Programmer's Journal</H2>
+<H2><A NAME="journal">Programmer's Journal</A></H2>

If you are programming Apache 1.3 mod_isapi modules, you must limit your
calls to ServerSupportFunction to the following directives:
@@ -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. 
- 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 Apache 1.3.13 and later
+ <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 Apache 1.3.13 and later
+ <DD>Will return the negotiated Keep-Alive status.
+ <DT>HSE_REQ_SEND_RESPONSE_HEADER_EX Apache 1.3.13 and later
+ <DD>Will behave as documented, although the fKeepConn flag is ignored.
+ <DT>HSE_REQ_IS_CONNECTED Apache 1.3.13 and later
+ <DD>Will report false if the request has been aborted.
</DL>

-Apache returns FALSE to any other call to ServerSupportFunction, and
+Apache returns FALSE to any unsupported call to ServerSupportFunction, and
sets the GetLastError value to ERROR_INVALID_PARAMETER.

-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.
+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.

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.

-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.
+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.

-Apache 2.0 mod_isapi will support additional features introduced in later
+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