apache2::filter.3

视频监控网络部分的协议ddns,的模块的实现代码,请大家大胆指正.

.PP
This method should be used only in streaming
filters.
.ie n .Sh """read"""
.el .Sh "\f(CWread\fP"
.IX Subsection "read"
Read data from the filter
.PP
.Vb 1
\&  $read = $f\->read($buffer, $wanted);
.Ve
.ie n .IP "obj: $f\fR ( \f(CW""Apache2::Filter object"" )" 4
.el .IP "obj: \f(CW$f\fR ( \f(CWApache2::Filter object\fR )" 4
.IX Item "obj: $f ( Apache2::Filter object )"
.PD 0
.ie n .IP "arg1: $buffer ( \s-1SCALAR\s0 )" 4
.el .IP "arg1: \f(CW$buffer\fR ( \s-1SCALAR\s0 )" 4
.IX Item "arg1: $buffer ( SCALAR )"
.PD
The buffer to fill. All previous data will be lost.
.ie n .IP "opt arg2: $wanted ( integer )" 4
.el .IP "opt arg2: \f(CW$wanted\fR ( integer )" 4
.IX Item "opt arg2: $wanted ( integer )"
How many bytes to attempt to read.
.Sp
If this optional argument is not specified \*(-- the default 8192 will be
used.
.ie n .IP "ret: $read ( integer )" 4
.el .IP "ret: \f(CW$read\fR ( integer )" 4
.IX Item "ret: $read ( integer )"
How many bytes were actually read.
.Sp
\&\f(CW$buffer\fR gets populated with the string that is read. It will
contain an empty string if there was nothing to read.
.ie n .IP "excpt: ""APR::Error""" 4
.el .IP "excpt: \f(CWAPR::Error\fR" 4
.IX Item "excpt: APR::Error"
.PD 0
.IP "since: 2.0.00" 4
.IX Item "since: 2.0.00"
.PD
.PP
Reads at most \f(CW$wanted\fR characters into \f(CW$buffer\fR. The returned
value \f(CW$read\fR tells exactly how many were read, making it easy to use
it in a while loop:
.PP
.Vb 4
\&  while ($filter\->read(my $buffer, $wanted)) {
\&      # transform $buffer here
\&      $filter\->print($buffer);
\&  }
.Ve
.PP
This is a streaming filter method, which acquires a single bucket
brigade behind the scenes and reads data from all its
buckets. Therefore it can only read from one bucket brigade per filter
invocation.
.PP
If the \s-1EOS\s0 bucket is read, the \f(CW\*(C`seen_eos\*(C'\fR method will
return a true value.
.ie n .Sh """seen_eos"""
.el .Sh "\f(CWseen_eos\fP"
.IX Subsection "seen_eos"
This methods returns a true value when the \s-1EOS\s0 bucket is seen by the
\&\f(CW\*(C`read\*(C'\fR method.
.PP
.Vb 1
\&  $ok = $f\->seen_eos;
.Ve
.ie n .IP "obj: $f\fR ( \f(CW""Apache2::Filter object"" )" 4
.el .IP "obj: \f(CW$f\fR ( \f(CWApache2::Filter object\fR )" 4
.IX Item "obj: $f ( Apache2::Filter object )"
The filter to remove
.ie n .IP "ret: $ok ( boolean )" 4
.el .IP "ret: \f(CW$ok\fR ( boolean )" 4
.IX Item "ret: $ok ( boolean )"
a true value if \s-1EOS\s0 has been seen, otherwise a false value
.IP "since: 2.0.00" 4
.IX Item "since: 2.0.00"
.PP
This method only works in streaming filters which exhaustively
\&\f(CW\*(C`$f\->read\*(C'\fR all the incoming data in a while loop,
like so:
.PP
.Vb 6
\&      while ($f\->read(my $buffer, $wanted)) {
\&          # do something with $buffer
\&      }
\&      if ($f\->seen_eos) {
\&          # do something
\&      }
.Ve
.PP
The technique in this example is useful when a streaming filter wants
to append something to the very end of data, or do something at the
end of the last filter invocation. After the \s-1EOS\s0 bucket is read, the
filter should expect not to be invoked again.
.PP
If an input streaming filter doesn't consume all data in the bucket
brigade (or even in several bucket brigades), it has to generate the
\&\s-1EOS\s0 event by itself. So when the filter is done it has to set the \s-1EOS\s0
flag:
.PP
.Vb 1
\&  $f\->seen_eos(1);
.Ve
.PP
when the filter handler returns, internally mod_perl will take care of
creating and sending the \s-1EOS\s0 bucket to the upstream input filter.
.PP
A similar logic may apply for output filters.
.PP
In most other cases you shouldn't set this flag.  When this flag is
prematurely set (before the real \s-1EOS\s0 bucket has arrived) in the
current filter invocation, instead of invoking the filter again,
mod_perl will create and send the \s-1EOS\s0 bucket to the next filter,
ignoring any other bucket brigades that may have left to consume. As
mentioned earlier this special behavior is useful in writing special
tests that test abnormal situations.
.SH "Other Filter-related API"
.IX Header "Other Filter-related API"
Other methods which affect filters, but called on
non\-\f(CW\*(C`Apache2::Filter\*(C'\fR objects:
.ie n .Sh """add_input_filter"""
.el .Sh "\f(CWadd_input_filter\fP"
.IX Subsection "add_input_filter"
Add \f(CW&callback\fR filter handler to input request filter chain.
.PP
.Vb 1
\&  $r\->add_input_filter(\e&callback);
.Ve
.PP
Add \f(CW&callback\fR filter handler to input connection filter chain.
.PP
.Vb 1
\&  $c\->add_input_filter(\e&callback);
.Ve
.ie n .IP "obj: $c\fR ( \f(CW""Apache2::Connection object""\fR ) or \f(CW$r\fR ( \f(CW""Apache2::RequestRec object"" )" 4
.el .IP "obj: \f(CW$c\fR ( \f(CWApache2::Connection object\fR ) or \f(CW$r\fR ( \f(CWApache2::RequestRec object\fR )" 4
.IX Item "obj: $c ( Apache2::Connection object ) or $r ( Apache2::RequestRec object )"
.PD 0
.ie n .IP "arg1: &callback (\s-1CODE\s0 ref)" 4
.el .IP "arg1: \f(CW&callback\fR (\s-1CODE\s0 ref)" 4
.IX Item "arg1: &callback (CODE ref)"
.IP "ret: no return value" 4
.IX Item "ret: no return value"
.IP "since: 2.0.00" 4
.IX Item "since: 2.0.00"
.PD
.PP
[\s-1META:\s0 It seems that you can't add a filter when another filter is
called. I've tried to add an output connection filter from the input
connection filter when it was called for the first time. It didn't
have any affect for the first request (over keepalive connection). The
only way I succeeded to do that is from that input connection filter's
filter_init handler.
In fact it does work if there is any filter additional filter of the
same kind configured from httpd.conf or via filter_init. It looks like
there is a bug in httpd, where it doesn't prepare the chain of 3rd
party filter if none were inserted before the first filter was called.]
.ie n .Sh """add_output_filter"""
.el .Sh "\f(CWadd_output_filter\fP"
.IX Subsection "add_output_filter"
Add \f(CW&callback\fR filter handler to output request filter chain.
.PP
.Vb 1
\&  $r\->add_output_filter(\e&callback);
.Ve
.PP
Add \f(CW&callback\fR filter handler to output connection filter chain.
.PP
.Vb 1
\&  $c\->add_output_filter(\e&callback);
.Ve
.ie n .IP "obj: $c\fR ( \f(CW""Apache2::Connection object""\fR ) or \f(CW$r\fR ( \f(CW""Apache2::RequestRec object"" )" 4
.el .IP "obj: \f(CW$c\fR ( \f(CWApache2::Connection object\fR ) or \f(CW$r\fR ( \f(CWApache2::RequestRec object\fR )" 4
.IX Item "obj: $c ( Apache2::Connection object ) or $r ( Apache2::RequestRec object )"
.PD 0
.ie n .IP "arg1: &callback (\s-1CODE\s0 ref)" 4
.el .IP "arg1: \f(CW&callback\fR (\s-1CODE\s0 ref)" 4
.IX Item "arg1: &callback (CODE ref)"
.IP "ret: no return value" 4
.IX Item "ret: no return value"
.IP "since: 2.0.00" 4
.IX Item "since: 2.0.00"
.PD
.SH "Filter Handler Attributes"
.IX Header "Filter Handler Attributes"
Packages using filter attributes have to subclass \f(CW\*(C`Apache2::Filter\*(C'\fR:
.PP
.Vb 2
\&  package MyApache2::FilterCool;
\&  use base qw(Apache2::Filter);
.Ve
.PP
Attributes are parsed during the code compilation, by the function
\&\f(CW\*(C`MODIFY_CODE_ATTRIBUTES\*(C'\fR, inherited from the \f(CW\*(C`Apache2::Filter\*(C'\fR
package.
.ie n .Sh """FilterRequestHandler"""
.el .Sh "\f(CWFilterRequestHandler\fP"
.IX Subsection "FilterRequestHandler"
The \f(CW\*(C`FilterRequestHandler\*(C'\fR attribute tells mod_perl to insert the
filter into an \s-1HTTP\s0 request filter chain.
.PP
For example, to configure an output request filter handler, use the
\&\f(CW\*(C`FilterRequestHandler\*(C'\fR attribute in the handler subroutine's
declaration:
.PP
.Vb 2
\&  package MyApache2::FilterOutputReq;
\&  sub handler : FilterRequestHandler { ... }
.Ve
.PP
and add the configuration entry:
.PP
.Vb 1
\&  PerlOutputFilterHandler MyApache2::FilterOutputReq
.Ve
.PP
This is the default mode. So if you are writing an \s-1HTTP\s0 request
filter, you don't have to specify this attribute.
.PP
The section \s-1HTTP\s0 Request vs. Connection
Filters
delves into more details.
.ie n .Sh """FilterConnectionHandler"""
.el .Sh "\f(CWFilterConnectionHandler\fP"
.IX Subsection "FilterConnectionHandler"
The \f(CW\*(C`FilterConnectionHandler\*(C'\fR attribute tells mod_perl to insert this
filter into a connection filter chain.
.PP
For example, to configure an output connection filter handler, use the
\&\f(CW\*(C`FilterConnectionHandler\*(C'\fR attribute in the handler subroutine's
declaration:
.PP
.Vb 2
\&  package MyApache2::FilterOutputCon;
\&  sub handler : FilterConnectionHandler { ... }
.Ve
.PP
and add the configuration entry:
.PP
.Vb 1
\&  PerlOutputFilterHandler MyApache2::FilterOutputCon
.Ve
.PP
The section \s-1HTTP\s0 Request vs. Connection
Filters
delves into more details.
.ie n .Sh """FilterInitHandler"""
.el .Sh "\f(CWFilterInitHandler\fP"
.IX Subsection "FilterInitHandler"
The attribute \f(CW\*(C`FilterInitHandler\*(C'\fR marks the function suitable to be
used as a filter initialization callback, which is called immediately
after a filter is inserted to the filter chain and before it's
actually called.
.PP
.Vb 5
\&  sub init : FilterInitHandler {
\&      my $f = shift;
\&      #...
\&      return Apache2::Const::OK;
\&  }
.Ve
.PP
In order to hook this filter callback, the real filter has to assign
this callback using the
\&\f(CW\*(C`FilterHasInitHandler\*(C'\fR which accepts a
reference to the callback function.
.PP
For further discussion and examples refer to the Filter
Initialization
Phase
tutorial section.
.ie n .Sh """FilterHasInitHandler"""
.el .Sh "\f(CWFilterHasInitHandler\fP"
.IX Subsection "FilterHasInitHandler"
If a filter wants to run an initialization callback it can register
such using the \f(CW\*(C`FilterHasInitHandler\*(C'\fR attribute. Similar to
\&\f(CW\*(C`push_handlers\*(C'\fR the callback reference is expected, rather than a
callback name. The used callback function has to have the
\&\f(CW\*(C`FilterInitHandler\*(C'\fR attribute. For example:
.PP
.Vb 8
\&  package MyApache2::FilterBar;
\&  use base qw(Apache2::Filter);
\&  sub init   : FilterInitHandler { ... }
\&  sub filter : FilterRequestHandler FilterHasInitHandler(\e&init) {
\&      my ($f, $bb) = @_;
\&      # ...
\&      return Apache2::Const::OK;
\&  }
.Ve
.PP
For further discussion and examples refer to the Filter
Initialization
Phase
tutorial section.
.SH "Configuration"
.IX Header "Configuration"
mod_perl 2.0 filters configuration is explained in the filter
handlers
tutorial.
.ie n .Sh """PerlInputFilterHandler"""
.el .Sh "\f(CWPerlInputFilterHandler\fP"
.IX Subsection "PerlInputFilterHandler"
See
\&\f(CW\*(C`PerlInputFilterHandler\*(C'\fR.
.ie n .Sh """PerlOutputFilterHandler"""
.el .Sh "\f(CWPerlOutputFilterHandler\fP"
.IX Subsection "PerlOutputFilterHandler"
See
\&\f(CW\*(C`PerlOutputFilterHandler\*(C'\fR.
.ie n .Sh """PerlSetInputFilter"""
.el .Sh "\f(CWPerlSetInputFilter\fP"
.IX Subsection "PerlSetInputFilter"
See
\&\f(CW\*(C`PerlSetInputFilter\*(C'\fR.
.ie n .Sh """PerlSetOutputFilter"""
.el .Sh "\f(CWPerlSetOutputFilter\fP"
.IX Subsection "PerlSetOutputFilter"
See
\&\f(CW\*(C`PerlSetInputFilter\*(C'\fR.
.SH "TIE Interface"
.IX Header "TIE Interface"
\&\f(CW\*(C`Apache2::Filter\*(C'\fR also implements a tied interface, so you can work
with the \f(CW$f\fR object as a hash reference.
.PP
The \s-1TIE\s0 interface is mostly unimplemented and might be implemented
post 2.0 release.
.ie n .Sh """TIEHANDLE"""
.el .Sh "\f(CWTIEHANDLE\fP"
.IX Subsection "TIEHANDLE"
.Vb 1
\&  $ret = TIEHANDLE($stashsv, $sv);
.Ve
.ie n .IP "obj: $stashsv ( \s-1SCALAR\s0 )" 4
.el .IP "obj: \f(CW$stashsv\fR ( \s-1SCALAR\s0 )" 4
.IX Item "obj: $stashsv ( SCALAR )"
.PD 0
.ie n .IP "arg1: $sv ( \s-1SCALAR\s0 )" 4
.el .IP "arg1: \f(CW$sv\fR ( \s-1SCALAR\s0 )" 4
.IX Item "arg1: $sv ( SCALAR )"
.ie n .IP "ret: $ret ( \s-1SCALAR\s0 )" 4
.el .IP "ret: \f(CW$ret\fR ( \s-1SCALAR\s0 )" 4
.IX Item "ret: $ret ( SCALAR )"
.IP "since: subject to change" 4
.IX Item "since: subject to change"
.PD
.ie n .Sh """PRINT"""
.el .Sh "\f(CWPRINT\fP"
.IX Subsection "PRINT"
.Vb 1
\&  $ret = PRINT(...);
.Ve
.ie n .IP "obj: ""..."" (\s-1XXX\s0)" 4
.el .IP "obj: \f(CW...\fR (\s-1XXX\s0)" 4
.IX Item "obj: ... (XXX)"
.PD 0
.ie n .IP "ret: $ret ( integer )" 4
.el .IP "ret: \f(CW$ret\fR ( integer )" 4
.IX Item "ret: $ret ( integer )"
.IP "since: subject to change" 4
.IX Item "since: subject to change"
.PD
.SH "See Also"
.IX Header "See Also"
mod_perl 2.0 documentation.
.SH "Copyright"
.IX Header "Copyright"
mod_perl 2.0 and its core modules are copyrighted under
The Apache Software License, Version 2.0.
.SH "Authors"
.IX Header "Authors"
The mod_perl development team and numerous
contributors.