httpd-docs mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From wr...@locus.apache.org
Subject cvs commit: httpd-docs-1.3/htdocs/manual/mod mod_isapi.html
Date Tue, 26 Sep 2000 15:23:17 GMT
wrowe       00/09/26 08:23:16

  Modified:    htdocs/manual/mod mod_isapi.html
  Log:
    Some corrections, clarifications and new directives.
    Hopefully in the new 'proper' form, but feel free to correct me.
  
  Revision  Changes    Path
  1.7       +258 -51   httpd-docs-1.3/htdocs/manual/mod/mod_isapi.html
  
  Index: mod_isapi.html
  ===================================================================
  RCS file: /home/cvs/httpd-docs-1.3/htdocs/manual/mod/mod_isapi.html,v
  retrieving revision 1.6
  retrieving revision 1.7
  diff -u -r1.6 -r1.7
  --- mod_isapi.html	2000/07/28 22:58:29	1.6
  +++ mod_isapi.html	2000/09/26 15:23:14	1.7
  @@ -16,58 +16,249 @@
   
   <H1 ALIGN="CENTER">Module mod_isapi</H1>
   
  -<P>This module is contained in the <CODE>mod_isapi.c</CODE> file, and
is
  -   compiled into the Windows distribution by default. It provides support for 
  -   ISAPI Extensions when running under Microsoft Windows. Any document with 
  -   a handler of <CODE>isapi-isa</CODE> will be processed by this module.</P>
  -
  -<H2>Purpose</H2>
  -
  -<P>This module implements the Internet Server Extension API. It allows 
  -   Internet Server Applications (<EM>i.e.</EM>, ISAPI .dll handler modules)
  -   to be used with Apache for Windows, subject to the noted restrictions.</P>
  +<P>This module supports ISAPI Extensions within Apache for Windows.</P>
   
  +<P><A
  +HREF="module-dict.html#Status"
  +REL="Help"
  +><STRONG>Status:</STRONG></A> Base
  +<BR>
  +<A
  +HREF="module-dict.html#SourceFile"
  +REL="Help"
  +><STRONG>Source File:</STRONG></A> mod_isapi.c
  +<BR>
  +<A
  +HREF="module-dict.html#ModuleIdentifier"
  +REL="Help"
  +><STRONG>Module Identifier:</STRONG></A> isapi_module
  +<BR>
  +<A
  +HREF="module-dict.html#Compatibility"
  +REL="Help"
  +><STRONG>Compatibility:</STRONG></A> WIN32 only
  +</P>
  +
  +<H2>Summary</H2>
  +
  +<P>This module implements the Internet Server extension API. It allows 
  +   Internet Server extensions (<EM>e.g.</EM> ISAPI .dll modules) to be
  +   served by Apache for Windows, subject to the noted restrictions.</P>
  +
  +<P>ISAPI extension modules (.dll files) are written by third parties.  The 
  +   Apache Group does not author these modules, so we provide no support for 
  +   them.  Please contact the ISAPI's author directly if you are experiencing 
  +   problems running their ISAPI extention.  <STRONG>Please <EM>do not</EM>

  +   post such problems to Apache's lists or bug reporting pages.</STRONG></P>
  +
   <H2>Usage</H2>
  +
  +<P>In the server configuration file, use the AddHandler directive to
  +   associate ISAPI files with the <CODE>isapi-isa</CODE> handler, and map 
  +   it to the with their file extensions.  To enable any .dll file to be 
  +   processed as an ISAPI extention, edit the httpd.conf file and add the 
  +   following line:</P>
   
  -<P>In the server configuration file, add a handler called
  -   <CODE>isapi-isa</CODE>, and map it to files with a <CODE>.DLL</CODE>
  -   extension. In other words:</P>
   <PRE>
       AddHandler isapi-isa dll
   </PRE>
  -<P>Now simply place the ISA DLLs into your document root, and they will
  -   be loaded when their URLs are accessed.</P>
   
  -<P>ISAPI Extensions are governed by the same restrictions as CGI
  -   scripts. That is, <CODE>Options ExecCGI</CODE> must be active in the
  -   directory that contains the ISA.</P>
  +<P>ISAPI Extensions are governed by the same permissions and restrictions 
  +   as CGI scripts. That is, <CODE>Options ExecCGI</CODE> must be set for
  +   the directory that contains the ISAPI .dll file.</P>
  +
  +<P>Now place an ISAPI .dll file into this web directory, with the 
  +   <CODE>Options ExecCGI</CODE> set properly, and it will be loaded and
  +   executed when requested by its URL.</P>
  +
  +   Review the <A HREF="#notes">Additional Notes</A> and the
  +   <A HREF="#journal">Programmer's Journal</A> for additional details and
  +   clarification of the specific ISAPI support offered by mod_isapi.</P>
  +
  +<H2>Directives</H2>
  +<UL>
  +<LI><A HREF="#ISAPIReadAheadBuffer">ISAPIReadAheadBuffer</A>
  +<LI><A HREF="#ISAPILogNotSupported">ISAPILogNotSupported</A>
  +<LI><A HREF="#ISAPIAppendLogToErrors">ISAPIAppendLogToErrors</A>
  +<LI><A HREF="#ISAPIAppendLogToQuery">ISAPIAppendLogToQuery</A>
  +</UL>
  +<HR>
  +
  +<H2><A NAME="ISAPIReadAheadBuffer">ISAPIReadAheadBuffer directive</A></H2>
  +<!--%plaintext &lt;?INDEX {\tt ISAPIReadAheadBuffer} directive&gt; -->
  +<A
  + HREF="directive-dict.html#Syntax"
  + REL="Help"
  +><STRONG>Syntax:</STRONG></A> ISAPIReadAheadBuffer <EM>size</EM><BR>
  +<A
  + HREF="directive-dict.html#Default"
  + REL="Help"
  +><STRONG>Default:</STRONG></A> 49152<BR>
  +<A
  + HREF="directive-dict.html#Context"
  + REL="Help"
  +><STRONG>Context:</STRONG></A> server config<BR>
  +<A
  + HREF="directive-dict.html#Override"
  + REL="Help"
  +><STRONG>Override:</STRONG></A> None<BR>
  +<A
  + HREF="directive-dict.html#Status"
  + REL="Help"
  +><STRONG>Status:</STRONG></A> Base<BR>
  +<A
  + HREF="directive-dict.html#Module"
  + REL="Help"
  +><STRONG>Module:</STRONG></A> mod_isapi<BR>
  +<A
  +HREF="module-dict.html#Compatibility"
  +REL="Help"
  +><STRONG>Compatibility:</STRONG></A> Apache 1.3.13 and later, Win32
