Mailing List Archive

Okay... This is the information that I have. Where I've marked META,
could somebody answer those questions? Thanks!


=head1 NAME

Apache::RequestRec -- A Perl API for Apache request object

=head1 SYNOPSIS

use Apache::RequestRec;
sub handler{
my $r = shift;

my $s = $r->server;
my $dir_config = $r->dir_config;
...
}

=head1 DESCRIPTION

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

=head1 API

Function arguments (if any) and return values are shown in the
function's synopsis.

=head2 allowed()

$s = $r->allowed;

META: I don't know the purpose of allowed. Sample code or explanation
would be enlightening.

=head2 allowed_methods()

$s = $r->allowed_methods()

META: I don't know the purpose of allowed_methods. Sample code or
explanation would be enlightening.

=head2 allowed_xmethods()

$s = $r->allowed_xmethods()

META: I don't know the purpose of allowed_xmethods. Sample code or
explanation would be enlightening.

=head2 ap_auth_type()

C<$r-E<gt>ap_auth_type> gets or sets the I<ap_auth_type> slot in the
request record.

$r->ap_auth_type('Basic');

or

my $auth_type = $r->ap_auth_type;

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 args()

$s = $r->args();

Returns the arguments to the request, unparsed. In a GET request,
this will be the query string, not including the leading question
mark. If your calling URI is /foobar.pl?foo=bar, $r-E<gt>args() will
return "foo=bar".

=head2 assbackwards();

$s = $r->assbackwards();

META: I don't know the purpose of assbackwards. Sample code or
explanation would be enlightening.

=head2 bytes_sent()

$s = $r->bytes_sent();

Returns the number of bytes sent by a post query.

=head2 canonical_filename()

$s = $r->canonical_filename();

Returns the full path to the script calling it. See also C<filename()>.

META: What is the difference between canonical_filename() and filename()?

=head2 connection()

$s = $r->connection();

Returns the C<Apache::Connection> object for the current request,
which has information in it about the connection between the client
and server.

=head2 content_encoding();

$s = $r->content_encoding();

content_encoding() gets and sets the outgoing Content-Encoding header.
You could use this to use L<gzip> to compress the page, and then set the
content encoding to gzip, so that the client knows what encoding to use
to decode the content.:

[snip code to gzip the content]

$r->content_encoding('gzip');
$r->print($content);

=head2 content_languages();

$s = $r->content_languages();

content_languages() gets and sets the value of the outgoing
Content-Languages header. It takes as its argument a blessed reference
of unknown type as argument.

META: I don't know the purpose of content_languages or how to use it,
really. Sample code or explanation would be enlightening.

=head2 content_type();

$s = $r->content_type("text/html");

content_type() gets and sets the outgoing Content-type: headers in the
response. You could use this to display plain text:

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

or to display an HTML table in such a manner that an IE client would
automatically start its spreadsheet program:

$r->content_type("application/vnd.ms-excel");

=head2 err_headers_out()

$s = $r->err_headers_out();

Expects an C<L<APR::Table>> object. Returns an C<APR::Table> object.

META: I don't know the purpose of err_headers_out. Sample code or
explanation would be enlightening.

=head2 filename()

$s = $r->filename();

filename() returns the full path to the script running. See also
C<cannonical_filename()>

META: what is the difference between filename() and canonical_filename()?

=head2 handler()

$s = $r->handler();

handler() returns the type of handler (usually determined from the
apache server configuration file, e.g. PerlScript) used by mod_perl to
execute the calling script.

=head2 headers_in();

$s = $r->headers_in();

headers_in() returns an C<L<APR::Table>> object containing the headers
sent by the browser.

=head2 headers_out();

$s = $r->headers_out();

headers_out() returns an C<L<APR::Table>> object containing the
headers to be sent to the browser. If you modify the C<L<APR::Table>>
object and pass it back to headers_out, you define the headers.

$headers = $r->headers_out();
$headers->set("Author" => "Joe Smith");
$r->headers_out($headers);

META: Is there a more elegant way to do that?

=head2 hostname()

$s = $r->hostname();

hostname() gets and sets the host name on which the script was called.
This is usually the same as the Host: header in the headers_in
C<L<APR::Table>> object.

=head2 input_filters()

$s = $r->input_filters;

input filter returns an C<Apache::Filter> object.

META: A pointer to a document on filters would be grand! Is this the
same concept as what is described here:
http://perl.apache.org/docs/2.0/devel/core/mod_perl_specific.html ?

=head2 main()

$main_r = $r->main;

META: what is a sub-request? What is an internal redirect?

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/is_initial_req__>>.

=head2 method()

$s = $r->method();

method() sets and returns the method type of the request. This can be
GET, POST, PUT, etc.

=head2 method_number();

$s = $r->method_number();

META: Where can I find a table of these numbers used by mod_perl

=head2 mtime()

$s = $r->mtime();
META: The only output I seem to be able to generate with mtime() is 0.
Help.

=head2 next()

$s = $r->next();

META: I don't understand next and previous.

See also C<previous()>.

=head2 no_local_copy()

