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