|
Apache::RequestRec - Perl API for Apache request record accessors |
allowedap_auth_typeargsassbackwardsbytes_sentconnectioncontent_encodingcontent_languagescontent_typeerr_headers_outfilenamefinfohandlerheader_onlyheaders_inheaders_outhostnameinput_filtersmainmethodmethod_numbermtimenextno_local_copynotesoutput_filterspath_infoper_dir_configpoolprevproto_input_filtersproto_numproto_output_filtersprotocolproxyreqrequest_timeserverstatusstatus_linesubprocess_envthe_requestunparsed_uriuriuser
Apache::RequestRec - Perl API for Apache request record accessors
use Apache::RequestRec ();
# set supported by the handler HTTP methods $allowed = $r->allowed();
# auth type $auth_type = $r->ap_auth_type();
# QUERY_STRING $args = $r->args();
# non-parsed-headers handler $status = $r->assbackwards();
# how many bytes were sent $bytes_sent = $r->bytes_sent();
# canonical filename $canon_filename = $r->canonical_filename();
# client connection record $c = $r->connection();
# "Content-Encoding" HTTP response header
$r->content_encoding("gzip");
# the languages of the content $languages = $r->content_languages();
# "Content-Encoding" HTTP response header
$r->content_type('text/plain');
# special response headers table $err_headers_out = $r->err_headers_out();
# request mapped filename $filename = $r->filename();
# request finfo $finfo = $r->finfo();
# 'SetHandler perl-script' equivalent
$r->handler('perl-script');
# was it a HEAD request? $status = $r->header_only();
# request input headers table $headers_in = $r->headers_in();
# request output headers table $headers_out = $r->headers_out();
# hostname $hostname = $r->hostname();
# input filters stack $input_filters = $r->input_filters();
# get the main request obj in a sub-request $main_r = $r->main();
# what's the current request (GET/POST/etc)? $method = $r->method();
# what's the current method number? $methnum = $r->method_number();
# current resource last modified time $mtime = $r->mtime();
# next request object (in redirect) $next_r = $r->next();
# there is no local copy $r->no_local_copy();
# Apache ascii notes table $notes = $r->notes();
# output filters stack $output_filters = $r->output_filters();
# PATH_INFO $path_info = $r->path_info();
# used in configuration directives modules $per_dir_config = $r->per_dir_config();
# pool with life span of the current request $p = $r->pool();
# previous request object in the internal redirect $prev_r = $r->prev();
# connection level input filters stack $proto_input_filters = $r->proto_input_filters();
# HTTP protocol version number $proto_num = $r->proto_num();
# connection level output filters stack $proto_output_filters = $r->proto_output_filters();
# the protocol, the client speaks: "HTTP/1.0", "HTTP/1.1", etc. $protocol = $r->protocol();
# is it a proxy request $status = $r->proxyreq($val);
# Time when the request started $request_time = $r->request_time();
# server object $s = $r->server();
# response status $status = $r->status();
# response status line $status_line = $r->status_line();
# manipulate %ENV of the subprocess $r->subprocess_env; $r->subprocess_env($key => $val);
# first HTTP request header $request = $r->the_request();
# the URI without any parsing performed $unparsed_uri = $r->unparsed_uri();
# The path portion of the URI $uri = $r->uri();
# auth username $user = $r->user();
Apache::RequestRec provides the Perl API for Apache request_rec
object.
The following packages extend the Apache::RequestRec functionality:
Apache::Access|docs::2.0::api::Apache::Access,
Apache::Log|docs::2.0::api::Apache::Log,
Apache::RequestIO|docs::2.0::api::Apache::RequestIO,
Apache::RequestUtil|docs::2.0::api::Apache::RequestUtil,
Apache::Response|docs::2.0::api::Apache::Response,
Apache::SubRequest|docs::2.0::api::Apache::SubRequest and
Apache::URI|docs::2.0::api::Apache::URI.
Apache::RequestRec provides the following functions and/or methods:
allowedGet/set the allowed methods bitmask.
$allowed = $r->allowed(); $prev_allowed = $r->allowed($new_allowed);
$r
( Apache::RequestRec object|docs::2.0::api::Apache::RequestRec )$new_allowed ( bitmask )$allowed ( bitmask )$allowed, which is a bitvector of the allowed methods.
If the $new_allowed argument is passed, the value before the change
is returned.
A handler must ensure that the request method is one that it is
capable of handling. Generally modules should Apache::DECLINE any
request methods they do not handle. Prior to aborting the handler
like this the handler should set $r->allowed to the list of
methods that it is willing to handle. This bitvector is used to
construct the "Allow:" header required for OPTIONS requests, and
Apache::HTTP_METHOD_NOT_ALLOWED (405) and
Apache::HTTP_NOT_IMPLEMENTED (501) status codes.
Since the default Apache handler deals with the OPTIONS method, all
response handlers can usually decline to deal with OPTIONS. For
example if the response handler handles only GET and POST
methods, and not OPTIONS, it may want to say:
use Apache::Const -compile => qw(OK DECLINED M_GET M_POST M_OPTIONS);
if ($r->method_number == Apache::M_OPTIONS) {
$r->allowed($r->allowed | (1<<Apache::M_GET) | (1<<Apache::M_POST));
return Apache::DECLINED;
}
TRACE is always allowed, modules don't need to set it explicitly.
Since the default_handler will always handle a GET, a module which
does *not* implement GET should probably return
Apache::HTTP_METHOD_NOT_ALLOWED. Unfortunately this means that a
script GET handler can't be installed by mod_actions.
For example, if the module can handle only POST method it could start with:
use Apache::Const -compile => qw(M_POST HTTP_METHOD_NOT_ALLOWED);
unless ($r->method_number == Apache::M_POST) {
$r->allowed($r->allowed | (1<<Apache::M_POST));
return Apache::HTTP_METHOD_NOT_ALLOWED;
}
ap_auth_typeIf an authentication check was made, get or set the ap_auth_type slot in the request record
$auth_type = $r->ap_auth_type(); $r->ap_auth_type($newval);
$r
( Apache::RequestRec object|docs::2.0::api::Apache::RequestRec )$newval (string)
$r->auth_type('Basic');
$auth_type (string)$newval is passed, nothing is returned. Otherwise the current
auth type is returned.
ap_auth_type holds the authentication type that has been negotiated
between the client and server during the actual request. Generally,
ap_auth_type is populated automatically when you call
$r->get_basic_auth_pw so you don't really need to worry too
much about it, but if you want to roll your own authentication
mechanism then you will have to populate ap_auth_type yourself.
Note that $r->ap_auth_type was
$r->connection->auth_type in the mod_perl 1.0 API.
argsGet/set the request QUERY string
$args = $r->args(); $prev_args = $r->args($new_args);
$r
( Apache::RequestRec object|docs::2.0::api::Apache::RequestRec )$new_args ( string )$args ( string )If $new_args was passed, returns the value before the change.
assbackwardsWhen set to a true value, Apache won't send any HTTP response headers allowing you to send any headers.
$status = $r->assbackwards(); $prev_status = $r->assbackwards($newval);
$r
( Apache::RequestRec object|docs::2.0::api::Apache::RequestRec )$newval (integer)$status (integer)If you send your own set of headers, which includes the Keep-Alive
HTTP response header, you must make sure to increment the number of
requests served over this connection (which is normally done by the
core connection output filter ap_http_header_filter, but skipped
when assbackwards is enabled).
$r->connection->keepalives($r->connection->keepalives + 1);
otherwise code relying on the value of
$r->connection->keepalives|docs::2.0::api::Apache::Connection/C_keepalives_
may malfunction. For example, this counter is used to tell when a new
request is coming in over the same connection to a filter that wants
to parse only HTTP headers (like
Apache::Filter::HTTPHeadersFixup). Of course you will need to set
$r->connection->keepalive(1)|docs::2.0::api::Apache::Connection/C_keepalive_
) as well.
bytes_sentThe number of bytes sent to the client, handy for logging, etc.
$bytes_sent = $r->bytes_sent();
$r
( Apache::RequestRec object|docs::2.0::api::Apache::RequestRec )$bytes_sent (integer)
connectionGet the client connection record
$c = $r->connection();
$r
( Apache::RequestRec object|docs::2.0::api::Apache::RequestRec )$c
( Apache::Connection object|docs::2.0::api::Apache::Connection )
content_encodingGet/set content encoding (the ``Content-Encoding'' HTTP header). Content encodings are string like ``gzip'' or ``compress''.
$ce = $r->content_encoding(); $prev_ce = $r->content_encoding($new_ce);
$r
( Apache::RequestRec object|docs::2.0::api::Apache::RequestRec )$new_ce ( string )$ce ( string )If $new_ce is passed, then the previous value is returned.
For example, here is how to send a gzip'ed response:
require Compress::Zlib;
$r->content_type("text/plain");
$r->content_encoding("gzip");
$r->print(Compress::Zlib::memGzip("some text to be gzipped));
content_languagesGet/set content languages (the "Content-Language" HTTP header).
Content languages are string like ``en'' or ``fr''.
$languages = $r->content_languages(); $prev_lang = $r->content_languages($nev_lang);
$r
( Apache::RequestRec object|docs::2.0::api::Apache::RequestRec )$new_lang ( ARRAY ref )$languages ( ARRAY ref )If $new_lang is passed, then the previous value is returned.
content_typeGet/set the HTTP response Content-type header value.
my $content_type = $r->content_type(); my $prev_content_type = $r->content_type($new_content_type);
$r
( Apache::RequestRec object|docs::2.0::api::Apache::RequestRec )$new_content_type (MIME type string)$content_typeIf $new_content_type was passed, the previous value is returned
instead.
For example, set the Content-type header to text/plain.
$r->content_type('text/plain');
If you set this header via the
headers_out|docs::2.0::api::Apache::RequestRec/C_headers_out_
table directly, it will be ignored by Apache. So do not do that.
err_headers_outGet/set MIME response headers, printed even on errors and persist across internal redirects.
$err_headers_out = $r->err_headers_out();
$r
( Apache::RequestRec object|docs::2.0::api::Apache::RequestRec )$err_headers_out
( APR::Table object|docs::2.0::api::APR::Table )The difference between headers_out|/C_headers_out_ and
err_headers_out, is that the latter are printed even on error, and
persist across internal redirects (so the headers printed for
ErrorDocument handlers will have them).
For example, if a handler wants to return a 404 response, but nevertheless to set a cookie, it has to be:
$r->err_headers_out->add('Set-Cookie' => $cookie);
return Apache::NOT_FOUND;
If the handler does:
$r->headers_out->add('Set-Cookie' => $cookie);
return Apache::NOT_FOUND;
the Set-Cookie header won't be sent.
filenameGet/set the filename on disk corresponding to this response (the result of the URI --> filename translation).
$filename = $r->filename(); $prev_filename = $r->filename($new_filename);
$r
( Apache::RequestRec object|docs::2.0::api::Apache::RequestRec )$new_filename ( string )$filename ( string )$new_filename argument was passed
finfoGet and set the finfo request record member:
$finfo = $r->finfo(); $r->finfo($finfo);
$r
( Apache::RequestRec object|docs::2.0::api::Apache::RequestRec )$finfo
( APR::Finfo object|docs::2.0::api::APR::Finfo )$finfo
( APR::Finfo object|docs::2.0::api::APR::Finfo )Due to the internal Apache implementation it's not possible to have
two different objects originating from $r->finfo at the same
time. Whenever $r->finfo is updated all objects will be updated
too to the latest value.
Most of the time, this method is used to get the finfo member. The
only reason you may want to set it is you need to use it before the
Apache's default map_to_storage phase is called.
Examples:
PerlMapToStorageHandler|docs::2.0::user::handlers::http/PerlMapToStorageHandler
phase):
use Apache::RequestRec (); use APR::Finfo (); print $r->finfo->fname;
finfo member (normally, before the
PerlMapToStorageHandler|docs::2.0::user::handlers::http/PerlMapToStorageHandler
phase):
use APR::Finfo (); use APR::Const -compile => qw(FINFO_NORM);
my $finfo = APR::Finfo::stat(__FILE__, APR::FINFO_NORM, $r->pool); $r->finfo($finfo);
handlerGet/set the equivalent of the SetHandler directive.
$handler = $r->handler(); $prev_handler = $r->handler($new_handler);
$r
( Apache::RequestRec object|docs::2.0::api::Apache::RequestRec )$new_handler ( string )$handler ( string )If $new_handler is passed, the previous value is returned.
header_onlyDid the client has asked for headers only? e.g. if the request method was HEAD.
$status = $r->header_only();
$r
( Apache::RequestRec object|docs::2.0::api::Apache::RequestRec )$status ( boolean )
headers_inGet/set the request MIME headers:
$headers_in = $r->headers_in();
$r
( Apache::RequestRec object|docs::2.0::api::Apache::RequestRec )$headers_in
( APR::Table object|docs::2.0::api::APR::Table )This table is available starting from the
PerlHeaderParserHandler|docs::2.0::user::handlers::http/PerlHeaderParserHandler
phase.
For example you can use it to retrieve the cookie value sent by the
client, in the Cookie: header:
my $cookie = $r->headers_in->{Cookie} || '';
headers_outGet/set MIME response headers, printed only on 2xx responses.
$headers_out = $r->headers_out();
$r
( Apache::RequestRec object|docs::2.0::api::Apache::RequestRec )$headers_out
( APR::Table object|docs::2.0::api::APR::Table )See also err_headers_out|/C_err_headers_out_, which allows to
set headers for non-2xx responses and persist across internal
redirects.
hostnameHost, as set by full URI or Host:
$hostname = $r->hostname();
$r
( Apache::RequestRec object|docs::2.0::api::Apache::RequestRec )$hostname ( string )
input_filtersGet/set the first filter in a linked list of request level input filters:
$input_filters = $r->input_filters(); $prev_input_filters = $r->input_filters($new_input_filters);
$r
( Apache::RequestRec object|docs::2.0::api::Apache::RequestRec )$new_input_filters$input_filters
( Apache::Filter object|docs::2.0::api::Apache::Filter )If $new_input_filters was passed, returns the previous value.
For example instead of using
$r->read()|docs::2.0::api::Apache::RequestIO/C_read_ to read
the POST data, one could use an explicit walk through incoming bucket
brigades to get that data. The following function read_post() does
just that (in fact that's what
$r->read()|docs::2.0::api::Apache::RequestIO/C_read_ does
behind the scenes):
use APR::Brigade (); use APR::Bucket (); use Apache::Filter ();
use Apache::Const -compile => qw(MODE_READBYTES); use APR::Const -compile => qw(SUCCESS BLOCK_READ);
use constant IOBUFSIZE => 8192;
sub read_post {
my $r = shift;
my $bb = APR::Brigade->new($r->pool,
$r->connection->bucket_alloc);
my $data = '';
my $seen_eos = 0;
do {
$r->input_filters->get_brigade($bb, Apache::MODE_READBYTES,
APR::BLOCK_READ, IOBUFSIZE);
for (my $b = $bb->first; $b; $b = $bb->next($b)) {
if ($b->is_eos) {
$seen_eos++;
last;
}
if ($b->read(my $buf)) {
$data .= $buf;
}
$b->remove; # optimization to reuse memory
}
} while (!$seen_eos);
$bb->destroy;
return $data;
}
As you can see $r->input_filters gives us a pointer to the last
of the top of the incoming filters stack.
mainGet the main request record
$main_r = $r->main();
$r
( Apache::RequestRec object|docs::2.0::api::Apache::RequestRec )$main_r
( Apache::RequestRec object|docs::2.0::api::Apache::RequestRec )undef.
To figure out whether you are inside a main request or a
sub-request/internal redirect, use
$r->is_initial_req|docs::2.0::api::Apache::RequestUtil/C_is_initial_req_.
methodGet/set the current request method (e.g. GET, HEAD, POST, etc.):
$method = $r->method(); $pre_method = $r->method($new_method);
$r
( Apache::RequestRec object|docs::2.0::api::Apache::RequestRec )$new_method ( string )$method ( string )if $new_method was passed the previous value is returned.
method_numberGet/set the HTTP method, issued by the client (Apache::M_GET,
Apache::M_POST, etc.)
$methnum = $r->method_number(); $prev_methnum = $r->method_number($new_methnum);
$r
( Apache::RequestRec object|docs::2.0::api::Apache::RequestRec )$new_methnum ( Apache::Const :methods
constant|docs::2.0::api::Apache::Const/C__methods_> )$methnum ( Apache::Const :methods
constant|docs::2.0::api::Apache::Const/C__methods_> )if $new_methnum was passed the previous value is returned.
See the $r->allowed|/C_allowed_ entry for examples.
mtimeLast modified time of the requested resource
$mtime = $r->mtime(); $prev_mtime = $r->mtime($new_mtime);
$r
( Apache::RequestRec object|docs::2.0::api::Apache::RequestRec )$new_mtime ( number )$mtime ( number )if $new_mtime was passed the previous value is returned.
nextPointer to the redirected request if this is an external redirect
$next_r = $r->next();
$r
( Apache::RequestRec object|docs::2.0::api::Apache::RequestRec )$next_r
( Apache::RequestRec object|docs::2.0::api::Apache::RequestRec )undef if there is no next request.
no_local_copyThere is no local copy of this response
$status = $r->no_local_copy();
$r
( Apache::RequestRec object|docs::2.0::api::Apache::RequestRec )$status (integer)Used internally in certain sub-requests to prevent sending
Apache::HTTP_NOT_MODIFIED for a fragment or error documents. For
example see the implementation in modules/filters/mod_include.c.
Also used internally in
$r->meets_conditions|docs::2.0::api::Apache::Response/C_meets_conditions_
-- if set to a true value, the conditions are always met.
notesGet/set text notes for the duration of this request. These notes can be passed from one module to another (not only mod_perl, but modules in any other language):
$notes = $r->notes(); $prev_notes = $r->notes($new_notes);
$r
( Apache::RequestRec object|docs::2.0::api::Apache::RequestRec )$new_notes
( APR::Table object|docs::2.0::api::APR::Table )$notes
( APR::Table object|docs::2.0::api::APR::Table )if the $new_notes argument was passed, returns the previous value.
If you want to pass Perl structures, you can use
$r->pnotes|docs::2.0::api::Apache::RequestUtil/C_pnotes_.
Also see
$c->notes|docs::2.0::api::Apache::Connection/C_notes_
output_filtersGet the first filter in a linked list of request level output filters:
$output_filters = $r->output_filters(); $prev_output_filters = $r->output_filters($new_output_filters);
$r
( Apache::RequestRec object|docs::2.0::api::Apache::RequestRec )$new_output_filters$output_filters
( Apache::Filter object|docs::2.0::api::Apache::Filter )If $new_output_filters was passed, returns the previous value.
For example instead of using
$r->print()|docs::2.0::api::Apache::RequestIO/C_print_ to
send the response body, one could send the data directly to the first
output filter. The following function send_response_body() does
just that:
use APR::Brigade (); use APR::Bucket (); use Apache::Filter ();
sub send_response_body {
my($r, $data) = @_;
my $bb = APR::Brigade->new($r->pool,
$r->connection->bucket_alloc);
my $b = APR::Bucket->new($data);
$bb->insert_tail($b);
$r->output_filters->fflush($bb);
$bb->destroy;
}
In fact that's what
$r->read()|docs::2.0::api::Apache::RequestIO/C_read_ does
behind the scenes. But it also knows to parse HTTP headers passed
together with the data and it also implements buffering, which the
above function does not.
path_infoGet/set the PATH_INFO, what is left in the path after the URI
--> filename translation:
$path_info = $r->path_info(); $prev_path_info = $r->path_info($path_info);
$r
( Apache::RequestRec object|docs::2.0::api::Apache::RequestRec )$path_info ( string )$path_info ( string )If the optional argument $path_info is passed, the previous value
is returned.
per_dir_configGet the dir config vector:
$per_dir_config = $r->per_dir_config();
$r
( Apache::RequestRec object|docs::2.0::api::Apache::RequestRec )$per_dir_config
( Apache::ConfVector object|docs::2.0::api::Apache::ConfVector )For an indepth discussion, refer to the Apache Server Configuration Customization in Perl chapter.
poolThe pool associated with the request
$p = $r->pool();
$r
( Apache::RequestRec object|docs::2.0::api::Apache::RequestRec )$p ( APR::Pool object|docs::2.0::api::APR::Pool )
prevPointer to the previous request if this is an internal redirect
$prev_r = $r->prev();
$r
( Apache::RequestRec object|docs::2.0::api::Apache::RequestRec )$prev_r ( Apache::RequestRec object|docs::2.0::api::Apache::RequestRec )undef if there is no previous request.
proto_input_filtersGet the first filter in a linked list of protocol level input filters:
$proto_input_filters = $r->proto_input_filters(); $prev_proto_input_filters = $r->proto_input_filters($new_proto_input_filters);
$r
( Apache::RequestRec object|docs::2.0::api::Apache::RequestRec )$new_proto_input_filters$proto_input_filters
( Apache::Filter object|docs::2.0::api::Apache::Filter )If $new_proto_input_filters was passed, returns the previous value.
$r->proto_input_filters points to the same filter as
$r->connection->input_filters|docs::2.0::api::Apache::Connection/C_input_filters_.
proto_numGet current request's HTTP protocol version number
$proto_num = $r->proto_num();
$r
( Apache::RequestRec object|docs::2.0::api::Apache::RequestRec )$proto_num (integer)
proto_output_filtersGet the first filter in a linked list of protocol level output filters:
$proto_output_filters = $r->proto_output_filters(); $prev_proto_output_filters = $r->proto_output_filters($new_proto_output_filters);
$r
( Apache::RequestRec object|docs::2.0::api::Apache::RequestRec )$new_proto_output_filters$proto_output_filters
( Apache::Filter object|docs::2.0::api::Apache::Filter )If $new_proto_output_filters was passed, returns the previous value.
$r->proto_output_filters points to the same filter as
$r->connection->output_filters|docs::2.0::api::Apache::Connection/C_output_filters_.
protocolGet a string identifying the protocol that the client speaks.
$protocol = $r->protocol();
$r
( Apache::RequestRec object|docs::2.0::api::Apache::RequestRec )$protocl ( string )"HTTP/1.0" or "HTTP/1.1".
If the client didn't specify the protocol version, the default is
"HTTP/0.9"
proxyreqGet/set the proxyrec request record member and optionally adjust other related fields.
$status = $r->proxyreq($val);
$r
( Apache::RequestRec object|docs::2.0::api::Apache::RequestRec )$val ( integer )$status ( integer )$val is 0 or 1, the proxyrec member will be set to that value
and previous value will be returned.
If $val is not passed, and $r->proxyreq is not true, and the
proxy request is matching the current vhost (scheme, hostname and
port), the proxyrec member will be set to 1 and that value will be
returned. In addition $r->uri is set to $r->unparsed_uri
and $r->filename is set to "modperl-proxy:".$r->uri. If
those conditions aren't true 0 is returned.
For example to turn a normal request into a proxy request to be
handled on the same server in the PerlTransHandler phase run:
my $real_url = $r->unparsed_uri;
$r->proxyreq(1);
$r->uri($real_url);
$r->filename("proxy:$real_url");
$r->handler('proxy-server');
Also remember that if you want to turn a proxy request into a non-proxy request, it's not enough to call:
$r->proxyreq(0);
You need to adjust $r->uri and $r->filename as well if
you run that code in PerlPostReadRequestHandler phase, since if you
don't -- mod_proxy's own post_read_request handler will override
your settings (as it will run after the mod_perl handler).
request_timeTime when the request started
$request_time = $r->request_time();
$r
( Apache::RequestRec object|docs::2.0::api::Apache::RequestRec )$request_time ( number )
serverGet the Apache::Server|docs::2.0::api::Apache::ServerRec object for
the server the request $r is running under.
$s = $r->server();
$r
( Apache::RequestRec object|docs::2.0::api::Apache::RequestRec )$s
( Apache::ServerRec object|docs::2.0::api::Apache::ServerRec )
statusGet/set the reply status for the client request.
$status = $r->status(); $prev_status = $r->status($new_status);
$r
( Apache::RequestRec object|docs::2.0::api::Apache::RequestRec )$new_status ( integer )$new_status is passed the new status is assigned.
Normally you would use some Apache::Const
constant|docs::2.0::api::Apache::Const>, e.g. Apache::REDIRECT.
$newval ( integer )If $new_status is passed the old value is returned.
Usually you will set this value indirectly by returning the status
code as the handler's function result. However, there are rare
instances when you want to trick Apache into thinking that the module
returned an Apache::OK status code, but actually send the browser a
non-OK status. This may come handy when implementing an HTTP proxy
handler. The proxy handler needs to send to the client, whatever
status code the proxied server has returned, while returning
Apache::OK to Apache. e.g.:
$r->status($some_code); return Apache::OK
See also $r->status_line|/C_status_line_, which. if set,
overrides $r->status.
status_lineGet/set the response status line. The status line is a string like
``200 Document follows'' and it will take precedence over the value
specified using the $r->status() described above.
$status_line = $r->status_line(); $prev_status_line = $r->status_line($new_status_line);
$r
( Apache::RequestRec object|docs::2.0::api::Apache::RequestRec )$new_status_line ( string )$status_line ( string )When discussing $r->status|/C_status_ we have mentioned that
sometimes a handler runs to a successful completion, but may need to
return a different code, which is the case with the proxy
server. Assuming that the proxy handler forwards to the client
whatever response the proxied server has sent, it'll usually use
status_line(), like so:
$r->status_line($response->code() . ' ' . $response->message()); return Apache::OK;
In this example $response could be for example an HTTP::Response
object, if LWP::UserAgent was used to implement the proxy.
This method is also handy when you extend the HTTP protocol and add new response codes. For example you could invent a new error code and tell Apache to use that in the response like so:
$r->status_line("499 We have been FooBared");
return Apache::OK;
Here 499 is the new response code, and We have been FooBared is
the custom response message.
subprocess_envGet/set the Apache subprocess_env table, or optionally set the
value of a named entry.
$r->subprocess_env;
$env_table = $r->subprocess_env;
$r->subprocess_env($key => $val);
$val = $r->subprocess_env($key);
$r
( Apache::RequestRec object|docs::2.0::api::Apache::RequestRec )$key ( string )$val ( string )...When called in VOID context with no arguments, it populate %ENV
with special variables (e.g. $ENV{QUERY_STRING}) like mod_cgi
does.
When called in a non-VOID context with no arguments, it returns an
APR::Table object|docs::2.0::api::APR::Table.
When the $key argument (string) is passed, it returns the
corresponding value (if such exists, or undef. The following two
lines are equivalent:
$val = $r->subprocess_env($key); $val = $r->subprocess_env->get($key);
When the $key and the $val arguments (strings) are passed, the
value is set. The following two lines are equivalent:
$r->subprocess_env($key => $val); $r->subprocess_env->set($key => $val);
The subprocess_env table|docs::2.0::api::APR::Table is used
by Apache::SubProcess|docs::2.0::api::Apache::SubProcess, to
pass environment variables to externally spawned processes. It's also
used by various Apache modules, and you should use this table to pass
the environment variables. For example if in
PerlHeaderParserHandler you do:
$r->subprocess_env(MyLanguage => "de");
you can then deploy mod_include and write in .shtml document:
<!--#if expr="$MyLanguage = en" --> English <!--#elif expr="$MyLanguage = de" --> Deutsch <!--#else --> Sorry <!--#endif -->
the_requestFirst HTTP request header
$request = $r->the_request();
$r
( Apache::RequestRec object|docs::2.0::api::Apache::RequestRec )$request ( string )GET /foo/bar/my_path_info?args=3 HTTP/1.0
unparsed_uriThe URI without any parsing performed
$unparsed_uri = $r->unparsed_uri();
$r
( Apache::RequestRec object|docs::2.0::api::Apache::RequestRec )$unparsed_uri ( string )If for example the request was:
GET /foo/bar/my_path_info?args=3 HTTP/1.0
$r->uri|/C_uri_ returns:
/foo/bar/my_path_info
whereas $r->unparsed_uri returns:
/foo/bar/my_path_info?args=3
uriThe path portion of the URI
$uri = $r->uri(); my $prec_uri = $r->uri($new_uri);
$r
( Apache::RequestRec object|docs::2.0::api::Apache::RequestRec )$new_uri ( string )$uri ( string )See the example in the $r->unparsed_uri|/C_unparsed_uri_
section.
userGet the user name, if an authentication process was successful. Or set it.
$user = $r->user(); $prev_user = $r->user($new_user);
$r
( Apache::RequestRec object|docs::2.0::api::Apache::RequestRec )$new_user ( string )$new_user to set a new value
$user ( string )If $new_user was passed, the previous value is returned.
For example, let's print the username passed by the client:
my($res, $sent_pw) = $r->get_basic_auth_pw; return $res if $res != Apache::OK; print "User: ", $r->user;
Apache::RequestRec 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.
allowed_methodsMETA: Autogenerated - needs to be reviewed/completed
List of allowed methods
$list = $r->allowed_methods();
$r
( Apache::RequestRec object|docs::2.0::api::Apache::RequestRec )$list
( Apache::MethodList object|docs::2.0::api::Apache::MethodList )META: Apache::MethodList is not available at the moment
allowed_xmethodsMETA: Autogenerated - needs to be reviewed/completed
Array of extension methods
$array = $r->allowed_xmethods();
$r
( Apache::RequestRec object|docs::2.0::api::Apache::RequestRec )$array
( APR::ArrayHeader object|docs::2.0::api::APR::ArrayHeader )META: APR::ArrayHeader is not available at the moment
request_configConfig vector containing pointers to request's per-server config structures
$ret = $r->request_config($newval);
$r
( Apache::RequestRec object|docs::2.0::api::Apache::RequestRec )$newval
( Apache::ConfVector object|docs::2.0::api::Apache::ConfVector )
used_path_infoMETA: Autogenerated - needs to be reviewed/completed
Flag for the handler to accept or reject path_info on the current request. All modules should respect the AP_REQ_ACCEPT_PATH_INFO and AP_REQ_REJECT_PATH_INFO values, while AP_REQ_DEFAULT_PATH_INFO indicates they may follow existing conventions. This is set to the user's preference upon HOOK_VERY_FIRST of the fixups.
$ret = $r->used_path_info($newval);
$r
( Apache::RequestRec object|docs::2.0::api::Apache::RequestRec )$newval (integer)
mod_perl 2.0 and its core modules are copyrighted under The Apache Software License, Version 2.0.
The mod_perl development team and numerous contributors.
|
Apache::RequestRec - Perl API for Apache request record accessors |