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: [EMAIL PROTECTED]
For additional commands, e-mail: [EMAIL PROTECTED]
