apache 插件开发之过滤器 (filter)

bestjoe

过滤器(filter)
A filter is a process that is applied to data that is sent or received by the server. Data sent by clients to the server is processed by input filters while data sent by the server to the client is processed by output filters. Multiple filters can be applied to the data, and the order of the filters can be explicitly specified.
过滤器用来对 server 收到/发送的数据进行再加工。过滤器分两种：input filters 用于处理 server 从 client 收到的数据，output filters 用于处理 server 向 client 发送的数据。一个数据流上可以挂多个过滤器。这些过滤器可以通过显式指定来确定执行顺序。　　Filters are used internally by Apache to perform functions such as chunking and byte-range request handling. In addition, modules can provide filters that are selectable using run-time configuration directives. The set of filters that apply to data can be manipulated with the SetInputFilter, SetOutputFilter, AddInputFilter, AddOutputFilter, RemoveInputFilter, and RemoveOutputFilter directives.


　　数据的输入和输出：
　　过滤器所加工的数据，存储在一种称为 桶 bucket 的容器中。 bucket 的实际存储可以是 文件\管道(pipe)\流(socket stream )堆内存(heap)甚至是栈内存（stack）。apache 提供了apr_bucket_read 方法，将 bucket 中的数据读取到用户指定的内存中。apchet 也提供了数据在不同类型的 bucket 之间传递的的手段。除了常规的 apr_bucket_copy　外，还提供了



　　


过滤器可以通过 conf 中 配置的指令来决定 过滤器用于哪些数据。apache filter 官方文档介绍了 filter 可接受的配置指令。 主要的可分为两类：　　１、强制过滤器（SetInputFilter, SetOutputFilter)。例如，在输出 http页面时，强制在每个页面加入页底的版权信息。
　　２、选择性过滤器。分为按扩展名过滤(AddHandler),按MIME类型过滤(AddInputFilter)
　　３、过滤器内部参数过滤。例如下面介绍的 CaseFilter。
　　


过滤器的注册和使用：
  　　过滤器使用 ap_register_output_filter 进行注册。并通过 ap_add_output_filter 来唤醒调用。

　　Filters currently register using

　　ap_register_output_filter(name, filter_func, filter_init, ftype)
　　and are inserted using

