NAME

       File::Dropbox - Convenient and fast Dropbox API abstraction

SYNOPSIS

           use File::Dropbox;
           use Fcntl;

           # Application credentials
           my %app = (
               oauth2        => 1,
               access_token  => $access_token,
           );

           my $dropbox = File::Dropbox->new(%app);

           # Open file for writing
           open $dropbox, '>', 'example' or die $!;

           while (<>) {
               # Upload data using 4MB chunks
               print $dropbox $_;
           }

           # Commit upload (optional, close will be called on reopen)
           close $dropbox or die $!;

           # Open for reading
           open $dropbox, '<', 'example' or die $!;

           # Download and print to STDOUT
           # Buffered, default buffer size is 4MB
           print while <$dropbox>;

           # Reset file position
           seek $dropbox, 0, Fcntl::SEEK_SET;

           # Get first character (unbuffered)
           say getc $dropbox;

           close $dropbox;

DESCRIPTION

       "File::Dropbox" provides high-level Dropbox API abstraction based on Tie::Handle. Code
       required to get "access_token" and "access_secret" for signed OAuth 1.0 requests or
       "access_token" for OAuth 2.0 requests is not included in this module.  To get "app_key"
       and "app_secret" you need to register your application with Dropbox.

       At this moment Dropbox API is not fully supported, "File::Dropbox" covers file read/write
       and directory listing methods. If you need full API support take look at
       WebService::Dropbox. "File::Dropbox" main purpose is not 100% API coverage, but simple and
       high-performance file operations.

       Due to API limitations and design you can not do read and write operations on one file at
       the same time. Therefore handle can be in read-only or write-only state, depending on last
       call to open. Supported functions for read-only state are: open, close, seek, tell,
       readline, read, sysread, getc, eof. For write-only state: open, close, syswrite, print,
       printf, say.

       All API requests are done using Furl module. For more accurate timeouts Net::DNS::Lite is
       used, as described in Furl::HTTP. Furl settings can be overridden using "furlopts".

METHODS

   new
           my $dropbox = File::Dropbox->new(
               access_secret => $access_secret,
               access_token  => $access_token,
               app_secret    => $app_secret,
               app_key       => $app_key,
               chunk         => 8 * 1024 * 1024,
               root          => 'dropbox',
               furlopts      => {
                   timeout => 20
               }
           );

           my $dropbox = File::Dropbox->new(
               access_token => $access_token,
               oauth2       => 1
           );

       Constructor, takes key-value pairs list

       access_secret
           OAuth 1.0 access secret

       access_token
           OAuth 1.0 access token or OAuth 2.0 access token

       app_secret
           OAuth 1.0 app secret

       app_key
           OAuth 1.0 app key

       oauth2
           OAuth 2.0 switch, defaults to false.

       chunk
           Upload chunk size in bytes. Also buffer size for "readline". Optional. Defaults to
           4MB.

       root
           Access type, "sandbox" for app-folder only access and "dropbox" for full access.

       furlopts
           Parameter hash, passed to Furl constructor directly. Default options

               timeout   => 10,
               inet_aton => \&Net::DNS::Lite::inet_aton,
               ssl_opts  => {
                   SSL_verify_mode => SSL_VERIFY_PEER(),
               }

FUNCTIONS

       All functions are not exported by default but can be exported on demand.

           use File::Dropbox qw{ contents metadata putfile };

       First argument for all functions should be GLOB reference, returned by "new".

   contents
       Arguments: $dropbox [, $path]

       Function returns list of hashrefs representing directory content. Hash fields described in
       Dropbox API docs <https://www.dropbox.com/developers/core/docs#metadata>. $path defaults
       to "/". If there is unfinished chunked upload on handle, it will be committed.

           foreach my $file (contents($dropbox, '/data')) {
               next if $file->{'is_dir'};
               say $file->{'path'}, ' - ', $file->{'bytes'};
           }

   metadata
       Arguments: $dropbox

       Function returns stored metadata for read-only handle, closed write handle or after call
       to "contents" or "putfile".

           open $dropbox, '<', '/data/2013.dat' or die $!;

           my $meta = metadata($dropbox);

           if ($meta->{'bytes'} > 1024) {
               # Do something
           }

   putfile
       Arguments: $dropbox, $path, $data

       Function is useful for uploading small files (up to 150MB possible) in one request (at
       least two API requests required for chunked upload, used in open-write-close sequence). If
       there is unfinished chunked upload on handle, it will be committed.

           local $/;
           open my $data, '<', '2012.dat' or die $!;

           putfile($dropbox, '/data/2012.dat', <$data>) or die $!;

           say 'Uploaded ', metadata($dropbox)->{'bytes'}, ' bytes';

           close $data;

   copyfile
       Arguments: $dropbox, $source, $target

       Function copies file or directory from one location to another. Metadata for copy can be
       accessed using "metadata" function.

           copyfile($dropbox, '/data/2012.dat', '/data/2012.dat.bak') or die $!;

           say 'Created backup with revision ', metadata($dropbox)->{'revision'};

   movefile
       Arguments: $dropbox, $source, $target

       Function moves file or directory from one location to another. Metadata for moved file can
       be accessed using "metadata" function.

           movefile($dropbox, '/data/2012.dat', '/data/2012.dat.bak') or die $!;

           say 'Created backup with size ', metadata($dropbox)->{'size'};

   deletefile
       Arguments: $dropbox, $path

       Function deletes file or folder at specified path. Metadata for deleted item is accessible
       via "metadata" function.

           deletefile($dropbox, '/data/2012.dat.bak') or die $!;

           say 'Deleted backup with last modification ', metadata($dropbox)->{'modification'};

   createfolder
       Arguments: $dropbox, $path

       Function creates folder at specified path. Metadata for created folder is accessible via
       "metadata" function.

           createfolder($dropbox, '/data/backups') or die $!;

           say 'Created folder at path ', metadata($dropbox)->{'path'};

SEE ALSO

       Furl, Furl::HTTP, WebService::Dropbox, Dropbox API
       <https://www.dropbox.com/developers/core/docs>

AUTHOR

       Alexander Nazarov <nfokz@cpan.org>

COPYRIGHT AND LICENSE

       Copyright 2013-2016 Alexander Nazarov

       This program is free software; you can redistribute it and/or modify it under the same
       terms as Perl itself.