The Perl Toolchain Summit needs more sponsors. If your company depends on Perl, please support this very important event.

NAME

Apache::RequestRec - Perl API for Apache request record accessors

Synopsis

  use Apache::RequestRec ();

  sub handler{
      my $r = shift;
      ...
      my $auth_type = $r->auth_type;
      ...
      my $s = $r->server;
  }

META: to be completed

Description

Apache::RequestRec provides the Perl API for Apache request object.

API

Apache::RequestRec provides the following functions and/or methods:

proxyreq

Get and set the proxyrec request record member and optionally adjust other related fields.

  $ret = $r->proxyreq($val);
obj: $r (Apache::RequestRec)
arg1 opt: $val (integer)

0, 1 or none.

ret: $ret (integer)

If $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).

pool

META: Autogenerated - needs to be reviewed/completed

The pool associated with the request

  $p = $r->pool();
obj: $r (Apache::RequestRec)
ret: $p (APR::Pool)

connection

META: Autogenerated - needs to be reviewed/completed

The connection record to the client

  $c = $r->connection();
obj: $r (Apache::RequestRec)
ret: $c (Apache::Connection)

server

Get the Apache::Server object for the server the request $r is running under.

  $s = $r->server();
obj: $r (Apache::RequestRec)
ret: $s (Apache::Server)

next

META: Autogenerated - needs to be reviewed/completed

Pointer to the redirected request if this is an external redirect

  $next_r = $r->next();
obj: $r (Apache::RequestRec)
ret: $next_r (Apache::RequestRec)

prev

META: Autogenerated - needs to be reviewed/completed

Pointer to the previous request if this is an internal redirect

  $prev_r = $r->prev();
obj: $r (Apache::RequestRec)
ret: $prev_r (Apache::RequestRec)

main

Get the main request record

  $main_r = $r->main();
obj: $r (Apache::RequestRec)
ret: $main_r (Apache::RequestRec)

If the current request is a sub-request, this method returns a blessed reference to the main request structure. If the current request is the main request, then this method returns undef.

To figure out whether you are inside a main request or a sub-request/internal redirect, use $r->is_initial_req.

the_request

META: Autogenerated - needs to be reviewed/completed

First line of request

  $request = $r->the_request();
obj: $r (Apache::RequestRec)
ret: $request (string)

assbackwards

When set to a true value, Apache won't send any HTTP response headers allowing you to send any headers.

  $status = $r->assbackwards($newval);
  $status = $r->assbackwards();
obj: $r (Apache::RequestRec)
arg1 opt: $newval (integer)

assign a new state.

ret: $status (integer)

current state.

since: 1.99_10

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 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)) as well.

header_only

META: Autogenerated - needs to be reviewed/completed

HEAD request, as opposed to GET

  $status = $r->header_only();
obj: $r (Apache::RequestRec)
ret: $status (integer)

protocol

META: Autogenerated - needs to be reviewed/completed

Protocol string, as given to us, or HTTP/0.9

  $protocol = $r->protocol();
obj: $r (Apache::RequestRec)
ret: $protocl (string)

proto_num

META: Autogenerated - needs to be reviewed/completed

Protocol version number of protocol; 1.1 = 1001

  $proto_num = $r->proto_num();
obj: $r (Apache::RequestRec)
ret: $proto_num (integer)

hostname

META: Autogenerated - needs to be reviewed/completed

Host, as set by full URI or Host:

  $hostname = $r->hostname();
obj: $r (Apache::RequestRec)
ret: $hostname (string)

request_time

META: Autogenerated - needs to be reviewed/completed

Time when the request started

  $request_time = $r->request_time();
obj: $r (Apache::RequestRec)
ret: $request_time (number)

status_line

META: Autogenerated - needs to be reviewed/completed

Status line, if set by script

  $status_line = $r->status_line();
obj: $r (Apache::RequestRec)
ret: $status_line (string)

status

META: Autogenerated - needs to be reviewed/completed

Get/set status line

  $status = $r->status($new_status);
  $status = $r->status();
obj: $r (Apache::RequestRec)
opt arg2: $new_status (integer)

If $new_status is passed the new status is assigned.

ret: $newval (integer)

If $new_status is passed the old status is returned.

method

