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¶
my $ua = Flickr::Upload->new(
{
'key' => '90909354',
'secret' => '37465825'
});
Instantiates a Flickr::Upload instance. The "key" argument is your API
key and the "secret" is the API secret associated with it. To get an
API key and secret, go to <
http://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 "auth_token". Note that the
"auth_token" must have been issued against the API key and secret
used to instantiate the uploader.
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
<
http://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
<
http://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
<
http://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
<
http://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.
SEE ALSO¶
<
http://flickr.com/services/api/>
Flickr::API
AUTHORS¶
Christophe Beauregard, cpb@cpan.org
AEvar Arnfjoerd` 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 AEvar
Arnfjoerd` 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.