New xml versions.

git-svn-id: https://svn.apache.org/repos/asf/httpd/httpd/trunk@93814 13f79535-47bb-0310-9956-ffa450edef68

1 files changed, 271 insertions, 0 deletions

diff --git a/docs/manual/mod/mod_isapi.xml b/docs/manual/mod/mod_isapi.xml
new file mode 100644
index 0000000000..c64cbd0b18
--- /dev/null
+++ b/docs/manual/mod/mod_isapi.xml
@@ -0,0 +1,271 @@
+<?xml version="1.0"?>
+<!DOCTYPE modulesynopsis SYSTEM "../style/modulesynopsis.dtd">
+<?xml-stylesheet type="text/xsl" href="../style/manual.xsl"?>
+<modulesynopsis>
+
+<name>mod_isapi</name>
+<description>ISAPI Extensions within Apache for Windows</description>
+<status>Base</status>
+<sourcefile>mod_isapi.c</sourcefile>
+<identifier>isapi_module</identifier>
+<compatibility>Win32 only</compatibility>
+
+<summary>
+    <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>
+</summary>
+
+<section><title>Usage</title> <p>In the server configuration file, use
+the <directive module="mod_mime">AddHandler</directive> 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>
+<example>
+    AddHandler isapi-isa .dll
+</example>
+
+    <p>There is no capability within the Apache server to leave a
+    requested module loaded. However, you may preload and keep a
+    specific module loaded by using the following syntax in your
+    httpd.conf:</p>
+<example>
+    ISAPICacheFile c:/WebWork/Scripts/ISAPI/mytest.dll
+</example>
+
+    <p>Whether or not you have preloaded an ISAPI extension, all
+    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>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>
+</section>
+
+<section id="notes"><title>Additional Notes</title>
+
+    <p>Apache's ISAPI implementation conforms to all of the ISAPI
+    2.0 specification, except for some "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
+    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, the directive <code>ISAPILogNotSupported
+    Off</code> exists to quiet this noise.</p>
+
+    <p>Some servers, like Microsoft IIS, load the ISAPI extension
+    into the server and keep it loaded until memory usage is too
+    high, or unless configuration options are specified. Apache
+    currently loads and unloads the ISAPI extension each time it is
+    requested, unless the ISAPICacheFile directive is specified.
+    This is inefficient, but Apache's memory model makes this the
+    most effective method. Many ISAPI modules are subtly
+    incompatible with the Apache server, and unloading these
+    modules helps to ensure the stability of the server.</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>
+</section>
+
+<section id="journal"><title>Programmer's Journal</title>
+
+    <p>If you are programming Apache 2.0 <module>mod_isapi</module>
+    modules, you must limit your calls to ServerSupportFunction to the
+    following directives:</p>
+
+    <dl>
+      <dt>HSE_REQ_SEND_URL_REDIRECT_RESP</dt>
+
+      <dd>Redirect the user to another location.<br />
+       This must be a fully qualified URL (e.g.
+      http://server/location).</dd>
+
+      <dt>HSE_REQ_SEND_URL</dt>
+
+      <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).<br />
+       This redirection is handled by the server, not the
+      browser.<br />
+       <strong>Warning:</strong> in their recent documentation,
+      Microsoft appears to have abandoned the distinction between
+      the two HSE_REQ_SEND_URL functions. Apache continues to treat
+      them as two distinct functions with different requirements
+      and behaviors.</dd>
+
+      <dt>HSE_REQ_SEND_RESPONSE_HEADER</dt>
+
+      <dd>Apache accepts a response body following the header if it
+      follows the blank line (two consecutive newlines) in the
+      headers string argument. This body cannot contain NULLs,
+      since the headers argument is NULL terminated.</dd>
+
+      <dt>HSE_REQ_DONE_WITH_SESSION</dt>
+
+      <dd>Apache considers this a no-op, since the session will be
+      finished when the ISAPI returns from processing.</dd>
+
+      <dt>HSE_REQ_MAP_URL_TO_PATH</dt>
+
+      <dd>Apache will translate a virtual name to a physical
+      name.</dd>
+
+      <dt>HSE_APPEND_LOG_PARAMETER</dt>
+
+      <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>
+
+          <li>in the %q log component with the
+          ISAPIAppendLogToQuery On directive</li>
+
+          <li>in the error log with the ISAPIAppendLogToErrors On
+          directive</li>
+        </ul>
+        The first option, the %{isapi-parameter}n component, is
+        always available and prefered.
+      </dd>
+
+      <dt>HSE_REQ_IS_KEEP_CONN</dt>
+
+      <dd>Will return the negotiated Keep-Alive status.</dd>
+
+      <dt>HSE_REQ_SEND_RESPONSE_HEADER_EX</dt>
+
+      <dd>Will behave as documented, although the fKeepConn flag is
+      ignored.</dd>
+
+      <dt>HSE_REQ_IS_CONNECTED</dt>
+
+      <dd>Will report false if the request has been aborted.</dd>
+    </dl>
+
+    <p>Apache returns FALSE to any unsupported call to
+    ServerSupportFunction, and sets the GetLastError value to
+    ERROR_INVALID_PARAMETER.</p>
+
+    <p>ReadClient 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.) All the
+    usual Apache CGI environment variables are available from
+    GetServerVariable, as well as the ALL_HTTP and ALL_RAW
+    values.</p>
+
+    <p>Apache 2.0 <module>mod_isapi</module> supports additional
+    features introduced in later versions of the ISAPI specification,
+    as well as limited emulation of async I/O and the TransmitFile
+    semantics.  Apache also supports preloading ISAPI .dlls for
+    performance, neither of which were not available under Apache 1.3
+    mod_isapi.</p>
+</section>
+
+<directivesynopsis>
+<name>ISAPIFileChache</name>
+<description>ISAPI .dll files to be loaded at startup</description>
+<syntax>ISAPIFileCache <em>file-path</em> [<em>file-path</em>] ...</syntax>
+<contextlist><context>server config</context></contextlist>
+
+<usage>
+    <p>Specifies a space-separated list of file names to be loaded
+    when the Apache server is launched, and remain loaded until the
+    server is shut down. This directive may be repeated for every
+    ISAPI .dll file desired. The full path name of each file should
+    be specified.</p>
+</usage>
+</directivesynopsis>
+
+<directivesynopsis>
+<name>ISAPIReadAheadBuffer</name>
+<description>Size of the Read Ahead Buffer sent to ISAPI 
+extensions</description>
+<syntax>ISAPIReadAheadBuffer <em>size</em></syntax>
+<default>ISAPIReadAheadBuffer 49152</default>
+<contextlist><context>server config</context></contextlist>
+
+<usage>
+    <p>Defines the maximum size of the Read Ahead Buffer sent to
+    ISAPI extensions when they are initially 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 extension's author.</p>
+</usage>
+</directivesynopsis>
+
+<directivesynopsis>
+<name>ISAPILogNotSupported</name>
+<description>Log unsupported feature requests from ISAPI
+extensions</description>
+<syntax>ISAPILogNotSupported on|off</syntax>
+<default>ISAPILogNotSupported on</default>
+<contextlist><context>server config</context></contextlist>
+
+<usage>
+    <p>Logs all requests for unsupported features from ISAPI
+    extensions 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>
+</usage>
+</directivesynopsis>
+
+<directivesynopsis>
+<name>ISAPIAppendLogToErrors</name>
+<description>Record HSE_APPEND_LOG_PARAMETER requests from ISAPI
+extensions to the error log</description>
+<syntax>ISAPIAppendLogToErrors on|off</syntax>
+<default>ISAPIAppendLogToErrors off</default>
+<contextlist><context>server config</context></contextlist>
+
+<usage>
+    <p>Record HSE_APPEND_LOG_PARAMETER requests from ISAPI
+    extensions to the server error log.</p>
+</usage>
+</directivesynopsis>
+
+<directivesynopsis>
+<name>ISAPIAppendLogToQuery</name>
+<description>Record HSE_APPEND_LOG_PARAMETER requests from ISAPI
+extensions to the query field</description>
+<syntax>ISAPIAppendLogToQuery on|off</syntax>
+<default>ISAPIAppendLogToQuery off</default>
+<contextlist><context>server config</context></contextlist>
+
+<usage>
+    <p>Record HSE_APPEND_LOG_PARAMETER requests from ISAPI
+    extensions to the query field (appended to the CustomLog %q
+    component).</p>
+</usage>
+</directivesynopsis>
+
+</modulesynopsis>
\ No newline at end of file