only<P>
  +
  +
  +        Defines the maximum size of the Read Ahead Buffer sent to 
  +        ISAPI extentions when they are initally invoked.  All 
  +        remaining data must be retrieved using the ReadClient 
  +        callback; some ISAPI extensions may not support the
  +        ReadClient function.  Refer questions to the ISAPI extention's 
  +        author.
  +        <P>
  +<HR>
  +
  +<H2><A NAME="ISAPILogNotSupported">ISAPILogNotSupported directive</A></H2>
  +<!--%plaintext &lt;?INDEX {\tt ISAPILogNotSupported} directive&gt; -->
  +<A
  + HREF="directive-dict.html#Syntax"
  + REL="Help"
  +><STRONG>Syntax:</STRONG></A> ISAPILogNotSupported <EM>on|off</EM><BR>
  +<A
  + HREF="directive-dict.html#Default"
  + REL="Help"
  +><STRONG>Default:</STRONG></A> on<BR>
  +<A
  + HREF="directive-dict.html#Context"
  + REL="Help"
  +><STRONG>Context:</STRONG></A> server config<BR>
  +<A
  + HREF="directive-dict.html#Override"
  + REL="Help"
  +><STRONG>Override:</STRONG></A> None<BR>
  +<A
  + HREF="directive-dict.html#Status"
  + REL="Help"
  +><STRONG>Status:</STRONG></A> Base<BR>
  +<A
  + HREF="directive-dict.html#Module"
  + REL="Help"
  +><STRONG>Module:</STRONG></A> mod_isapi<BR>
  +<A
  +HREF="module-dict.html#Compatibility"
  +REL="Help"
  +><STRONG>Compatibility:</STRONG></A> Apache 1.3.13 and later, Win32
