1docs::api::Apache2::FilUtseerr(3C)ontributed Perl Documednotcast:i:oanpi::Apache2::Filter(3)
2
6 Apache2::Filter - Perl API for Apache 2.0 Filtering
7
9 use Apache2::Filter ();
10 # filter attributes
12 my $c = $f->c;
13 my $r = $f->r;
14 my $frec = $f->frec();
15 my $next_f = $f->next;
16 my $ctx = $f->ctx;
18 $f->ctx($ctx);
19 # bucket brigade filtering API
21 $rc = $f->next->get_brigade($bb, $mode, $block, $readbytes);
22 $rc = $f->next->pass_brigade($bb);
23 $rc = $f->fflush($bb);
24 # streaming filtering API
26 while ($filter->read(my $buffer, $wanted)) {
27 # transform $buffer here
28 $filter->print($buffer);
29 }
30 if ($f->seen_eos) {
31 $filter->print("filter signature");
32 }
33 # filter manipulations
35 $r->add_input_filter(\&callback);
36 $c->add_input_filter(\&callback);
37 $r->add_output_filter(\&callback);
38 $c->add_output_filter(\&callback);
39 $f->remove;
40
42 "Apache2::Filter" provides Perl API for Apache 2.0 filtering framework.
43 Make sure to read "the Filtering tutorial⎪docs::2.0::user::han‐
45 dlers::filters".
46
48 The following methods can be called from any filter handler:
49 "c"
51 Get the current connection object from a connection or a request fil‐
53 ter:
54 $c = $f->c;
56 obj: $f ( "Apache2::Filter object" )
58 ret: $c ( "Apache2::Connection object" )
59 since: 2.0.00
60 "ctx"
62 Get/set the filter context data.
64 $ctx = $f->ctx;
66 $f->ctx($ctx);
67 obj: $f ( "Apache2::Filter object" )
69 opt arg2: $ctx ( SCALAR )
70 next context
71 ret: $ctx ( SCALAR )
73 current context
74 since: 2.0.00
76 A filter context is created before the filter is called for the first
78 time and it's destroyed at the end of the request. The context is pre‐
79 served between filter invocations of the same request. So if a filter
80 needs to store some data between invocations it should use the filter
81 context for that. The filter context is initialized with the "undef"
82 value.
83 The "ctx" method accepts a single SCALAR argument. Therefore if you
85 want to store any other perl datastructure you should use a reference
86 to it.
87 For example you can store a hash reference:
89 $f->ctx({ foo => 'bar' });
91 and then access it:
93 $foo = $f->ctx->{foo};
95 if you access the context more than once it's more efficient to copy
97 it's value before using it:
98 my $ctx = $f->ctx;
100 $foo = $ctx->{foo};
101 to avoid redundant method calls. As of this writing $ctx is not a tied
103 variable, so if you modify it need to store it at the end:
104 $f->ctx($ctx);
106 META: later we might make it a TIEd-variable interface, so it'll be
108 stored automatically.
109 Besides its primary purpose of storing context data across multiple
111 filter invocations, this method is also useful when used as a flag. For
112 example here is how to ensure that something happens only once during
113 the filter's life:
114 unless ($f->ctx) {
116 do_something_once();
117 $f->ctx(1);
118 }
119 "frec"
121 Get/set the "Apache2::FilterRec" (filter record) object.
123 $frec = $f->frec();
125 obj: $f ( "Apache2::Filter object" )
127 ret: $frec ( "Apache2::FilterRec object" )
128 since: 2.0.00
129 For example you can call "$frec->name" to get filter's name.
131 "next"
133 Return the "Apache2::Filter" object of the next filter in chain.
135 $next_f = $f->next;
137 obj: $f ( "Apache2::Filter object" )
139 The current filter object
140 ret: $next_f ( "Apache2::Filter object" )
142 The next filter object in chain
143 since: 2.0.00
145 Since Apache inserts several core filters at the end of each chain,
147 normally this method always returns an object. However if it's not a
148 mod_perl filter handler, you can call only the following methods on it:
149 "get_brigade", "pass_brigade", "c", "r", "frec" and "next". If you call
150 other methods the behavior is undefined.
151 The next filter can be a mod_perl one or not, it's easy to tell which
153 one is that by calling "$f->frec->name".
154 "r"
156 Inside an HTTP request filter retrieve the current request object:
158 $r = $f->r;
160 obj: $f ( "Apache2::Filter object" )
162 ret: $r ( "Apache2::RequestRec object" )
163 since: 2.0.00
164 If a sub-request adds filters, then that sub-request object is associ‐
166 ated with the filter.
167 "remove"
169 Remove the current filter from the filter chain (for the current
171 request or connection).
172 $f->remove;
174 obj: $f ( "Apache2::Filter object" )
176 ret: no return value
177 since: 2.0.00
178 Notice that you should either complete the current filter invocation
180 normally (by calling "get_brigade" or "pass_brigade" depending on the
181 filter kind) or if nothing was done, return "Apache2::Const::DECLINED"
182 and mod_perl will take care of passing the current bucket brigade
183 through unmodified to the next filter in chain.
184 Note: calling remove() on the very top connection filter doesn't affect
186 the filter chain due to a bug in Apache 2.0 (which may be fixed in
187 2.1). So don't use it with connection filters, till it gets fixed in
188 Apache and then make sure to require the minimum Apache version if you
189 rely on.
190 Remember that if the connection is "$c->keepalive" ) and the connection
192 filter is removed, it won't be added until the connection is closed.
193 Which may happen after many HTTP requests. You may want to keep the
194 filter in place and pass the data through unmodified, by returning
195 "Apache2::Const::DECLINED". If you need to reset the whole or parts of
196 the filter context between requests, use the technique based on
197 "$c->keepalives" counting.
198 This method works for native Apache (non-mod_perl) filters too.
200
202 The following methods can be called from any filter, directly manipu‐
203 lating bucket brigades:
204 "fflush"
206 Flush a bucket brigade down the filter stack.
208 $rc = $f->fflush($bb);
210 obj: $f ( "Apache2::Filter object" )
212 The current filter
213 arg1: $bb ( "Apache2::Brigade object" )
215 The brigade to flush
216 ret: $rc ( "APR::Const status constant" )
218 Refer to the "pass_brigade()" entry.
219 excpt: "APR::Error"
221 Exceptions are thrown only when this function is called in the VOID
222 context. Refer to the "get_brigade()" entry for details.
223 since: 2.0.00
225 "fflush" is a shortcut method. So instead of doing:
227 my $b = APR::Bucket::flush_create($f->c->bucket_alloc);
229 $bb->insert_tail($b);
230 $f->pass_brigade($bb);
231 one can just write:
233 $f->fflush($bb);
235 "get_brigade"
237 This is a method to use in bucket brigade input filters. It acquires a
239 bucket brigade from the upstream input filter.
240 $rc = $next_f->get_brigade($bb, $mode, $block, $readbytes);
242 $rc = $next_f->get_brigade($bb, $mode, $block);
243 $rc = $next_f->get_brigade($bb, $mode)
244 $rc = $next_f->get_brigade($bb);
245 obj: $next_f ( "Apache2::Filter object" )
247 The next filter in the filter chain.
248 Inside filter handlers it's usually "$f->next". Inside protocol
250 handlers: "$c->input_filters".
251 arg1: $bb ( "APR::Brigade object" )
253 The original bucket brigade passed to "get_brigade()", which must
254 be empty.
255 Inside input filter handlers it's usually the second argument to
257 the filter handler.
258 Otherwise it should be created:
260 my $bb = APR::Brigade->new($c->pool, $c->bucket_alloc);
262 On return it gets populated with the next bucket brigade. That
264 brigade may contain nothing if there was no more data to read. The
265 return status tells the outcome.
266 opt arg2: $mode ( "Apache2::Const :input_mode constant" )
268 The filter mode in which the data should be read.
269 If inside the filter handler, you should normally pass the same
271 mode that was passed to the filter handler (the third argument).
272 At the end of this section the available modes are presented.
274 If the argument $mode is not passed, "Apache2::Const::MODE_READ‐
276 BYTES" is used as a default value.
277 opt arg3: $block ( "APR::Const :read_type constant" )
279 You may ask the reading operation to be blocking:
280 "APR::Const::BLOCK_READ", or nonblocking: "APR::Const::NON‐
281 BLOCK_READ".
282 If inside the filter handler, you should normally pass the same
284 blocking mode argument that was passed to the filter handler (the
285 forth argument).
286 If the argument $block is not passed, "APR::Const::BLOCK_READ" is
288 used as a default value.
289 opt arg4: $readbytes ( integer )
291 How many bytes to read from the next filter.
292 If inside the filter handler, you may want the same number of
294 bytes, as the upstream filter, i.e. the argument that was passed to
295 the filter handler (the fifth argument).
296 If the argument $block is not passed, 8192 is used as a default
298 value.
299 ret: $rc ( "APR::Const status constant" )
301 On success, "APR::Const::SUCCESS" is returned and $bb is populated
302 (see the $bb entry).
303 In case of a failure -- a failure code is returned, in which case
305 normally it should be returned to the caller.
306 If the bottom-most filter doesn't read from the network, then
308 "Apache2::NOBODY_READ" is returned (META: need to add this con‐
309 stant).
310 Inside protocol handlers the return code can also be
312 "APR::Const::EOF", which is success as well.
313 excpt: "APR::Error"
315 You don't have to ask for the return value. If this function is
316 called in the VOID context, e.g.:
317 $f->next->get_brigade($bb, $mode, $block, $readbytes);
319 mod_perl will do the error checking on your behalf, and if the
321 return code is not "APR::Const::SUCCESS", an "APR::Error exception"
322 will be thrown. The only time you want to do the error checking
323 yourself, is when return codes besides "APR::Const::SUCCESS" are
324 considered as successful and you want to manage them by yourself.
325 since: 2.0.00
327 Available input filter modes (the optional second argument $mode) are:
329 * "Apache2::Const::MODE_READBYTES"
331 The filter should return at most readbytes data
332 * "Apache2::Const::MODE_GETLINE"
334 The filter should return at most one line of CRLF data. (If a
335 potential line is too long or no CRLF is found, the filter may
336 return partial data).
337 * "Apache2::Const::MODE_EATCRLF"
339 The filter should implicitly eat any CRLF pairs that it sees.
340 * "Apache2::Const::MODE_SPECULATIVE"
342 The filter read should be treated as speculative and any returned
343 data should be stored for later retrieval in another mode.
344 * "Apache2::Const::MODE_EXHAUSTIVE"
346 The filter read should be exhaustive and read until it can not read
347 any more. Use this mode with extreme caution.
348 * "Apache2::Const::MODE_INIT"
350 The filter should initialize the connection if needed, NNTP or FTP
351 over SSL for example.
352 Either compile all these constants with:
354 use Apache2::Const -compile => qw(:input_mode);
356 But it's a bit more efficient to compile only those constants that you
358 need.
359 Example:
361 Here is a fragment of a filter handler, that receives a bucket brigade
363 from the upstream filter:
364 use Apache2::Filter ();
366 use APR::Const -compile => qw(SUCCESS);
367 use Apache2::Const -compile => qw(OK);
368 sub filter {
369 my ($f, $bb, $mode, $block, $readbytes) = @_;
370 my $rc = $f->next->get_brigade($bb, $mode, $block, $readbytes);
372 return $rc unless $rc == APR::Const::SUCCESS;
373 # ... process $bb
375 return Apache2::Const::OK;
377 }
378 Usually arguments $mode, $block, $readbytes are the same as passed to
380 the filter itself.
381 You can see that in case of a failure, the handler returns immediately
383 with that failure code, which gets propagated to the downstream filter.
384 If you decide not check the return code, you can write it as:
386 sub filter {
388 my ($f, $bb, $mode, $block, $readbytes) = @_;
389 $f->next->get_brigade($bb, $mode, $block, $readbytes);
391 # ... process $bb
393 return Apache2::Const::OK;
395 }
396 and the error checking will be done on your behalf.
398 You will find many more examples in "the filter han‐
400 dlers⎪docs::2.0::user::handlers::filters" and "the protocol han‐
401 dlers⎪docs::2.0::user::handlers::protocols" tutorials.
402 "pass_brigade"
404 This is a method to use in bucket brigade output filters. It passes
406 the current bucket brigade to the downstream output filter.
407 $rc = $next_f->pass_brigade($bb);
409 obj: $next_f ( "Apache2::Filter object" )
411 The next filter in the filter chain.
412 Inside output filter handlers it's usually "$f->next". Inside pro‐
414 tocol handlers: "$c->output_filters".
415 arg1: $bb ( "APR::Brigade object" )
417 The bucket brigade to pass.
418 Inside output filter handlers it's usually the second argument to
420 the filter handler (after potential manipulations).
421 ret: $rc ( "APR::Const status constant" )
423 On success, "APR::Const::SUCCESS" is returned.
424 In case of a failure -- a failure code is returned, in which case
426 normally it should be returned to the caller.
427 If the bottom-most filter doesn't write to the network, then
429 "Apache2::NOBODY_WROTE" is returned (META: need to add this con‐
430 stant).
431 Also refer to the "get_brigade()" entry to see how to avoid check‐
433 ing the errors explicitly.
434 excpt: "APR::Error"
436 Exceptions are thrown only when this function is called in the VOID
437 context. Refer to the "get_brigade()" entry for details.
438 since: 2.0.00
440 The caller relinquishes ownership of the brigade (i.e. it may get
442 destroyed/overwritten/etc. by the callee).
443 Example:
445 Here is a fragment of a filter handler, that passes a bucket brigade to
447 the downstream filter (after some potential processing of the buckets
448 in the bucket brigade):
449 use Apache2::Filter ();
451 use APR::Const -compile => qw(SUCCESS);
452 use Apache2::Const -compile => qw(OK);
453 sub filter {
454 my ($f, $bb) = @_;
455 # ... process $bb
457 my $rc = $f->next->pass_brigade($bb);
459 return $rc unless $rc == APR::Const::SUCCESS;
460 return Apache2::Const::OK;
462 }
463
465 The following methods can be called from any filter, which uses the
466 simplified streaming functionality:
467 "print"
469 Send the contents of $buffer to the next filter in chain (via internal
471 buffer).
472 $sent = $f->print($buffer);
474 obj: $f ( "Apache2::Filter object" )
476 arg1: $buffer ( string )
477 The data to send.
478 ret: $sent ( integer )
480 How many characters were sent. There is no need to check, since all
481 should go through and if something goes work an exception will be
482 thrown.
483 excpt: "APR::Error"
485 since: 2.0.00
486 This method should be used only in streaming filters.
488 "read"
490 Read data from the filter
492 $read = $f->read($buffer, $wanted);
494 obj: $f ( "Apache2::Filter object" )
496 arg1: $buffer ( SCALAR )
497 The buffer to fill. All previous data will be lost.
498 opt arg2: $wanted ( integer )
500 How many bytes to attempt to read.
501 If this optional argument is not specified -- the default 8192 will
503 be used.
504 ret: $read ( integer )
506 How many bytes were actually read.
507 $buffer gets populated with the string that is read. It will con‐
509 tain an empty string if there was nothing to read.
510 excpt: "APR::Error"
512 since: 2.0.00
513 Reads at most $wanted characters into $buffer. The returned value $read
515 tells exactly how many were read, making it easy to use it in a while
516 loop:
517 while ($filter->read(my $buffer, $wanted)) {
519 # transform $buffer here
520 $filter->print($buffer);
521 }
522 This is a streaming filter method, which acquires a single bucket
524 brigade behind the scenes and reads data from all its buckets. There‐
525 fore it can only read from one bucket brigade per filter invocation.
526 If the EOS bucket is read, the "seen_eos" method will return a true
528 value.
529 "seen_eos"
531 This methods returns a true value when the EOS bucket is seen by the
533 "read" method.
534 $ok = $f->seen_eos;
536 obj: $f ( "Apache2::Filter object" )
538 The filter to remove
539 ret: $ok ( boolean )
541 a true value if EOS has been seen, otherwise a false value
542 since: 2.0.00
544 This method only works in streaming filters which exhaustively
546 "$f->read" all the incoming data in a while loop, like so:
547 while ($f->read(my $buffer, $wanted)) {
549 # do something with $buffer
550 }
551 if ($f->seen_eos) {
552 # do something
553 }
554 The technique in this example is useful when a streaming filter wants
556 to append something to the very end of data, or do something at the end
557 of the last filter invocation. After the EOS bucket is read, the filter
558 should expect not to be invoked again.
559 If an input streaming filter doesn't consume all data in the bucket
561 brigade (or even in several bucket brigades), it has to generate the
562 EOS event by itself. So when the filter is done it has to set the EOS
563 flag:
564 $f->seen_eos(1);
566 when the filter handler returns, internally mod_perl will take care of
568 creating and sending the EOS bucket to the upstream input filter.
569 A similar logic may apply for output filters.
571 In most other cases you shouldn't set this flag. When this flag is
573 prematurely set (before the real EOS bucket has arrived) in the current
574 filter invocation, instead of invoking the filter again, mod_perl will
575 create and send the EOS bucket to the next filter, ignoring any other
576 bucket brigades that may have left to consume. As mentioned earlier
577 this special behavior is useful in writing special tests that test
578 abnormal situations.
579
581 Other methods which affect filters, but called on non-"Apache2::Filter"
582 objects:
583 "add_input_filter"
585 Add &callback filter handler to input request filter chain.
587 $r->add_input_filter(\&callback);
589 Add &callback filter handler to input connection filter chain.
591 $c->add_input_filter(\&callback);
593 obj: $c ( "Apache2::Connection object" ) or $r ( "Apache2::RequestRec
595 object" )
596 arg1: &callback (CODE ref)
597 ret: no return value
598 since: 2.0.00
599 [META: It seems that you can't add a filter when another filter is
601 called. I've tried to add an output connection filter from the input
602 connection filter when it was called for the first time. It didn't have
603 any affect for the first request (over keepalive connection). The only
604 way I succeeded to do that is from that input connection filter's fil‐
605 ter_init handler. In fact it does work if there is any filter addi‐
606 tional filter of the same kind configured from httpd.conf or via fil‐
607 ter_init. It looks like there is a bug in httpd, where it doesn't pre‐
608 pare the chain of 3rd party filter if none were inserted before the
609 first filter was called.]
610 "add_output_filter"
612 Add &callback filter handler to output request filter chain.
614 $r->add_output_filter(\&callback);
616 Add &callback filter handler to output connection filter chain.
618 $c->add_output_filter(\&callback);
620 obj: $c ( "Apache2::Connection object" ) or $r ( "Apache2::RequestRec
622 object" )
623 arg1: &callback (CODE ref)
624 ret: no return value
625 since: 2.0.00
626
628 Packages using filter attributes have to subclass "Apache2::Filter":
629 package MyApache2::FilterCool;
631 use base qw(Apache2::Filter);
632 Attributes are parsed during the code compilation, by the function
634 "MODIFY_CODE_ATTRIBUTES", inherited from the "Apache2::Filter" package.
635 "FilterRequestHandler"
637 The "FilterRequestHandler" attribute tells mod_perl to insert the fil‐
639 ter into an HTTP request filter chain.
640 For example, to configure an output request filter handler, use the
642 "FilterRequestHandler" attribute in the handler subroutine's declara‐
643 tion:
644 package MyApache2::FilterOutputReq;
646 sub handler : FilterRequestHandler { ... }
647 and add the configuration entry:
649 PerlOutputFilterHandler MyApache2::FilterOutputReq
651 This is the default mode. So if you are writing an HTTP request filter,
653 you don't have to specify this attribute.
654 The section HTTP Request vs. Connection Filters delves into more
656 details.
657 "FilterConnectionHandler"
659 The "FilterConnectionHandler" attribute tells mod_perl to insert this
661 filter into a connection filter chain.
662 For example, to configure an output connection filter handler, use the
664 "FilterConnectionHandler" attribute in the handler subroutine's decla‐
665 ration:
666 package MyApache2::FilterOutputCon;
668 sub handler : FilterConnectionHandler { ... }
669 and add the configuration entry:
671 PerlOutputFilterHandler MyApache2::FilterOutputCon
673 The section HTTP Request vs. Connection Filters delves into more
675 details.
676 "FilterInitHandler"
678 The attribute "FilterInitHandler" marks the function suitable to be
680 used as a filter initialization callback, which is called immediately
681 after a filter is inserted to the filter chain and before it's actually
682 called.
683 sub init : FilterInitHandler {
685 my $f = shift;
686 #...
687 return Apache2::Const::OK;
688 }
689 In order to hook this filter callback, the real filter has to assign
691 this callback using the "FilterHasInitHandler" which accepts a refer‐
692 ence to the callback function.
693 For further discussion and examples refer to the Filter Initialization
695 Phase tutorial section.
696 "FilterHasInitHandler"
698 If a filter wants to run an initialization callback it can register
700 such using the "FilterHasInitHandler" attribute. Similar to "push_han‐
701 dlers" the callback reference is expected, rather than a callback name.
702 The used callback function has to have the "FilterInitHandler"
703 attribute. For example:
704 package MyApache2::FilterBar;
706 use base qw(Apache2::Filter);
707 sub init : FilterInitHandler { ... }
708 sub filter : FilterRequestHandler FilterHasInitHandler(\&init) {
709 my ($f, $bb) = @_;
710 # ...
711 return Apache2::Const::OK;
712 }
713 For further discussion and examples refer to the Filter Initialization
715 Phase tutorial section.
716
718 mod_perl 2.0 filters configuration is explained in the filter handlers
719 tutorial.
720 "PerlInputFilterHandler"
722 See "PerlInputFilterHandler".
724 "PerlOutputFilterHandler"
726 See "PerlOutputFilterHandler".
728 "PerlSetInputFilter"
730 See "PerlSetInputFilter".
732 "PerlSetOutputFilter"
734 See "PerlSetInputFilter".
736
738 "Apache2::Filter" also implements a tied interface, so you can work
739 with the $f object as a hash reference.
740 The TIE interface is mostly unimplemented and might be implemented post
742 2.0 release.
743 "TIEHANDLE"
745 $ret = TIEHANDLE($stashsv, $sv);
747 obj: $stashsv ( SCALAR )
749 arg1: $sv ( SCALAR )
750 ret: $ret ( SCALAR )
751 since: subject to change
752 "PRINT"
754 $ret = PRINT(...);
756 obj: "..." (XXX)
758 ret: $ret ( integer )
759 since: subject to change
760
762 mod_perl 2.0 documentation.
763
765 mod_perl 2.0 and its core modules are copyrighted under The Apache
766 Software License, Version 2.0.
767
769 The mod_perl development team and numerous contributors.
770perl v5.8.8 2006-11-19 docs::api::Apache2::Filter(3)