Debian Codegraph @

README

raw ◀ ▶
Source reconstructed at patch state 0 of 1 — not the installed (fully patched) source.
1 Debian patch touch this file
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