mod_isapi.xml revision 173acde414093bc645e1510e36a7e0e0bd4986f3
da6c28aaf62fa55f0fdb8004aa40f88f23bf53f0amw<!DOCTYPE modulesynopsis SYSTEM "/style/modulesynopsis.dtd">
da6c28aaf62fa55f0fdb8004aa40f88f23bf53f0amw<?xml-stylesheet type="text/xsl" href="/style/manual.en.xsl"?>
da6c28aaf62fa55f0fdb8004aa40f88f23bf53f0amw<modulesynopsis>
da6c28aaf62fa55f0fdb8004aa40f88f23bf53f0amw<description>ISAPI Extensions within Apache for Windows</description>
da6c28aaf62fa55f0fdb8004aa40f88f23bf53f0amw <p>This module implements the Internet Server extension API. It
da6c28aaf62fa55f0fdb8004aa40f88f23bf53f0amw allows Internet Server extensions (<em>e.g.</em> ISAPI .dll
da6c28aaf62fa55f0fdb8004aa40f88f23bf53f0amw modules) to be served by Apache for Windows, subject to the
da6c28aaf62fa55f0fdb8004aa40f88f23bf53f0amw noted restrictions.</p>
da6c28aaf62fa55f0fdb8004aa40f88f23bf53f0amw <p>ISAPI extension modules (.dll files) are written by third
da6c28aaf62fa55f0fdb8004aa40f88f23bf53f0amw parties. The Apache Group does not author these modules, so we
da6c28aaf62fa55f0fdb8004aa40f88f23bf53f0amw provide no support for them. Please contact the ISAPI's author
8622ec4569457733001d4982ef7f5b44427069beGordon Ross directly if you are experiencing problems running their ISAPI
f96bd5c800e73e351b0b6e4bd7f00b578dad29bbAlan Wright extension. <strong>Please <em>do not</em> post such problems to
9fb67ea305c66b6a297583b9b0db6796b0dfe497afshin salek ardakani - Sun Microsystems - Irvine United States<section id="usage"><title>Usage</title>
55bf511df53aad0fdb7eb3fa349f0308cc05234cas <p>In the server configuration file, use
6537f381d2d9e7b4e2f7b29c3e7a3f13be036f2eas the <directive module="mod_mime">AddHandler</directive> directive to
da6c28aaf62fa55f0fdb8004aa40f88f23bf53f0amw associate ISAPI files with the <code>isapi-isa</code> handler, and map
da6c28aaf62fa55f0fdb8004aa40f88f23bf53f0amw it to them with their file extensions. To enable any .dll file to be
55bf511df53aad0fdb7eb3fa349f0308cc05234cas processed as an ISAPI extension, edit the httpd.conf file and add the
da6c28aaf62fa55f0fdb8004aa40f88f23bf53f0amw following line:</p>
da6c28aaf62fa55f0fdb8004aa40f88f23bf53f0amw AddHandler isapi-isa .dll
da6c28aaf62fa55f0fdb8004aa40f88f23bf53f0amw </example>
da6c28aaf62fa55f0fdb8004aa40f88f23bf53f0amw <p>There is no capability within the Apache server to leave a
da6c28aaf62fa55f0fdb8004aa40f88f23bf53f0amw requested module loaded. However, you may preload and keep a
da6c28aaf62fa55f0fdb8004aa40f88f23bf53f0amw specific module loaded by using the following syntax in your
da6c28aaf62fa55f0fdb8004aa40f88f23bf53f0amw </example>
da6c28aaf62fa55f0fdb8004aa40f88f23bf53f0amw <p>Whether or not you have preloaded an ISAPI extension, all
da6c28aaf62fa55f0fdb8004aa40f88f23bf53f0amw ISAPI extensions are governed by the same permissions and
da6c28aaf62fa55f0fdb8004aa40f88f23bf53f0amw restrictions as CGI scripts. That is, <code>Options
da6c28aaf62fa55f0fdb8004aa40f88f23bf53f0amw ExecCGI</code> must be set for the directory that contains the
da6c28aaf62fa55f0fdb8004aa40f88f23bf53f0amw ISAPI .dll file.</p>
da6c28aaf62fa55f0fdb8004aa40f88f23bf53f0amw <p>Review the <a href="#notes">Additional Notes</a> and the <a
da6c28aaf62fa55f0fdb8004aa40f88f23bf53f0amw href="#journal">Programmer's Journal</a> for additional details
da6c28aaf62fa55f0fdb8004aa40f88f23bf53f0amw and clarification of the specific ISAPI support offered by
da6c28aaf62fa55f0fdb8004aa40f88f23bf53f0amw mod_isapi.</p>
55bf511df53aad0fdb7eb3fa349f0308cc05234cas <p>Apache's ISAPI implementation conforms to all of the ISAPI
55bf511df53aad0fdb7eb3fa349f0308cc05234cas 2.0 specification, except for some "Microsoft-specific"
55bf511df53aad0fdb7eb3fa349f0308cc05234cas extensions dealing with asynchronous I/O. Apache's I/O model
55bf511df53aad0fdb7eb3fa349f0308cc05234cas does not allow asynchronous reading and writing in a manner
55bf511df53aad0fdb7eb3fa349f0308cc05234cas that the ISAPI could access. If an ISA tries to access
55bf511df53aad0fdb7eb3fa349f0308cc05234cas unsupported features, including async I/O, a message is placed
55bf511df53aad0fdb7eb3fa349f0308cc05234cas in the error log to help with debugging. Since these messages
55bf511df53aad0fdb7eb3fa349f0308cc05234cas can become a flood, the directive <code>ISAPILogNotSupported
55bf511df53aad0fdb7eb3fa349f0308cc05234cas <p>Some servers, like Microsoft IIS, load the ISAPI extension
55bf511df53aad0fdb7eb3fa349f0308cc05234cas into the server and keep it loaded until memory usage is too
55bf511df53aad0fdb7eb3fa349f0308cc05234cas high, or unless configuration options are specified. Apache
55bf511df53aad0fdb7eb3fa349f0308cc05234cas currently loads and unloads the ISAPI extension each time it is
55bf511df53aad0fdb7eb3fa349f0308cc05234cas requested, unless the ISAPICacheFile directive is specified.
8622ec4569457733001d4982ef7f5b44427069beGordon Ross This is inefficient, but Apache's memory model makes this the
55bf511df53aad0fdb7eb3fa349f0308cc05234cas most effective method. Many ISAPI modules are subtly
55bf511df53aad0fdb7eb3fa349f0308cc05234cas incompatible with the Apache server, and unloading these
55bf511df53aad0fdb7eb3fa349f0308cc05234cas modules helps to ensure the stability of the server.</p>
da6c28aaf62fa55f0fdb8004aa40f88f23bf53f0amw <p>Also, remember that while Apache supports ISAPI Extensions,
55bf511df53aad0fdb7eb3fa349f0308cc05234cas it <strong>does not support ISAPI Filters.</strong> Support for
55bf511df53aad0fdb7eb3fa349f0308cc05234cas filters may be added at a later date, but no support is planned
55bf511df53aad0fdb7eb3fa349f0308cc05234cas at this time.</p>
da6c28aaf62fa55f0fdb8004aa40f88f23bf53f0amw <p>If you are programming Apache 2.0 <module>mod_isapi</module>
f96bd5c800e73e351b0b6e4bd7f00b578dad29bbAlan Wright modules, you must limit your calls to ServerSupportFunction to the
c8ec8eea9849cac239663c46be8a7f5d2ba7ca00jose borrego following directives:</p>
9fb67ea305c66b6a297583b9b0db6796b0dfe497afshin salek ardakani - Sun Microsystems - Irvine United States <dt>HSE_REQ_SEND_URL_REDIRECT_RESP</dt>
55bf511df53aad0fdb7eb3fa349f0308cc05234cas This must be a fully qualified URL (e.g.
55bf511df53aad0fdb7eb3fa349f0308cc05234cas This cannot be a fully qualified URL, you are not allowed to
55bf511df53aad0fdb7eb3fa349f0308cc05234cas pass the protocol or a server name (e.g. simply
55bf511df53aad0fdb7eb3fa349f0308cc05234cas /location).<br />
55bf511df53aad0fdb7eb3fa349f0308cc05234cas This redirection is handled by the server, not the
da6c28aaf62fa55f0fdb8004aa40f88f23bf53f0amw browser.<br />
55bf511df53aad0fdb7eb3fa349f0308cc05234cas Microsoft appears to have abandoned the distinction between
55bf511df53aad0fdb7eb3fa349f0308cc05234cas the two HSE_REQ_SEND_URL functions. Apache continues to treat
55bf511df53aad0fdb7eb3fa349f0308cc05234cas them as two distinct functions with different requirements
55bf511df53aad0fdb7eb3fa349f0308cc05234cas and behaviors.</dd>
55bf511df53aad0fdb7eb3fa349f0308cc05234cas <dd>Apache accepts a response body following the header if it
55bf511df53aad0fdb7eb3fa349f0308cc05234cas follows the blank line (two consecutive newlines) in the
da6c28aaf62fa55f0fdb8004aa40f88f23bf53f0amw headers string argument. This body cannot contain NULLs,
da6c28aaf62fa55f0fdb8004aa40f88f23bf53f0amw since the headers argument is NULL terminated.</dd>
55bf511df53aad0fdb7eb3fa349f0308cc05234cas <dd>Apache considers this a no-op, since the session will be
55bf511df53aad0fdb7eb3fa349f0308cc05234cas finished when the ISAPI returns from processing.</dd>
da6c28aaf62fa55f0fdb8004aa40f88f23bf53f0amw <dd>Apache will translate a virtual name to a physical
6537f381d2d9e7b4e2f7b29c3e7a3f13be036f2eas name.</dd>
55bf511df53aad0fdb7eb3fa349f0308cc05234cas This logged message may be captured in any of the following
da6c28aaf62fa55f0fdb8004aa40f88f23bf53f0amw <li>in the \"%{isapi-parameter}n\" component in a
da6c28aaf62fa55f0fdb8004aa40f88f23bf53f0amw CustomLog directive</li>
55bf511df53aad0fdb7eb3fa349f0308cc05234cas <li>in the %q log component with the
55bf511df53aad0fdb7eb3fa349f0308cc05234cas ISAPIAppendLogToQuery On directive</li>
55bf511df53aad0fdb7eb3fa349f0308cc05234cas <li>in the error log with the ISAPIAppendLogToErrors On
55bf511df53aad0fdb7eb3fa349f0308cc05234cas directive</li>
da6c28aaf62fa55f0fdb8004aa40f88f23bf53f0amw The first option, the %{isapi-parameter}n component, is
da6c28aaf62fa55f0fdb8004aa40f88f23bf53f0amw always available and prefered.
da6c28aaf62fa55f0fdb8004aa40f88f23bf53f0amw <dd>Will behave as documented, although the fKeepConn flag is
55bf511df53aad0fdb7eb3fa349f0308cc05234cas ignored.</dd>
55bf511df53aad0fdb7eb3fa349f0308cc05234cas <dd>Will report false if the request has been aborted.</dd>
55bf511df53aad0fdb7eb3fa349f0308cc05234cas <p>Apache returns FALSE to any unsupported call to
da6c28aaf62fa55f0fdb8004aa40f88f23bf53f0amw ServerSupportFunction, and sets the GetLastError value to
da6c28aaf62fa55f0fdb8004aa40f88f23bf53f0amw ERROR_INVALID_PARAMETER.</p>
55bf511df53aad0fdb7eb3fa349f0308cc05234cas <p>ReadClient retrieves the request body exceeding the initial
55bf511df53aad0fdb7eb3fa349f0308cc05234cas buffer (defined by ISAPIReadAheadBuffer). Based on the
55bf511df53aad0fdb7eb3fa349f0308cc05234cas ISAPIReadAheadBuffer setting (number of bytes to buffer prior
da6c28aaf62fa55f0fdb8004aa40f88f23bf53f0amw to calling the ISAPI handler) shorter requests are sent
55bf511df53aad0fdb7eb3fa349f0308cc05234cas complete to the extension when it is invoked. If the request is
da6c28aaf62fa55f0fdb8004aa40f88f23bf53f0amw longer, the ISAPI extension must use ReadClient to retrieve the
da6c28aaf62fa55f0fdb8004aa40f88f23bf53f0amw remaining request body.</p>
55bf511df53aad0fdb7eb3fa349f0308cc05234cas <p>WriteClient is supported, but only with the HSE_IO_SYNC flag
da6c28aaf62fa55f0fdb8004aa40f88f23bf53f0amw or no option flag (value of 0). Any other WriteClient request
55bf511df53aad0fdb7eb3fa349f0308cc05234cas will be rejected with a return value of FALSE, and a
da6c28aaf62fa55f0fdb8004aa40f88f23bf53f0amw GetLastError value of ERROR_INVALID_PARAMETER.</p>
da6c28aaf62fa55f0fdb8004aa40f88f23bf53f0amw <p>GetServerVariable is supported, although extended server
da6c28aaf62fa55f0fdb8004aa40f88f23bf53f0amw variables do not exist (as defined by other servers.) All the
da6c28aaf62fa55f0fdb8004aa40f88f23bf53f0amw usual Apache CGI environment variables are available from
da6c28aaf62fa55f0fdb8004aa40f88f23bf53f0amw GetServerVariable, as well as the ALL_HTTP and ALL_RAW
da6c28aaf62fa55f0fdb8004aa40f88f23bf53f0amw values.</p>
da6c28aaf62fa55f0fdb8004aa40f88f23bf53f0amw <p>Apache 2.0 <module>mod_isapi</module> supports additional
da6c28aaf62fa55f0fdb8004aa40f88f23bf53f0amw features introduced in later versions of the ISAPI specification,
da6c28aaf62fa55f0fdb8004aa40f88f23bf53f0amw as well as limited emulation of async I/O and the TransmitFile
da6c28aaf62fa55f0fdb8004aa40f88f23bf53f0amw semantics. Apache also supports preloading ISAPI .dlls for
da6c28aaf62fa55f0fdb8004aa40f88f23bf53f0amw performance, neither of which were not available under Apache 1.3
da6c28aaf62fa55f0fdb8004aa40f88f23bf53f0amw mod_isapi.</p>
da6c28aaf62fa55f0fdb8004aa40f88f23bf53f0amw<directivesynopsis>
da6c28aaf62fa55f0fdb8004aa40f88f23bf53f0amw<description>ISAPI .dll files to be loaded at startup</description>
da6c28aaf62fa55f0fdb8004aa40f88f23bf53f0amw<syntax>ISAPICacheFile <em>file-path</em> [<em>file-path</em>] ...</syntax>
da6c28aaf62fa55f0fdb8004aa40f88f23bf53f0amw <p>Specifies a space-separated list of file names to be loaded
da6c28aaf62fa55f0fdb8004aa40f88f23bf53f0amw when the Apache server is launched, and remain loaded until the
da6c28aaf62fa55f0fdb8004aa40f88f23bf53f0amw server is shut down. This directive may be repeated for every
55bf511df53aad0fdb7eb3fa349f0308cc05234cas ISAPI .dll file desired. The full path name of each file should
da6c28aaf62fa55f0fdb8004aa40f88f23bf53f0amw be specified.</p>
da6c28aaf62fa55f0fdb8004aa40f88f23bf53f0amw</directivesynopsis>
da6c28aaf62fa55f0fdb8004aa40f88f23bf53f0amw<directivesynopsis>
da6c28aaf62fa55f0fdb8004aa40f88f23bf53f0amw<description>Size of the Read Ahead Buffer sent to ISAPI
da6c28aaf62fa55f0fdb8004aa40f88f23bf53f0amwextensions</description>
da6c28aaf62fa55f0fdb8004aa40f88f23bf53f0amw <p>Defines the maximum size of the Read Ahead Buffer sent to
da6c28aaf62fa55f0fdb8004aa40f88f23bf53f0amw ISAPI extensions when they are initially invoked. All remaining
da6c28aaf62fa55f0fdb8004aa40f88f23bf53f0amw data must be retrieved using the ReadClient callback; some
da6c28aaf62fa55f0fdb8004aa40f88f23bf53f0amw ISAPI extensions may not support the ReadClient function. Refer
da6c28aaf62fa55f0fdb8004aa40f88f23bf53f0amw questions to the ISAPI extension's author.</p>
da6c28aaf62fa55f0fdb8004aa40f88f23bf53f0amw</directivesynopsis>
da6c28aaf62fa55f0fdb8004aa40f88f23bf53f0amw<directivesynopsis>
55bf511df53aad0fdb7eb3fa349f0308cc05234cas<description>Log unsupported feature requests from ISAPI
da6c28aaf62fa55f0fdb8004aa40f88f23bf53f0amwextensions</description>
da6c28aaf62fa55f0fdb8004aa40f88f23bf53f0amw <p>Logs all requests for unsupported features from ISAPI
da6c28aaf62fa55f0fdb8004aa40f88f23bf53f0amw extensions in the server error log. This may help administrators
55bf511df53aad0fdb7eb3fa349f0308cc05234cas to track down problems. Once set to on and all desired ISAPI modules
55bf511df53aad0fdb7eb3fa349f0308cc05234cas are functioning, it should be set back to off.</p>
da6c28aaf62fa55f0fdb8004aa40f88f23bf53f0amw</directivesynopsis>
da6c28aaf62fa55f0fdb8004aa40f88f23bf53f0amw<directivesynopsis>
da6c28aaf62fa55f0fdb8004aa40f88f23bf53f0amw<description>Record HSE_APPEND_LOG_PARAMETER requests from ISAPI
da6c28aaf62fa55f0fdb8004aa40f88f23bf53f0amwextensions to the error log</description>
55bf511df53aad0fdb7eb3fa349f0308cc05234cas <p>Record HSE_APPEND_LOG_PARAMETER requests from ISAPI
55bf511df53aad0fdb7eb3fa349f0308cc05234cas extensions to the server error log.</p>
55bf511df53aad0fdb7eb3fa349f0308cc05234cas</directivesynopsis>
55bf511df53aad0fdb7eb3fa349f0308cc05234cas<directivesynopsis>
55bf511df53aad0fdb7eb3fa349f0308cc05234cas<description>Record HSE_APPEND_LOG_PARAMETER requests from ISAPI
55bf511df53aad0fdb7eb3fa349f0308cc05234casextensions to the query field</description>
55bf511df53aad0fdb7eb3fa349f0308cc05234cas <p>Record HSE_APPEND_LOG_PARAMETER requests from ISAPI
55bf511df53aad0fdb7eb3fa349f0308cc05234cas extensions to the query field (appended to the CustomLog %q
55bf511df53aad0fdb7eb3fa349f0308cc05234cas component).</p>
f96bd5c800e73e351b0b6e4bd7f00b578dad29bbAlan Wright</directivesynopsis>
55bf511df53aad0fdb7eb3fa349f0308cc05234cas<directivesynopsis>
55bf511df53aad0fdb7eb3fa349f0308cc05234cas<description>Fake asynchronous support for isapi callbacks</description>
da6c28aaf62fa55f0fdb8004aa40f88f23bf53f0amw <p>While set to on, asynchronous support for isapi callbacks is
f96bd5c800e73e351b0b6e4bd7f00b578dad29bbAlan Wright simulated.</p>
da6c28aaf62fa55f0fdb8004aa40f88f23bf53f0amw</directivesynopsis>
da6c28aaf62fa55f0fdb8004aa40f88f23bf53f0amw</modulesynopsis>