Provided by: libflickr-upload-perl_1.60-2_all 
NAME
Flickr::Upload - Upload images to "flickr.com"
SYNOPSIS
use Flickr::Upload;
my $ua = Flickr::Upload->new(
{
'key' => '90909354',
'secret' => '37465825'
});
$ua->upload(
'photo' => '/tmp/image.jpg',
'auth_token' => $auth_token,
'tags' => 'me myself eye',
'is_public' => 1,
'is_friend' => 1,
'is_family' => 1
) or die "Failed to upload /tmp/image.jpg";
DESCRIPTION
Upload an image to flickr.com.
METHODS
new
Using Flickr Authentication
my $ua = Flickr::Upload->new(
{
'key' => '90909354',
'secret' => '37465825'
});
Using OAuth Authentication
my $ua = Flickr::Upload->new(
{
'consumer_key' => 'your_api_key',
'consumer_secret' => 'your_app_secret',
});
Retrieve saved configuration (possibly including OAuth access token)
my $config_file = "$ENV{HOME}/saved-flickr.st";
my $ua = Flickr::Upload->import_storable_config($config_file);
Instantiates a Flickr::Upload instance, using either the Flickr Authentication or the
OAuth Authentication. The "key" or "consumer_key" argument is your API key and the
"secret" or "consumer_secret" argument is the API secret associated with it. To get an API
key and secret, go to <https://www.flickr.com/services/api/key.gne>.
The resulting Flickr::Upload instance is a subclass of Flickr::API and can be used for any
other Flickr API calls. As such, Flickr::Upload is also a subclass of LWP::UserAgent.
upload
my $photoid = $ua->upload(
'photo' => '/tmp/image.jpg',
'auth_token' => $auth_token,
'tags' => 'me myself eye',
'is_public' => 1,
'is_friend' => 1,
'is_family' => 1
'async' => 0,
);
Taking a Flickr::Upload instance $ua as an argument, this is basically a direct interface
to the Flickr Photo Upload API. Required parameters are "photo" and, when using Flickr
Authentication, "auth_token". Note that the "auth_token" must have been issued against
the API key and secret used to instantiate the uploader.
When using OAuth, "auth_token" is not required, and the Flickr::Upload instance must
instead contain a valid Net::OAuth access token which can be added by calling the
Flickr::API "oauth_access_token" method.
Returns the resulting identifier of the uploaded photo on success, "undef" on failure.
According to the API documentation, after an upload the user should be directed to the
page <https://www.flickr.com/tools/uploader_edit.gne?ids=$photoid>.
If the "async" option is non-zero, the photo will be uploaded asynchronously and a
successful upload returns a ticket identifier. See
<https://www.flickr.com/services/api/upload.async.html>. The caller can then periodically
poll for a photo id using the "check_upload" method. Note that photo and ticket
identifiers aren't necessarily numeric.
check_upload
my %status2txt = (0 => 'not complete', 1 => 'completed', 2 => 'failed');
my @rc = $ua->check_upload( @ticketids );
for( @rc ) {
print "Ticket $_->{id} has $status2txt{$_->{complete}}\n";
print "\tPhoto id is $_->{photoid}\n" if exists $_->{photoid};
}
This function will check the status of one or more asynchronous uploads. A list of ticket
identifiers are provided (@ticketids) and each is checked. This is basically just a
wrapper around the Flickr API "flickr.photos.upload.checkTickets" method.
On success, a list of hash references is returned. Each hash contains a "id" (the ticket
id), "complete" and, if completed, "photoid" members. "invalid" may also be returned.
Status codes (for "complete") are as documented at
<https://www.flickr.com/services/api/upload.async.html> and, actually, the returned fields
are identical to those listed in the "ticket" tag of the response. The returned list
isn't guaranteed to be in any particular order.
This function polls a web server, so avoid calling it too frequently.
make_upload_request
my $req = $uploader->make_upload_request(
'auth_token' => '82374523',
'tags' => 'me myself eye',
'is_public' => 1,
'is_friend' => 1,
'is_family' => 1
);
$req->header( 'X-Greetz' => 'hi cal' );
my $resp = $ua->request( $req );
Creates an HTTP::Request object loaded with all the flick upload parameters. This will
also sign the request, which means you won't be able to mess any further with the upload
request parameters.
Takes all the same parameters as upload, except that the photo argument isn't required.
This in intended so that the caller can include it by messing directly with the HTTP
content (via $DYNAMIC_FILE_UPLOAD or the HTTP::Message class, among other things). See
"t/" directory from the source distribution for examples.
Returns a standard HTTP::Response POST object. The caller can manually do the upload or
just call the upload_request function.
upload_request
my $photoid = upload_request( $ua, $request );
Taking (at least) LWP::UserAgent and HTTP::Request objects as arguments, this executes the
request and processes the result as a flickr upload. It's assumed that the request looks a
lot like something created with make_upload_request. Note that the request must be signed
according to the Flickr API authentication rules.
Returns the resulting identifier of the uploaded photo (or ticket for asynchronous
uploads) on success, "undef" on failure. According to the API documentation, after an
upload the user should be directed to the page
<https://www.flickr.com/tools/uploader_edit.gne?ids=$photoid>.
file_length_in_encoded_chunk
$HTTP::Request::Common::DYNAMIC_FILE_UPLOAD = 1;
my $photo = 'image.jpeg';
my $photo_size = (stat($photo))[7];
my $req = $ua->make_upload_request( ... );
my $gen = $req->content();
die unless ref($gen) eq "CODE";
my $state;
my $size;
$req->content(
sub {
my $chunk = &$gen();
$size += Flickr::Upload::file_length_in_encoded_chunk(\$chunk, \$state, $photo_size);
warn "$size bytes have now been uploaded";
return $chunk;
}
);
$rc = $ua->upload_request( $req );
This subroutine is tells you how much of a chunk in a series of variable size multipart
HTTP chunks contains a single file being uploaded given a reference to the current chunk,
a reference to a state variable that lives between calls, and the size of the file being
uploaded.
It can be used used along with HTTP::Request::Common's
$HTTP::Request::Common::DYNAMIC_FILE_UPLOAD facility to implement upload progress bars or
other upload monitors, see flickr_upload for a practical example and t/progress_request.t
for tests.
photosets_create
Calls Flickr's "flickr.photosets.create" method,
to create a new Set.
The set will use the PrimaryPhotoID as the thumbnail photo.
returns: UNDEF on failure, PhotosetID on success.
my $photoset_id = $ua->photosets_create( title => 'title',
description => 'description',
primary_photo_id => ID,
auth_token => AUTH_TOKEN );
$ua->photosets_addphoto ( photoset_id => $photoset_id,
photo_id => ID );
photosets_addphoto
Calls Flickr's "flickr.photosets.addPhoto" method,
to add a (existing) photo to an existing set.
returns: UNDEF on failure, TRUE on success.
my $photoset_id = $ua->photosets_create( title => 'title',
description => 'description',
primary_photo_id => ID,
auth_token => AUTH_TOKEN );
$ua->photosets_addphoto ( photoset_id => $photoset_id,
photo_id => ID );
SEE ALSO
<https://www.flickr.com/services/api/>
Flickr::API
AUTHORS
Christophe Beauregard, cpb@cpan.org
Ævar Arnfjörð Bjarmason, <avar@cpan.org>
COPYRIGHT AND LICENSE
This module is not an official Flickr.com (or Ludicorp, or Yahoo) service.
Copyright (C) 2004-2008 by Christophe Beauregard and 2008-2009 by Ævar Arnfjörð Bjarmason
This library is free software; you can redistribute it and/or modify it under the same
terms as Perl itself, either Perl version 5.8.3 or, at your option, any later version of
Perl 5 you may have available.