.\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.42)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings.  \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote.  \*(C+ will
.\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
.\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
.    ds -- \(*W-
.    ds PI pi
.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
.    ds L" ""
.    ds R" ""
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds -- \|\(em\|
.    ds PI \(*p
.    ds L" ``
.    ds R" ''
.    ds C`
.    ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is >0, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{\
.    if \nF \{\
.        de IX
.        tm Index:\\$1\t\\n%\t"\\$2"
..
.        if !\nF==2 \{\
.            nr % 0
.            nr F 2
.        \}
.    \}
.\}
.rr rF
.\" ========================================================================
.\"
.IX Title "Flickr::Upload 3pm"
.TH Flickr::Upload 3pm "2022-06-14" "perl v5.34.0" "User Contributed Perl Documentation"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "NAME"
Flickr::Upload \- Upload images to "flickr.com"
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 1
\&        use Flickr::Upload;
\&
\&        my $ua = Flickr::Upload\->new(
\&                {
\&                        \*(Aqkey\*(Aq => \*(Aq90909354\*(Aq,
\&                        \*(Aqsecret\*(Aq => \*(Aq37465825\*(Aq
\&                });
\&        $ua\->upload(
\&                \*(Aqphoto\*(Aq => \*(Aq/tmp/image.jpg\*(Aq,
\&                \*(Aqauth_token\*(Aq => $auth_token,
\&                \*(Aqtags\*(Aq => \*(Aqme myself eye\*(Aq,
\&                \*(Aqis_public\*(Aq => 1,
\&                \*(Aqis_friend\*(Aq => 1,
\&                \*(Aqis_family\*(Aq => 1
\&        ) or die "Failed to upload /tmp/image.jpg";
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
Upload an image to flickr.com.
.SH "METHODS"
.IX Header "METHODS"
.SS "new"
.IX Subsection "new"
.IP "Using Flickr Authentication" 4
.IX Item "Using Flickr Authentication"
.Vb 5
\&        my $ua = Flickr::Upload\->new(
\&                {
\&                        \*(Aqkey\*(Aq => \*(Aq90909354\*(Aq,
\&                        \*(Aqsecret\*(Aq => \*(Aq37465825\*(Aq
\&                });
.Ve
.IP "Using OAuth Authentication" 4
.IX Item "Using OAuth Authentication"
.Vb 5
\&        my $ua = Flickr::Upload\->new(
\&                {
\&                        \*(Aqconsumer_key\*(Aq => \*(Aqyour_api_key\*(Aq,
\&                        \*(Aqconsumer_secret\*(Aq => \*(Aqyour_app_secret\*(Aq,
\&                });
.Ve
.IP "Retrieve saved configuration (possibly including OAuth access token)" 4
.IX Item "Retrieve saved configuration (possibly including OAuth access token)"
.Vb 2
\&        my $config_file = "$ENV{HOME}/saved\-flickr.st";
\&        my $ua = Flickr::Upload\->import_storable_config($config_file);
.Ve
.PP
Instantiates a Flickr::Upload instance, using either the Flickr
Authentication or the OAuth Authentication. The \f(CW\*(C`key\*(C'\fR or
\&\f(CW\*(C`consumer_key\*(C'\fR argument is your \s-1API\s0 key and the \f(CW\*(C`secret\*(C'\fR or
\&\f(CW\*(C`consumer_secret\*(C'\fR argument is the \s-1API\s0 secret associated with it. To
get an \s-1API\s0 key and secret, go to
<https://www.flickr.com/services/api/key.gne>.
.PP
The resulting Flickr::Upload instance is a subclass of Flickr::API
and can be used for any other Flickr \s-1API\s0 calls.  As such,
Flickr::Upload is also a subclass of LWP::UserAgent.
.SS "upload"
.IX Subsection "upload"
.Vb 9
\&        my $photoid = $ua\->upload(
\&                \*(Aqphoto\*(Aq => \*(Aq/tmp/image.jpg\*(Aq,
\&                \*(Aqauth_token\*(Aq => $auth_token,
\&                \*(Aqtags\*(Aq => \*(Aqme myself eye\*(Aq,
\&                \*(Aqis_public\*(Aq => 1,
\&                \*(Aqis_friend\*(Aq => 1,
\&                \*(Aqis_family\*(Aq => 1
\&                \*(Aqasync\*(Aq => 0,
\&        );
.Ve
.PP
Taking a Flickr::Upload instance \f(CW$ua\fR as an argument, this is
basically a direct interface to the Flickr Photo Upload \s-1API.\s0 Required
parameters are \f(CW\*(C`photo\*(C'\fR and, when using Flickr Authentication,
\&\f(CW\*(C`auth_token\*(C'\fR.  Note that the \f(CW\*(C`auth_token\*(C'\fR must have been issued
against the \s-1API\s0 key and secret used to instantiate the uploader.
.PP
When using OAuth, \f(CW\*(C`auth_token\*(C'\fR 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
\&\f(CW\*(C`oauth_access_token\*(C'\fR method.
.PP
Returns the resulting identifier of the uploaded photo on success,
\&\f(CW\*(C`undef\*(C'\fR on failure. According to the \s-1API\s0 documentation, after an upload the
user should be directed to the page
<https://www.flickr.com/tools/uploader_edit.gne?ids=$photoid>.
.PP
If the \f(CW\*(C`async\*(C'\fR 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 \f(CW\*(C`check_upload\*(C'\fR method. Note
that photo and ticket identifiers aren't necessarily numeric.
.SS "check_upload"
.IX Subsection "check_upload"
.Vb 6
\&        my %status2txt = (0 => \*(Aqnot complete\*(Aq, 1 => \*(Aqcompleted\*(Aq, 2 => \*(Aqfailed\*(Aq);
\&        my @rc = $ua\->check_upload( @ticketids );
\&        for( @rc ) {
\&                print "Ticket $_\->{id} has $status2txt{$_\->{complete}}\en";
\&                print "\etPhoto id is $_\->{photoid}\en" if exists $_\->{photoid};
\&        }
.Ve
.PP
This function will check the status of one or more asynchronous uploads. A
list of ticket identifiers are provided (\f(CW@ticketids\fR) and each is
checked. This is basically just a wrapper around the Flickr \s-1API\s0
\&\f(CW\*(C`flickr.photos.upload.checkTickets\*(C'\fR method.
.PP
On success, a list of hash references is returned. Each
hash contains a \f(CW\*(C`id\*(C'\fR (the ticket id), \f(CW\*(C`complete\*(C'\fR and, if
completed, \f(CW\*(C`photoid\*(C'\fR members. \f(CW\*(C`invalid\*(C'\fR may also be returned.
Status codes (for \f(CW\*(C`complete\*(C'\fR) 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 \f(CW\*(C`ticket\*(C'\fR tag of the
response.  The returned list isn't guaranteed to be in any particular order.
.PP
This function polls a web server, so avoid calling it too frequently.
.SS "make_upload_request"
.IX Subsection "make_upload_request"
.Vb 9
\&        my $req = $uploader\->make_upload_request(
\&                \*(Aqauth_token\*(Aq => \*(Aq82374523\*(Aq,
\&                \*(Aqtags\*(Aq => \*(Aqme myself eye\*(Aq,
\&                \*(Aqis_public\*(Aq => 1,
\&                \*(Aqis_friend\*(Aq => 1,
\&                \*(Aqis_family\*(Aq => 1
\&        );
\&        $req\->header( \*(AqX\-Greetz\*(Aq => \*(Aqhi cal\*(Aq );
\&        my $resp = $ua\->request( $req );
.Ve
.PP
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.
.PP
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 \s-1HTTP\s0 content (via \f(CW$DYNAMIC_FILE_UPLOAD\fR or
the HTTP::Message class, among other things). See \f(CW\*(C`t/\*(C'\fR directory from
the source distribution for examples.
.PP
Returns a standard HTTP::Response \s-1POST\s0 object. The caller can manually
do the upload or just call the upload_request function.
.SS "upload_request"
.IX Subsection "upload_request"
.Vb 1
\&        my $photoid = upload_request( $ua, $request );
.Ve
.PP
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 \s-1API\s0 authentication rules.
.PP
Returns the resulting identifier of the uploaded photo (or ticket for
asynchronous uploads) on success, \f(CW\*(C`undef\*(C'\fR on failure. According to the
\&\s-1API\s0 documentation, after an upload the user should be directed to the
page <https://www.flickr.com/tools/uploader_edit.gne?ids=$photoid>.
.SS "file_length_in_encoded_chunk"
.IX Subsection "file_length_in_encoded_chunk"
.Vb 6
\&        $HTTP::Request::Common::DYNAMIC_FILE_UPLOAD = 1;
\&        my $photo = \*(Aqimage.jpeg\*(Aq;
\&        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(\e$chunk, \e$state, $photo_size);
\&
\&                        warn "$size bytes have now been uploaded";
\&
\&                        return $chunk;
\&                }
\&        );
\&
\&        $rc = $ua\->upload_request( $req );
.Ve
.PP
This subroutine is tells you how much of a chunk in a series of
variable size multipart \s-1HTTP\s0 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.
.PP
It can be used used along with HTTP::Request::Common's
\&\f(CW$HTTP::Request::Common::DYNAMIC_FILE_UPLOAD\fR facility to implement
upload progress bars or other upload monitors, see flickr_upload
for a practical example and \fIt/progress_request.t\fR for tests.
.SS "photosets_create"
.IX Subsection "photosets_create"
.Vb 2
\&        Calls Flickr\*(Aqs "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 => \*(Aqtitle\*(Aq,
\&                                       description => \*(Aqdescription\*(Aq,
\&                                       primary_photo_id => ID,
\&                                       auth_token => AUTH_TOKEN );
\&
\&        $ua\->photosets_addphoto ( photoset_id => $photoset_id,
\&                                  photo_id => ID );
.Ve
.SS "photosets_addphoto"
.IX Subsection "photosets_addphoto"
.Vb 2
\&        Calls Flickr\*(Aqs "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 => \*(Aqtitle\*(Aq,
\&                                       description => \*(Aqdescription\*(Aq,
\&                                       primary_photo_id => ID,
\&                                       auth_token => AUTH_TOKEN );
\&
\&        $ua\->photosets_addphoto ( photoset_id => $photoset_id,
\&                                  photo_id => ID );
.Ve
.SH "SEE ALSO"
.IX Header "SEE ALSO"
<https://www.flickr.com/services/api/>
.PP
Flickr::API
.SH "AUTHORS"
.IX Header "AUTHORS"
Christophe Beauregard, cpb@cpan.org
.PP
Ævar Arnfjörð Bjarmason, <avar@cpan.org>
.SH "COPYRIGHT AND LICENSE"
.IX Header "COPYRIGHT AND LICENSE"
This module is not an official Flickr.com (or Ludicorp, or Yahoo) service.
.PP
Copyright (C) 2004\-2008 by Christophe Beauregard and 2008\-2009 by
Ævar Arnfjörð Bjarmason
.PP
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.