1Flickr::Upload(3) User Contributed Perl Documentation Flickr::Upload(3)
2
6 Flickr::Upload - Upload images to "flickr.com"
7
9 use Flickr::Upload;
10 my $ua = Flickr::Upload->new(
12 {
13 'key' => '90909354',
14 'secret' => '37465825'
15 });
16 $ua->upload(
17 'photo' => '/tmp/image.jpg',
18 'auth_token' => $auth_token,
19 'tags' => 'me myself eye',
20 'is_public' => 1,
21 'is_friend' => 1,
22 'is_family' => 1
23 ) or die "Failed to upload /tmp/image.jpg";
24
26 Upload an image to flickr.com.
27
29 new
30 Using Flickr Authentication
31 my $ua = Flickr::Upload->new(
32 {
33 'key' => '90909354',
34 'secret' => '37465825'
35 });
36 Using OAuth Authentication
38 my $ua = Flickr::Upload->new(
39 {
40 'consumer_key' => 'your_api_key',
41 'consumer_secret' => 'your_app_secret',
42 });
43 Retrieve saved configuration (possibly including OAuth access token)
45 my $config_file = "$ENV{HOME}/saved-flickr.st";
46 my $ua = Flickr::Upload->import_storable_config($config_file);
47 Instantiates a Flickr::Upload instance, using either the Flickr
49 Authentication or the OAuth Authentication. The "key" or "consumer_key"
50 argument is your API key and the "secret" or "consumer_secret" argument
51 is the API secret associated with it. To get an API key and secret, go
52 to <https://www.flickr.com/services/api/key.gne>.
53 The resulting Flickr::Upload instance is a subclass of Flickr::API and
55 can be used for any other Flickr API calls. As such, Flickr::Upload is
56 also a subclass of LWP::UserAgent.
57 upload
59 my $photoid = $ua->upload(
60 'photo' => '/tmp/image.jpg',
61 'auth_token' => $auth_token,
62 'tags' => 'me myself eye',
63 'is_public' => 1,
64 'is_friend' => 1,
65 'is_family' => 1
66 'async' => 0,
67 );
68 Taking a Flickr::Upload instance $ua as an argument, this is basically
70 a direct interface to the Flickr Photo Upload API. Required parameters
71 are "photo" and, when using Flickr Authentication, "auth_token". Note
72 that the "auth_token" must have been issued against the API key and
73 secret used to instantiate the uploader.
74 When using OAuth, "auth_token" is not required, and the Flickr::Upload
76 instance must instead contain a valid Net::OAuth access token which can
77 be added by calling the Flickr::API "oauth_access_token" method.
78 Returns the resulting identifier of the uploaded photo on success,
80 "undef" on failure. According to the API documentation, after an upload
81 the user should be directed to the page
82 <https://www.flickr.com/tools/uploader_edit.gne?ids=$photoid>.
83 If the "async" option is non-zero, the photo will be uploaded
85 asynchronously and a successful upload returns a ticket identifier. See
86 <https://www.flickr.com/services/api/upload.async.html>. The caller can
87 then periodically poll for a photo id using the "check_upload" method.
88 Note that photo and ticket identifiers aren't necessarily numeric.
89 check_upload
91 my %status2txt = (0 => 'not complete', 1 => 'completed', 2 => 'failed');
92 my @rc = $ua->check_upload( @ticketids );
93 for( @rc ) {
94 print "Ticket $_->{id} has $status2txt{$_->{complete}}\n";
95 print "\tPhoto id is $_->{photoid}\n" if exists $_->{photoid};
96 }
97 This function will check the status of one or more asynchronous
99 uploads. A list of ticket identifiers are provided (@ticketids) and
100 each is checked. This is basically just a wrapper around the Flickr API
101 "flickr.photos.upload.checkTickets" method.
102 On success, a list of hash references is returned. Each hash contains a
104 "id" (the ticket id), "complete" and, if completed, "photoid" members.
105 "invalid" may also be returned. Status codes (for "complete") are as
106 documented at <https://www.flickr.com/services/api/upload.async.html>
107 and, actually, the returned fields are identical to those listed in the
108 "ticket" tag of the response. The returned list isn't guaranteed to be
109 in any particular order.
110 This function polls a web server, so avoid calling it too frequently.
112 make_upload_request
114 my $req = $uploader->make_upload_request(
115 'auth_token' => '82374523',
116 'tags' => 'me myself eye',
117 'is_public' => 1,
118 'is_friend' => 1,
119 'is_family' => 1
120 );
121 $req->header( 'X-Greetz' => 'hi cal' );
122 my $resp = $ua->request( $req );
123 Creates an HTTP::Request object loaded with all the flick upload
125 parameters. This will also sign the request, which means you won't be
126 able to mess any further with the upload request parameters.
127 Takes all the same parameters as upload, except that the photo argument
129 isn't required. This in intended so that the caller can include it by
130 messing directly with the HTTP content (via $DYNAMIC_FILE_UPLOAD or the
131 HTTP::Message class, among other things). See "t/" directory from the
132 source distribution for examples.
133 Returns a standard HTTP::Response POST object. The caller can manually
135 do the upload or just call the upload_request function.
136 upload_request
138 my $photoid = upload_request( $ua, $request );
139 Taking (at least) LWP::UserAgent and HTTP::Request objects as
141 arguments, this executes the request and processes the result as a
142 flickr upload. It's assumed that the request looks a lot like something
143 created with make_upload_request. Note that the request must be signed
144 according to the Flickr API authentication rules.
145 Returns the resulting identifier of the uploaded photo (or ticket for
147 asynchronous uploads) on success, "undef" on failure. According to the
148 API documentation, after an upload the user should be directed to the
149 page <https://www.flickr.com/tools/uploader_edit.gne?ids=$photoid>.
150 file_length_in_encoded_chunk
152 $HTTP::Request::Common::DYNAMIC_FILE_UPLOAD = 1;
153 my $photo = 'image.jpeg';
154 my $photo_size = (stat($photo))[7];
155 my $req = $ua->make_upload_request( ... );
156 my $gen = $req->content();
157 die unless ref($gen) eq "CODE";
158 my $state;
160 my $size;
161 $req->content(
163 sub {
164 my $chunk = &$gen();
165 $size += Flickr::Upload::file_length_in_encoded_chunk(\$chunk, \$state, $photo_size);
167 warn "$size bytes have now been uploaded";
169 return $chunk;
171 }
172 );
173 $rc = $ua->upload_request( $req );
175 This subroutine is tells you how much of a chunk in a series of
177 variable size multipart HTTP chunks contains a single file being
178 uploaded given a reference to the current chunk, a reference to a state
179 variable that lives between calls, and the size of the file being
180 uploaded.
181 It can be used used along with HTTP::Request::Common's
183 $HTTP::Request::Common::DYNAMIC_FILE_UPLOAD facility to implement
184 upload progress bars or other upload monitors, see flickr_upload for a
185 practical example and t/progress_request.t for tests.
186 photosets_create
188 Calls Flickr's "flickr.photosets.create" method,
189 to create a new Set.
190 The set will use the PrimaryPhotoID as the thumbnail photo.
192 returns: UNDEF on failure, PhotosetID on success.
194 my $photoset_id = $ua->photosets_create( title => 'title',
196 description => 'description',
197 primary_photo_id => ID,
198 auth_token => AUTH_TOKEN );
199 $ua->photosets_addphoto ( photoset_id => $photoset_id,
201 photo_id => ID );
202 photosets_addphoto
204 Calls Flickr's "flickr.photosets.addPhoto" method,
205 to add a (existing) photo to an existing set.
206 returns: UNDEF on failure, TRUE on success.
208 my $photoset_id = $ua->photosets_create( title => 'title',
210 description => 'description',
211 primary_photo_id => ID,
212 auth_token => AUTH_TOKEN );
213 $ua->photosets_addphoto ( photoset_id => $photoset_id,
215 photo_id => ID );
216
218 <https://www.flickr.com/services/api/>
219 Flickr::API
221
223 Christophe Beauregard, cpb@cpan.org
224 Ævar Arnfjörð Bjarmason, <avar@cpan.org>
226
228 This module is not an official Flickr.com (or Ludicorp, or Yahoo)
229 service.
230 Copyright (C) 2004-2008 by Christophe Beauregard and 2008-2009 by Ævar
232 Arnfjörð Bjarmason
233 This library is free software; you can redistribute it and/or modify it
235 under the same terms as Perl itself, either Perl version 5.8.3 or, at
236 your option, any later version of Perl 5 you may have available.
237perl v5.36.0 2023-01-20 Flickr::Upload(3)