| <!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> |
