Racket Dropbox SDK

5.3.2.1

Racket Dropbox SDK

(require "dropbox.rkt")

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

1 OAuth authentication

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

; 1) Set the app's key and key secret.
;    These will be used when obtaining request and access tokens.
(set!-APP-KEY "3ysfqt0flcbex2t")
(set!-APP-SECRET "hia6gkco347zczj")

; 2) Get a request token.
;    The obtained request token and token secret are automatically saved
;    internally and used to generate the authorization url and obtain the
;    access token.
(obtain-request-token)

; 3) Direct the user to a browser pointed at the authorization url returned
;    by get-authorization-url.
(get-authorization-url)

; 4) 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
(obtain-request-token) →
string? string?

Step 1 of OAuth authentication. Gets a request token and request token secret and saves it internally. Also returns the obtained request token and request token secret.

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]) → jsexpr?
  local-filepath : string?
  remote-filepath : string?
  locale : string? = "en"
  overwrite? : (or/c "true" "false") = "true"
  parent-rev : string? = ""

Uploads a file less than 150MB. Use upload-large-file for larger files. Both local-filepath and remote-filepath must be files and not directories. When parent-rev is specified, the file will be replaced only if the latest version matches. Otherwise, the file will be renamed.

procedure
(upload-large-file local-filepath
remote-filepath
[ #:locale locale
#:overwrite? overwrite?
#:parent-rev parent-rev
#:chunk-size chunk-size
#:verbose? verbose?
#:resume? resume?
#:resume-id resume-id
#:resume-offset resume-offset])
→ (or/c jsexpr? thunk?)
  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
  resume? : boolean? = #f
  resume-id : string? = ""
  resume-offset : number? = 0

Uploads a file in chunks. Default chunk-size is 4MB. Use this function to upload files greater than 150MB. 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. Alternatively, an upload can be manually resumed by setting resumed? to #t and giving the appropriate resume-id and resume-offset (set verbose? to #t to get this information).

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.

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