Apache2::Response(3pm)

1docs::api::Apache2::ResUpsoenrseC(o3n)tributed Perl Docudmoecnst:a:taipoin::Apache2::Response(3)
2
3
4

NAME

6       Apache2::Response - Perl API for Apache HTTP request response methods
7

Synopsis

9         use Apache2::Response ();
10
11         $r->custom_response(Apache2::Const::FORBIDDEN, "No Entry today");
12
13         $etag = $r->make_etag($force_weak);
14         $r->set_etag();
15         $status = $r->meets_conditions();
16
17         $mtime_rat = $r->rationalize_mtime($mtime);
18         $r->set_last_modified($mtime);
19         $r->update_mtime($mtime);
20
21         $r->send_cgi_header($buffer);
22
23         $r->set_content_length($length);
24
25         $ret = $r->set_keepalive();
26

Description

28       "Apache2::Response" provides the Apache request object utilities API
29       for dealing with HTTP response generation process.
30

API

32       "Apache2::Response" provides the following functions and/or methods:
33
34       "custom_response"
35
36       Install a custom response handler for a given status
37
38         $r->custom_response($status, $string);
39
40       obj: $r ( "Apache2::RequestRec object" )
41           The current request
42
43       arg1: $status ( "Apache2::Const constant" )
44           The status for which the custom response should be used (e.g.
45           "Apache2::Const::AUTH_REQUIRED")
46
47       arg2: $string (string)
48           The custom response to use.  This can be a static string, or a URL,
49           full or just the uri path (/foo/bar.txt).
50
51       ret: no return value
52       since: 2.0.00
53
54       "custom_response()" doesn't alter the response code, but is used to
55       replace the standard response body. For example, here is how to change
56       the response body for the access handler failure:
57
58         package MyApache2::MyShop;
59         use Apache2::Response ();
60         use Apache2::Const -compile => qw(FORBIDDEN OK);
61         sub access {
62             my $r = shift;
63
64             if (MyApache2::MyShop::tired_squirrels()) {
65                 $r->custom_response(Apache2::Const::FORBIDDEN,
66                     "It's siesta time, please try later");
67                 return Apache2::Const::FORBIDDEN;
68             }
69
70             return Apache2::Const::OK;
71         }
72         ...
73
74         # httpd.conf
75         PerlModule MyApache2::MyShop
76         <Location /TestAPI__custom_response>
77             AuthName dummy
78             AuthType none
79             PerlAccessHandler   MyApache2::MyShop::access
80             PerlResponseHandler MyApache2::MyShop::response
81         </Location>
82
83       When squirrels can't run any more, the handler will return 403, with
84       the custom message:
85
86         It's siesta time, please try later
87
88       "make_etag"
89
90       Construct an entity tag from the resource information.  If it's a real
91       file, build in some of the file characteristics.
92
93         $etag = $r->make_etag($force_weak);
94
95       obj: $r ( "Apache2::RequestRec object" )
96           The current request
97
98       arg1: $force_weak (number)
99           Force the entity tag to be weak - it could be modified again in as
100           short an interval.
101
102       ret: $etag (string)
103           The entity tag
104
105       since: 2.0.00
106
107       "meets_conditions"
108
109       Implements condition "GET" rules for HTTP/1.1 specification.  This
110       function inspects the client headers and determines if the response
111       fulfills the specified requirements.
112
113         $status = $r->meets_conditions();
114
115       obj: $r ( "Apache2::RequestRec object" )
116           The current request
117
118       ret: $status ( "Apache2::Const status constant" )
119           "Apache2::Const::OK" if the response fulfills the condition GET
120           rules. Otherwise some other status code (which should be returned
121           to Apache).
122
123       since: 2.0.00
124
125       Refer to the Generating Correct HTTP Headers document for an indepth
126       discussion of this method.
127
128       "rationalize_mtime"
129
130       Return the latest rational time from a request/mtime pair.
131
132         $mtime_rat = $r->rationalize_mtime($mtime);
133
134       obj: $r ( "Apache2::RequestRec object" )
135           The current request
136
137       arg1: $mtime ( time in seconds )
138           The last modified time
139
140       ret: $mtime_rat ( time in seconds )
141           the latest rational time from a request/mtime pair.  Mtime is
142           returned unless it's in the future, in which case we return the
143           current time.
144
145       since: 2.0.00
146
147       "send_cgi_header"
148
149       Parse the header
150
151         $r->send_cgi_header($buffer);
152
153       obj: $r ( "Apache2::RequestRec object" )
154       arg1: $buffer (string)
155           headers and optionally a response body
156
157       ret: no return value
158       since: 2.0.00
159
160       This method is really for back-compatibility with mod_perl 1.0. It's
161       very inefficient to send headers this way, because of the parsing over‐
162       head.
163
164       If there is a response body following the headers it'll be handled too
165       (as if it was sent via "print()").
166
167       Notice that if only HTTP headers are included they won't be sent until
168       some body is sent (again the "send" part is retained from the mod_perl
169       1.0 method).
170
171       "set_content_length"
172
173       Set the content length for this request.
174
175         $r->set_content_length($length);
176
177       obj: $r ( "Apache2::RequestRec object" )
178           The current request
179
180       arg1: $length (integer)
181           The new content length
182
183       ret: no return value
184       since: 2.0.00
185
186       "set_etag"
187
188       Set the E-tag outgoing header
189
190         $r->set_etag();
191
192       obj: $r ( "Apache2::RequestRec object" )
193       ret: no return value
194       since: 2.0.00
195
196       "set_keepalive"
197
198       Set the keepalive status for this request
199
200         $ret = $r->set_keepalive();
201
202       obj: $r ( "Apache2::RequestRec object" )
203           The current request
204
205       ret: $ret ( boolean )
206           true if keepalive can be set, false otherwise
207
208       since: 2.0.00
209
210       It's called by "ap_http_header_filter()". For the complete complicated
211       logic implemented by this method see httpd-2.0/server/http_protocol.c.
212
213       "set_last_modified"
214
215       sets the "Last-Modified" response header field to the value of the
216       mtime field in the request structure -- rationalized to keep it from
217       being in the future.
218
219         $r->set_last_modified($mtime);
220
221       obj: $r ( "Apache2::RequestRec object" )
222       opt arg1: $mtime ( time in seconds )
223           if the $mtime argument is passed, $r->update_mtime will be first
224           run with that argument.
225
226       ret: no return value
227       since: 2.0.00
228
229       "update_mtime"
230
231       Set the "$r->mtime" field to the specified value if it's later than
232       what's already there.
233
234         $r->update_mtime($mtime);
235
236       obj: $r ( "Apache2::RequestRec object" )
237           The current request
238
239       arg1: $mtime ( time in seconds )
240       ret: no return value
241       since: 2.0.00
242
243       See also: $r->set_last_modified.
244

