perl-modperl-cvs mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From s...@apache.org
Subject cvs commit: modperl-docs/src/docs/2.0/api/Apache Filter.pod
Date Thu, 17 Apr 2003 08:33:40 GMT
stas        2003/04/17 01:33:38

  Modified:    src/docs/2.0/api config.cfg
  Added:       src/docs/2.0/api/Apache Filter.pod
  Log:
  - start the Apache::Filter manpage
  - document the newly implemented attributes
  
  Revision  Changes    Path
  1.20      +1 -0      modperl-docs/src/docs/2.0/api/config.cfg
  
  Index: config.cfg
  ===================================================================
  RCS file: /home/cvs/modperl-docs/src/docs/2.0/api/config.cfg,v
  retrieving revision 1.19
  retrieving revision 1.20
  diff -u -r1.19 -r1.20
  --- config.cfg	22 Mar 2003 08:20:30 -0000	1.19
  +++ config.cfg	17 Apr 2003 08:33:38 -0000	1.20
  @@ -20,6 +20,7 @@
           Apache/Access.pod
           Apache/Log.pod
           Apache/Directive.pod
  +        Apache/Filter.pod
           Apache/RequestRec.pod
           Apache/RequestUtil.pod
           Apache/ServerUtil.pod
  
  
  
  1.1                  modperl-docs/src/docs/2.0/api/Apache/Filter.pod
  
  Index: Filter.pod
  ===================================================================
  =head1 NAME
  
  Apache::Filter -- A Perl API for Apache 2.0 Filtering
  
  =head1 Synopsis
  
    use Apache::Filter;
  
  =head1 Description
  
  C<Apache::Filter> provides the Perl API for Apache 2.0 filtering
  framework
  
  =head1 API
  
  Function arguments (if any) and return values are shown in the
  function's synopsis.
  
  =head2 ...
  
  =head1 Attributes
  
  To use attributes the package they are defined in, has to subclass
  C<Apache::Filter>:
  
    use base qw(Apache::Filter);
  
  Attributes are parsed during the code compilation.
  
  =head2 C<FilterRequestHandler>
  
  =head2 C<FilterConnectionHandler>
  
  =head2 C<FilterInitHandler>
  
    sub init : FilterInitHandler {
        my $filter = shift;
        #...
        return Apache::OK;
    }
  
  The attribute C<FilterInitHandler> 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 "long" before it's
  actually called.
  
  For example you may decide to remove the filter before it had a chance
  to run.
  
    sub init : FilterInitHandler {
        my $filter = shift;
        $filter->remove() if should_remove_filter();
        return Apache::OK;
    }
  
  In order to hook this filter callback, the real filter has to assign
  this callback using the
  C<L<FilterHasInitHandler|/C_FilterHasInitHandler_>> which accepts a
  reference to the callback function.
  
  =head2 C<FilterHasInitHandler>
  
  If a filter wants to run an initialization callback it can register
  such using the C<FilterHasInitHandler> attribute. Similar to
  C<push_handlers> the callback reference is expected, rather than a
  callback name. The used callback function has to have the
  C<L<FilterInitHandler|/C_FilterInitHandler_>> attribute. For example:
  
    package MyFilter;
    use base qw(Apache::Filter);
    sub init   : FilterInitHandler { ... }
    sub filter : FilterRequestHandler FilterHasInitHandler(\&init) {
        my ($filter, $bb) = @_;
        # ...
        return Apache::OK;
    }
  
  While attributes are parsed during the code compilation (it's really a
  sort of source filter), the argument to the C<FilterHasInitHandler()>
  attribute is compiled at a later stage once the module is compiled.
  
  The argument to C<FilterHasInitHandler()> can be any perl code which
  when C<eval()>'ed returns a reference to a function. For example:
  
    package MyFilter;
    sub get_pre_handler { \&MyOtherfilter::init }
    sub filter : FilterHasInitHandler(get_pre_handler()) { ... }
  
  Notice that the argument to C<FilterHasInitHandler()> is always
  C<eval()>'ed in the package of the real filter handler (not the init
  handler). So the above code leads to the following evaluation:
  
    $init_handler_sub = eval "package MyFilter; get_pre_handler()";
  
  though, this is done in C.
  
  META: currently only one callback can be registered per filter, if the
  need to register more than one arises it should be very easy to do.
  
  =cut
  
  
  

Mime
View raw message