$s = $r->no_local_copy();

META: I don't understand the purpose of no_local_copy.

=head2 notes()

$s = $r->notes();

META: ?

=head2 output_filters()

$s = $r->output_filters();

=head2 path_info()

path_info() returns the information in the request after the uri for the
script. It includes the leading slash. e.g.:

The request was for the script at /perl/test.pl. The complete request
was /perl/test.pl/foobar.

$s = $r->path_info;

$s contains "/foobar".

=head2 per_dir_config()

$s = $r->per_dir_config()

Returns an C<Apache::ConfVector> object.

META: perl -MApache2 -MModPerl::MethodLookup -e print_object
Apache::ConfVector does not work.

=head2 pool()

Returns an C<APR::Pool> object.

META: I saw something about a pool object somewhere in the docs, but I
don't know where it was. Help!

=head2 prev()

See also C<next>.

=head2 proto_input_filters()

Returns an C<Apache::Filter> object.

=head2 proto_num()

$s = $r->proto_num();

Gets and sets the protocol number.

META: Where can I find a table linking protocols to protocol numbers?
(I'm actually guessing that this is a protocol number, and not a proto num).


=head2 proto_output_filters()

$s = $r->proto_output_filters();

Gets and sets the proto_output_filters. Returns an C<Apache::Filter>
object.

=head2 protocol()

$s = $r->protocol;

protocol() returns the protocol from the request. In a typical Web
request, this will be a variation of HTTP/1.1.

=head2 proxyreq()

$s = $r->proxyreq;

META: What does this do?

=head2 remaining()

$s = $r->remaining;

META: What does this do?

=head2 request_config()

$s = $r->request_config()

Returns an C<Apache::ConfVector> object.

META: What does this do?

=head2 server()

$s = $r->server();

Gets the C<Apache::Server> object for the server the request C<$r> is
running under.

=head2 status()

$s = $r->status();

Gets and sets the status code of the request. For a normally executed
script, this will be "200". But the standard response codes are available.

=head2 status_line()

$s = $r->status_line();

META: What does this do?

=head2 subprocess_env()

$s = $r->subprocess_env();

Returns an C<L<APR::Table>> object containing the environment variables
of the subprocess in which the script is executing. The environment
variables may include the standard CGI environment variables, as well as
others.

=head2 the_request()

$s = $r->the_request;

Returns the value of the request, as it would appear in an Apache
transfer log. E. g. GET /perl/test.pl HTTP/1.1

=head2 unparsed_uri()

$s = $r-E<gt>unparsed_uri

Returns the entire uri, not including the hostname or the schema. If
the request were for /perl/test.pl/foobar?foo=bar, the return value
would be /perl/test.pl/foobar?foo=bar.

=head2 uri()

$s = $r->uri

Returns the value of the uri of the request. This includes path info,
but not the query string. If the request were for
/perl/test.pl/foobar?foo=bar, the return value would be
/perl/test.pl/foobar.

=head2 used_path_info()

$s = $r->used_path_info();

META: What does this do? In my test script, all I could get it to
return was 2


META: Does dir_config() belong in the Apache::RequestRec
Documentation? Doesn't it belong in the Apache::RequestUtil or
Apache::ServerUtil documentation?

=head2 dir_config()

dir_config() provides an interface for the per-directory variable
specified by the C<PerlSetVar> and C<PerlAddVar> directives, and also
can be manipulated via the C<L<APR::Table|docs::2.0::api::APR::Table>>
methods.

The keys are case-insensitive.

$apr_table = $r->dir_config();

dir_config() called in a scalar context without the C<$key> argument
returns a I<HASH> reference blessed into the
C<L<APR::Table|docs::2.0::api::APR::Table>> class. This object can be
manipulated via the C<L<APR::Table|docs::2.0::api::APR::Table>>
methods. For available methods see
the C<L<APR::Table|docs::2.0::api::APR::Table>> manpage.

@values = $r->dir_config($key);

If the C<$key> argument is passed in the list context a list of all
matching values will be returned. This method is ineffective for big
tables, as it does a linear search of the table. Thefore avoid using
this way of calling dir_config() unless you know that there could be
more than one value for the wanted key and all the values are wanted.

$value = $r->dir_config($key);

If the C<$key> argument is passed in the scalar context only a single
value will be returned. Since the table preserves the insertion order,
if there is more than one value for the same key, the oldest value
assosiated with the desired key is returned. Calling in the scalar
context is also much faster, as it'll stop searching the table as soon
as the first match happens.

$r->dir_config($key => $val);

If the C<$key> and the C<$val> arguments are used, the set() operation
will happen: all existing values associated with the key C<$key> (and
the key itself) will be deleted and C<$value> will be placed instead.

$r->dir_config($key => undef);

If C<$val> is I<undef> the unset() operation will happen: all existing
values associated with the key C<$key> (and the key itself) will be
deleted.





=cut



---------------------------------------------------------------------
To unsubscribe, e-mail: docs-dev-unsubscribe@perl.apache.org
For additional commands, e-mail: docs-dev-help@perl.apache.org