NAME

WWW::Zooomr::Scraper - upload files to Zooomr via website interface

VERSION

This document describes WWW::Zooomr::Scraper version 0.3.0. Most likely, this version number here is outdate, and you should peek the source.

SYNOPSIS

   use WWW::Zooomr::Scraper;

   my $zooomr = WWW::Zooomr::Scraper->new();

   eval {
      $zooomr->login(username => 'polettix', password => 'whatever');
      my $photo_uri = $zooomr->upload(filename => '/path/to/file.jpg');
      print {*STDOUT} "URI: $photo_uri\n";
      $zooomr->logout();
   } or warn "error uploading: $@";

DESCRIPTION

This module allows uploading photos to Zooomr (http://www.zooomr.com/) programatically through the website interface, i.e. through the same upload facility that can be used from the browser.

INTERFACE

Object Handling and Configuration

new

   my $zooomr = WWW::Zooomr::Scraper->new(%config);
   my $zooomr = WWW::Zooomr::Scraper->new(\%config);

Create a new object. The parameters that can be passed are the following:

"updater"
"agent"
"username"
"password"
"login_page"
"upload_page"
"logout_page"

See the documentation for each corresponding accessor method. Moreover, the following parameters can be passed (though they do not have accessors):

proxy: set the proxy to use for accessing the Internet; this parameter implies setting the proxy in the "agent".
cookie: set the cookie file to use in order to gather the access credentials. This parameter triggers a call to "load_cookies_from".

reconfig

   $zooomr->reconfig(%config);
   $zooomr->reconfig(\%config);

Reconfigures the object with the given configuration - the same parameters accepted by "new" can be passed. Additionally, this method sets an "agent" if one is not passed or didn't exists previously, and loads the cookie file if passed.

update_proxy

   $zooomer->update_proxy($new_proxy_string);

This method reconfigures the proxy in the "agent" inside the object. This method can be used to set a new proxy in case of changed network conditions.

load_cookies_from

   $zooomr->load_cookies_from($filename);

Load the credentials from the specified cookie file. This is useful if you want to avoid configuring the "username" and "password" parameters; in this case, you should enter the Zooomr website by yourself, then point the object to the cookie file produced by your browser, where the connection credentials are stored.

Note that the Cookie file must have a Mozilla format. SQLite-based system used by Firefox is OK, as long as HTTP::Cookies::Mozilla is used and it's a recent-enough version.

Accessors

The following are accessor methods that give access to objects or configurations.

get_updater

set_updater

The updater is an optional object that is used to provide notifications to the external world. See the dedicated section "The Updater" below.

get_agent

set_agent

Object a-la WWW::Mechanize that acts as the User-Agent.

For better result, it is suggested that the agent is set in auto-checking mode.

get_username

set_username

Username for accessing the Zooomr website and upload photos.

get_password

set_password

Password for "username" at the Zooomr website.

get_login_page

set_login_page

The URI of the Zooomr login page. You shouldn't need to set this because the default value should work out of the box.

get_upload_page

set_upload_page

The URI of the Zooomr page for uploading. You shouldn't need to set this because the default value should work out of the box.

get_logout_page

set_logout_page

The URI of the Zooomr logout page. You shouldn't need to set this because the default value should work out of the box.

Interaction Methods

login

   $zooomr->login();
   $zooomr->login(username => 'polettix');
   $zooomr->login(username => 'polettix', password => 'whatever');

Perform the login phase.

Two parameters can be accepted: username and password, with the same meaning as the accessors. As a matter of fact, passing either one sets the corresponding value inside the object, i.e. it calls the accessor for you.

logout

   $zooomr->logout();

Log out from Zooomr.

upload

   $zooomr->upload(filename => '/path/to/file.jpg', %other_config);
   $zooomr->upload(\%config);

Add one file to Zooomr. Assumes that the "login" phase has been performed successfully.

Returns the URI of the page where the photo can be accessed. Throws an exception if any error occurs.

The following parameters are supported:

filename: mandatory, the name of the photo file to upload;
tags: a string with a comma-separated list of tags to associate to the photo;
public: flag indicating whether the photo is public (if 1) or private (if 0);
friends: if the "public" flag above is set to 0, you can optionally set that the photo can be seen by friends;
family: if the "public" flag above is set to 0, you can optionally set that the photo can be seen by family members;
file_counter: this is an opaque value that is passed along to the updater, see "The Updater".

The Updater

You can set an updater object that will be used to track different statuses of the login/upload processes. In particular, the latter operation can be long and the User might get nervous without proper feedbak; the updater is the solution to this problem.

The Updater is something completely optional. If it is set, it must sport an interface that is specific to the upload phase. The required method is the following:

post

   $updater->post($type, %parameters);

Send a specific status message. Possible values for $type are:

start_file

This event is posted when the file upload starts. In this case, the parameters that are passed are the following:

filename: the full path to the file to be uploaded;
barename: the bare name of the file, i.e. the file's basename filename without the so-called extension. For example, /path/to/myfile.jpg has a barename equal to myfile.
file_counter: The same value passed to the upload function.
file_octets: The number of octets that will be uploaded, i.e. the Content-Length of the request soon to be sent.

update_file

This event is posted at regular intervals to give a feedback about the upload. Only one parameter is sent, i.e. sent_octets, with the total number of octets sent (even though the latest chunk is to be sent yet).

end_file

This event is posted when the file upload ends. The following parameters are passed:

filename: the name of the uploaded file;
uri: the URI where the uploaded file is (set to undef if the upload was not successful);
outcome: either success or failure.

The following code represents a minimal but working updater based on Term::ProgressBar:

   package Some::Updater;
   use strict;
   use warnings;
   use Term::ProgressBar;

   sub post {
      my ($self, $method, %params) = @_;
      $self->$method(%params);
   }

   sub start_file {
      my ($self, %params) = @_;
      $self->{pb} = Term::ProgressBar->new({
         count => $params{file_octets},
         name  => $params{barename},
      });
      $self->{pb} = $pb;
      return;
   }

   sub update_file {
      my ($self, %params) = @_;
      return unless $self->{pb}; # just in case...
      $self->{pb}->update($params{sent_octets});
      return;
   }

   sub update_file {
      my ($self, %params) = @_;
      if ($params{outcome} eq 'failure') {
         print {*STDERR} "something failed with $params{filename}\n";
      }
      else {
         print {*STDERR} "$params{filename} uploaded to $params{uri}\n";
      }
      return;
   }

DIAGNOSTICS

Some of these errors could be overridden if the User-Agent object is set to auto_check mode.

could't get %s page

The specified page (either the login, upload or logout) couldn't be got, so the related operation bailed out.

This message is overridden by the auto_check mode in the User-Agent.

no login form

The login page was got, but there is no login form in it. It should indicate that Zooomr changed the interface.

This message is overridden by the auto_check mode in the User-Agent.

no button to click

The login form has no button to be clicked. It should indicate that Zooomr changed the interface.

upload completed by no photo

The upload process was completed but the photo didn't appear in the User's default page in Zooomr. This should indicate a failed upload, actually.

could not load cookie file %s

The cookie file was not accepted by /load_cookies_from. It could be unreadable, or in a non-Mozilla format.

CONFIGURATION AND ENVIRONMENT

WWW::Zooomr::Scraper requires no configuration files or environment variables.

It honors the $ENV{http_proxy} environment variable when set.

DEPENDENCIES

This module depends on the following non-core modules:

version
WWW::Mechanize
Path::Class

Additionally, the function "load_cookies_from" depends upon HTTP::Cookies::Mozilla.

INCOMPATIBILITIES

None reported.

BUGS AND LIMITATIONS

No bugs have been reported.

Please report any bugs or feature requests through http://rt.cpan.org/

AUTHOR

Flavio Poletti <flavio [at] polettix [dot] it>

LICENCE AND COPYRIGHT

This module is free software; you can redistribute it and/or modify it under the same terms as Perl 5.8.x itself. See perlartistic and perlgpl.

Questo modulo è software libero: potete ridistribuirlo e/o modificarlo negli stessi termini di Perl 5.8.x stesso. Vedete anche perlartistic e perlgpl.

DISCLAIMER OF WARRANTY

BECAUSE THIS SOFTWARE IS LICENSED FREE OF CHARGE, THERE IS NO WARRANTY FOR THE SOFTWARE, TO THE EXTENT PERMITTED BY APPLICABLE LAW. EXCEPT WHEN OTHERWISE STATED IN WRITING THE COPYRIGHT HOLDERS AND/OR OTHER PARTIES PROVIDE THE SOFTWARE "AS IS" WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESSED OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. THE ENTIRE RISK AS TO THE QUALITY AND PERFORMANCE OF THE SOFTWARE IS WITH YOU. SHOULD THE SOFTWARE PROVE DEFECTIVE, YOU ASSUME THE COST OF ALL NECESSARY SERVICING, REPAIR, OR CORRECTION.

IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN WRITING WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MAY MODIFY AND/OR REDISTRIBUTE THE SOFTWARE AS PERMITTED BY THE ABOVE LICENCE, BE LIABLE TO YOU FOR DAMAGES, INCLUDING ANY GENERAL, SPECIAL, INCIDENTAL, OR CONSEQUENTIAL DAMAGES ARISING OUT OF THE USE OR INABILITY TO USE THE SOFTWARE (INCLUDING BUT NOT LIMITED TO LOSS OF DATA OR DATA BEING RENDERED INACCURATE OR LOSSES SUSTAINED BY YOU OR THIRD PARTIES OR A FAILURE OF THE SOFTWARE TO OPERATE WITH ANY OTHER SOFTWARE), EVEN IF SUCH HOLDER OR OTHER PARTY HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGES.

NEGAZIONE DELLA GARANZIA

Poiché questo software viene dato con una licenza gratuita, non c'è alcuna garanzia associata ad esso, ai fini e per quanto permesso dalle leggi applicabili. A meno di quanto possa essere specificato altrove, il proprietario e detentore del copyright fornisce questo software "così com'è" senza garanzia di alcun tipo, sia essa espressa o implicita, includendo fra l'altro (senza però limitarsi a questo) eventuali garanzie implicite di commerciabilità e adeguatezza per uno scopo particolare. L'intero rischio riguardo alla qualità ed alle prestazioni di questo software rimane a voi. Se il software dovesse dimostrarsi difettoso, vi assumete tutte le responsabilità ed i costi per tutti i necessari servizi, riparazioni o correzioni.

In nessun caso, a meno che ciò non sia richiesto dalle leggi vigenti o sia regolato da un accordo scritto, alcuno dei detentori del diritto di copyright, o qualunque altra parte che possa modificare, o redistribuire questo software così come consentito dalla licenza di cui sopra, potrà essere considerato responsabile nei vostri confronti per danni, ivi inclusi danni generali, speciali, incidentali o conseguenziali, derivanti dall'utilizzo o dall'incapacità di utilizzo di questo software. Ciò include, a puro titolo di esempio e senza limitarsi ad essi, la perdita di dati, l'alterazione involontaria o indesiderata di dati, le perdite sostenute da voi o da terze parti o un fallimento del software ad operare con un qualsivoglia altro software. Tale negazione di garanzia rimane in essere anche se i dententori del copyright, o qualsiasi altra parte, è stata avvisata della possibilità di tali danneggiamenti.

Se decidete di utilizzare questo software, lo fate a vostro rischio e pericolo. Se pensate che i termini di questa negazione di garanzia non si confacciano alle vostre esigenze, o al vostro modo di considerare un software, o ancora al modo in cui avete sempre trattato software di terze parti, non usatelo. Se lo usate, accettate espressamente questa negazione di garanzia e la piena responsabilità per qualsiasi tipo di danno, di qualsiasi natura, possa derivarne.

	Global
`s`	Focus search bar
`?`	Bring up this help dialog

	GitHub
`g` `p`	Go to pull requests
`g` `i`	go to github issues (only if github is preferred repository)

	POD
`g` `a`	Go to author
`g` `c`	Go to changes
`g` `i`	Go to issues
`g` `d`	Go to dist
`g` `r`	Go to repository/SCM
`g` `s`	Go to source
`g` `b`	Go to file browse

	Search terms
module: (e.g. module:Plugin)
distribution: (e.g. distribution:Dancer auth)
author: (e.g. author:SONGMU Redis)
version: (e.g. version:1.00)