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
45 tutorial|docs::2.0::user::handlers::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
52 filter:
53 $c = $f->c;
55 obj: $f ( "Apache2::Filter object" )
57 ret: $c ( "Apache2::Connection object" )
58 since: 2.0.00
59 "ctx"
61 Get/set the filter context data.
62 $ctx = $f->ctx;
64 $f->ctx($ctx);
65 obj: $f ( "Apache2::Filter object" )
67 opt arg2: $ctx ( SCALAR )
68 next context
69 ret: $ctx ( SCALAR )
71 current context
72 since: 2.0.00
74 A filter context is created before the filter is called for the first
76 time and it's destroyed at the end of the request. The context is
77 preserved between filter invocations of the same request. So if a
78 filter needs to store some data between invocations it should use the
79 filter context for that. The filter context is initialized with the
80 "undef" value.
81 The "ctx" method accepts a single SCALAR argument. Therefore if you
83 want to store any other perl datastructure you should use a reference
84 to it.
85 For example you can store a hash reference:
87 $f->ctx({ foo => 'bar' });
89 and then access it:
91 $foo = $f->ctx->{foo};
93 if you access the context more than once it's more efficient to copy
95 it's value before using it:
96 my $ctx = $f->ctx;
98 $foo = $ctx->{foo};
99 to avoid redundant method calls. As of this writing $ctx is not a tied
101 variable, so if you modify it need to store it at the end:
102 $f->ctx($ctx);
104 META: later we might make it a TIEd-variable interface, so it'll be
106 stored automatically.
107 Besides its primary purpose of storing context data across multiple
109 filter invocations, this method is also useful when used as a flag. For
110 example here is how to ensure that something happens only once during
111 the filter's life:
112 unless ($f->ctx) {
114 do_something_once();
115 $f->ctx(1);
116 }
117 "frec"
119 Get/set the "Apache2::FilterRec" (filter record) object.
120 $frec = $f->frec();
122 obj: $f ( "Apache2::Filter object" )
124 ret: $frec ( "Apache2::FilterRec object" )
125 since: 2.0.00
126 For example you can call "$frec->name" to get filter's name.
128 "next"
130 Return the "Apache2::Filter" object of the next filter in chain.
131 $next_f = $f->next;
133 obj: $f ( "Apache2::Filter object" )
135 The current filter object
136 ret: $next_f ( "Apache2::Filter object" )
138 The next filter object in chain
139 since: 2.0.00
141 Since Apache inserts several core filters at the end of each chain,
143 normally this method always returns an object. However if it's not a
144 mod_perl filter handler, you can call only the following methods on it:
145 "get_brigade", "pass_brigade", "c", "r", "frec" and "next". If you call
146 other methods the behavior is undefined.
147 The next filter can be a mod_perl one or not, it's easy to tell which
149 one is that by calling "$f->frec->name".
150 "r"
152 Inside an HTTP request filter retrieve the current request object:
153 $r = $f->r;
155 obj: $f ( "Apache2::Filter object" )
157 ret: $r ( "Apache2::RequestRec object" )
158 since: 2.0.00
159 If a sub-request adds filters, then that sub-request object is
161 associated with the filter.
162 "remove"
164 Remove the current filter from the filter chain (for the current
165 request or connection).
166 $f->remove;
168 obj: $f ( "Apache2::Filter object" )
170 ret: no return value
171 since: 2.0.00
172 Notice that you should either complete the current filter invocation
174 normally (by calling "get_brigade" or "pass_brigade" depending on the
175 filter kind) or if nothing was done, return "Apache2::Const::DECLINED"
176 and mod_perl will take care of passing the current bucket brigade
177 through unmodified to the next filter in chain.
178 Note: calling remove() on the very top connection filter doesn't affect
180 the filter chain due to a bug in Apache 2.0 (which may be fixed in
181 2.1). So don't use it with connection filters, till it gets fixed in
182 Apache and then make sure to require the minimum Apache version if you
183 rely on.
184 Remember that if the connection is "$c->keepalive" ) and the connection
186 filter is removed, it won't be added until the connection is closed.
187 Which may happen after many HTTP requests. You may want to keep the
188 filter in place and pass the data through unmodified, by returning
189 "Apache2::Const::DECLINED". If you need to reset the whole or parts of
190 the filter context between requests, use the technique based on
191 "$c->keepalives" counting.
192 This method works for native Apache (non-mod_perl) filters too.
194
196 The following methods can be called from any filter, directly
197 manipulating bucket brigades:
198 "fflush"
200 Flush a bucket brigade down the filter stack.
201 $rc = $f->fflush($bb);
203 obj: $f ( "Apache2::Filter object" )
205 The current filter
206 arg1: $bb ( "Apache2::Brigade object" )
208 The brigade to flush
209 ret: $rc ( "APR::Const status constant" )
211 Refer to the "pass_brigade()" entry.
212 excpt: "APR::Error"
214 Exceptions are thrown only when this function is called in the VOID
215 context. Refer to the "get_brigade()" entry for details.
216 since: 2.0.00
218 "fflush" is a shortcut method. So instead of doing:
220 my $b = APR::Bucket::flush_create($f->c->bucket_alloc);
222 $bb->insert_tail($b);
223 $f->pass_brigade($bb);
224 one can just write:
226 $f->fflush($bb);
228 "get_brigade"
230 This is a method to use in bucket brigade input filters. It acquires a
231 bucket brigade from the upstream input filter.
232 $rc = $next_f->get_brigade($bb, $mode, $block, $readbytes);
234 $rc = $next_f->get_brigade($bb, $mode, $block);
235 $rc = $next_f->get_brigade($bb, $mode)
236 $rc = $next_f->get_brigade($bb);
237 obj: $next_f ( "Apache2::Filter object" )
239 The next filter in the filter chain.
240 Inside filter handlers it's usually "$f->next". Inside protocol
242 handlers: "$c->input_filters".
243 arg1: $bb ( "APR::Brigade object" )
245 The original bucket brigade passed to "get_brigade()", which must
246 be empty.
247 Inside input filter handlers it's usually the second argument to
249 the filter handler.
250 Otherwise it should be created:
252 my $bb = APR::Brigade->new($c->pool, $c->bucket_alloc);
254 On return it gets populated with the next bucket brigade. That
256 brigade may contain nothing if there was no more data to read. The
257 return status tells the outcome.
258 opt arg2: $mode ( "Apache2::Const :input_mode constant" )
260 The filter mode in which the data should be read.
261 If inside the filter handler, you should normally pass the same
263 mode that was passed to the filter handler (the third argument).
264 At the end of this section the available modes are presented.
266 If the argument $mode is not passed,
268 "Apache2::Const::MODE_READBYTES" is used as a default value.
269 opt arg3: $block ( "APR::Const :read_type constant" )
271 You may ask the reading operation to be blocking:
272 "APR::Const::BLOCK_READ", or nonblocking:
273 "APR::Const::NONBLOCK_READ".
274 If inside the filter handler, you should normally pass the same
276 blocking mode argument that was passed to the filter handler (the
277 forth argument).
278 If the argument $block is not passed, "APR::Const::BLOCK_READ" is
280 used as a default value.
281 opt arg4: $readbytes ( integer )
283 How many bytes to read from the next filter.
284 If inside the filter handler, you may want the same number of
286 bytes, as the upstream filter, i.e. the argument that was passed to
287 the filter handler (the fifth argument).
288 If the argument $block is not passed, 8192 is used as a default
290 value.
291 ret: $rc ( "APR::Const status constant" )
293 On success, "APR::Const::SUCCESS" is returned and $bb is populated
294 (see the $bb entry).
295 In case of a failure -- a failure code is returned, in which case
297 normally it should be returned to the caller.
298 If the bottom-most filter doesn't read from the network, then
300 "Apache2::NOBODY_READ" is returned (META: need to add this
301 constant).
302 Inside protocol handlers the return code can also be
304 "APR::Const::EOF", which is success as well.
305 excpt: "APR::Error"
307 You don't have to ask for the return value. If this function is
308 called in the VOID context, e.g.:
309 $f->next->get_brigade($bb, $mode, $block, $readbytes);
311 mod_perl will do the error checking on your behalf, and if the
313 return code is not "APR::Const::SUCCESS", an "APR::Error exception"
314 will be thrown. The only time you want to do the error checking
315 yourself, is when return codes besides "APR::Const::SUCCESS" are
316 considered as successful and you want to manage them by yourself.
317 since: 2.0.00
319 Available input filter modes (the optional second argument $mode) are:
321 · "Apache2::Const::MODE_READBYTES"
323 The filter should return at most readbytes data
325 · "Apache2::Const::MODE_GETLINE"
327 The filter should return at most one line of CRLF data. (If a
329 potential line is too long or no CRLF is found, the filter may
330 return partial data).
331 · "Apache2::Const::MODE_EATCRLF"
333 The filter should implicitly eat any CRLF pairs that it sees.
335 · "Apache2::Const::MODE_SPECULATIVE"
337 The filter read should be treated as speculative and any returned
339 data should be stored for later retrieval in another mode.
340 · "Apache2::Const::MODE_EXHAUSTIVE"
342 The filter read should be exhaustive and read until it can not read
344 any more. Use this mode with extreme caution.
345 · "Apache2::Const::MODE_INIT"
347 The filter should initialize the connection if needed, NNTP or FTP
349 over SSL for example.
350 Either compile all these constants with:
352 use Apache2::Const -compile => qw(:input_mode);
354 But it's a bit more efficient to compile only those constants that you
356 need.
357 Example:
359 Here is a fragment of a filter handler, that receives a bucket brigade
361 from the upstream filter:
362 use Apache2::Filter ();
364 use APR::Const -compile => qw(SUCCESS);
365 use Apache2::Const -compile => qw(OK);
366 sub filter {
367 my ($f, $bb, $mode, $block, $readbytes) = @_;
368 my $rc = $f->next->get_brigade($bb, $mode, $block, $readbytes);
370 return $rc unless $rc == APR::Const::SUCCESS;
371 # ... process $bb
373 return Apache2::Const::OK;
375 }
376 Usually arguments $mode, $block, $readbytes are the same as passed to
378 the filter itself.
379 You can see that in case of a failure, the handler returns immediately
381 with that failure code, which gets propagated to the downstream filter.
382 If you decide not check the return code, you can write it as:
384 sub filter {
386 my ($f, $bb, $mode, $block, $readbytes) = @_;
387 $f->next->get_brigade($bb, $mode, $block, $readbytes);
389 # ... process $bb
391 return Apache2::Const::OK;
393 }
394 and the error checking will be done on your behalf.
396 You will find many more examples in "the filter
398 handlers|docs::2.0::user::handlers::filters" and "the protocol
399 handlers|docs::2.0::user::handlers::protocols" tutorials.
400 "pass_brigade"
402 This is a method to use in bucket brigade output filters. It passes
403 the current bucket brigade to the downstream output filter.
404 $rc = $next_f->pass_brigade($bb);
406 obj: $next_f ( "Apache2::Filter object" )
408 The next filter in the filter chain.
409 Inside output filter handlers it's usually "$f->next". Inside
411 protocol handlers: "$c->output_filters".
412 arg1: $bb ( "APR::Brigade object" )
414 The bucket brigade to pass.
415 Inside output filter handlers it's usually the second argument to
417 the filter handler (after potential manipulations).
418 ret: $rc ( "APR::Const status constant" )
420 On success, "APR::Const::SUCCESS" is returned.
421 In case of a failure -- a failure code is returned, in which case
423 normally it should be returned to the caller.
424 If the bottom-most filter doesn't write to the network, then
426 "Apache2::NOBODY_WROTE" is returned (META: need to add this
427 constant).
428 Also refer to the "get_brigade()" entry to see how to avoid
430 checking the errors explicitly.
431 excpt: "APR::Error"
433 Exceptions are thrown only when this function is called in the VOID
434 context. Refer to the "get_brigade()" entry for details.
435 since: 2.0.00
437 The caller relinquishes ownership of the brigade (i.e. it may get
439 destroyed/overwritten/etc. by the callee).
440 Example:
442 Here is a fragment of a filter handler, that passes a bucket brigade to
444 the downstream filter (after some potential processing of the buckets
445 in the bucket brigade):
446 use Apache2::Filter ();
448 use APR::Const -compile => qw(SUCCESS);
449 use Apache2::Const -compile => qw(OK);
450 sub filter {
451 my ($f, $bb) = @_;
452 # ... process $bb
454 my $rc = $f->next->pass_brigade($bb);
456 return $rc unless $rc == APR::Const::SUCCESS;
457 return Apache2::Const::OK;
459 }
460
462 The following methods can be called from any filter, which uses the
463 simplified streaming functionality:
464 "print"
466 Send the contents of $buffer to the next filter in chain (via internal
467 buffer).
468 $sent = $f->print($buffer);
470 obj: $f ( "Apache2::Filter object" )
472 arg1: $buffer ( string )
473 The data to send.
474 ret: $sent ( integer )
476 How many characters were sent. There is no need to check, since all
477 should go through and if something goes work an exception will be
478 thrown.
479 excpt: "APR::Error"
481 since: 2.0.00
482 This method should be used only in streaming filters.
484 "read"
486 Read data from the filter
487 $read = $f->read($buffer, $wanted);
489 obj: $f ( "Apache2::Filter object" )
491 arg1: $buffer ( SCALAR )
492 The buffer to fill. All previous data will be lost.
493 opt arg2: $wanted ( integer )
495 How many bytes to attempt to read.
496 If this optional argument is not specified -- the default 8192 will
498 be used.
499 ret: $read ( integer )
501 How many bytes were actually read.
502 $buffer gets populated with the string that is read. It will
504 contain an empty string if there was nothing to read.
505 excpt: "APR::Error"
507 since: 2.0.00
508 Reads at most $wanted characters into $buffer. The returned value $read
510 tells exactly how many were read, making it easy to use it in a while
511 loop:
512 while ($filter->read(my $buffer, $wanted)) {
514 # transform $buffer here
515 $filter->print($buffer);
516 }
517 This is a streaming filter method, which acquires a single bucket
519 brigade behind the scenes and reads data from all its buckets.
520 Therefore it can only read from one bucket brigade per filter
521 invocation.
522 If the EOS bucket is read, the "seen_eos" method will return a true
524 value.
525 "seen_eos"
527 This methods returns a true value when the EOS bucket is seen by the
528 "read" method.
529 $ok = $f->seen_eos;
531 obj: $f ( "Apache2::Filter object" )
533 The filter to remove
534 ret: $ok ( boolean )
536 a true value if EOS has been seen, otherwise a false value
537 since: 2.0.00
539 This method only works in streaming filters which exhaustively
541 "$f->read" all the incoming data in a while loop, like so:
542 while ($f->read(my $buffer, $wanted)) {
544 # do something with $buffer
545 }
546 if ($f->seen_eos) {
547 # do something
548 }
549 The technique in this example is useful when a streaming filter wants
551 to append something to the very end of data, or do something at the end
552 of the last filter invocation. After the EOS bucket is read, the filter
553 should expect not to be invoked again.
554 If an input streaming filter doesn't consume all data in the bucket
556 brigade (or even in several bucket brigades), it has to generate the
557 EOS event by itself. So when the filter is done it has to set the EOS
558 flag:
559 $f->seen_eos(1);
561 when the filter handler returns, internally mod_perl will take care of
563 creating and sending the EOS bucket to the upstream input filter.
564 A similar logic may apply for output filters.
566 In most other cases you shouldn't set this flag. When this flag is
568 prematurely set (before the real EOS bucket has arrived) in the current
569 filter invocation, instead of invoking the filter again, mod_perl will
570 create and send the EOS bucket to the next filter, ignoring any other
571 bucket brigades that may have left to consume. As mentioned earlier
572 this special behavior is useful in writing special tests that test
573 abnormal situations.
574
576 Other methods which affect filters, but called on non-"Apache2::Filter"
577 objects:
578 "add_input_filter"
580 Add &callback filter handler to input request filter chain.
581 $r->add_input_filter(\&callback);
583 Add &callback filter handler to input connection filter chain.
585 $c->add_input_filter(\&callback);
587 obj: $c ( "Apache2::Connection object" ) or $r ( "Apache2::RequestRec
589 object" )
590 arg1: &callback (CODE ref)
591 ret: no return value
592 since: 2.0.00
593 [META: It seems that you can't add a filter when another filter is
595 called. I've tried to add an output connection filter from the input
596 connection filter when it was called for the first time. It didn't have
597 any affect for the first request (over keepalive connection). The only
598 way I succeeded to do that is from that input connection filter's
599 filter_init handler. In fact it does work if there is any filter
600 additional filter of the same kind configured from httpd.conf or via
601 filter_init. It looks like there is a bug in httpd, where it doesn't
602 prepare the chain of 3rd party filter if none were inserted before the
603 first filter was called.]
604 "add_output_filter"
606 Add &callback filter handler to output request filter chain.
607 $r->add_output_filter(\&callback);
609 Add &callback filter handler to output connection filter chain.
611 $c->add_output_filter(\&callback);
613 obj: $c ( "Apache2::Connection object" ) or $r ( "Apache2::RequestRec
615 object" )
616 arg1: &callback (CODE ref)
617 ret: no return value
618 since: 2.0.00
619
621 Packages using filter attributes have to subclass "Apache2::Filter":
622 package MyApache2::FilterCool;
624 use base qw(Apache2::Filter);
625 Attributes are parsed during the code compilation, by the function
627 "MODIFY_CODE_ATTRIBUTES", inherited from the "Apache2::Filter" package.
628 "FilterRequestHandler"
630 The "FilterRequestHandler" attribute tells mod_perl to insert the
631 filter into an HTTP request filter chain.
632 For example, to configure an output request filter handler, use the
634 "FilterRequestHandler" attribute in the handler subroutine's
635 declaration:
636 package MyApache2::FilterOutputReq;
638 sub handler : FilterRequestHandler { ... }
639 and add the configuration entry:
641 PerlOutputFilterHandler MyApache2::FilterOutputReq
643 This is the default mode. So if you are writing an HTTP request filter,
645 you don't have to specify this attribute.
646 The section HTTP Request vs. Connection Filters delves into more
648 details.
649 "FilterConnectionHandler"
651 The "FilterConnectionHandler" attribute tells mod_perl to insert this
652 filter into a connection filter chain.
653 For example, to configure an output connection filter handler, use the
655 "FilterConnectionHandler" attribute in the handler subroutine's
656 declaration:
657 package MyApache2::FilterOutputCon;
659 sub handler : FilterConnectionHandler { ... }
660 and add the configuration entry:
662 PerlOutputFilterHandler MyApache2::FilterOutputCon
664 The section HTTP Request vs. Connection Filters delves into more
666 details.
667 "FilterInitHandler"
669 The attribute "FilterInitHandler" marks the function suitable to be
670 used as a filter initialization callback, which is called immediately
671 after a filter is inserted to the filter chain and before it's actually
672 called.
673 sub init : FilterInitHandler {
675 my $f = shift;
676 #...
677 return Apache2::Const::OK;
678 }
679 In order to hook this filter callback, the real filter has to assign
681 this callback using the "FilterHasInitHandler" which accepts a
682 reference to the callback function.
683 For further discussion and examples refer to the Filter Initialization
685 Phase tutorial section.
686 "FilterHasInitHandler"
688 If a filter wants to run an initialization callback it can register
689 such using the "FilterHasInitHandler" attribute. Similar to
690 "push_handlers" the callback reference is expected, rather than a
691 callback name. The used callback function has to have the
692 "FilterInitHandler" attribute. For example:
693 package MyApache2::FilterBar;
695 use base qw(Apache2::Filter);
696 sub init : FilterInitHandler { ... }
697 sub filter : FilterRequestHandler FilterHasInitHandler(\&init) {
698 my ($f, $bb) = @_;
699 # ...
700 return Apache2::Const::OK;
701 }
702 For further discussion and examples refer to the Filter Initialization
704 Phase tutorial section.
705
707 mod_perl 2.0 filters configuration is explained in the filter handlers
708 tutorial.
709 "PerlInputFilterHandler"
711 See "PerlInputFilterHandler".
712 "PerlOutputFilterHandler"
714 See "PerlOutputFilterHandler".
715 "PerlSetInputFilter"
717 See "PerlSetInputFilter".
718 "PerlSetOutputFilter"
720 See "PerlSetInputFilter".
721
723 "Apache2::Filter" also implements a tied interface, so you can work
724 with the $f object as a hash reference.
725 The TIE interface is mostly unimplemented and might be implemented post
727 2.0 release.
728 "TIEHANDLE"
730 $ret = TIEHANDLE($stashsv, $sv);
731 obj: $stashsv ( SCALAR )
733 arg1: $sv ( SCALAR )
734 ret: $ret ( SCALAR )
735 since: subject to change
736 "PRINT"
738 $ret = PRINT(...);
739 obj: "..." (XXX)
741 ret: $ret ( integer )
742 since: subject to change
743
745 mod_perl 2.0 documentation.
746
748 mod_perl 2.0 and its core modules are copyrighted under The Apache
749 Software License, Version 2.0.
750
752 The mod_perl development team and numerous contributors.
753perl v5.12.0 2008-04-17 docs::api::Apache2::Filter(3)