Login | Register For Free | Help
Search for: (Advanced)

Mailing List Archive: ModPerl: Docs-dev

[mp2] Apache::RequestRec Documentation

 

 

ModPerl docs-dev RSS feed   Index | Next | Previous | View Threaded


jnerad at bellsouth

Jun 6, 2003, 7:46 AM

Post #1 of 5 (2267 views)
Permalink
[mp2] Apache::RequestRec Documentation

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 [at] perl
For additional commands, e-mail: docs-dev-help [at] perl


stas at stason

Jun 6, 2003, 5:10 PM

Post #2 of 5 (2163 views)
Permalink
Re: [mp2] Apache::RequestRec Documentation [In reply to]

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

Thanks a lot, Jack. Now most these META are already answered in the Apache
docs. So the first thing to do is to import these and only then polish them.
That's why I have suggested that you don't spend any time on these just yet.
I'll try to get things imported early next week (or may be Lyle will beat me
to it ;) and then you can start merging your doc on top of the existing docs.
Sounds OK?


__________________________________________________________________
Stas Bekman JAm_pH ------> Just Another mod_perl Hacker
http://stason.org/ mod_perl Guide ---> http://perl.apache.org
mailto:stas [at] stason http://use.perl.org http://apacheweek.com
http://modperlbook.org http://apache.org http://ticketmaster.com


---------------------------------------------------------------------
To unsubscribe, e-mail: docs-dev-unsubscribe [at] perl
For additional commands, e-mail: docs-dev-help [at] perl


jnerad at bellsouth

Jun 6, 2003, 8:25 PM

Post #3 of 5 (2155 views)
Permalink
Re: [mp2] Apache::RequestRec Documentation [In reply to]

Stas Bekman wrote:

> Jack Nerad wrote:
>
>> Okay... This is the information that I have. Where I've marked META,
>> could somebody answer those questions? Thanks!
>
>
> Thanks a lot, Jack. Now most these META are already answered in the
> Apache docs. So the first thing to do is to import these and only then
> polish them.
> That's why I have suggested that you don't spend any time on these
> just yet.


It isn't too much work to add what will be imported. So it is no big
deal. I just wanted to get what I had out there so that people could
look at it. I take it the imported documents will cover the Apache
request object, or something?

One of the questions I had was regarding dir_config being documented in
the Apache::RequestRec module. That didn't seem right to me, since it
isn't a method of that module. What are your thoughts? Should every
object method be documented, or should the methods be kept with their
modules?

>
> I'll try to get things imported early next week (or may be Lyle will
> beat me to it ;) and then you can start merging your doc on top of the
> existing docs. Sounds OK?


Aye Aye. <patiently waiting import>

--
Jack Nerad


---------------------------------------------------------------------
To unsubscribe, e-mail: docs-dev-unsubscribe [at] perl
For additional commands, e-mail: docs-dev-help [at] perl


stas at stason

Jun 6, 2003, 8:42 PM

Post #4 of 5 (2151 views)
Permalink
Re: [mp2] Apache::RequestRec Documentation [In reply to]

Jack Nerad wrote:
> Stas Bekman wrote:
>
>> Jack Nerad wrote:
>>
>>> Okay... This is the information that I have. Where I've marked META,
>>> could somebody answer those questions? Thanks!
>>
>>
>>
>> Thanks a lot, Jack. Now most these META are already answered in the
>> Apache docs. So the first thing to do is to import these and only then
>> polish them.
>> That's why I have suggested that you don't spend any time on these
>> just yet.
>
>
>
> It isn't too much work to add what will be imported. So it is no big
> deal. I just wanted to get what I had out there so that people could
> look at it. I take it the imported documents will cover the Apache
> request object, or something?

the imported docs will cover all methods. there are many more object types
than Apache::RequestRec

> One of the questions I had was regarding dir_config being documented in
> the Apache::RequestRec module. That didn't seem right to me, since it
> isn't a method of that module. What are your thoughts? Should every
> object method be documented, or should the methods be kept with their
> modules?

Every method will be documented in the manpage for the module which contains
it. For example dir_config belongs to Apache::RequestUtil and
Apache::ServerUtil. So it'll be documented there.

>> I'll try to get things imported early next week (or may be Lyle will
>> beat me to it ;) and then you can start merging your doc on top of the
>> existing docs. Sounds OK?
>
> Aye Aye. <patiently waiting import>

It's not a problem to import. We just wanted to make the import be formatted
in the best way, so we have little work to polish. Just to give you an idea:
there are more than 38 modules and there are hundreds of methods that need to
be documented.

Thanks for your patience.


__________________________________________________________________
Stas Bekman JAm_pH ------> Just Another mod_perl Hacker
http://stason.org/ mod_perl Guide ---> http://perl.apache.org
mailto:stas [at] stason http://use.perl.org http://apacheweek.com
http://modperlbook.org http://apache.org http://ticketmaster.com


---------------------------------------------------------------------
To unsubscribe, e-mail: docs-dev-unsubscribe [at] perl
For additional commands, e-mail: docs-dev-help [at] perl


stas at stason

Jan 14, 2004, 5:21 PM

Post #5 of 5 (2142 views)
Permalink
Re: [mp2] Apache::RequestRec Documentation [In reply to]

Jack Nerad wrote:
> Stas Bekman wrote:
>
>> Jack Nerad wrote:
>>
>>> Okay... This is the information that I have. Where I've marked META,
>>> could somebody answer those questions? Thanks!
>>
>>
>>
>> Thanks a lot, Jack. Now most these META are already answered in the
>> Apache docs. So the first thing to do is to import these and only then
>> polish them.
>> That's why I have suggested that you don't spend any time on these
>> just yet.
>
>
>
> It isn't too much work to add what will be imported. So it is no big
> deal. I just wanted to get what I had out there so that people could
> look at it. I take it the imported documents will cover the Apache
> request object, or something?
>
> One of the questions I had was regarding dir_config being documented in
> the Apache::RequestRec module. That didn't seem right to me, since it
> isn't a method of that module. What are your thoughts? Should every
> object method be documented, or should the methods be kept with their
> modules?
>
>>
>> I'll try to get things imported early next week (or may be Lyle will
>> beat me to it ;) and then you can start merging your doc on top of the
>> existing docs. Sounds OK?
>
>
>
> Aye Aye. <patiently waiting import>

Jack, sorry that it took more than 6 months (and actually almost 2 years since
first desired), but now the documentation skeletons for most of the API is
available. There are some 400+ methods in it, so we could really use help to
review the skeletons, add examples, etc. I'll post an call for help to the
modperl list soon.

Meanwhile if you can integrate your patches that you've sent earlier [1] that
would be very helpful. Make sure that you use cvs, since I update the pages
often now. Thanks.

(1) http://mathforum.org/epigone/modperl-docs-dev/vinolkring

__________________________________________________________________
Stas Bekman JAm_pH ------> Just Another mod_perl Hacker
http://stason.org/ mod_perl Guide ---> http://perl.apache.org
mailto:stas [at] stason http://use.perl.org http://apacheweek.com
http://modperlbook.org http://apache.org http://ticketmaster.com


---------------------------------------------------------------------
To unsubscribe, e-mail: docs-dev-unsubscribe [at] perl
For additional commands, e-mail: docs-dev-help [at] perl

ModPerl docs-dev RSS feed   Index | Next | Previous | View Threaded
 
 


Interested in having your list archived? Contact Gossamer Threads
 
  Web Applications & Managed Hosting Powered by Gossamer Threads Inc.