Skip to content

Commit 4966d22

Browse files
ThomasMaulThomasMaul
committed
Documentation nearly done, Windows not tested yet, async missing
1 parent d7505d5 commit 4966d22

19 files changed

Lines changed: 6975 additions & 84 deletions

‎Documentation/Classes/FileTransfer_Dropbox.md‎

Lines changed: 319 additions & 19 deletions
Original file line numberDiff line numberDiff line change
@@ -1,27 +1,327 @@
1-
<!-- Type your summary here -->
2-
## Description
1+
<!--Dropbox File Transfer Class (using internally dbxcli) -->
2+
# FileTransfer
33

4-
Uses https://github.com/dropbox/dbxcli
4+
This class is a wrapper for dropbox command line interface, a tool allowing upload, download or file manipulation on Dropbox.
5+
See https://github.com/ThomasMaul/FileTransfer_Class for details
56

6-
We use a command line interface tool from Dropbox.
7-
Dropbox wrote it in language "Go", which allows to compile a single binary which could be embedded in your application and deployed with it (Apache License).
7+
## Example
8+
```4D
9+
var $ftp : cs.FileTransfer_Dropbox
10+
$ftp:=cs.FileTransfer_Dropbox.new()
11+
$source:="/product/4D.dmg"
12+
$target:=Convert path system to POSIX(System folder(Desktop))
13+
$result:=$ftp.download($source; $target)
14+
If ($result.success)
15+
...
16+
End if
17+
```
18+
## Summary
19+
| |
20+
|-|
21+
|[cs.FileTransfer_Dropbox_.new](#new)<p>&nbsp;&nbsp;&nbsp;&nbsp;creates and returns a FileTransfer object allow to access Dropbox.|
22+
|[result parameter](#result-parameter)(#new)<p>&nbsp;&nbsp;&nbsp;&nbsp;All transfer function returns a result object|
23+
|[.upload](#upload)<p>&nbsp;&nbsp;&nbsp;&nbsp;Upload a file to the server.|
24+
|[.getDirectoryListing](#getDirectoryListing)<p>&nbsp;&nbsp;&nbsp;&nbsp;Returns directory listing from remote server.|
25+
|[.createDirectory](#createDirectory)<p>&nbsp;&nbsp;&nbsp;&nbsp;Creates a new directory on remote server.|
26+
|[.deleteDirectory](#deleteDirectory)<p>&nbsp;&nbsp;&nbsp;&nbsp;Deletes a directory on remote server.|
27+
|[.deleteFile](#deleteFile)<p>&nbsp;&nbsp;&nbsp;&nbsp;Deletes a file on remote server.|
28+
|[.renameFile](#renameFile)<p>&nbsp;&nbsp;&nbsp;&nbsp;Renames a file on remote server.|
29+
|[.moveFile](#renameFile)<p>&nbsp;&nbsp;&nbsp;&nbsp;Moves a file on remote server.|
30+
|[.version](#version)<p>&nbsp;&nbsp;&nbsp;&nbsp;returns in result.data version information from Dropbox Command Line Interface Tool|
31+
|[.setPath](#setPath)<p>&nbsp;&nbsp;&nbsp;&nbsp;Allows to use another dbxcli installation.|
32+
|[.setAsyncMode](#setAsyncMode)<p>&nbsp;&nbsp;&nbsp;&nbsp;By default all commands are executed synchronously, meaning the command do not return till execution is completed or a timeout occurred. This allows all command to return the result or execution information..|
33+
|[.stop](#stop)<p>&nbsp;&nbsp;&nbsp;&nbsp;Terminates the execution of a running operation, such as upload or download.|
34+
|[.status](#status)<p>&nbsp;&nbsp;&nbsp;&nbsp;Returns informations about the execution of a running operation.|
35+
|[.wait](#wait)<p>&nbsp;&nbsp;&nbsp;&nbsp;Only useful in combination with setAsyncMode.|
36+
|[.useCallback](#useCallback)<p>&nbsp;&nbsp;&nbsp;&nbsp;Allows to show a progress bar during long running operations.|
837

9-
If Dropbox changes the API, just download their latest release and replace the binary.
38+
-------###### status,s top, wait, set async, still missing ########
1039

11-
For Mac:
12-
The downloaded binary is not signed, so execution on Mac is limited (you need to launch with Control key pressed). To use and deploy we advise to sign it, and then sign/notarize the embedding 4D application.
40+
## new
1341

14-
Setup on customer computer / Both platforms:
15-
To authorize the binary, you need to execute it once through terminal/console and enter:
16-
{path}dbxcli ls
42+
### cs.FileTransfer_Dropbox_.new()
43+
44+
creates and returns a FileTransfer object allow to access Dropbox account.
45+
46+
|Parameter|Type||Description|
47+
|---------|--- |:---:|------|
48+
|result|cs.FileTransfer|<-|New FileTransfer object|
49+
50+
#### Description
51+
52+
The cs.FileTransfer_Dropbox_.new() function creates and returns an object allow to access a Dropbox account for file transfer operations, such as upload or download a document, get directory, as well as create and delete a directory or rename, delete or remove a document.
53+
54+
Internally the class uses dbxcli to access the file server.
55+
56+
```4D
57+
var $ftp : cs.FileTransfer
58+
$ftp:=cs.FileTransfer_Dropbox_.new()
59+
```
60+
61+
## File transfer commands
62+
63+
### result parameter
64+
All function returns a result object
65+
66+
|Name|Type|Description|
67+
|---|---|---|
68+
|success|boolean|false if command failed|
69+
|responseError|Text|error message if command failed|
70+
|data|Text|optional: execution result|
71+
|list|collection|optional: execution result|
72+
73+
## upload
74+
75+
### .upload(source: Text; target: Text) -> result : Object
76+
|Parameter|Type||Description|
77+
|---------|--- |:---:|------|
78+
|source|Text|->|POSIX path to local file|
79+
|target|Text|->|path to remote file|
80+
|result|Object|<-|result object|
81+
82+
#### Description
83+
Upload one file to server.
84+
85+
If file already exists it is overwritten.
86+
If source or target contains spaces, encapsulate with quotes (char(34)).
87+
88+
After uploading a file, the result object returns false or true.
89+
90+
## download
91+
92+
### .download(source: Text; target: Text) -> result : Object
93+
|Parameter|Type||Description|
94+
|---------|--- |:---:|------|
95+
|source|Text|->|path to remote file|
96+
|target|Text|->|POSIX path to local file|
97+
|result|Object|<-|result object|
98+
99+
#### Description
100+
Download one file from server.
101+
102+
If file already exists it is overwritten.
103+
If source or target contains spaces, encapsulate with quotes (char(34)).
104+
105+
After downloading a file, the result object returns false or true.
106+
107+
## getDirectoryListing
108+
109+
### .getDirectoryListing(target: Text) -> result : Object
110+
|Parameter|Type||Description|
111+
|---------|--- |:---:|------|
112+
|target|Text|->|path to remote|
113+
|result|Object|<-|result object|
114+
115+
#### Description
116+
Returns directory listing from remote server.
117+
118+
result.data contains unfiltered answer from server.
119+
result.list contains collection, each representing one file/directory.
120+
121+
The answer is parsed and .list collection contains:
122+
- revision // file revision, for folders "-"
123+
- size // file size, such as "76 KiB" or "315 MiB", for folder "-"
124+
- date // date, such as "1 year ago", "3 days ago", for folders "-"
125+
- path // full path to download/access "/filename.pdf"
126+
127+
128+
## createDirectory
129+
130+
### .createDirectory(target: Text) -> result : Object
131+
|Parameter|Type||Description|
132+
|---------|--- |:---:|------|
133+
|target|Text|->|path to remote|
134+
|result|Object|<-|result object|
135+
136+
#### Description
137+
Creates a new directory on remote server.
138+
139+
## deleteDirectory
140+
141+
### .deleteDirectory(target: Text, force: Boolean) -> result : Object
142+
|Parameter|Type||Description|
143+
|---------|--- |:---:|------|
144+
|target|Text|->|path to remote|
145+
|force|Boolean|->|true to delete none empty folders|
146+
|result|Object|<-|result object|
147+
148+
#### Description
149+
Deletes a directory on remote server.
150+
151+
Note: only empty directories can be deleted. Delete all files before you delete the directory or pass true as second parameter (default false)
152+
153+
## deleteFile
154+
155+
### .deleteFile(target: Text) -> result : Object
156+
|Parameter|Type||Description|
157+
|---------|--- |:---:|------|
158+
|target|Text|->|path to remote|
159+
|result|Object|<-|result object|
160+
161+
#### Description
162+
Deletes a file on remote server.
163+
164+
## renameFile
165+
166+
### .renameFile(source: Text; target: Text) -> result : Object
167+
|Parameter|Type||Description|
168+
|---------|--- |:---:|------|
169+
|source|Text|->|path to remote file|
170+
|target|Text|->|path to renamed remote file|
171+
|result|Object|<-|result object|
172+
173+
#### Description
174+
Deletes a file on remote server.
175+
176+
## moveFile
177+
178+
### .moveFile(source: Text; target: Text) -> result : Object
179+
|Parameter|Type||Description|
180+
|---------|--- |:---:|------|
181+
|source|Text|->|path to remote file|
182+
|target|Text|->|path to renamed remote file|
183+
|result|Object|<-|result object|
184+
185+
#### Description
186+
Moves a file on remote server to another directory (and/or rename it)
187+
188+
189+
## Settings commands
190+
191+
## .version()
192+
193+
###.version() -> result : object
194+
|Parameter|Type||Description|
195+
|---------|--- |:---:|------|
196+
|result|Object|<-|result object|
197+
198+
#### Description
199+
returns in result.data version information from cURL.
200+
201+
Example:
202+
dbxcli version: v3.0.0
203+
SDK version: 5.4.0
204+
Spec version: 097e9ba
205+
206+
207+
## setPath
208+
209+
### .setPath(Path: Text)
210+
|Parameter|Type||Description|
211+
|---------|--- |:---:|------|
212+
|Path|Text|->|Path to local dbxcli installation|
213+
214+
#### Description
215+
Allows to use another dbxcli installation.
216+
217+
Precompiled versions for Mac and Windows can be downloaded from:
218+
[dbxcli](https://github.com/dropbox/dbxcli)
219+
220+
221+
## setAsyncMode
222+
223+
### .setAsyncMode(async:Boolean)
224+
|Parameter|Type||Description|
225+
|---------|--- |:---:|------|
226+
|async|Boolean|->|asynchronous execution|
227+
228+
#### Description
229+
By default all commands are executed synchronously, meaning the command do not return till execution is completed or a timeout occurred. This allows all command to return the result or execution information.
230+
231+
If Asynchronous mode is enabled, all commands returns immediately, not waiting for execution. The result will not include useful informations.
232+
233+
Useful in combination with .stop(), .status() and .wait() calls or with useCallback.
234+
235+
Note: asynchronous only works if the 4D progress continues to run. As long the 4D process is alive, open commands will continue to execute. If the 4D process terminals, all still running FTP operations will end.
236+
237+
## stop
238+
239+
### .stop()
240+
241+
#### Description
242+
Terminates the execution of a running operation, such as upload or download. Only useful in combination with setAsyncMode.
243+
244+
## status
245+
246+
### .status()
247+
248+
#### Description
249+
Returns informations about the execution of a running operation, such as upload or download. Only useful in combination with setAsyncMode.
250+
251+
Return object contains:
252+
253+
|Name|Type|Description|
254+
|---|---|---|
255+
|terminated|boolean|true if command finished execution|
256+
|responseError|Text|error message if command failed|
257+
|response|Text|message if command succeeded|
258+
|exitCode|Text|exit code returned by dbxcli|
259+
|errors|collection|optional: execution errors received by 4D|
260+
261+
## wait
262+
263+
### .wait(seconds:Integer)
264+
|Parameter|Type||Description|
265+
|---------|--- |:---:|------|
266+
|seconds|Integer|->|max time in seconds|
267+
268+
#### Description
269+
Only useful in combination with setAsyncMode.
270+
If upload/download commands are executed in a 4D form or another 4D worker, execution will automatically continue in background.
271+
If they are executed in the current 4D process and you want to loop for poll for results, use .wait(1) instead of Delay Process.
272+
The command returns after given wait time or before if execution is finished.
273+
274+
275+
## useCallback
276+
277+
### .useCallback(callback: 4D.Function; ID: Text)
278+
|Parameter|Type||Description|
279+
|---------|--- |:---:|------|
280+
|callback|4D.Function|->|4d function to call during progress|
281+
|ID|Text|->|text to pass to callback method to identify job|
282+
283+
#### Description
284+
Allows to show a progress bar during long running operations or to get informed when command execution is complete.
285+
286+
The callback method is called whenever a new progress message is available from dbxcli and get's 3 parameter passed. The given ID, the progress text and the completeness ratio from 0-100%.
287+
288+
Note: only useable on Windows.
289+
290+
#### Example
291+
292+
```4D
293+
$ftp.useCallback(Formula(ProgressCallback); "Download 4D.dmg")
294+
$ftp.setAsyncMode(True)
295+
$result:=$ftp.download($source; $target)
296+
Repeat
297+
$ftp.wait(1) // needed while our process is running
298+
// wait is not needed if a form would be open or if a worker would handle the job
299+
$status:=$ftp.status()
300+
Until (Bool($status.terminated))
301+
```
302+
303+
Method ProgressCallback
304+
305+
```4D
306+
#DECLARE($ID : Text; $message : Text; $value : Integer)
307+
// called from cs.FileTransfer if callback is set via .useCallback()
308+
309+
// $ID is set through code - $message comes from curl
310+
311+
var ProgressBarID : Integer
312+
313+
If (ProgressBarID=0)
314+
ProgressBarID:=Progress New
315+
Progress SET MESSAGE(ProgressBarID; $ID)
316+
End if
317+
318+
If ($value=100)
319+
Progress QUIT(ProgressBarID)
320+
ProgressBarID:=0
321+
Else
322+
Progress SET PROGRESS(ProgressBarID; $value/100)
323+
End if
324+
```
17325

18-
It will ask for access:
19-
1. Go to https://www.dropbox.com/1/oauth2/authorize?client_id=07o23gulcj8qi69&response_type=code&state=state
20-
2. Click "Allow" (you might have to log in first).
21-
3. Copy the authorization code.
22-
Enter the authorization code here:
23-
xxxx
24326

25-
This needs to be done manually once.
26327

27-
codesign --force --sign "Developer ID Application: 4D Deutschland GmbH" /Users/thomas/Desktop/dbxcli

‎Documentation/Classes/FileTransfer_curl.md‎

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -19,7 +19,7 @@ End if
1919
## Summary
2020
| |
2121
|-|
22-
|[cs.FileTransfer.new](#new)<p>&nbsp;&nbsp;&nbsp;&nbsp;creates and returns a FileTransfer object allow to access (s)FTP(s) Servers.|
22+
|[cs.FileTransfer_curl_.new](#new)<p>&nbsp;&nbsp;&nbsp;&nbsp;creates and returns a FileTransfer object allow to access (s)FTP(s) Servers.|
2323
|[result parameter](#result-parameter)(#new)<p>&nbsp;&nbsp;&nbsp;&nbsp;All transfer function returns a result object|
2424
|[.upload](#upload)<p>&nbsp;&nbsp;&nbsp;&nbsp;Upload one or several files to server.|
2525
|[.getDirectoryListing](#getDirectoryListing)<p>&nbsp;&nbsp;&nbsp;&nbsp;Returns directory listing from remote server.|
@@ -40,15 +40,15 @@ End if
4040
|[.enableProgressData](#enableProgressData)<p>&nbsp;&nbsp;&nbsp;&nbsp;If enabled, result.data will include progress information text.|
4141
|[.setAsyncMode](#setAsyncMode)<p>&nbsp;&nbsp;&nbsp;&nbsp;By default all commands are executed synchronously, meaning the command do not return till execution is completed or a timeout occurred. This allows all command to return the result or execution information..|
4242
|[.stop](#stop)<p>&nbsp;&nbsp;&nbsp;&nbsp;Terminates the execution of a running operation, such as upload or download.|
43-
|[.status](#status)<p>&nbsp;&nbsp;&nbsp;&nbsp;RReturns informations about the execution of a running operation.|
43+
|[.status](#status)<p>&nbsp;&nbsp;&nbsp;&nbsp;Returns informations about the execution of a running operation.|
4444
|[.wait](#wait)<p>&nbsp;&nbsp;&nbsp;&nbsp;Only useful in combination with setAsyncMode.|
4545
|[.useCallback](#useCallback)<p>&nbsp;&nbsp;&nbsp;&nbsp;Allows to show a progress bar during long running operations.|
4646

4747

4848

4949
## new
5050

51-
### cs.FileTransfer.new(url: Text; user: Text; password: Text; protocol:Text)
51+
### cs.FileTransfer_curl_.new(url: Text; user: Text; password: Text; protocol:Text)
5252

5353
creates and returns a FileTransfer object allow to access (s)FTP(s) Servers.
5454

‎Project/Sources/Classes/FileTransfer_Dropbox.4dm‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -5,6 +5,8 @@ Class constructor()
55
This:C1470._Path:=Convert path system to POSIX:C1106($path)
66
Else
77
This:C1470._return:=Char:C90(10) //Char(13)+Char(10)
8+
$path:=Get 4D folder:C485(Current resources folder:K5:16)+"Dropbox"+Folder separator:K24:12+"dbxcli.exe"
9+
This:C1470._Path:=Convert path system to POSIX:C1106($path)
810
End if
911

1012

‎Project/Sources/Methods/test_dropbox.4dm‎

Lines changed: 9 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -4,6 +4,15 @@ $ftp:=cs:C1710.FileTransfer_Dropbox.new()
44
//$ftp.setPath(" /Users/thomas/Desktop/dbxcli")
55

66

7+
If (False:C215)
8+
$source:="/"
9+
$result:=$ftp.version($source)
10+
If ($result.success)
11+
$answer:=$result.data
12+
End if
13+
End if
14+
15+
716
If (False:C215)
817
$source:="/"
918
$result:=$ftp.getDirectoryListing($source)

0 commit comments

Comments
 (0)