APR::Request(3pm)

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.09 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
32           APR::Request::Custom->handle($pool,
33                                        $query_string,
34                                        $cookie_header,
35                                        $parser,
36                                        $read_limit,
37                                        $brigade)
38
39       Creates a new APR::Request::Custom object.  The $query_string and
40       $cookie_headers are immediately parsed into the "args" and "jar"
41       tables.  The $parser is an APR::Request::Parser object which is invoked
42       when fetching "body" entries from the $brigade.  The $read_limit repre‐
43       sents the maximum number of bytes this handle may feed into the parser.
44

METHODS

46       APR::Request
47
48       pool
49
50           $req->pool()
51
52       Returns the APR::Pool object associated to this handle.
53
54       bucket_alloc
55
56           $req->bucket_alloc()
57
58       Returns the APR::BucketAlloc object associated to this handle.
59
60       jar_status
61
62           $req->jar_status()
63
64       Returns the final status code of the handle's cookie header parser.
65
66       args_status
67
68           $req->args_status()
69
70       Returns the final status code of the handle's query-string parser.
71
72       body_status
73
74           $req->body_status()
75
76       Returns the final status code of the handle's body parser.
77
78       param_status
79
80           $req->param_status()
81
82       Returns "($req->args_status, $req->body_status)" in list context; oth‐
83       erwise returns "$req->args_status ⎪⎪ $req->body_status".
84
85       parse
86
87           $req->parse()
88
89       Parses the jar, args, and body tables. Returns "$req->jar_status,
90       $req->args_status, $req->body_status".
91
92           @status = $req->parse;
93           ok @status == 3;
94           ok $status[0] == $req->jar_status;
95           ok $status[1] == $req->args_status;
96           ok $status[2] == $req->body_status;
97
98       jar
99
100           $req->jar()
101           $req->jar($key)
102
103       With no arguments, this method returns a tied APR::Request::Cookie::Ta‐
104       ble object (or undef if the "Cookie" header is absent) in scalar con‐
105       text, or the names (in order, with repetitions) of all the parsed cook‐
106       ies.
107
108       With the $key argument, in scalar context this method fetches the first
109       matching cookie.  In list context it returns all matching cookies.  The
110       returned cookies are the values as they appeared in the incoming Cookie
111       header.
112
113       jar() will throw an APR::Request::Error object whenever jar_status() is
114       non-zero and the return value is potentially invalid (eg "scalar
115       $req->jar($key)" will not die if the desired cookie was successfully
116       parsed).
117
118           $jar = $req->jar;
119           @cookie_names = $req->jar;
120           ok $jar->isa("APR::Request::Cookie::Table");
121           ok shift @cookie_names eq $_ for keys %$jar;
122
123           $cookie = $req->jar("apache");
124           @cookies = $req->jar("apache");
125
126       args
127
128           $req->args()
129           $req->args($key)
130
131       With no arguments, this method returns a tied APR::Request::Param::Ta‐
132       ble object (or undef if the query string is absent) in scalar context,
133       or the names (in order, with repetitions) of all the parsed query-
134       string arguments.
135
136       With the $key argument, in scalar context this method fetches the first
137       matching query-string arg.  In list context it returns all matching
138       args.
139
140       args() will throw an APR::Request::Error object whenever args_status()
141       is non-zero and the return value is potentially invalid (eg "scalar
142       $req->args($key)" will not die if the desired query argument was suc‐
143       cessfully parsed).
144
145          $args = $req->args;
146          @arg_names = $req->args;
147          ok $args->isa("APR::Request::Param::Table");
148          ok shift @arg_names eq $_ for keys %$args;
149
150          $foo = $req->args("foo");
151          @bar = $req->args("bar");
152
153       body
154
155           $req->body()
156           $req->body($key)
157
158       With no arguments, this method returns a tied APR::Request::Param::Ta‐
159       ble object (or undef if the request body is absent) in scalar context,
160       or the names (in order, with repetitions) of all the parsed cookies.
161
162       With the $key argument, in scalar context this method fetches the first
163       matching body param.  In list context it returns all matching body
164       params.
165
166       body() will throw an APR::Request::Error object whenever body_status()
167       is non-zero and the return value is potentially invalid (eg "scalar
168       $req->body($key)" will not die if the desired body param was success‐
169       fully parsed).
170
171           $body = $req->body;
172           @body_names = $req->body;
173           ok $body->isa("APR::Request::Param::Table");
174           ok shift @body_names eq $_ for keys %$body;
175
176           $alpha = $req->body("alpha");
177           @beta = $req->body("beta");
178
179       param
180
181           $req->param()
182           $req->param($key)
183
184       With no arguments, this method returns a tied APR::Request::Param::Ta‐
185       ble object (or undef, if the query string and request body are absent)
186       in scalar context, or the names (in order, with repetitions) of all the
187       incoming (args + body) params.
188
189       With the $key argument, in scalar context this method fetches the first
190       matching param.  In list context it returns all matching params.
191
192       param() will throw an APR::Request::Error object whenever param_sta‐
193       tus() is non-zero and the return value is potentially invalid (eg
194       "scalar $req->param($key)" will not die if the desired param was suc‐
195       cessfully parsed).
196
197           $param = $req->param;
198           @param_names = $req->param;
199           ok $param->isa("APR::Request::Param::Table");
200           ok shift @param_names eq $_ for keys %$param;
201
202           $foo = $req->param("foo");
203           @foo = $req->param("foo");
204
205       upload
206
207           $req->upload()
208           $req->upload($key)
209
210       With no arguments, this method returns a tied APR::Request::Param::Ta‐
211       ble object (or undef if the request body is absent) in scalar context
212       (whose entries are APR::Request::Param objects), or the names (in
213       order, with repetitions) of all the incoming uploads.
214
215       With the $key argument, in scalar context this method fetches the first
216       matching upload.  In list context it returns all matching uploads.  The
217       return values are APR::Request::Param objects.
218
219       upload() will throw an APR::Request::Error object whenever body_sta‐
220       tus() is non-zero.
221
222           $uploads = $req->upload;
223           @upload_names = $req->upload;
224           ok $uploads->isa("APR::Request::Param::Table");
225           ok shift @upload_names eq $_ for keys %$uploads;
226           ok $_->upload for values %$uploads;
227
228           $up = $req->upload("beta");
229           @ups = $req->upload("beta");
230           ok $_->isa("APR::Request::Param") for $up, @ups;
231           ok $_->upload for $up, @ups;
232
233       read_limit
234
235           $req->read_limit()
236           $req->read_limit($set)
237
238       Get/set the read limit, which controls the total amount of bytes that
239       can be fed to the current parser.
240
241       brigade_limit
242
243           $req->brigade_limit()
244           $req->brigade_limit($set)
245
246       Get/set the brigade_limit for the current parser.  This limit deter‐
247       mines how many bytes of a file upload that the parser may spool into
248       main memory.  Uploads exceeding this limit are written directly to
249       disk.
250
251       temp_dir
252
253           $req->temp_dir()
254           $req->temp_dir($set)
255
256       Get/set the spool directory for uploads which exceed the configured
257       brigade_limit.
258
259       disable_uploads
260
261           $req->disable_uploads()
262
263       Engage the disable_uploads hook for this request.
264
265       upload_hook
266
267           $req->upload_hook($callback)
268
269       Add an upload hook callback for this request.  The arguments to the
270       $callback sub are ($upload, $new_data).
271
272       import
273
274       Exports a list of subs into the caller's package.
275

