trusty (3) Flickr::Upload.3pm.gz
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'
});
Instatiates 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
AUTHOR
Christophe Beauregard, cpb@cpan.org
COPYRIGHT AND LICENSE
This module is not an official Flickr.com (or Ludicorp, or Yahoo) service.
Copyright (C) 2004,2005 by Christophe Beauregard
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.