stas 2004/07/23 18:22:52
Modified: src/docs/2.0/api/Apache RequestRec.pod ServerRec.pod
Log:
work in progress
Revision Changes Path
1.22 +252 -156 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.21
retrieving revision 1.22
diff -u -u -r1.21 -r1.22
--- RequestRec.pod 22 Jul 2004 06:53:59 -0000 1.21
+++ RequestRec.pod 24 Jul 2004 01:22:51 -0000 1.22
@@ -24,17 +24,20 @@
=head1 Description
-
C<Apache::RequestRec> provides the Perl API for Apache request_rec
object.
+The following packages extend the C<Apache::RequestRec> functionality:
+C<L<Apache::Access|docs::2.0::api::Apache::Access>>,
+C<L<Apache::Log|docs::2.0::api::Apache::Log>>,
+C<L<Apache::RequestIO|docs::2.0::api::Apache::RequestIO>>,
+C<L<Apache::RequestUtil|docs::2.0::api::Apache::RequestUtil>>,
+C<L<Apache::Response|docs::2.0::api::Apache::Response>>,
+C<L<Apache::SubRequest|docs::2.0::api::Apache::SubRequest>> and
+C<L<Apache::URI|docs::2.0::api::Apache::URI>>.
+
-The following packages extend C<Apache::RequestRec> functionality:
- Apache/RequestIO.pod
- Apache/RequestRec.pod
- Apache/RequestUtil.pod
- ... complete ...
=head1 API
@@ -45,88 +48,66 @@
=head2 C<allowed>
-META: Autogenerated - needs to be reviewed/completed
-
-'allowed' is a bitvector of the allowed methods.
+Get/set the allowed methods bitmask.
- $allowed = $r->allowed();
+ $allowed = $r->allowed();
+ $prev_allowed = $r->allowed($new_allowed);
=over 4
=item obj: C<$r>
( C<L<Apache::RequestRec object|docs::2.0::api::Apache::RequestRec>> )
-=item ret: C<$allowed> (number)
-
-=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.
-
-
+=item opt arg1: C<$new_allowed> ( bitmask )
+Set the bitvector.
+=item ret: C<$allowed> ( bitmask )
-=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
-
-
-
-
-
-
-=head2 C<allowed_xmethods>
-
-META: Autogenerated - needs to be reviewed/completed
-
-Array of extension methods
-
- $array = $r->allowed_xmethods();
-
-=over 4
-
-=item obj: C<$r>
-( C<L<Apache::RequestRec object|docs::2.0::api::Apache::RequestRec>> )
+returns C<$allowed>, which is a bitvector of the allowed methods.
-=item ret: C<$array> ( C<L<APR::ArrayHeader
object|docs::2.0::api::APR::ArrayHeader>> )
+If the C<$new_allowed> argument is passed, the value before the change
+is returned.
=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 C<Apache::DECLINE> any
+request methods they do not handle. Prior to aborting the handler
+like this the handler should set C<$r-E<gt>allowed> to the list of
+methods that it is willing to handle. This bitvector is used to
+construct the C<"Allow:"> header required for C<OPTIONS> requests, and
+C<Apache::HTTP_METHOD_NOT_ALLOWED> (405) and
+C<Apache::HTTP_NOT_IMPLEMENTED> (501) status codes.
+
+Since the default Apache handler deals with the C<OPTIONS> method, all
+response handlers can usually decline to deal with C<OPTIONS>. For
+example if the response handler handles only C<GET> and C<POST>
+methods, and not C<OPTIONS>, it may want to say:
+
+ use Apache::Const -compile => qw(OK DECLINED M_GET M_POST M_OPTIONS);
+ if ($r->method_number == Apache::M_OPTIONS) {
+ $r->allowed($r->allowed | (1<<Apache::M_GET) | (1<<Apache::M_POST));
+ return Apache::DECLINED;
+ }
+
+C<TRACE> is always allowed, modules don't need to set it explicitly.
+
+Since the default_handler will always handle a C<GET>, a module which
+does *not* implement C<GET> should probably return
+C<Apache::HTTP_METHOD_NOT_ALLOWED>. Unfortunately this means that a
+script C<GET> handler can't be installed by mod_actions.
+
+For example, if the module can handle only POST method it could start
+with:
+
+ use Apache::Const -compile => qw(M_POST HTTP_METHOD_NOT_ALLOWED);
+ unless ($r->method_number == Apache::M_POST) {
+ $r->allowed($r->allowed | (1<<Apache::M_POST));
+ return Apache::HTTP_METHOD_NOT_ALLOWED;
+ }
@@ -177,21 +158,25 @@
=head2 C<args>
-META: Autogenerated - needs to be reviewed/completed
-
-The QUERY_ARGS extracted from this request
+Get/set the request QUERY string
- $args = $r->args();
- $r->args($args);
+ $args = $r->args();
+ $prev_args = $r->args($new_args);
=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 arg1: C<$new_args> ( string )
-=item ret: C<$args> (string)
+Optinally set the new QUERY string
+
+=item ret: C<$args> ( string )
+
+The current QUERY string
+
+If C<$new_args> was passed, returns the value before the change.
=item since: 1.99_12
@@ -210,8 +195,8 @@
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();
+ $status = $r->assbackwards();
+ $prev_status = $r->assbackwards($newval);
=over 4
@@ -228,8 +213,6 @@
=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>
@@ -246,18 +229,18 @@
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.
+C<L<$r-E<gt>connection-E<gt>keepalive(1)|docs::2.0::api::Apache::Connection/C_keepalive_>>
+) as well.
-=head2 C<bytes_sent>
-META: Autogenerated - needs to be reviewed/completed
-body byte count, for easy access
+=head2 C<bytes_sent>
+
+The number of bytes sent to the client, handy for logging, etc.
$bytes_sent = $r->bytes_sent();
@@ -276,11 +259,15 @@
+
+
+
=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();
@@ -289,7 +276,7 @@
=item obj: C<$r>
( C<L<Apache::RequestRec object|docs::2.0::api::Apache::RequestRec>> )
-=item ret: C<$canon_filename> (string)
+=item ret: C<$canon_filename> ( string )
=item since: 1.99_12
@@ -304,9 +291,7 @@
=head2 C<connection>
-META: Autogenerated - needs to be reviewed/completed
-
-The connection record to the client
+Get the client connection record
$c = $r->connection();
@@ -315,7 +300,8 @@
=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 ret: C<$c>
+( C<L<Apache::Connection object|docs::2.0::api::Apache::Connection>> )
=item since: 1.99_12
@@ -325,47 +311,44 @@
-=head2 C<content_encoding>
-META: Autogenerated - needs to be reviewed/completed
+=head2 C<content_encoding>
+Get/set content encoding (the "Content-Encoding" HTTP header).
+Content encodings are string like I<"gzip"> or I<"compress">.
- $ce = $r->content_encoding();
+ $ce = $r->content_encoding();
+ $prev_ce = $r->content_encoding($new_ce);
=over 4
=item obj: C<$r>
( C<L<Apache::RequestRec object|docs::2.0::api::Apache::RequestRec>> )
-=item ret: C<$ce> (string)
-
-=item since: 1.99_12
-
-=back
-
+=item opt arg1: C<$new_ce> ( string )
+If passed, sets the content encoding to a new value. It must be a
+lowercased string.
+=item ret: C<$ce> ( string )
+The current content encoding.
-=head2 C<content_languages>
-
-META: Autogenerated - needs to be reviewed/completed
-
-Array of strings representing the content languages
+If C<$new_ce> is passed, then the previous value is returned.
- $array_header = $r->content_languages();
+=item since: 1.99_12
-=over 4
+=back
-=item obj: C<$r>
-( C<L<Apache::RequestRec object|docs::2.0::api::Apache::RequestRec>> )
+For example, here is how to send a gzip'ed response:
-=item ret: C<$array_header> ( C<L<APR::ArrayHeader
object|docs::2.0::api::APR::ArrayHeader>> )
+ require Compress::Zlib;
+ $r->content_type("text/plain");
+ $r->content_encoding("gzip");
+ $r->print(Compress::Zlib::memGzip("some text to be gzipped));
-=item since: 1.99_12
-=back
@@ -377,15 +360,15 @@
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);
+ my $content_type = $r->content_type();
+ my $prev_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<$new_content_type> (MIME type/string)
+=item opt arg1: 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.
@@ -394,9 +377,10 @@
The current content-type value.
-=item since 1.99_10
+If C<$new_content_type> was passed, the previous value is returned
+instead.
-=item since: 1.99_12
+=item since 1.99_10
=back
@@ -413,12 +397,12 @@
-=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
+=head2 C<err_headers_out>
+
+Get/set MIME response headers, printed even on errors and persist
+across internal redirects.
$err_headers_out = $r->err_headers_out();
@@ -427,18 +411,30 @@
=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<$err_headers_out>
+( C<L<APR::Table object|docs::2.0::api::APR::Table>> )
=item since: 1.99_12
=back
+The difference between C<L<headers_out|/C_headers_out_>> and
+C<err_headers_out>, is that the latter are printed even on error, and
+persist across internal redirects (so the headers printed for
+C<ErrorDocument> handlers will have them).
+
+For example, if a handler wants to return a 404 response, but
+nevertheless to set a cookie, it has to be:
-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).
+ $r->err_headers_out->add('Set-Cookie' => $cookie);
+ return Apache::NOT_FOUND;
+If the handler does:
+ $r->headers_out->add('Set-Cookie' => $cookie);
+ return Apache::NOT_FOUND;
+
+the C<Set-Cookie> header won't be sent.
@@ -459,9 +455,9 @@
=item obj: C<$r>
( C<L<Apache::RequestRec object|docs::2.0::api::Apache::RequestRec>> )
-=item opt arg2: C<$filename> (string)
+=item opt arg2: C<$filename> ( string )
-=item ret: C<$filename> (string)
+=item ret: C<$filename> ( string )
=item since: 1.99_12
@@ -548,9 +544,9 @@
=item obj: C<$r>
( C<L<Apache::RequestRec object|docs::2.0::api::Apache::RequestRec>> )
-=item opt arg2: C<$new_handler> (string)
+=item opt arg2: C<$new_handler> ( string )
-=item ret: C<$handler> (string)
+=item ret: C<$handler> ( string )
=item since: 1.99_12
@@ -586,7 +582,7 @@
=head2 C<headers_in>
-META: Autogenerated - needs to be reviewed/completed
+Get/set the request MIME headers:
$headers_in = $r->headers_in();
@@ -595,22 +591,30 @@
=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<$headers_in>
+( C<L<APR::Table object|docs::2.0::api::APR::Table>> )
=item since: 1.99_12
=back
+This table is available starting from the
+C<L<PerlHeaderParserHandler|docs::2.0::user::handlers::http/PerlHeaderParserHandler>>
+phase.
+For example you can use it to retrieve the cookie value sent by the
+client, in the C<Cookie:> header:
+
+ my $cookie = $r->headers_in->{Cookie} || '';
-=head2 C<headers_out>
-META: Autogenerated - needs to be reviewed/completed
-MIME header environment for the response
+=head2 C<headers_out>
+
+Get/set MIME response headers, printed only on 2xx responses.
$headers_out = $r->headers_out();
@@ -619,12 +623,16 @@
=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 ret: C<$headers_out>
+( C<L<APR::Table object|docs::2.0::api::APR::Table>> )
=item since: 1.99_12
=back
+See also C<L<err_headers_out|/C_err_headers_out_>>, which allows to
+set headers for non-2xx responses and persist across internal
+redirects.
@@ -645,7 +653,7 @@
=item obj: C<$r>
( C<L<Apache::RequestRec object|docs::2.0::api::Apache::RequestRec>> )
-=item ret: C<$hostname> (string)
+=item ret: C<$hostname> ( string )
=item since: 1.99_12
@@ -725,7 +733,7 @@
=item obj: C<$r>
( C<L<Apache::RequestRec object|docs::2.0::api::Apache::RequestRec>> )
-=item ret: C<$method> (string)
+=item ret: C<$method> ( string )
=item since: 1.99_12
@@ -737,23 +745,23 @@
=head2 C<method_number>
-META: Autogenerated - needs to be reviewed/completed
-
-Apache::M_GET, Apache::M_POST, etc.
+What's HTTP method was issued by the client (C<Apache::M_GET>,
+C<Apache::M_POST>, etc.)
- $methno = $r->method_number();
+ $methnum = $r->method_number();
=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<$methnum> (integer)
-=item since: 1.99_12
+=item since: 1.99_15
=back
+See the C<L<$r-E<gt>allowed|/C_allowed_>> entry for examples.
@@ -907,9 +915,9 @@
=item obj: C<$r>
( C<L<Apache::RequestRec object|docs::2.0::api::Apache::RequestRec>> )
-=item opt arg2: C<$path_info> (string)
+=item opt arg2: C<$path_info> ( string )
-=item ret: C<$path_info> (string)
+=item ret: C<$path_info> ( string )
=item since: 1.99_12
@@ -1077,7 +1085,7 @@
=item obj: C<$r>
( C<L<Apache::RequestRec object|docs::2.0::api::Apache::RequestRec>> )
-=item ret: C<$protocl> (string)
+=item ret: C<$protocl> ( string )
=item since: 1.99_12
@@ -1287,7 +1295,7 @@
=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_line> ( string )
=item since: 1.99_12
@@ -1320,7 +1328,7 @@
=item obj: C<$r>
( C<L<Apache::RequestRec object|docs::2.0::api::Apache::RequestRec>> )
-=item ret: C<$request> (string)
+=item ret: C<$request> ( string )
=item since: 1.99_12
@@ -1347,7 +1355,7 @@
=item obj: C<$r>
( C<L<Apache::RequestRec object|docs::2.0::api::Apache::RequestRec>> )
-=item ret: C<$unparsed_uri> (string)
+=item ret: C<$unparsed_uri> ( string )
=item since: 1.99_12
@@ -1371,9 +1379,9 @@
=item obj: C<$r>
( C<L<Apache::RequestRec object|docs::2.0::api::Apache::RequestRec>> )
-=item opt arg2: C<$uri> (string)
+=item opt arg2: C<$uri> ( string )
-=item ret: C<$uri> (string)
+=item ret: C<$uri> ( string )
=item since: 1.99_12
@@ -1428,14 +1436,102 @@
=item obj: C<$r>
( C<L<Apache::RequestRec object|docs::2.0::api::Apache::RequestRec>> )
-=item opt arg2: C<$user> (string)
+=item opt arg2: C<$user> ( string )
+
+=item ret: C<$user> ( string )
+
+=item since: 1.99_12
+
+=back
+
+
+
+
+=head1 Unsupported API
+
+C<Apache::RequestRec> also provides auto-generated Perl interface for
+a few other methods which aren't tested at the moment and therefore
+their API is a subject to change. These methods will be finalized
+later as a need arises. If you want to rely on any of the following
+methods please contact the L<the mod_perl development mailing
+list|maillist::dev> so we can help each other take the steps necessary
+to shift the method to an officially supported API.
+
+
+
+=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
+
+META: Apache::MethodList is not available at the moment
+
+
+
+
+=head2 C<allowed_xmethods>
+
+META: Autogenerated - needs to be reviewed/completed
+
+Array of extension methods
+
+ $array = $r->allowed_xmethods();
+
+=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<$user> (string)
+=item since: 1.99_12
+
+=back
+
+
+META: APR::ArrayHeader is not available at the moment
+
+
+
+
+=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 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 since: 1.99_12
=back
+
+
+META: APR::ArrayHeader is not available at the moment
1.4 +3 -1 modperl-docs/src/docs/2.0/api/Apache/ServerRec.pod
Index: ServerRec.pod
===================================================================
RCS file: /home/cvs/modperl-docs/src/docs/2.0/api/Apache/ServerRec.pod,v
retrieving revision 1.3
retrieving revision 1.4
diff -u -u -r1.3 -r1.4
--- ServerRec.pod 22 Jul 2004 05:37:51 -0000 1.3
+++ ServerRec.pod 24 Jul 2004 01:22:51 -0000 1.4
@@ -44,9 +44,11 @@
=head1 Description
-
C<Apache::ServerRec> provides the Perl API for Apache server_rec
object.
+
+C<L<Apache::ServerUtil|docs::2.0::api::Apache::ServerUtil>> provides
+an extra functionality.
---------------------------------------------------------------------
To unsubscribe, e-mail: [EMAIL PROTECTED]
For additional commands, e-mail: [EMAIL PROTECTED]
