=head1 NAME

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




=head1 Synopsis

  use Apache::RequestRec ();

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

META: to be completed




=head1 Description


C<Apache::RequestRec> provides the Perl API for Apache request object.




=head1 API

C<Apache::RequestRec> provides the following functions and/or methods:




=head2 C<proxyreq>

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

  $ret = $r->proxyreq($val);

=over 4

=item arg1: C<$r> (C<L<Apache::RequestRec|docs::2.0::api::Apache::RequestRec>>)

=item arg2 opt: C<$val> (integer)

0, 1 or none.

=item ret: C<$ret> (integer)

If C<$val> is 0 or 1, the I<proxyrec> member will be set to that value
and previous value will be returned.

If C<$val> is not passed, and C<$r-E<gt>proxyreq> is not true, and the
proxy request is matching the current vhost (scheme, hostname and
port), the I<proxyrec> member will be set to 1 and that value will be
returned. In addition C<$r-E<gt>uri> is set to C<$r-E<gt>unparsed_uri>
and C<$r-E<gt>filename> is set to C<"modperl-proxy:".$r-E<gt>uri>. If
those conditions aren't true 0 is returned.

=back

For example to turn a normal request into a proxy request to be
handled on the same server in the C<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 C<$r-E<gt>uri> and C<$r-E<gt>filename> as well if
you run that code in C<PerlPostReadRequestHandler> phase, since if you
don't -- C<mod_proxy>'s own post_read_request handler will override
your settings (as it will run after the mod_perl handler).




=head2 C<pool>

META: Autogenerated - needs to be reviewed/completed

The pool associated with the request

  $p = $r->pool();

=over 4

=item arg1: C<$r> (C<L<Apache::RequestRec|docs::2.0::api::Apache::RequestRec>>)

=item ret: C<$p> (C<L<APR::Pool|docs::2.0::api::APR::Pool>>)

=back





=head2 C<connection>

META: Autogenerated - needs to be reviewed/completed

The connection record to the client

  $c = $r->connection();

=over 4

=item arg1: C<$r> (C<L<Apache::RequestRec|docs::2.0::api::Apache::RequestRec>>)

=item ret: C<$c> (C<L<Apache::Connection|docs::2.0::api::Apache::Connection>>)

=back





=head2 C<server>

Get the C<L<Apache::Server|docs::2.0::api::Apache::Server>> object for
the server the request C<$r> is running under.

  $s = $r->server();

=over 4

=item arg1: C<$r> (C<L<Apache::RequestRec|docs::2.0::api::Apache::RequestRec>>)

=item ret: C<$s> (C<L<Apache::Server|docs::2.0::api::Apache::Server>>)

=back





=head2 C<next>

META: Autogenerated - needs to be reviewed/completed

Pointer to the redirected request if this is an external redirect

  $next_r = $r->next();

=over 4

=item arg1: C<$r> (C<L<Apache::RequestRec|docs::2.0::api::Apache::RequestRec>>)

=item ret: C<$next_r> (C<L<Apache::RequestRec|docs::2.0::api::Apache::RequestRec>>)

=back





=head2 C<prev>

META: Autogenerated - needs to be reviewed/completed

Pointer to the previous request if this is an internal redirect

  $prev_r = $r->prev();

=over 4

=item arg1: C<$r> (C<L<Apache::RequestRec|docs::2.0::api::Apache::RequestRec>>)

=item ret: C<$prev_r> (C<L<Apache::RequestRec|docs::2.0::api::Apache::RequestRec>>)

=back





=head2 C<main>

Get the main request record

  $main_r = $r->main();

=over 4

=item arg1: C<$r> (C<L<Apache::RequestRec|docs::2.0::api::Apache::RequestRec>>)

