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

NAME

6       Flickr::Upload - Upload images to "flickr.com"
7

SYNOPSIS

9               use Flickr::Upload;
10
11               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

DESCRIPTION

26       Upload an image to flickr.com.
27

METHODS

29   new
30       Using Flickr Authentication
31                   my $ua = Flickr::Upload->new(
32                           {
33                                   'key' => '90909354',
34                                   'secret' => '37465825'
35                           });
36
37       Using OAuth Authentication
38                   my $ua = Flickr::Upload->new(
39                           {
40                                   'consumer_key' => 'your_api_key',
41                                   'consumer_secret' => 'your_app_secret',
42                           });
43
44       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
48       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
54       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
58   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
69       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
75       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
79       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
84       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
90   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
98       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
103       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
111       This function polls a web server, so avoid calling it too frequently.
112
113   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
124       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
128       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
134       Returns a standard HTTP::Response POST object. The caller can manually
135       do the upload or just call the upload_request function.
136
137   upload_request
138               my $photoid = upload_request( $ua, $request );
139
140       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
146       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
151   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
159               my $state;
160               my $size;
161
162               $req->content(
163                       sub {
164                               my $chunk = &$gen();
165
166                               $size += Flickr::Upload::file_length_in_encoded_chunk(\$chunk, \$state, $photo_size);
167
168                               warn "$size bytes have now been uploaded";
169
170                               return $chunk;
171                       }
172               );
173
174               $rc = $ua->upload_request( $req );
175
176       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
182       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
187   photosets_create
188               Calls Flickr's "flickr.photosets.create" method,
189               to create a new Set.
190
191               The set will use the PrimaryPhotoID as the thumbnail photo.
192
193               returns: UNDEF on failure, PhotosetID on success.
194
195               my $photoset_id = $ua->photosets_create( title => 'title',
196                                              description => 'description',
197                                              primary_photo_id => ID,
198                                              auth_token => AUTH_TOKEN );
199
200               $ua->photosets_addphoto ( photoset_id => $photoset_id,
201                                         photo_id => ID );
202
203   photosets_addphoto
204               Calls Flickr's "flickr.photosets.addPhoto" method,
205               to add a (existing) photo to an existing set.
206
207               returns: UNDEF on failure, TRUE on success.
208
209               my $photoset_id = $ua->photosets_create( title => 'title',
210                                              description => 'description',
211                                              primary_photo_id => ID,
212                                              auth_token => AUTH_TOKEN );
213
214               $ua->photosets_addphoto ( photoset_id => $photoset_id,
215                                         photo_id => ID );
216

SEE ALSO

218       <https://www.flickr.com/services/api/>
219
220       Flickr::API
221

AUTHORS

223       Christophe Beauregard, cpb@cpan.org
224
225       Ævar Arnfjörð Bjarmason, <avar@cpan.org>
226
228       This module is not an official Flickr.com (or Ludicorp, or Yahoo)
229       service.
230
231       Copyright (C) 2004-2008 by Christophe Beauregard and 2008-2009 by Ævar
232       Arnfjörð Bjarmason
233
234       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.
237
238
239
240perl v5.34.0                      2022-01-21                 Flickr::Upload(3)
Impressum