mod_isapi.xml revision 3d81f57512275ca06a60a9bcbd23c1f8b429fdf2
6aada32e978e09cc60d52cb05ae4cee91b676da1slive<!DOCTYPE modulesynopsis SYSTEM "/style/modulesynopsis.dtd">
e942c741056732f50da2074b36fe59805d370650slive<?xml-stylesheet type="text/xsl" href="/style/manual.en.xsl"?>
5f5d1b4cc970b7f06ff8ef6526128e9a27303d88nd<!-- $LastChangedRevision$ -->
3d81f57512275ca06a60a9bcbd23c1f8b429fdf2colm Copyright 2002-2006 The Apache Software Foundation or its licensors, as
d5d794fc2f4cc9ca6d6da17cfa2cdcd8d244bacdnd Licensed under the Apache License, Version 2.0 (the "License");
d5d794fc2f4cc9ca6d6da17cfa2cdcd8d244bacdnd you may not use this file except in compliance with the License.
d5d794fc2f4cc9ca6d6da17cfa2cdcd8d244bacdnd You may obtain a copy of the License at
d5d794fc2f4cc9ca6d6da17cfa2cdcd8d244bacdnd Unless required by applicable law or agreed to in writing, software
d5d794fc2f4cc9ca6d6da17cfa2cdcd8d244bacdnd distributed under the License is distributed on an "AS IS" BASIS,
d5d794fc2f4cc9ca6d6da17cfa2cdcd8d244bacdnd WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
d5d794fc2f4cc9ca6d6da17cfa2cdcd8d244bacdnd See the License for the specific language governing permissions and
d5d794fc2f4cc9ca6d6da17cfa2cdcd8d244bacdnd limitations under the License.
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
173acde414093bc645e1510e36a7e0e0bd4986f3erikabele extension. <strong>Please <em>do not</em> post such problems to
173acde414093bc645e1510e36a7e0e0bd4986f3erikabele <p>In the server configuration file, use
173acde414093bc645e1510e36a7e0e0bd4986f3erikabele the <directive module="mod_mime">AddHandler</directive> directive to
173acde414093bc645e1510e36a7e0e0bd4986f3erikabele associate ISAPI files with the <code>isapi-isa</code> handler, and map
173acde414093bc645e1510e36a7e0e0bd4986f3erikabele it to them with their file extensions. To enable any .dll file to be
173acde414093bc645e1510e36a7e0e0bd4986f3erikabele processed as an ISAPI extension, edit the httpd.conf file and add the
173acde414093bc645e1510e36a7e0e0bd4986f3erikabele following line:</p>
173acde414093bc645e1510e36a7e0e0bd4986f3erikabele 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
173acde414093bc645e1510e36a7e0e0bd4986f3erikabele ISAPICacheFile c:/WebWork/Scripts/ISAPI/mytest.dll
6aada32e978e09cc60d52cb05ae4cee91b676da1slive <p>Whether or not you have preloaded an ISAPI extension, all
6aada32e978e09cc60d52cb05ae4cee91b676da1slive ISAPI extensions are governed by the same permissions and
cd8a69c2fb1cb3fa066fe42fb4cbba9d38a1cd4and restrictions as CGI scripts. That is, <directive module="core"
cd8a69c2fb1cb3fa066fe42fb4cbba9d38a1cd4and >Options</directive> <code>ExecCGI</code> must be set for the
cd8a69c2fb1cb3fa066fe42fb4cbba9d38a1cd4and directory that contains the 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 <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
cd8a69c2fb1cb3fa066fe42fb4cbba9d38a1cd4and >ISAPICacheFile</directive> 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,
cd8a69c2fb1cb3fa066fe42fb4cbba9d38a1cd4and 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>
cd8a69c2fb1cb3fa066fe42fb4cbba9d38a1cd4and modules, you must limit your calls to <code>ServerSupportFunction</code>
cd8a69c2fb1cb3fa066fe42fb4cbba9d38a1cd4and to the following directives:</p>
cd8a69c2fb1cb3fa066fe42fb4cbba9d38a1cd4and This cannot be a fully qualified URL, you are not allowed to
cd8a69c2fb1cb3fa066fe42fb4cbba9d38a1cd4and This redirection is handled by the server, not the
6aada32e978e09cc60d52cb05ae4cee91b676da1slive browser.<br />
cd8a69c2fb1cb3fa066fe42fb4cbba9d38a1cd4and <p>In their recent documentation, Microsoft appears to have
cd8a69c2fb1cb3fa066fe42fb4cbba9d38a1cd4and abandoned the distinction between the two
cd8a69c2fb1cb3fa066fe42fb4cbba9d38a1cd4and <code>HSE_REQ_SEND_URL</code> functions. Apache continues to treat
cd8a69c2fb1cb3fa066fe42fb4cbba9d38a1cd4and them as two distinct functions with different requirements
cd8a69c2fb1cb3fa066fe42fb4cbba9d38a1cd4and and behaviors.</p>
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
cd8a69c2fb1cb3fa066fe42fb4cbba9d38a1cd4and <li>in the <code>\"%{isapi-parameter}n\"</code> component in a
cd8a69c2fb1cb3fa066fe42fb4cbba9d38a1cd4and directive</li>
cd8a69c2fb1cb3fa066fe42fb4cbba9d38a1cd4and <directive module="mod_isapi">ISAPIAppendLogToQuery</directive>
cd8a69c2fb1cb3fa066fe42fb4cbba9d38a1cd4and <li>in the error log with the <directive module="mod_isapi"
cd8a69c2fb1cb3fa066fe42fb4cbba9d38a1cd4and >ISAPIAppendLogToErrors</directive> <code>On</code> directive</li>
cd8a69c2fb1cb3fa066fe42fb4cbba9d38a1cd4and <p>The first option, the <code>%{isapi-parameter}n</code> component,
cd8a69c2fb1cb3fa066fe42fb4cbba9d38a1cd4and is always available and preferred.</p>
6aada32e978e09cc60d52cb05ae4cee91b676da1slive <dd>Will return the negotiated Keep-Alive status.</dd>
cd8a69c2fb1cb3fa066fe42fb4cbba9d38a1cd4and <dd>Will behave as documented, although the <code>fKeepConn</code>
cd8a69c2fb1cb3fa066fe42fb4cbba9d38a1cd4and flag is ignored.</dd>
6aada32e978e09cc60d52cb05ae4cee91b676da1slive <dd>Will report false if the request has been aborted.</dd>
cd8a69c2fb1cb3fa066fe42fb4cbba9d38a1cd4and <p>Apache returns <code>FALSE</code> to any unsupported call to
cd8a69c2fb1cb3fa066fe42fb4cbba9d38a1cd4and <p><code>ReadClient</code> retrieves the request body exceeding the
cd8a69c2fb1cb3fa066fe42fb4cbba9d38a1cd4and >ISAPIReadAheadBuffer</directive>). Based on the
cd8a69c2fb1cb3fa066fe42fb4cbba9d38a1cd4and <directive>ISAPIReadAheadBuffer</directive> setting (number of bytes
cd8a69c2fb1cb3fa066fe42fb4cbba9d38a1cd4and to buffer prior to calling the ISAPI handler) shorter requests are sent
6aada32e978e09cc60d52cb05ae4cee91b676da1slive complete to the extension when it is invoked. If the request is
cd8a69c2fb1cb3fa066fe42fb4cbba9d38a1cd4and longer, the ISAPI extension must use <code>ReadClient</code> to
cd8a69c2fb1cb3fa066fe42fb4cbba9d38a1cd4and retrieve the remaining request body.</p>
cd8a69c2fb1cb3fa066fe42fb4cbba9d38a1cd4and <p><code>WriteClient</code> is supported, but only with the
cd8a69c2fb1cb3fa066fe42fb4cbba9d38a1cd4and <code>HSE_IO_SYNC</code> flag or no option flag (value of
cd8a69c2fb1cb3fa066fe42fb4cbba9d38a1cd4and <code>0</code>). Any other <code>WriteClient</code> request
cd8a69c2fb1cb3fa066fe42fb4cbba9d38a1cd4and will be rejected with a return value of <code>FALSE</code>, and a
cd8a69c2fb1cb3fa066fe42fb4cbba9d38a1cd4and <p><code>GetServerVariable</code> 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
cd8a69c2fb1cb3fa066fe42fb4cbba9d38a1cd4and <code>GetServerVariable</code>, as well as the <code>ALL_HTTP</code>
6aada32e978e09cc60d52cb05ae4cee91b676da1slive <p>Apache 2.0 <module>mod_isapi</module> supports additional
6aada32e978e09cc60d52cb05ae4cee91b676da1slive features introduced in later versions of the ISAPI specification,
cd8a69c2fb1cb3fa066fe42fb4cbba9d38a1cd4and as well as limited emulation of async I/O and the
cd8a69c2fb1cb3fa066fe42fb4cbba9d38a1cd4and <code>TransmitFile</code> semantics. Apache also supports preloading
cd8a69c2fb1cb3fa066fe42fb4cbba9d38a1cd4and ISAPI .dlls for performance, neither of which were not available under
6aada32e978e09cc60d52cb05ae4cee91b676da1slive<directivesynopsis>
6aada32e978e09cc60d52cb05ae4cee91b676da1slive<description>ISAPI .dll files to be loaded at startup</description>
cd8a69c2fb1cb3fa066fe42fb4cbba9d38a1cd4and<syntax>ISAPICacheFile <var>file-path</var> [<var>file-path</var>]
cd8a69c2fb1cb3fa066fe42fb4cbba9d38a1cd4and...</syntax>
cd8a69c2fb1cb3fa066fe42fb4cbba9d38a1cd4and<contextlist><context>server config</context><context>virtual host</context>
cd8a69c2fb1cb3fa066fe42fb4cbba9d38a1cd4and</contextlist>
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
cd8a69c2fb1cb3fa066fe42fb4cbba9d38a1cd4and be specified. If the path name is not absolute, it will be treated
cd8a69c2fb1cb3fa066fe42fb4cbba9d38a1cd4and relative to <directive module="core">ServerRoot</directive>.</p>
6aada32e978e09cc60d52cb05ae4cee91b676da1slive</directivesynopsis>
6aada32e978e09cc60d52cb05ae4cee91b676da1slive<directivesynopsis>
705bc21ba2aa9e0400c5e5bc7e93d476a64d65bckess<description>Size of the Read Ahead Buffer sent to ISAPI
6aada32e978e09cc60d52cb05ae4cee91b676da1sliveextensions</description>
cd8a69c2fb1cb3fa066fe42fb4cbba9d38a1cd4and<contextlist><context>server config</context><context>virtual host</context>
cd8a69c2fb1cb3fa066fe42fb4cbba9d38a1cd4and<context>directory</context><context>.htaccess</context></contextlist>
6aada32e978e09cc60d52cb05ae4cee91b676da1slive <p>Defines the maximum size of the Read Ahead Buffer sent to
6aada32e978e09cc60d52cb05ae4cee91b676da1slive ISAPI extensions when they are initially invoked. All remaining
cd8a69c2fb1cb3fa066fe42fb4cbba9d38a1cd4and data must be retrieved using the <code>ReadClient</code> callback; some
cd8a69c2fb1cb3fa066fe42fb4cbba9d38a1cd4and ISAPI extensions may not support the <code>ReadClient</code> function.
cd8a69c2fb1cb3fa066fe42fb4cbba9d38a1cd4and Refer questions to the ISAPI extension's author.</p>
6aada32e978e09cc60d52cb05ae4cee91b676da1slive</directivesynopsis>
6aada32e978e09cc60d52cb05ae4cee91b676da1slive<directivesynopsis>
6aada32e978e09cc60d52cb05ae4cee91b676da1slive<description>Log unsupported feature requests from ISAPI
6aada32e978e09cc60d52cb05ae4cee91b676da1sliveextensions</description>
cd8a69c2fb1cb3fa066fe42fb4cbba9d38a1cd4and<contextlist><context>server config</context><context>virtual host</context>
cd8a69c2fb1cb3fa066fe42fb4cbba9d38a1cd4and<context>directory</context><context>.htaccess</context></contextlist>
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>
cd8a69c2fb1cb3fa066fe42fb4cbba9d38a1cd4and<description>Record <code>HSE_APPEND_LOG_PARAMETER</code> requests from
cd8a69c2fb1cb3fa066fe42fb4cbba9d38a1cd4andISAPI extensions to the error log</description>
cd8a69c2fb1cb3fa066fe42fb4cbba9d38a1cd4and<contextlist><context>server config</context><context>virtual host</context>
cd8a69c2fb1cb3fa066fe42fb4cbba9d38a1cd4and<context>directory</context><context>.htaccess</context></contextlist>
cd8a69c2fb1cb3fa066fe42fb4cbba9d38a1cd4and <p>Record <code>HSE_APPEND_LOG_PARAMETER</code> requests from ISAPI
6aada32e978e09cc60d52cb05ae4cee91b676da1slive extensions to the server error log.</p>
6aada32e978e09cc60d52cb05ae4cee91b676da1slive</directivesynopsis>
6aada32e978e09cc60d52cb05ae4cee91b676da1slive<directivesynopsis>
cd8a69c2fb1cb3fa066fe42fb4cbba9d38a1cd4and<description>Record <code>HSE_APPEND_LOG_PARAMETER</code> requests from
cd8a69c2fb1cb3fa066fe42fb4cbba9d38a1cd4andISAPI extensions to the query field</description>
cd8a69c2fb1cb3fa066fe42fb4cbba9d38a1cd4and<contextlist><context>server config</context><context>virtual host</context>
cd8a69c2fb1cb3fa066fe42fb4cbba9d38a1cd4and<context>directory</context><context>.htaccess</context></contextlist>
cd8a69c2fb1cb3fa066fe42fb4cbba9d38a1cd4and <p>Record <code>HSE_APPEND_LOG_PARAMETER</code> requests from ISAPI
cd8a69c2fb1cb3fa066fe42fb4cbba9d38a1cd4and extensions to the query field (appended to the <directive
cd8a69c2fb1cb3fa066fe42fb4cbba9d38a1cd4and module="mod_log_config">CustomLog</directive> <code>%q</code>
6aada32e978e09cc60d52cb05ae4cee91b676da1slive component).</p>
6aada32e978e09cc60d52cb05ae4cee91b676da1slive</directivesynopsis>
705bc21ba2aa9e0400c5e5bc7e93d476a64d65bckess<directivesynopsis>
cd8a69c2fb1cb3fa066fe42fb4cbba9d38a1cd4and<description>Fake asynchronous support for ISAPI callbacks</description>
cd8a69c2fb1cb3fa066fe42fb4cbba9d38a1cd4and<contextlist><context>server config</context><context>virtual host</context>
cd8a69c2fb1cb3fa066fe42fb4cbba9d38a1cd4and<context>directory</context><context>.htaccess</context></contextlist>
cd8a69c2fb1cb3fa066fe42fb4cbba9d38a1cd4and <p>While set to on, asynchronous support for ISAPI callbacks is
705bc21ba2aa9e0400c5e5bc7e93d476a64d65bckess simulated.</p>
705bc21ba2aa9e0400c5e5bc7e93d476a64d65bckess</directivesynopsis>
173acde414093bc645e1510e36a7e0e0bd4986f3erikabele</modulesynopsis>