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 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 => 'secret',
        access_token  => '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 => '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. $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

AUTHOR

Alexander Nazarov <nfokz@cpan.org>

COPYRIGHT AND LICENSE

Copyright 2013, 2014 Alexander Nazarov

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

cpanm File::Dropbox

perl -MCPAN -e shell
install File::Dropbox