Debian Codegraph @

docs/html/group__apreq__xs__request.html

raw ◀ ▶
1 Debian patch touch this file
1 <html>
2 <head>
3 <link rel="stylesheet" type="text/css" href="dox.css" />
4 <title>libapreq2-2.17: Apache2::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">Apache2::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="#Apache2::Request">Apache2::Request</a>
38 <ul>
39 <li><a href="#new">new</a></li>
40 <li><a href="#instance">instance</a></li>
41 <li><a href="#param">param</a></li>
42 <li><a href="#parms-params">parms, params</a></li>
43 <li><a href="#body">body</a></li>
44 <li><a href="#upload">upload</a></li>
45 <li><a href="#args_status">args_status</a></li>
46 <li><a href="#body_status">body_status</a></li>
47 <li><a href="#param_status">param_status</a></li>
48 <li><a href="#parse">parse</a></li>
49 </ul>
50 </li>
51 <li><a href="#SUBCLASSING-Apache2::Request">SUBCLASSING Apache2::Request</a></li>
52 <li><a href="#PORTING-from-1.X">PORTING from 1.X</a></li>
53 <li><a href="#SEE-ALSO">SEE ALSO</a></li>
54 <li><a href="#COPYRIGHT">COPYRIGHT</a></li>
55 </ul>
56
57 <h1 id="NAME">NAME</h1>
58
59 <p>Apache2::Request - Methods for dealing with client request data</p>
60
61 <h1 id="SYNOPSIS">SYNOPSIS</h1>
62
63 <pre><code>use Apache2::Request;
64 $req = Apache2::Request-&gt;new($r);
65 @foo = $req-&gt;param(&quot;foo&quot;);
66 $bar = $req-&gt;args(&quot;bar&quot;);</code></pre>
67
68 <h1 id="DESCRIPTION">DESCRIPTION</h1>
69
70 <p>The Apache2::Request module provides methods for parsing GET and POST parameters encoded with either <i>application/x-www-form-urlencoded</i> or <i>multipart/form-data</i>. Although Apache2::Request provides a few new APIs for accessing the parsed data, it remains largely backwards-compatible with the original 1.X API. See the <a href="#PORTING-from-1.X">&quot;PORTING from 1.X&quot;</a> section below for a list of known issues.</p>
71
72 <p>This manpage documents the Apache2::Request package.</p>
73
74 <h1 id="Apache2::Request">Apache2::Request</h1>
75
76 <p>The interface is designed to mimic the CGI.pm routines for parsing query parameters. The main differences are</p>
77
78 <ul>
79
80 <li><p><code>Apache2::Request::new</code> takes an environment-specific object <code>$r</code> as (second) argument. Newer versions of CGI.pm also accept this syntax within modperl.</p>
81
82 </li>
83 <li><p>The query parameters are stored in APR::Table derived objects, and are therefore retrieved from the table by using case-insensitive keys.</p>
84
85 </li>
86 <li><p>The query string is always parsed immediately, even for POST requests.</p>
87
88 </li>
89 </ul>
90
91 <h2 id="new">new</h2>
92
93 <pre><code>Apache2::Request-&gt;new($r, %args)</code></pre>
94
95 <p>Creates a new Apache2::Request object.</p>
96
97 <pre><code>my $req = Apache2::Request-&gt;new($r, POST_MAX =&gt; &quot;1M&quot;);</code></pre>
98
99 <p>With mod_perl2, the environment object $r must be an Apache2::RequestRec object. In that case, all methods from Apache2::RequestRec are inherited. In the (default) CGI environment, $r must be an APR::Pool object.</p>
100
101 <p>The following args are optional:</p>
102
103 <ul>
104
105 <li><p><code>POST_MAX</code>, <code>MAX_BODY</code></p>
106
107 <p>Limit the size of POST data (in bytes).</p>
108
109 </li>
110 <li><p><code>DISABLE_UPLOADS</code></p>
111
112 <p>Disable file uploads.</p>
113
114 </li>
115 <li><p><code>TEMP_DIR</code></p>
116
117 <p>Sets the directory where upload files are spooled. On a *nix-like that supports <i>link(2)</i>, the TEMP_DIR should be located on the same file system as the final destination file:</p>
118
119 <pre><code>use Apache2::Upload;
120 my $req = Apache2::Request-&gt;new($r, TEMP_DIR =&gt; &quot;/home/httpd/tmp&quot;);
121 my $upload = $req-&gt;upload(&#39;file&#39;);
122 $upload-&gt;link(&quot;/home/user/myfile&quot;);</code></pre>
123
124 <p>For more details on <code>link</code>, see <a>Apache2::Upload</a>.</p>
125
126 </li>
127 <li><p><code>HOOK_DATA</code></p>
128
129 <p>Extra configuration info passed as the fourth argument to an upload hook. See the description for the next item, <code>UPLOAD_HOOK</code>.</p>
130
131 </li>
132 <li><p><code>UPLOAD_HOOK</code></p>
133
134 <p>Sets up a callback to run whenever file upload data is read. This can be used to provide an upload progress meter during file uploads. Apache will automatically continue writing the original data to $upload-&gt;fh after the hook exits.</p>
135
136 <pre><code>my $transparent_hook = sub {
137 my ($upload, $data, $data_len, $hook_data) = @_;
138 warn &quot;$hook_data: got $data_len bytes for &quot; . $upload-&gt;name;
139 };
140
141 my $req = Apache2::Request-&gt;new($r,
142 HOOK_DATA =&gt; &quot;Note&quot;,
143 UPLOAD_HOOK =&gt; $transparent_hook,
144 );</code></pre>
145
146 </li>
147 </ul>
148
149 <h2 id="instance">instance</h2>
150
151 <pre><code>Apache2::Request-&gt;instance($r)</code></pre>
152
153 <p>The default (and only) behavior of <i>Apache2::Request</i> is to intelligently cache <b>POST</b> data for the duration of the request. Thus there is no longer the need for a separate <code>instance()</code> method as existed in <i>Apache2::Request</i> for Apache 1.3 - all <b>POST</b> data is always available from each and every <i>Apache2::Request</i> object created during the request&#39;s lifetime.</p>
154
155 <p>However an <code>instance()</code> method is aliased to <code>new()</code> in this release to ease the pain of porting from 1.X to 2.X.</p>
156
157 <h2 id="param">param</h2>
158
159 <pre><code>$req-&gt;param()
160 $req-&gt;param($name)</code></pre>
161
•162 <p>Get the request parameters (using case-insensitive keys) by mimicking the OO interface of <code>CGI::param</code>.</p>
163
164 <pre><code># similar to CGI.pm
165
166 my $foo_value = $req-&gt;param(&#39;foo&#39;);
167 my @foo_values = $req-&gt;param(&#39;foo&#39;);
168 my @param_names = $req-&gt;param;
169
170 # the following differ slightly from CGI.pm
171
172 # returns ref to APR::Request::Param::Table object representing
173 # all (args + body) params
174 my $table = $req-&gt;param;
175 @table_keys = keys %$table;</code></pre>
176
177 <p>In list context, or when invoked with no arguments as <code>$req-&gt;param()</code>, <code>param</code> induces libapreq2 to read and parse all remaining data in the request body. However, <code>scalar $req-&gt;param(&quot;foo&quot;)</code> is lazy: libapreq2 will only read and parse more data if</p>
178
179 <pre><code>1) no &quot;foo&quot; param appears in the query string arguments, AND
180 2) no &quot;foo&quot; param appears in the previously parsed POST data.</code></pre>
181
182 <p>In this circumstance libapreq2 will read and parse additional blocks of the incoming request body until either</p>
183
184 <pre><code>1) it has found the the &quot;foo&quot; param, or
185 2) parsing is completed.</code></pre>
186
187 <p>Observe that <code>scalar $req-&gt;param(&quot;foo&quot;)</code> will not raise an exception if it can locate &quot;foo&quot; in the existing body or args tables, even if the query-string parser or the body parser has failed. In all other circumstances <code>param</code> will throw an Apache2::Request::Error object into $@ should either parser fail.</p>
188
189 <pre><code>$req-&gt;args_status(1); # set error state for query-string parser
190 ok $req-&gt;param_status == 1;
191
192 $foo = $req-&gt;param(&quot;foo&quot;);
193 ok $foo == 1;
194 eval { @foo = $req-&gt;param(&quot;foo&quot;) };
195 ok $@-&gt;isa(&quot;Apache2::Request::Error&quot;);
196 undef $@;
197 eval { my $not_found = $req-&gt;param(&quot;non-existent-param&quot;) };
198 ok $@-&gt;isa(&quot;Apache2::Request::Error&quot;);
199
200 $req-&gt;args_status(0); # reset query-string parser state to &quot;success&quot;</code></pre>
201
202 <p>Note: modifications to the <code>scalar $req-&gt;param()</code> table only affect the returned table object (the underlying C apr_table_t is <i>generated</i> from the parse data by apreq_params()). Modifications do not affect the actual request data, and will not be seen by other libapreq2 applications.</p>
203
204 <h2 id="parms-params">parms, params</h2>
205
206 <p>The functionality of these functions is assumed by <code>param</code>, so they are no longer necessary. Aliases to <code>param</code> are provided in this release for backwards compatibility, however they are deprecated and may be removed from a future release.</p>
207
208 <h2 id="body">body</h2>
209
210 <pre><code>$req-&gt;body()
211 $req-&gt;body($name)</code></pre>
212
213 <p>Returns an <i>APR::Request::Param::Table</i> object containing the POST data parameters of the <i>Apache2::Request</i> object.</p>
214
215 <pre><code>my $body = $req-&gt;body;</code></pre>
216
217 <p>An optional name parameter can be passed to return the POST data parameter associated with the given name:</p>
218
219 <pre><code>my $foo_body = $req-&gt;body(&quot;foo&quot;);</code></pre>
220
221 <p>More generally, <code>body()</code> follows the same pattern as <code>param()</code> with respect to its return values and argument list. The main difference is that modifications to the <code>scalar $req-&gt;body()</code> table affect the underlying apr_table_t attribute in apreq_request_t, so their impact will be noticed by all libapreq2 applications during this request.</p>
222
223 <h2 id="upload">upload</h2>
224
225 <pre><code>$req-&gt;upload()
226 $req-&gt;upload($name)</code></pre>
227
228 <p>Requires <code>Apache2::Upload</code>. With no arguments, this method returns an <i>APR::Request::Param::Table</i> object in scalar context, or the names of all <i>Apache2::Upload</i> objects in list context.</p>
229
230 <p>An optional name parameter can be passed to return the <i>Apache2::Upload</i> object associated with the given name:</p>
231
232 <pre><code>my $upload = $req-&gt;upload($name);</code></pre>
233
234 <p>More generally, <code>upload()</code> follows the same pattern as <code>param()</code> with respect to its return values and argument list. The main difference is that its returned values are Apache2::Upload object refs, not simple scalars.</p>
235
236 <p>Note: modifications to the <code>scalar $req-&gt;upload()</code> table only affect the returned table object (the underlying C apr_table_t is <i>generated</i> by apreq_uploads()). They do not affect the actual request data, and will not be seen by other libapreq2 applications.</p>
237
238 <h2 id="args_status">args_status</h2>
239
240 <pre><code>$req-&gt;args_status()</code></pre>
241
242 <p>Get the <i>APR</i> status code of the query-string parser. APR_SUCCESS on success, error otherwise.</p>
243
244 <h2 id="body_status">body_status</h2>
245
246 <pre><code>$req-&gt;body_status()</code></pre>
247
248 <p>Get the current <i>APR</i> status code of the parsed POST data. APR_SUCCESS when parser has completed, APR_INCOMPLETE if parser has more data to parse, APR_EINIT if no post data has been parsed, error otherwise.</p>
249
250 <h2 id="param_status">param_status</h2>
251
252 <pre><code>$req-&gt;param_status()</code></pre>
253
254 <p>In scalar context, this returns <code>args_status</code> if there was an error during the query-string parse, otherwise this returns <code>body_status</code>, ie</p>
255
256 <pre><code>$req-&gt;args_status || $req-&gt;body_status</code></pre>
257
258 <p>In list context <code>param_status</code> returns the list <code>(args_status, body_status)</code>.</p>
259
260 <h2 id="parse">parse</h2>
261
262 <pre><code>$req-&gt;parse()</code></pre>
263
264 <p>Forces the request to be parsed immediately. In void context, this will throw an APR::Request::Error should the either the query-string or body parser fail. In all other contexts it will return the two parsers&#39; combined <i>APR</i> status code</p>
265
266 <pre><code>$req-&gt;body_status || $req-&gt;args_status</code></pre>
267
268 <p>However <code>parse</code> should be avoided in most normal situations. For example, in a mod_perl content handler it is more efficient to write</p>
269
270 <pre><code>sub handler {
271 my $r = shift;
272 my $req = Apache2::Request-&gt;new($r);
273 $r-&gt;discard_request_body; # efficiently parses the request body
274 my $parser_status = $req-&gt;body_status;
275
276 #...
277 }</code></pre>
278
279 <p>Calling <code>$r-&gt;discard_request_body</code> outside the content handler is generally a mistake, so use <code>$req-&gt;parse</code> there, but <b>only as a last resort</b>. The Apache2::Request API is <b>designed</b> around a lazy-parsing scheme, so calling <code>parse</code> should not affect the behavior of any other methods.</p>
280
281 <h1 id="SUBCLASSING-Apache2::Request">SUBCLASSING Apache2::Request</h1>
282
283 <p>If the instances of your subclass are hash references then you can actually inherit from Apache2::Request as long as the Apache2::Request object is stored in an attribute called &quot;r&quot; or &quot;_r&quot;. (The Apache2::Request class effectively does the delegation for you automagically, as long as it knows where to find the Apache2::Request object to delegate to.) For example:</p>
284
285 <pre><code>package MySubClass;
286 use Apache2::Request;
287 our @ISA = qw(Apache2::Request);
288 sub new {
289 my($class, @args) = @_;
290 return bless { r =&gt; Apache2::Request-&gt;new(@args) }, $class;
291 }</code></pre>
292
293 <h1 id="PORTING-from-1.X">PORTING from 1.X</h1>
294
295 <p>This is the complete list of changes to existing methods from Apache2::Request 1.X. These issues need to be addressed when porting 1.X apps to the new 2.X API.</p>
296
297 <ul>
298
299 <li><p>Apache2::Upload is now a separate module. Applications requiring the upload API must <code>use Apache2::Upload</code> in 2.X. This is easily addressed by preloading the modules during server startup.</p>
300
301 </li>
302 <li><p>You can no longer add (or set or delete) parameters in the <code>scalar $req-&gt;param</code>, <code>scalar $req-&gt;args</code> or <code>scalar $req-&gt;body</code> tables. Nor can you add (or set or delete) cookies in the <code>scalar $req-&gt;jar</code> table.</p>
303
304 </li>
305 <li><p><code>instance()</code> is now identical to <code>new()</code>, and is now deprecated. It may be removed from a future 2.X release.</p>
306
307 </li>
308 <li><p><code>param</code> includes the functionality of <code>parms()</code> and <code>params()</code>, so they are now deprecated and may be removed from a future 2.X release.</p>
309
310 </li>
•311 <li><p><code>param</code> called in a list context no longer returns a unique list of parameters. The returned list contains multiple instances of the parameter name for multivalued fields.</p>
312
313 </li>
314 </ul>
315
316 <h1 id="SEE-ALSO">SEE ALSO</h1>
317
318 <p><a>APR::Request::Param</a>, <a>APR::Request::Error</a>, <a>Apache2::Upload</a>, <a>Apache2::Cookie</a>, APR::Table(3).</p>
319
320 <h1 id="COPYRIGHT">COPYRIGHT</h1>
321
322 <pre><code>Licensed to the Apache Software Foundation (ASF) under one or more
323 contributor license agreements. See the NOTICE file distributed with
324 this work for additional information regarding copyright ownership.
325 The ASF licenses this file to You under the Apache License, Version 2.0
326 (the &quot;License&quot;); you may not use this file except in compliance with
327 the License. You may obtain a copy of the License at
328
329 http://www.apache.org/licenses/LICENSE-2.0
330
331 Unless required by applicable law or agreed to in writing, software
332 distributed under the License is distributed on an &quot;AS IS&quot; BASIS,
333 WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
334 See the License for the specific language governing permissions and
335 limitations under the License.</code></pre>
336
337
338 </div><!-- contents -->
339 <div id="footer">
340 <p class="apache">
341 Copyright &copy; 2003-2006 <a href="http://www.apache.org">The Apache Software Foundation</a>.<br/>
342 See <a href="apreq_license.html">LICENSE</a>.</p>
343 <p class="menu">
344 <span style="color:#aaa">page generated by <a href="http://www.doxygen.org/"><code>doxygen</code></a>
345 version 1.9.1 on Thu Aug 18 2022</span>
346 </p>
347 </div>
348 </body>
349 </html>