apache2::filter.3

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

care of passing the current bucket brigade through unmodified to the
next filter in chain.
.PP
Note: calling \fIremove()\fR on the very top connection filter doesn't
affect the filter chain due to a bug in Apache 2.0 (which may be fixed
in 2.1). So don't use it with connection filters, till it gets fixed
in Apache and then make sure to require the minimum Apache version if
you rely on.
.PP
Remember that if the connection is
\&\f(CW\*(C`$c\->keepalive\*(C'\fR
) and the connection filter is removed, it won't be added until the
connection is closed. Which may happen after many \s-1HTTP\s0 requests. You
may want to keep the filter in place and pass the data through
unmodified, by returning \f(CW\*(C`Apache2::Const::DECLINED\*(C'\fR. If you need to reset the
whole or parts of the filter context between requests, use the
technique based on \f(CW\*(C`$c\->keepalives\*(C'\fR
counting.
.PP
This method works for native Apache (non\-mod_perl) filters too.
.SH "Bucket Brigade Filter API"
.IX Header "Bucket Brigade Filter API"
The following methods can be called from any filter, directly
manipulating bucket brigades:
.ie n .Sh """fflush"""
.el .Sh "\f(CWfflush\fP"
.IX Subsection "fflush"
Flush a bucket brigade down the filter stack.
.PP
.Vb 1
\&  $rc = $f\->fflush($bb);
.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 current filter
.ie n .IP "arg1: $bb\fR ( \f(CW""Apache2::Brigade object"" )" 4
.el .IP "arg1: \f(CW$bb\fR ( \f(CWApache2::Brigade object\fR )" 4
.IX Item "arg1: $bb ( Apache2::Brigade object )"
The brigade to flush
.ie n .IP "ret:  $rc\fR ( \f(CW""APR::Const status constant"" )" 4
.el .IP "ret:  \f(CW$rc\fR ( \f(CWAPR::Const status constant\fR )" 4
.IX Item "ret:  $rc ( APR::Const status constant )"
Refer to the \f(CW\*(C`pass_brigade()\*(C'\fR entry.
.ie n .IP "excpt: ""APR::Error""" 4
.el .IP "excpt: \f(CWAPR::Error\fR" 4
.IX Item "excpt: APR::Error"
Exceptions are thrown only when this function is called in the \s-1VOID\s0
context. Refer to the \f(CW\*(C`get_brigade()\*(C'\fR entry for
details.
.IP "since: 2.0.00" 4
.IX Item "since: 2.0.00"
.PP
\&\f(CW\*(C`fflush\*(C'\fR is a shortcut method. So instead of doing:
.PP
.Vb 3
\&  my $b = APR::Bucket::flush_create($f\->c\->bucket_alloc);
\&  $bb\->insert_tail($b);
\&  $f\->pass_brigade($bb);
.Ve
.PP
one can just write:
.PP
.Vb 1
\&  $f\->fflush($bb);
.Ve
.ie n .Sh """get_brigade"""
.el .Sh "\f(CWget_brigade\fP"
.IX Subsection "get_brigade"
This is a method to use in bucket brigade input filters. It acquires a
bucket brigade from the upstream input filter.
.PP
.Vb 4
\&  $rc = $next_f\->get_brigade($bb, $mode, $block, $readbytes);
\&  $rc = $next_f\->get_brigade($bb, $mode, $block);
\&  $rc = $next_f\->get_brigade($bb, $mode)
\&  $rc = $next_f\->get_brigade($bb);
.Ve
.ie n .IP "obj: $next_f\fR ( \f(CW""Apache2::Filter object"" )" 4
.el .IP "obj: \f(CW$next_f\fR ( \f(CWApache2::Filter object\fR )" 4
.IX Item "obj: $next_f ( Apache2::Filter object )"
The next filter in the filter chain.
.Sp
Inside filter handlers it's
usually \f(CW\*(C`$f\->next\*(C'\fR. Inside protocol
handlers:
\&\f(CW\*(C`$c\->input_filters\*(C'\fR.
.ie n .IP "arg1: $bb\fR ( \f(CW""APR::Brigade object"" )" 4
.el .IP "arg1: \f(CW$bb\fR ( \f(CWAPR::Brigade object\fR )" 4
.IX Item "arg1: $bb ( APR::Brigade object )"
The original bucket brigade passed to \f(CW\*(C`get_brigade()\*(C'\fR, which must be
empty.
.Sp
Inside input filter
handlers it's usually the second
argument to the filter handler.
.Sp
Otherwise it should be created:
.Sp
.Vb 1
\&  my $bb = APR::Brigade\->new($c\->pool, $c\->bucket_alloc);
.Ve
.Sp
On return it gets populated with the next bucket brigade. That brigade
may contain nothing if there was no more data to read. The return
status tells the outcome.
.ie n .IP "opt arg2: $mode\fR ( \f(CW""Apache2::Const :input_mode constant"" )" 4
.el .IP "opt arg2: \f(CW$mode\fR ( \f(CWApache2::Const :input_mode constant\fR )" 4
.IX Item "opt arg2: $mode ( Apache2::Const :input_mode constant )"
The filter mode in which the data should be read.
.Sp
If inside the filter handler, you should normally pass the same mode
that was passed to the filter handler (the third argument).
.Sp
At the end of this section the available modes are presented.
.Sp
If the argument \f(CW$mode\fR is not passed,
\&\f(CW\*(C`Apache2::Const::MODE_READBYTES\*(C'\fR
is used as a default value.
.ie n .IP "opt arg3: $block\fR ( \f(CW""APR::Const :read_type constant"" )" 4
.el .IP "opt arg3: \f(CW$block\fR ( \f(CWAPR::Const :read_type constant\fR )" 4
.IX Item "opt arg3: $block ( APR::Const :read_type constant )"
You may ask the reading operation to be blocking:
\&\f(CW\*(C`APR::Const::BLOCK_READ\*(C'\fR,
or nonblocking:
\&\f(CW\*(C`APR::Const::NONBLOCK_READ\*(C'\fR.
.Sp
If inside the filter handler, you should normally pass the same
blocking mode argument that was passed to the filter handler (the
forth argument).
.Sp
If the argument \f(CW$block\fR is not passed,
\&\f(CW\*(C`APR::Const::BLOCK_READ\*(C'\fR is
used as a default value.
.ie n .IP "opt arg4: $readbytes ( integer )" 4
.el .IP "opt arg4: \f(CW$readbytes\fR ( integer )" 4
.IX Item "opt arg4: $readbytes ( integer )"
How many bytes to read from the next filter.
.Sp
If inside the filter handler, you may want the same number of bytes,
as the upstream filter, i.e. the argument that was passed to the
filter handler (the fifth argument).
.Sp
If the argument \f(CW$block\fR is not passed, 8192 is used as a default
value.
.ie n .IP "ret: $rc\fR ( \f(CW""APR::Const status constant"" )" 4
.el .IP "ret: \f(CW$rc\fR ( \f(CWAPR::Const status constant\fR )" 4
.IX Item "ret: $rc ( APR::Const status constant )"
On success,
\&\f(CW\*(C`APR::Const::SUCCESS\*(C'\fR is
returned and \f(CW$bb\fR is populated (see the \f(CW$bb\fR entry).
.Sp
In case of a failure \*(-- a failure code is returned, in which case
normally it should be returned to the caller.
.Sp
If the bottom-most filter doesn't read from the network, then
\&\f(CW\*(C`Apache2::NOBODY_READ\*(C'\fR is returned (\s-1META:\s0 need to add this constant).
.Sp
Inside protocol handlers the
return code can also be \f(CW\*(C`APR::Const::EOF\*(C'\fR, which is success as well.
.ie n .IP "excpt: ""APR::Error""" 4
.el .IP "excpt: \f(CWAPR::Error\fR" 4
.IX Item "excpt: APR::Error"
You don't have to ask for the return value. If this function is called
in the \s-1VOID\s0 context, e.g.:
.Sp
.Vb 1
\&  $f\->next\->get_brigade($bb, $mode, $block, $readbytes);
.Ve
.Sp
mod_perl will do the error checking on your behalf, and if the return
code is not
\&\f(CW\*(C`APR::Const::SUCCESS\*(C'\fR, an
\&\f(CW\*(C`APR::Error exception\*(C'\fR will be thrown.
The only time you want to do the error checking yourself, is when
return codes besides
\&\f(CW\*(C`APR::Const::SUCCESS\*(C'\fR are
considered as successful and you want to manage them by yourself.
.IP "since: 2.0.00" 4
.IX Item "since: 2.0.00"
.PP
Available input filter modes (the optional second argument \f(CW$mode\fR)
are:
.IP "\(bu" 4
\&\f(CW\*(C`Apache2::Const::MODE_READBYTES\*(C'\fR
.Sp
The filter should return at most readbytes data
.IP "\(bu" 4
\&\f(CW\*(C`Apache2::Const::MODE_GETLINE\*(C'\fR
.Sp
The filter should return at most one line of \s-1CRLF\s0 data.  (If a
potential line is too long or no \s-1CRLF\s0 is found, the filter may return
partial data).
.IP "\(bu" 4
\&\f(CW\*(C`Apache2::Const::MODE_EATCRLF\*(C'\fR
.Sp
The filter should implicitly eat any \s-1CRLF\s0 pairs that it sees.
.IP "\(bu" 4
\&\f(CW\*(C`Apache2::Const::MODE_SPECULATIVE\*(C'\fR
.Sp
The filter read should be treated as speculative and any returned data
should be stored for later retrieval in another mode.
.IP "\(bu" 4
\&\f(CW\*(C`Apache2::Const::MODE_EXHAUSTIVE\*(C'\fR
.Sp
The filter read should be exhaustive and read until it can not read
any more. Use this mode with extreme caution.
.IP "\(bu" 4
\&\f(CW\*(C`Apache2::Const::MODE_INIT\*(C'\fR
.Sp
The filter should initialize the connection if needed, \s-1NNTP\s0 or \s-1FTP\s0
over \s-1SSL\s0 for example.
.PP
Either compile all these constants with:
.PP
.Vb 1
\&  use Apache2::Const \-compile => qw(:input_mode);
.Ve
.PP
But it's a bit more efficient to compile only those constants that you
need.
.PP
Example:
.PP
Here is a fragment of a filter handler, that receives a bucket brigade
from the upstream filter:
.PP
.Vb 5
\&  use Apache2::Filter ();
\&  use APR::Const    \-compile => qw(SUCCESS);
\&  use Apache2::Const \-compile => qw(OK);
\&  sub filter {
\&      my ($f, $bb, $mode, $block, $readbytes) = @_;
\&      
\&      my $rc = $f\->next\->get_brigade($bb, $mode, $block, $readbytes);
\&      return $rc unless $rc == APR::Const::SUCCESS;
\&      
\&      # ... process $bb
\&      
\&      return Apache2::Const::OK;
\&  }
.Ve
.PP
Usually arguments \f(CW$mode\fR, \f(CW$block\fR, \f(CW$readbytes\fR are the same as
passed to the filter itself.
.PP
You can see that in case of a failure, the handler returns immediately
with that failure code, which gets propagated to the downstream
filter.
.PP
If you decide not check the return code, you can write it as:
.PP
.Vb 2
\&  sub filter {
\&      my ($f, $bb, $mode, $block, $readbytes) = @_;
\&      
\&      $f\->next\->get_brigade($bb, $mode, $block, $readbytes);
\&      
\&      # ... process $bb
\&      
\&      return Apache2::Const::OK;
\&  }
.Ve
.PP
and the error checking will be done on your behalf.
.PP
You will find many more examples in \f(CW\*(C`the filter
handlers|docs::2.0::user::handlers::filters\*(C'\fR and
\&\f(CW\*(C`the protocol
handlers|docs::2.0::user::handlers::protocols\*(C'\fR tutorials.
.ie n .Sh """pass_brigade"""
.el .Sh "\f(CWpass_brigade\fP"
.IX Subsection "pass_brigade"
This is a method to use in bucket brigade output filters.  It passes
the current bucket brigade to the downstream output filter.
.PP
.Vb 1
\&  $rc = $next_f\->pass_brigade($bb);
.Ve
.ie n .IP "obj: $next_f\fR ( \f(CW""Apache2::Filter object"" )" 4
.el .IP "obj: \f(CW$next_f\fR ( \f(CWApache2::Filter object\fR )" 4
.IX Item "obj: $next_f ( Apache2::Filter object )"
The next filter in the filter chain.
.Sp
Inside output filter handlers
it's usually \f(CW\*(C`$f\->next\*(C'\fR. Inside protocol
handlers:
\&\f(CW\*(C`$c\->output_filters\*(C'\fR.
.ie n .IP "arg1: $bb\fR ( \f(CW""APR::Brigade object"" )" 4
.el .IP "arg1: \f(CW$bb\fR ( \f(CWAPR::Brigade object\fR )" 4
.IX Item "arg1: $bb ( APR::Brigade object )"
The bucket brigade to pass.
.Sp
Inside output filter
handlers it's usually the second 
argument to the filter handler (after potential manipulations).
.ie n .IP "ret: $rc\fR ( \f(CW""APR::Const status constant"" )" 4
.el .IP "ret: \f(CW$rc\fR ( \f(CWAPR::Const status constant\fR )" 4
.IX Item "ret: $rc ( APR::Const status constant )"
On success,
\&\f(CW\*(C`APR::Const::SUCCESS\*(C'\fR is
returned.
.Sp
In case of a failure \*(-- a failure code is returned, in which case
normally it should be returned to the caller.
.Sp
If the bottom-most filter doesn't write to the network, then
\&\f(CW\*(C`Apache2::NOBODY_WROTE\*(C'\fR is returned (\s-1META:\s0 need to add this constant).
.Sp
Also refer to the \f(CW\*(C`get_brigade()\*(C'\fR entry to see how
to avoid checking the errors explicitly.
.ie n .IP "excpt: ""APR::Error""" 4
.el .IP "excpt: \f(CWAPR::Error\fR" 4
.IX Item "excpt: APR::Error"
Exceptions are thrown only when this function is called in the \s-1VOID\s0
context. Refer to the \f(CW\*(C`get_brigade()\*(C'\fR entry for
details.
.IP "since: 2.0.00" 4
.IX Item "since: 2.0.00"
.PP
The caller relinquishes ownership of the brigade (i.e. it may get
destroyed/overwritten/etc. by the callee).
.PP
Example:
.PP
Here is a fragment of a filter handler, that passes a bucket brigade
to the downstream filter (after some potential processing of the
buckets in the bucket brigade):
.PP
.Vb 5
\&  use Apache2::Filter ();
\&  use APR::Const    \-compile => qw(SUCCESS);
\&  use Apache2::Const \-compile => qw(OK);
\&  sub filter {
\&      my ($f, $bb) = @_;
\&  
\&      # ... process $bb
\&  
\&      my $rc = $f\->next\->pass_brigade($bb);
\&      return $rc unless $rc == APR::Const::SUCCESS;
\&  
\&      return Apache2::Const::OK;
\&  }
.Ve
.SH "Streaming Filter API"
.IX Header "Streaming Filter API"
The following methods can be called from any filter, which uses the
simplified streaming functionality:
.ie n .Sh """print"""
.el .Sh "\f(CWprint\fP"
.IX Subsection "print"
Send the contents of \f(CW$buffer\fR to the next filter in chain (via
internal buffer).
.PP
.Vb 1
\&  $sent = $f\->print($buffer);
.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 ( string )" 4
.el .IP "arg1: \f(CW$buffer\fR ( string )" 4
.IX Item "arg1: $buffer ( string )"
.PD
The data to send.
.ie n .IP "ret: $sent ( integer )" 4
.el .IP "ret: \f(CW$sent\fR ( integer )" 4
.IX Item "ret: $sent ( integer )"
How many characters were sent. There is no need to check, since all
should go through and if something goes work an exception will be
thrown.
.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