NAME
Apache2::HookRun - Perl API for Invoking Apache HTTP phases
SSyynnooppssiiss# httpd.conf
PerlProcessConnectionHandler MyApache2::PseudoHTTP::handler#file:MyApache2/PseudoHTTP.pm
#--------------
package MyApache2::PseudoHTTP;use Apache2::HookRun ();
use Apache2::RequestUtil (); use Apache2::RequestRec ();use Apache2::Const -compile => qw(OK DECLINED DONE SERVERERROR);
# implement the HTTP protocol cycle in protocol handler
sub handler {my $c = shift;
my $r = Apache2::RequestRec->new($c);
# register any custom callbacks here, e.g.:
# $r->pushhandlers(PerlAccessHandler => \&myaccess);
$rc = $r->runpostreadrequest();
return $rc unless $rc == Apache2::Const::OK or $rc == Apache2::Const::DECLINED;
$rc = $r->runtranslatename;
return $rc unless $rc == Apache2::Const::OK or $rc == Apache2::Const::DECLINED;
$rc = $r->runmaptostorage;
return $rc unless $rc == Apache2::Const::OK or $rc == Apache2::Const::DECLINED;
# this must be run all a big havoc will happen in the following
# phases
$r->locationmerge($path);
$rc = $r->runheaderparser;
return $rc unless $rc == Apache2::Const::OK or $rc == Apache2::Const::DECLINED;
my $args = $r->args || '';
if ($args eq 'die') {
$r->die(Apache2::Const::SERVERERROR);
return Apache2::Const::DONE; }$rc = $r->runaccesschecker;
return $rc unless $rc == Apache2::Const::OK or $rc == Apache2::Const::DECLINED;
$rc = $r->runauthchecker;
return $rc unless $rc == Apache2::Const::OK or $rc == Apache2::Const::DECLINED;
$rc = $r->runcheckuserid;
return $rc unless $rc == Apache2::Const::OK or $rc == Apache2::Const::DECLINED;
$rc = $r->runtypechecker;
return $rc unless $rc == Apache2::Const::OK or $rc == Apache2::Const::DECLINED;
$rc = $r->runfixups;
return $rc unless $rc == Apache2::Const::OK or $rc == Apache2::Const::DECLINED;
# $r->runhandler is called internally by $r->invokehandler,
# invokehandler sets all kind of filters, and does a few other
# things but it's possible to call $r->runhandler, bypassing
# invokehandler
$rc = $r->invokehandler;
return $rc unless $rc == Apache2::Const::OK or $rc == Apache2::Const::DECLINED;
$rc = $r->runlogtransaction;
return $rc unless $rc == Apache2::Const::OK or $rc == Apache2::Const::DECLINED;
return Apache2::Const::OK; } DDeessccrriippttiioonn"Apache2::HookRun" exposes parts of the Apache HTTP protocol
implementation, responsible for invoking callbacks for each HTTP Request cycle phase. Armed with that API, you could run some of the http protocol framework parts when implementing your own protocols. For example see how HTTP AAA (access, auth and authz) hooks are called from a protocol handler, implementing a command server, which has nothing to do with HTTP. Alsoyou can see in Synopsis how to re-implement Apache HTTP cycle in the
protocol handler. Using this API you could probably also change the normal Apache behavior (e.g. invoking some hooks earlier than normal, or later), but before doing that you will probably need to spend some time reading through the Apache C code. That's why some of the methods in this document, point you to the specific functions in the Apache source code. If you just try to use the methods from this module, without understanding them well, don't be surprised if you will get some nasty crashes, from which modperl can't protect you. AAPPII"Apache2::HookRun" provides the following functions and/or methods:
""ddiiee"" Kill the current request$r->die($type);
obj: $r ( "Apache2::RequestRec object" )
The current requestarg1: $type ( integer )
Why the request is dieing. Expects an Apache status constant. ret: no return value since: 2.0.00 This method doesn't really abort the request, it just handles the sending of the error response, logging the error and such. You want to take a look at the internals of "apdie()" inhttpd-2.0/modules/http/httprequest.c for more details.
""iinnvvookkeehhaannddlleerr"" Run the response phase.$rc = $r->invokehandler();
obj: $r ( "Apache2::RequestRec object" )
The current requestret: $rc ( integer )
The status of the current phase run: "Apache2::Const::OK", "Apache2::HTTP..." since: 2.0.00 "invokehandler()" allows modules to insert filters, sets a default handler if none is set, runs "runhandler()" and handles some errors. For more details see "apinvokehandler()" inhttpd-2.0/server/config.c.
""rruunnaacccceesssscchheecckkeerr"" Run the resource access control phase.$rc = $r->runaccesschecker();
obj: $r ( "Apache2::RequestRec object" )
the current requestret: $rc ( integer )
The status of the current phase run: "Apache2::Const::OK", "Apache2::Const::DECLINED", "Apache2::HTTP...". since: 2.0.00 This phase runs before a user is authenticated, so this hook is really to apply additional restrictions independent of a user. It also runs independent of '"Require"' directive usage. ""rruunnaauutthhcchheecckkeerr"" Run the authentication phase.$rc = $r->runauthchecker();
obj: $r ( "Apache2::RequestRec object" )
the current requestret: $rc ( integer )
The status of the current phase run: "Apache2::Const::OK", "Apache2::Const::DECLINED", "Apache2::HTTP...". since: 2.0.00 This phase is used to check to see if the resource being requested isavailable for the authenticated user ("$r->user" and
"$r->apauthtype").
It runs after the accesschecker and checkuserid hooks. Note that it will only be called if Apache determines that access control has been applied to this resource (through a '"Require"' directive). ""rruunncchheecckkuusseerriidd"" Run the authorization phase.$rc = $r->runcheckuserid();
obj: $r ( "Apache2::RequestRec object" )
The current requestret: $rc ( integer )
The status of the current phase run: "Apache2::Const::OK", "Apache2::Const::DECLINED", "Apache2::HTTP...". since: 2.0.00 This hook is used to analyze the request headers, authenticate theuser, and set the user information in the request record ("$r->user"
and "$r->apauthtype").
This hook is only run when Apache determines that authentication/authorization is required for this resource (as determined by the '"Require"' directive). It runs after the accesschecker hook, and before the authchecker hook. ""rruunnffiixxuuppss"" Run the fixup phase.$rc = $r->runfixups();
obj: $r ( "Apache2::RequestRec object" )
The current requestret: $rc ( integer )
The status of the current phase run: "Apache2::Const::OK", "Apache2::Const::DECLINED", "Apache2::HTTP...". since: 2.0.00This phase allows modules to perform module-specific fixing of HTTP
header fields. This is invoked just before the response phase. ""rruunnhhaannddlleerr"" Run the response phase.$rc = $r->runhandler();
obj: $r ( "Apache2::RequestRec object" )
The requestrecret: $rc ( integer )
The status of the current phase run: "Apache2::Const::OK", "Apache2::Const::DECLINED", "Apache2::HTTP...". since: 2.0.00 "runhandler()" is called internally by "invokehandler()". Use "runhandler()" only if you want to bypass the extra functionality provided by "invokehandler()". ""rruunnhheeaaddeerrppaarrsseerr"" Run the header parser phase.$rc = $r->runheaderparser();
obj: $r ( "Apache2::RequestRec object" )
The current requestret: $rc ( integer )
"Apache2::Const::OK" or "Apache2::Const::DECLINED". since: 2.0.00 ""rruunnllooggttrraannssaaccttiioonn"" Run the logging phase.$rc = $r->runlogtransaction();
obj: $r ( "Apache2::RequestRec object" )
The current requestret: $rc ( integer )
The status of the current phase run: "Apache2::Const::OK", "Apache2::Const::DECLINED", "Apache2::HTTP..." since: 2.0.00This hook allows modules to perform any module-specific logging
activities over and above the normal server things. ""rruunnmmaappttoossttoorraaggee"" Run the maptostorage phase.$rc = $r->runmaptostorage();
obj: $r ( "Apache2::RequestRec object" )
The current requestret: $rc ( integer )
"Apache2::Const::DONE" (or "Apache2::HTTP*") if this contextless request was just fulfilled (such as "TRACE"), "Apache2::Const::OK" if this is not a file, and "Apache2::Const::DECLINED" if this is a file. The core maptostorage ("Apache2::HOOKRUNLAST") will"directorywalk()" and "filewalk()" the "$r->filename" (all
internal C functions). since: 2.0.00 This phase allows modules to set the perdirconfig based on their own context (such as "" sections) and responds to contextless requests such as "TRACE" that need no security or filesystem mapping based on the filesystem. ""rruunnppoossttrreeaaddrreeqquueesstt"" Run the postreadrequest phase. $rc = $r->runpostreadrequest();
obj: $r ( "Apache2::RequestRec object" )
The current requestret: $rc ( integer )
The status of the current phase run: "Apache2::Const::OK" or "Apache2::Const::DECLINED". since: 2.0.00 This phase is run right after "readrequest()" or "internalredirect()", and not run during any subrequests. This hook allows modules to affect the request immediately after the request has been read, and before any other phases have been processes. This allows modules to make decisions based upon the input header fields ""rruunnttrraannssllaatteennaammee"" Run the translate phase.$rc = $r->runtranslatename();
obj: $r ( "Apache2::RequestRec object" )
The current requestret: $rc ( integer )
The status of the current phase run: "Apache2::Const::OK", "Apache2::Const::DECLINED", "Apache2::HTTP...". since: 2.0.00 This phase gives modules an opportunity to translate the URI into an actual filename. If no modules do anything special, the server's default rules will be applied. ""rruunnttyyppeecchheecckkeerr"" Run the typechecker phase.$rc = $r->runtypechecker();
obj: $r ( "Apache2::RequestRec object" )
the current requestret: $rc ( integer )
The status of the current phase run: "Apache2::Const::OK", "Apache2::Const::DECLINED", "Apache2::HTTP...". since: 2.0.00 This phase is used to determine and/or set the various document typeinformation bits, like "Content-type" (via "$r->contenttype"),
language, etc. 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.perl v5.a8p.a8chemodperl-101.1~2::mo2d00p5e-r1l0-22.00.2::docs::api::Apache2::HookRun(3)