Apache2::Upload(3pm)

1Apache2::Upload(3)    User Contributed Perl Documentation   Apache2::Upload(3)
2
3
4

NAME

6       Apache2::Upload - Methods for dealing with file uploads.
7

SYNOPSIS

9           use Apache2::Upload;
10
11           $req = Apache2::Request->new($r);
12           $upload = $req->upload("foo");
13           $size = $upload->size;
14
15           # three methods to get at the upload's contents ... slurp, fh, io
16
17           $upload->slurp($slurp_data);
18
19           read $upload->fh, $fh_data, $size;
20           ok $slurp_data eq $fh_data;
21
22           my $io = $upload->io;
23           print while <$io>;
24

DESCRIPTION

26       Apache2::Upload is a new module based on the original package included
27       in Apache2::Request 1.X.  Users requiring the upload API must now "use
28       Apache2::Upload", which adds the "upload" method to Apache2::Request.
29       Apache2::Upload is largely backwards-compatible with the original 1.X
30       API.  See the "PORTING from 1.X" section below for a list of known
31       issues.
32
33       This manpage documents the Apache2::Upload package.
34

Apache2::Upload

36       name
37
38           $upload->name()
39
40       The name of the HTML form element which generated the upload.
41
42       filename
43
44           $upload->filename()
45
46       The (client-side) filename as submitted in the HTML form.  Note: some
47       agents will submit the file's full pathname, while others may submit
48       just the basename.
49
50       fh
51
52           $upload->fh()
53
54       Creates filehandle reference to the upload's spooled tempfile, which
55       contains the full contents of the upload.
56
57       io
58
59           $upload->io()
60
61       Creates a tied IO handle.  This method is a more efficient version of
62       "fh", but with "io" the handle ref returned is not seekable.  It is
63       tied to an APR::Request::Brigade object, so you may use the brigade API
64       on the tied object if you want to manipulate the IO stream (beyond sim‐
65       ply reading from it).
66
67       The returned reference is actually an object which has "read" and
68       "readline" methods available.  However these methods are just syntactic
69       sugar for the underlying "READ" and "READLINE" methods from
70       APR::Request::Brigade.
71
72           $io = $upload->io;
73           print while $io->read($_); # equivalent to: tied(*$io)->READ($_)
74
75       See READ and READLINE below for additional notes on their usage.
76
77       bb
78
79           $upload->bb()
80           $upload->bb($set)
81
82       Get/set the APR::Brigade which represents the upload's contents.
83
84       size
85
86           $upload->size()
87
88       Returns the size of the upload in bytes.
89
90       info
91
92           $upload->info()
93           $upload->info($set)
94
95       Get/set the additional header information table for the uploaded file.
96       Returns a hash reference tied to the APR::Table class.  An optional
97       $table argument can be passed to reassign the upload's internal
98       (apr_table_t) info table to the one $table represents.
99
100           my $info = $upload->info;
101           while (my($hdr_name, $hdr_value) = each %$info) {
102               # ...
103           }
104
105           # fetch upload's Content-Type header
106           my $type = $upload->info->{"Content-type"};
107
108       type
109
110           $upload->type()
111
112       Returns the MIME type of the given Apache2::Upload object.
113
114           my $type = $upload->type;
115
116           #same as
117           my $content_type = $upload->info->{"Content-Type"};
118           $content_type =~ s/;.*$//ms;
119
120       link
121
122           $upload->link()
123
124       To avoid recopying the upload's internal tempfile brigade on a
125       *nix-like system, link will create a hard link to it:
126
127         my $upload = $req->upload('foo');
128         $upload->link("/path/to/newfile") or
129             die sprintf "link from '%s' failed: $!", $upload->tempname;
130
131       Typically the new name must lie on the same device and partition as the
132       brigade's tempfile.  If this or any other reason prevents the OS from
133       linking the files, "link()" will instead copy the temporary file to the
134       specified location.
135
136       slurp
137
138           $upload->slurp($contents)
139
140       Reads the full contents of a file upload into the scalar argument.  The
141       return value is the length of the file.
142
143           my $size = $upload->slurp($contents);
144
145       tempname
146
147           $upload->tempname()
148
149       Provides the name of the spool file.
150
151           my $tempname = $upload->tempname;
152

APR::Request::Brigade

154       This class is derived from APR::Brigade, providing additional methods
155       for TIEHANDLE, READ and READLINE.  To be memory efficient, these meth‐
156       ods delete buckets from the brigade as soon as their data is actually
157       read, so you cannot "seek" on handles tied to this class.  Such handles
158       have semantics similar to that of a read-only socket.
159
160       TIEHANDLE
161
162           APR::Request::Brigade->TIEHANDLE($bb)
163
164       Creates a copy of the bucket brigade represented by $bb, and blesses
165       that copy into the APR::Request::Brigade class.  This provides syntac‐
166       tic sugar for using perl's builtin "read", "readline", and "<>" opera‐
167       tions on handles tied to this package:
168
169           use Symbol;
170           $fh = gensym;
171           tie *$fh, "APR::Request:Brigade", $bb;
172           print while <$fh>;
173
174       READ
175
176           $bb->READ($contents)
177           $bb->READ($contents, $length)
178           $bb->READ($contents, $length, $offset)
179
180       Reads data from the brigade $bb into $contents.  When omitted $length
181       defaults to "-1", which reads the first bucket into $contents.  A posi‐
182       tive $length will read in $length bytes, or the remainder of the
183       brigade, whichever is greater. $offset represents the index in $context
184       to read the new data.
185
186       READLINE
187
188           $bb->READLINE()
189
190       Returns the first line of data from the bride. Lines are terminated by
191       linefeeds (the '\012' character), but we may eventually use $/ instead.
192

PORTING from 1.X

194       * "$upload->next()" is no longer available;  please use the
195       "APR::Request::Param::Table" API when iterating over upload entries.
196       * "info($header_name)" is replaced by "info($set)".
197       * "type()" returns only the MIME-type portion of the Content-Type
198       header.
199

COPYRIGHT

205         Licensed to the Apache Software Foundation (ASF) under one or more
206         contributor license agreements.  See the NOTICE file distributed with
207         this work for additional information regarding copyright ownership.
208         The ASF licenses this file to You under the Apache License, Version 2.0
209         (the "License"); you may not use this file except in compliance with
210         the License.  You may obtain a copy of the License at
211
212             http://www.apache.org/licenses/LICENSE-2.0
213
214         Unless required by applicable law or agreed to in writing, software
215         distributed under the License is distributed on an "AS IS" BASIS,
216         WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
217         See the License for the specific language governing permissions and
218         limitations under the License.
219
220
221
222perl v5.8.8                       2006-11-09                Apache2::Upload(3)