META: Autogenerated - needs to be reviewed/completed

Request method (eg. GET, HEAD, POST, etc.)

  $method = $r->method();
obj: $r (Apache::RequestRec)
ret: $method (string)

method_number

META: Autogenerated - needs to be reviewed/completed

Apache::M_GET, Apache::M_POST, etc.

  $methno = $r->method_number();
obj: $r (Apache::RequestRec)
ret: $methno (integer)

allowed

META: Autogenerated - needs to be reviewed/completed

'allowed' is a bitvector of the allowed methods.

  $allowed = $r->allowed();
obj: $r (Apache::RequestRec)
ret: $allowed (number)

A handler must ensure that the request method is one that it is capable of handling. Generally modules should 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 HTTP_METHOD_NOT_ALLOWED and HTTP_NOT_IMPLEMENTED status codes.

Since the default_handler deals with OPTIONS, all modules can usually decline to deal with OPTIONS. 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 HTTP_METHOD_NOT_ALLOWED. Unfortunately this means that a Script GET handler can't be installed by mod_actions.

allowed_xmethods

META: Autogenerated - needs to be reviewed/completed

Array of extension methods

  $array = $r->allowed_xmethods();
obj: $r (Apache::RequestRec)
ret: $array (APR::ArrayHeader)

allowed_methods

META: Autogenerated - needs to be reviewed/completed

List of allowed methods

  $list = $r->allowed_methods();
obj: $r (Apache::RequestRec)
ret: $list (Apache::MethodList)

bytes_sent

META: Autogenerated - needs to be reviewed/completed

body byte count, for easy access

  $bytes_sent = $r->bytes_sent();
obj: $r (Apache::RequestRec)
ret: $bytes_sent (integer)

mtime

META: Autogenerated - needs to be reviewed/completed

Last modified time of the requested resource

  $mtime = $r->mtime($new_mtime);
  $mtime = $r->mtime();
obj: $r (Apache::RequestRec)
opt arg2: $new_mtime (number)
ret: $mtime (number)

remaining

META: Autogenerated - needs to be reviewed/completed

Remaining bytes left to read from the request body

  $bytes = $r->remaining();

META: I think this method is not needed if the deprecated client_block methods aren't used, (and plain $r-<read() is used instead).

obj: $r (Apache::RequestRec)
ret: $bytes (integer)

headers_in

META: Autogenerated - needs to be reviewed/completed

  $headers_in = $r->headers_in();
obj: $r (Apache::RequestRec)
ret: $headers_in (APR::Table)

headers_out

META: Autogenerated - needs to be reviewed/completed

MIME header environment for the response

  $headers_out = $r->headers_out();
obj: $r (Apache::RequestRec)
ret: $headers_out (APR::Table)

err_headers_out

META: Autogenerated - needs to be reviewed/completed

MIME header environment for the response, printed even on errors and persist across internal redirects

  $err_headers_out = $r->err_headers_out();
obj: $r (Apache::RequestRec)
err: $err_headers_out (APR::Table)

The difference between 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).

notes

META: Autogenerated - needs to be reviewed/completed

Notes from one module to another

  $notes = $r->notes();
  $notes = $r->notes($new_notes);
obj: $r (Apache::RequestRec)
opt arg2: $new_notes (APR::Table)
ret: $notes (APR::Table)

The 'notes' is for notes from one module to another, with no other set purpose in mind...

handler

META: Autogenerated - needs to be reviewed/completed

  $handler = $r->handler();
  $handler = $r->handler($new_handler);
obj: $r (Apache::RequestRec)
opt arg2: $new_handler (string)
ret: $handler (string)

content_type

Get/set the HTTP response Content-type header value.

  my $content_type = $r->content_type();
  my $content_type = $r->content_type($new_content_type);
obj: $r (Apache::RequestRec)
arg1 opt: $new_content_type (MIME type/string)

Assign a new HTTP response content-type. It will affect the response only if HTTP headers weren't sent yet.

ret: $content_type

The current content-type value.

since 1.99_10

For example, set the Content-type header to text/plain.

  $r->content_type('text/plain');

If you set this header via the headers_out table directly, it will be ignored by Apache. So do not do that.

content_encoding

META: Autogenerated - needs to be reviewed/completed

  $ce = $r->content_encoding();
