2 <!DOCTYPE modulesynopsis SYSTEM "../style/modulesynopsis.dtd">
3 <?xml-stylesheet type="text/xsl" href="../style/manual.en.xsl"?>
4 <!-- $Revision: 1.9 $ -->
7 Copyright 2002-2004 The Apache Software Foundation
9 Licensed under the Apache License, Version 2.0 (the "License");
10 you may not use this file except in compliance with the License.
11 You may obtain a copy of the License at
13 http://www.apache.org/licenses/LICENSE-2.0
15 Unless required by applicable law or agreed to in writing, software
16 distributed under the License is distributed on an "AS IS" BASIS,
17 WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
18 See the License for the specific language governing permissions and
19 limitations under the License.
22 <modulesynopsis metafile="mod_isapi.xml.meta">
24 <name>mod_isapi</name>
25 <description>ISAPI Extensions within Apache for Windows</description>
27 <sourcefile>mod_isapi.c</sourcefile>
28 <identifier>isapi_module</identifier>
29 <compatibility>Win32 only</compatibility>
32 <p>This module implements the Internet Server extension API. It
33 allows Internet Server extensions (<em>e.g.</em> ISAPI .dll
34 modules) to be served by Apache for Windows, subject to the
35 noted restrictions.</p>
37 <p>ISAPI extension modules (.dll files) are written by third
38 parties. The Apache Group does not author these modules, so we
39 provide no support for them. Please contact the ISAPI's author
40 directly if you are experiencing problems running their ISAPI
41 extension. <strong>Please <em>do not</em> post such problems to
42 Apache's lists or bug reporting pages.</strong></p>
45 <section id="usage"><title>Usage</title>
47 <p>In the server configuration file, use
48 the <directive module="mod_mime">AddHandler</directive> directive to
49 associate ISAPI files with the <code>isapi-isa</code> handler, and map
50 it to them with their file extensions. To enable any .dll file to be
51 processed as an ISAPI extension, edit the httpd.conf file and add the
54 AddHandler isapi-isa .dll
57 <p>There is no capability within the Apache server to leave a
58 requested module loaded. However, you may preload and keep a
59 specific module loaded by using the following syntax in your
62 ISAPICacheFile c:/WebWork/Scripts/ISAPI/mytest.dll
65 <p>Whether or not you have preloaded an ISAPI extension, all
66 ISAPI extensions are governed by the same permissions and
67 restrictions as CGI scripts. That is, <directive module="core"
68 >Options</directive> <code>ExecCGI</code> must be set for the
69 directory that contains the ISAPI .dll file.</p>
71 <p>Review the <a href="#notes">Additional Notes</a> and the <a
72 href="#journal">Programmer's Journal</a> for additional details
73 and clarification of the specific ISAPI support offered by
74 <module>mod_isapi</module>.</p>
77 <section id="notes"><title>Additional Notes</title>
79 <p>Apache's ISAPI implementation conforms to all of the ISAPI
80 2.0 specification, except for some "Microsoft-specific"
81 extensions dealing with asynchronous I/O. Apache's I/O model
82 does not allow asynchronous reading and writing in a manner
83 that the ISAPI could access. If an ISA tries to access
84 unsupported features, including async I/O, a message is placed
85 in the error log to help with debugging. Since these messages
86 can become a flood, the directive <code>ISAPILogNotSupported
87 Off</code> exists to quiet this noise.</p>
89 <p>Some servers, like Microsoft IIS, load the ISAPI extension
90 into the server and keep it loaded until memory usage is too
91 high, or unless configuration options are specified. Apache
92 currently loads and unloads the ISAPI extension each time it is
93 requested, unless the <directive module="mod_isapi"
94 >ISAPICacheFile</directive> directive is specified.
95 This is inefficient, but Apache's memory model makes this the
96 most effective method. Many ISAPI modules are subtly
97 incompatible with the Apache server, and unloading these
98 modules helps to ensure the stability of the server.</p>
100 <p>Also, remember that while Apache supports ISAPI Extensions,
101 it <strong>does not support ISAPI Filters</strong>. Support for
102 filters may be added at a later date, but no support is planned
106 <section id="journal"><title>Programmer's Journal</title>
108 <p>If you are programming Apache 2.0 <module>mod_isapi</module>
109 modules, you must limit your calls to <code>ServerSupportFunction</code>
110 to the following directives:</p>
113 <dt><code>HSE_REQ_SEND_URL_REDIRECT_RESP</code></dt>
114 <dd>Redirect the user to another location.<br />
115 This must be a fully qualified URL (<em>e.g.</em>
116 <code>http://server/location</code>).</dd>
118 <dt><code>HSE_REQ_SEND_URL</code></dt>
119 <dd>Redirect the user to another location.<br />
120 This cannot be a fully qualified URL, you are not allowed to
121 pass the protocol or a server name (<em>e.g.</em> simply
122 <code>/location</code>).<br />
123 This redirection is handled by the server, not the
125 <note type="warning"><title>Warning</title>
126 <p>In their recent documentation, Microsoft appears to have
127 abandoned the distinction between the two
128 <code>HSE_REQ_SEND_URL</code> functions. Apache continues to treat
129 them as two distinct functions with different requirements
133 <dt><code>HSE_REQ_SEND_RESPONSE_HEADER</code></dt>
134 <dd>Apache accepts a response body following the header if it
135 follows the blank line (two consecutive newlines) in the
136 headers string argument. This body cannot contain NULLs,
137 since the headers argument is NULL terminated.</dd>
139 <dt><code>HSE_REQ_DONE_WITH_SESSION</code></dt>
140 <dd>Apache considers this a no-op, since the session will be
141 finished when the ISAPI returns from processing.</dd>
143 <dt><code>HSE_REQ_MAP_URL_TO_PATH</code></dt>
144 <dd>Apache will translate a virtual name to a physical
147 <dt><code>HSE_APPEND_LOG_PARAMETER</code></dt>
149 This logged message may be captured in any of the following
153 <li>in the <code>\"%{isapi-parameter}n\"</code> component in a
154 <directive module="mod_log_config">CustomLog</directive>
157 <li>in the <code>%q</code> log component with the
158 <directive module="mod_isapi">ISAPIAppendLogToQuery</directive>
159 <code>On</code> directive</li>
161 <li>in the error log with the <directive module="mod_isapi"
162 >ISAPIAppendLogToErrors</directive> <code>On</code> directive</li>
165 <p>The first option, the <code>%{isapi-parameter}n</code> component,
166 is always available and preferred.</p>
169 <dt><code>HSE_REQ_IS_KEEP_CONN</code></dt>
170 <dd>Will return the negotiated Keep-Alive status.</dd>
172 <dt><code>HSE_REQ_SEND_RESPONSE_HEADER_EX</code></dt>
173 <dd>Will behave as documented, although the <code>fKeepConn</code>
174 flag is ignored.</dd>
176 <dt><code>HSE_REQ_IS_CONNECTED</code></dt>
177 <dd>Will report false if the request has been aborted.</dd>
180 <p>Apache returns <code>FALSE</code> to any unsupported call to
181 <code>ServerSupportFunction</code>, and sets the
182 <code>GetLastError</code> value to
183 <code>ERROR_INVALID_PARAMETER</code>.</p>
185 <p><code>ReadClient</code> retrieves the request body exceeding the
186 initial buffer (defined by <directive module="mod_isapi"
187 >ISAPIReadAheadBuffer</directive>). Based on the
188 <directive>ISAPIReadAheadBuffer</directive> setting (number of bytes
189 to buffer prior to calling the ISAPI handler) shorter requests are sent
190 complete to the extension when it is invoked. If the request is
191 longer, the ISAPI extension must use <code>ReadClient</code> to
192 retrieve the remaining request body.</p>
194 <p><code>WriteClient</code> is supported, but only with the
195 <code>HSE_IO_SYNC</code> flag or no option flag (value of
196 <code>0</code>). Any other <code>WriteClient</code> request
197 will be rejected with a return value of <code>FALSE</code>, and a
198 <code>GetLastError</code> value of
199 <code>ERROR_INVALID_PARAMETER</code>.</p>
201 <p><code>GetServerVariable</code> is supported, although extended server
202 variables do not exist (as defined by other servers.) All the
203 usual Apache CGI environment variables are available from
204 <code>GetServerVariable</code>, as well as the <code>ALL_HTTP</code>
205 and <code>ALL_RAW</code> values.</p>
207 <p>Apache 2.0 <module>mod_isapi</module> supports additional
208 features introduced in later versions of the ISAPI specification,
209 as well as limited emulation of async I/O and the
210 <code>TransmitFile</code> semantics. Apache also supports preloading
211 ISAPI .dlls for performance, neither of which were not available under
212 Apache 1.3 <code>mod_isapi</code>.</p>
216 <name>ISAPICacheFile</name>
217 <description>ISAPI .dll files to be loaded at startup</description>
218 <syntax>ISAPICacheFile <var>file-path</var> [<var>file-path</var>]
220 <contextlist><context>server config</context><context>virtual host</context>
224 <p>Specifies a space-separated list of file names to be loaded
225 when the Apache server is launched, and remain loaded until the
226 server is shut down. This directive may be repeated for every
227 ISAPI .dll file desired. The full path name of each file should
228 be specified. If the path name is not absolute, it will be treated
229 relative to <directive module="core">ServerRoot</directive>.</p>
234 <name>ISAPIReadAheadBuffer</name>
235 <description>Size of the Read Ahead Buffer sent to ISAPI
236 extensions</description>
237 <syntax>ISAPIReadAheadBuffer <var>size</var></syntax>
238 <default>ISAPIReadAheadBuffer 49152</default>
239 <contextlist><context>server config</context><context>virtual host</context>
240 <context>directory</context><context>.htaccess</context></contextlist>
241 <override>FileInfo</override>
244 <p>Defines the maximum size of the Read Ahead Buffer sent to
245 ISAPI extensions when they are initially invoked. All remaining
246 data must be retrieved using the <code>ReadClient</code> callback; some
247 ISAPI extensions may not support the <code>ReadClient</code> function.
248 Refer questions to the ISAPI extension's author.</p>
253 <name>ISAPILogNotSupported</name>
254 <description>Log unsupported feature requests from ISAPI
255 extensions</description>
256 <syntax>ISAPILogNotSupported on|off</syntax>
257 <default>ISAPILogNotSupported off</default>
258 <contextlist><context>server config</context><context>virtual host</context>
259 <context>directory</context><context>.htaccess</context></contextlist>
260 <override>FileInfo</override>
263 <p>Logs all requests for unsupported features from ISAPI
264 extensions in the server error log. This may help administrators
265 to track down problems. Once set to on and all desired ISAPI modules
266 are functioning, it should be set back to off.</p>
271 <name>ISAPIAppendLogToErrors</name>
272 <description>Record <code>HSE_APPEND_LOG_PARAMETER</code> requests from
273 ISAPI extensions to the error log</description>
274 <syntax>ISAPIAppendLogToErrors on|off</syntax>
275 <default>ISAPIAppendLogToErrors off</default>
276 <contextlist><context>server config</context><context>virtual host</context>
277 <context>directory</context><context>.htaccess</context></contextlist>
278 <override>FileInfo</override>
281 <p>Record <code>HSE_APPEND_LOG_PARAMETER</code> requests from ISAPI
282 extensions to the server error log.</p>
287 <name>ISAPIAppendLogToQuery</name>
288 <description>Record <code>HSE_APPEND_LOG_PARAMETER</code> requests from
289 ISAPI extensions to the query field</description>
290 <syntax>ISAPIAppendLogToQuery on|off</syntax>
291 <default>ISAPIAppendLogToQuery on</default>
292 <contextlist><context>server config</context><context>virtual host</context>
293 <context>directory</context><context>.htaccess</context></contextlist>
294 <override>FileInfo</override>
297 <p>Record <code>HSE_APPEND_LOG_PARAMETER</code> requests from ISAPI
298 extensions to the query field (appended to the <directive
299 module="mod_log_config">CustomLog</directive> <code>%q</code>
305 <name>ISAPIFakeAsync</name>
306 <description>Fake asynchronous support for ISAPI callbacks</description>
307 <syntax>ISAPIFakeAsync on|off</syntax>
308 <default>ISAPIFakeAsync off</default>
309 <contextlist><context>server config</context><context>virtual host</context>
310 <context>directory</context><context>.htaccess</context></contextlist>
311 <override>FileInfo</override>
314 <p>While set to on, asynchronous support for ISAPI callbacks is