PC Professionell 2004 December/PCpro_2004_12.ISO/files/webserver/xampp/xampp-perl-addon-1.4.9-installer.exe/SubRequest.pm

Perl POD Document | 2004-09-23 | 10.5 KB | 503 lines

#
# /*
#  * *********** WARNING **************
#  * This file generated by ModPerl::WrapXS/0.01
#  * Any changes made here will be lost
#  * ***********************************
#  * 01: lib/ModPerl/Code.pm:701
#  * 02: O:\147xampp\sources\mod_perl-1.99_16\blib\lib/ModPerl/WrapXS.pm:584
#  * 03: O:\147xampp\sources\mod_perl-1.99_16\blib\lib/ModPerl/WrapXS.pm:1100
#  * 04: Makefile.PL:335
#  * 05: Makefile.PL:283
#  * 06: Makefile.PL:51
#  */
#


package Apache::SubRequest;

use strict;
use warnings FATAL => 'all';

@Apache::SubRequest::ISA = 'Apache::RequestRec';


use Apache::XSLoader ();
our $VERSION = '0.01';
Apache::XSLoader::load __PACKAGE__;



1;
__END__

=head1 NAME

Apache::SubRequest - Perl API for Apache subrequests




=head1 Synopsis

  use Apache::SubRequest ();

  # run internal redirects at once
  $r->internal_redirect($new_uri);
  $r->internal_redirect_handler($new_uri);

  # create internal redirect objects
  $subr = $r->lookup_uri("/foo");
  $subr = $r->lookup_method_uri("GET", "/tmp/bar")
  $subr = $r->lookup_file("/tmp/bar");
  # optionally manipulate the output through main request filters
  $subr = $r->lookup_uri("/foo", $r->output_filters);
  # now run them
  my $rc = $subr->run;
  # optional
  $subr->DESTROY;




=head1 Description

C<Apache::SubRequest> contains API for creating and running of Apache
sub-requests.

C<Apache::SubRequest> is a sub-class of C<L<Apache::RequestRec
object|docs::2.0::api::Apache::RequestRec>>.







=head1 API

C<Apache::SubRequest> provides the following functions and/or methods:





=head2 C<DESTROY>

Free the memory associated with a sub request

  $subr->DESTROY();

=over 4

=item obj: C<$subr> ( C<L<Apache::SubRequest
object|docs::2.0::api::Apache::SubRequest/Description>> )

The sub request to finish

=item ret: no return value

=item since: 1.99_12

=back

This method will be called automatically when C<$subr> goes out of
scope, so there is no need to call it explicitly, unless you want to
free the memory earlier than that (for example if you run several
subrequests).












=head2 C<internal_redirect>

Redirect the current request to some other uri internally

  $r->internal_redirect($new_uri);

=over 4

=item obj: C<$r>
( C<L<Apache::RequestRec object|docs::2.0::api::Apache::RequestRec>> )

The current request

=item arg1: C<$new_uri> ( string )

The URI to replace the current request with

=item ret: no return value

=item since: 1.99_12

=back

In case that you want some other request to be served as the top-level
request instead of what the client requested directly, call this
method from a handler, and then immediately return C<Apache::OK>. The
client will be unaware the a different request was served to her
behind the scenes.








=head2 C<internal_redirect_handler>

Identical to C<internal_redirect|/C_internal_redirect_>, plus
automatically sets
C<L<$r-E<gt>content_type|docs::2.0::api::Apache::RequestRec/C_content_type_>>
is of the sub-request to be the same as of the main request, if
C<L<$r-E<gt>handler|docs::2.0::api::Apache::RequestRec/C_handler_>> is
true.

  $r->internal_redirect_handler($new_uri);

=over 4

=item obj: C<$r>
( C<L<Apache::RequestRec object|docs::2.0::api::Apache::RequestRec>> )

The current request

=item arg1: C<$new_uri> ( string )

The URI to replace the current request with.

=item ret: no return value

=item since: 1.99_12

=back

This function is designed for things like actions or CGI scripts, when
using C<AddHandler>, and you want to preserve the content type across
an internal redirect.










=head2 C<lookup_file>

Create a subrequest for the given file.  This sub request can be
inspected to find information about the requested file

  $ret = $r->lookup_file($new_file);
  $ret = $r->lookup_file($new_file, $next_filter);

=over 4

=item obj: C<$r>
( C<L<Apache::RequestRec object|docs::2.0::api::Apache::RequestRec>> )

The current request

=item arg1: C<$new_file> ( string )

The file to lookup

=item opt arg2: C<$next_filter>
( C<L<Apache::Filter|docs::2.0::api::Apache::Filter>> )

See C<L<$r-E<gt>lookup_uri|/C_lookup_uri_>> for details.

=item ret: C<$ret> ( C<L<Apache::SubRequest
object|docs::2.0::api::Apache::SubRequest/Description>> )

The sub request record.

=item since: 1.99_15

=back

See C<L<$r-E<gt>lookup_uri|/C_lookup_uri_>> for further discussion.




=head2 C<lookup_method_uri>

Create a sub request for the given URI using a specific method.  This
sub request can be inspected to find information about the requested
URI

  $ret = $r->lookup_method_uri($method, $new_uri);
  $ret = $r->lookup_method_uri($method, $new_uri, $next_filter);

=over 4

=item obj: C<$r>
( C<L<Apache::RequestRec object|docs::2.0::api::Apache::RequestRec>> )

The current request

=item arg1: C<$method> ( string )

The method to use in the new sub request (e.g. C<"GET">)

=item arg2: C<$new_uri> ( string )

The URI to lookup

