/ 
File-Dropbox-0.4
River stage zero No dependents
/ File::Dropbox

NAME

File::Dropbox - Convenient and fast Dropbox API abstraction

SYNOPSIS

use File::Dropbox;
use Fcntl;

# Application credentials
my %app = (
    app_key       => 'app key',
    app_secret    => 'app secret',
    access_token  => 'access token',
    access_secret => 'access secret',
);

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 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 => 'secret',
    access_token  => 'token',
    app_secret    => 'app secret',
    app_key       => 'app key',
    chunk         => 8 * 1024 * 1024,
    root          => 'dropbox',
    furlopts      => {
        timeout => 20
    }
);

Constructor, takes key-value pairs list

access_secret

OAuth 1.0 access secret

access_token

OAuth 1.0 access token

app_secret

OAuth 1.0 app secret

app_key

OAuth 1.0 app key

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

SEE ALSO

Furl, Furl::HTTP, WebService::Dropbox, Dropbox API

AUTHOR

Alexander Nazarov <nfokz@cpan.org>

COPYRIGHT AND LICENSE

Copyright 2013 Alexander Nazarov

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