SUBROUTINES

277       APR::Request
278
279       encode
280
281           encode($string)
282
283       Exportable sub which returns the url-encoded form of $string.
284
285       decode
286
287           decode($string)
288
289       Exportable sub which returns the url-decoded form of $string.
290

SUBCLASSING

292       APR::Request
293
294       If the instances of your subclass are hash references then you can
295       actually inherit from APR::Request as long as the APR::Request object
296       is stored in an attribute called "r" or "_r". (The APR::Request class
297       effectively does the delegation for you automagically, as long as it
298       knows where to find the APR::Request object to delegate to.)  For exam‐
299       ple:
300
301               package MySubClass;
302               use APR::Request::Custom;
303               our @ISA = qw(APR::Request);
304               sub new {
305                   my($class, @args) = @_;
306                   return bless { r => APR::Request::Custom->handle(@args) }, $class;
307               }
308

METHODS

310         APR::Request::Cookie::Table - read-only version of APR::Table.
311
312       Tables in this class normally arise from calls to
313       "APR::Request::jar()".
314
315       cookie_class
316
317           $table->cookie_class()
318           $table->cookie_class($set)
319
320       Get/set the class each table element is blessed into during a get or
321       FETCH call.  If defined, the class must be derived from
322       APR::Request::Cookie.  When called with $set, it returns the $table.
323       Otherwise it returns the name of the current class, or undef if no
324       cookie class is defined.
325
326       get
327
328           $table->get($key)
329
330       Same as FETCH.
331
332       FETCH
333
334           $table->FETCH($key)
335
336       In scalar context, this returns the first value matching $key (note:
337       see NEXTKEY for additional notes).  The match is always case-insensi‐
338       tive.  In list context, this returns all matching values.  Note: the
339       type of the return values depends on the table's current cookie_class.
340
341       EXISTS
342
343       Synonym for "defined"; these tables are not allowed to contain unde‐
344       fined values. Since these are constant tables, they don't autovivify
345       either.
346
347       FIRSTKEY
348
349           $table->FIRSTKEY()
350
351       Returns the first key in the table.
352
353       NEXTKEY
354
355           $table->NEXTKEY()
356
357       Returns the next key in the table.  For perl 5.8+, if the key is multi‐
358       valued, a subsequent FETCH on this key will return the corresponding
359       value, until either NEXTKEY or FIRSTKEY is invoked again.  For perl
360       5.6, FETCH always returns the first value.
361
362       do
363
364           $table->do($callback, @keys)
365
366       Same as APR::Table::do; iterates over the table calling $call‐
367       back->($key, $value) for each matching @keys.  If @keys is empty, this
368       iterates over the entire table.
369
370       Note: The type of $value inserted into the callback depends on the ta‐
371       ble's current cookie_class.
372

