stas 2004/07/24 00:07:07
Modified: src/docs/2.0/api/Apache RequestRec.pod
Log:
working on the never ending Apache::RequestRec
Revision Changes Path
1.23 +120 -32 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.22
retrieving revision 1.23
diff -u -u -r1.22 -r1.23
--- RequestRec.pod 24 Jul 2004 01:22:51 -0000 1.22
+++ RequestRec.pod 24 Jul 2004 07:07:07 -0000 1.23
@@ -125,7 +125,7 @@
=item obj: C<$r>
( C<L<Apache::RequestRec object|docs::2.0::api::Apache::RequestRec>> )
-=item opt arg2: C<$newval> (string)
+=item opt arg1: C<$newval> (string)
If this argument is passed then a new auth type is assigned. For example:
@@ -443,22 +443,26 @@
=head2 C<filename>
-META: Autogenerated - needs to be reviewed/completed
-
-The filename on disk corresponding to this response
+Get/set the filename on disk corresponding to this response (the
+result of the I<URI --E<gt> filename> translation).
- $filename = $r->filename();
- $r->filename($filename);
+ $filename = $r->filename();
+ $prev_filename = $r->filename($new_filename);
=over 4
=item obj: C<$r>
( C<L<Apache::RequestRec object|docs::2.0::api::Apache::RequestRec>> )
-=item opt arg2: C<$filename> ( string )
+=item opt arg1: C<$new_filename> ( string )
+
+new value
=item ret: C<$filename> ( string )
+the current filename, or the previous value if the optional
+C<$new_filename> argument was passed
+
=item since: 1.99_12
=back
@@ -473,7 +477,7 @@
Get and set the I<finfo> request record member:
$finfo = $r->finfo();
- $finfo = $r->finfo($finfo);
+ $r->finfo($finfo);
=over 4
@@ -532,22 +536,30 @@
+
+
=head2 C<handler>
-META: Autogenerated - needs to be reviewed/completed
+Get/set the equivalent of the C<SetHandler> directive.
- $handler = $r->handler();
- $handler = $r->handler($new_handler);
+ $handler = $r->handler();
+ $prev_handler = $r->handler($new_handler);
=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 opt arg1: C<$new_handler> ( string )
+
+the new handler.
=item ret: C<$handler> ( string )
+the current handler.
+
+If C<$new_handler> is passed, the previous value is returned.
+
=item since: 1.99_12
=back
@@ -560,9 +572,8 @@
=head2 C<header_only>
-META: Autogenerated - needs to be reviewed/completed
-
-HEAD request, as opposed to GET
+Did the client has asked for headers only? e.g. if the request method
+was B<HEAD>.
$status = $r->header_only();
@@ -571,7 +582,9 @@
=item obj: C<$r>
( C<L<Apache::RequestRec object|docs::2.0::api::Apache::RequestRec>> )
-=item ret: C<$status> (integer)
+=item ret: C<$status> ( boolean )
+
+Returns true if the client is asking for headers only, false otherwise
=item since: 1.99_12
@@ -580,6 +593,8 @@
+
+
=head2 C<headers_in>
Get/set the request MIME headers:
@@ -612,6 +627,7 @@
+
=head2 C<headers_out>
Get/set MIME response headers, printed only on 2xx responses.
@@ -640,9 +656,8 @@
-=head2 C<hostname>
-META: Autogenerated - needs to be reviewed/completed
+=head2 C<hostname>
Host, as set by full URI or Host:
@@ -667,8 +682,6 @@
=head2 C<input_filters>
-META: Autogenerated - needs to be reviewed/completed
-
A list of input filters to be used for this request
$input_filters = $r->input_filters();
@@ -684,8 +697,57 @@
=back
+For example instead of using
+C<L<$r-E<gt>read()|docs::2.0::api::Apache::RequestIO/C_read_>> to read
+the POST data, one could use an explicit walk through incoming bucket
+brigades to get that data. The following function C<read_post()> does
+just that (in fact that's what
+C<L<$r-E<gt>read()|docs::2.0::api::Apache::RequestIO/C_read_>> does
+behind the scenes):
+
+ use APR::Brigade ();
+ use APR::Bucket ();
+ use Apache::Filter ();
+
+ use Apache::Const -compile => qw(MODE_READBYTES);
+ use APR::Const -compile => qw(SUCCESS BLOCK_READ);
+
+ use constant IOBUFSIZE => 8192;
+
+ sub read_post {
+ my $r = shift;
+
+ my $bb = APR::Brigade->new($r->pool,
+ $r->connection->bucket_alloc);
+
+ my $data = '';
+ my $seen_eos = 0;
+ do {
+ $r->input_filters->get_brigade($bb, Apache::MODE_READBYTES,
+ APR::BLOCK_READ, IOBUFSIZE);
+
+ for (my $b = $bb->first; $b; $b = $bb->next($b)) {
+ if ($b->is_eos) {
+ $seen_eos++;
+ last;
+ }
+
+ if ($b->read(my $buf)) {
+ $data .= $buf;
+ }
+
+ $b->remove; # optimization to reuse memory
+ }
+
+ } while (!$seen_eos);
+
+ $bb->destroy;
+
+ return $data;
+ }
-
+As you can see C<$r-E<gt>input_filters> gives us a pointer to the last
+of the top of the incoming filters stack.
@@ -781,7 +843,7 @@
=item obj: C<$r>
( C<L<Apache::RequestRec object|docs::2.0::api::Apache::RequestRec>> )
-=item opt arg2: C<$new_mtime> (number)
+=item opt arg1: C<$new_mtime> (number)
=item ret: C<$mtime> (number)
@@ -856,7 +918,7 @@
=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 opt arg1: 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>> )
@@ -874,9 +936,8 @@
=head2 C<output_filters>
-META: Autogenerated - needs to be reviewed/completed
-
-A list of output filters to be used for this request
+A pointer to the first filter in the output filter stack for this
+request:
$output_filters = $r->output_filters();
@@ -885,13 +946,40 @@
=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<$output_filters>
+( C<L<Apache::Filter object|docs::2.0::api::Apache::Filter>> )
=item since: 1.99_12
=back
-
+For example instead of using
+C<L<$r-E<gt>print()|docs::2.0::api::Apache::RequestIO/C_print_>> to
+send the response body, one could send the data directly to the first
+output filter. The following function C<send_response_body()> does
+just that:
+
+ use APR::Brigade ();
+ use APR::Bucket ();
+ use Apache::Filter ();
+
+ sub send_response_body {
+ my($r, $data) = @_;
+
+ my $bb = APR::Brigade->new($r->pool,
+ $r->connection->bucket_alloc);
+
+ my $b = APR::Bucket->new($data);
+ $bb->insert_tail($b);
+ $r->output_filters->fflush($bb);
+ $bb->destroy;
+ }
+
+In fact that's what
+C<L<$r-E<gt>read()|docs::2.0::api::Apache::RequestIO/C_read_>> does
+behind the scenes. But it also knows to parse HTTP headers passed
+together with the data and it also implements buffering, which the
+above function does not.
@@ -915,7 +1003,7 @@
=item obj: C<$r>
( C<L<Apache::RequestRec object|docs::2.0::api::Apache::RequestRec>> )
-=item opt arg2: C<$path_info> ( string )
+=item opt arg1: C<$path_info> ( string )
=item ret: C<$path_info> ( string )
@@ -1264,7 +1352,7 @@
=item obj: C<$r>
( C<L<Apache::RequestRec object|docs::2.0::api::Apache::RequestRec>> )
-=item opt arg2: C<$new_status> (integer)
+=item opt arg1: C<$new_status> (integer)
If C<$new_status> is passed the new status is assigned.
@@ -1379,7 +1467,7 @@
=item obj: C<$r>
( C<L<Apache::RequestRec object|docs::2.0::api::Apache::RequestRec>> )
-=item opt arg2: C<$uri> ( string )
+=item opt arg1: C<$uri> ( string )
=item ret: C<$uri> ( string )
@@ -1436,7 +1524,7 @@
=item obj: C<$r>
( C<L<Apache::RequestRec object|docs::2.0::api::Apache::RequestRec>> )
-=item opt arg2: C<$user> ( string )
+=item opt arg1: C<$user> ( string )
=item ret: C<$user> ( string )
---------------------------------------------------------------------
To unsubscribe, e-mail: [EMAIL PROTECTED]
For additional commands, e-mail: [EMAIL PROTECTED]
