granicus.if.org Git - apache/blob - docs/manual/mod/mod_isapi.html

   1 <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN">
   2 <HTML>
   3 <HEAD>
   4 <TITLE>Apache module mod_isapi</TITLE>
   5 </HEAD>
   6
   7 <!-- Background white, links blue (unvisited), navy (visited), red (active) -->
   8 <BODY
   9  BGCOLOR="#FFFFFF"
  10  TEXT="#000000"
  11  LINK="#0000FF"
  12  VLINK="#000080"
  13  ALINK="#FF0000"
  14 >
  15 <!--#include virtual="header.html" -->
  16
  17 <H1 ALIGN="CENTER">Module mod_isapi</H1>
  18
  19 <P>This module supports ISAPI Extensions within Apache for Windows.</P>
  20
  21 <P><A
  22 HREF="module-dict.html#Status"
  23 REL="Help"
  24 ><STRONG>Status:</STRONG></A> Base
  25 <BR>
  26 <A
  27 HREF="module-dict.html#SourceFile"
  28 REL="Help"
  29 ><STRONG>Source File:</STRONG></A> mod_isapi.c
  30 <BR>
  31 <A
  32 HREF="module-dict.html#ModuleIdentifier"
  33 REL="Help"
  34 ><STRONG>Module Identifier:</STRONG></A> isapi_module
  35 <BR>
  36 <A
  37 HREF="module-dict.html#Compatibility"
  38 REL="Help"
  39 ><STRONG>Compatibility:</STRONG></A> WIN32 only
  40 </P>
  41
  42 <H2>Summary</H2>
  43
  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>
  47
  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>
  53
  54 <H2>Directives</H2>
  55 <UL>
  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>
  61 </UL>
  62
  63 <H2>Usage</H2>
  64
  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
  69    following line:</P>
  70
  71 <PRE>
  72     AddHandler isapi-isa .dll
  73 </PRE>
  74
  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:
  78
  79 <PRE>
  80     ISAPICacheFile c:/WebWork/Scripts/ISAPI/mytest.dll
  81 </PRE>
  82
  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>
  87
  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>
  91
  92 <H2><A NAME="notes">Additional Notes</A></H2>
  93
  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>
 102
 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>
 111
 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>
 115
 116 <H2><A NAME="journal">Programmer's Journal</A></H2>
 117
 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>
 120
 121 <DL>
 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).
 125   <DT>HSE_REQ_SEND_URL
 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:
 146       <UL>
 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
 150       </UL>
 151         The first option, the %{isapi-parameter}n component, is always available
 152         and prefered.
 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.
 159 </DL>
 160
 161 <P>Apache returns FALSE to any unsupported call to ServerSupportFunction, and
 162    sets the GetLastError value to ERROR_INVALID_PARAMETER.</P>
 163
 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>
 170
 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>
 175
 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>
 180
 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>
 186
 187 <HR>
 188
 189 <H2><A NAME="isapifilecache">ISAPIFileCache directive</A></H2>
 190 <!--%plaintext &lt;?INDEX {\tt ISAPIFileCache} directive&gt; -->
 191 <A
 192  HREF="directive-dict.html#Syntax"
 193  REL="Help"
 194 ><STRONG>Syntax:</STRONG></A> ISAPIFileCache <EM>file</em> [<em>file</em>] ...<BR>
 195 <A
 196  HREF="directive-dict.html#Context"
 197  REL="Help"
 198 ><STRONG>Context:</STRONG></A> server config<BR>
 199 <A
 200  HREF="directive-dict.html#Override"
 201  REL="Help"
 202 ><STRONG>Override:</STRONG></A> None<BR>
 203 <A
 204  HREF="directive-dict.html#Status"
 205  REL="Help"
 206 ><STRONG>Status:</STRONG></A> Base<BR>
 207 <A
 208  HREF="directive-dict.html#Module"
 209  REL="Help"
 210 ><STRONG>Module:</STRONG></A> mod_isapi<BR>
 211 <A
 212 HREF="module-dict.html#Compatibility"
 213 REL="Help"
 214 ><STRONG>Compatibility:</STRONG></A> Apache 2.0 and later, Win32 only<P>
 215
 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.
 221         <P>
 222 <HR>
 223
 224 <H2><A NAME="isapireadaheadbuffer">ISAPIReadAheadBuffer directive</A></H2>
 225 <!--%plaintext &lt;?INDEX {\tt ISAPIReadAheadBuffer} directive&gt; -->
 226 <A
 227  HREF="directive-dict.html#Syntax"
 228  REL="Help"
 229 ><STRONG>Syntax:</STRONG></A> ISAPIReadAheadBuffer <EM>size</EM><BR>
 230 <A
 231  HREF="directive-dict.html#Default"
 232  REL="Help"
 233 ><STRONG>Default:</STRONG></A> 49152<BR>
 234 <A
 235  HREF="directive-dict.html#Context"
 236  REL="Help"
 237 ><STRONG>Context:</STRONG></A> server config<BR>
 238 <A
 239  HREF="directive-dict.html#Override"
 240  REL="Help"
 241 ><STRONG>Override:</STRONG></A> None<BR>
 242 <A
 243  HREF="directive-dict.html#Status"
 244  REL="Help"
 245 ><STRONG>Status:</STRONG></A> Base<BR>
 246 <A
 247  HREF="directive-dict.html#Module"
 248  REL="Help"
 249 ><STRONG>Module:</STRONG></A> mod_isapi<BR>
 250 <A
 251 HREF="module-dict.html#Compatibility"
 252 REL="Help"
 253 ><STRONG>Compatibility:</STRONG></A> Apache 1.3.13 and later, Win32 only<P>
 254
 255
 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
 261         author.
 262         <P>
 263 <HR>
 264
 265 <H2><A NAME="isapilognotsupported">ISAPILogNotSupported directive</A></H2>
 266 <!--%plaintext &lt;?INDEX {\tt ISAPILogNotSupported} directive&gt; -->
 267 <A
 268  HREF="directive-dict.html#Syntax"
 269  REL="Help"
 270 ><STRONG>Syntax:</STRONG></A> ISAPILogNotSupported on|off<BR>
 271 <A
 272  HREF="directive-dict.html#Default"
 273  REL="Help"
 274 ><STRONG>Default:</STRONG></A> on<BR>
 275 <A
 276  HREF="directive-dict.html#Context"
 277  REL="Help"
 278 ><STRONG>Context:</STRONG></A> server config<BR>
 279 <A
 280  HREF="directive-dict.html#Override"
 281  REL="Help"
 282 ><STRONG>Override:</STRONG></A> None<BR>
 283 <A
 284  HREF="directive-dict.html#Status"
 285  REL="Help"
 286 ><STRONG>Status:</STRONG></A> Base<BR>
 287 <A
 288  HREF="directive-dict.html#Module"
 289  REL="Help"
 290 ><STRONG>Module:</STRONG></A> mod_isapi<BR>
 291 <A
 292 HREF="module-dict.html#Compatibility"
 293 REL="Help"
 294 ><STRONG>Compatibility:</STRONG></A> Apache 1.3.13 and later, Win32 only<P>
 295
 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.
 300         <P>
 301 <HR>
 302
 303 <H2><A NAME="isapiappendlogtoerrors">ISAPIAppendLogToErrors directive</A></H2>
 304 <!--%plaintext &lt;?INDEX {\tt ISAPIAppendLogToErrors} directive&gt; -->
 305 <A
 306  HREF="directive-dict.html#Syntax"
 307  REL="Help"
 308 ><STRONG>Syntax:</STRONG></A> ISAPIAppendLogToErrors on|off<BR>
 309 <A
 310  HREF="directive-dict.html#Default"
 311  REL="Help"
 312 ><STRONG>Default:</STRONG></A> off<BR>
 313 <A
 314  HREF="directive-dict.html#Context"
 315  REL="Help"
 316 ><STRONG>Context:</STRONG></A> server config<BR>
 317 <A
 318  HREF="directive-dict.html#Override"
 319  REL="Help"
 320 ><STRONG>Override:</STRONG></A> None<BR>
 321 <A
 322  HREF="directive-dict.html#Status"
 323  REL="Help"
 324 ><STRONG>Status:</STRONG></A> Base<BR>
 325 <A
 326  HREF="directive-dict.html#Module"
 327  REL="Help"
 328 ><STRONG>Module:</STRONG></A> mod_isapi<BR>
 329 <A
 330 HREF="module-dict.html#Compatibility"
 331 REL="Help"
 332 ><STRONG>Compatibility:</STRONG></A> Apache 1.3.13 and later, Win32 only<P>
 333
 334         Record HSE_APPEND_LOG_PARAMETER requests from ISAPI extentions
 335         to the server error log.
 336         <P>
 337 <HR>
 338
 339 <H2><A NAME="isapiappendlogtoquery">ISAPIAppendLogToQuery directive</A></H2>
 340 <!--%plaintext &lt;?INDEX {\tt ISAPIAppendLogToQuery} directive&gt; -->
 341 <A
 342  HREF="directive-dict.html#Syntax"
 343  REL="Help"
 344 ><STRONG>Syntax:</STRONG></A> ISAPIAppendLogToQuery on|off<BR>
 345 <A
 346  HREF="directive-dict.html#Default"
 347  REL="Help"
 348 ><STRONG>Default:</STRONG></A> off<BR>
 349 <A
 350  HREF="directive-dict.html#Context"
 351  REL="Help"
 352 ><STRONG>Context:</STRONG></A> server config<BR>
 353 <A
 354  HREF="directive-dict.html#Override"
 355  REL="Help"
 356 ><STRONG>Override:</STRONG></A> None<BR>
 357 <A
 358  HREF="directive-dict.html#Status"
 359  REL="Help"
 360 ><STRONG>Status:</STRONG></A> Base<BR>
 361 <A
 362  HREF="directive-dict.html#Module"
 363  REL="Help"
 364 ><STRONG>Module:</STRONG></A> mod_isapi<BR>
 365 <A
 366 HREF="module-dict.html#Compatibility"
 367 REL="Help"
 368 ><STRONG>Compatibility:</STRONG></A> Apache 1.3.13 and later, Win32 only<P>
 369
 370         Record HSE_APPEND_LOG_PARAMETER requests from ISAPI extentions
 371         to the query field (appended to the CustomLog %q component).
 372         <P>
 373
 374 <!--#include virtual="footer.html" -->
 375 </BODY>
 376 </HTML>