perl-docs-cvs mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From s...@apache.org
Subject cvs commit: modperl-docs/src/docs/2.0/api/Apache RequestRec.pod
Date Sat, 24 Jul 2004 07:07:07 GMT
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: docs-cvs-unsubscribe@perl.apache.org
For additional commands, e-mail: docs-cvs-help@perl.apache.org


Mime
View raw message