You are viewing a plain text version of this content. The canonical link for it is here.
Posted to docs-cvs@perl.apache.org by st...@apache.org on 2004/07/22 08:53:59 UTC
cvs commit: modperl-docs/src/docs/2.0/api/Apache RequestRec.pod
stas 2004/07/21 23:53:59
Modified: src/docs/2.0/api/Apache RequestRec.pod
Log:
sort methods
Revision Changes Path
1.21 +479 -398 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.20
retrieving revision 1.21
diff -u -u -r1.20 -r1.21
--- RequestRec.pod 12 Jul 2004 23:13:22 -0000 1.20
+++ RequestRec.pod 22 Jul 2004 06:53:59 -0000 1.21
@@ -42,64 +42,87 @@
C<Apache::RequestRec> provides the following functions and/or methods:
-=head2 C<finfo>
-Get and set the I<finfo> request record member:
+=head2 C<allowed>
- $finfo = $r->finfo();
- $finfo = $r->finfo($finfo);
+META: Autogenerated - needs to be reviewed/completed
+
+'allowed' is a bitvector of the allowed methods.
+
+ $allowed = $r->allowed();
=over 4
=item obj: C<$r>
( C<L<Apache::RequestRec object|docs::2.0::api::Apache::RequestRec>> )
-=item opt arg1: C<$finfo>
-( C<L<APR::Finfo object|docs::2.0::api::APR::Finfo>> )
+=item ret: C<$allowed> (number)
-=item ret: C<$finfo>
-( C<L<APR::Finfo object|docs::2.0::api::APR::Finfo>> )
+=item since: 1.99_12
-Always returns the current object.
+=back
-Due to the internal Apache implementation it's not possible to have
-two different objects originating from C<$r-E<gt>finfo> at the same
-time. Whenever C<$r-E<gt>finfo> is updated all objects will be updated
-too to the latest value.
+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.
-=item since: 1.99_15
+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_methods>
+
+META: Autogenerated - needs to be reviewed/completed
+
+List of allowed methods
+
+ $list = $r->allowed_methods();
+
+=over 4
+
+=item obj: C<$r>
+( C<L<Apache::RequestRec object|docs::2.0::api::Apache::RequestRec>> )
+
+=item ret: C<$list> ( C<L<Apache::MethodList object|docs::2.0::api::Apache::MethodList>> )
+
+=item since: 1.99_12
=back
-Most of the time, this method is used to get the C<finfo> member. The
-only reason you may want to set it is you need to use it before the
-Apache's default map_to_storage phase is called.
-Examples:
-=over
-=item *
-What Apache thinks is the current request filename (post the
-C<L<PerlMapToStorageHandler|docs::2.0::user::handlers::http/PerlMapToStorageHandler>>
-phase):
- use Apache::RequestRec ();
- use APR::Finfo ();
- print $r->finfo->fname;
+=head2 C<allowed_xmethods>
-=item *
+META: Autogenerated - needs to be reviewed/completed
-Populate the C<finfo> member (normally, before the
-C<L<PerlMapToStorageHandler|docs::2.0::user::handlers::http/PerlMapToStorageHandler>>
-phase):
+Array of extension methods
- use APR::Finfo ();
- use APR::Const -compile => qw(FINFO_NORM);
+ $array = $r->allowed_xmethods();
- my $finfo = APR::Finfo::stat(__FILE__, APR::FINFO_NORM, $r->pool);
- $r->finfo($finfo);
+=over 4
+
+=item obj: C<$r>
+( C<L<Apache::RequestRec object|docs::2.0::api::Apache::RequestRec>> )
+
+=item ret: C<$array> ( C<L<APR::ArrayHeader object|docs::2.0::api::APR::ArrayHeader>> )
+
+=item since: 1.99_12
=back
@@ -108,74 +131,67 @@
-=head2 C<proxyreq>
+=head2 C<ap_auth_type>
-Get and set the I<proxyrec> request record member and optionally
-adjust other related fields.
+If an authentication check was made, get or set the I<ap_auth_type>
+slot in the request record
- $ret = $r->proxyreq($val);
+ $auth_type = $r->ap_auth_type();
+ $r->ap_auth_type($newval);
=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 arg2: C<$newval> (string)
-0, 1 or none.
+If this argument is passed then a new auth type is assigned. For example:
-=item ret: C<$ret> (integer)
+ $r->auth_type('Basic');
-If C<$val> is 0 or 1, the I<proxyrec> member will be set to that value
-and previous value will be returned.
+=item ret: C<$auth_type> (string)
-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.
+If C<$newval> is passed, nothing is returned. Otherwise the current
+auth type is returned.
=item since: 1.99_12
=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:
+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.
- my $real_url = $r->unparsed_uri;
- $r->proxyreq(1);
- $r->uri($real_url);
- $r->filename("proxy:$real_url");
- $r->handler('proxy-server');
+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.
-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>
+=head2 C<args>
META: Autogenerated - needs to be reviewed/completed
-The pool associated with the request
+The QUERY_ARGS extracted from this request
- $p = $r->pool();
+ $args = $r->args();
+ $r->args($args);
=over 4
=item obj: C<$r>
( C<L<Apache::RequestRec object|docs::2.0::api::Apache::RequestRec>> )
-=item ret: C<$p> ( C<L<APR::Pool object|docs::2.0::api::APR::Pool>> )
+=item opt arg2: C<$args> (string)
+
+=item ret: C<$args> (string)
=item since: 1.99_12
@@ -185,42 +201,72 @@
-=head2 C<connection>
-META: Autogenerated - needs to be reviewed/completed
-The connection record to the client
- $c = $r->connection();
+
+=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 obj: C<$r>
( C<L<Apache::RequestRec object|docs::2.0::api::Apache::RequestRec>> )
-=item ret: C<$c> ( C<L<Apache::Connection object|docs::2.0::api::Apache::Connection>> )
+=item arg1 opt: C<$newval> (integer)
+
+assign a new state.
+
+=item ret: C<$status> (integer)
+
+current state.
+
+=item since: 1.99_10
=item since: 1.99_12
=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<server>
-Get the C<L<Apache::Server|docs::2.0::api::Apache::ServerRec>> object for
-the server the request C<$r> is running under.
+=head2 C<bytes_sent>
- $s = $r->server();
+META: Autogenerated - needs to be reviewed/completed
+
+body byte count, for easy access
+
+ $bytes_sent = $r->bytes_sent();
=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 ret: C<$bytes_sent> (integer)
=item since: 1.99_12
@@ -230,20 +276,20 @@
-=head2 C<next>
+=head2 C<canonical_filename>
META: Autogenerated - needs to be reviewed/completed
-Pointer to the redirected request if this is an external redirect
- $next_r = $r->next();
+
+ $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<$next_r> ( C<L<Apache::RequestRec object|docs::2.0::api::Apache::RequestRec>> )
+=item ret: C<$canon_filename> (string)
=item since: 1.99_12
@@ -253,20 +299,23 @@
-=head2 C<prev>
+
+
+
+=head2 C<connection>
META: Autogenerated - needs to be reviewed/completed
-Pointer to the previous request if this is an internal redirect
+The connection record to the client
- $prev_r = $r->prev();
+ $c = $r->connection();
=over 4
=item obj: C<$r>
( C<L<Apache::RequestRec object|docs::2.0::api::Apache::RequestRec>> )
-=item ret: C<$prev_r> ( C<L<Apache::RequestRec object|docs::2.0::api::Apache::RequestRec>> )
+=item ret: C<$c> ( C<L<Apache::Connection object|docs::2.0::api::Apache::Connection>> )
=item since: 1.99_12
@@ -276,28 +325,20 @@
-=head2 C<main>
+=head2 C<content_encoding>
-Get the main request record
+META: Autogenerated - needs to be reviewed/completed
- $main_r = $r->main();
+
+
+ $ce = $r->content_encoding();
=over 4
=item obj: C<$r>
( C<L<Apache::RequestRec object|docs::2.0::api::Apache::RequestRec>> )
-=item ret: C<$main_r> ( C<L<Apache::RequestRec object|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_>>.
-
+=item ret: C<$ce> (string)
=item since: 1.99_12
@@ -307,20 +348,20 @@
-=head2 C<the_request>
+=head2 C<content_languages>
META: Autogenerated - needs to be reviewed/completed
-First line of request
+Array of strings representing the content languages
- $request = $r->the_request();
+ $array_header = $r->content_languages();
=over 4
=item obj: C<$r>
( C<L<Apache::RequestRec object|docs::2.0::api::Apache::RequestRec>> )
-=item ret: C<$request> (string)
+=item ret: C<$array_header> ( C<L<APR::ArrayHeader object|docs::2.0::api::APR::ArrayHeader>> )
=item since: 1.99_12
@@ -330,89 +371,97 @@
-=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();
+=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 obj: C<$r>
( C<L<Apache::RequestRec object|docs::2.0::api::Apache::RequestRec>> )
-=item arg1 opt: C<$newval> (integer)
+=item arg1 opt: C<$new_content_type> (MIME type/string)
-assign a new state.
+Assign a new HTTP response content-type. It will affect the response
+only if HTTP headers weren't sent yet.
-=item ret: C<$status> (integer)
+=item ret: C<$content_type>
-current state.
+The current content-type value.
-=item since: 1.99_10
+=item since 1.99_10
=item since: 1.99_12
=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).
+For example, set the C<Content-type> header to I<text/plain>.
- $r->connection->keepalives($r->connection->keepalives + 1);
+ $r->content_type('text/plain');
-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.
+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<header_only>
+
+
+
+=head2 C<err_headers_out>
META: Autogenerated - needs to be reviewed/completed
-HEAD request, as opposed to GET
+MIME header environment for the response, printed even on errors and
+persist across internal redirects
- $status = $r->header_only();
+ $err_headers_out = $r->err_headers_out();
=over 4
=item obj: C<$r>
( C<L<Apache::RequestRec object|docs::2.0::api::Apache::RequestRec>> )
-=item ret: C<$status> (integer)
+=item err: C<$err_headers_out> ( C<L<APR::Table object|docs::2.0::api::APR::Table>> )
=item since: 1.99_12
=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<protocol>
+
+
+
+
+=head2 C<filename>
META: Autogenerated - needs to be reviewed/completed
-Protocol string, as given to us, or HTTP/0.9
+The filename on disk corresponding to this response
- $protocol = $r->protocol();
+ $filename = $r->filename();
+ $r->filename($filename);
=over 4
=item obj: C<$r>
( C<L<Apache::RequestRec object|docs::2.0::api::Apache::RequestRec>> )
-=item ret: C<$protocl> (string)
+=item opt arg2: C<$filename> (string)
+
+=item ret: C<$filename> (string)
=item since: 1.99_12
@@ -422,66 +471,86 @@
-=head2 C<proto_num>
-META: Autogenerated - needs to be reviewed/completed
+=head2 C<finfo>
-Protocol version number of protocol; 1.1 = 1001
+Get and set the I<finfo> request record member:
- $proto_num = $r->proto_num();
+ $finfo = $r->finfo();
+ $finfo = $r->finfo($finfo);
=over 4
=item obj: C<$r>
( C<L<Apache::RequestRec object|docs::2.0::api::Apache::RequestRec>> )
-=item ret: C<$proto_num> (integer)
+=item opt arg1: C<$finfo>
+( C<L<APR::Finfo object|docs::2.0::api::APR::Finfo>> )
-=item since: 1.99_12
+=item ret: C<$finfo>
+( C<L<APR::Finfo object|docs::2.0::api::APR::Finfo>> )
-=back
+Always returns the current object.
+Due to the internal Apache implementation it's not possible to have
+two different objects originating from C<$r-E<gt>finfo> at the same
+time. Whenever C<$r-E<gt>finfo> is updated all objects will be updated
+too to the latest value.
+=item since: 1.99_15
+=back
+Most of the time, this method is used to get the C<finfo> member. The
+only reason you may want to set it is you need to use it before the
+Apache's default map_to_storage phase is called.
-=head2 C<hostname>
+Examples:
-META: Autogenerated - needs to be reviewed/completed
+=over
-Host, as set by full URI or Host:
+=item *
- $hostname = $r->hostname();
+What Apache thinks is the current request filename (post the
+C<L<PerlMapToStorageHandler|docs::2.0::user::handlers::http/PerlMapToStorageHandler>>
+phase):
-=over 4
+ use Apache::RequestRec ();
+ use APR::Finfo ();
+ print $r->finfo->fname;
-=item obj: C<$r>
-( C<L<Apache::RequestRec object|docs::2.0::api::Apache::RequestRec>> )
+=item *
-=item ret: C<$hostname> (string)
+Populate the C<finfo> member (normally, before the
+C<L<PerlMapToStorageHandler|docs::2.0::user::handlers::http/PerlMapToStorageHandler>>
+phase):
-=item since: 1.99_12
+ use APR::Finfo ();
+ use APR::Const -compile => qw(FINFO_NORM);
-=back
+ my $finfo = APR::Finfo::stat(__FILE__, APR::FINFO_NORM, $r->pool);
+ $r->finfo($finfo);
+=back
-=head2 C<request_time>
+=head2 C<handler>
META: Autogenerated - needs to be reviewed/completed
-Time when the request started
-
- $request_time = $r->request_time();
+ $handler = $r->handler();
+ $handler = $r->handler($new_handler);
=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 arg2: C<$new_handler> (string)
+
+=item ret: C<$handler> (string)
=item since: 1.99_12
@@ -491,20 +560,22 @@
-=head2 C<status_line>
+
+
+=head2 C<header_only>
META: Autogenerated - needs to be reviewed/completed
-Status line, if set by script
+HEAD request, as opposed to GET
- $status_line = $r->status_line();
+ $status = $r->header_only();
=over 4
=item obj: C<$r>
( C<L<Apache::RequestRec object|docs::2.0::api::Apache::RequestRec>> )
-=item ret: C<$status_line> (string)
+=item ret: C<$status> (integer)
=item since: 1.99_12
@@ -513,28 +584,18 @@
-
-=head2 C<status>
+=head2 C<headers_in>
META: Autogenerated - needs to be reviewed/completed
-Get/set status line
-
- $status = $r->status($new_status);
- $status = $r->status();
+ $headers_in = $r->headers_in();
=over 4
=item obj: C<$r>
( C<L<Apache::RequestRec object|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.
+=item ret: C<$headers_in> ( C<L<APR::Table object|docs::2.0::api::APR::Table>> )
=item since: 1.99_12
@@ -544,20 +605,21 @@
-=head2 C<method>
+
+=head2 C<headers_out>
META: Autogenerated - needs to be reviewed/completed
-Request method (eg. GET, HEAD, POST, etc.)
+MIME header environment for the response
- $method = $r->method();
+ $headers_out = $r->headers_out();
=over 4
=item obj: C<$r>
( C<L<Apache::RequestRec object|docs::2.0::api::Apache::RequestRec>> )
-=item ret: C<$method> (string)
+=item ret: C<$headers_out> ( C<L<APR::Table object|docs::2.0::api::APR::Table>> )
=item since: 1.99_12
@@ -567,20 +629,23 @@
-=head2 C<method_number>
+
+
+
+=head2 C<hostname>
META: Autogenerated - needs to be reviewed/completed
-Apache::M_GET, Apache::M_POST, etc.
+Host, as set by full URI or Host:
- $methno = $r->method_number();
+ $hostname = $r->hostname();
=over 4
=item obj: C<$r>
( C<L<Apache::RequestRec object|docs::2.0::api::Apache::RequestRec>> )
-=item ret: C<$methno> (integer)
+=item ret: C<$hostname> (string)
=item since: 1.99_12
@@ -590,58 +655,55 @@
-=head2 C<allowed>
+
+
+=head2 C<input_filters>
META: Autogenerated - needs to be reviewed/completed
-'allowed' is a bitvector of the allowed methods.
+A list of input filters to be used for this request
- $allowed = $r->allowed();
+ $input_filters = $r->input_filters();
=over 4
=item obj: C<$r>
( C<L<Apache::RequestRec object|docs::2.0::api::Apache::RequestRec>> )
-=item ret: C<$allowed> (number)
+=item ret: C<$input_filters> ( C<L<Apache::Filter object|docs::2.0::api::Apache::Filter>> )
=item since: 1.99_12
=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
+=head2 C<main>
-Array of extension methods
+Get the main request record
- $array = $r->allowed_xmethods();
+ $main_r = $r->main();
=over 4
=item obj: C<$r>
( C<L<Apache::RequestRec object|docs::2.0::api::Apache::RequestRec>> )
-=item ret: C<$array> ( C<L<APR::ArrayHeader object|docs::2.0::api::APR::ArrayHeader>> )
+=item ret: C<$main_r> ( C<L<Apache::RequestRec object|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_>>.
+
=item since: 1.99_12
@@ -650,21 +712,20 @@
-
-=head2 C<allowed_methods>
+=head2 C<method>
META: Autogenerated - needs to be reviewed/completed
-List of allowed methods
+Request method (eg. GET, HEAD, POST, etc.)
- $list = $r->allowed_methods();
+ $method = $r->method();
=over 4
=item obj: C<$r>
( C<L<Apache::RequestRec object|docs::2.0::api::Apache::RequestRec>> )
-=item ret: C<$list> ( C<L<Apache::MethodList object|docs::2.0::api::Apache::MethodList>> )
+=item ret: C<$method> (string)
=item since: 1.99_12
@@ -674,20 +735,20 @@
-=head2 C<bytes_sent>
+=head2 C<method_number>
META: Autogenerated - needs to be reviewed/completed
-body byte count, for easy access
+Apache::M_GET, Apache::M_POST, etc.
- $bytes_sent = $r->bytes_sent();
+ $methno = $r->method_number();
=over 4
=item obj: C<$r>
( C<L<Apache::RequestRec object|docs::2.0::api::Apache::RequestRec>> )
-=item ret: C<$bytes_sent> (integer)
+=item ret: C<$methno> (integer)
=item since: 1.99_12
@@ -697,6 +758,7 @@
+
=head2 C<mtime>
META: Autogenerated - needs to be reviewed/completed
@@ -723,23 +785,24 @@
-=head2 C<remaining>
-META: Autogenerated - needs to be reviewed/completed
-Remaining bytes left to read from the request body
- $bytes = $r->remaining();
+=head2 C<next>
-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).
+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 obj: C<$r>
( C<L<Apache::RequestRec object|docs::2.0::api::Apache::RequestRec>> )
-=item ret: C<$bytes> (integer)
+=item ret: C<$next_r>
+( C<L<Apache::RequestRec object|docs::2.0::api::Apache::RequestRec>> )
=item since: 1.99_12
@@ -748,120 +811,131 @@
-
-=head2 C<headers_in>
+=head2 C<no_local_copy>
META: Autogenerated - needs to be reviewed/completed
- $headers_in = $r->headers_in();
+There is no local copy of this response
+
+ $status = $r->no_local_copy();
=over 4
=item obj: C<$r>
( C<L<Apache::RequestRec object|docs::2.0::api::Apache::RequestRec>> )
-=item ret: C<$headers_in> ( C<L<APR::Table object|docs::2.0::api::APR::Table>> )
+=item ret: C<$status> (integer)
=item since: 1.99_12
=back
-=head2 C<headers_out>
+
+
+
+=head2 C<notes>
META: Autogenerated - needs to be reviewed/completed
-MIME header environment for the response
+Notes from one module to another
- $headers_out = $r->headers_out();
+ $notes = $r->notes();
+ $notes = $r->notes($new_notes);
=over 4
=item obj: C<$r>
( C<L<Apache::RequestRec object|docs::2.0::api::Apache::RequestRec>> )
-=item ret: C<$headers_out> ( C<L<APR::Table object|docs::2.0::api::APR::Table>> )
+=item opt arg2: C<$new_notes> ( C<L<APR::Table object|docs::2.0::api::APR::Table>> )
+
+=item ret: C<$notes> ( C<L<APR::Table object|docs::2.0::api::APR::Table>> )
+
=item since: 1.99_12
=back
+The 'notes' is for notes from one module to another, with no other set
+purpose in mind...
+
-=head2 C<err_headers_out>
+=head2 C<output_filters>
META: Autogenerated - needs to be reviewed/completed
-MIME header environment for the response, printed even on errors and
-persist across internal redirects
+A list of output filters to be used for this request
- $err_headers_out = $r->err_headers_out();
+ $output_filters = $r->output_filters();
=over 4
=item obj: C<$r>
( C<L<Apache::RequestRec object|docs::2.0::api::Apache::RequestRec>> )
-=item err: C<$err_headers_out> ( C<L<APR::Table object|docs::2.0::api::APR::Table>> )
+=item ret: C<$output_filters> ( C<L<Apache::Filter object|docs::2.0::api::Apache::Filter>> )
=item since: 1.99_12
=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>
+
+
+
+
+=head2 C<path_info>
META: Autogenerated - needs to be reviewed/completed
-Notes from one module to another
+The PATH_INFO extracted from this request
- $notes = $r->notes();
- $notes = $r->notes($new_notes);
+ $path_info = $r->path_info();
+ $r->path_info($path_info);
=over 4
=item obj: C<$r>
( C<L<Apache::RequestRec object|docs::2.0::api::Apache::RequestRec>> )
-=item opt arg2: C<$new_notes> ( C<L<APR::Table object|docs::2.0::api::APR::Table>> )
-
-=item ret: C<$notes> ( C<L<APR::Table object|docs::2.0::api::APR::Table>> )
+=item opt arg2: C<$path_info> (string)
+=item ret: C<$path_info> (string)
=item since: 1.99_12
=back
-The 'notes' is for notes from one module to another, with no other set
-purpose in mind...
-=head2 C<handler>
+
+
+=head2 C<per_dir_config>
META: Autogenerated - needs to be reviewed/completed
- $handler = $r->handler();
- $handler = $r->handler($new_handler);
+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 obj: C<$r>
( C<L<Apache::RequestRec object|docs::2.0::api::Apache::RequestRec>> )
-=item opt arg2: C<$new_handler> (string)
-
-=item ret: C<$handler> (string)
+=item ret: C<$per_dir_config> ( C<L<Apache::ConfVector object|docs::2.0::api::Apache::ConfVector>> )
=item since: 1.99_12
@@ -871,56 +945,45 @@
-=head2 C<content_type>
-Get/set the HTTP response I<Content-type> header value.
+=head2 C<pool>
- my $content_type = $r->content_type();
- my $content_type = $r->content_type($new_content_type);
+META: Autogenerated - needs to be reviewed/completed
+
+The pool associated with the request
+
+ $p = $r->pool();
=over 4
=item obj: C<$r>
( C<L<Apache::RequestRec object|docs::2.0::api::Apache::RequestRec>> )
-=item arg1 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
+=item ret: C<$p> ( C<L<APR::Pool object|docs::2.0::api::APR::Pool>> )
=item since: 1.99_12
=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
+=head2 C<prev>
+META: Autogenerated - needs to be reviewed/completed
+Pointer to the previous request if this is an internal redirect
- $ce = $r->content_encoding();
+ $prev_r = $r->prev();
=over 4
=item obj: C<$r>
( C<L<Apache::RequestRec object|docs::2.0::api::Apache::RequestRec>> )
-=item ret: C<$ce> (string)
+=item ret: C<$prev_r> ( C<L<Apache::RequestRec object|docs::2.0::api::Apache::RequestRec>> )
=item since: 1.99_12
@@ -930,20 +993,20 @@
-=head2 C<content_languages>
+=head2 C<proto_input_filters>
META: Autogenerated - needs to be reviewed/completed
-Array of strings representing the content languages
+A list of protocol level input filters to be used for this request
- $array_header = $r->content_languages();
+ $proto_input_filters = $r->proto_input_filters();
=over 4
=item obj: C<$r>
( C<L<Apache::RequestRec object|docs::2.0::api::Apache::RequestRec>> )
-=item ret: C<$array_header> ( C<L<APR::ArrayHeader object|docs::2.0::api::APR::ArrayHeader>> )
+=item ret: C<$proto_input_filters> ( C<L<Apache::Filter object|docs::2.0::api::Apache::Filter>> )
=item since: 1.99_12
@@ -953,23 +1016,21 @@
-=head2 C<user>
+
+=head2 C<proto_num>
META: Autogenerated - needs to be reviewed/completed
-If an authentication check was made, this gets set to the user name.
+Protocol version number of protocol; 1.1 = 1001
- $r->user($user);
- $user = $r->user();
+ $proto_num = $r->proto_num();
=over 4
=item obj: C<$r>
( C<L<Apache::RequestRec object|docs::2.0::api::Apache::RequestRec>> )
-=item opt arg2: C<$user> (string)
-
-=item ret: C<$user> (string)
+=item ret: C<$proto_num> (integer)
=item since: 1.99_12
@@ -977,62 +1038,46 @@
+=head2 C<proto_output_filters>
+META: Autogenerated - needs to be reviewed/completed
-=head2 C<ap_auth_type>
-
-If an authentication check was made, get or set the I<ap_auth_type>
-slot in the request record
+A list of protocol level output filters to be used for this request
- $auth_type = $r->ap_auth_type();
- $r->ap_auth_type($newval);
+ $proto_output_filters = $r->proto_output_filters();
=over 4
=item obj: C<$r>
( C<L<Apache::RequestRec object|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:
+=item ret: C<$proto_output_filters> ( C<L<Apache::Filter object|docs::2.0::api::Apache::Filter>> )
- $r->auth_type('Basic');
+=item since: 1.99_12
-=item ret: C<$auth_type> (string)
+=back
-If C<$newval> is passed, nothing is returned. Otherwise the current
-auth type is returned.
-=item since: 1.99_12
-=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>
+=head2 C<protocol>
META: Autogenerated - needs to be reviewed/completed
-There is no local copy of this response
+Protocol string, as given to us, or HTTP/0.9
- $status = $r->no_local_copy();
+ $protocol = $r->protocol();
=over 4
=item obj: C<$r>
( C<L<Apache::RequestRec object|docs::2.0::api::Apache::RequestRec>> )
-=item ret: C<$status> (integer)
+=item ret: C<$protocl> (string)
=item since: 1.99_12
@@ -1042,46 +1087,80 @@
-=head2 C<unparsed_uri>
-
-META: Autogenerated - needs to be reviewed/completed
+=head2 C<proxyreq>
-The URI without any parsing performed
+Get and set the I<proxyrec> request record member and optionally
+adjust other related fields.
- $unparsed_uri = $r->unparsed_uri();
+ $ret = $r->proxyreq($val);
=over 4
=item obj: C<$r>
( C<L<Apache::RequestRec object|docs::2.0::api::Apache::RequestRec>> )
-=item ret: C<$unparsed_uri> (string)
+=item arg1 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.
=item since: 1.99_12
=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<uri>
+
+
+
+
+=head2 C<remaining>
META: Autogenerated - needs to be reviewed/completed
-The path portion of the URI
+Remaining bytes left to read from the request body
- $uri = $r->uri();
- $r->uri($uri);
+ $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 obj: C<$r>
( C<L<Apache::RequestRec object|docs::2.0::api::Apache::RequestRec>> )
-=item opt arg2: C<$uri> (string)
-
-=item ret: C<$uri> (string)
+=item ret: C<$bytes> (integer)
=item since: 1.99_12
@@ -1091,23 +1170,22 @@
-=head2 C<filename>
+
+
+=head2 C<request_config>
META: Autogenerated - needs to be reviewed/completed
-The filename on disk corresponding to this response
+Notes on *this* request
- $filename = $r->filename();
- $r->filename($filename);
+ $ret = $r->request_config($newval);
=over 4
=item obj: C<$r>
( C<L<Apache::RequestRec object|docs::2.0::api::Apache::RequestRec>> )
-=item opt arg2: C<$filename> (string)
-
-=item ret: C<$filename> (string)
+=item arg1: C<$newval> ( C<L<Apache::ConfVector object|docs::2.0::api::Apache::ConfVector>> )
=item since: 1.99_12
@@ -1117,20 +1195,22 @@
-=head2 C<canonical_filename>
-META: Autogenerated - needs to be reviewed/completed
+=head2 C<request_time>
+META: Autogenerated - needs to be reviewed/completed
- $canon_filename = $r->canonical_filename();
+Time when the request started
+
+ $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<$canon_filename> (string)
+=item ret: C<$request_time> (number)
=item since: 1.99_12
@@ -1140,23 +1220,20 @@
-=head2 C<path_info>
-META: Autogenerated - needs to be reviewed/completed
+=head2 C<server>
-The PATH_INFO extracted from 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.
- $path_info = $r->path_info();
- $r->path_info($path_info);
+ $s = $r->server();
=over 4
=item obj: C<$r>
( C<L<Apache::RequestRec object|docs::2.0::api::Apache::RequestRec>> )
-=item opt arg2: C<$path_info> (string)
-
-=item ret: C<$path_info> (string)
+=item ret: C<$s> ( C<L<Apache::ServerRec object|docs::2.0::api::Apache::ServerRec>> )
=item since: 1.99_12
@@ -1165,24 +1242,27 @@
-
-=head2 C<args>
+=head2 C<status>
META: Autogenerated - needs to be reviewed/completed
-The QUERY_ARGS extracted from this request
+Get/set status line
- $args = $r->args();
- $r->args($args);
+ $status = $r->status($new_status);
+ $status = $r->status();
=over 4
=item obj: C<$r>
( C<L<Apache::RequestRec object|docs::2.0::api::Apache::RequestRec>> )
-=item opt arg2: C<$args> (string)
+=item opt arg2: C<$new_status> (integer)
-=item ret: C<$args> (string)
+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.
=item since: 1.99_12
@@ -1192,25 +1272,22 @@
-=head2 C<used_path_info>
+
+
+=head2 C<status_line>
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.
+Status line, if set by script
- $ret = $r->used_path_info($newval);
+ $status_line = $r->status_line();
=over 4
=item obj: C<$r>
( C<L<Apache::RequestRec object|docs::2.0::api::Apache::RequestRec>> )
-=item arg1: C<$newval> (integer)
+=item ret: C<$status_line> (string)
=item since: 1.99_12
@@ -1220,45 +1297,30 @@
-=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 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 since: 1.99_12
+=head2 C<subprocess_env>
-=back
-=head2 C<request_config>
+=head2 C<the_request>
META: Autogenerated - needs to be reviewed/completed
-Notes on *this* request
+First line of request
- $ret = $r->request_config($newval);
+ $request = $r->the_request();
=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<$request> (string)
=item since: 1.99_12
@@ -1268,20 +1330,24 @@
-=head2 C<output_filters>
+
+
+
+
+=head2 C<unparsed_uri>
META: Autogenerated - needs to be reviewed/completed
-A list of output filters to be used for this request
+The URI without any parsing performed
- $output_filters = $r->output_filters();
+ $unparsed_uri = $r->unparsed_uri();
=over 4
=item obj: C<$r>
( C<L<Apache::RequestRec object|docs::2.0::api::Apache::RequestRec>> )
-=item ret: C<$output_filters> ( C<L<Apache::Filter object|docs::2.0::api::Apache::Filter>> )
+=item ret: C<$unparsed_uri> (string)
=item since: 1.99_12
@@ -1291,20 +1357,23 @@
-=head2 C<input_filters>
+=head2 C<uri>
META: Autogenerated - needs to be reviewed/completed
-A list of input filters to be used for this request
+The path portion of the URI
- $input_filters = $r->input_filters();
+ $uri = $r->uri();
+ $r->uri($uri);
=over 4
=item obj: C<$r>
( C<L<Apache::RequestRec object|docs::2.0::api::Apache::RequestRec>> )
-=item ret: C<$input_filters> ( C<L<Apache::Filter object|docs::2.0::api::Apache::Filter>> )
+=item opt arg2: C<$uri> (string)
+
+=item ret: C<$uri> (string)
=item since: 1.99_12
@@ -1314,20 +1383,26 @@
-=head2 C<proto_output_filters>
+
+=head2 C<used_path_info>
META: Autogenerated - needs to be reviewed/completed
-A list of protocol level output filters to be used for this request
+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.
- $proto_output_filters = $r->proto_output_filters();
+ $ret = $r->used_path_info($newval);
=over 4
=item obj: C<$r>
( C<L<Apache::RequestRec object|docs::2.0::api::Apache::RequestRec>> )
-=item ret: C<$proto_output_filters> ( C<L<Apache::Filter object|docs::2.0::api::Apache::Filter>> )
+=item arg1: C<$newval> (integer)
=item since: 1.99_12
@@ -1337,24 +1412,30 @@
-=head2 C<proto_input_filters>
+
+
+=head2 C<user>
META: Autogenerated - needs to be reviewed/completed
-A list of protocol level input filters to be used for this request
+If an authentication check was made, this gets set to the user name.
- $proto_input_filters = $r->proto_input_filters();
+ $r->user($user);
+ $user = $r->user();
=over 4
=item obj: C<$r>
( C<L<Apache::RequestRec object|docs::2.0::api::Apache::RequestRec>> )
-=item ret: C<$proto_input_filters> ( C<L<Apache::Filter object|docs::2.0::api::Apache::Filter>> )
+=item opt arg2: C<$user> (string)
+
+=item ret: C<$user> (string)
=item since: 1.99_12
=back
+
---------------------------------------------------------------------
To unsubscribe, e-mail: docs-cvs-unsubscribe@perl.apache.org
For additional commands, e-mail: docs-cvs-help@perl.apache.org