I posted my proposed smart filter module a few days ago, in response a post here identifying a situation where it is relevant.
I have now completed a first version of the accompanying manual page.
I attach:
mod_filter.xml
mod_filter.xml.meta
mod_filter.html
Two images used to illustrate the module
I've also uploaded the HTML to http://www.apache.org/~niq/ .
I believe I have addressed the concerns raised when I mooted the idea
of this some weeks ago:
* Existing filters are binary-compatible with the new module
* I've restored the filter_init handlers to the architecture
* I've retained my proposal to enable dealing with aspects of
the HTTP protocol on behalf of filter. However, the default
is always for the filter harness to do nothing, and leave the
filter provider (a content filter module) to deal with that
as before.
Working code and documentation (modulo bugs and TODOs) should help
demonstrate the purpose and utility of the proposal, and move the
discussion forward. I'd like to offer this as a contribution to the
core httpd distribution, to be included as standard in 2.2.
What is currently implemented is the basic architecture as described
before. Configuration is fully dynamic, with my proposed set of
configuration directives now implemented.
Note that the module only applies to output filters and will only
work with AP_FTYPE_RESOURCE or CONTENT_SET filters. I don't see a
need for this functionality elsewhere (but I'm open to persuasion:-)
The main TBD is an ap_filter... API interface for other modules to
work actively with it. To implement that, I will need to merge the
ap_filter_rec_t structure into the mod_filter_rec. This will be
binary back-compatible (the new fields go on to the end of the
ap_filter_rec_t), but will of course require commits to code outside
the module, specifically util_filter.
A second TODO is to enable mod_filter to run as a provider for itself.
The purpose of this is to enable chaining of configuration rules beyond
what we can already do by setting an environment variable with
mod_rewrite and dispatching on an "env=" variable (example: insert
DEFLATE depending on both Accept-Encoding request header and
Content-Type response header. mod_rewrite can't do that because
it runs too early to be sure to have the response headers).
--
Nick Kew<?xml version="1.0"?>
<!DOCTYPE modulesynopsis SYSTEM "../style/modulesynopsis.dtd">
<?xml-stylesheet type="text/xsl" href="../style/manual.en.xsl"?>
<!-- $Revision: 1.18 $ -->
<!--
Copyright 2004 The Apache Software Foundation
Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
You may obtain a copy of the License at
http://www.apache.org/licenses/LICENSE-2.0
Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.
-->
<modulesynopsis metafile="mod_filter.xml.meta">
<name>mod_filter</name>
<description>Context-sensitive smart filter configuration module</description>
<status>Extension</status>
<sourcefile>mod_filter.c</sourcefile>
<identifier>filter_module</identifier>
<compatibility>Apache 2.0 and higher</compatibility>
<summary>
<p>This module enables smart, context-sensitive configuration of
output content filters. For example, apache can be configured to
process different content-types through different filters, even
when the content-type is not known in advance (e.g. in a proxy).
</p>
</summary>
<section id="smart"><title>Smart Filtering</title>
<p>In the traditional filtering model, filters are inserted unconditionally
using <directive module="core">AddOutputFilter</directive> and family.
Each filter then needs to determine whether to run, and there is little
flexibility available for server admins to allow the chain to be
configured dynamically.</p>
<p>mod_filter by contrast gives server administrators a great deal of
flexibility in configuring the filter chain. In fact, filters can be
inserted based on any Request Header, Response Header or Environment
Variable. This generalises the limited flexibility offered by
<directive module="core">AddOutputFilterByType</directive>, and fixes
it to work correctly with dynamic content, regardless of the
content generator. The ability to dispatch based on Environment
Variables offers the full flexibility of configuration with
<module>mod_rewrite</module> to anyone who needs it.</p>
</section>
<section id="terms"><title>Filter Declarations, Providers and Chains</title>
<img src="oldfilter.gif" alt=""/>
<p>In the traditional model, output filters are a simple chain
from the content generator (handler) to the client. This works well
provided the filter chain can be correctly configured, but presents
problems when the filters need to be configured dynamically based on
the outcome of the handler.</p>
<img src="newfilter.gif" alt=""/>
<p>mod_filter works by introducing indirection into the filter
chain. Instead of introducing filters in the chain, we introduce
a filter harness which in turn dispatches conditionally
to a filter provider. Any content filter may be used as a provider
to mod_filter; no change to existing filter modules is required
(although it may be possible to simplify them). There can be
multiple providers for one filter, but no more than one provider will
run for any single request.
</p>
<p>A filter chain comprises any number of instances of the filter
harness, each of which may have any number of providers. A special
case is that of a single provider with unconditional dispatch: this
is equivalent to inserting the provider filter directly into the chain.
</p>
</section>
<section id="config"><title>Configuring the Chain</title>
<p>There are three stages to configuring a filter chain with mod_filter.
For details of the directives, see below.</p>
<dl>
<dt>Declare Filters</dt>
<dd>The <directive>FilterDeclare</directive> directive declares a filter,
assigning it a name and a dispatch criterion.</dd>
<dt>Register Providers</dt>
<dd>The <directive>FilterProvider</directive> directive registers a provider with a
filter.
The filter must have been registered with <directive>FilterDeclare</directive>.
The provider must have been registered with
<code>ap_register_output_filter</code> by some module. The final argument
to <directive>FilterProvider</directive> is a match string, that will be checked
against
the filter's dispatch criterion to determine whether to run this provider.</dd>
<dt>Configure the Chain</dt>
<dd>The above directives build components of a smart filter chain,
but do not configure it to run. The <directive>FilterChain</directive> directive
builds a filter chain from smart filters declared, offering the
flexibility to insert filters at the beginning or end of the chain,
remove a filter, or clear the chain.</dd>
</dl>
<p>Example: a configuration to unpack, downsample and re-pack web images.</p>
<example>
FilterDeclare unpack Content-Type<br/>
FilterProvider unpack jpeg_unpack $image/jpeg<br/>
FilterProvider unpack gif_unpack $image/gif<br/>
FilterProvider unpack png_unpack $image/png<br/>
FilterDeclare downsample Content-Type<br/>
FilterProvider downsample downsample_filter $image<br/>
FilterProtocol downsample "change=yes"<br/>
FilterDeclare pack Content-Type<br/>
FilterProvider pack jpeg_pack $image/jpeg<br/>
FilterProvider pack gif_pack $image/gif<br/>
FilterProvider pack png_pack $image/png<br/>
FilterChain unpack downsample repack<br/>
</example>
</section>
<section id="protocol"><title>Protocol Handling</title>
<p>Historically, each filter is responsible for ensuring that whatever
changes it makes are correctly represented in the HTTP response headers,
and that it does not run when it would make an illegal change. This
imposes a burden on filter authors to re-implement some common
functionality in every filter:</p>
<ul>
<li>Many filters will change the content, invalidating existing content
tags, checksums, hashes, and lengths.</li>
<li>Filters that require an entire, unbroken response in input need to
ensure they don't get byteranges from a backend.</li>
<li>Filters that transform output in a filter need to ensure they don't
violate a <code>Cache-Control: no-transform</code> header from the
backend.</li>
<li>Filters may make responses uncacheable.</li>
</ul>
<p>mod_filter aims to offer generic handling of these details of filter
implementation, reducing the complexity required of content filter modules.
This is work-in-progress; the <directive>FilterProtocol</directive>
implements some of this functionality, but there are no API calls yet.</p>
<p>At the same time, mod_filter should not interfere with a filter that
wants to handle all aspects of the protocol. By default (i.e. in the
absence of any <directive>FilterProtocol</directive> directives), mod_filter
will leave the headers untouched.</p>
</section>
<directivesynopsis>
<name>FilterDeclare</name>
<description>Declare a smart filter</description>
<syntax>FilterDeclare <var>filter-name</var> [req|resp|env]=<var>dispatch</var>
</syntax>
<contextlist><context>server config</context><context>virtual host</context>
<context>directory</context><context>.htaccess</context></contextlist>
<usage>
<p>This directive declares an output filter together with a
header or environment variable that will determine runtime
configuration. The first argument is a <code>filter-name</code>
for use in <directive>FilterProvider</directive>,
<directive>FilterChain</directive> and
<directive>FilterProtocol</directive> directives.
The second 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.</p>
</usage>
</directivesynopsis>
<directivesynopsis>
<name>FilterProvider</name>
<description>Register a content filter</description>
<syntax>FilterProvider <var>filter-name</var> <var>provider-name</var>
<var>match</var></syntax>
<contextlist><context>server config</context><context>virtual host</context>
<context>directory</context><context>.htaccess</context></contextlist>
<usage>
<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> in the <directive>FilterDeclare</directive>
directive that declared <var>filter-name</var>.</p>
<p><var>filter-name</var> must have been declared with
<directive>FilterDeclare</directive>. <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>match</var> argument specifies a match that will be applied to
the filter's <var>dispatch</var> criterion. The match may be a string
match (exact match or substring), a regexp, an integer (greater, lessthan
or equals), or unconditional. The first character of the <var>match</var>
argument determines this:</p>
<dl>
<dt>default</dt>
<dd>exact match</dd>
<dt>$</dt>
<dd>substring match</dd>
<dt>/</dt>
<dd>regexp match</dd>
<dt>=</dt>
<dd>integer equality</dd>
<dt><</dt>
<dd>integer less-than</dd>
<dt>></dt>
<dd>integer greater-than</dd>
<dt>*</dt>
<dd>Unconditional match</dd>
</dl>
</usage>
</directivesynopsis>
<directivesynopsis>
<name>FilterChain</name>
<description>Configure the filter chain</description>
<syntax>FilterChain ([EMAIL PROTECTED]<var>filter-name</var>)+</syntax>
<contextlist><context>server config</context><context>virtual host</context>
<context>directory</context><context>.htaccess</context></contextlist>
<usage>
<p>This configures an actual filter chain, from declared filters.
<directive>FilterChain</directive> takes any number of arguments,
each optionally preceded with a single-character control that
determines what to do:</p>
<dl>
<dt>+filter-name</dt>
<dd>Add filter-name to the end of the filter chain</dd>
<dt>@filter-name</dt>
<dd>Insert filter-name at the start of the filter chain</dd>
<dt>-filter-name</dt>
<dd>Remove filter-name from the filter chain</dd>
<dt>=filter-name</dt>
<dd>Empty the filter chain and insert filter-name</dd>
<dt>!</dt>
<dd>Empty the filter chain</dd>
<dt>filter-name</dt>
<dd>Equivalent to +filter-name</dd>
</dl>
</usage>
</directivesynopsis>
<directivesynopsis>
<name>FilterProtocol</name>
<description>Deal with correct HTTP protocol handling</description>
<syntax>FilterProtocol filter-name [provider-name] "proto-flags"</syntax>
<contextlist><context>server config</context><context>virtual host</context>
<context>directory</context><context>.htaccess</context></contextlist>
<usage>
<p>This directs mod_filter 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 filter-name and a provider for that filter.
With two arguments it applies to a filter-name whenever the filter runs
<em>any</em> provider.</p>
<p>proto-flags is one or more of</p>
<dl>
<dt>change=yes</dt>
<dd>The filter changes the content, including possibly the content length</dd>
<dt>change=1:1</dt>
<dd>The filter changes the content, but will not change the content length</dd>
<dt>byteranges=no</dt>
<dd>The filter cannot work on byteranges and requires complete input</dd>
<dt>proxy=no</dt>
<dd>The filter should not run in a proxy context</dd>
<dt>proxy=transform</dt>
<dd>The filter transforms the response in a manner incompatible with
the HTTP <code>Cache-Control: no-transform</code> header.</dd>
<dt>cache=no</dt>
<dd>The filter renders the output uncacheable (eg by introducing randomised
content changes)</dd>
</dl>
</usage>
</directivesynopsis>
</modulesynopsis>
<?xml version="1.0" encoding="UTF-8" ?>
<metafile>
<basename>mod_filter</basename>
<path>/mod/</path>
<relpath>..</relpath>
<variants>
<variant>en</variant>
</variants>
</metafile>
<?xml version="1.0" encoding="ISO-8859-1"?> <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd";> <html xmlns="http://www.w3.org/1999/xhtml"; xml:lang="en" lang="en"><head><meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1" /><!-- XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX This file is generated from xml source: DO NOT EDIT XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX --> <title>mod_filter - Apache HTTP Server</title> <link title="Main stylesheet" type="text/css" media="all" rel="stylesheet" href="../style/css/manual.css" /> <link title="No Sidebar - Default font size" type="text/css" media="all" rel="alternate stylesheet" href="../style/css/manual-loose-100pc.css" /> <link type="text/css" media="print" rel="stylesheet" href="../style/css/manual-print.css" /> <link rel="shortcut icon" href="../images/favicon.ico" /></head> <body> <div id="page-header"> <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> <p class="apache">Apache HTTP Server Version 2.1</p> <img src="../images/feather.gif" alt="" /></div> <div class="up"><a href="./"><img src="../images/left.gif" alt="<-" title="<-" /></a></div> <div id="path"> <a href="http://www.apache.org/";>Apache</a> > <a href="http://httpd.apache.org/";>HTTP Server</a> > <a href="http://httpd.apache.org/docs-project/";>Documentation</a> > <a href="../">Version 2.1</a> > <a href="./">Modules</a></div> <div id="page-content"> <div id="preamble"><h1>Apache Module mod_filter</h1> <div class="toplang"> <p><span>Available Languages: </span><a href="../en/mod/mod_filter.html" title="English"> en </a></p> </div> <table class="module"><tr><th><a href="module-dict.html#Description">Description:</a></th><td>Context-sensitive smart filter configuration module</td></tr> <tr><th><a href="module-dict.html#Status">Status:</a></th><td>Extension</td></tr> <tr><th><a href="module-dict.html#ModuleIdentifier">Module Identifier:</a></th><td>filter_module</td></tr> <tr><th><a href="module-dict.html#SourceFile">Source File:</a></th><td>mod_filter.c</td></tr> <tr><th><a href="module-dict.html#Compatibility">Compatibility:</a></th><td>Apache 2.0 and higher</td></tr></table> <h3>Summary</h3> <p>This module enables smart, context-sensitive configuration of output content filters. For example, apache can be configured to process different content-types through different filters, even when the content-type is not known in advance (e.g. in a proxy). </p> </div> <div id="quickview"><h3 class="directives">Directives</h3> <ul id="toc"> <li><img src="../images/down.gif" alt="" /> <a href="#filterchain">FilterChain</a></li> <li><img src="../images/down.gif" alt="" /> <a href="#filterdeclare">FilterDeclare</a></li> <li><img src="../images/down.gif" alt="" /> <a href="#filterprotocol">FilterProtocol</a></li> <li><img src="../images/down.gif" alt="" /> <a href="#filterprovider">FilterProvider</a></li> </ul> <h3>Topics</h3> <ul id="topics"> <li><img src="../images/down.gif" alt="" /> <a href="#smart">Smart Filtering</a></li> <li><img src="../images/down.gif" alt="" /> <a href="#terms">Filter Declarations, Providers and Chains</a></li> <li><img src="../images/down.gif" alt="" /> <a href="#config">Configuring the Chain</a></li> <li><img src="../images/down.gif" alt="" /> <a href="#protocol">Protocol Handling</a></li> </ul></div> <div class="top"><a href="#page-header"><img src="../images/up.gif" alt="top" /></a></div> <div class="section"> <h2><a id="smart" name="smart">Smart Filtering</a></h2> <p>In the traditional filtering model, filters are inserted unconditionally using <code class="directive"><a href="../mod/core.html#addoutputfilter">AddOutputFilter</a></code> and family. Each filter then needs to determine whether to run, and there is little flexibility available for server admins to allow the chain to be configured dynamically.</p> <p>mod_filter by contrast gives server administrators a great deal of flexibility in configuring the filter chain. In fact, filters can be inserted based on any Request Header, Response Header or Environment Variable. This generalises the limited flexibility offered by <code class="directive"><a href="../mod/core.html#addoutputfilterbytype">AddOutputFilterByType</a></code>, and fixes it to work correctly with dynamic content, regardless of the content generator. The ability to dispatch based on Environment Variables offers the full flexibility of configuration with <code class="module"><a href="../mod/mod_rewrite.html">mod_rewrite</a></code> to anyone who needs it.</p> </div><div class="top"><a href="#page-header"><img src="../images/up.gif" alt="top" /></a></div> <div class="section"> <h2><a id="terms" name="terms">Filter Declarations, Providers and Chains</a></h2> <img src="oldfilter.gif" alt="" /> <p>In the traditional model, output filters are a simple chain from the content generator (handler) to the client. This works well provided the filter chain can be correctly configured, but presents problems when the filters need to be configured dynamically based on the outcome of the handler.</p> <img src="newfilter.gif" alt="" /> <p>mod_filter works by introducing indirection into the filter chain. Instead of introducing filters in the chain, we introduce a filter harness which in turn dispatches conditionally to a filter provider. Any content filter may be used as a provider to mod_filter; no change to existing filter modules is required (although it may be possible to simplify them). There can be multiple providers for one filter, but no more than one provider will run for any single request. </p> <p>A filter chain comprises any number of instances of the filter harness, each of which may have any number of providers. A special case is that of a single provider with unconditional dispatch: this is equivalent to inserting the provider filter directly into the chain. </p> </div><div class="top"><a href="#page-header"><img src="../images/up.gif" alt="top" /></a></div> <div class="section"> <h2><a id="config" name="config">Configuring the Chain</a></h2> <p>There are three stages to configuring a filter chain with mod_filter. For details of the directives, see below.</p> <dl> <dt>Declare Filters</dt> <dd>The <code class="directive">FilterDeclare</code> directive declares a filter, assigning it a name and a dispatch criterion.</dd> <dt>Register Providers</dt> <dd>The <code class="directive">FilterProvider</code> directive registers a provider with a filter. The filter must have been registered with <code class="directive">FilterDeclare</code>. The provider must have been registered with <code>ap_register_output_filter</code> by some module. The final argument to <code class="directive">FilterProvider</code> is a match string, that will be checked against the filter's dispatch criterion to determine whether to run this provider.</dd> <dt>Configure the Chain</dt> <dd>The above directives build components of a smart filter chain, but do not configure it to run. The <code class="directive">FilterChain</code> directive builds a filter chain from smart filters declared, offering the flexibility to insert filters at the beginning or end of the chain, remove a filter, or clear the chain.</dd> </dl> <p>Example: a configuration to unpack, downsample and re-pack web images.</p> <div class="example"><p><code> FilterDeclare unpack Content-Type<br /> FilterProvider unpack jpeg_unpack $image/jpeg<br /> FilterProvider unpack gif_unpack $image/gif<br /> FilterProvider unpack png_unpack $image/png<br /> FilterDeclare downsample Content-Type<br /> FilterProvider downsample downsample_filter $image<br /> FilterProtocol downsample "change=yes"<br /> FilterDeclare pack Content-Type<br /> FilterProvider pack jpeg_pack $image/jpeg<br /> FilterProvider pack gif_pack $image/gif<br /> FilterProvider pack png_pack $image/png<br /> FilterChain unpack downsample repack<br /> </code></p></div> </div><div class="top"><a href="#page-header"><img src="../images/up.gif" alt="top" /></a></div> <div class="section"> <h2><a id="protocol" name="protocol">Protocol Handling</a></h2> <p>Historically, each filter is responsible for ensuring that whatever changes it makes are correctly represented in the HTTP response headers, and that it does not run when it would make an illegal change. This imposes a burden on filter authors to re-implement some common functionality in every filter:</p> <ul> <li>Many filters will change the content, invalidating existing content tags, checksums, hashes, and lengths.</li> <li>Filters that require an entire, unbroken response in input need to ensure they don't get byteranges from a backend.</li> <li>Filters that transform output in a filter need to ensure they don't violate a <code>Cache-Control: no-transform</code> header from the backend.</li> <li>Filters may make responses uncacheable.</li> </ul> <p>mod_filter aims to offer generic handling of these details of filter implementation, reducing the complexity required of content filter modules. This is work-in-progress; the <code class="directive">FilterProtocol</code> implements some of this functionality, but there are no API calls yet.</p> <p>At the same time, mod_filter 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">FilterProtocol</code> directives), mod_filter will leave the headers untouched.</p> </div> <div class="top"><a href="#page-header"><img src="../images/up.gif" alt="top" /></a></div> <div class="directive-section"><h2><a id="FilterChain" name="FilterChain">FilterChain</a> <a id="filterchain" name="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 ([EMAIL PROTECTED]<var>filter-name</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#Status">Status:</a></th><td>Extension</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>+filter-name</dt> <dd>Add filter-name to the end of the filter chain</dd> <dt>@filter-name</dt> <dd>Insert filter-name at the start of the filter chain</dd> <dt>-filter-name</dt> <dd>Remove filter-name from the filter chain</dd> <dt>=filter-name</dt> <dd>Empty the filter chain and insert filter-name</dd> <dt>!</dt> <dd>Empty the filter chain</dd> <dt>filter-name</dt> <dd>Equivalent to +filter-name</dd> </dl> </div> <div class="top"><a href="#page-header"><img src="../images/up.gif" alt="top" /></a></div> <div class="directive-section"><h2><a id="FilterDeclare" name="FilterDeclare">FilterDeclare</a> <a id="filterdeclare" name="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> [req|resp|env]=<var>dispatch</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#Status">Status:</a></th><td>Extension</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 <code>filter-name</code> for use in <code class="directive">FilterProvider</code>, <code class="directive">FilterChain</code> and <code class="directive">FilterProtocol</code> directives. The second 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.</p> </div> <div class="top"><a href="#page-header"><img src="../images/up.gif" alt="top" /></a></div> <div class="directive-section"><h2><a id="FilterProtocol" name="FilterProtocol">FilterProtocol</a> <a id="filterprotocol" name="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 filter-name [provider-name] "proto-flags"</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#Status">Status:</a></th><td>Extension</td></tr> <tr><th><a href="directive-dict.html#Module">Module:</a></th><td>mod_filter</td></tr> </table> <p>This directs mod_filter 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 filter-name and a provider for that filter. With two arguments it applies to a filter-name whenever the filter runs <em>any</em> provider.</p> <p>proto-flags is one or more of</p> <dl> <dt>change=yes</dt> <dd>The filter changes the content, including possibly the content length</dd> <dt>change=1:1</dt> <dd>The filter changes the content, but will not change the content length</dd> <dt>byteranges=no</dt> <dd>The filter cannot work on byteranges and requires complete input</dd> <dt>proxy=no</dt> <dd>The filter should not run in a proxy context</dd> <dt>proxy=transform</dt> <dd>The filter transforms the response in a manner incompatible with the HTTP <code>Cache-Control: no-transform</code> header.</dd> <dt>cache=no</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 src="../images/up.gif" alt="top" /></a></div> <div class="directive-section"><h2><a id="FilterProvider" name="FilterProvider">FilterProvider</a> <a id="filterprovider" name="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> <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#Status">Status:</a></th><td>Extension</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> in the <code class="directive">FilterDeclare</code> directive that declared <var>filter-name</var>.</p> <p><var>filter-name</var> must have been declared with <code class="directive">FilterDeclare</code>. <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>match</var> argument specifies a match that will be applied to the filter's <var>dispatch</var> criterion. The match may be a string match (exact match or substring), a regexp, an integer (greater, lessthan or equals), or unconditional. The first character of the <var>match</var> argument determines this:</p> <dl> <dt>default</dt> <dd>exact match</dd> <dt>$</dt> <dd>substring match</dd> <dt>/</dt> <dd>regexp match</dd> <dt>=</dt> <dd>integer equality</dd> <dt><</dt> <dd>integer less-than</dd> <dt>></dt> <dd>integer greater-than</dd> <dt>*</dt> <dd>Unconditional match</dd> </dl> </div> </div> <div class="bottomlang"> <p><span>Available Languages: </span><a href="../en/mod/mod_filter.html" title="English"> en </a></p> </div><div id="footer"> <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> <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>
<<attachment: oldfilter.gif>>
<<attachment: newfilter.gif>>
