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

   1 <?xml version="1.0" encoding="ISO-8859-1"?>
   2 <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
   3 <html xmlns="http://www.w3.org/1999/xhtml" lang="en" xml:lang="en"><head><!--
   4         XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
   5               This file is generated from xml source: DO NOT EDIT
   6         XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
   7       -->
   8 <title>mod_isapi - Apache HTTP Server</title>
   9 <link href="../style/css/manual.css" rel="stylesheet" media="all" type="text/css" title="Main stylesheet" />
  10 <link href="../style/css/manual-loose-100pc.css" rel="alternate stylesheet" media="all" type="text/css" title="No Sidebar - Default font size" />
  11 <link href="../style/css/manual-print.css" rel="stylesheet" media="print" type="text/css" />
  12 <link href="../images/favicon.ico" rel="shortcut icon" /></head>
  13 <body>
  14 <div id="page-header">
  15 <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>
  16 <p class="apache">Apache HTTP Server Version 2.1</p>
  17 <img alt="" src="../images/feather.gif" /></div>
  18 <div class="up"><a href="./"><img title="&lt;-" alt="&lt;-" src="../images/left.gif" /></a></div>
  19 <div id="path">
  20 <a href="http://www.apache.org/">Apache</a> &gt; <a href="http://httpd.apache.org/">HTTP Server</a> &gt; <a href="http://httpd.apache.org/docs-project/">Documentation</a> &gt; <a href="../">Version 2.1</a> &gt; <a href="./">Modules</a></div>
  21 <div id="page-content">
  22 <div id="preamble"><h1>Apache Module mod_isapi</h1>
  23 <div class="toplang">
  24 <p><span>Available Languages: </span><a href="../en/mod/mod_isapi.html" title="English">&nbsp;en&nbsp;</a></p>
  25 </div>
  26 <table class="module"><tr><th><a href="module-dict.html#Description">Description:</a></th><td>ISAPI Extensions within Apache for Windows</td></tr>
  27 <tr><th><a href="module-dict.html#Status">Status:</a></th><td>Base</td></tr>
  28 <tr><th><a href="module-dict.html#ModuleIdentifier">Module Identifier:</a></th><td>isapi_module</td></tr>
  29 <tr><th><a href="module-dict.html#SourceFile">Source File:</a></th><td>mod_isapi.c</td></tr>
  30 <tr><th><a href="module-dict.html#Compatibility">Compatibility:</a></th><td>Win32 only</td></tr></table>
  31 <h3>Summary</h3>
  32
  33     <p>This module implements the Internet Server extension API. It
  34     allows Internet Server extensions (<em>e.g.</em> ISAPI .dll
  35     modules) to be served by Apache for Windows, subject to the
  36     noted restrictions.</p>
  37
  38     <p>ISAPI extension modules (.dll files) are written by third
  39     parties. The Apache Group does not author these modules, so we
  40     provide no support for them. Please contact the ISAPI's author
  41     directly if you are experiencing problems running their ISAPI
  42     extension. <strong>Please <em>do not</em> post such problems to
  43     Apache's lists or bug reporting pages.</strong></p>
  44 </div>
  45 <div id="quickview"><h3 class="directives">Directives</h3>
  46 <ul id="toc">
  47 <li><img alt="" src="../images/down.gif" /> <a href="#isapiappendlogtoerrors">ISAPIAppendLogToErrors</a></li>
  48 <li><img alt="" src="../images/down.gif" /> <a href="#isapiappendlogtoquery">ISAPIAppendLogToQuery</a></li>
  49 <li><img alt="" src="../images/down.gif" /> <a href="#isapicachefile">ISAPICacheFile</a></li>
  50 <li><img alt="" src="../images/down.gif" /> <a href="#isapifakeasync">ISAPIFakeAsync</a></li>
  51 <li><img alt="" src="../images/down.gif" /> <a href="#isapilognotsupported">ISAPILogNotSupported</a></li>
  52 <li><img alt="" src="../images/down.gif" /> <a href="#isapireadaheadbuffer">ISAPIReadAheadBuffer</a></li>
  53 </ul>
  54 <h3>Topics</h3>
  55 <ul id="topics">
  56 <li><img alt="" src="../images/down.gif" /> <a href="#usage">Usage</a></li>
  57 <li><img alt="" src="../images/down.gif" /> <a href="#notes">Additional Notes</a></li>
  58 <li><img alt="" src="../images/down.gif" /> <a href="#journal">Programmer's Journal</a></li>
  59 </ul></div>
  60 <div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
  61 <div class="section">
  62 <h2><a name="usage" id="usage">Usage</a></h2>
  63
  64     <p>In the server configuration file, use
  65     the <code class="directive"><a href="../mod/mod_mime.html#addhandler">AddHandler</a></code> directive to
  66     associate ISAPI files with the <code>isapi-isa</code> handler, and map
  67     it to them with their file extensions. To enable any .dll file to be
  68     processed as an ISAPI extension, edit the httpd.conf file and add the
  69     following line:</p>
  70     <div class="example"><p><code>
  71         AddHandler isapi-isa .dll
  72     </code></p></div>
  73
  74     <p>There is no capability within the Apache server to leave a
  75     requested module loaded. However, you may preload and keep a
  76     specific module loaded by using the following syntax in your
  77     httpd.conf:</p>
  78     <div class="example"><p><code>
  79         ISAPICacheFile c:/WebWork/Scripts/ISAPI/mytest.dll
  80     </code></p></div>
  81
  82     <p>Whether or not you have preloaded an ISAPI extension, all
  83     ISAPI extensions are governed by the same permissions and
  84     restrictions as CGI scripts. That is, <code class="directive"><a href="../mod/core.html#options">Options</a></code> <code>ExecCGI</code> must be set for the
  85     directory that contains the ISAPI .dll file.</p>
  86
  87     <p>Review the <a href="#notes">Additional Notes</a> and the <a href="#journal">Programmer's Journal</a> for additional details
  88     and clarification of the specific ISAPI support offered by
  89     <code class="module"><a href="../mod/mod_isapi.html">mod_isapi</a></code>.</p>
  90 </div><div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
  91 <div class="section">
  92 <h2><a name="notes" id="notes">Additional Notes</a></h2>
  93
  94     <p>Apache's ISAPI implementation conforms to all of the ISAPI
  95     2.0 specification, except for some "Microsoft-specific"
  96     extensions dealing with asynchronous I/O. Apache's I/O model
  97     does not allow asynchronous reading and writing in a manner
  98     that the ISAPI could access. If an ISA tries to access
  99     unsupported features, including async I/O, a message is placed
 100     in the error log to help with debugging. Since these messages
 101     can become a flood, the directive <code>ISAPILogNotSupported
 102     Off</code> exists to quiet this noise.</p>
 103
 104     <p>Some servers, like Microsoft IIS, load the ISAPI extension
 105     into the server and keep it loaded until memory usage is too
 106     high, or unless configuration options are specified. Apache
 107     currently loads and unloads the ISAPI extension each time it is
 108     requested, unless the <code class="directive"><a href="#isapicachefile">ISAPICacheFile</a></code> directive is specified.
 109     This is inefficient, but Apache's memory model makes this the
 110     most effective method. Many ISAPI modules are subtly
 111     incompatible with the Apache server, and unloading these
 112     modules helps to ensure the stability of the server.</p>
 113
 114     <p>Also, remember that while Apache supports ISAPI Extensions,
 115     it <strong>does not support ISAPI Filters</strong>. Support for
 116     filters may be added at a later date, but no support is planned
 117     at this time.</p>
 118 </div><div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
 119 <div class="section">
 120 <h2><a name="journal" id="journal">Programmer's Journal</a></h2>
 121
 122     <p>If you are programming Apache 2.0 <code class="module"><a href="../mod/mod_isapi.html">mod_isapi</a></code>
 123     modules, you must limit your calls to <code>ServerSupportFunction</code>
 124     to the following directives:</p>
 125
 126     <dl>
 127       <dt><code>HSE_REQ_SEND_URL_REDIRECT_RESP</code></dt>
 128       <dd>Redirect the user to another location.<br />
 129       This must be a fully qualified URL (<em>e.g.</em>
 130       <code>http://server/location</code>).</dd>
 131
 132       <dt><code>HSE_REQ_SEND_URL</code></dt>
 133       <dd>Redirect the user to another location.<br />
 134       This cannot be a fully qualified URL, you are not allowed to
 135       pass the protocol or a server name (<em>e.g.</em> simply
 136       <code>/location</code>).<br />
 137       This redirection is handled by the server, not the
 138       browser.<br />
 139       <div class="warning"><h3>Warning</h3>
 140         <p>In their recent documentation, Microsoft appears to have
 141         abandoned the distinction between the two
 142         <code>HSE_REQ_SEND_URL</code> functions. Apache continues to treat
 143         them as two distinct functions with different requirements
 144         and behaviors.</p>
 145       </div></dd>
 146
 147       <dt><code>HSE_REQ_SEND_RESPONSE_HEADER</code></dt>
 148       <dd>Apache accepts a response body following the header if it
 149       follows the blank line (two consecutive newlines) in the
 150       headers string argument. This body cannot contain NULLs,
 151       since the headers argument is NULL terminated.</dd>
 152
 153       <dt><code>HSE_REQ_DONE_WITH_SESSION</code></dt>
 154       <dd>Apache considers this a no-op, since the session will be
 155       finished when the ISAPI returns from processing.</dd>
 156
 157       <dt><code>HSE_REQ_MAP_URL_TO_PATH</code></dt>
 158       <dd>Apache will translate a virtual name to a physical
 159       name.</dd>
 160
 161       <dt><code>HSE_APPEND_LOG_PARAMETER</code></dt>
 162       <dd>
 163         This logged message may be captured in any of the following
 164         logs:
 165
 166         <ul>
 167           <li>in the <code>\"%{isapi-parameter}n\"</code> component in a
 168           <code class="directive"><a href="../mod/mod_log_config.html#customlog">CustomLog</a></code>
 169           directive</li>
 170
 171           <li>in the <code>%q</code> log component with the
 172           <code class="directive"><a href="#isapiappendlogtoquery">ISAPIAppendLogToQuery</a></code>
 173           <code>On</code> directive</li>
 174
 175           <li>in the error log with the <code class="directive"><a href="#isapiappendlogtoerrors">ISAPIAppendLogToErrors</a></code> <code>On</code> directive</li>
 176         </ul>
 177
 178         <p>The first option, the <code>%{isapi-parameter}n</code> component,
 179         is always available and preferred.</p>
 180       </dd>
 181
 182       <dt><code>HSE_REQ_IS_KEEP_CONN</code></dt>
 183       <dd>Will return the negotiated Keep-Alive status.</dd>
 184
 185       <dt><code>HSE_REQ_SEND_RESPONSE_HEADER_EX</code></dt>
 186       <dd>Will behave as documented, although the <code>fKeepConn</code>
 187       flag is ignored.</dd>
 188
 189       <dt><code>HSE_REQ_IS_CONNECTED</code></dt>
 190       <dd>Will report false if the request has been aborted.</dd>
 191     </dl>
 192
 193     <p>Apache returns <code>FALSE</code> to any unsupported call to
 194     <code>ServerSupportFunction</code>, and sets the
 195     <code>GetLastError</code> value to
 196     <code>ERROR_INVALID_PARAMETER</code>.</p>
 197
 198     <p><code>ReadClient</code> retrieves the request body exceeding the
 199     initial buffer (defined by <code class="directive"><a href="#isapireadaheadbuffer">ISAPIReadAheadBuffer</a></code>). Based on the
 200     <code class="directive">ISAPIReadAheadBuffer</code> setting (number of bytes
 201     to buffer prior to calling the ISAPI handler) shorter requests are sent
 202     complete to the extension when it is invoked. If the request is
 203     longer, the ISAPI extension must use <code>ReadClient</code> to
 204     retrieve the remaining request body.</p>
 205
 206     <p><code>WriteClient</code> is supported, but only with the
 207     <code>HSE_IO_SYNC</code> flag or no option flag (value of
 208     <code>0</code>). Any other <code>WriteClient</code> request
 209     will be rejected with a return value of <code>FALSE</code>, and a
 210     <code>GetLastError</code> value of
 211     <code>ERROR_INVALID_PARAMETER</code>.</p>
 212
 213     <p><code>GetServerVariable</code> is supported, although extended server
 214     variables do not exist (as defined by other servers.) All the
 215     usual Apache CGI environment variables are available from
 216     <code>GetServerVariable</code>, as well as the <code>ALL_HTTP</code>
 217     and <code>ALL_RAW</code> values.</p>
 218
 219     <p>Apache 2.0 <code class="module"><a href="../mod/mod_isapi.html">mod_isapi</a></code> supports additional
 220     features introduced in later versions of the ISAPI specification,
 221     as well as limited emulation of async I/O and the
 222     <code>TransmitFile</code> semantics.  Apache also supports preloading
 223     ISAPI .dlls for performance, neither of which were not available under
 224     Apache 1.3 <code>mod_isapi</code>.</p>
 225 </div>
 226 <div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
 227 <div class="directive-section"><h2><a name="ISAPIAppendLogToErrors" id="ISAPIAppendLogToErrors">ISAPIAppendLogToErrors</a> <a name="isapiappendlogtoerrors" id="isapiappendlogtoerrors">Directive</a></h2>
 228 <table class="directive">
 229 <tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Record HSE_APPEND_LOG_PARAMETER requests from
 230 ISAPI extensions to the error log</td></tr>
 231 <tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>ISAPIAppendLogToErrors on|off</code></td></tr>
 232 <tr><th><a href="directive-dict.html#Default">Default:</a></th><td><code>ISAPIAppendLogToErrors off</code></td></tr>
 233 <tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config, virtual host, directory, .htaccess</td></tr>
 234 <tr><th><a href="directive-dict.html#Override">Override:</a></th><td>FileInfo</td></tr>
 235 <tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Base</td></tr>
 236 <tr><th><a href="directive-dict.html#Module">Module:</a></th><td>mod_isapi</td></tr>
 237 </table>
 238     <p>Record <code>HSE_APPEND_LOG_PARAMETER</code> requests from ISAPI
 239     extensions to the server error log.</p>
 240
 241 </div>
 242 <div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
 243 <div class="directive-section"><h2><a name="ISAPIAppendLogToQuery" id="ISAPIAppendLogToQuery">ISAPIAppendLogToQuery</a> <a name="isapiappendlogtoquery" id="isapiappendlogtoquery">Directive</a></h2>
 244 <table class="directive">
 245 <tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Record HSE_APPEND_LOG_PARAMETER requests from
 246 ISAPI extensions to the query field</td></tr>
 247 <tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>ISAPIAppendLogToQuery on|off</code></td></tr>
 248 <tr><th><a href="directive-dict.html#Default">Default:</a></th><td><code>ISAPIAppendLogToQuery on</code></td></tr>
 249 <tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config, virtual host, directory, .htaccess</td></tr>
 250 <tr><th><a href="directive-dict.html#Override">Override:</a></th><td>FileInfo</td></tr>
 251 <tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Base</td></tr>
 252 <tr><th><a href="directive-dict.html#Module">Module:</a></th><td>mod_isapi</td></tr>
 253 </table>
 254     <p>Record <code>HSE_APPEND_LOG_PARAMETER</code> requests from ISAPI
 255     extensions to the query field (appended to the <code class="directive"><a href="../mod/mod_log_config.html#customlog">CustomLog</a></code> <code>%q</code>
 256     component).</p>
 257
 258 </div>
 259 <div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
 260 <div class="directive-section"><h2><a name="ISAPICacheFile" id="ISAPICacheFile">ISAPICacheFile</a> <a name="isapicachefile" id="isapicachefile">Directive</a></h2>
 261 <table class="directive">
 262 <tr><th><a href="directive-dict.html#Description">Description:</a></th><td>ISAPI .dll files to be loaded at startup</td></tr>
 263 <tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>ISAPICacheFile <var>file-path</var> [<var>file-path</var>]
 264 ...</code></td></tr>
 265 <tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config, virtual host</td></tr>
 266 <tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Base</td></tr>
 267 <tr><th><a href="directive-dict.html#Module">Module:</a></th><td>mod_isapi</td></tr>
 268 </table>
 269     <p>Specifies a space-separated list of file names to be loaded
 270     when the Apache server is launched, and remain loaded until the
 271     server is shut down. This directive may be repeated for every
 272     ISAPI .dll file desired. The full path name of each file should
 273     be specified. If the path name is not absolute, it will be treated
 274     relative to <code class="directive"><a href="../mod/core.html#serverroot">ServerRoot</a></code>.</p>
 275
 276 </div>
 277 <div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
 278 <div class="directive-section"><h2><a name="ISAPIFakeAsync" id="ISAPIFakeAsync">ISAPIFakeAsync</a> <a name="isapifakeasync" id="isapifakeasync">Directive</a></h2>
 279 <table class="directive">
 280 <tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Fake asynchronous support for ISAPI callbacks</td></tr>
 281 <tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>ISAPIFakeAsync on|off</code></td></tr>
 282 <tr><th><a href="directive-dict.html#Default">Default:</a></th><td><code>ISAPIFakeAsync off</code></td></tr>
 283 <tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config, virtual host, directory, .htaccess</td></tr>
 284 <tr><th><a href="directive-dict.html#Override">Override:</a></th><td>FileInfo</td></tr>
 285 <tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Base</td></tr>
 286 <tr><th><a href="directive-dict.html#Module">Module:</a></th><td>mod_isapi</td></tr>
 287 </table>
 288     <p>While set to on, asynchronous support for ISAPI callbacks is
 289     simulated.</p>
 290
 291 </div>
 292 <div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
 293 <div class="directive-section"><h2><a name="ISAPILogNotSupported" id="ISAPILogNotSupported">ISAPILogNotSupported</a> <a name="isapilognotsupported" id="isapilognotsupported">Directive</a></h2>
 294 <table class="directive">
 295 <tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Log unsupported feature requests from ISAPI
 296 extensions</td></tr>
 297 <tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>ISAPILogNotSupported on|off</code></td></tr>
 298 <tr><th><a href="directive-dict.html#Default">Default:</a></th><td><code>ISAPILogNotSupported off</code></td></tr>
 299 <tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config, virtual host, directory, .htaccess</td></tr>
 300 <tr><th><a href="directive-dict.html#Override">Override:</a></th><td>FileInfo</td></tr>
 301 <tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Base</td></tr>
 302 <tr><th><a href="directive-dict.html#Module">Module:</a></th><td>mod_isapi</td></tr>
 303 </table>
 304     <p>Logs all requests for unsupported features from ISAPI
 305     extensions in the server error log. This may help administrators
 306     to track down problems. Once set to on and all desired ISAPI modules
 307     are functioning, it should be set back to off.</p>
 308
 309 </div>
 310 <div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
 311 <div class="directive-section"><h2><a name="ISAPIReadAheadBuffer" id="ISAPIReadAheadBuffer">ISAPIReadAheadBuffer</a> <a name="isapireadaheadbuffer" id="isapireadaheadbuffer">Directive</a></h2>
 312 <table class="directive">
 313 <tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Size of the Read Ahead Buffer sent to ISAPI
 314 extensions</td></tr>
 315 <tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>ISAPIReadAheadBuffer <var>size</var></code></td></tr>
 316 <tr><th><a href="directive-dict.html#Default">Default:</a></th><td><code>ISAPIReadAheadBuffer 49152</code></td></tr>
 317 <tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config, virtual host, directory, .htaccess</td></tr>
 318 <tr><th><a href="directive-dict.html#Override">Override:</a></th><td>FileInfo</td></tr>
 319 <tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Base</td></tr>
 320 <tr><th><a href="directive-dict.html#Module">Module:</a></th><td>mod_isapi</td></tr>
 321 </table>
 322     <p>Defines the maximum size of the Read Ahead Buffer sent to
 323     ISAPI extensions when they are initially invoked. All remaining
 324     data must be retrieved using the <code>ReadClient</code> callback; some
 325     ISAPI extensions may not support the <code>ReadClient</code> function.
 326     Refer questions to the ISAPI extension's author.</p>
 327
 328 </div>
 329 </div>
 330 <div class="bottomlang">
 331 <p><span>Available Languages: </span><a href="../en/mod/mod_isapi.html" title="English">&nbsp;en&nbsp;</a></p>
 332 </div><div id="footer">
 333 <p class="apache">Copyright 1999-2004 The Apache Software Foundation.<br />Licensed under the <a href="http://www.apache.org/licenses/LICENSE-2.0">Apache License, Version 2.0</a>.</p>
 334 <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>
 335 </body></html>