Debian Codegraph @

docs/html/group__apreq__xs__apr__request.html

raw
1 <html>
2 <head>
3 <link rel="stylesheet" type="text/css" href="dox.css" />
4 <title>libapreq2-2.17: APR::Request</title>
5 </head>
6 <body>
7 <div id="page-header">
8 <p class="menu">
9 <a href="http://www.apache.org/">Apache Software Foundation</a> &gt; <a href="http://httpd.apache.org">HTTP Server Project</a> &gt;
10 <a href="http://httpd.apache.org/apreq/">Request Library Subproject</a></p>
11 <p class="apache">Apache HTTP Server Request Library</p>
12 <img alt="" src="feather.gif" /></div>
13 <!-- Generated by Doxygen 1.9.1 -->
14 <script type="text/javascript" src="menudata.js"></script>
15 <script type="text/javascript" src="menu.js"></script>
16 <script type="text/javascript">
17 /* @license magnet:?xt=urn:btih:cf05388f2679ee054f2beb29a391d25f4e673ac3&amp;dn=gpl-2.0.txt GPL-v2 */
18 $(function() {
19 initMenu('',false,false,'search.php','Search');
20 });
21 /* @license-end */</script>
22 <div id="main-nav"></div>
23 </div><!-- top -->
24 <div class="header">
25 <div class="headertitle">
26 <div class="title">APR::Request<div class="ingroups"><a class="el" href="group__apreq__lang.html">Language Bindings</a> &raquo; <a class="el" href="group__apreq__xs.html">Perl</a></div></div> </div>
27 </div><!--header-->
28 <div class="contents">
29
30
31
32
33 <ul id="index">
34 <li><a href="#NAME">NAME</a></li>
35 <li><a href="#SYNOPSIS">SYNOPSIS</a></li>
36 <li><a href="#DESCRIPTION">DESCRIPTION</a></li>
37 <li><a href="#METHODS">METHODS</a>
38 <ul>
39 <li><a href="#handle">handle</a></li>
40 </ul>
41 </li>
42 <li><a href="#METHODS1">METHODS</a>
43 <ul>
44 <li><a href="#pool">pool</a></li>
45 <li><a href="#bucket_alloc">bucket_alloc</a></li>
46 <li><a href="#jar_status">jar_status</a></li>
47 <li><a href="#args_status">args_status</a></li>
48 <li><a href="#body_status">body_status</a></li>
49 <li><a href="#param_status">param_status</a></li>
50 <li><a href="#parse">parse</a></li>
51 <li><a href="#jar">jar</a></li>
52 <li><a href="#args">args</a></li>
53 <li><a href="#body">body</a></li>
54 <li><a href="#param">param</a></li>
55 <li><a href="#upload">upload</a></li>
56 <li><a href="#read_limit">read_limit</a></li>
57 <li><a href="#brigade_limit">brigade_limit</a></li>
58 <li><a href="#temp_dir">temp_dir</a></li>
59 <li><a href="#disable_uploads">disable_uploads</a></li>
60 <li><a href="#upload_hook">upload_hook</a></li>
61 <li><a href="#import">import</a></li>
62 </ul>
63 </li>
64 <li><a href="#SUBROUTINES">SUBROUTINES</a>
65 <ul>
66 <li><a href="#encode">encode</a></li>
67 <li><a href="#decode">decode</a></li>
68 </ul>
69 </li>
70 <li><a href="#SUBCLASSING">SUBCLASSING</a></li>
71 <li><a href="#METHODS2">METHODS</a>
72 <ul>
73 <li><a href="#cookie_class">cookie_class</a></li>
74 <li><a href="#get">get</a></li>
75 <li><a href="#FETCH">FETCH</a></li>
76 <li><a href="#EXISTS">EXISTS</a></li>
77 <li><a href="#FIRSTKEY">FIRSTKEY</a></li>
78 <li><a href="#NEXTKEY">NEXTKEY</a></li>
79 <li><a href="#do">do</a></li>
80 </ul>
81 </li>
82 <li><a href="#METHODS3">METHODS</a>
83 <ul>
84 <li><a href="#param_class">param_class</a></li>
85 <li><a href="#get1">get</a></li>
86 <li><a href="#FETCH1">FETCH</a></li>
87 <li><a href="#EXISTS1">EXISTS</a></li>
88 <li><a href="#NEXTKEY1">NEXTKEY</a></li>
89 <li><a href="#FIRSTKEY1">FIRSTKEY</a></li>
90 <li><a href="#do1">do</a></li>
91 </ul>
92 </li>
93 <li><a href="#SEE-ALSO">SEE ALSO</a></li>
94 <li><a href="#COPYRIGHT">COPYRIGHT</a></li>
95 </ul>
96
97 <h1 id="NAME">NAME</h1>
98
99 <p>APR::Request - wrapper for libapreq2&#39;s module/handle API.</p>
100
101 <h1 id="SYNOPSIS">SYNOPSIS</h1>
102
103 <pre><code>use APR::Request;
104
105 $req = APR::Request::Custom-&gt;handle($pool,
106 &quot;foo=arg1&amp;bar=arg2&quot;,
107 &quot;apache=quux&quot;,
108 $parser, 1e6, $bb);
109 $param = $req-&gt;param(&quot;foo&quot;);
110 $cookie = $req-&gt;jar(&quot;apache&quot;);</code></pre>
111
112 <h1 id="DESCRIPTION">DESCRIPTION</h1>
113
114 <p>The <code>APR::Request</code> module provides the base methods for interfacing with libapreq2&#39;s module API. It also provides a few utility functions and constants.</p>
115
116 <p>This manpage documents version 2.17 of the APR::Request, APR::Request::Custom, APR::Request::Cookie::Table, and APR::Request::Param::Table packages.</p>
117
118 <h1 id="METHODS">METHODS</h1>
119
120 <p>APR::Request::Custom - derived from APR::Request.</p>
121
122 <h2 id="handle">handle</h2>
123
124 <pre><code>APR::Request::Custom-&gt;handle($pool,
125 $query_string,
126 $cookie_header,
127 $parser,
128 $read_limit,
129 $brigade)</code></pre>
130
131 <p>Creates a new APR::Request::Custom object. The $query_string and $cookie_headers are immediately parsed into the <code>args</code> and <code>jar</code> tables. The $parser is an APR::Request::Parser object which is invoked when fetching <code>body</code> entries from the $brigade. The $read_limit represents the maximum number of bytes this handle may feed into the parser.</p>
132
133 <h1 id="METHODS1">METHODS</h1>
134
135 <p>APR::Request</p>
136
137 <h2 id="pool">pool</h2>
138
139 <pre><code>$req-&gt;pool()</code></pre>
140
141 <p>Returns the APR::Pool object associated to this handle.</p>
142
143 <h2 id="bucket_alloc">bucket_alloc</h2>
144
145 <pre><code>$req-&gt;bucket_alloc()</code></pre>
146
147 <p>Returns the APR::BucketAlloc object associated to this handle.</p>
148
149 <h2 id="jar_status">jar_status</h2>
150
151 <pre><code>$req-&gt;jar_status()</code></pre>
152
153 <p>Returns the final status code of the handle&#39;s cookie header parser.</p>
154
155 <h2 id="args_status">args_status</h2>
156
157 <pre><code>$req-&gt;args_status()</code></pre>
158
159 <p>Returns the final status code of the handle&#39;s query-string parser.</p>
160
161 <h2 id="body_status">body_status</h2>
162
163 <pre><code>$req-&gt;body_status()</code></pre>
164
165 <p>Returns the final status code of the handle&#39;s body parser.</p>
166
167 <h2 id="param_status">param_status</h2>
168
169 <pre><code>$req-&gt;param_status()</code></pre>
170
171 <p>Returns <code>($req-&gt;args_status, $req-&gt;body_status)</code> in list context; otherwise returns <code>$req-&gt;args_status || $req-&gt;body_status</code>.</p>
172
173 <h2 id="parse">parse</h2>
174
175 <pre><code>$req-&gt;parse()</code></pre>
176
177 <p>Parses the jar, args, and body tables. Returns <code>$req-&gt;jar_status, $req-&gt;args_status, $req-&gt;body_status</code>.</p>
178
179 <pre><code>@status = $req-&gt;parse;
180 ok @status == 3;
181 ok $status[0] == $req-&gt;jar_status;
182 ok $status[1] == $req-&gt;args_status;
183 ok $status[2] == $req-&gt;body_status;</code></pre>
184
185 <h2 id="jar">jar</h2>
186
187 <pre><code>$req-&gt;jar()
188 $req-&gt;jar($key)</code></pre>
189
190 <p>With no arguments, this method returns a tied APR::Request::Cookie::Table object (or undef if the &quot;Cookie&quot; header is absent) in scalar context, or the names (in order, with repetitions) of all the parsed cookies.</p>
191
192 <p>With the <code>$key</code> argument, in scalar context this method fetches the first matching cookie. In list context it returns all matching cookies. The returned cookies are the values as they appeared in the incoming Cookie header.</p>
193
194 <p>jar() will throw an APR::Request::Error object whenever jar_status() is non-zero and the return value is potentially invalid (eg <code>scalar $req-&gt;jar($key)</code> will not die if the desired cookie was successfully parsed).</p>
195
196 <pre><code>$jar = $req-&gt;jar;
197 @cookie_names = $req-&gt;jar;
198 ok $jar-&gt;isa(&quot;APR::Request::Cookie::Table&quot;);
199 ok shift @cookie_names eq $_ for keys %$jar;
200
201 $cookie = $req-&gt;jar(&quot;apache&quot;);
202 @cookies = $req-&gt;jar(&quot;apache&quot;);</code></pre>
203
204 <h2 id="args">args</h2>
205
206 <pre><code>$req-&gt;args()
207 $req-&gt;args($key)</code></pre>
208
209 <p>With no arguments, this method returns a tied APR::Request::Param::Table object (or undef if the query string is absent) in scalar context, or the names (in order, with repetitions) of all the parsed query-string arguments.</p>
210
211 <p>With the <code>$key</code> argument, in scalar context this method fetches the first matching query-string arg. In list context it returns all matching args.</p>
212
213 <p>args() will throw an APR::Request::Error object whenever args_status() is non-zero and the return value is potentially invalid (eg <code>scalar $req-&gt;args($key)</code> will not die if the desired query argument was successfully parsed).</p>
214
215 <pre><code>$args = $req-&gt;args;
216 @arg_names = $req-&gt;args;
217 ok $args-&gt;isa(&quot;APR::Request::Param::Table&quot;);
218 ok shift @arg_names eq $_ for keys %$args;
219
220 $foo = $req-&gt;args(&quot;foo&quot;);
221 @bar = $req-&gt;args(&quot;bar&quot;);</code></pre>
222
223 <h2 id="body">body</h2>
224
225 <pre><code>$req-&gt;body()
226 $req-&gt;body($key)</code></pre>
227
228 <p>With no arguments, this method returns a tied APR::Request::Param::Table object (or undef if the request body is absent) in scalar context, or the names (in order, with repetitions) of all the parsed cookies.</p>
229
230 <p>With the <code>$key</code> argument, in scalar context this method fetches the first matching body param. In list context it returns all matching body params.</p>
231
232 <p>body() will throw an APR::Request::Error object whenever body_status() is non-zero and the return value is potentially invalid (eg <code>scalar $req-&gt;body($key)</code> will not die if the desired body param was successfully parsed).</p>
233
234 <pre><code>$body = $req-&gt;body;
235 @body_names = $req-&gt;body;
236 ok $body-&gt;isa(&quot;APR::Request::Param::Table&quot;);
237 ok shift @body_names eq $_ for keys %$body;
238
239 $alpha = $req-&gt;body(&quot;alpha&quot;);
240 @beta = $req-&gt;body(&quot;beta&quot;);</code></pre>
241
242 <h2 id="param">param</h2>
243
244 <pre><code>$req-&gt;param()
245 $req-&gt;param($key)</code></pre>
246
247 <p>With no arguments, this method returns a tied APR::Request::Param::Table object (or undef, if the query string and request body are absent) in scalar context, or the names (in order, with repetitions) of all the incoming (args + body) params.</p>
248
249 <p>With the <code>$key</code> argument, in scalar context this method fetches the first matching param. In list context it returns all matching params.</p>
250
251 <p>param() will throw an APR::Request::Error object whenever param_status() is non-zero and the return value is potentially invalid (eg <code>scalar $req-&gt;param($key)</code> will not die if the desired param was successfully parsed).</p>
252
253 <pre><code>$param = $req-&gt;param;
254 @param_names = $req-&gt;param;
255 ok $param-&gt;isa(&quot;APR::Request::Param::Table&quot;);
256 ok shift @param_names eq $_ for keys %$param;
257
258 $foo = $req-&gt;param(&quot;foo&quot;);
259 @foo = $req-&gt;param(&quot;foo&quot;);</code></pre>
260
261 <h2 id="upload">upload</h2>
262
263 <pre><code>$req-&gt;upload()
264 $req-&gt;upload($key)</code></pre>
265
266 <p>With no arguments, this method returns a tied APR::Request::Param::Table object (or undef if the request body is absent) in scalar context (whose entries are APR::Request::Param objects), or the names (in order, with repetitions) of all the incoming uploads.</p>
267
268 <p>With the <code>$key</code> argument, in scalar context this method fetches the first matching upload. In list context it returns all matching uploads. The return values are APR::Request::Param objects.</p>
269
270 <p>upload() will throw an APR::Request::Error object whenever body_status() is non-zero.</p>
271
272 <pre><code>$uploads = $req-&gt;upload;
273 @upload_names = $req-&gt;upload;
274 ok $uploads-&gt;isa(&quot;APR::Request::Param::Table&quot;);
275 ok shift @upload_names eq $_ for keys %$uploads;
276 ok $_-&gt;upload for values %$uploads;
277
278 $up = $req-&gt;upload(&quot;beta&quot;);
279 @ups = $req-&gt;upload(&quot;beta&quot;);
280 ok $_-&gt;isa(&quot;APR::Request::Param&quot;) for $up, @ups;
281 ok $_-&gt;upload for $up, @ups;</code></pre>
282
283 <h2 id="read_limit">read_limit</h2>
284
285 <pre><code>$req-&gt;read_limit()
286 $req-&gt;read_limit($set)</code></pre>
287
288 <p>Get/set the read limit, which controls the total amount of bytes that can be fed to the current parser.</p>
289
290 <h2 id="brigade_limit">brigade_limit</h2>
291
292 <pre><code>$req-&gt;brigade_limit()
293 $req-&gt;brigade_limit($set)</code></pre>
294
295 <p>Get/set the brigade_limit for the current parser. This limit determines how many bytes of a file upload that the parser may spool into main memory. Uploads exceeding this limit are written directly to disk.</p>
296
297 <h2 id="temp_dir">temp_dir</h2>
298
299 <pre><code>$req-&gt;temp_dir()
300 $req-&gt;temp_dir($set)</code></pre>
301
302 <p>Get/set the spool directory for uploads which exceed the configured brigade_limit.</p>
303
304 <h2 id="disable_uploads">disable_uploads</h2>
305
306 <pre><code>$req-&gt;disable_uploads()</code></pre>
307
308 <p>Engage the disable_uploads hook for this request.</p>
309
310 <h2 id="upload_hook">upload_hook</h2>
311
312 <pre><code>$req-&gt;upload_hook($callback)</code></pre>
313
314 <p>Add an upload hook callback for this request. The arguments to the $callback sub are ($upload, $new_data).</p>
315
316 <h2 id="import">import</h2>
317
318 <p>Exports a list of subs into the caller&#39;s package.</p>
319
320 <h1 id="SUBROUTINES">SUBROUTINES</h1>
321
322 <p>APR::Request</p>
323
324 <h2 id="encode">encode</h2>
325
326 <pre><code>encode($string)</code></pre>
327
328 <p>Exportable sub which returns the url-encoded form of <code>$string</code>.</p>
329
330 <h2 id="decode">decode</h2>
331
332 <pre><code>decode($string)</code></pre>
333
334 <p>Exportable sub which returns the url-decoded form of <code>$string</code>.</p>
335
336 <h1 id="SUBCLASSING">SUBCLASSING</h1>
337
338 <p>APR::Request</p>
339
340 <p>If the instances of your subclass are hash references then you can actually inherit from APR::Request as long as the APR::Request object is stored in an attribute called &quot;r&quot; or &quot;_r&quot;. (The APR::Request class effectively does the delegation for you automagically, as long as it knows where to find the APR::Request object to delegate to.) For example:</p>
341
342 <pre><code>package MySubClass;
343 use APR::Request::Custom;
344 our @ISA = qw(APR::Request);
345 sub new {
346 my($class, @args) = @_;
347 return bless { r =&gt; APR::Request::Custom-&gt;handle(@args) }, $class;
348 }</code></pre>
349
350 <h1 id="METHODS2">METHODS</h1>
351
352 <pre><code>APR::Request::Cookie::Table - read-only version of APR::Table.</code></pre>
353
354 <p>Tables in this class normally arise from calls to <code>APR::Request::jar()</code>.</p>
355
356 <h2 id="cookie_class">cookie_class</h2>
357
358 <pre><code>$table-&gt;cookie_class()
359 $table-&gt;cookie_class($set)</code></pre>
360
361 <p>Get/set the class each table element is blessed into during a <a>get</a> or <a>FETCH</a> call. If defined, the class must be derived from APR::Request::Cookie. When called with $set, it returns the $table. Otherwise it returns the name of the current class, or undef if no cookie class is defined.</p>
362
363 <h2 id="get">get</h2>
364
365 <pre><code>$table-&gt;get($key)</code></pre>
366
367 <p>Same as FETCH.</p>
368
369 <h2 id="FETCH">FETCH</h2>
370
371 <pre><code>$table-&gt;FETCH($key)</code></pre>
372
373 <p>In scalar context, this returns the first value matching $key (note: see NEXTKEY for additional notes). The match is always case-insensitive. In list context, this returns all matching values. Note: the type of the return values depends on the table&#39;s current cookie_class.</p>
374
375 <h2 id="EXISTS">EXISTS</h2>
376
377 <p>Synonym for <code>defined</code>; these tables are not allowed to contain undefined values. Since these are constant tables, they don&#39;t autovivify either.</p>
378
379 <h2 id="FIRSTKEY">FIRSTKEY</h2>
380
381 <pre><code>$table-&gt;FIRSTKEY()</code></pre>
382
383 <p>Returns the first key in the table.</p>
384
385 <h2 id="NEXTKEY">NEXTKEY</h2>
386
387 <pre><code>$table-&gt;NEXTKEY()</code></pre>
388
389 <p>Returns the next key in the table. For perl 5.8+, if the key is multivalued, a subsequent FETCH on this key will return the corresponding value, until either NEXTKEY or FIRSTKEY is invoked again. For perl 5.6, FETCH always returns the first value.</p>
390
391 <h2 id="do">do</h2>
392
393 <pre><code>$table-&gt;do($callback, @keys)</code></pre>
394
395 <p>Same as APR::Table::do; iterates over the table calling $callback-&gt;($key, $value) for each matching @keys. If @keys is empty, this iterates over the entire table.</p>
396
397 <p>Note: The type of $value inserted into the callback depends on the table&#39;s current cookie_class.</p>
398
399 <h1 id="METHODS3">METHODS</h1>
400
401 <p>APR::Request::Param::Table</p>
402
403 <h2 id="param_class">param_class</h2>
404
405 <pre><code>$table-&gt;param_class()
406 $table-&gt;param_class($set)</code></pre>
407
408 <p>Get/set the class each table element is blessed into during a <code>get</code> or <code>FETCH</code> call. If defined, the class must be derived from APR::Request::Param. When called with $set, it returns the $table. Otherwise it returns the name of the current class, or undef if no param class is defined.</p>
409
410 <h2 id="get1">get</h2>
411
412 <pre><code>$table-&gt;get($key)</code></pre>
413
414 <p>Same as FETCH.</p>
415
416 <h2 id="FETCH1">FETCH</h2>
417
418 <pre><code>$table-&gt;FETCH($key)</code></pre>
419
420 <p>In scalar context, this returns the first value matching $key (see NEXTKEY for additional notes on this). The match is always case-insensitive. In list context, this returns all matching values. Note: the type of the return values depends on the table&#39;s current param_class.</p>
421
422 <h2 id="EXISTS1">EXISTS</h2>
423
424 <p>Synonym for <code>defined</code>; these tables are not allowed to contain undefined values. Since these are constant tables, they don&#39;t autovivify either.</p>
425
426 <h2 id="NEXTKEY1">NEXTKEY</h2>
427
428 <pre><code>$table-&gt;NEXTKEY()</code></pre>
429
430 <p>Returns the next key in the table. For perl 5.8+, if the key is multivalued, a subsequent FETCH on this key will return the corresponding value, until either NEXTKEY or FIRSTKEY is invoked again. For perl 5.6, FETCH always returns the first value.</p>
431
432 <h2 id="FIRSTKEY1">FIRSTKEY</h2>
433
434 <pre><code>$table-&gt;FIRSTKEY()</code></pre>
435
436 <p>Returns the first key in the table.</p>
437
438 <h2 id="do1">do</h2>
439
440 <pre><code>$table-&gt;do($callback, @keys)</code></pre>
441
442 <p>Same as APR::Table::do; iterates over the table calling $callback-&gt;($key, $value) for each matching @keys. If @keys is empty, this iterates over the entire table.</p>
443
444 <p>Note: The type of $value inserted into the callback depends on the table&#39;s current value_class.</p>
445
446 <h1 id="SEE-ALSO">SEE ALSO</h1>
447
448 <p><a>APR::Request::Error</a>, <a>APR::Request::Param</a>, <a>APR::Request::Cookie</a>, <a>APR::Request::Parser</a></p>
449
450 <h1 id="COPYRIGHT">COPYRIGHT</h1>
451
452 <pre><code>Licensed to the Apache Software Foundation (ASF) under one or more
453 contributor license agreements. See the NOTICE file distributed with
454 this work for additional information regarding copyright ownership.
455 The ASF licenses this file to You under the Apache License, Version 2.0
456 (the &quot;License&quot;); you may not use this file except in compliance with
457 the License. You may obtain a copy of the License at
458
459 http://www.apache.org/licenses/LICENSE-2.0
460
461 Unless required by applicable law or agreed to in writing, software
462 distributed under the License is distributed on an &quot;AS IS&quot; BASIS,
463 WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
464 See the License for the specific language governing permissions and
465 limitations under the License.</code></pre>
466
467
468 </div><!-- contents -->
469 <div id="footer">
470 <p class="apache">
471 Copyright &copy; 2003-2006 <a href="http://www.apache.org">The Apache Software Foundation</a>.<br/>
472 See <a href="apreq_license.html">LICENSE</a>.</p>
473 <p class="menu">
474 <span style="color:#aaa">page generated by <a href="http://www.doxygen.org/"><code>doxygen</code></a>
475 version 1.9.1 on Thu Aug 18 2022</span>
476 </p>
477 </div>
478 </body>
479 </html>