=item opt arg3: C<$next_filter>
( C<L<Apache::Filter object|docs::2.0::api::Apache::Filter>> )

See C<L<$r-E<gt>lookup_uri|/C_lookup_uri_>> for details.

=item ret: C<$ret> ( C<L<Apache::SubRequest
object|docs::2.0::api::Apache::SubRequest/Description>> )

The sub request record.

=item since: 1.99_15

=back

See C<L<$r-E<gt>lookup_uri|/C_lookup_uri_>> for further discussion.





=head2 C<lookup_uri>

Create a sub request from the given URI.  This sub request can be
inspected to find information about the requested URI.

  $ret = $r->lookup_uri($new_uri);
  $ret = $r->lookup_uri($new_uri, $next_filter);

=over 4

=item obj: C<$r>
( C<L<Apache::RequestRec object|docs::2.0::api::Apache::RequestRec>> )

The current request

=item arg1: C<$new_uri> ( string )

The URI to lookup

=item opt arg2: C<$next_filter>
( C<L<Apache::Filter object|docs::2.0::api::Apache::Filter>> )

The first filter the subrequest should pass the data through.  If not
specified it defaults to the first connection output filter for the
main request
C<L<$r-E<gt>proto_output_filters|docs::2.0::api::Apache::RequestRec/C_proto_output_filters_>>. So
if the subrequest sends any output it will be filtered only once. If
for example you desire to apply the main request's output filters to
the sub-request output as well pass
C<L<$r-E<gt>output_filters|docs::2.0::api::Apache::RequestRec/C_output_filters_>>
as an argument.

=item ret: C<$ret> ( C<L<Apache::SubRequest
object|docs::2.0::api::Apache::SubRequest/Description>> )

The sub request record

=item since: 1.99_15

=back

Here is an example of a simple subrequest which serves uri
I</new_uri>:

  sub handler {
      my $r = shift;

      my $subr = $r->lookup_uri("/new_uri");
      $sub->run;

      return Apache::OK;
  }

If let's say you have three request output filters registered to run
for the main request:

  PerlOutputFilterHandler MyApache::SubReqExample::filterA
  PerlOutputFilterHandler MyApache::SubReqExample::filterB
  PerlOutputFilterHandler MyApache::SubReqExample::filterC

and you wish to run them all, the code needs to become:

      my $subr = $r->lookup_uri("/new_uri", $r->output_filters);

and if you wish to run them all, but the first one (C<filterA>), the
code needs to be adjusted to be:

      my $subr = $r->lookup_uri("/new_uri", $r->output_filters->next);





=head2 C<run>

Run a sub-request

  $rc = $subr->run();

=over 4

=item obj: C<$subr>
( C<L<Apache::RequestRec object|docs::2.0::api::Apache::RequestRec>> )

The sub-request (e.g. returned by C<L<lookup_uri|/C_lookup_uri_>>)

=item ret: C<$rc> ( integer )

The return code of the handler (C<Apache::OK>, C<Apache::DECLINED>,
etc.)

=item since: 1.99_12

=back






=head1 Unsupported API

C<Apache::SubRequest> also provides auto-generated Perl interface for
a few other methods which aren't tested at the moment and therefore
their API is a subject to change. These methods will be finalized
later as a need arises. If you want to rely on any of the following
methods please contact the L<the mod_perl development mailing
list|maillist::dev> so we can help each other take the steps necessary
to shift the method to an officially supported API.






=head2 C<internal_fast_redirect>

META: Autogenerated - needs to be reviewed/completed

Redirect the current request to a sub_req, merging the pools

  $r->internal_fast_redirect($sub_req);

=over 4

=item obj: C<$r>
( C<L<Apache::RequestRec object|docs::2.0::api::Apache::RequestRec>> )

The current request

=item arg1: C<$sub_req> ( string )

A subrequest created from this request

=item ret: no return value

=item since: 1.99_12

=back


META: httpd-2.0/modules/http/http_request.c declares this function as:

  /* XXX: Is this function is so bogus and fragile that we deep-6 it? */

do we really want to expose it to mod_perl users?






=head2 C<lookup_dirent>

META: Autogenerated - needs to be reviewed/completed

Create a sub request for the given apr_dir_read result.  This sub request
can be inspected to find information about the requested file

  $lr = $r->lookup_dirent($finfo);
  $lr = $r->lookup_dirent($finfo, $subtype);
  $lr = $r->lookup_dirent($finfo, $subtype, $next_filter);

=over 4

=item obj: C<$r>
( C<L<Apache::RequestRec object|docs::2.0::api::Apache::RequestRec>> )

The current request

=item arg1: C<$finfo>
( C<L<APR::Finfo object|docs::2.0::api::APR::Finfo>> )

The apr_dir_read result to lookup

=item arg2: C<$subtype> ( integer )

What type of subrequest to perform, one of;

  Apache::SUBREQ_NO_ARGS     ignore r->args and r->path_info
  Apache::SUBREQ_MERGE_ARGS  merge  r->args and r->path_info

=item arg3: C<$next_filter> ( integer )

The first filter the sub_request should use.  If this is
NULL, it defaults to the first filter for the main request

=item ret: C<$lr>
( C<L<Apache::RequestRec object|docs::2.0::api::Apache::RequestRec>> )

The new request record

=item since: 1.99_12

=back

META: where do we take the apr_dir_read result from?





=head1 See Also

L<mod_perl 2.0 documentation|docs::2.0::index>.




=head1 Copyright

mod_perl 2.0 and its core modules are copyrighted under
The Apache Software License, Version 2.0.




=head1 Authors

L<The mod_perl development team and numerous
contributors|about::contributors::people>.

=cut