--- name: "File::Dropbox" section: "3pm" platform: "linux" package: "libfile-dropbox-perl" version: "0.7-2" release: "Debian 13 (Trixie)" platforms: ["linux"] url: "https://new.carta.tech/File::Dropbox" --- # File::Dropbox(3pm) Convenient and fast Dropbox API abstraction ## 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 \. `$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 \ ## AUTHOR Alexander Nazarov \ ## 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.