Unsupported API

246       "Apache2::Response" also provides auto-generated Perl interface for a
247       few other methods which aren't tested at the moment and therefore their
248       API is a subject to change. These methods will be finalized later as a
249       need arises. If you want to rely on any of the following methods please
250       contact the the mod_perl development mailing list so we can help each
251       other take the steps necessary to shift the method to an officially
252       supported API.
253
254       "send_error_response"
255
256       Send an "error" response back to client. It is used for any response
257       that can be generated by the server from the request record.  This
258       includes all 204 (no content), 3xx (redirect), 4xx (client error), and
259       5xx (server error) messages that have not been redirected to another
260       handler via the ErrorDocument feature.
261
262         $r->send_error_response($recursive_error);
263
264       obj: $r ( "Apache2::RequestRec object" )
265           The current request
266
267       arg1: $recursive_error ( boolean )
268           the error status in case we get an error in the process of trying
269           to deal with an "ErrorDocument" to handle some other error.  In
270           that case, we print the default report for the first thing that
271           went wrong, and more briefly report on the problem with the "Error‐
272           Document".
273
274       ret: no return value
275       since: 2.0.00
276
277       META: it's really an internal Apache method, I'm not quite sure how can
278       it be used externally.
279
280       "send_mmap"
281
282       META: Autogenerated - needs to be reviewed/completed
283
284       Send an MMAP'ed file to the client
285
286         $ret = $r->send_mmap($mm, $offset, $length);
287
288       obj: $r ( "Apache2::RequestRec object" )
289           The current request
290
291       arg1: $mm ("APR::Mmap")
292           The MMAP'ed file to send
293
294       arg2: $offset (number)
295           The offset into the MMAP to start sending
296
297       arg3: $length (integer)
298           The amount of data to send
299
300       ret: $ret (integer)
301           The number of bytes sent
302
303       since: 2.0.00
304
305       META: requires a working APR::Mmap, which is not supported at the
306       moment.
307

Copyright

312       mod_perl 2.0 and its core modules are copyrighted under The Apache
313       Software License, Version 2.0.
314

Authors

316       The mod_perl development team and numerous contributors.
317
318
319
320perl v5.8.8                       2006-11-19   docs::api::Apache2::Response(3)