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

Unsupported API

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

Copyright

300       mod_perl 2.0 and its core modules are copyrighted under The Apache
301       Software License, Version 2.0.
302

Authors

304       The mod_perl development team and numerous contributors.
305
306
307
308perl v5.36.0                      2023-01-19   docs::api::Apache2::Response(3)