Racket Dropbox SDK

7.7

top ← prev up next →

Racket Dropbox SDK

Stephen Chang <stchang@racket-lang.org>

(require dropbox)

package: dropbox

Dropbox SDK for Racket. Requires Racket version 5.3.1.12 or later.

1 OAuth authentication

A Dropbox app must first get authorization to access a user’s files. This is done in several steps.

; 1) Set the app's key, secret, and access type.
;    "app_folder" access gives limited access while "dropbox" access
;    allows access to the user's entire dropbox account. The access type
;    must match the access level of the app.
;    These values will be used in subsequent steps.
(set!-APP-KEY "3ysfqt0flcbex2t")
(set!-APP-SECRET "hia6gkco347zczj")
(set!-ACCESS-TYPE "app_folder")

; 2) Direct the user to a browser pointed at the authorization url returned
;    by get-authorization-url. This can only be done if the app key and
;    app secret are set.
(get-authorization-url)

; 3) Get an access token.
;    This can only be done after the user grants access at the authorization
;    url returned by get-authorization-url. The obtained access token and
;    token secret are automatically saved internally and sent as
;    authorization in the header of subsequent API calls.
(obtain-access-token)

procedure
(set!-APP-KEY akey) → void?
akey : string?

Sets the app key for your Dropbox app. App keys and secrets can be obtained here.

procedure
(set!-APP-SECRET asecret) → void?
asecret : string?

Sets the app secret for your Dropbox app. App keys and secrets can be obtained here.

procedure
(set!-ACCESS-TYPE atype) → void?
atype : (or/c "app_folder" "dropbox")

Sets the access level type for your Dropbox app. This is set when creating the app here. Possible values are "app_folder" (limited access) or "dropbox" (full access). More info on access levels here.