only<P>
  +
  +        Logs all requests for unsupported features from ISAPI extentions
  +        in the server error log.  While this should be turned off once
  +        all desired ISAPI modules are functioning, it defaults to on
  +        to help administrators track down problems.
  +        <P>
  +<HR>
  +
  +<H2><A NAME="ISAPIAppendLogToErrors">ISAPIAppendLogToErrors directive</A></H2>
  +<!--%plaintext &lt;?INDEX {\tt ISAPIAppendLogToErrors} directive&gt; -->
  +<A
  + HREF="directive-dict.html#Syntax"
  + REL="Help"
  +><STRONG>Syntax:</STRONG></A> ISAPIAppendLogToErrors <EM>on|off</EM><BR>
  +<A
  + HREF="directive-dict.html#Default"
  + REL="Help"
  +><STRONG>Default:</STRONG></A> off<BR>
  +<A
  + HREF="directive-dict.html#Context"
  + REL="Help"
  +><STRONG>Context:</STRONG></A> server config<BR>
  +<A
  + HREF="directive-dict.html#Override"
  + REL="Help"
  +><STRONG>Override:</STRONG></A> None<BR>
  +<A
  + HREF="directive-dict.html#Status"
  + REL="Help"
  +><STRONG>Status:</STRONG></A> Base<BR>
  +<A
  + HREF="directive-dict.html#Module"
  + REL="Help"
  +><STRONG>Module:</STRONG></A> mod_isapi<BR>
  +<A
  +HREF="module-dict.html#Compatibility"
  +REL="Help"
  +><STRONG>Compatibility:</STRONG></A> Apache 1.3.13 and later, Win32
only<P>
  +
  +        Record HSE_APPEND_LOG_PARAMETER requests from ISAPI extentions
  +        to the server error log.
  +        <P>
  +<HR>
  +
  +<H2><A NAME="ISAPIAppendLogToQuery">ISAPIAppendLogToQuery directive</A></H2>
  +<!--%plaintext &lt;?INDEX {\tt ISAPIAppendLogToQuery} directive&gt; -->
  +<A
  + HREF="directive-dict.html#Syntax"
  + REL="Help"
  +><STRONG>Syntax:</STRONG></A> ISAPIAppendLogToQuery <EM>on|off</EM><BR>
  +<A
  + HREF="directive-dict.html#Default"
  + REL="Help"
  +><STRONG>Default:</STRONG></A> off<BR>
  +<A
  + HREF="directive-dict.html#Context"
  + REL="Help"
  +><STRONG>Context:</STRONG></A> server config<BR>
  +<A
  + HREF="directive-dict.html#Override"
  + REL="Help"
  +><STRONG>Override:</STRONG></A> None<BR>
  +<A
  + HREF="directive-dict.html#Status"
  + REL="Help"
  +><STRONG>Status:</STRONG></A> Base<BR>
  +<A
  + HREF="directive-dict.html#Module"
  + REL="Help"
  +><STRONG>Module:</STRONG></A> mod_isapi<BR>
  +<A
  +HREF="module-dict.html#Compatibility"
  +REL="Help"
  +><STRONG>Compatibility:</STRONG></A> Apache 1.3.13 and later, Win32
