1Request(3) User Contributed Perl Documentation Request(3)
2
6 APR::Request - wrapper for libapreq2's module/handle API.
7
9 use APR::Request;
10 $req = APR::Request::Custom->handle($pool,
12 "foo=arg1&bar=arg2",
13 "apache=quux",
14 $parser, 1e6, $bb);
15 $param = $req->param("foo");
16 $cookie = $req->jar("apache");
17
19 The "APR::Request" module provides the base methods for interfacing
20 with libapreq2's module API. It also provides a few utility functions
21 and constants.
22 This manpage documents version 2.17 of the APR::Request,
24 APR::Request::Custom, APR::Request::Cookie::Table, and
25 APR::Request::Param::Table packages.
26
28 APR::Request::Custom - derived from APR::Request.
29 handle
31 APR::Request::Custom->handle($pool,
32 $query_string,
33 $cookie_header,
34 $parser,
35 $read_limit,
36 $brigade)
37 Creates a new APR::Request::Custom object. The $query_string and
39 $cookie_headers are immediately parsed into the "args" and "jar"
40 tables. The $parser is an APR::Request::Parser object which is invoked
41 when fetching "body" entries from the $brigade. The $read_limit
42 represents the maximum number of bytes this handle may feed into the
43 parser.
44
46 APR::Request
47 pool
49 $req->pool()
50 Returns the APR::Pool object associated to this handle.
52 bucket_alloc
54 $req->bucket_alloc()
55 Returns the APR::BucketAlloc object associated to this handle.
57 jar_status
59 $req->jar_status()
60 Returns the final status code of the handle's cookie header parser.
62 args_status
64 $req->args_status()
65 Returns the final status code of the handle's query-string parser.
67 body_status
69 $req->body_status()
70 Returns the final status code of the handle's body parser.
72 param_status
74 $req->param_status()
75 Returns "($req->args_status, $req->body_status)" in list context;
77 otherwise returns "$req->args_status || $req->body_status".
78 parse
80 $req->parse()
81 Parses the jar, args, and body tables. Returns "$req->jar_status,
83 $req->args_status, $req->body_status".
84 @status = $req->parse;
86 ok @status == 3;
87 ok $status[0] == $req->jar_status;
88 ok $status[1] == $req->args_status;
89 ok $status[2] == $req->body_status;
90 jar
92 $req->jar()
93 $req->jar($key)
94 With no arguments, this method returns a tied
96 APR::Request::Cookie::Table object (or undef if the "Cookie" header is
97 absent) in scalar context, or the names (in order, with repetitions) of
98 all the parsed cookies.
99 With the $key argument, in scalar context this method fetches the first
101 matching cookie. In list context it returns all matching cookies. The
102 returned cookies are the values as they appeared in the incoming Cookie
103 header.
104 jar() will throw an APR::Request::Error object whenever jar_status() is
106 non-zero and the return value is potentially invalid (eg "scalar
107 $req->jar($key)" will not die if the desired cookie was successfully
108 parsed).
109 $jar = $req->jar;
111 @cookie_names = $req->jar;
112 ok $jar->isa("APR::Request::Cookie::Table");
113 ok shift @cookie_names eq $_ for keys %$jar;
114 $cookie = $req->jar("apache");
116 @cookies = $req->jar("apache");
117 args
119 $req->args()
120 $req->args($key)
121 With no arguments, this method returns a tied
123 APR::Request::Param::Table object (or undef if the query string is
124 absent) in scalar context, or the names (in order, with repetitions) of
125 all the parsed query-string arguments.
126 With the $key argument, in scalar context this method fetches the first
128 matching query-string arg. In list context it returns all matching
129 args.
130 args() will throw an APR::Request::Error object whenever args_status()
132 is non-zero and the return value is potentially invalid (eg "scalar
133 $req->args($key)" will not die if the desired query argument was
134 successfully parsed).
135 $args = $req->args;
137 @arg_names = $req->args;
138 ok $args->isa("APR::Request::Param::Table");
139 ok shift @arg_names eq $_ for keys %$args;
140 $foo = $req->args("foo");
142 @bar = $req->args("bar");
143 body
145 $req->body()
146 $req->body($key)
147 With no arguments, this method returns a tied
149 APR::Request::Param::Table object (or undef if the request body is
150 absent) in scalar context, or the names (in order, with repetitions) of
151 all the parsed cookies.
152 With the $key argument, in scalar context this method fetches the first
154 matching body param. In list context it returns all matching body
155 params.
156 body() will throw an APR::Request::Error object whenever body_status()
158 is non-zero and the return value is potentially invalid (eg "scalar
159 $req->body($key)" will not die if the desired body param was
160 successfully parsed).
161 $body = $req->body;
163 @body_names = $req->body;
164 ok $body->isa("APR::Request::Param::Table");
165 ok shift @body_names eq $_ for keys %$body;
166 $alpha = $req->body("alpha");
168 @beta = $req->body("beta");
169 param
171 $req->param()
172 $req->param($key)
173 With no arguments, this method returns a tied
175 APR::Request::Param::Table object (or undef, if the query string and
176 request body are absent) in scalar context, or the names (in order,
177 with repetitions) of all the incoming (args + body) params.
178 With the $key argument, in scalar context this method fetches the first
180 matching param. In list context it returns all matching params.
181 param() will throw an APR::Request::Error object whenever
183 param_status() is non-zero and the return value is potentially invalid
184 (eg "scalar $req->param($key)" will not die if the desired param was
185 successfully parsed).
186 $param = $req->param;
188 @param_names = $req->param;
189 ok $param->isa("APR::Request::Param::Table");
190 ok shift @param_names eq $_ for keys %$param;
191 $foo = $req->param("foo");
193 @foo = $req->param("foo");
194 upload
196 $req->upload()
197 $req->upload($key)
198 With no arguments, this method returns a tied
200 APR::Request::Param::Table object (or undef if the request body is
201 absent) in scalar context (whose entries are APR::Request::Param
202 objects), or the names (in order, with repetitions) of all the incoming
203 uploads.
204 With the $key argument, in scalar context this method fetches the first
206 matching upload. In list context it returns all matching uploads. The
207 return values are APR::Request::Param objects.
208 upload() will throw an APR::Request::Error object whenever
210 body_status() is non-zero.
211 $uploads = $req->upload;
213 @upload_names = $req->upload;
214 ok $uploads->isa("APR::Request::Param::Table");
215 ok shift @upload_names eq $_ for keys %$uploads;
216 ok $_->upload for values %$uploads;
217 $up = $req->upload("beta");
219 @ups = $req->upload("beta");
220 ok $_->isa("APR::Request::Param") for $up, @ups;
221 ok $_->upload for $up, @ups;
222 read_limit
224 $req->read_limit()
225 $req->read_limit($set)
226 Get/set the read limit, which controls the total amount of bytes that
228 can be fed to the current parser.
229 brigade_limit
231 $req->brigade_limit()
232 $req->brigade_limit($set)
233 Get/set the brigade_limit for the current parser. This limit
235 determines how many bytes of a file upload that the parser may spool
236 into main memory. Uploads exceeding this limit are written directly to
237 disk.
238 temp_dir
240 $req->temp_dir()
241 $req->temp_dir($set)
242 Get/set the spool directory for uploads which exceed the configured
244 brigade_limit.
245 disable_uploads
247 $req->disable_uploads()
248 Engage the disable_uploads hook for this request.
250 upload_hook
252 $req->upload_hook($callback)
253 Add an upload hook callback for this request. The arguments to the
255 $callback sub are ($upload, $new_data).
256 import
258 Exports a list of subs into the caller's package.
259
261 APR::Request
262 encode
264 encode($string)
265 Exportable sub which returns the url-encoded form of $string.
267 decode
269 decode($string)
270 Exportable sub which returns the url-decoded form of $string.
272
274 APR::Request
275 If the instances of your subclass are hash references then you can
277 actually inherit from APR::Request as long as the APR::Request object
278 is stored in an attribute called "r" or "_r". (The APR::Request class
279 effectively does the delegation for you automagically, as long as it
280 knows where to find the APR::Request object to delegate to.) For
281 example:
282 package MySubClass;
284 use APR::Request::Custom;
285 our @ISA = qw(APR::Request);
286 sub new {
287 my($class, @args) = @_;
288 return bless { r => APR::Request::Custom->handle(@args) }, $class;
289 }
290
292 APR::Request::Cookie::Table - read-only version of APR::Table.
293 Tables in this class normally arise from calls to APR::Request::jar().
295 cookie_class
297 $table->cookie_class()
298 $table->cookie_class($set)
299 Get/set the class each table element is blessed into during a get or
301 FETCH call. If defined, the class must be derived from
302 APR::Request::Cookie. When called with $set, it returns the $table.
303 Otherwise it returns the name of the current class, or undef if no
304 cookie class is defined.
305 get
307 $table->get($key)
308 Same as FETCH.
310 FETCH
312 $table->FETCH($key)
313 In scalar context, this returns the first value matching $key (note:
315 see NEXTKEY for additional notes). The match is always case-
316 insensitive. In list context, this returns all matching values. Note:
317 the type of the return values depends on the table's current
318 cookie_class.
319 EXISTS
321 Synonym for "defined"; these tables are not allowed to contain
322 undefined values. Since these are constant tables, they don't
323 autovivify either.
324 FIRSTKEY
326 $table->FIRSTKEY()
327 Returns the first key in the table.
329 NEXTKEY
331 $table->NEXTKEY()
332 Returns the next key in the table. For perl 5.8+, if the key is
334 multivalued, a subsequent FETCH on this key will return the
335 corresponding value, until either NEXTKEY or FIRSTKEY is invoked again.
336 For perl 5.6, FETCH always returns the first value.
337 do
339 $table->do($callback, @keys)
340 Same as APR::Table::do; iterates over the table calling
342 $callback->($key, $value) for each matching @keys. If @keys is empty,
343 this iterates over the entire table.
344 Note: The type of $value inserted into the callback depends on the
346 table's current cookie_class.
347
349 APR::Request::Param::Table
350 param_class
352 $table->param_class()
353 $table->param_class($set)
354 Get/set the class each table element is blessed into during a "get" or
356 "FETCH" call. If defined, the class must be derived from
357 APR::Request::Param. When called with $set, it returns the $table.
358 Otherwise it returns the name of the current class, or undef if no
359 param class is defined.
360 get
362 $table->get($key)
363 Same as FETCH.
365 FETCH
367 $table->FETCH($key)
368 In scalar context, this returns the first value matching $key (see
370 NEXTKEY for additional notes on this). The match is always case-
371 insensitive. In list context, this returns all matching values. Note:
372 the type of the return values depends on the table's current
373 param_class.
374 EXISTS
376 Synonym for "defined"; these tables are not allowed to contain
377 undefined values. Since these are constant tables, they don't
378 autovivify either.
379 NEXTKEY
381 $table->NEXTKEY()
382 Returns the next key in the table. For perl 5.8+, if the key is
384 multivalued, a subsequent FETCH on this key will return the
385 corresponding value, until either NEXTKEY or FIRSTKEY is invoked again.
386 For perl 5.6, FETCH always returns the first value.
387 FIRSTKEY
389 $table->FIRSTKEY()
390 Returns the first key in the table.
392 do
394 $table->do($callback, @keys)
395 Same as APR::Table::do; iterates over the table calling
397 $callback->($key, $value) for each matching @keys. If @keys is empty,
398 this iterates over the entire table.
399 Note: The type of $value inserted into the callback depends on the
401 table's current value_class.
402
404 APR::Request::Error, APR::Request::Param, APR::Request::Cookie,
405 APR::Request::Parser
406
408 Licensed to the Apache Software Foundation (ASF) under one or more
409 contributor license agreements. See the NOTICE file distributed with
410 this work for additional information regarding copyright ownership.
411 The ASF licenses this file to You under the Apache License, Version 2.0
412 (the "License"); you may not use this file except in compliance with
413 the License. You may obtain a copy of the License at
414 http://www.apache.org/licenses/LICENSE-2.0
416 Unless required by applicable law or agreed to in writing, software
418 distributed under the License is distributed on an "AS IS" BASIS,
419 WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
420 See the License for the specific language governing permissions and
421 limitations under the License.
422perl v5.36.0 2023-01-19 Request(3)