NAME
Apache2::SubRequest - Perl API for Apache subrequests
SSyynnooppssiissuse Apache2::SubRequest ();
# run internal redirects at once
$r->internalredirect($newuri);
$r->internalredirecthandler($newuri);
# create internal redirect objects
$subr = $r->lookupuri("/foo");
$subr = $r->lookupmethoduri("GET", "/tmp/bar")
$subr = $r->lookupfile("/tmp/bar");
# optionally manipulate the output through main request filters
$subr = $r->lookupuri("/foo", $r->outputfilters);
# now run them
my $rc = $subr->run;
DDeessccrriippttiioonn"Apache2::SubRequest" contains API for creating and running of Apache
sub-requests.
"Apache2::SubRequest" is a sub-class of "Apache2::RequestRec object".
AAPPII"Apache2::SubRequest" provides the following functions and/or methods:
""DDEESSTTRROOYY"" Free the memory associated with a sub request:undef $subr; # but normally don't do that
obj: $subr ( "Apache2::SubRequest object" )
The sub request to finish ret: no return value since: 2.0.00"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 "apdestroysubreq" being called more than once, resulting in multiple brain injuries and certain hair loss. ""iinntteerrnnaallrreeddiirreecctt"" Redirect the current request to some other uri internally$r->internalredirect($newuri);
obj: $r ( "Apache2::RequestRec object" )
The current requestarg1: $newuri ( string )
The URI to replace the current request with ret: no return value since: 2.0.00In 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. ""iinntteerrnnaallrreeddiirreecctthhaannddlleerr"" Identical to "internalredirect", plus automatically sets"$r->contenttype" is of the sub-request to be the same as of the main
request, if "$r->handler" is true.
$r->internalredirecthandler($newuri);
obj: $r ( "Apache2::RequestRec object" )
The current requestarg1: $newuri ( string )
The URI to replace the current request with. ret: no return value since: 2.0.00 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. ""llooookkuuppffiillee"" Create a subrequest for the given file. This sub request can be inspected to find information about the requested file$ret = $r->lookupfile($newfile);
$ret = $r->lookupfile($newfile, $nextfilter);
obj: $r ( "Apache2::RequestRec object" )
The current requestarg1: $newfile ( string )
The file to lookupopt arg2: $nextfilter ( "Apache2::Filter" )
See "$r->lookupuri" for details.
ret: $ret ( "Apache2::SubRequest object" )
The sub request record. since: 2.0.00See "$r->lookupuri" for further discussion.
""llooookkuuppmmeetthhoodduurrii"" 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->lookupmethoduri($method, $newuri);
$ret = $r->lookupmethoduri($method, $newuri, $nextfilter);
obj: $r ( "Apache2::RequestRec object" )
The current requestarg1: $method ( string )
The method to use in the new sub request (e.g. "GET")arg2: $newuri ( string )
The URI to lookupopt arg3: $nextfilter ( "Apache2::Filter object" )
See "$r->lookupuri" for details.
ret: $ret ( "Apache2::SubRequest object" )
The sub request record. since: 2.0.00See "$r->lookupuri" for further discussion.
""llooookkuuppuurrii"" Create a sub request from the given URI. This sub request can be inspected to find information about the requested URI.$ret = $r->lookupuri($newuri);
$ret = $r->lookupuri($newuri, $nextfilter);
obj: $r ( "Apache2::RequestRec object" )
The current requestarg1: $newuri ( string )
The URI to lookupopt arg2: $nextfilter ( "Apache2::Filter object" )
The first filter the subrequest should pass the data through. If not specified it defaults to the first connection output filter forthe main request "$r->protooutputfilters". So if the subrequest
sends any output it will be filtered only once. If for example youdesire to apply the main request's output filters to the sub-
request output as well pass "$r->outputfilters" as an argument.
ret: $ret ( "Apache2::SubRequest object" )
The sub request record since: 2.0.00 Here is an example of a simple subrequest which serves uri /newuri: sub handler {my $r = shift;
my $subr = $r->lookupuri("/newuri");
$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->lookupuri("/newuri", $r->outputfilters);
and if you wish to run them all, but the first one ("filterA"), the code needs to be adjusted to be:my $subr = $r->lookupuri("/newuri", $r->outputfilters->next);
""rruunn""Run a sub-request
$rc = $subr->run();
obj: $subr ( "Apache2::RequestRec object" )
The sub-request (e.g. returned by "lookupuri")
ret: $rc ( integer )
The return code of the handler ("Apache2::Const::OK", "Apache2::Const::DECLINED", etc.) since: 2.0.00 UUnnssuuppppoorrtteedd AAPPII"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 modperl development mailing list so we can help each other take the steps necessary to shift the method to an officially supported API. ""iinntteerrnnaallffaassttrreeddiirreecctt""META: Autogenerated - needs to be reviewed/completed
Redirect the current request to a subreq, merging the pools$r->internalfastredirect($subreq);
obj: $r ( "Apache2::RequestRec object" )
The current requestarg1: $subreq ( string )
A subrequest created from this request ret: no return value since: 2.0.00META: httpd-2.0/modules/http/httprequest.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 modperl users? ""llooookkuuppddiirreenntt""META: Autogenerated - needs to be reviewed/completed
Create a sub request for the given aprdirread result. This sub request can be inspected to find information about the requested file$lr = $r->lookupdirent($finfo);
$lr = $r->lookupdirent($finfo, $subtype);
$lr = $r->lookupdirent($finfo, $subtype, $nextfilter);
obj: $r ( "Apache2::RequestRec object" )
The current requestarg1: $finfo ( "APR::Finfo object" )
The aprdirread result to lookuparg2: $subtype ( integer )
What type of subrequest to perform, one of;Apache2::SUBREQNOARGS ignore r->args and r->pathinfo
Apache2::SUBREQMERGEARGS merge r->args and r->pathinfo
arg3: $nextfilter ( integer )
The first filter the subrequest should use. If this is NULL, it defaults to the first filter for the main requestret: $lr ( "Apache2::RequestRec object" )
The new request record since: 2.0.00 META: where do we take the aprdirread result from? SSeeee AAllssoo modperl 2.0 documentation. CCooppyyrriigghhtt modperl 2.0 and its core modules are copyrighted under The Apache Software License, Version 2.0. AAuutthhoorrss The modperl development team and numerous contributors.perlavp5a.c8h.e8modperl-101.1~2::modp2e0r0l5-21.00-.220::docs::api::Apache2::SubRequest(3)