File::Dropbox(3pm)

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".

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'};

AUTHOR

Alexander Nazarov <[email protected]>

COPYRIGHT AND LICENSE

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