METHODS

374       APR::Request::Param::Table
375
376       param_class
377
378           $table->param_class()
379           $table->param_class($set)
380
381       Get/set the class each table element is blessed into during a "get" or
382       "FETCH" call.  If defined, the class must be derived from
383       APR::Request::Param.  When called with $set, it returns the $table.
384       Otherwise it returns the name of the current class, or undef if no
385       param class is defined.
386
387       get
388
389           $table->get($key)
390
391       Same as FETCH.
392
393       FETCH
394
395           $table->FETCH($key)
396
397       In scalar context, this returns the first value matching $key (see NEX‐
398       TKEY for additional notes on this).  The match is always case-insensi‐
399       tive.  In list context, this returns all matching values.  Note: the
400       type of the return values depends on the table's current param_class.
401
402       EXISTS
403
404       Synonym for "defined"; these tables are not allowed to contain unde‐
405       fined values. Since these are constant tables, they don't autovivify
406       either.
407
408       NEXTKEY
409
410           $table->NEXTKEY()
411
412       Returns the next key in the table.  For perl 5.8+, if the key is multi‐
413       valued, a subsequent FETCH on this key will return the corresponding
414       value, until either NEXTKEY or FIRSTKEY is invoked again.  For perl
415       5.6, FETCH always returns the first value.
416
417       FIRSTKEY
418
419           $table->FIRSTKEY()
420
421       Returns the first key in the table.
422
423       do
424
425           $table->do($callback, @keys)
426
427       Same as APR::Table::do; iterates over the table calling $call‐
428       back->($key, $value) for each matching @keys.  If @keys is empty, this
429       iterates over the entire table.
430
431       Note: The type of $value inserted into the callback depends on the ta‐
432       ble's current value_class.
433

COPYRIGHT

439         Licensed to the Apache Software Foundation (ASF) under one or more
440         contributor license agreements.  See the NOTICE file distributed with
441         this work for additional information regarding copyright ownership.
442         The ASF licenses this file to You under the Apache License, Version 2.0
443         (the "License"); you may not use this file except in compliance with
444         the License.  You may obtain a copy of the License at
445
446             http://www.apache.org/licenses/LICENSE-2.0
447
448         Unless required by applicable law or agreed to in writing, software
449         distributed under the License is distributed on an "AS IS" BASIS,
450         WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
451         See the License for the specific language governing permissions and
452         limitations under the License.
453
454
455
456perl v5.8.8                       2007-10-25                        Request(3)