mod_filter.html.en

Apache官方在今天放出产品系列2.2的最新版本2.2.11的源码包 最流行的HTTP服务器软件之一

    modules.  For httpd 2.1 and later, the
    <code>ap_register_output_filter_protocol</code> and
    <code>ap_filter_protocol</code> API enables filter modules to
    declare their own behaviour.</p>

    <p>At the same time, <code class="module"><a href="../mod/mod_filter.html">mod_filter</a></code> should not interfere
    with a filter that wants to handle all aspects of the protocol.  By
    default (i.e. in the absence of any <code class="directive"><a href="#filterprotocol">FilterProtocol</a></code> directives), <code class="module"><a href="../mod/mod_filter.html">mod_filter</a></code>
    will leave the headers untouched.</p>

    <p>At the time of writing, this feature is largely untested,
    as modules in common use are designed to work with 2.0.
    Modules using it should test it carefully.</p>
</div>
<div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
<div class="directive-section"><h2><a name="FilterChain" id="FilterChain">FilterChain</a> <a name="filterchain" id="filterchain">Directive</a></h2>
<table class="directive">
<tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Configure the filter chain</td></tr>
<tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>FilterChain [+=-@!]<var>filter-name</var> <var>...</var></code></td></tr>
<tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config, virtual host, directory, .htaccess</td></tr>
<tr><th><a href="directive-dict.html#Override">Override:</a></th><td>Options</td></tr>
<tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Base</td></tr>
<tr><th><a href="directive-dict.html#Module">Module:</a></th><td>mod_filter</td></tr>
</table>
    <p>This configures an actual filter chain, from declared filters.
    <code class="directive">FilterChain</code> takes any number of arguments,
    each optionally preceded with a single-character control that
    determines what to do:</p>

    <dl>
    <dt><code>+<var>filter-name</var></code></dt>
    <dd>Add <var>filter-name</var> to the end of the filter chain</dd>

    <dt><code>@<var>filter-name</var></code></dt>
    <dd>Insert <var>filter-name</var> at the start of the filter chain</dd>

    <dt><code>-<var>filter-name</var></code></dt>
    <dd>Remove <var>filter-name</var> from the filter chain</dd>

    <dt><code>=<var>filter-name</var></code></dt>
    <dd>Empty the filter chain and insert <var>filter-name</var></dd>

    <dt><code>!</code></dt>
    <dd>Empty the filter chain</dd>

    <dt><code><var>filter-name</var></code></dt>
    <dd>Equivalent to <code>+<var>filter-name</var></code></dd>
    </dl>

</div>
<div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
<div class="directive-section"><h2><a name="FilterDeclare" id="FilterDeclare">FilterDeclare</a> <a name="filterdeclare" id="filterdeclare">Directive</a></h2>
<table class="directive">
<tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Declare a smart filter</td></tr>
<tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>FilterDeclare <var>filter-name</var> <var>[type]</var></code></td></tr>
<tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config, virtual host, directory, .htaccess</td></tr>
<tr><th><a href="directive-dict.html#Override">Override:</a></th><td>Options</td></tr>
<tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Base</td></tr>
<tr><th><a href="directive-dict.html#Module">Module:</a></th><td>mod_filter</td></tr>
</table>
    <p>This directive declares an output filter together with a
    header or environment variable that will determine runtime
    configuration.  The first argument is a <var>filter-name</var>
    for use in <code class="directive"><a href="#filterprovider">FilterProvider</a></code>,
    <code class="directive"><a href="#filterchain">FilterChain</a></code> and
    <code class="directive"><a href="#filterprotocol">FilterProtocol</a></code> directives.</p>

    <p>The final (optional) argument
    is the type of filter, and takes values of <code>ap_filter_type</code>
    - namely <code>RESOURCE</code> (the default), <code>CONTENT_SET</code>,
    <code>PROTOCOL</code>, <code>TRANSCODE</code>, <code>CONNECTION</code>
    or <code>NETWORK</code>.</p>

</div>
<div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
<div class="directive-section"><h2><a name="FilterProtocol" id="FilterProtocol">FilterProtocol</a> <a name="filterprotocol" id="filterprotocol">Directive</a></h2>
<table class="directive">
<tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Deal with correct HTTP protocol handling</td></tr>
<tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>FilterProtocol <var>filter-name</var> [<var>provider-name</var>]
    <var>proto-flags</var></code></td></tr>
<tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config, virtual host, directory, .htaccess</td></tr>
<tr><th><a href="directive-dict.html#Override">Override:</a></th><td>Options</td></tr>
<tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Base</td></tr>
<tr><th><a href="directive-dict.html#Module">Module:</a></th><td>mod_filter</td></tr>
</table>
    <p>This directs <code class="module"><a href="../mod/mod_filter.html">mod_filter</a></code> to deal with ensuring the
    filter doesn't run when it shouldn't, and that the HTTP response
    headers are correctly set taking into account the effects of the
    filter.</p>

    <p>There are two forms of this directive.  With three arguments, it
    applies specifically to a <var>filter-name</var> and a
    <var>provider-name</var> for that filter.
    With two arguments it applies to a <var>filter-name</var> whenever the
    filter runs <em>any</em> provider.</p>

    <p><var>proto-flags</var> is one or more of</p>

    <dl>
    <dt><code>change=yes</code></dt>
    <dd>The filter changes the content, including possibly the content
    length</dd>

    <dt><code>change=1:1</code></dt>
    <dd>The filter changes the content, but will not change the content
    length</dd>

    <dt><code>byteranges=no</code></dt>
    <dd>The filter cannot work on byteranges and requires complete input</dd>

    <dt><code>proxy=no</code></dt>
    <dd>The filter should not run in a proxy context</dd>

    <dt><code>proxy=transform</code></dt>
    <dd>The filter transforms the response in a manner incompatible with
    the HTTP <code>Cache-Control: no-transform</code> header.</dd>

    <dt><code>cache=no</code></dt>
    <dd>The filter renders the output uncacheable (eg by introducing randomised
    content changes)</dd>
    </dl>