ap_add_output_filter(name, ctx, req, conn) 　　关于 以上两个api的用法，Ryan Bloom 在其文章 Writing Apache 2.0 Output Filters  中做了详细解释。
　　
　　apache 2.2.17中，提供了一个CaseFilter示例 (.\modules\cache\mod_cache.c)。caseFilter 用于把向 client 输出的字母都转换为大写。寥寥百行代码，是学习 filter的良好教程。


  1 /* Licensed to the Apache Software Foundation (ASF) under one or more
  2  * contributor license agreements.  See the NOTICE file distributed with
  3  * this work for additional information regarding copyright ownership.
  4  * The ASF licenses this file to You under the Apache License, Version 2.0
  5  * (the "License"); you may not use this file except in compliance with
  6  * the License.  You may obtain a copy of the License at
  7  *
  8  *     http://www.apache.org/licenses/LICENSE-2.0
  9  *
10  * Unless required by applicable law or agreed to in writing, software
11  * distributed under the License is distributed on an "AS IS" BASIS,
12  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13  * See the License for the specific language governing permissions and
14  * limitations under the License.
15  */
16
17 #include "httpd.h"
18 #include "http_config.h"
19 #include "apr_buckets.h"
20 #include "apr_general.h"
21 #include "apr_lib.h"
22 #include "util_filter.h"
23 #include "http_request.h"
24
25 #include
26
27 static const char s_szCaseFilterName[]="CaseFilter";
28 module AP_MODULE_DECLARE_DATA case_filter_module;
29
30 typedef struct
31     {
32     int bEnabled;
33     } CaseFilterConfig;
34
35 static void *CaseFilterCreateServerConfig(apr_pool_t *p,server_rec *s)
36     {
37     CaseFilterConfig *pConfig=apr_pcalloc(p,sizeof *pConfig);
38
39     pConfig->bEnabled=0;
40
41     return pConfig;
42     }
43
44 static void CaseFilterInsertFilter(request_rec *r)
45     {
46     CaseFilterConfig *pConfig=ap_get_module_config(r->server->module_config,
47                                                    &case_filter_module);
48
49     if(!pConfig->bEnabled)
50         return;
51
52     ap_add_output_filter(s_szCaseFilterName,NULL,r,r->connection);
53     }
54
55 static apr_status_t CaseFilterOutFilter(ap_filter_t *f,
56                                         apr_bucket_brigade *pbbIn)
57     {
58     request_rec *r = f->r;
59     conn_rec *c = r->connection;
60     apr_bucket *pbktIn;
61     apr_bucket_brigade *pbbOut;
62
63     pbbOut=apr_brigade_create(r->pool, c->bucket_alloc);
64     for (pbktIn = APR_BRIGADE_FIRST(pbbIn);
65          pbktIn != APR_BRIGADE_SENTINEL(pbbIn);
66          pbktIn = APR_BUCKET_NEXT(pbktIn))
67     {
68         const char *data;
69         apr_size_t len;
70         char *buf;
71         apr_size_t n;
72         apr_bucket *pbktOut;
73
74         if(APR_BUCKET_IS_EOS(pbktIn))
75             {
76             apr_bucket *pbktEOS=apr_bucket_eos_create(c->bucket_alloc);
77             APR_BRIGADE_INSERT_TAIL(pbbOut,pbktEOS);
78             continue;
79             }
80
81         /* read */
82         apr_bucket_read(pbktIn,&data,&len,APR_BLOCK_READ);
83
84         /* write */
85         buf = apr_bucket_alloc(len, c->bucket_alloc);
86         for(n=0 ; n < len ; ++n)
87             buf[n] = apr_toupper(data[n]);
88
89         pbktOut = apr_bucket_heap_create(buf, len, apr_bucket_free,
90                                          c->bucket_alloc);
91         APR_BRIGADE_INSERT_TAIL(pbbOut,pbktOut);
92         }
93
94     /* Q: is there any advantage to passing a brigade for each bucket?
95      * A: obviously, it can cut down server resource consumption, if this
96      * experimental module was fed a file of 4MB, it would be using 8MB for
97      * the 'read' buckets and the 'write' buckets.
98      *
99      * Note it is more efficient to consume (destroy) each bucket as it's
100      * processed above than to do a single cleanup down here.  In any case,
101      * don't let our caller pass the same buckets to us, twice;
102      */
103     apr_brigade_cleanup(pbbIn);
104     return ap_pass_brigade(f->next,pbbOut);
105     }
106
107 static const char *CaseFilterEnable(cmd_parms *cmd, void *dummy, int arg)
108     {
109     CaseFilterConfig *pConfig=ap_get_module_config(cmd->server->module_config,
110                                                    &case_filter_module);
111     pConfig->bEnabled=arg;
112
113     return NULL;
114     }
115
116 static const command_rec CaseFilterCmds[] =
117     {
118     AP_INIT_FLAG("CaseFilter", CaseFilterEnable, NULL, RSRC_CONF,
119                  "Run a case filter on this host"),
120     { NULL }
121     };
122
123 static void CaseFilterRegisterHooks(apr_pool_t *p)
124     {
125     ap_hook_insert_filter(CaseFilterInsertFilter,NULL,NULL,APR_HOOK_MIDDLE);
126     ap_register_output_filter(s_szCaseFilterName,CaseFilterOutFilter,NULL,
127                               AP_FTYPE_RESOURCE);
128     }
129
130 module AP_MODULE_DECLARE_DATA case_filter_module =
131 {
132     STANDARD20_MODULE_STUFF,
133     NULL,
134     NULL,
135     CaseFilterCreateServerConfig,
136     NULL,
137     CaseFilterCmds,
138     CaseFilterRegisterHooks
139 };　　
　　以上代码的执行过程是这样的：
1、加载 case_filter_module 模块，通过 CaseFilterRegisterHooks 注册过滤函数 CaseFilterOutFilter。
　　2、
　　相关链接：
　　

apache filter 官方文档　　http://httpd.apache.org/docs/2.0/filter.html  介绍了 filter 可接受的配置指令。

　　

http://www.apachetutor.org/dev/smart-filter

Ryan Bloom  Writing Apache 2.0 Output Filters

Ryan Bloom  Writing Filters for Apache 2.0