stas 2004/07/21 23:31:41
Modified: src/docs/2.0/api/Apache Response.pod
Log:
complete Apache::Response
Revision Changes Path
1.7 +110 -68 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.6
retrieving revision 1.7
diff -u -u -r1.6 -r1.7
--- Response.pod 22 Jul 2004 05:37:51 -0000 1.6
+++ Response.pod 22 Jul 2004 06:31:41 -0000 1.7
@@ -8,8 +8,25 @@
=head1 Synopsis
use Apache::Response ();
+
+ $r->custom_response(Apache::FORBIDDEN, "No Entry today");
+
+ $etag = $r->make_etag($force_weak);
+ $r->set_etag();
+ $status = $r->meets_conditions();
+
+ $mtime_rat = $r->rationalize_mtime($mtime);
+ $r->set_last_modified($mtime);
+ $r->update_mtime($mtime);
+
+ $r->send_cgi_header($buffer);
+
+ $r->set_content_length($length);
+
+ $ret = $r->set_keepalive();
+
+
-META: to be completed
@@ -243,18 +260,11 @@
+=head2 C<set_content_length>
-=head2 C<send_error_response>
-
-META: Autogenerated - needs to be reviewed/completed
-
-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.
+Set the content length for this request.
- $r->send_error_response($recursive_error);
+ $r->set_content_length($length);
=over 4
@@ -263,13 +273,9 @@
The current request
-=item arg1: C<$recursive_error> (string)
+=item arg1: C<$length> (integer)
-last arg indicates error status in case we get an error in the process
-of trying to deal with an C<ErrorDocument> to handle some other error.
-In that case, we print the default report for the first thing that
-went wrong, and more briefly report on the problem with the
-C<ErrorDocument>.
+The new content length
=item ret: no return value
@@ -281,36 +287,20 @@
-=head2 C<send_mmap>
-META: Autogenerated - needs to be reviewed/completed
-Send an MMAP'ed file to the client
+=head2 C<set_etag>
- $ret = $r->send_mmap($mm, $offset, $length);
+Set the E-tag outgoing header
+
+ $r->set_etag();
=over 4
=item obj: C<$r>
( C<L<Apache::RequestRec object|docs::2.0::api::Apache::RequestRec>> )
-The current request
-
-=item arg1: C<$mm> (C<L<APR::Mmap|docs::2.0::api::APR::Mmap>>)
-
-The MMAP'ed file to send
-
-=item arg2: C<$offset> (number)
-
-The offset into the MMAP to start sending
-
-=item arg3: C<$length> (integer)
-
-The amount of data to send
-
-=item ret: C<$ret> (integer)
-
-The number of bytes sent
+=item ret: no return value
=item since: 1.99_10
@@ -320,11 +310,13 @@
-=head2 C<set_content_length>
-Set the content length for this request.
- $r->set_content_length($length);
+=head2 C<set_keepalive>
+
+Set the keepalive status for this request
+
+ $ret = $r->set_keepalive();
=over 4
@@ -333,35 +325,41 @@
The current request
-=item arg1: C<$length> (integer)
-
-The new content length
+=item ret: C<$ret> ( boolean )
-=item ret: no return value
+true if keepalive can be set, false otherwise
=item since: 1.99_10
=back
+It's called by C<ap_http_header_filter()>. For the complete
+complicated logic implemented by this method see
+F<httpd-2.0/server/http_protocol.c>.
+=head2 C<set_last_modified>
-=head2 C<set_etag>
-
-META: Autogenerated - needs to be reviewed/completed
-
-Set the E-tag outgoing header
+sets the C<Last-Modified> response header field to the value of the
+mtime field in the request structure -- rationalized to keep it from
+being in the future.
- $r->set_etag();
+ $r->set_last_modified($mtime);
=over 4
=item obj: C<$r>
( C<L<Apache::RequestRec object|docs::2.0::api::Apache::RequestRec>> )
+=item opt arg1: C<$mtime> ( time in microseconds )
+
+if the C<$mtime> argument is passed,
+L<$r-E<gt>update_mtime|/C_update_mtime_> will be first run with that
+argument.
+
=item ret: no return value
=item since: 1.99_10
@@ -372,13 +370,13 @@
-=head2 C<set_keepalive>
-
-META: Autogenerated - needs to be reviewed/completed
+=head2 C<update_mtime>
-Set the keepalive status for this request
+Set the
+C<L<$r-E<gt>mtime|docs::2.0::api::Apache::RequestRec/C_mtime_>> field
+to the specified value if it's later than what's already there.
- $ret = $r->set_keepalive();
+ $r->update_mtime($mtime);
=over 4
@@ -387,31 +385,56 @@
The current request
-=item ret: C<$ret> (integer)
+=item arg1: C<$mtime> ( time in microseconds )
-1 if keepalive can be set, 0 otherwise
+=item ret: no return value
=item since: 1.99_10
=back
+See also: L<$r-E<gt>set_last_modified|/C_set_last_modified_>.
-=head2 C<set_last_modified>
-META: Autogenerated - needs to be reviewed/completed
+=head1 Unsupported API
+C<Apache::Response> 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.
- $r->set_last_modified($mtime);
+
+
+
+=head2 C<send_error_response>
+
+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 object|docs::2.0::api::Apache::RequestRec>> )
-=item arg1: C<$mtime> (number)
+The current request
+
+=item arg1: C<$recursive_error> ( boolean )
+
+the error status in case we get an error in the process of trying to
+deal with an C<ErrorDocument> to handle some other error. In that
+case, we print the default report for the first thing that went wrong,
+and more briefly report on the problem with the C<ErrorDocument>.
=item ret: no return value
@@ -419,17 +442,19 @@
=back
+META: it's really an internal Apache method, I'm not quite sure how
+can it be used externally.
-=head2 C<update_mtime>
+
+=head2 C<send_mmap>
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.
+Send an MMAP'ed file to the client
- $r->update_mtime($dependency_mtime);
+ $ret = $r->send_mmap($mm, $offset, $length);
=over 4
@@ -438,13 +463,30 @@
The current request
-=item arg1: C<$dependency_mtime> (number)
+=item arg1: C<$mm> (C<L<APR::Mmap|docs::2.0::api::APR::Mmap>>)
-=item ret: no return value
+The MMAP'ed file to send
+
+=item arg2: C<$offset> (number)
+
+The offset into the MMAP to start sending
+
+=item arg3: C<$length> (integer)
+
+The amount of data to send
+
+=item ret: C<$ret> (integer)
+
+The number of bytes sent
=item since: 1.99_10
=back
+
+META: requires a working APR::Mmap, which is not supported at the
+moment.
+
+
---------------------------------------------------------------------
To unsubscribe, e-mail: [EMAIL PROTECTED]
For additional commands, e-mail: [EMAIL PROTECTED]