only<P>
  +
  +        Record HSE_APPEND_LOG_PARAMETER requests from ISAPI extentions
  +        to the query field (appended to the CustomLog %q component).
  +        <P>
  +<HR>
   
  -<H2>Notes</H2>
  +<H2><A NAME="notes">Additional Notes</A></H2>
   
   <P>Apache's ISAPI implementation conforms to all of the ISAPI 2.0
      specification, except for the "Microsoft-specific" extensions dealing
      with asynchronous I/O. Apache's I/O model does not allow asynchronous
      reading and writing in a manner that the ISAPI could access. If an ISA
  -   tries to access async I/O, a message will be place in the error log,
  -   to help with debugging.
  +   tries to access unsupported features, including async I/O, a message is
  +   placed in the error log to help with debugging. Since these messages
  +   can become a flood, a new directive; 
  +   <CODE>ISAPILogNotSupported Off</CODE>, is introduced in Apache 1.3.13.</P>
   
   <P>Some servers, like Microsoft IIS, load the ISA into the server, and
  -   keep it loaded until memory usage is too high, and it is
  -   unloaded. Apache currently loads and unloads the ISA for each
  -   request. This is inefficient, but Apache's request model makes this
  -   method the only method that currently works. A future release may use
  -   a more effective loading method.
  -
  -<P>Apache 1.3a1 currently limits POST and PUT input to 48k per
  -   request. This is to work around a problem with the ISAPI implementation
  -   that could result in a denial of service attack. It is expected that
  -   support for larger uploads will be added soon.
  -
  -<P>Also, remember that while Apache supports ISAPI Extensions, it does
  -   not support ISAPI Filters. Support for filters may be added at a later
  -   date, but no support is planned at this time.</P>
  +   keep it loaded until memory usage is too high, or specific configuration
  +   options are used.  Apache currently loads and unloads the ISA for each
  +   request.  This is inefficient, but Apache's request model makes this
  +   method the only method that currently works.  Apache 2.0 is expected to
  +   support more effective loading and caching methods, with more precise
  +   control over individual ISAPI modules and directories.</P>
  +
  +<P>Also, remember that while Apache supports ISAPI Extensions, it 
  +   <STRONG>does not support ISAPI Filters.</STRONG>  Support for filters may

  +   be added at a later date, but no support is planned at this time.</P>
   
  -<H2>Programmer's Journal</H2>
  +<H2><A NAME="journal">Programmer's Journal</A></H2>
   
   <P>If you are programming Apache 1.3 mod_isapi modules, you must limit your
      calls to ServerSupportFunction to the following directives:</P>
  @@ -90,35 +281,51 @@
           the blank line (two consecutive newlines) in the headers string 
           argument.  This body cannot contain NULLs, since the headers
           argument is NULL terminated.
  -  <DT>HSE_REQ_SEND_URL
  -    <DD>Redirect the user to another location.<BR>
  -        This cannot be a fully qualified URL, you are not allowed
  -        to pass the protocol or a server name (e.g. simply /location)
  -  <DT>HSE_REQ_MAP_URL_TO_PATH
  -    <DD>Apache will translate a virtual name to a physical name.
     <DT>HSE_REQ_DONE_WITH_SESSION
       <DD>Apache considers this a no-op, since the session will be finished
           when the ISAPI returns from processing.
  +  <DT>HSE_REQ_MAP_URL_TO_PATH
  +    <DD>Apache will translate a virtual name to a physical name.
  +  <DT>HSE_APPEND_LOG_PARAMETER <EM>Apache 1.3.13 and later</EM>
  +    <DD>This logged message may be captured in any of the following logs:
  +      <UL>
  +        <LI>in the \"%{isapi-parameter}n\" component in a CustomLog directive
  +        <LI>in the %q log component with the ISAPIAppendLogToQuery On directive
  +        <LI>in the error log with the ISAPIAppendLogToErrors On directive
  +      </UL>
  +        The first option, the %{isapi-parameter}n component, is always available
  +        and prefered.
  +  <DT>HSE_REQ_IS_KEEP_CONN <EM>Apache 1.3.13 and later</EM>
  +    <DD>Will return the negotiated Keep-Alive status.
  +  <DT>HSE_REQ_SEND_RESPONSE_HEADER_EX <EM>Apache 1.3.13 and later</EM>
  +    <DD>Will behave as documented, although the fKeepConn flag is ignored.
  +  <DT>HSE_REQ_IS_CONNECTED <EM>Apache 1.3.13 and later</EM>
  +    <DD>Will report false if the request has been aborted.
   </DL>
   
  -<P>Apache returns FALSE to any other call to ServerSupportFunction, and
  +<P>Apache returns FALSE to any unsupported call to ServerSupportFunction, and
      sets the GetLastError value to ERROR_INVALID_PARAMETER.</P>
   
  -<P>ReadClient is not truly supported.  The entire body of the message, 
  -   up to 49152 bytes, is sent to the client in the initial request.
  -   If the request is longer, the ISAPI extension is never called.  
  -   Calling ReadClient, however, does no harm.</P>
  +<P>Prior to Apache 1.3.13, ReadClient was a noop, and any request with a request
  +   body greater than 48kb was rejected by mod_isapi.  As of Apache 1.3.13,
  +   ReadClient now retrieves the request body exceeding the initial buffer 
  +   (defined by ISAPIReadAheadBuffer).  Based on the ISAPIReadAheadBuffer 
  +   setting (number of bytes to buffer prior to calling the ISAPI handler) 
  +   shorter requests are sent complete to the extension when it is invoked.
  +   If the request is longer, the ISAPI extension must use ReadClient to
  +   retrieve the remaining request body.</P>
   
   <P>WriteClient is supported, but only with the HSE_IO_SYNC flag or
      no option flag (value of 0).  Any other WriteClient request will
      be rejected with a return value of FALSE, and a GetLastError
      value of ERROR_INVALID_PARAMETER.</P>
   
  -<P>GetServerVariable is supported, although extended server variables 
  -   do not exist (as defined by other servers.)  In general, all CGI 
  -   environment variables are available through GetServerVariable.</P>
  +<P>GetServerVariable is supported, although extended server variables do not
  +   exist (as defined by other servers.)  All the usual Apache CGI environment 
  +   variables are available from GetServerVariable.  As of Apache 1.3.13,
  +   the ALL_HTTP and ALL_RAW and variables are now available.</P>
   
  -<P>Apache 2.0 mod_isapi will support additional features introduced in later
  +<P>Apache 2.0 mod_isapi may support additional features introduced in later
      versions of the ISAPI specification, as well as limited emulation of
      async I/O and the TransmitFile semantics.  Apache 2.0 may also support
      caching of ISAPI .dlls for performance.  No further enhancements to the
  
  
  

Mime
View raw message