mirror of
https://github.com/apache/httpd.git
synced 2025-06-01 23:21:45 +03:00
642f536bba
git-svn-id: https://svn.apache.org/repos/asf/httpd/httpd/trunk@96665 13f79535-47bb-0310-9956-ffa450edef68
254 lines
18 KiB
XML
254 lines
18 KiB
XML
<?xml version="1.0" encoding="ISO-8859-1"?>
|
||
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
|
||
<html xmlns="http://www.w3.org/1999/xhtml" lang="en" xml:lang="en"><head><!--
|
||
XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
|
||
This file is generated from xml source: DO NOT EDIT
|
||
XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
|
||
--><title>mod_isapi - Apache HTTP Server</title><link href="../style/css/manual.css" rel="stylesheet" media="all" type="text/css" title="Main stylesheet" /><link href="../images/favicon.ico" rel="shortcut icon" /></head><body><div id="page-header"><p class="menu"><a href="../mod/">Modules</a> | <a href="../mod/directives.html">Directives</a> | <a href="../faq/">FAQ</a> | <a href="../glossary.html">Glossary</a> | <a href="../sitemap.html">Sitemap</a></p><p class="apache">Apache HTTP Server Version 2.0</p><img alt="" src="../images/feather.gif" /></div><div class="up"><a href="./"><img title="<-" alt="<-" src="../images/left.gif" /></a></div><div id="path"><a href="http://www.apache.org/">Apache</a> > <a href="http://httpd.apache.org/">HTTP Server</a> > <a href="http://httpd.apache.org/docs-project/">Documentation</a> > <a href="../">Version 2.0</a> > <a href="./">Modules</a></div><div id="page-content"><div id="preamble"><h1>Apache Module mod_isapi</h1><table class="module"><tr><th>Description:
|
||
</th><td>ISAPI Extensions within Apache for Windows</td></tr><tr><th><a href="module-dict.html#Status">Status:
|
||
</a></th><td>Base</td></tr><tr><th><a href="module-dict.html#ModuleIdentifier">Module Identifier:
|
||
</a></th><td>isapi_module</td></tr><tr><th><a href="module-dict.html#Compatibility">Compatibility:
|
||
</a></th><td>Win32 only</td></tr></table><h3>Summary</h3>
|
||
<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>
|
||
</div><div id="quickview"><h3 class="directives">Directives</h3><ul id="toc"><li><img alt="" src="../images/down.gif" /> <a href="#isapiappendlogtoerrors">ISAPIAppendLogToErrors</a></li><li><img alt="" src="../images/down.gif" /> <a href="#isapiappendlogtoquery">ISAPIAppendLogToQuery</a></li><li><img alt="" src="../images/down.gif" /> <a href="#isapicachefile">ISAPICacheFile</a></li><li><img alt="" src="../images/down.gif" /> <a href="#isapifakeasync">ISAPIFakeAsync</a></li><li><img alt="" src="../images/down.gif" /> <a href="#isapilognotsupported">ISAPILogNotSupported</a></li><li><img alt="" src="../images/down.gif" /> <a href="#isapireadaheadbuffer">ISAPIReadAheadBuffer</a></li></ul><h3>Topics</h3><ul id="topics"><li><img alt="" src="../images/down.gif" /> Usage</li><li><img alt="" src="../images/down.gif" /> <a href="#notes">Additional Notes</a></li><li><img alt="" src="../images/down.gif" /> <a href="#journal">Programmer's Journal</a></li></ul></div><div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div><div class="section"><h2>Usage</h2> <p>In the server configuration file, use
|
||
the <code class="directive"><a href="../mod/mod_mime.html#addhandler">AddHandler</a></code> 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>
|
||
<div class="example"><p><code>
|
||
AddHandler isapi-isa .dll
|
||
</code></p></div>
|
||
|
||
<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:</p>
|
||
<div class="example"><p><code>
|
||
ISAPICacheFile c:/WebWork/Scripts/ISAPI/mytest.dll
|
||
</code></p></div>
|
||
|
||
<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>
|
||
</div><div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div><div class="section"><h2><a name="notes" id="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>
|
||
</div><div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div><div class="section"><h2><a name="journal" id="journal">Programmer's Journal</a></h2>
|
||
|
||
<p>If you are programming Apache 2.0 <code class="module"><a href="../mod/mod_isapi.html">mod_isapi</a></code>
|
||
modules, you must limit your calls to ServerSupportFunction to the
|
||
following directives:</p>
|
||
|
||
<dl>
|
||
<dt>HSE_REQ_SEND_URL_REDIRECT_RESP</dt>
|
||
|
||
<dd>Redirect the user to another location.<br />
|
||
This must be a fully qualified URL (e.g.
|
||
http://server/location).</dd>
|
||
|
||
<dt>HSE_REQ_SEND_URL</dt>
|
||
|
||
<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.</dd>
|
||
|
||
<dt>HSE_REQ_SEND_RESPONSE_HEADER</dt>
|
||
|
||
<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.</dd>
|
||
|
||
<dt>HSE_REQ_DONE_WITH_SESSION</dt>
|
||
|
||
<dd>Apache considers this a no-op, since the session will be
|
||
finished when the ISAPI returns from processing.</dd>
|
||
|
||
<dt>HSE_REQ_MAP_URL_TO_PATH</dt>
|
||
|
||
<dd>Apache will translate a virtual name to a physical
|
||
name.</dd>
|
||
|
||
<dt>HSE_APPEND_LOG_PARAMETER</dt>
|
||
|
||
<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>
|
||
|
||
<li>in the %q log component with the
|
||
ISAPIAppendLogToQuery On directive</li>
|
||
|
||
<li>in the error log with the ISAPIAppendLogToErrors On
|
||
directive</li>
|
||
</ul>
|
||
The first option, the %{isapi-parameter}n component, is
|
||
always available and prefered.
|
||
</dd>
|
||
|
||
<dt>HSE_REQ_IS_KEEP_CONN</dt>
|
||
|
||
<dd>Will return the negotiated Keep-Alive status.</dd>
|
||
|
||
<dt>HSE_REQ_SEND_RESPONSE_HEADER_EX</dt>
|
||
|
||
<dd>Will behave as documented, although the fKeepConn flag is
|
||
ignored.</dd>
|
||
|
||
<dt>HSE_REQ_IS_CONNECTED</dt>
|
||
|
||
<dd>Will report false if the request has been aborted.</dd>
|
||
</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 <code class="module"><a href="../mod/mod_isapi.html">mod_isapi</a></code> 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>
|
||
</div><div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div><div class="directive-section"><h2><a name="ISAPIAppendLogToErrors" id="ISAPIAppendLogToErrors">ISAPIAppendLogToErrors</a> <a name="isapiappendlogtoerrors" id="isapiappendlogtoerrors">Directive</a></h2><table class="directive"><tr><th>Description:
|
||
</th><td>Record HSE_APPEND_LOG_PARAMETER requests from ISAPI
|
||
extensions to the error log</td></tr><tr><th><a href="directive-dict.html#Syntax">Syntax:
|
||
</a></th><td>ISAPIAppendLogToErrors on|off</td></tr><tr><th><a href="directive-dict.html#Default">Default:
|
||
</a></th><td><code>ISAPIAppendLogToErrors off</code></td></tr><tr><th><a href="directive-dict.html#Context">Context:
|
||
</a></th><td>server config, virtual host, directory, .htaccess</td></tr><tr><th><a href="directive-dict.html#Override">Override:
|
||
</a></th><td>FileInfo</td></tr><tr><th><a href="directive-dict.html#Status">Status:
|
||
</a></th><td>Base</td></tr><tr><th><a href="directive-dict.html#Module">Module:
|
||
</a></th><td>mod_isapi</td></tr></table>
|
||
<p>Record HSE_APPEND_LOG_PARAMETER requests from ISAPI
|
||
extensions to the server error log.</p>
|
||
</div><div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div><div class="directive-section"><h2><a name="ISAPIAppendLogToQuery" id="ISAPIAppendLogToQuery">ISAPIAppendLogToQuery</a> <a name="isapiappendlogtoquery" id="isapiappendlogtoquery">Directive</a></h2><table class="directive"><tr><th>Description:
|
||
</th><td>Record HSE_APPEND_LOG_PARAMETER requests from ISAPI
|
||
extensions to the query field</td></tr><tr><th><a href="directive-dict.html#Syntax">Syntax:
|
||
</a></th><td>ISAPIAppendLogToQuery on|off</td></tr><tr><th><a href="directive-dict.html#Default">Default:
|
||
</a></th><td><code>ISAPIAppendLogToQuery on</code></td></tr><tr><th><a href="directive-dict.html#Context">Context:
|
||
</a></th><td>server config, virtual host, directory, .htaccess</td></tr><tr><th><a href="directive-dict.html#Override">Override:
|
||
</a></th><td>FileInfo</td></tr><tr><th><a href="directive-dict.html#Status">Status:
|
||
</a></th><td>Base</td></tr><tr><th><a href="directive-dict.html#Module">Module:
|
||
</a></th><td>mod_isapi</td></tr></table>
|
||
<p>Record HSE_APPEND_LOG_PARAMETER requests from ISAPI
|
||
extensions to the query field (appended to the CustomLog %q
|
||
component).</p>
|
||
</div><div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div><div class="directive-section"><h2><a name="ISAPICacheFile" id="ISAPICacheFile">ISAPICacheFile</a> <a name="isapicachefile" id="isapicachefile">Directive</a></h2><table class="directive"><tr><th>Description:
|
||
</th><td>ISAPI .dll files to be loaded at startup</td></tr><tr><th><a href="directive-dict.html#Syntax">Syntax:
|
||
</a></th><td>ISAPICacheFile <em>file-path</em> [<em>file-path</em>] ...</td></tr><tr><th><a href="directive-dict.html#Context">Context:
|
||
</a></th><td>server config, virtual host</td></tr><tr><th><a href="directive-dict.html#Status">Status:
|
||
</a></th><td>Base</td></tr><tr><th><a href="directive-dict.html#Module">Module:
|
||
</a></th><td>mod_isapi</td></tr></table>
|
||
<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>
|
||
</div><div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div><div class="directive-section"><h2><a name="ISAPIFakeAsync" id="ISAPIFakeAsync">ISAPIFakeAsync</a> <a name="isapifakeasync" id="isapifakeasync">Directive</a></h2><table class="directive"><tr><th>Description:
|
||
</th><td>Fake asynchronous support for isapi callbacks</td></tr><tr><th><a href="directive-dict.html#Syntax">Syntax:
|
||
</a></th><td>ISAPIFakeAsync on|off</td></tr><tr><th><a href="directive-dict.html#Default">Default:
|
||
</a></th><td><code>ISAPIFakeAsync off</code></td></tr><tr><th><a href="directive-dict.html#Context">Context:
|
||
</a></th><td>server config, virtual host, directory, .htaccess</td></tr><tr><th><a href="directive-dict.html#Override">Override:
|
||
</a></th><td>FileInfo</td></tr><tr><th><a href="directive-dict.html#Status">Status:
|
||
</a></th><td>Base</td></tr><tr><th><a href="directive-dict.html#Module">Module:
|
||
</a></th><td>mod_isapi</td></tr></table>
|
||
<p>While set to on, asynchronous support for isapi callbacks is
|
||
simulated.</p>
|
||
</div><div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div><div class="directive-section"><h2><a name="ISAPILogNotSupported" id="ISAPILogNotSupported">ISAPILogNotSupported</a> <a name="isapilognotsupported" id="isapilognotsupported">Directive</a></h2><table class="directive"><tr><th>Description:
|
||
</th><td>Log unsupported feature requests from ISAPI
|
||
extensions</td></tr><tr><th><a href="directive-dict.html#Syntax">Syntax:
|
||
</a></th><td>ISAPILogNotSupported on|off</td></tr><tr><th><a href="directive-dict.html#Default">Default:
|
||
</a></th><td><code>ISAPILogNotSupported off</code></td></tr><tr><th><a href="directive-dict.html#Context">Context:
|
||
</a></th><td>server config, virtual host, directory, .htaccess</td></tr><tr><th><a href="directive-dict.html#Override">Override:
|
||
</a></th><td>FileInfo</td></tr><tr><th><a href="directive-dict.html#Status">Status:
|
||
</a></th><td>Base</td></tr><tr><th><a href="directive-dict.html#Module">Module:
|
||
</a></th><td>mod_isapi</td></tr></table>
|
||
<p>Logs all requests for unsupported features from ISAPI
|
||
extensions in the server error log. This may help administrators
|
||
to track down problems. Once set to on and all desired ISAPI modules
|
||
are functioning, it should be set back to off.</p>
|
||
</div><div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div><div class="directive-section"><h2><a name="ISAPIReadAheadBuffer" id="ISAPIReadAheadBuffer">ISAPIReadAheadBuffer</a> <a name="isapireadaheadbuffer" id="isapireadaheadbuffer">Directive</a></h2><table class="directive"><tr><th>Description:
|
||
</th><td>Size of the Read Ahead Buffer sent to ISAPI
|
||
extensions</td></tr><tr><th><a href="directive-dict.html#Syntax">Syntax:
|
||
</a></th><td>ISAPIReadAheadBuffer <em>size</em></td></tr><tr><th><a href="directive-dict.html#Default">Default:
|
||
</a></th><td><code>ISAPIReadAheadBuffer 49152</code></td></tr><tr><th><a href="directive-dict.html#Context">Context:
|
||
</a></th><td>server config, directory, .htaccess</td></tr><tr><th><a href="directive-dict.html#Override">Override:
|
||
</a></th><td>FileInfo</td></tr><tr><th><a href="directive-dict.html#Status">Status:
|
||
</a></th><td>Base</td></tr><tr><th><a href="directive-dict.html#Module">Module:
|
||
</a></th><td>mod_isapi</td></tr></table>
|
||
<p>Defines the maximum size of the Read Ahead Buffer sent to
|
||
ISAPI extensions when they are initially 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 extension's author.</p>
|
||
</div></div><div id="footer"><p class="apache">Maintained by the <a href="http://httpd.apache.org/docs-project/">Apache HTTP Server Documentation Project</a></p><p class="menu"><a href="../mod/">Modules</a> | <a href="../mod/directives.html">Directives</a> | <a href="../faq/">FAQ</a> | <a href="../glossary.html">Glossary</a> | <a href="../sitemap.html">Sitemap</a></p></div></body></html> |