=item ret: C<$main_r> (C<L<Apache::RequestRec|docs::2.0::api::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
C<L<$r-E<gt>is_initial_req|docs::2.0::api::Apache::RequestUtil/C_is_initial_req_>>.


=back





=head2 C<the_request>

META: Autogenerated - needs to be reviewed/completed

First line of request

  $request = $r->the_request();

=over 4

=item arg1: C<$r> (C<L<Apache::RequestRec|docs::2.0::api::Apache::RequestRec>>)

=item ret: C<$request> (string)

=back





=head2 C<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();

=over 4

=item arg1: C<$r> (C<L<Apache::RequestRec|docs::2.0::api::Apache::RequestRec>>)

=item arg2 opt: C<$newval> (integer)

assign a new state.

=item ret: C<$status> (integer)

current state.

=item since: 1.99_10

=back

If you send your own set of headers, which includes the C<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 C<ap_http_header_filter>, but skipped
when C<assbackwards> is enabled).

  $r->connection->keepalives($r->connection->keepalives + 1);

otherwise code relying on the value of
C<L<$r-E<gt>connection-E<gt>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
C<Apache::Filter::HTTPHeadersFixup>). Of course you will need to set
C<L<$r-E<gt>connection-E<gt>keepalive(1)|docs::2.0::api::Apache::Connection/C_keepalive_>>)
as well.



=head2 C<header_only>

META: Autogenerated - needs to be reviewed/completed

HEAD request, as opposed to GET

  $status = $r->header_only();

=over 4

=item arg1: C<$r> (C<L<Apache::RequestRec|docs::2.0::api::Apache::RequestRec>>)

=item ret: C<$status> (integer)

=back





=head2 C<protocol>

META: Autogenerated - needs to be reviewed/completed

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

  $protocol = $r->protocol();

=over 4

=item arg1: C<$r> (C<L<Apache::RequestRec|docs::2.0::api::Apache::RequestRec>>)

=item ret: C<$protocl> (string)

=back





=head2 C<proto_num>

META: Autogenerated - needs to be reviewed/completed

Protocol version number of protocol; 1.1 = 1001

  $proto_num = $r->proto_num();

=over 4

=item arg1: C<$r> (C<L<Apache::RequestRec|docs::2.0::api::Apache::RequestRec>>)

=item ret: C<$proto_num> (integer)

=back





=head2 C<hostname>

META: Autogenerated - needs to be reviewed/completed

Host, as set by full URI or Host:

  $hostname = $r->hostname();

=over 4

=item arg1: C<$r> (C<L<Apache::RequestRec|docs::2.0::api::Apache::RequestRec>>)

=item ret: C<$hostname> (string)

=back





=head2 C<request_time>

META: Autogenerated - needs to be reviewed/completed

Time when the request started

  $request_time = $r->request_time();

=over 4

=item arg1: C<$r> (C<L<Apache::RequestRec|docs::2.0::api::Apache::RequestRec>>)

=item ret: C<$request_time> (number)

=back





=head2 C<status_line>

META: Autogenerated - needs to be reviewed/completed

Status line, if set by script

  $status_line = $r->status_line();

=over 4

=item arg1: C<$r> (C<L<Apache::RequestRec|docs::2.0::api::Apache::RequestRec>>)

=item ret: C<$status_line> (string)

=back





=head2 C<status>

META: Autogenerated - needs to be reviewed/completed

Get/set status line

  $status = $r->status($new_status);
  $status = $r->status();

=over 4

=item arg1: C<$r> (C<L<Apache::RequestRec|docs::2.0::api::Apache::RequestRec>>)

=item opt arg2: C<$new_status> (integer)

If C<$new_status> is passed the new status is assigned.

=item ret: C<$newval> (integer)

If C<$new_status> is passed the old status is returned.

=back





=head2 C<method>

META: Autogenerated - needs to be reviewed/completed

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

  $method = $r->method();

=over 4

=item arg1: C<$r> (C<L<Apache::RequestRec|docs::2.0::api::Apache::RequestRec>>)

=item ret: C<$method> (string)

=back