procedure
(get-authorization-url [ #:locale locale
#:callback callback-url]) → string?
locale : string? = "en"
callback-url : string?
= "https://www.dropbox.com/1/oauth/authorize"

Step 2 of OAuth authentication. Returns a url in string form. Direct the app user to this page to grant the app access to the user’s files. Takes an optional locale parameter and callback url to display after the user grants access.

procedure
(obtain-access-token) →
string? string?

Step 3 of OAuth authentication. Gets an access token and access token secret and saves it internally. These will be automatically used in the authorization on subsequent API calls. Also returns the obtained access token and access token secret.

2 Account info

procedure
(get-account-info [#:locale locale]) → jsexpr?
locale : string? = "en"

Returns information about the user’s account as a jsexpr.

3 Uploading, downloading, and metadata

procedure
(get-metadata path
[ #:file-limit file-limit
#:hash hash
#:list lst
#:inc-del inc-del
#:rev rev
#:locale locale]) → jsexpr?
  path : string?
  file-limit : number? = 10000
  hash : string? = ""
  lst : (or/c "true" "false") = "true"
  inc-del : (or/c "true" "false") = "false"
  rev : string? = ""
  locale : string? = "en"

Returns metadata of specified remote file or folder as a jsexpr. See here for more info about metadata fields.

procedure
(upload-file
local-filepath
remote-filepath
[ #:locale locale
#:overwrite? overwrite?
#:parent-rev parent-rev
#:chunk-size chunk-size
#:verbose? verbose?
#:return-resume-info-on-error? return-resume-info-on-error?
#:resume? resume?
#:resume-id resume-id
#:resume-offset resume-offset])
→ (or/c jsexpr? thunk? (list string? number?))
  local-filepath : string?
  remote-filepath : string?
  locale : string? = "en"
  overwrite? : (or/c "true" "false") = "true"
  parent-rev : string? = ""
  chunk-size : number? = 4194304
  verbose? : boolean? = #f
  return-resume-info-on-error? : boolean? = #f
  resume? : boolean? = #f
  resume-id : string? = ""
  resume-offset : number? = 0

Uploads a file. Both local-filepath and remote-filepath must be files and not directories. When parent-rev is specified, it will be replaced only if latest version matches the upload; otherwise, the remote file will be renamed first. The file is uploaded in chunks. Default chunk-size is 4MB. When verbose? is #t, the progress is printed as each chunk completes.

If an upload is interrupted due to network outage, a thunk is returned that resumes the upload when evaluated, unless return-resume-info-on-error? is #t, in which case a list containing a resume-id string and resume-offset number is returned. To manually resume an upload, set resumed? to #t and give the appropriate resume-id and resume-offset.

When the upload completes successfully, a jsexpr is returned with the metadata of the uploaded file.

procedure
(download-file remote-filepath
local-filepath
[ #:rev rev
#:exists exists]) → void?
  remote-filepath : string?
  local-filepath : string?
  rev : string? = ""
   exists :
(or/c 'error 'append 'update 'can-update
      'replace 'truncate
      'must-truncate 'truncate/replace)
= 'error

Downloads specified file to specified local path. The exists parameter is the same as in open-output-file.

procedure
(get-delta [#:cursor cursor #:locale locale]) → jsexpr?
cursor : string? = ""
locale : string? = "en"

Returns a jsexpr with delta information between a user’s local state and the server’s state. More information here.

procedure
(get-revisions filepath
[ #:rev-limit rev-limit
#:locale locale]) → jsexpr?
  filepath : string?
  rev-limit : number? = 10
  locale : string? = "en"

Returns revision information about specified file as a jsexpr.

procedure
(restore-file filepath rev [#:locale locale]) → jsexpr?
  filepath : string?
  rev : string?
  locale : string? = "en"

Restore specified file to specified revision.

procedure
(search remote-dir
query
[ #:file-limit file-limit
#:inc-del inc-del
#:locale locale]) → jsexpr?
  remote-dir : string?
  query : string?
  file-limit : number? = 1000
  inc-del : (or/c "true" "false") = "false"
  locale : string? = "en"

Searches speficied directory for paths containing the specified query. Subdirectories are recursively searched. Results are returned as a jsexpr.

procedure
(get-share-url remote-path
[ #:locale locale
#:short-url short-url]) → jsexpr?
  remote-path : string?
  locale : string? = "en"
  short-url : (or/c "true" "false") = "true"

Publicly shares the specified path (ie file or directory) and at the returned url in a jsexpr. When short-url is #t, a shortened url is used.

procedure
(get-media-url remote-file [#:locale locale]) → jsexpr?
remote-file : string?
locale : string? = "en"

Publicly shares the specified file at the returned url in a jsexpr. This function is better for streaming media because it bypasses the Dropbox webserver.

procedure
(get-image-thumbnail remote-file
local-file
[ #:format format
#:size size
#:exists exists]) → void?
  remote-file : string?
  local-file : string?
  format : (or/c "jpeg" "png") = "jpeg"
  size : (or/c "xs" "s" "m" "l" "xl") = "s"
   exists :
(or/c 'error 'append 'update 'can-update
      'replace 'truncate
      'must-truncate 'truncate/replace)
= 'error

Downloads a thumbnail for the specified image file to the specified local file. Image file must be jpg or png. The exists parameter is the same as in open-output-file.

4 File Operations: Copy, delete, move

procedure
(get-copy-ref remote-file) → jsexpr?
remote-file : string?

Returns a copy-ref in a jsexpr. Can be used with copy. More info here.

procedure
(copy from
to
[ #:locale locale
#:copy-ref copy-ref]) → jsexpr?
  from : string?
  to : string?
  locale : string? = "en"
  copy-ref : (or/c #f string?) = #f

Copies specified file or folder to specified destination. When a non-false copy-ref is specified, it is used instead of the from path.

procedure
(create-folder path [#:locale locale]) → jsexpr?
path : string?
locale : string? = "en"

Tries to create the specified folder. If successful, returns a jsexpr with the folder’s metadata. Otherwise (ie, the folder already exists), the jsexpr contains the error.

procedure
(delete path [#:locale locale]) → jsexpr?
path : string?
locale : string? = "en"

Deletes the specified file or folder. Returns metadata for deleted file or folder as a jsexpr.

procedure
(move from to [#:locale locale]) → jsexpr?
  from : string?
  to : string?
  locale : string? = "en"

Moves specified file or folder to specified destination. Returns metadata for moved file or folder in a jsexpr.

procedure
(exists? dirname filename) → boolean?
dirname : string?
filename : string?

Indicates whether specified remote file exists in specified directory. Uses a search query.

top ← prev up next →

1	OAuth authentication
2	Account info
3	Uploading, downloading, and metadata
4	File Operations: Copy, delete, move