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.16 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
295 "APR::Request::jar()".
296 cookie_class
298 $table->cookie_class()
299 $table->cookie_class($set)
300 Get/set the class each table element is blessed into during a get or
302 FETCH call. If defined, the class must be derived from
303 APR::Request::Cookie. When called with $set, it returns the $table.
304 Otherwise it returns the name of the current class, or undef if no
305 cookie class is defined.
306 get
308 $table->get($key)
309 Same as FETCH.
311 FETCH
313 $table->FETCH($key)
314 In scalar context, this returns the first value matching $key (note:
316 see NEXTKEY for additional notes). The match is always case-
317 insensitive. In list context, this returns all matching values. Note:
318 the type of the return values depends on the table's current
319 cookie_class.
320 EXISTS
322 Synonym for "defined"; these tables are not allowed to contain
323 undefined values. Since these are constant tables, they don't
324 autovivify either.
325 FIRSTKEY
327 $table->FIRSTKEY()
328 Returns the first key in the table.
330 NEXTKEY
332 $table->NEXTKEY()
333 Returns the next key in the table. For perl 5.8+, if the key is
335 multivalued, a subsequent FETCH on this key will return the
336 corresponding value, until either NEXTKEY or FIRSTKEY is invoked again.
337 For perl 5.6, FETCH always returns the first value.
338 do
340 $table->do($callback, @keys)
341 Same as APR::Table::do; iterates over the table calling
343 $callback->($key, $value) for each matching @keys. If @keys is empty,
344 this iterates over the entire table.
345 Note: The type of $value inserted into the callback depends on the
347 table's current cookie_class.
348
350 APR::Request::Param::Table
351 param_class
353 $table->param_class()
354 $table->param_class($set)
355 Get/set the class each table element is blessed into during a "get" or
357 "FETCH" call. If defined, the class must be derived from
358 APR::Request::Param. When called with $set, it returns the $table.
359 Otherwise it returns the name of the current class, or undef if no
360 param class is defined.
361 get
363 $table->get($key)
364 Same as FETCH.
366 FETCH
368 $table->FETCH($key)
369 In scalar context, this returns the first value matching $key (see
371 NEXTKEY for additional notes on this). The match is always case-
372 insensitive. In list context, this returns all matching values. Note:
373 the type of the return values depends on the table's current
374 param_class.
375 EXISTS
377 Synonym for "defined"; these tables are not allowed to contain
378 undefined values. Since these are constant tables, they don't
379 autovivify either.
380 NEXTKEY
382 $table->NEXTKEY()
383 Returns the next key in the table. For perl 5.8+, if the key is
385 multivalued, a subsequent FETCH on this key will return the
386 corresponding value, until either NEXTKEY or FIRSTKEY is invoked again.
387 For perl 5.6, FETCH always returns the first value.
388 FIRSTKEY
390 $table->FIRSTKEY()
391 Returns the first key in the table.
393 do
395 $table->do($callback, @keys)
396 Same as APR::Table::do; iterates over the table calling
398 $callback->($key, $value) for each matching @keys. If @keys is empty,
399 this iterates over the entire table.
400 Note: The type of $value inserted into the callback depends on the
402 table's current value_class.
403
405 APR::Request::Error, APR::Request::Param, APR::Request::Cookie,
406 APR::Request::Parser
407
409 Licensed to the Apache Software Foundation (ASF) under one or more
410 contributor license agreements. See the NOTICE file distributed with
411 this work for additional information regarding copyright ownership.
412 The ASF licenses this file to You under the Apache License, Version 2.0
413 (the "License"); you may not use this file except in compliance with
414 the License. You may obtain a copy of the License at
415 http://www.apache.org/licenses/LICENSE-2.0
417 Unless required by applicable law or agreed to in writing, software
419 distributed under the License is distributed on an "AS IS" BASIS,
420 WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
421 See the License for the specific language governing permissions and
422 limitations under the License.
423perl v5.32.1 2021-05-15 Request(3)