1 <html xmlns="http://www.w3.org/TR/xhtml1/strict"><head><!--
2 XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
3 This file is generated from xml source: DO NOT EDIT
4 XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
5 --><title>mod_isapi - Apache HTTP Server</title><link href="../style/manual.css" type="text/css" rel="stylesheet"/></head><body><blockquote><div align="center"><img alt="[APACHE DOCUMENTATION]" src="../images/sub.gif"/><h3>Apache HTTP Server Version 2.0</h3></div><h1 align="center">Apache Module mod_isapi</h1><table cellspacing="1" cellpadding="0" bgcolor="#cccccc"><tr><td><table bgcolor="#ffffff"><tr><td valign="top"><span class="help">Description:</span></td><td><description>ISAPI Extensions within Apache for Windows</description></td></tr><tr><td><a href="module-dict.html#Status" class="help">Status:</a></td><td>Base</td></tr><tr><td><a href="module-dict.html#ModuleIdentifier" class="help">Module Identifier:</a></td><td>isapi_module</td></tr><tr><td align="left" valign="top"><a href="module-dict.html#Compatibility" class="help">Compatibility:</a></td><td><compatibility>Win32 only</compatibility></td></tr></table></td></tr></table><h2>Summary</h2><summary>
6 <p>This module implements the Internet Server extension API. It
7 allows Internet Server extensions (<em>e.g.</em> ISAPI .dll
8 modules) to be served by Apache for Windows, subject to the
9 noted restrictions.</p>
11 <p>ISAPI extension modules (.dll files) are written by third
12 parties. The Apache Group does not author these modules, so we
13 provide no support for them. Please contact the ISAPI's author
14 directly if you are experiencing problems running their ISAPI
15 extention. <strong>Please <em>do not</em> post such problems to
16 Apache's lists or bug reporting pages.</strong></p>
17 </summary><h2>Directives</h2><ul><li><a href="#isapiappendlogtoerrors">ISAPIAppendLogToErrors</a></li><li><a href="#isapiappendlogtoquery">ISAPIAppendLogToQuery</a></li><li><a href="#isapifilechache">ISAPIFileChache</a></li><li><a href="#isapilognotsupported">ISAPILogNotSupported</a></li><li><a href="#isapireadaheadbuffer">ISAPIReadAheadBuffer</a></li></ul><h2>Usage</h2> <p>In the server configuration file, use
18 the <a href="mod_mime.html#addhandler" class="directive"><code class="directive">AddHandler</code></a> directive to
19 associate ISAPI files with the <code>isapi-isa</code> handler, and map
20 it to the with their file extensions. To enable any .dll file to be
21 processed as an ISAPI extention, edit the httpd.conf file and add the
23 <blockquote><table cellpadding="10"><tr><td bgcolor="#eeeeee"><code>
24 AddHandler isapi-isa .dll
25 </code></td></tr></table></blockquote>
27 <p>There is no capability within the Apache server to leave a
28 requested module loaded. However, you may preload and keep a
29 specific module loaded by using the following syntax in your
31 <blockquote><table cellpadding="10"><tr><td bgcolor="#eeeeee"><code>
32 ISAPICacheFile c:/WebWork/Scripts/ISAPI/mytest.dll
33 </code></td></tr></table></blockquote>
35 <p>Whether or not you have preloaded an ISAPI extension, all
36 ISAPI extensions are governed by the same permissions and
37 restrictions as CGI scripts. That is, <code>Options
38 ExecCGI</code> must be set for the directory that contains the
41 <p>Review the <a href="#notes">Additional Notes</a> and the <a href="#journal">Programmer's Journal</a> for additional details
42 and clarification of the specific ISAPI support offered by
44 <h2><a name="notes">Additional Notes</a></h2>
46 <p>Apache's ISAPI implementation conforms to all of the ISAPI
47 2.0 specification, except for some "Microsoft-specific"
48 extensions dealing with asynchronous I/O. Apache's I/O model
49 does not allow asynchronous reading and writing in a manner
50 that the ISAPI could access. If an ISA tries to access
51 unsupported features, including async I/O, a message is placed
52 in the error log to help with debugging. Since these messages
53 can become a flood, the directive <code>ISAPILogNotSupported
54 Off</code> exists to quiet this noise.</p>
56 <p>Some servers, like Microsoft IIS, load the ISAPI extension
57 into the server and keep it loaded until memory usage is too
58 high, or unless configuration options are specified. Apache
59 currently loads and unloads the ISAPI extension each time it is
60 requested, unless the ISAPICacheFile directive is specified.
61 This is inefficient, but Apache's memory model makes this the
62 most effective method. Many ISAPI modules are subtly
63 incompatible with the Apache server, and unloading these
64 modules helps to ensure the stability of the server.</p>
66 <p>Also, remember that while Apache supports ISAPI Extensions,
67 it <strong>does not support ISAPI Filters.</strong> Support for
68 filters may be added at a later date, but no support is planned
70 <h2><a name="journal">Programmer's Journal</a></h2>
72 <p>If you are programming Apache 2.0 <code><a href="mod_isapi.html">mod_isapi</a></code>
73 modules, you must limit your calls to ServerSupportFunction to the
74 following directives:</p>
77 <dt>HSE_REQ_SEND_URL_REDIRECT_RESP</dt>
79 <dd>Redirect the user to another location.<br>
80 This must be a fully qualified URL (e.g.
81 http://server/location).</dd>
83 <dt>HSE_REQ_SEND_URL</dt>
85 <dd>Redirect the user to another location.<br>
86 This cannot be a fully qualified URL, you are not allowed to
87 pass the protocol or a server name (e.g. simply
89 This redirection is handled by the server, not the
91 <strong>Warning:</strong> in their recent documentation,
92 Microsoft appears to have abandoned the distinction between
93 the two HSE_REQ_SEND_URL functions. Apache continues to treat
94 them as two distinct functions with different requirements
97 <dt>HSE_REQ_SEND_RESPONSE_HEADER</dt>
99 <dd>Apache accepts a response body following the header if it
100 follows the blank line (two consecutive newlines) in the
101 headers string argument. This body cannot contain NULLs,
102 since the headers argument is NULL terminated.</dd>
104 <dt>HSE_REQ_DONE_WITH_SESSION</dt>
106 <dd>Apache considers this a no-op, since the session will be
107 finished when the ISAPI returns from processing.</dd>
109 <dt>HSE_REQ_MAP_URL_TO_PATH</dt>
111 <dd>Apache will translate a virtual name to a physical
114 <dt>HSE_APPEND_LOG_PARAMETER</dt>
117 This logged message may be captured in any of the following
121 <li>in the \"%{isapi-parameter}n\" component in a
122 CustomLog directive</li>
124 <li>in the %q log component with the
125 ISAPIAppendLogToQuery On directive</li>
127 <li>in the error log with the ISAPIAppendLogToErrors On
130 The first option, the %{isapi-parameter}n component, is
131 always available and prefered.
134 <dt>HSE_REQ_IS_KEEP_CONN</dt>
136 <dd>Will return the negotiated Keep-Alive status.</dd>
138 <dt>HSE_REQ_SEND_RESPONSE_HEADER_EX</dt>
140 <dd>Will behave as documented, although the fKeepConn flag is
143 <dt>HSE_REQ_IS_CONNECTED</dt>
145 <dd>Will report false if the request has been aborted.</dd>
148 <p>Apache returns FALSE to any unsupported call to
149 ServerSupportFunction, and sets the GetLastError value to
150 ERROR_INVALID_PARAMETER.</p>
152 <p>ReadClient retrieves the request body exceeding the initial
153 buffer (defined by ISAPIReadAheadBuffer). Based on the
154 ISAPIReadAheadBuffer setting (number of bytes to buffer prior
155 to calling the ISAPI handler) shorter requests are sent
156 complete to the extension when it is invoked. If the request is
157 longer, the ISAPI extension must use ReadClient to retrieve the
158 remaining request body.</p>
160 <p>WriteClient is supported, but only with the HSE_IO_SYNC flag
161 or no option flag (value of 0). Any other WriteClient request
162 will be rejected with a return value of FALSE, and a
163 GetLastError value of ERROR_INVALID_PARAMETER.</p>
165 <p>GetServerVariable is supported, although extended server
166 variables do not exist (as defined by other servers.) All the
167 usual Apache CGI environment variables are available from
168 GetServerVariable, as well as the ALL_HTTP and ALL_RAW
171 <p>Apache 2.0 <code><a href="mod_isapi.html">mod_isapi</a></code> supports additional
172 features introduced in later versions of the ISAPI specification,
173 as well as limited emulation of async I/O and the TransmitFile
174 semantics. Apache also supports preloading ISAPI .dlls for
175 performance, neither of which were not available under Apache 1.3
177 <hr/><h2><a name="ISAPIAppendLogToErrors">ISAPIAppendLogToErrors</a> <a name="isapiappendlogtoerrors">Directive</a></h2><table cellpadding="1" cellspacing="0" border="0" bgcolor="#cccccc"><tr><td><table bgcolor="#ffffff"><tr><td><strong>Description: </strong></td><td>Record HSE_APPEND_LOG_PARAMETER requests from ISAPI
178 extensions to the error log</td></tr><tr><td><a href="directive-dict.html#Syntax" class="help">Syntax:</a></td><td><syntax>ISAPIAppendLogToErrors on|off</syntax></td></tr><tr><td><a href="directive-dict.html#Default" class="help">Default:</a></td><td><code>ISAPIAppendLogToErrors off</code></td></tr><tr><td><a href="directive-dict.html#Context" class="help">Context:</a></td><td>server config</td></tr><tr><td><a href="directive-dict.html#Status" class="help">Status:</a></td><td>Base</td></tr><tr><td><a href="directive-dict.html#Module" class="help">Module:</a></td><td>mod_isapi</td></tr></table></td></tr></table><usage>
179 <p>Record HSE_APPEND_LOG_PARAMETER requests from ISAPI
180 extensions to the server error log.</p>
181 </usage><hr/><h2><a name="ISAPIAppendLogToQuery">ISAPIAppendLogToQuery</a> <a name="isapiappendlogtoquery">Directive</a></h2><table cellpadding="1" cellspacing="0" border="0" bgcolor="#cccccc"><tr><td><table bgcolor="#ffffff"><tr><td><strong>Description: </strong></td><td>Record HSE_APPEND_LOG_PARAMETER requests from ISAPI
182 extensions to the query field</td></tr><tr><td><a href="directive-dict.html#Syntax" class="help">Syntax:</a></td><td><syntax>ISAPIAppendLogToQuery on|off</syntax></td></tr><tr><td><a href="directive-dict.html#Default" class="help">Default:</a></td><td><code>ISAPIAppendLogToQuery off</code></td></tr><tr><td><a href="directive-dict.html#Context" class="help">Context:</a></td><td>server config</td></tr><tr><td><a href="directive-dict.html#Status" class="help">Status:</a></td><td>Base</td></tr><tr><td><a href="directive-dict.html#Module" class="help">Module:</a></td><td>mod_isapi</td></tr></table></td></tr></table><usage>
183 <p>Record HSE_APPEND_LOG_PARAMETER requests from ISAPI
184 extensions to the query field (appended to the CustomLog %q
186 </usage><hr/><h2><a name="ISAPIFileChache">ISAPIFileChache</a> <a name="isapifilechache">Directive</a></h2><table cellpadding="1" cellspacing="0" border="0" bgcolor="#cccccc"><tr><td><table bgcolor="#ffffff"><tr><td><strong>Description: </strong></td><td>ISAPI .dll files to be loaded at startup</td></tr><tr><td><a href="directive-dict.html#Syntax" class="help">Syntax:</a></td><td><syntax>ISAPIFileCache <em>file-path</em> [<em>file-path</em>] ...</syntax></td></tr><tr><td><a href="directive-dict.html#Context" class="help">Context:</a></td><td>server config</td></tr><tr><td><a href="directive-dict.html#Status" class="help">Status:</a></td><td>Base</td></tr><tr><td><a href="directive-dict.html#Module" class="help">Module:</a></td><td>mod_isapi</td></tr></table></td></tr></table><usage>
187 <p>Specifies a space-separated list of file names to be loaded
188 when the Apache server is launched, and remain loaded until the
189 server is shut down. This directive may be repeated for every
190 ISAPI .dll file desired. The full path name of each file should
192 </usage><hr/><h2><a name="ISAPILogNotSupported">ISAPILogNotSupported</a> <a name="isapilognotsupported">Directive</a></h2><table cellpadding="1" cellspacing="0" border="0" bgcolor="#cccccc"><tr><td><table bgcolor="#ffffff"><tr><td><strong>Description: </strong></td><td>Log unsupported feature requests from ISAPI
193 extensions</td></tr><tr><td><a href="directive-dict.html#Syntax" class="help">Syntax:</a></td><td><syntax>ISAPILogNotSupported on|off</syntax></td></tr><tr><td><a href="directive-dict.html#Default" class="help">Default:</a></td><td><code>ISAPILogNotSupported on</code></td></tr><tr><td><a href="directive-dict.html#Context" class="help">Context:</a></td><td>server config</td></tr><tr><td><a href="directive-dict.html#Status" class="help">Status:</a></td><td>Base</td></tr><tr><td><a href="directive-dict.html#Module" class="help">Module:</a></td><td>mod_isapi</td></tr></table></td></tr></table><usage>
194 <p>Logs all requests for unsupported features from ISAPI
195 extensions in the server error log. While this should be turned
196 off once all desired ISAPI modules are functioning, it defaults
197 to on to help administrators track down problems.</p>
198 </usage><hr/><h2><a name="ISAPIReadAheadBuffer">ISAPIReadAheadBuffer</a> <a name="isapireadaheadbuffer">Directive</a></h2><table cellpadding="1" cellspacing="0" border="0" bgcolor="#cccccc"><tr><td><table bgcolor="#ffffff"><tr><td><strong>Description: </strong></td><td>Size of the Read Ahead Buffer sent to ISAPI
199 extensions</td></tr><tr><td><a href="directive-dict.html#Syntax" class="help">Syntax:</a></td><td><syntax>ISAPIReadAheadBuffer <em>size</em></syntax></td></tr><tr><td><a href="directive-dict.html#Default" class="help">Default:</a></td><td><code>ISAPIReadAheadBuffer 49152</code></td></tr><tr><td><a href="directive-dict.html#Context" class="help">Context:</a></td><td>server config</td></tr><tr><td><a href="directive-dict.html#Status" class="help">Status:</a></td><td>Base</td></tr><tr><td><a href="directive-dict.html#Module" class="help">Module:</a></td><td>mod_isapi</td></tr></table></td></tr></table><usage>
200 <p>Defines the maximum size of the Read Ahead Buffer sent to
201 ISAPI extensions when they are initially invoked. All remaining
202 data must be retrieved using the ReadClient callback; some
203 ISAPI extensions may not support the ReadClient function. Refer
204 questions to the ISAPI extension's author.</p>
205 </usage><hr/><h3 align="center">Apache HTTP Server Version 2.0</h3><a href="./"><img alt="Index" src="../images/index.gif"/></a><a href="../"><img alt="Home" src="../images/home.gif"/></a></blockquote></body></html>