=head2 C<method_number>

META: Autogenerated - needs to be reviewed/completed

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

  $methno = $r->method_number();

=over 4

=item arg1: C<$r> (C<L<Apache::RequestRec|docs::2.0::api::Apache::RequestRec>>)

=item ret: C<$methno> (integer)

=back





=head2 C<allowed>

META: Autogenerated - needs to be reviewed/completed

'allowed' is a bitvector of the allowed methods.

  $allowed = $r->allowed();

=over 4

=item arg1: C<$r> (C<L<Apache::RequestRec|docs::2.0::api::Apache::RequestRec>>)

=item ret: C<$allowed> (number)

=back

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-E<gt>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.



=head2 C<allowed_xmethods>

META: Autogenerated - needs to be reviewed/completed

Array of extension methods

  $array = $r->allowed_xmethods();

=over 4

=item arg1: C<$r> (C<L<Apache::RequestRec|docs::2.0::api::Apache::RequestRec>>)

=item ret: C<$array> (C<L<APR::ArrayHeader|docs::2.0::api::APR::ArrayHeader>>)

=back





=head2 C<allowed_methods>

META: Autogenerated - needs to be reviewed/completed

List of allowed methods

  $list = $r->allowed_methods();

=over 4

=item arg1: C<$r> (C<L<Apache::RequestRec|docs::2.0::api::Apache::RequestRec>>)

=item ret: C<$list> (C<L<Apache::MethodList|docs::2.0::api::Apache::MethodList>>)

=back





=head2 C<bytes_sent>

META: Autogenerated - needs to be reviewed/completed

body byte count, for easy access

  $bytes_sent = $r->bytes_sent();

=over 4

=item arg1: C<$r> (C<L<Apache::RequestRec|docs::2.0::api::Apache::RequestRec>>)

=item ret: C<$bytes_sent> (integer)

=back





=head2 C<mtime>

META: Autogenerated - needs to be reviewed/completed

Last modified time of the requested resource

  $mtime = $r->mtime($new_mtime);
  $mtime = $r->mtime();

=over 4

=item arg1: C<$r> (C<L<Apache::RequestRec|docs::2.0::api::Apache::RequestRec>>)

=item opt arg2: C<$new_mtime> (number)

=item ret: C<$mtime> (number)

=back





=head2 C<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-E<lt>read() is used instead).

=over 4

=item arg1: C<$r> (C<L<Apache::RequestRec|docs::2.0::api::Apache::RequestRec>>)

=item ret: C<$bytes> (integer)

=back





=head2 C<headers_in>

META: Autogenerated - needs to be reviewed/completed

  $headers_in = $r->headers_in();

=over 4

=item arg1: C<$r> (C<L<Apache::RequestRec|docs::2.0::api::Apache::RequestRec>>)

=item ret: C<$headers_in> (C<L<APR::Table|docs::2.0::api::APR::Table>>)

=back


=head2 C<headers_out>

META: Autogenerated - needs to be reviewed/completed

MIME header environment for the response

  $headers_out = $r->headers_out();

=over 4

=item arg1: C<$r> (C<L<Apache::RequestRec|docs::2.0::api::Apache::RequestRec>>)

=item ret: C<$headers_out> (C<L<APR::Table|docs::2.0::api::APR::Table>>)

=back





=head2 C<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();

=over 4

=item arg1: C<$r> (C<L<Apache::RequestRec|docs::2.0::api::Apache::RequestRec>>)

=item err: C<$err_headers_out> (C<L<APR::Table|docs::2.0::api::APR::Table>>)

=back


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





=head2 C<notes>

META: Autogenerated - needs to be reviewed/completed

Notes from one module to another

  $notes = $r->notes();
  $notes = $r->notes($new_notes);

=over 4

=item arg1: C<$r> (C<L<Apache::RequestRec|docs::2.0::api::Apache::RequestRec>>)

