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