| 1 |
NAME |
| 2 |
File::Dropbox - Convenient and fast Dropbox API abstraction |
| 3 |
|
| 4 |
SYNOPSIS |
| 5 |
use File::Dropbox; |
| 6 |
use Fcntl; |
| 7 |
|
| 8 |
# Application credentials |
| 9 |
my %app = ( |
| 10 |
oauth2 => 1, |
| 11 |
access_token => $access_token, |
| 12 |
); |
| 13 |
|
| 14 |
my $dropbox = File::Dropbox->new(%app); |
| 15 |
|
| 16 |
# Open file for writing |
| 17 |
open $dropbox, '>', 'example' or die $!; |
| 18 |
|
| 19 |
while (<>) { |
| 20 |
# Upload data using 4MB chunks |
| 21 |
print $dropbox $_; |
| 22 |
} |
| 23 |
|
| 24 |
# Commit upload (optional, close will be called on reopen) |
| 25 |
close $dropbox or die $!; |
| 26 |
|
| 27 |
# Open for reading |
| 28 |
open $dropbox, '<', 'example' or die $!; |
| 29 |
|
| 30 |
# Download and print to STDOUT |
| 31 |
# Buffered, default buffer size is 4MB |
| 32 |
print while <$dropbox>; |
| 33 |
|
| 34 |
# Reset file position |
| 35 |
seek $dropbox, 0, Fcntl::SEEK_SET; |
| 36 |
|
| 37 |
# Get first character (unbuffered) |
| 38 |
say getc $dropbox; |
| 39 |
|
| 40 |
close $dropbox; |
| 41 |
|
| 42 |
DESCRIPTION |
| 43 |
"File::Dropbox" provides high-level Dropbox API abstraction based on |
| 44 |
Tie::Handle. Code required to get "access_token" and "access_secret" for |
| 45 |
signed OAuth 1.0 requests or "access_token" for OAuth 2.0 requests is |
| 46 |
not included in this module. To get "app_key" and "app_secret" you need |
| 47 |
to register your application with Dropbox. |
| 48 |
|
| 49 |
At this moment Dropbox API is not fully supported, "File::Dropbox" |
| 50 |
covers file read/write and directory listing methods. If you need full |
| 51 |
API support take look at WebService::Dropbox. "File::Dropbox" main |
| 52 |
purpose is not 100% API coverage, but simple and high-performance file |
| 53 |
operations. |
| 54 |
|
| 55 |
Due to API limitations and design you can not do read and write |
| 56 |
operations on one file at the same time. Therefore handle can be in |
| 57 |
read-only or write-only state, depending on last call to open. Supported |
| 58 |
functions for read-only state are: open, close, seek, tell, readline, |
| 59 |
read, sysread, getc, eof. For write-only state: open, close, syswrite, |
| 60 |
print, printf, say. |
| 61 |
|
| 62 |
All API requests are done using Furl module. For more accurate timeouts |
| 63 |
Net::DNS::Lite is used, as described in Furl::HTTP. Furl settings can be |
| 64 |
overriden using "furlopts". |
| 65 |
|
| 66 |
METHODS |
| 67 |
new |
| 68 |
my $dropbox = File::Dropbox->new( |
| 69 |
access_secret => $access_secret, |
| 70 |
access_token => $access_token, |
| 71 |
app_secret => $app_secret, |
| 72 |
app_key => $app_key, |
| 73 |
chunk => 8 * 1024 * 1024, |
| 74 |
root => 'dropbox', |
| 75 |
furlopts => { |
| 76 |
timeout => 20 |
| 77 |
} |
| 78 |
); |
| 79 |
|
| 80 |
my $dropbox = File::Dropbox->new( |
| 81 |
access_token => $access_token, |
| 82 |
oauth2 => 1 |
| 83 |
); |
| 84 |
|
| 85 |
Constructor, takes key-value pairs list |
| 86 |
|
| 87 |
access_secret |
| 88 |
OAuth 1.0 access secret |
| 89 |
|
| 90 |
access_token |
| 91 |
OAuth 1.0 access token or OAuth 2.0 access token |
| 92 |
|
| 93 |
app_secret |
| 94 |
OAuth 1.0 app secret |
| 95 |
|
| 96 |
app_key |
| 97 |
OAuth 1.0 app key |
| 98 |
|
| 99 |
oauth2 |
| 100 |
OAuth 2.0 switch, defaults to false. |
| 101 |
|
| 102 |
chunk |
| 103 |
Upload chunk size in bytes. Also buffer size for "readline". |
| 104 |
Optional. Defaults to 4MB. |
| 105 |
|
| 106 |
root |
| 107 |
Access type, "sandbox" for app-folder only access and "dropbox" for |
| 108 |
full access. |
| 109 |
|
| 110 |
furlopts |
| 111 |
Parameter hash, passed to Furl constructor directly. Default options |
| 112 |
|
| 113 |
timeout => 10, |
| 114 |
inet_aton => \&Net::DNS::Lite::inet_aton, |
| 115 |
ssl_opts => { |
| 116 |
SSL_verify_mode => SSL_VERIFY_PEER(), |
| 117 |
} |
| 118 |
|
| 119 |
FUNCTIONS |
| 120 |
All functions are not exported by default but can be exported on demand. |
| 121 |
|
| 122 |
use File::Dropbox qw{ contents metadata putfile }; |
| 123 |
|
| 124 |
First argument for all functions should be GLOB reference, returned by |
| 125 |
"new". |
| 126 |
|
| 127 |
contents |
| 128 |
Arguments: $dropbox [, $path] |
| 129 |
|
| 130 |
Function returns list of hashrefs representing directory content. Hash |
| 131 |
fields described in Dropbox API docs |
| 132 |
<https://www.dropbox.com/developers/core/docs#metadata>. $path defaults |
| 133 |
to "/". If there is unfinished chunked upload on handle, it will be |
| 134 |
commited. |
| 135 |
|
| 136 |
foreach my $file (contents($dropbox, '/data')) { |
| 137 |
next if $file->{'is_dir'}; |
| 138 |
say $file->{'path'}, ' - ', $file->{'bytes'}; |
| 139 |
} |
| 140 |
|
| 141 |
metadata |
| 142 |
Arguments: $dropbox |
| 143 |
|
| 144 |
Function returns stored metadata for read-only handle, closed write |
| 145 |
handle or after call to "contents" or "putfile". |
| 146 |
|
| 147 |
open $dropbox, '<', '/data/2013.dat' or die $!; |
| 148 |
|
| 149 |
my $meta = metadata($dropbox); |
| 150 |
|
| 151 |
if ($meta->{'bytes'} > 1024) { |
| 152 |
# Do something |
| 153 |
} |
| 154 |
|
| 155 |
putfile |
| 156 |
Arguments: $dropbox, $path, $data |
| 157 |
|
| 158 |
Function is useful for uploading small files (up to 150MB possible) in |
| 159 |
one request (at least two API requests required for chunked upload, used |
| 160 |
in open-write-close sequence). If there is unfinished chunked upload on |
| 161 |
handle, it will be commited. |
| 162 |
|
| 163 |
local $/; |
| 164 |
open my $data, '<', '2012.dat' or die $!; |
| 165 |
|
| 166 |
putfile($dropbox, '/data/2012.dat', <$data>) or die $!; |
| 167 |
|
| 168 |
say 'Uploaded ', metadata($dropbox)->{'bytes'}, ' bytes'; |
| 169 |
|
| 170 |
close $data; |
| 171 |
|
| 172 |
copyfile |
| 173 |
Arguments: $dropbox, $source, $target |
| 174 |
|
| 175 |
Function copies file or directory from one location to another. Metadata |
| 176 |
for copy can be accessed using "metadata" function. |
| 177 |
|
| 178 |
copyfile($dropbox, '/data/2012.dat', '/data/2012.dat.bak') or die $!; |
| 179 |
|
| 180 |
say 'Created backup with revision ', metadata($dropbox)->{'revision'}; |
| 181 |
|
| 182 |
movefile |
| 183 |
Arguments: $dropbox, $source, $target |
| 184 |
|
| 185 |
Function moves file or directory from one location to another. Metadata |
| 186 |
for moved file can be accessed using "metadata" function. |
| 187 |
|
| 188 |
movefile($dropbox, '/data/2012.dat', '/data/2012.dat.bak') or die $!; |
| 189 |
|
| 190 |
say 'Created backup with size ', metadata($dropbox)->{'size'}; |
| 191 |
|
| 192 |
deletefile |
| 193 |
Arguments: $dropbox, $path |
| 194 |
|
| 195 |
Function deletes file or folder at specified path. Metadata for deleted |
| 196 |
item is accessible via "metadata" function. |
| 197 |
|
| 198 |
deletefile($dropbox, '/data/2012.dat.bak') or die $!; |
| 199 |
|
| 200 |
say 'Deleted backup with last modification ', metadata($dropbox)->{'modification'}; |
| 201 |
|
| 202 |
createfolder |
| 203 |
Arguments: $dropbox, $path |
| 204 |
|
| 205 |
Function creates folder at specified path. Metadata for created folder |
| 206 |
is accessible via "metadata" function. |
| 207 |
|
| 208 |
createfolder($dropbox, '/data/backups') or die $!; |
| 209 |
|
| 210 |
say 'Created folder at path ', metadata($dropbox)->{'path'}; |
| 211 |
|
| 212 |
SEE ALSO |
| 213 |
Furl, Furl::HTTP, WebService::Dropbox, Dropbox API |
| 214 |
<https://www.dropbox.com/developers/core/docs> |
| 215 |
|
| 216 |
AUTHOR |
| 217 |
Alexander Nazarov <[email protected]> |
| 218 |
|
| 219 |
COPYRIGHT AND LICENSE |
| 220 |
Copyright 2013-2016 Alexander Nazarov |
| 221 |
|
| 222 |
This program is free software; you can redistribute it and/or modify it |
| 223 |
under the same terms as Perl itself. |
| 224 |
|