=item opt arg2: C<$new_notes> (C<L<APR::Table|docs::2.0::api::APR::Table>>)

=item ret: C<$notes> (C<L<APR::Table|docs::2.0::api::APR::Table>>)


=back

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



=head2 C<handler>

META: Autogenerated - needs to be reviewed/completed

  $handler = $r->handler();
  $handler = $r->handler($new_handler);

=over 4

=item arg1: C<$r> (C<L<Apache::RequestRec|docs::2.0::api::Apache::RequestRec>>)

=item opt arg2: C<$new_handler> (string)

=item ret: C<$handler> (string)

=back





=head2 C<content_type>

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

  my $content_type = $r->content_type();
  my $content_type = $r->content_type($new_content_type);

=over 4

=item arg1: C<$r> (C<L<Apache::RequestRec|docs::2.0::api::Apache::RequestRec>>)

=item arg2 opt: C<$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.

=item ret: C<$content_type>

The current content-type value.

=item since 1.99_10

=back

For example, set the C<Content-type> header to I<text/plain>.

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

If you set this header via the
C<L<headers_out|docs::2.0::api::Apache::RequestRec/C_headers_out_>>
table directly, it will be ignored by Apache. So do not do that.


=head2 C<content_encoding>

META: Autogenerated - needs to be reviewed/completed



  $ce = $r->content_encoding();

=over 4

=item arg1: C<$r> (C<L<Apache::RequestRec|docs::2.0::api::Apache::RequestRec>>)

=item ret: C<$ce> (string)

=back





=head2 C<content_languages>

META: Autogenerated - needs to be reviewed/completed

Array of strings representing the content languages

  $array_header = $r->content_languages();

=over 4

=item arg1: C<$r> (C<L<Apache::RequestRec|docs::2.0::api::Apache::RequestRec>>)

=item ret: C<$array_header> (C<L<APR::ArrayHeader|docs::2.0::api::APR::ArrayHeader>>)

=back





=head2 C<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();

=over 4

=item arg1: C<$r> (C<L<Apache::RequestRec|docs::2.0::api::Apache::RequestRec>>)

=item opt arg2: C<$user> (string)

=item ret: C<$user> (string)

=back





=head2 C<ap_auth_type>

If an authentication check was made, get or set the I<ap_auth_type>
slot in the request record

  $auth_type = $r->ap_auth_type();
  $r->ap_auth_type($newval);

=over 4

=item arg1: C<$r> (C<L<Apache::RequestRec|docs::2.0::api::Apache::RequestRec>>)

=item opt arg2: C<$newval> (string)

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

  $r->auth_type('Basic');

=item ret: C<$auth_type> (string)

If C<$newval> is passed, nothing is returned. Otherwise the current
auth type is returned.

=back

I<ap_auth_type> holds the authentication type that has been negotiated
between the client and server during the actual request.  Generally,
I<ap_auth_type> is populated automatically when you call
C<$r-E<gt>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 I<ap_auth_type> yourself.

Note that C<$r-E<gt>ap_auth_type> was
C<$r-E<gt>connection-E<gt>auth_type> in the mod_perl 1.0 API.



=head2 C<no_local_copy>

META: Autogenerated - needs to be reviewed/completed

There is no local copy of this response

  $status = $r->no_local_copy();

=over 4

=item arg1: C<$r> (C<L<Apache::RequestRec|docs::2.0::api::Apache::RequestRec>>)

=item ret: C<$status> (integer)

=back





=head2 C<unparsed_uri>

META: Autogenerated - needs to be reviewed/completed

The URI without any parsing performed

  $unparsed_uri = $r->unparsed_uri();

=over 4

=item arg1: C<$r> (C<L<Apache::RequestRec|docs::2.0::api::Apache::RequestRec>>)

=item ret: C<$unparsed_uri> (string)

=back





=head2 C<uri>

META: Autogenerated - needs to be reviewed/completed

