|
|
Apache2::SubRequest - Perl API for Apache subrequests
use Apache2::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;
Apache2::SubRequest contains API for creating and running of Apache
sub-requests.
Apache2::SubRequest is a sub-class of Apache2::RequestRec
object|docs::2.0::api::Apache2::RequestRec>.
Apache2::SubRequest provides the following functions and/or methods:
DESTROYFree the memory associated with a sub request:
undef $subr; # but normally don't do that
$subr ( Apache2::SubRequest
object|docs::2.0::api::Apache2::SubRequest/Description> )
The sub request to finish
DESTROY is called automatically when $subr goes out of scope.
If you want to free the memory earlier than that (for example if you
run several subrequests), you can undef the object as:
undef $subr;
but never call DESTROY explicitly, since it'll result in
ap_destroy_sub_req being called more than once, resulting in
multiple brain injuries and certain hair loss.
internal_redirectRedirect the current request to some other uri internally
$r->internal_redirect($new_uri);
$r
( Apache2::RequestRec object|docs::2.0::api::Apache2::RequestRec )
The current request
$new_uri ( string )
The URI to replace the current request with
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 Apache2::Const::OK. The
client will be unaware the a different request was served to her
behind the scenes.
internal_redirect_handlerIdentical to internal_redirect|/C_internal_redirect_, plus
automatically sets
$r->content_type|docs::2.0::api::Apache2::RequestRec/C_content_type_
is of the sub-request to be the same as of the main request, if
$r->handler|docs::2.0::api::Apache2::RequestRec/C_handler_ is
true.
$r->internal_redirect_handler($new_uri);
$r
( Apache2::RequestRec object|docs::2.0::api::Apache2::RequestRec )
The current request
$new_uri ( string )
The URI to replace the current request with.
This function is designed for things like actions or CGI scripts, when
using AddHandler, and you want to preserve the content type across
an internal redirect.
lookup_fileCreate 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);
$r
( Apache2::RequestRec object|docs::2.0::api::Apache2::RequestRec )
The current request
$new_file ( string )
The file to lookup
$next_filter
( Apache2::Filter|docs::2.0::api::Apache2::Filter )
See $r->lookup_uri|/C_lookup_uri_ for details.
$ret ( Apache2::SubRequest
object|docs::2.0::api::Apache2::SubRequest/Description> )
The sub request record.
See $r->lookup_uri|/C_lookup_uri_ for further discussion.
lookup_method_uriCreate 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);
$r
( Apache2::RequestRec object|docs::2.0::api::Apache2::RequestRec )
The current request
$method ( string )
The method to use in the new sub request (e.g. "GET")
$new_uri ( string )
The URI to lookup
$next_filter
( Apache2::Filter object|docs::2.0::api::Apache2::Filter )
See $r->lookup_uri|/C_lookup_uri_ for details.
$ret ( Apache2::SubRequest
object|docs::2.0::api::Apache2::SubRequest/Description> )
The sub request record.
See $r->lookup_uri|/C_lookup_uri_ for further discussion.
lookup_uriCreate 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);
$r
( Apache2::RequestRec object|docs::2.0::api::Apache2::RequestRec )
The current request
$new_uri ( string )
The URI to lookup
$next_filter
( Apache2::Filter object|docs::2.0::api::Apache2::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
$r->proto_output_filters|docs::2.0::api::Apache2::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
$r->output_filters|docs::2.0::api::Apache2::RequestRec/C_output_filters_
as an argument.
$ret ( Apache2::SubRequest
object|docs::2.0::api::Apache2::SubRequest/Description> )
The sub request record
Here is an example of a simple subrequest which serves uri /new_uri:
sub handler {
my $r = shift;
my $subr = $r->lookup_uri("/new_uri");
$sub->run;
return Apache2::Const::OK;
}
If let's say you have three request output filters registered to run for the main request:
PerlOutputFilterHandler MyApache2::SubReqExample::filterA PerlOutputFilterHandler MyApache2::SubReqExample::filterB PerlOutputFilterHandler MyApache2::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 (filterA), the
code needs to be adjusted to be:
my $subr = $r->lookup_uri("/new_uri", $r->output_filters->next);
runRun a sub-request
$rc = $subr->run();
$subr
( Apache2::RequestRec object|docs::2.0::api::Apache2::RequestRec )
The sub-request (e.g. returned by lookup_uri|/C_lookup_uri_)
$rc ( integer )
The return code of the handler (Apache2::Const::OK, Apache2::Const::DECLINED,
etc.)
Apache2::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 the mod_perl development mailing list so we can help each other take the steps necessary
to shift the method to an officially supported API.
internal_fast_redirectMETA: Autogenerated - needs to be reviewed/completed
Redirect the current request to a sub_req, merging the pools
$r->internal_fast_redirect($sub_req);
$r
( Apache2::RequestRec object|docs::2.0::api::Apache2::RequestRec )
The current request
$sub_req ( string )
A subrequest created from this request
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?
lookup_direntMETA: 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);
$r
( Apache2::RequestRec object|docs::2.0::api::Apache2::RequestRec )
The current request
$finfo
( APR::Finfo object|docs::2.0::api::APR::Finfo )
The apr_dir_read result to lookup
$subtype ( integer )
What type of subrequest to perform, one of;
Apache2::SUBREQ_NO_ARGS ignore r->args and r->path_info Apache2::SUBREQ_MERGE_ARGS merge r->args and r->path_info
$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
$lr
( Apache2::RequestRec object|docs::2.0::api::Apache2::RequestRec )
The new request record
META: where do we take the apr_dir_read result from?
mod_perl 2.0 and its core modules are copyrighted under The Apache Software License, Version 2.0.