这是我的页面头部

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

过滤器(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 可接受的配置指令。 主要的可分为两类:

1、强制过滤器(SetInputFilter, SetOutputFilter)。例如,在输出 http页面时,强制在每个页面加入页底的版权信息。

2、选择性过滤器。分为按扩展名过滤(AddHandler),按MIME类型过滤(AddInputFilter)

3、过滤器内部参数过滤。例如下面介绍的 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 <ctype.h>
 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 *= f->r;
 59     conn_rec *= 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


 

posted @ 2011-05-05 11:19  范晨鹏  阅读(7838)  评论(0编辑  收藏  举报