The path portion of the URI

  $uri = $r->uri();
  $r->uri($uri);

=over 4

=item arg1: C<$r> (C<L<Apache::RequestRec|docs::2.0::api::Apache::RequestRec>>)

=item opt arg2: C<$uri> (string)

=item ret: C<$uri> (string)

=back





=head2 C<filename>

META: Autogenerated - needs to be reviewed/completed

The filename on disk corresponding to this response

  $filename = $r->filename();
  $r->filename($filename);

=over 4

=item arg1: C<$r> (C<L<Apache::RequestRec|docs::2.0::api::Apache::RequestRec>>)

=item opt arg2: C<$filename> (string)

=item ret: C<$filename> (string)

=back





=head2 C<canonical_filename>

META: Autogenerated - needs to be reviewed/completed



  $canon_filename = $r->canonical_filename();

=over 4

=item arg1: C<$r> (C<L<Apache::RequestRec|docs::2.0::api::Apache::RequestRec>>)

=item ret: C<$canon_filename> (string)

=back





=head2 C<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);

=over 4

=item arg1: C<$r> (C<L<Apache::RequestRec|docs::2.0::api::Apache::RequestRec>>)

=item opt arg2: C<$path_info> (string)

=item ret: C<$path_info> (string)

=back





=head2 C<args>

META: Autogenerated - needs to be reviewed/completed

The QUERY_ARGS extracted from this request

  $args = $r->args();
  $r->args($args);

=over 4

=item arg1: C<$r> (C<L<Apache::RequestRec|docs::2.0::api::Apache::RequestRec>>)

=item opt arg2: C<$args> (string)

=item ret: C<$args> (string)

=back





=head2 C<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);

=over 4

=item arg1: C<$r> (C<L<Apache::RequestRec|docs::2.0::api::Apache::RequestRec>>)

=item arg2: C<$newval> (integer)

=back





=head2 C<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();

=over 4

=item arg1: C<$r> (C<L<Apache::RequestRec|docs::2.0::api::Apache::RequestRec>>)

=item ret: C<$per_dir_config> (C<L<Apache::ConfVector|docs::2.0::api::Apache::ConfVector>>)

=back





=head2 C<request_config>

META: Autogenerated - needs to be reviewed/completed

Notes on *this* request

  $ret = $r->request_config($newval);

=over 4

=item arg1: C<$r> (C<L<Apache::RequestRec|docs::2.0::api::Apache::RequestRec>>)

=item arg2: C<$newval> (C<L<Apache::ConfVector|docs::2.0::api::Apache::ConfVector>>)

=back





=head2 C<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();

=over 4

=item arg1: C<$r> (C<L<Apache::RequestRec|docs::2.0::api::Apache::RequestRec>>)

=item ret: C<$output_filters> (C<L<Apache::Filter|docs::2.0::api::Apache::Filter>>)

=back





=head2 C<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();

=over 4

=item arg1: C<$r> (C<L<Apache::RequestRec|docs::2.0::api::Apache::RequestRec>>)

=item ret: C<$input_filters> (C<L<Apache::Filter|docs::2.0::api::Apache::Filter>>)

=back





=head2 C<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();

=over 4

=item arg1: C<$r> (C<L<Apache::RequestRec|docs::2.0::api::Apache::RequestRec>>)

=item ret: C<$proto_output_filters> (C<L<Apache::Filter|docs::2.0::api::Apache::Filter>>)

=back





=head2 C<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();

=over 4

=item arg1: C<$r> (C<L<Apache::RequestRec|docs::2.0::api::Apache::RequestRec>>)

=item ret: C<$proto_input_filters> (C<L<Apache::Filter|docs::2.0::api::Apache::Filter>>)

=back




=head1 See Also

L<mod_perl 2.0 documentation|docs::2.0::index>.




=head1 Copyright

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




=head1 Authors

L<The mod_perl development team and numerous
contributors|about::contributors::people>.

=cut

