1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 221 222 223 224
|
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
<https://www.dropbox.com/developers/core/docs#metadata>. $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
<https://www.dropbox.com/developers/core/docs>
AUTHOR
Alexander Nazarov <nfokz@cpan.org>
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.
|