obj: $r (Apache::RequestRec)
ret: $ce (string)

content_languages

META: Autogenerated - needs to be reviewed/completed

Array of strings representing the content languages

  $array_header = $r->content_languages();
obj: $r (Apache::RequestRec)
ret: $array_header (APR::ArrayHeader)

user

META: Autogenerated - needs to be reviewed/completed

If an authentication check was made, this gets set to the user name.

  $r->user($user);
  $user = $r->user();
obj: $r (Apache::RequestRec)
opt arg2: $user (string)
ret: $user (string)

ap_auth_type

If 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);
obj: $r (Apache::RequestRec)
opt arg2: $newval (string)

If this argument is passed then a new auth type is assigned. For example:

  $r->auth_type('Basic');
ret: $auth_type (string)

If $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.

no_local_copy

META: Autogenerated - needs to be reviewed/completed

There is no local copy of this response

  $status = $r->no_local_copy();
obj: $r (Apache::RequestRec)
ret: $status (integer)

unparsed_uri

META: Autogenerated - needs to be reviewed/completed

The URI without any parsing performed

  $unparsed_uri = $r->unparsed_uri();
obj: $r (Apache::RequestRec)
ret: $unparsed_uri (string)

uri

META: Autogenerated - needs to be reviewed/completed

The path portion of the URI

  $uri = $r->uri();
  $r->uri($uri);
obj: $r (Apache::RequestRec)
opt arg2: $uri (string)
ret: $uri (string)

filename

META: Autogenerated - needs to be reviewed/completed

The filename on disk corresponding to this response

  $filename = $r->filename();
  $r->filename($filename);
obj: $r (Apache::RequestRec)
opt arg2: $filename (string)
ret: $filename (string)

canonical_filename

META: Autogenerated - needs to be reviewed/completed

  $canon_filename = $r->canonical_filename();
obj: $r (Apache::RequestRec)
ret: $canon_filename (string)

path_info

META: Autogenerated - needs to be reviewed/completed

The PATH_INFO extracted from this request

  $path_info = $r->path_info();
  $r->path_info($path_info);
obj: $r (Apache::RequestRec)
opt arg2: $path_info (string)
ret: $path_info (string)

args

META: Autogenerated - needs to be reviewed/completed

The QUERY_ARGS extracted from this request

  $args = $r->args();
  $r->args($args);
obj: $r (Apache::RequestRec)
opt arg2: $args (string)
ret: $args (string)

used_path_info

META: 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);
obj: $r (Apache::RequestRec)
arg1: $newval (integer)

per_dir_config

META: Autogenerated - needs to be reviewed/completed

These are config vectors, with one void* pointer for each module (the thing pointed to being the module's business). * Options set in config files, etc.

  $per_dir_config = $r->per_dir_config();
obj: $r (Apache::RequestRec)
ret: $per_dir_config (Apache::ConfVector)

request_config

META: Autogenerated - needs to be reviewed/completed

Notes on *this* request

  $ret = $r->request_config($newval);
obj: $r (Apache::RequestRec)
arg1: $newval (Apache::ConfVector)

output_filters

META: Autogenerated - needs to be reviewed/completed

A list of output filters to be used for this request

  $output_filters = $r->output_filters();
obj: $r (Apache::RequestRec)
ret: $output_filters (Apache::Filter)

input_filters

META: Autogenerated - needs to be reviewed/completed

A list of input filters to be used for this request

  $input_filters = $r->input_filters();
obj: $r (Apache::RequestRec)
ret: $input_filters (Apache::Filter)

proto_output_filters

META: Autogenerated - needs to be reviewed/completed

A list of protocol level output filters to be used for this request

  $proto_output_filters = $r->proto_output_filters();
obj: $r (Apache::RequestRec)
ret: $proto_output_filters (Apache::Filter)

proto_input_filters

META: Autogenerated - needs to be reviewed/completed

A list of protocol level input filters to be used for this request

  $proto_input_filters = $r->proto_input_filters();
obj: $r (Apache::RequestRec)
ret: $proto_input_filters (Apache::Filter)

See Also

mod_perl 2.0 documentation.

Copyright

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

Authors

The mod_perl development team and numerous contributors.