1Request(3)            User Contributed Perl Documentation           Request(3)
2
3
4

NAME

6       APR::Request - wrapper for libapreq2's module/handle API.
7

SYNOPSIS

9         use APR::Request;
10
11         $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

DESCRIPTION

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
23       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

METHODS

28       APR::Request::Custom - derived from APR::Request.
29
30   handle
31           APR::Request::Custom->handle($pool,
32                                        $query_string,
33                                        $cookie_header,
34                                        $parser,
35                                        $read_limit,
36                                        $brigade)
37
38       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

METHODS

46       APR::Request
47
48   pool
49           $req->pool()
50
51       Returns the APR::Pool object associated to this handle.
52
53   bucket_alloc
54           $req->bucket_alloc()
55
56       Returns the APR::BucketAlloc object associated to this handle.
57
58   jar_status
59           $req->jar_status()
60
61       Returns the final status code of the handle's cookie header parser.
62
63   args_status
64           $req->args_status()
65
66       Returns the final status code of the handle's query-string parser.
67
68   body_status
69           $req->body_status()
70
71       Returns the final status code of the handle's body parser.
72
73   param_status
74           $req->param_status()
75
76       Returns "($req->args_status, $req->body_status)" in list context;
77       otherwise returns "$req->args_status || $req->body_status".
78
79   parse
80           $req->parse()
81
82       Parses the jar, args, and body tables. Returns "$req->jar_status,
83       $req->args_status, $req->body_status".
84
85           @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
91   jar
92           $req->jar()
93           $req->jar($key)
94
95       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
100       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
105       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
110           $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
115           $cookie = $req->jar("apache");
116           @cookies = $req->jar("apache");
117
118   args
119           $req->args()
120           $req->args($key)
121
122       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
127       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
131       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
136          $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
141          $foo = $req->args("foo");
142          @bar = $req->args("bar");
143
144   body
145           $req->body()
146           $req->body($key)
147
148       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
153       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
157       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
162           $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
167           $alpha = $req->body("alpha");
168           @beta = $req->body("beta");
169
170   param
171           $req->param()
172           $req->param($key)
173
174       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
179       With the $key argument, in scalar context this method fetches the first
180       matching param.  In list context it returns all matching params.
181
182       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
187           $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
192           $foo = $req->param("foo");
193           @foo = $req->param("foo");
194
195   upload
196           $req->upload()
197           $req->upload($key)
198
199       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
205       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
209       upload() will throw an APR::Request::Error object whenever
210       body_status() is non-zero.
211
212           $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
218           $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
223   read_limit
224           $req->read_limit()
225           $req->read_limit($set)
226
227       Get/set the read limit, which controls the total amount of bytes that
228       can be fed to the current parser.
229
230   brigade_limit
231           $req->brigade_limit()
232           $req->brigade_limit($set)
233
234       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
239   temp_dir
240           $req->temp_dir()
241           $req->temp_dir($set)
242
243       Get/set the spool directory for uploads which exceed the configured
244       brigade_limit.
245
246   disable_uploads
247           $req->disable_uploads()
248
249       Engage the disable_uploads hook for this request.
250
251   upload_hook
252           $req->upload_hook($callback)
253
254       Add an upload hook callback for this request.  The arguments to the
255       $callback sub are ($upload, $new_data).
256
257   import
258       Exports a list of subs into the caller's package.
259

SUBROUTINES

261       APR::Request
262
263   encode
264           encode($string)
265
266       Exportable sub which returns the url-encoded form of $string.
267
268   decode
269           decode($string)
270
271       Exportable sub which returns the url-decoded form of $string.
272

SUBCLASSING

274       APR::Request
275
276       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
283               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

METHODS

292         APR::Request::Cookie::Table - read-only version of APR::Table.
293
294       Tables in this class normally arise from calls to
295       "APR::Request::jar()".
296
297   cookie_class
298           $table->cookie_class()
299           $table->cookie_class($set)
300
301       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
307   get
308           $table->get($key)
309
310       Same as FETCH.
311
312   FETCH
313           $table->FETCH($key)
314
315       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
321   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
326   FIRSTKEY
327           $table->FIRSTKEY()
328
329       Returns the first key in the table.
330
331   NEXTKEY
332           $table->NEXTKEY()
333
334       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
339   do
340           $table->do($callback, @keys)
341
342       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
346       Note: The type of $value inserted into the callback depends on the
347       table's current cookie_class.
348

METHODS

350       APR::Request::Param::Table
351
352   param_class
353           $table->param_class()
354           $table->param_class($set)
355
356       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
362   get
363           $table->get($key)
364
365       Same as FETCH.
366
367   FETCH
368           $table->FETCH($key)
369
370       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
376   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
381   NEXTKEY
382           $table->NEXTKEY()
383
384       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
389   FIRSTKEY
390           $table->FIRSTKEY()
391
392       Returns the first key in the table.
393
394   do
395           $table->do($callback, @keys)
396
397       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
401       Note: The type of $value inserted into the callback depends on the
402       table's current value_class.
403

SEE ALSO

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
416             http://www.apache.org/licenses/LICENSE-2.0
417
418         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.
423
424
425
426perl v5.34.0                      2021-07-22                        Request(3)
Impressum