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 Response.pod
Date Mon, 19 Jul 2004 00:04:24 GMT
stas        2004/07/18 17:04:24

  Modified:    src/docs/2.0/api/Apache Response.pod
  Log:
  work in progress
  
  Revision  Changes    Path
  1.5       +167 -65   modperl-docs/src/docs/2.0/api/Apache/Response.pod
  
  Index: Response.pod
  ===================================================================
  RCS file: /home/cvs/modperl-docs/src/docs/2.0/api/Apache/Response.pod,v
  retrieving revision 1.4
  retrieving revision 1.5
  diff -u -u -r1.4 -r1.5
  --- Response.pod	22 May 2004 02:03:27 -0000	1.4
  +++ Response.pod	19 Jul 2004 00:04:24 -0000	1.5
  @@ -16,7 +16,10 @@
   
   =head1 Description
   
  -META: to be completed
  +C<Apache::Response> provides the L<Apache request
  +object|docs::2.0::api::Apache::RequestRec> utilities API for dealing
  +with HTTP response generation process.
  +
   
   
   
  @@ -30,38 +33,76 @@
   
   =head2 C<custom_response>
   
  -META: Autogenerated - needs to be reviewed/completed
  -
   Install a custom response handler for a given status
   
     $r->custom_response($status, $string);
   
   =over 4
   
  -=item obj: C<$r> (C<L<Apache::RequestRec|docs::2.0::api::Apache::RequestRec>>)
  +=item obj: C<$r>
  +( C<L<Apache::RequestRec object|docs::2.0::api::Apache::RequestRec>> )
   
   The current request
   
  -=item arg1: C<$status> (integer)
  +=item arg1: C<$status> ( C<L<Apache::Const
  +constant|docs::2.0::api::Apache::Const>> )
   
   The status for which the custom response should be used
  +(e.g. C<Apache::AUTH_REQUIRED>)
   
   =item arg2: C<$string> (string)
   
  -The custom response.  This can be a static string, a file
  -or a URL
  +The custom response to use.  This can be a static string, or a URL,
  +full or just the uri path (I</foo/bar.txt>).
   
   =item ret: no return value
   
  +=item since: 1.99_10
  +
   =back
   
  +C<custom_response()> doesn't alter the response code, but is used to
  +replace the standard response body. For example, here is how to change
  +the response body for the access handler failure:
  +
  +  package MyApache::MyShop;
  +  use Apache::Response ();
  +  use Apache::Const -compile => qw(FORBIDDEN OK);
  +  sub access {
  +      my $r = shift;
  +   
  +      if (MyApache::MyShop::tired_squirrels()) {
  +          $r->custom_response(Apache::FORBIDDEN,
  +              "It's siesta time, please try later");
  +          return Apache::FORBIDDEN;
  +      }
  +  
  +      return Apache::OK;
  +  }
  +  ...
  +
  +  # httpd.conf
  +  PerlModule MyApache::MyShop
  +  <Location /TestAPI__custom_response>
  +      AuthName dummy
  +      AuthType none
  +      PerlAccessHandler   MyApache::MyShop::access
  +      PerlResponseHandler MyApache::MyShop::response
  +  </Location>
   
  +When squirrels can't run any more, the handler will return 403, with
  +the custom message:
   
  +  It's siesta time, please try later
   
   
  -=head2 C<make_etag>
   
  -META: Autogenerated - needs to be reviewed/completed
  +
  +
  +
  +
  +
  +=head2 C<make_etag>
   
   Construct an entity tag from the resource information.  If it's a real
   file, build in some of the file characteristics.
  @@ -70,7 +111,8 @@
   
   =over 4
   
  -=item obj: C<$r> (C<L<Apache::RequestRec|docs::2.0::api::Apache::RequestRec>>)
  +=item obj: C<$r>
  +( C<L<Apache::RequestRec object|docs::2.0::api::Apache::RequestRec>> )
   
   The current request
   
  @@ -83,50 +125,62 @@
   
   The entity tag
   
  +=item since: 1.99_10
  +
   =back
   
   
   
   
   
  -=head2 C<meets_conditions>
   
  -META: Autogenerated - needs to be reviewed/completed
   
  -Implements condition GET rules for HTTP/1.1 specification.  This function
  -inspects the client headers and determines if the response fulfills
  -the requirements specified.
  +=head2 C<meets_conditions>
  +
  +Implements condition C<GET> rules for HTTP/1.1 specification.  This
  +function inspects the client headers and determines if the response
  +fulfills the specified requirements.
   
  -  $ret = $r->meets_conditions();
  +  $status = $r->meets_conditions();
   
   =over 4
   
  -=item obj: C<$r> (C<L<Apache::RequestRec|docs::2.0::api::Apache::RequestRec>>)
  +=item obj: C<$r>
  +( C<L<Apache::RequestRec object|docs::2.0::api::Apache::RequestRec>> )
   
   The current request
   
  -=item ret: C<$ret> (integer)
  +=item ret: C<$status> ( C<L<Apache::Const
  +status constant|docs::2.0::api::Apache::Const>> )
   
  -1 if the response fulfills the condition GET rules, 0 otherwise
  +C<Apache::OK> if the response fulfills the condition GET
  +rules. Otherwise some other status code (which should be returned to
  +Apache).
  +
  +=item since: 1.99_10
   
   =back
   
  +Refer to the L<Generating Correct HTTP
  +Headers|docs::general::correct_headers::correct_headers/> document
  +for an indepth discussion of this method.
   
   
   
   
  -=head2 C<rationalize_mtime>
   
  -META: Autogenerated - needs to be reviewed/completed
   
  -Return the latest rational time from a request/mtime pair.  Mtime is
  -returned unless it's in the future, in which case we return the current time.
   
  -  $rat_mtime = $r->rationalize_mtime($mtime);
  +=head2 C<rationalize_mtime>
  +
  +Return the latest rational time from a request/mtime pair.
  +
  +  $mtime_rat = $r->rationalize_mtime($mtime);
   
   =over 4
   
  -=item obj: C<$r> (C<L<Apache::RequestRec|docs::2.0::api::Apache::RequestRec>>)
  +=item obj: C<$r>
  +( C<L<Apache::RequestRec object|docs::2.0::api::Apache::RequestRec>> )
   
   The current request
   
  @@ -134,12 +188,58 @@
   
   The last modified time
   
  -=item ret: C<$rat_mtime> (number)
  +=item ret: C<$mtime_rat> (number)
   
  -the latest rational time.
  +the latest rational time from a request/mtime pair.  Mtime is
  +returned unless it's in the future, in which case we return the
  +current time.
  +
  +=item since: 1.99_10
  +
  +=back
  +
  +
  +
  +
  +
  +
  +
  +=head2 C<send_cgi_header>
  +
  +Parse the header
  +
  +  $r->send_cgi_header($buffer);
  +
  +=over 4
  +
  +=item obj: C<$r>
  +( C<L<Apache::RequestRec object|docs::2.0::api::Apache::RequestRec>> )
  +
  +=item arg1: C<$buffer> (string)
  +
  +headers and optionally a response body
  +
  +=item ret: no return value
  +
  +=item since: 1.99_10
   
   =back
   
  +This method is really for back-compatibility with mod_perl 1.0. It's
  +very inefficient to send headers this way, because of the parsing
  +overhead.
  +
  +If there is a response body following the headers it'll be handled too
  +(as if it was sent via
  +C<L<print()|docs::2.0::api::Apache::RequestIO::C_print_/>>).
  +
  +Notice that if only HTTP headers are included they won't be sent until
  +some body is sent (again the "send" part is retained from the mod_perl
  +1.0 method).
  +
  +
  +
  +
   
   
   
  @@ -148,13 +248,18 @@
   
   META: Autogenerated - needs to be reviewed/completed
   
  -Send error back to client.
  +Send an "error" response back to client. It is used for any response
  +that can be generated by the server from the request record.  This
  +includes all 204 (no content), 3xx (redirect), 4xx (client error), and
  +5xx (server error) messages that have not been redirected to another
  +handler via the ErrorDocument feature.
   
     $r->send_error_response($recursive_error);
   
   =over 4
   
  -=item obj: C<$r> (C<L<Apache::RequestRec|docs::2.0::api::Apache::RequestRec>>)
  +=item obj: C<$r>
  +( C<L<Apache::RequestRec object|docs::2.0::api::Apache::RequestRec>> )
   
   The current request
   
  @@ -168,6 +273,8 @@
   
   =item ret: no return value
   
  +=item since: 1.99_10
  +
   =back
   
   
  @@ -184,7 +291,8 @@
   
   =over 4
   
  -=item obj: C<$r> (C<L<Apache::RequestRec|docs::2.0::api::Apache::RequestRec>>)
  +=item obj: C<$r>
  +( C<L<Apache::RequestRec object|docs::2.0::api::Apache::RequestRec>> )
   
   The current request
   
  @@ -204,6 +312,8 @@
   
   The number of bytes sent
   
  +=item since: 1.99_10
  +
   =back
   
   
  @@ -220,7 +330,8 @@
   
   =over 4
   
  -=item obj: C<$r> (C<L<Apache::RequestRec|docs::2.0::api::Apache::RequestRec>>)
  +=item obj: C<$r>
  +( C<L<Apache::RequestRec object|docs::2.0::api::Apache::RequestRec>> )
   
   The current request
   
  @@ -230,6 +341,8 @@
   
   =item ret: no return value
   
  +=item since: 1.99_10
  +
   =back
   
   
  @@ -246,10 +359,13 @@
   
   =over 4
   
  -=item obj: C<$r> (C<L<Apache::RequestRec|docs::2.0::api::Apache::RequestRec>>)
  +=item obj: C<$r>
  +( C<L<Apache::RequestRec object|docs::2.0::api::Apache::RequestRec>> )
   
   =item ret: no return value
   
  +=item since: 1.99_10
  +
   =back
   
   
  @@ -266,7 +382,8 @@
   
   =over 4
   
  -=item obj: C<$r> (C<L<Apache::RequestRec|docs::2.0::api::Apache::RequestRec>>)
  +=item obj: C<$r>
  +( C<L<Apache::RequestRec object|docs::2.0::api::Apache::RequestRec>> )
   
   The current request
   
  @@ -274,37 +391,13 @@
   
   1 if keepalive can be set, 0 otherwise
   
  -=back
  -
  -
  -
  -
  -
  -=head2 C<update_mtime>
  -
  -META: Autogenerated - needs to be reviewed/completed
  -
  -Function to set the r-E<gt>mtime field to the specified value if it's
  -later than what's already there.
  -
  -  $r->update_mtime($dependency_mtime);
  -
  -=over 4
  -
  -=item obj: C<$r> (C<L<Apache::RequestRec|docs::2.0::api::Apache::RequestRec>>)
  -
  -The current request
  -
  -=item arg1: C<$dependency_mtime> (number)
  -
  -=item ret: no return value
  +=item since: 1.99_10
   
   =back
   
   
   
   
  -
   =head2 C<set_last_modified>
   
   META: Autogenerated - needs to be reviewed/completed
  @@ -315,35 +408,44 @@
   
   =over 4
   
  -=item obj: C<$r> (C<L<Apache::RequestRec|docs::2.0::api::Apache::RequestRec>>)
  +=item obj: C<$r>
  +( C<L<Apache::RequestRec object|docs::2.0::api::Apache::RequestRec>> )
   
   =item arg1: C<$mtime> (number)
   
   =item ret: no return value
   
  -=back
  +=item since: 1.99_10
   
  +=back
   
   
   
   
  -=head2 C<send_cgi_header>
  +=head2 C<update_mtime>
   
   META: Autogenerated - needs to be reviewed/completed
   
  +Function to set the r-E<gt>mtime field to the specified value if it's
  +later than what's already there.
   
  -
  -  $r->send_cgi_header($buffer);
  +  $r->update_mtime($dependency_mtime);
   
   =over 4
   
  -=item obj: C<$r> (C<L<Apache::RequestRec|docs::2.0::api::Apache::RequestRec>>)
  +=item obj: C<$r>
  +( C<L<Apache::RequestRec object|docs::2.0::api::Apache::RequestRec>> )
   
  -=item arg1: C<$buffer> (string)
  +The current request
  +
  +=item arg1: C<$dependency_mtime> (number)
   
   =item ret: no return value
   
  +=item since: 1.99_10
  +
   =back
  +
   
   
   
  
  
  

---------------------------------------------------------------------
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