| 1 |
<html> |
| 2 |
<head> |
| 3 |
<link rel="stylesheet" type="text/css" href="dox.css" /> |
| 4 |
<title>libapreq2-2.17: Apache2::Upload</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> > <a href="http://httpd.apache.org">HTTP Server Project</a> > |
| 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&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::Upload<div class="ingroups"><a class="el" href="group__apreq__lang.html">Language Bindings</a> » <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::Upload">Apache2::Upload</a> |
| 38 |
<ul> |
| 39 |
<li><a href="#name">name</a></li> |
| 40 |
<li><a href="#filename">filename</a></li> |
| 41 |
<li><a href="#fh">fh</a></li> |
| 42 |
<li><a href="#io">io</a></li> |
| 43 |
<li><a href="#bb">bb</a></li> |
| 44 |
<li><a href="#size">size</a></li> |
| 45 |
<li><a href="#info">info</a></li> |
| 46 |
<li><a href="#type">type</a></li> |
| 47 |
<li><a href="#link">link</a></li> |
| 48 |
<li><a href="#slurp">slurp</a></li> |
| 49 |
<li><a href="#tempname">tempname</a></li> |
| 50 |
</ul> |
| 51 |
</li> |
| 52 |
<li><a href="#APR::Request::Brigade">APR::Request::Brigade</a> |
| 53 |
<ul> |
| 54 |
<li><a href="#TIEHANDLE">TIEHANDLE</a></li> |
| 55 |
<li><a href="#READ">READ</a></li> |
| 56 |
<li><a href="#READLINE">READLINE</a></li> |
| 57 |
</ul> |
| 58 |
</li> |
| 59 |
<li><a href="#PORTING-from-1.X">PORTING from 1.X</a></li> |
| 60 |
<li><a href="#SEE-ALSO">SEE ALSO</a></li> |
| 61 |
<li><a href="#COPYRIGHT">COPYRIGHT</a></li> |
| 62 |
</ul> |
| 63 |
|
| 64 |
<h1 id="NAME">NAME</h1> |
| 65 |
|
| 66 |
<p>Apache2::Upload - Methods for dealing with file uploads.</p> |
| 67 |
|
| 68 |
<h1 id="SYNOPSIS">SYNOPSIS</h1> |
| 69 |
|
| 70 |
<pre><code>use Apache2::Upload; |
| 71 |
|
| 72 |
$req = Apache2::Request->new($r); |
| 73 |
$upload = $req->upload("foo"); |
| 74 |
$size = $upload->size; |
| 75 |
|
| 76 |
# three methods to get at the upload's contents ... slurp, fh, io |
| 77 |
|
| 78 |
$upload->slurp($slurp_data); |
| 79 |
|
| 80 |
read $upload->fh, $fh_data, $size; |
| 81 |
ok $slurp_data eq $fh_data; |
| 82 |
|
| 83 |
my $io = $upload->io; |
| 84 |
print while <$io>;</code></pre> |
| 85 |
|
| 86 |
<h1 id="DESCRIPTION">DESCRIPTION</h1> |
| 87 |
|
| 88 |
<p>Apache2::Upload is a new module based on the original package included in Apache2::Request 1.X. Users requiring the upload API must now <code>use Apache2::Upload</code>, which adds the <code>upload</code> method to Apache2::Request. Apache2::Upload is largely backwards-compatible with the original 1.X API. See the <a href="#PORTING-from-1.X">"PORTING from 1.X"</a> section below for a list of known issues.</p> |
| 89 |
|
| 90 |
<p>This manpage documents the Apache2::Upload package.</p> |
| 91 |
|
| 92 |
<h1 id="Apache2::Upload">Apache2::Upload</h1> |
| 93 |
|
| 94 |
<h2 id="name">name</h2> |
| 95 |
|
| 96 |
<pre><code>$upload->name()</code></pre> |
| 97 |
|
| 98 |
<p>The name of the HTML form element which generated the upload.</p> |
| 99 |
|
| 100 |
<h2 id="filename">filename</h2> |
| 101 |
|
| 102 |
<pre><code>$upload->filename()</code></pre> |
| 103 |
|
| 104 |
<p>The (client-side) filename as submitted in the HTML form. Note: some agents will submit the file's full pathname, while others may submit just the basename.</p> |
| 105 |
|
| 106 |
<h2 id="fh">fh</h2> |
| 107 |
|
| 108 |
<pre><code>$upload->fh()</code></pre> |
| 109 |
|
| 110 |
<p>Creates filehandle reference to the upload's spooled tempfile, which contains the full contents of the upload.</p> |
| 111 |
|
| 112 |
<h2 id="io">io</h2> |
| 113 |
|
| 114 |
<pre><code>$upload->io()</code></pre> |
| 115 |
|
| 116 |
<p>Creates a tied IO handle. This method is a more efficient version of <code>fh</code>, but with <code>io</code> the handle ref returned is not seekable. It is tied to an APR::Request::Brigade object, so you may use the brigade API on the tied object if you want to manipulate the IO stream (beyond simply reading from it).</p> |
| 117 |
|
| 118 |
<p>The returned reference is actually an object which has <code>read</code> and <code>readline</code> methods available. However these methods are just syntactic sugar for the underlying <code>READ</code> and <code>READLINE</code> methods from APR::Request::Brigade.</p> |
| 119 |
|
| 120 |
<pre><code>$io = $upload->io; |
| 121 |
print while $io->read($_); # equivalent to: tied(*$io)->READ($_)</code></pre> |
| 122 |
|
| 123 |
<p>See <a>READ</a> and <a>READLINE</a> below for additional notes on their usage.</p> |
| 124 |
|
| 125 |
<h2 id="bb">bb</h2> |
| 126 |
|
| 127 |
<pre><code>$upload->bb() |
| 128 |
$upload->bb($set)</code></pre> |
| 129 |
|
| 130 |
<p>Get/set the APR::Brigade which represents the upload's contents.</p> |
| 131 |
|
| 132 |
<h2 id="size">size</h2> |
| 133 |
|
| 134 |
<pre><code>$upload->size()</code></pre> |
| 135 |
|
| 136 |
<p>Returns the size of the upload in bytes.</p> |
| 137 |
|
| 138 |
<h2 id="info">info</h2> |
| 139 |
|
| 140 |
<pre><code>$upload->info() |
| 141 |
$upload->info($set)</code></pre> |
| 142 |
|
| 143 |
<p>Get/set the additional header information table for the uploaded file. Returns a hash reference tied to the <i>APR::Table</i> class. An optional <code>$table</code> argument can be passed to reassign the upload's internal (apr_table_t) info table to the one <code>$table</code> represents.</p> |
| 144 |
|
| 145 |
<pre><code>my $info = $upload->info; |
| 146 |
while (my($hdr_name, $hdr_value) = each %$info) { |
| 147 |
# ... |
| 148 |
} |
| 149 |
|
| 150 |
# fetch upload's Content-Type header |
| 151 |
my $type = $upload->info->{"Content-type"};</code></pre> |
| 152 |
|
| 153 |
<h2 id="type">type</h2> |
| 154 |
|
| 155 |
<pre><code>$upload->type()</code></pre> |
| 156 |
|
| 157 |
<p>Returns the MIME type of the given <i>Apache2::Upload</i> object.</p> |
| 158 |
|
| 159 |
<pre><code>my $type = $upload->type; |
| 160 |
|
| 161 |
#same as |
| 162 |
my $content_type = $upload->info->{"Content-Type"}; |
| 163 |
$content_type =~ s/;.*$//ms;</code></pre> |
| 164 |
|
| 165 |
<h2 id="link">link</h2> |
| 166 |
|
| 167 |
<pre><code>$upload->link()</code></pre> |
| 168 |
|
| 169 |
<p>To avoid recopying the upload's internal tempfile brigade on a *nix-like system, <i>link</i> will create a hard link to it:</p> |
| 170 |
|
| 171 |
<pre><code>my $upload = $req->upload('foo'); |
| 172 |
$upload->link("/path/to/newfile") or |
| 173 |
die sprintf "link from '%s' failed: $!", $upload->tempname;</code></pre> |
| 174 |
|
| 175 |
<p>Typically the new name must lie on the same device and partition as the brigade's tempfile. If this or any other reason prevents the OS from linking the files, <code>link()</code> will instead copy the temporary file to the specified location.</p> |
| 176 |
|
| 177 |
<h2 id="slurp">slurp</h2> |
| 178 |
|
| 179 |
<pre><code>$upload->slurp($contents)</code></pre> |
| 180 |
|
| 181 |
<p>Reads the full contents of a file upload into the scalar argument. The return value is the length of the file.</p> |
| 182 |
|
| 183 |
<pre><code>my $size = $upload->slurp($contents);</code></pre> |
| 184 |
|
| 185 |
<h2 id="tempname">tempname</h2> |
| 186 |
|
| 187 |
<pre><code>$upload->tempname()</code></pre> |
| 188 |
|
| 189 |
<p>Provides the name of the spool file.</p> |
| 190 |
|
| 191 |
<pre><code>my $tempname = $upload->tempname;</code></pre> |
| 192 |
|
| 193 |
<h1 id="APR::Request::Brigade">APR::Request::Brigade</h1> |
| 194 |
|
| 195 |
<p>This class is derived from APR::Brigade, providing additional methods for TIEHANDLE, READ and READLINE. To be memory efficient, these methods delete buckets from the brigade as soon as their data is actually read, so you cannot <code>seek</code> on handles tied to this class. Such handles have semantics similar to that of a read-only socket.</p> |
| 196 |
|
| 197 |
<h2 id="TIEHANDLE">TIEHANDLE</h2> |
| 198 |
|
| 199 |
<pre><code>APR::Request::Brigade->TIEHANDLE($bb)</code></pre> |
| 200 |
|
| 201 |
<p>Creates a copy of the bucket brigade represented by $bb, and blesses that copy into the APR::Request::Brigade class. This provides syntactic sugar for using perl's builtin <code>read</code>, <code>readline</code>, and <code><></code> operations on handles tied to this package:</p> |
| 202 |
|
| 203 |
<pre><code>use Symbol; |
| 204 |
$fh = gensym; |
| 205 |
tie *$fh, "APR::Request:Brigade", $bb; |
| 206 |
print while <$fh>;</code></pre> |
| 207 |
|
| 208 |
<h2 id="READ">READ</h2> |
| 209 |
|
| 210 |
<pre><code>$bb->READ($contents) |
| 211 |
$bb->READ($contents, $length) |
| 212 |
$bb->READ($contents, $length, $offset)</code></pre> |
| 213 |
|
| 214 |
<p>Reads data from the brigade $bb into $contents. When omitted $length defaults to <code>-1</code>, which reads the first bucket into $contents. A positive $length will read in $length bytes, or the remainder of the brigade, whichever is greater. $offset represents the index in $context to read the new data.</p> |
| 215 |
|
| 216 |
<h2 id="READLINE">READLINE</h2> |
| 217 |
|
| 218 |
<pre><code>$bb->READLINE()</code></pre> |
| 219 |
|
| 220 |
<p>Returns the first line of data from the bride. Lines are terminated by linefeeds (the '\012' character), but we may eventually use <code>$/</code> instead.</p> |
| 221 |
|
| 222 |
<h1 id="PORTING-from-1.X">PORTING from 1.X</h1> |
| 223 |
|
| 224 |
<ul> |
| 225 |
|
| 226 |
<li><p><code>$upload->next()</code> is no longer available; please use the <code>APR::Request::Param::Table</code> API when iterating over upload entries.</p> |
| 227 |
|
| 228 |
</li> |
| 229 |
<li><p><code>info($header_name)</code> is replaced by <code>info($set)</code>.</p> |
| 230 |
|
| 231 |
</li> |
| 232 |
<li><p><code>type()</code> returns only the MIME-type portion of the Content-Type header.</p> |
| 233 |
|
| 234 |
</li> |
| 235 |
</ul> |
| 236 |
|
| 237 |
<h1 id="SEE-ALSO">SEE ALSO</h1> |
| 238 |
|
| 239 |
<p><a>APR::Request::Param::Table</a>, <a>APR::Request::Error</a>, <a>Apache2::Request</a>, APR::Table(3)</p> |
| 240 |
|
| 241 |
<h1 id="COPYRIGHT">COPYRIGHT</h1> |
| 242 |
|
| 243 |
<pre><code>Licensed to the Apache Software Foundation (ASF) under one or more |
| 244 |
contributor license agreements. See the NOTICE file distributed with |
| 245 |
this work for additional information regarding copyright ownership. |
| 246 |
The ASF licenses this file to You under the Apache License, Version 2.0 |
| 247 |
(the "License"); you may not use this file except in compliance with |
| 248 |
the License. You may obtain a copy of the License at |
| 249 |
|
| 250 |
http://www.apache.org/licenses/LICENSE-2.0 |
| 251 |
|
| 252 |
Unless required by applicable law or agreed to in writing, software |
| 253 |
distributed under the License is distributed on an "AS IS" BASIS, |
| 254 |
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. |
| 255 |
See the License for the specific language governing permissions and |
| 256 |
limitations under the License.</code></pre> |
| 257 |
|
| 258 |
|
| 259 |
</div><!-- contents --> |
| 260 |
<div id="footer"> |
| 261 |
<p class="apache"> |
| 262 |
Copyright © 2003-2006 <a href="http://www.apache.org">The Apache Software Foundation</a>.<br/> |
| 263 |
See <a href="apreq_license.html">LICENSE</a>.</p> |
| 264 |
<p class="menu"> |
| 265 |
<span style="color:#aaa">page generated by <a href="http://www.doxygen.org/"><code>doxygen</code></a> |
| 266 |
version 1.9.1 on Thu Aug 18 2022</span> |
| 267 |
</p> |
| 268 |
</div> |
| 269 |
</body> |
| 270 |
</html> |