1 <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN">
4 <TITLE>Apache module mod_isapi</TITLE>
7 <!-- Background white, links blue (unvisited), navy (visited), red (active) -->
15 <!--#include virtual="header.html" -->
17 <H1 ALIGN="CENTER">Module mod_isapi</H1>
19 <P>This module supports ISAPI Extensions within Apache for Windows.</P>
22 HREF="module-dict.html#Status"
24 ><STRONG>Status:</STRONG></A> Base
27 HREF="module-dict.html#SourceFile"
29 ><STRONG>Source File:</STRONG></A> mod_isapi.c
32 HREF="module-dict.html#ModuleIdentifier"
34 ><STRONG>Module Identifier:</STRONG></A> isapi_module
37 HREF="module-dict.html#Compatibility"
39 ><STRONG>Compatibility:</STRONG></A> WIN32 only
44 <P>This module implements the Internet Server extension API. It allows
45 Internet Server extensions (<EM>e.g.</EM> ISAPI .dll modules) to be
46 served by Apache for Windows, subject to the noted restrictions.</P>
48 <P>ISAPI extension modules (.dll files) are written by third parties. The
49 Apache Group does not author these modules, so we provide no support for
50 them. Please contact the ISAPI's author directly if you are experiencing
51 problems running their ISAPI extention. <STRONG>Please <EM>do not</EM>
52 post such problems to Apache's lists or bug reporting pages.</STRONG></P>
56 <LI><A HREF="#isapifilecache">ISAPIFileCache</A>
57 <LI><A HREF="#isapireadaheadbuffer">ISAPIReadAheadBuffer</A>
58 <LI><A HREF="#isapilognotsupported">ISAPILogNotSupported</A>
59 <LI><A HREF="#isapiappendlogtoerrors">ISAPIAppendLogToErrors</A>
60 <LI><A HREF="#isapiappendlogtoquery">ISAPIAppendLogToQuery</A>
65 <P>In the server configuration file, use the AddHandler directive to
66 associate ISAPI files with the <CODE>isapi-isa</CODE> handler, and map
67 it to the with their file extensions. To enable any .dll file to be
68 processed as an ISAPI extention, edit the httpd.conf file and add the
72 AddHandler isapi-isa .dll
75 <P>There is no capability within the Apache server to leave a requested
76 module loaded. However, you may preload and keep a specific module loaded
77 by using the following syntax in your httpd.conf:
80 ISAPICacheFile c:/WebWork/Scripts/ISAPI/mytest.dll
83 <P>Whether or not you have preloaded an ISAPI extension, all ISAPI
84 extensions are governed by the same permissions and restrictions
85 as CGI scripts. That is, <CODE>Options ExecCGI</CODE> must be set for
86 the directory that contains the ISAPI .dll file.</P>
88 <P>Review the <A HREF="#notes">Additional Notes</A> and the
89 <A HREF="#journal">Programmer's Journal</A> for additional details and
90 clarification of the specific ISAPI support offered by mod_isapi.</P>
92 <H2><A NAME="notes">Additional Notes</A></H2>
94 <P>Apache's ISAPI implementation conforms to all of the ISAPI 2.0
95 specification, except for some "Microsoft-specific" extensions dealing
96 with asynchronous I/O. Apache's I/O model does not allow asynchronous
97 reading and writing in a manner that the ISAPI could access. If an ISA
98 tries to access unsupported features, including async I/O, a message is
99 placed in the error log to help with debugging. Since these messages
100 can become a flood, the directive <CODE>ISAPILogNotSupported Off</CODE>
101 exists to quiet this noise.</P>
103 <P>Some servers, like Microsoft IIS, load the ISAPI extension into the server
104 and keep it loaded until memory usage is too high, or unless configuration
105 options are specified. Apache currently loads and unloads the ISAPI
106 extension each time it is requested, unless the ISAPICacheFile directive
107 is specified. This is inefficient, but Apache's memory model makes this
108 the most effective method. Many ISAPI modules are subtly incompatible
109 with the Apache server, and unloading these modules helps to ensure the
110 stability of the server.</P>
112 <P>Also, remember that while Apache supports ISAPI Extensions, it
113 <STRONG>does not support ISAPI Filters.</STRONG> Support for filters may
114 be added at a later date, but no support is planned at this time.</P>
116 <H2><A NAME="journal">Programmer's Journal</A></H2>
118 <P>If you are programming Apache 2.0 mod_isapi modules, you must limit your
119 calls to ServerSupportFunction to the following directives:</P>
122 <DT>HSE_REQ_SEND_URL_REDIRECT_RESP
123 <DD>Redirect the user to another location.<BR>
124 This must be a fully qualified URL (e.g. http://server/location).
126 <DD>Redirect the user to another location.<BR>
127 This cannot be a fully qualified URL, you are not allowed
128 to pass the protocol or a server name (e.g. simply /location).<BR>
129 This redirection is handled by the server, not the browser.<BR>
130 <STRONG>Warning:</STRONG> in their recent documentation, Microsoft
131 appears to have abandoned the distinction between the two
132 HSE_REQ_SEND_URL functions. Apache continues to treat them as two
133 distinct functions with different requirements and behaviors.
134 <DT>HSE_REQ_SEND_RESPONSE_HEADER
135 <DD>Apache accepts a response body following the header if it follows
136 the blank line (two consecutive newlines) in the headers string
137 argument. This body cannot contain NULLs, since the headers
138 argument is NULL terminated.
139 <DT>HSE_REQ_DONE_WITH_SESSION
140 <DD>Apache considers this a no-op, since the session will be finished
141 when the ISAPI returns from processing.
142 <DT>HSE_REQ_MAP_URL_TO_PATH
143 <DD>Apache will translate a virtual name to a physical name.
144 <DT>HSE_APPEND_LOG_PARAMETER
145 <DD>This logged message may be captured in any of the following logs:
147 <LI>in the \"%{isapi-parameter}n\" component in a CustomLog directive
148 <LI>in the %q log component with the ISAPIAppendLogToQuery On directive
149 <LI>in the error log with the ISAPIAppendLogToErrors On directive
151 The first option, the %{isapi-parameter}n component, is always available
153 <DT>HSE_REQ_IS_KEEP_CONN
154 <DD>Will return the negotiated Keep-Alive status.
155 <DT>HSE_REQ_SEND_RESPONSE_HEADER_EX
156 <DD>Will behave as documented, although the fKeepConn flag is ignored.
157 <DT>HSE_REQ_IS_CONNECTED
158 <DD>Will report false if the request has been aborted.
161 <P>Apache returns FALSE to any unsupported call to ServerSupportFunction, and
162 sets the GetLastError value to ERROR_INVALID_PARAMETER.</P>
164 <P>ReadClient retrieves the request body exceeding the initial buffer
165 (defined by ISAPIReadAheadBuffer). Based on the ISAPIReadAheadBuffer
166 setting (number of bytes to buffer prior to calling the ISAPI handler)
167 shorter requests are sent complete to the extension when it is invoked.
168 If the request is longer, the ISAPI extension must use ReadClient to
169 retrieve the remaining request body.</P>
171 <P>WriteClient is supported, but only with the HSE_IO_SYNC flag or
172 no option flag (value of 0). Any other WriteClient request will
173 be rejected with a return value of FALSE, and a GetLastError
174 value of ERROR_INVALID_PARAMETER.</P>
176 <P>GetServerVariable is supported, although extended server variables do not
177 exist (as defined by other servers.) All the usual Apache CGI environment
178 variables are available from GetServerVariable, as well as the ALL_HTTP
179 and ALL_RAW values.</P>
181 <P>Apache 2.0 mod_isapi supports additional features introduced in later
182 versions of the ISAPI specification, as well as limited emulation of
183 async I/O and the TransmitFile semantics. Apache also supports preloading
184 ISAPI .dlls for performance, neither of which were not available under
185 Apache 1.3 mod_isapi.</P>
189 <H2><A NAME="isapifilecache">ISAPIFileCache directive</A></H2>
190 <!--%plaintext <?INDEX {\tt ISAPIFileCache} directive> -->
192 HREF="directive-dict.html#Syntax"
194 ><STRONG>Syntax:</STRONG></A> ISAPIFileCache <EM>file [file...]</EM><BR>
196 HREF="directive-dict.html#Context"
198 ><STRONG>Context:</STRONG></A> server config<BR>
200 HREF="directive-dict.html#Override"
202 ><STRONG>Override:</STRONG></A> None<BR>
204 HREF="directive-dict.html#Status"
206 ><STRONG>Status:</STRONG></A> Base<BR>
208 HREF="directive-dict.html#Module"
210 ><STRONG>Module:</STRONG></A> mod_isapi<BR>
212 HREF="module-dict.html#Compatibility"
214 ><STRONG>Compatibility:</STRONG></A> Apache 2.0 and later, Win32 only<P>
216 Specifies a space-separated list of file names to be loaded
217 when the Apache server is launched, and remain loaded until
218 the server is shut down. This directive may be repeated
219 for every ISAPI .dll file desired. The full path name of
220 each file should be specified.
224 <H2><A NAME="isapireadaheadbuffer">ISAPIReadAheadBuffer directive</A></H2>
225 <!--%plaintext <?INDEX {\tt ISAPIReadAheadBuffer} directive> -->
227 HREF="directive-dict.html#Syntax"
229 ><STRONG>Syntax:</STRONG></A> ISAPIReadAheadBuffer <EM>size</EM><BR>
231 HREF="directive-dict.html#Default"
233 ><STRONG>Default:</STRONG></A> 49152<BR>
235 HREF="directive-dict.html#Context"
237 ><STRONG>Context:</STRONG></A> server config<BR>
239 HREF="directive-dict.html#Override"
241 ><STRONG>Override:</STRONG></A> None<BR>
243 HREF="directive-dict.html#Status"
245 ><STRONG>Status:</STRONG></A> Base<BR>
247 HREF="directive-dict.html#Module"
249 ><STRONG>Module:</STRONG></A> mod_isapi<BR>
251 HREF="module-dict.html#Compatibility"
253 ><STRONG>Compatibility:</STRONG></A> Apache 1.3.13 and later, Win32 only<P>
256 Defines the maximum size of the Read Ahead Buffer sent to
257 ISAPI extentions when they are initally invoked. All
258 remaining data must be retrieved using the ReadClient
259 callback; some ISAPI extensions may not support the
260 ReadClient function. Refer questions to the ISAPI extention's
265 <H2><A NAME="isapilognotsupported">ISAPILogNotSupported directive</A></H2>
266 <!--%plaintext <?INDEX {\tt ISAPILogNotSupported} directive> -->
268 HREF="directive-dict.html#Syntax"
270 ><STRONG>Syntax:</STRONG></A> ISAPILogNotSupported <EM>on|off</EM><BR>
272 HREF="directive-dict.html#Default"
274 ><STRONG>Default:</STRONG></A> on<BR>
276 HREF="directive-dict.html#Context"
278 ><STRONG>Context:</STRONG></A> server config<BR>
280 HREF="directive-dict.html#Override"
282 ><STRONG>Override:</STRONG></A> None<BR>
284 HREF="directive-dict.html#Status"
286 ><STRONG>Status:</STRONG></A> Base<BR>
288 HREF="directive-dict.html#Module"
290 ><STRONG>Module:</STRONG></A> mod_isapi<BR>
292 HREF="module-dict.html#Compatibility"
294 ><STRONG>Compatibility:</STRONG></A> Apache 1.3.13 and later, Win32 only<P>
296 Logs all requests for unsupported features from ISAPI extentions
297 in the server error log. While this should be turned off once
298 all desired ISAPI modules are functioning, it defaults to on
299 to help administrators track down problems.
303 <H2><A NAME="isapiappendlogtoerrors">ISAPIAppendLogToErrors directive</A></H2>
304 <!--%plaintext <?INDEX {\tt ISAPIAppendLogToErrors} directive> -->
306 HREF="directive-dict.html#Syntax"
308 ><STRONG>Syntax:</STRONG></A> ISAPIAppendLogToErrors <EM>on|off</EM><BR>
310 HREF="directive-dict.html#Default"
312 ><STRONG>Default:</STRONG></A> off<BR>
314 HREF="directive-dict.html#Context"
316 ><STRONG>Context:</STRONG></A> server config<BR>
318 HREF="directive-dict.html#Override"
320 ><STRONG>Override:</STRONG></A> None<BR>
322 HREF="directive-dict.html#Status"
324 ><STRONG>Status:</STRONG></A> Base<BR>
326 HREF="directive-dict.html#Module"
328 ><STRONG>Module:</STRONG></A> mod_isapi<BR>
330 HREF="module-dict.html#Compatibility"
332 ><STRONG>Compatibility:</STRONG></A> Apache 1.3.13 and later, Win32 only<P>
334 Record HSE_APPEND_LOG_PARAMETER requests from ISAPI extentions
335 to the server error log.
339 <H2><A NAME="isapiappendlogtoquery">ISAPIAppendLogToQuery directive</A></H2>
340 <!--%plaintext <?INDEX {\tt ISAPIAppendLogToQuery} directive> -->
342 HREF="directive-dict.html#Syntax"
344 ><STRONG>Syntax:</STRONG></A> ISAPIAppendLogToQuery <EM>on|off</EM><BR>
346 HREF="directive-dict.html#Default"
348 ><STRONG>Default:</STRONG></A> off<BR>
350 HREF="directive-dict.html#Context"
352 ><STRONG>Context:</STRONG></A> server config<BR>
354 HREF="directive-dict.html#Override"
356 ><STRONG>Override:</STRONG></A> None<BR>
358 HREF="directive-dict.html#Status"
360 ><STRONG>Status:</STRONG></A> Base<BR>
362 HREF="directive-dict.html#Module"
364 ><STRONG>Module:</STRONG></A> mod_isapi<BR>
366 HREF="module-dict.html#Compatibility"
368 ><STRONG>Compatibility:</STRONG></A> Apache 1.3.13 and later, Win32 only<P>
370 Record HSE_APPEND_LOG_PARAMETER requests from ISAPI extentions
371 to the query field (appended to the CustomLog %q component).
374 <!--#include virtual="footer.html" -->