</div>
<div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
<div class="directive-section"><h2><a name="FilterProvider" id="FilterProvider">FilterProvider</a> <a name="filterprovider" id="filterprovider">Directive</a></h2>
<table class="directive">
<tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Register a content filter</td></tr>
<tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>FilterProvider <var>filter-name</var> <var>provider-name</var>
 [req|resp|env]=<var>dispatch</var> <var>match</var></code></td></tr>
<tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config, virtual host, directory, .htaccess</td></tr>
<tr><th><a href="directive-dict.html#Override">Override:</a></th><td>Options</td></tr>
<tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Base</td></tr>
<tr><th><a href="directive-dict.html#Module">Module:</a></th><td>mod_filter</td></tr>
</table>
    <p>This directive registers a <em>provider</em> for the smart filter.
    The provider will be called if and only if the <var>match</var> declared
    here matches the value of the header or environment variable declared
    as <var>dispatch</var>.</p>

    <p>
    <var>provider-name</var> must have been registered by loading
    a module that registers the name with
    <code>ap_register_output_filter</code>.

    </p>

    <p>The <var>dispatch</var> argument is a string with optional
    <code>req=</code>, <code>resp=</code> or <code>env=</code> prefix
    causing it to dispatch on (respectively) the request header, response
    header, or environment variable named.  In the absence of a
    prefix, it defaults to a response header.  A special case is the
    word <code>handler</code>, which causes <code class="module"><a href="../mod/mod_filter.html">mod_filter</a></code>
    to dispatch on the content handler.</p>

    <p>The <var>match</var> argument specifies a match that will be applied to
    the filter's <var>dispatch</var> criterion.  The <var>match</var> may be
    a string match (exact match or substring), a <a class="glossarylink" href="../glossary.html#regex" title="see glossary">regex</a>, an integer (greater, lessthan or equals), or
    unconditional.  The first characters of the <var>match</var> argument
    determines this:</p>

    <p><strong>First</strong>, if the first character is an exclamation mark
    (<code>!</code>), this reverses the rule, so the provider will be used
    if and only if the match <em>fails</em>.</p>

    <p><strong>Second</strong>, it interprets the first character excluding
    any leading <code>!</code> as follows:</p>

    <table class="bordered"><tr class="header"><th>Character</th><th>Description</th></tr>
<tr><td><em>(none)</em></td><td>exact match</td></tr>
<tr class="odd"><td><code>$</code></td><td>substring match</td></tr>
<tr><td><code>/</code></td><td>regex match (delimited by a second <code>/</code>)</td></tr>
<tr class="odd"><td><code>=</code></td><td>integer equality</td></tr>
<tr><td><code>&lt;</code></td><td>integer less-than</td></tr>
<tr class="odd"><td><code>&lt;=</code></td><td>integer less-than or equal</td></tr>
<tr><td><code>&gt;</code></td><td>integer greater-than</td></tr>
<tr class="odd"><td><code>&gt;=</code></td><td>integer greater-than or equal</td></tr>
<tr><td><code>*</code></td><td>Unconditional match</td></tr>
</table>

</div>
<div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
<div class="directive-section"><h2><a name="FilterTrace" id="FilterTrace">FilterTrace</a> <a name="filtertrace" id="filtertrace">Directive</a></h2>
<table class="directive">
<tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Get debug/diagnostic information from
    <code class="module"><a href="../mod/mod_filter.html">mod_filter</a></code></td></tr>
<tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>FilterTrace <var>filter-name</var> <var>level</var></code></td></tr>
<tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config, virtual host, directory</td></tr>
<tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Base</td></tr>
<tr><th><a href="directive-dict.html#Module">Module:</a></th><td>mod_filter</td></tr>
</table>
    <p>This directive generates debug information from
    <code class="module"><a href="../mod/mod_filter.html">mod_filter</a></code>.
    It is designed to help test and debug providers (filter modules), although
    it may also help with <code class="module"><a href="../mod/mod_filter.html">mod_filter</a></code> itself.</p>

    <p>The debug output depends on the <var>level</var> set:</p>
    <dl>
    <dt><code>0</code> (default)</dt>
    <dd>No debug information is generated.</dd>

    <dt><code>1</code></dt>
    <dd><code class="module"><a href="../mod/mod_filter.html">mod_filter</a></code> will record buckets and brigades
    passing through the filter to the error log, before the provider has
    processed them. This is similar to the information generated by
    <a href="http://apache.webthing.com/mod_diagnostics/">mod_diagnostics</a>.
    </dd>

    <dt><code>2</code> (not yet implemented)</dt>
    <dd>Will dump the full data passing through to a tempfile before the
    provider. <strong>For single-user debug only</strong>; this will not
    support concurrent hits.</dd>
    </dl>

</div>
</div>
<div class="bottomlang">
<p><span>Available Languages: </span><a href="../en/mod/mod_filter.html" title="English">&nbsp;en&nbsp;</a></p>
</div><div id="footer">
<p class="apache">Copyright 2008 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>
<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>
</body></html>