NAME

Flickr::Upload - Upload images to flickr.com

SYNOPSIS

        use LWP::UserAgent;
        use Flickr::Upload qw(upload);

        my $ua = LWP::UserAgent->new;
        upload(
                $ua,
                'photo' => '/tmp/image.jpg',
                'email' => 'self@example.com',
                'password' => 'pr1vat3',
                '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.

FUNCTIONS

upload

        my $photoid = upload(
                $ua,
                'photo' => '/tmp/image.jpg',
                'email' => 'self@example.com',
                'password' => 'pr1vat3',
                'tags' => 'me myself eye',
                'is_public' => 1,
                'is_friend' => 1,
                'is_family' => 1
                'async' => 0,
        );

Taking a LWP::UserAgent as an argument ($ua), this is basically a direct interface to the Flickr Photo Upload API. Required parameters are photo, email, and password. uri may be provided if you don't want to use the default, http://www.flickr.com/tools/uploader_go.gne (i.e. you have a custom server running somewhere that supports the API).

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 number. See http://flickr.com/services/api/upload.async.html. The caller can then periodically poll for a photo id using the check_upload call.

check_upload

        my %status2txt = (0 => 'not complete', 1 => 'completed', 2 => 'failed');
        my @rc = check_upload( $ua, @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.

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 = make_upload_request(
                'email' => 'self@example.com',
                'password' => 'pr1vat3',
                '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.

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 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.

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.

SEE ALSO

http://flickr.com/services/api/.

AUTHOR

Christophe Beauregard, cpb@cpan.org

COPYRIGHT AND LICENSE

This module is not an official Flickr.com (or Ludicorp) 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.