stas 2004/08/01 22:34:14
Modified: src/docs/2.0/api/Apache RequestRec.pod
Log:
finally complete Apache::RequestRec
Revision Changes Path
1.25 +424 -146 modperl-docs/src/docs/2.0/api/Apache/RequestRec.pod
Index: RequestRec.pod
===================================================================
RCS file: /home/cvs/modperl-docs/src/docs/2.0/api/Apache/RequestRec.pod,v
retrieving revision 1.24
retrieving revision 1.25
diff -u -u -r1.24 -r1.25
--- RequestRec.pod 24 Jul 2004 09:27:37 -0000 1.24
+++ RequestRec.pod 2 Aug 2004 05:34:13 -0000 1.25
@@ -8,16 +8,139 @@
=head1 Synopsis
use Apache::RequestRec ();
-
- sub handler{
- my $r = shift;
- ...
- my $auth_type = $r->auth_type;
- ...
- my $s = $r->server;
- }
-
-META: to be completed
+
+ # 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");
+
+ # "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();
@@ -203,7 +326,7 @@
=item obj: C<$r>
( C<L<Apache::RequestRec object|docs::2.0::api::Apache::RequestRec>> )
-=item arg1 opt: C<$newval> (integer)
+=item opt arg1: C<$newval> (integer)
assign a new state.
@@ -262,25 +385,6 @@
-=head2 C<canonical_filename>
-
-META: Autogenerated - needs to be reviewed/completed
-
-XXX: The true filename, we canonicalize r-E<gt>filename if these don't
-match
-
- $canon_filename = $r->canonical_filename();
-
-=over 4
-
-=item obj: C<$r>
-( C<L<Apache::RequestRec object|docs::2.0::api::Apache::RequestRec>> )
-
-=item ret: C<$canon_filename> ( string )
-
-=item since: 1.99_12
-
-=back
@@ -680,6 +784,8 @@
+
+
=head2 C<input_filters>
Get/set the first filter in a linked list of request level input
@@ -861,11 +967,11 @@
=item opt arg1: C<$new_mtime> ( number )
-a new value
+a new value (in microseconds).
=item ret: C<$mtime> ( number )
-the current value.
+the current value (in microseconds).
if C<$new_mtime> was passed the previous value is returned.
@@ -933,6 +1039,10 @@
+
+
+
+
=head2 C<notes>
Get/set text notes that can be passed from one module to another (not
@@ -1037,12 +1147,11 @@
=head2 C<path_info>
-META: Autogenerated - needs to be reviewed/completed
-
-The PATH_INFO extracted from this request
+Get/set the C<PATH_INFO>, what is left in the path after the I<URI
+--E<gt> filename> translation:
- $path_info = $r->path_info();
- $r->path_info($path_info);
+ $path_info = $r->path_info();
+ $prev_path_info = $r->path_info($path_info);
=over 4
@@ -1051,8 +1160,15 @@
=item opt arg1: C<$path_info> ( string )
+Set a new value
+
=item ret: C<$path_info> ( string )
+Return the current value.
+
+If the optional argument C<$path_info> is passed, the previous value
+is returned.
+
=item since: 1.99_12
=back
@@ -1064,11 +1180,7 @@
=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.
+Get the dir config vector:
$per_dir_config = $r->per_dir_config();
@@ -1077,12 +1189,18 @@
=item obj: C<$r>
( C<L<Apache::RequestRec object|docs::2.0::api::Apache::RequestRec>> )
-=item ret: C<$per_dir_config> ( C<L<Apache::ConfVector
object|docs::2.0::api::Apache::ConfVector>> )
+=item ret: C<$per_dir_config>
+( C<L<Apache::ConfVector object|docs::2.0::api::Apache::ConfVector>> )
=item since: 1.99_12
=back
+For an indepth discussion, refer to the L<Apache Server Configuration
+Customization in Perl chapter|docs::2.0::user::config::custom>.
+
+
+
@@ -1110,6 +1228,8 @@
+
+
=head2 C<prev>
Pointer to the previous request if this is an internal redirect
@@ -1170,11 +1290,11 @@
-=head2 C<proto_num>
-META: Autogenerated - needs to be reviewed/completed
-Protocol version number of protocol; 1.1 = 1001
+=head2 C<proto_num>
+
+Get current request's HTTP protocol version number
$proto_num = $r->proto_num();
@@ -1185,6 +1305,9 @@
=item ret: C<$proto_num> (integer)
+current request's HTTP protocol version number, e.g.: HTTP/1.0 ==
+1000, HTTP/1.1 = 1001
+
=item since: 1.99_12
=back
@@ -1193,6 +1316,8 @@
+
+
=head2 C<proto_output_filters>
Get the first filter in a linked list of protocol level output
@@ -1232,9 +1357,7 @@
=head2 C<protocol>
-META: Autogenerated - needs to be reviewed/completed
-
-Protocol string, as given to us, or HTTP/0.9
+Get a string identifying the protocol that the client speaks.
$protocol = $r->protocol();
@@ -1245,6 +1368,11 @@
=item ret: C<$protocl> ( string )
+Typical values are C<"HTTP/1.0"> or C<"HTTP/1.1">.
+
+If the client didn't specify the protocol version, the default is
+C<"HTTP/0.9">
+
=item since: 1.99_12
=back
@@ -1253,23 +1381,24 @@
+
=head2 C<proxyreq>
-Get and set the I<proxyrec> request record member and optionally
-adjust other related fields.
+Get/set the I<proxyrec> request record member and optionally adjust
+other related fields.
- $ret = $r->proxyreq($val);
+ $status = $r->proxyreq($val);
=over 4
=item obj: C<$r>
( C<L<Apache::RequestRec object|docs::2.0::api::Apache::RequestRec>> )
-=item arg1 opt: C<$val> (integer)
+=item opt arg1: C<$val> ( integer )
0, 1 or none.
-=item ret: C<$ret> (integer)
+=item ret: C<$status> ( integer )
If C<$val> is 0 or 1, the I<proxyrec> member will be set to that value
and previous value will be returned.
@@ -1310,23 +1439,22 @@
-=head2 C<remaining>
-META: Autogenerated - needs to be reviewed/completed
-Remaining bytes left to read from the request body
+=head2 C<request_time>
- $bytes = $r->remaining();
+Time when the request started
-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).
+ $request_time = $r->request_time();
=over 4
=item obj: C<$r>
( C<L<Apache::RequestRec object|docs::2.0::api::Apache::RequestRec>> )
-=item ret: C<$bytes> (integer)
+=item ret: C<$request_time> ( number )
+
+(in microseconds).
=item since: 1.99_12
@@ -1338,20 +1466,20 @@
-=head2 C<request_config>
-
-META: Autogenerated - needs to be reviewed/completed
+=head2 C<server>
-Notes on *this* request
+Get the C<L<Apache::Server|docs::2.0::api::Apache::ServerRec>> object for
+the server the request C<$r> is running under.
- $ret = $r->request_config($newval);
+ $s = $r->server();
=over 4
=item obj: C<$r>
( C<L<Apache::RequestRec object|docs::2.0::api::Apache::RequestRec>> )
-=item arg1: C<$newval> ( C<L<Apache::ConfVector
object|docs::2.0::api::Apache::ConfVector>> )
+=item ret: C<$s>
+( C<L<Apache::ServerRec object|docs::2.0::api::Apache::ServerRec>> )
=item since: 1.99_12
@@ -1363,121 +1491,185 @@
-=head2 C<request_time>
-
-META: Autogenerated - needs to be reviewed/completed
+=head2 C<status>
-Time when the request started
+Get/set the reply status for the client request.
- $request_time = $r->request_time();
+ $status = $r->status();
+ $prev_status = $r->status($new_status);
=over 4
=item obj: C<$r>
( C<L<Apache::RequestRec object|docs::2.0::api::Apache::RequestRec>> )
-=item ret: C<$request_time> (number)
+=item opt arg1: C<$new_status> ( integer )
-=item since: 1.99_12
+If C<$new_status> is passed the new status is assigned.
-=back
+Normally you would use some C<L<Apache::Const
+constant|docs::2.0::api::Apache::Const>>, e.g. C<Apache::REDIRECT>.
+=item ret: C<$newval> ( integer )
+The current value.
+If C<$new_status> is passed the old value is returned.
+=item since: 1.99_12
+=back
-=head2 C<server>
+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 C<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
+C<Apache::OK> to Apache. e.g.:
-Get the C<L<Apache::Server|docs::2.0::api::Apache::ServerRec>> object for
-the server the request C<$r> is running under.
+ $r->status($some_code);
+ return Apache::OK
- $s = $r->server();
+See also C<L<$r-E<gt>status_line|/C_status_line_>>, which. if set,
+overrides C<$r-E<gt>status>.
-=over 4
-=item obj: C<$r>
-( C<L<Apache::RequestRec object|docs::2.0::api::Apache::RequestRec>> )
-=item ret: C<$s> ( C<L<Apache::ServerRec
object|docs::2.0::api::Apache::ServerRec>> )
-=item since: 1.99_12
-=back
+=head2 C<status_line>
+Get/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 C<$r-E<gt>status()> described above.
-=head2 C<status>
-
-META: Autogenerated - needs to be reviewed/completed
-
-Get/set status line
-
- $status = $r->status($new_status);
- $status = $r->status();
+ $status_line = $r->status_line();
+ $prev_status_line = $r->status_line($new_status_line);
=over 4
=item obj: C<$r>
( C<L<Apache::RequestRec object|docs::2.0::api::Apache::RequestRec>> )
-=item opt arg1: C<$new_status> (integer)
-
-If C<$new_status> is passed the new status is assigned.
+=item opt arg1: C<$new_status_line> ( string )
-=item ret: C<$newval> (integer)
-
-If C<$new_status> is passed the old status is returned.
+=item ret: C<$status_line> ( string )
=item since: 1.99_12
=back
+When discussing C<L<$r-E<gt>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
+C<status_line()>, like so:
+
+ $r->status_line($response->code() . ' ' . $response->message());
+ return Apache::OK;
+
+In this example C<$response> could be for example an C<HTTP::Response>
+object, if C<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 C<499> is the new response code, and I<We have been FooBared> is
+the custom response message.
-=head2 C<status_line>
-META: Autogenerated - needs to be reviewed/completed
-Status line, if set by script
- $status_line = $r->status_line();
+
+=head2 C<subprocess_env>
+
+Get/set the Apache C<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);
=over 4
=item obj: C<$r>
( C<L<Apache::RequestRec object|docs::2.0::api::Apache::RequestRec>> )
-=item ret: C<$status_line> ( string )
+=item opt arg1: C<$key> ( string )
+
+=item opt arg2: C<$val> ( string )
+
+=item ret: C<...>
=item since: 1.99_12
=back
+When called in VOID context with no arguments, it populate C<%ENV>
+with special variables (e.g. C<$ENV{QUERY_STRING}>) like mod_cgi
+does.
+When called in a non-VOID context with no arguments, it returns an
+C<L<APR::Table object|docs::2.0::api::APR::Table>>.
+When the C<$key> argument (string) is passed, it returns the
+corresponding value (if such exists, or C<undef>. The following two
+lines are equivalent:
+ $val = $r->subprocess_env($key);
+ $val = $r->subprocess_env->get($key);
+When the C<$key> and the C<$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 C<subprocess_env> C<L<table|docs::2.0::api::APR::Table>> is used
+by C<L<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
+C<PerlHeaderParserHandler> you do:
-=head2 C<subprocess_env>
+ $r->subprocess_env(MyLanguage => "de");
+you can then deploy C<mod_include> and write in I<.shtml> document:
+ <!--#if expr="$MyLanguage = en" -->
+ English
+ <!--#elif expr="$MyLanguage = de" -->
+ Deutsch
+ <!--#else -->
+ Sorry
+ <!--#endif -->
-=head2 C<the_request>
-META: Autogenerated - needs to be reviewed/completed
-First line of request
+
+
+
+
+=head2 C<the_request>
+
+First HTTP request header
$request = $r->the_request();
@@ -1488,6 +1680,10 @@
=item ret: C<$request> ( string )
+For example:
+
+ GET /foo/bar/my_path_info?args=3 HTTP/1.0
+
=item since: 1.99_12
=back
@@ -1502,8 +1698,6 @@
=head2 C<unparsed_uri>
-META: Autogenerated - needs to be reviewed/completed
-
The URI without any parsing performed
$unparsed_uri = $r->unparsed_uri();
@@ -1519,18 +1713,30 @@
=back
+If for example the request was:
+ GET /foo/bar/my_path_info?args=3 HTTP/1.0
+
+C<L<$r-E<gt>uri|/C_uri_>> returns:
+
+ /foo/bar/my_path_info
+
+whereas C<$r-E<gt>unparsed_uri> returns:
+
+ /foo/bar/my_path_info?args=3
-=head2 C<uri>
-META: Autogenerated - needs to be reviewed/completed
+
+
+
+=head2 C<uri>
The path portion of the URI
- $uri = $r->uri();
- $r->uri($uri);
+ $uri = $r->uri();
+ my $prec_uri = $r->uri($uri);
=over 4
@@ -1545,62 +1751,52 @@
=back
+See the example in the C<L<$r-E<gt>unparsed_uri|/C_unparsed_uri_>>
+section.
-=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);
+=head2 C<user>
+
+Get the user name, if an L<authentication> process was successful. Or
+set it.
+
+ $user = $r->user();
+ $prev_user = $r->user($new_user);
=over 4
=item obj: C<$r>
( C<L<Apache::RequestRec object|docs::2.0::api::Apache::RequestRec>> )
-=item arg1: C<$newval> (integer)
-
-=item since: 1.99_12
-
-=back
-
-
-
-
+=item opt arg1: C<$new_user> ( string )
+Pass C<$new_user> to set a new value
+=item ret: C<$user> ( string )
-=head2 C<user>
+The current username if an authentication process was successful.
-META: Autogenerated - needs to be reviewed/completed
+If C<$new_user> was passed, the previous value is returned.
-If an authentication check was made, this gets set to the user name.
+=item since: 1.99_12
- $r->user($user);
- $user = $r->user();
+=back
-=over 4
+For example, let's print the username passed by the client:
-=item obj: C<$r>
-( C<L<Apache::RequestRec object|docs::2.0::api::Apache::RequestRec>> )
+ my($res, $sent_pw) = $r->get_basic_auth_pw;
+ return $res if $res != Apache::OK;
+ print "User: ", $r->user;
-=item opt arg1: C<$user> ( string )
-=item ret: C<$user> ( string )
-=item since: 1.99_12
-=back
@@ -1642,6 +1838,9 @@
+
+
+
=head2 C<allowed_xmethods>
META: Autogenerated - needs to be reviewed/completed
@@ -1662,12 +1861,39 @@
=back
-
META: APR::ArrayHeader is not available at the moment
+
+
+
+=head2 C<canonical_filename>
+
+META: Autogenerated - needs to be reviewed/completed
+
+XXX: The true filename, we canonicalize r-E<gt>filename if these don't
+match
+
+ $canon_filename = $r->canonical_filename();
+
+=over 4
+
+=item obj: C<$r>
+( C<L<Apache::RequestRec object|docs::2.0::api::Apache::RequestRec>> )
+
+=item ret: C<$canon_filename> ( string )
+
+=item since: 1.99_12
+
+=back
+
+
+
+
+
+
=head2 C<content_languages>
META: Autogenerated - needs to be reviewed/completed
@@ -1687,9 +1913,61 @@
=back
+META: APR::ArrayHeader is not available at the moment
+
+
+
+
+
+
+=head2 C<request_config>
+
+Notes on *this* request
+
+ $ret = $r->request_config($newval);
+
+=over 4
+
+=item obj: C<$r>
+( C<L<Apache::RequestRec object|docs::2.0::api::Apache::RequestRec>> )
+
+=item opt arg1: C<$newval>
+( C<L<Apache::ConfVector object|docs::2.0::api::Apache::ConfVector>> )
+
+=item since: 1.99_12
+
+=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 obj: C<$r>
+( C<L<Apache::RequestRec object|docs::2.0::api::Apache::RequestRec>> )
+
+=item arg1: C<$newval> (integer)
+
+=item since: 1.99_12
+
+=back
+
-META: APR::ArrayHeader is not available at the moment
---------------------------------------------------------------------
To unsubscribe, e-mail: [EMAIL PROTECTED]
For additional commands, e-mail: [EMAIL PROTECTED]
