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.17 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 APR::Request::jar().
295
296   cookie_class
297           $table->cookie_class()
298           $table->cookie_class($set)
299
300       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
306   get
307           $table->get($key)
308
309       Same as FETCH.
310
311   FETCH
312           $table->FETCH($key)
313
314       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
320   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
325   FIRSTKEY
326           $table->FIRSTKEY()
327
328       Returns the first key in the table.
329
330   NEXTKEY
331           $table->NEXTKEY()
332
333       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
338   do
339           $table->do($callback, @keys)
340
341       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
345       Note: The type of $value inserted into the callback depends on the
346       table's current cookie_class.
347

METHODS

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

SEE ALSO

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
415             http://www.apache.org/licenses/LICENSE-2.0
416
417         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.
422
423
424
425perl v5.38.0                      2023-07-20                        Request(3)
Impressum