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 可接受的配置指令。 主要的可分为两类：

１、强制过滤器（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  < 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  * 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