On This Page
Legend:
Library
Module
Module type
Parameter
Class
Class type
Library
Module
Module type
Parameter
Class
Class type
package dropbox
Create a concrete Dropbox API implementation given a client one. Note that several instances have been instantiated for you in the Dropbox_* modules so you generally do not have to call this yourself.
Parameters
module Client : Cohttp_lwt.S.ClientSignature
val session : OAuth2.token -> tval token : t -> OAuth2.tokenThe token of the current session.
type name_details = Dropbox_t.name_details = {familiar_name : string;(*The locale-dependent familiar name for the user.
*)given_name : string;(*The user's given name.
*)surname : string;(*The user's surname.
*)
}type team = Dropbox_t.team = {name : string;(*The name of the team the user belongs to.
*)team_id : int;(*The ID of the team the user belongs to.
*)
}type quota_info = Dropbox_t.quota_info = {quota : int;(*The user's used quota in shared folders (bytes).
*)normal : int;(*The user's total quota allocation (bytes).
*)
}type info = Dropbox_t.info = {uid : int;(*The user's unique Dropbox ID.
*)display_name : string;(*The user's display name.
*)email_verified : bool;name_details : name_details;referral_link : Uri.t;country : string;(*The user's two-letter country code, if available.
*)locale : string;(*Locale preference set by the user (e.g. en-us).
*)is_paired : bool;(*If true, there is a paired account associated with this user.
*)team : team option;(*If the user belongs to a team, contains team information.
*)quota_info : quota_info;
}type photo_info = Dropbox_json.Photo.info = {time_taken : Date.t option;(*The creation time of the photo
*)lat_long : (float * float) option;(*The GPS coordinates of the photo, if any.
*)
}type video_info = Dropbox_json.Video.info = {time_taken : Date.t option;(*The creation time of the video
*)duration : float option;(*The video length in ms
*)lat_long : (float * float) option;(*The GPS coordinates of the video, if any.
*)
}type user = Dropbox_t.user = {uid : int;(*The user's unique Dropbox ID
*)display_name : string;(*The name of the user
*)same_team : bool;(*Whether the user is on the same team as the linked account
*)member_id : string;(*If this endpoint is called by a Dropbox for Business app and the user is on that team, a member_id field will also be present
*)
}type user_info = Dropbox_t.user_info = {user : user;access_type : string;active : bool;(*Whether the user is active in a shared folder
*)
}type metadata = Dropbox_t.metadata = {size : string;(*A human-readable description of the file size (translated by locale).
*)bytes : int;(*The file size in bytes.
*)mime_type : string;path : string;(*The canonical path to the file or folder.
*)is_dir : bool;(*Whether the given entry is a folder or not.
*)is_deleted : bool;(*Whether the given entry is deleted. (Only interesting if deleted files are returned.)
*)rev : string;(*A unique identifier for the current revision of a file. This field is the same
*)revas elsewhere in the API and can be used to detect changes and avoid conflicts.hash : string;(*A folder's hash is useful for indicating changes to the folder's contents in later calls to
*)metadata. This is roughly the folder equivalent to a file'srev. (Is""for a file.)thumb_exists : bool;photo_info : [ `None | `Pending | `Some of photo_info ];(*Only returned when the include_media_info parameter is true and the file is an image. A dictionary that includes the creation time (time_taken) and the GPS coordinates (lat_long).
*)video_info : [ `None | `Pending | `Some of video_info ];(*Only returned when the include_media_info parameter is true and the file is a video. A dictionary that includes the creation time (time_taken), the GPS coordinates (lat_long), and the length of the video in milliseconds (duration).
*)icon : string;modified : Date.t option;(*The last time the file was modified on Dropbox (not included for the root folder).
*)client_mtime : Date.t option;(*For files, this is the modification time set by the desktop client when the file was added to Dropbox. Since this time is not verified (the Dropbox server stores whatever the desktop client sends up), this should only be used for display purposes (such as sorting) and not, for example, to determine if a file has changed or not.
*)root : [ `Dropbox | `App_folder ];(*The root or top-level folder depending on your access level. All paths returned are relative to this root level.
*)contents : metadata list;(*For folders, contents is the list of the metadata of the files contained in this folder. Return nothing if the folder is empty.
*)read_only : bool;(*For shared folders, this field specifies whether the user has read-only access to the folder. For files within a shared folder, this specifies the read-only status of the parent shared folder.
*)modifier : user option;(*For files within a shared folder, this field specifies which user last modified this file. If the modifying user no longer exists, the value will be null.
*)
}type delta = {entries : (string * metadata option) list;(*A list of "delta entries". Each delta entry is a 2-item list of one of the following forms:
(path, Some metadata)- Indicates that there is a file/folder at the given path. You should add the entry to your local state. The metadata value is the same as what would be returned by themetadatacall, except folder metadata doesn't have hash or contents fields. To correctly process delta entries:- If the new entry includes parent folders that don't yet exist in your local state, create those parent folders in your local state.
- If the new entry is a file, replace whatever your local state has at path with the new entry.
- If the new entry is a folder, check what your local state has at <path>. If it's a file, replace it with the new entry. If it's a folder, apply the new <metadata> to the folder, but don't modify the folder's children. If your local state doesn't yet include this path, create it as a folder.
- If the new entry is a folder with the read-only field set to true, apply the read-only permission recursively to all files within the shared folder.
(path, None)- Indicates that there is no file/folder at the given path. To update your local state to match, anything at path and all its children should be deleted. Deleting a folder in your Dropbox will sometimes send down a single deleted entry for that folder, and sometimes separate entries for the folder and all child paths. If your local state doesn't have anything at path, ignore this entry.Note: Dropbox treats file names in a case-insensitive but case-preserving way. To facilitate this, the
*)pathvalues above are lower-cased versions of the actual path. The last path component of themetadatavalue will be case-preserved.reset : bool;(*If
*)true, clear your local state before processing the delta entries. reset is always true on the initial call todelta(i.e., when no cursor is passed in). Otherwise, it is true in rare situations, such as after server or account maintenance, or if a user deletes their app folder.cursor : cursor;(*Encodes the latest information that has been returned. On the next call to
*)delta, pass in this value.has_more : bool;(*If
*)true, then there are more entries available; you can calldeltaagain immediately to retrieve those entries. Iffalse, then wait for at least five minutes (preferably longer) before checking again.
}type longpoll_delta = Dropbox_t.longpoll_delta = {changes : bool;(*Incidate whether new changes are available.
*)backoff : int option;(*If present, it indicates how many seconds your code should wait before calling
*)longpoll_deltaagain.
}type copy_ref = Dropbox_t.copy_ref = {copy_ref : string;(*A reference string to the specified file
*)expires : Date.t;(*The link's expiration date in Dropbox's usual date format. All links are currently set to expire far enough in the future so that expiration is effectively not an issue.
*)
}val get_file :
t ->
?rev:string ->
?start:int ->
?len:int ->
string ->
(metadata * string Lwt_stream.t) option Lwt.tget_file t name return the metadata for the file and a stream of its content. None indicates that the file does not exists.
val metadata :
t ->
?file_limit:int ->
?hash:string ->
?list:bool ->
?include_deleted:bool ->
?rev:string ->
?locale:string ->
?include_media_info:bool ->
?include_membership:bool ->
string ->
metadata option Lwt.tmetadata t path return the metadata for the file or the folder path. A return value of None means that the file does not exists.
val delta :
?cursor:cursor ->
?locale:string ->
?path_prefix:string ->
?include_media_info:bool ->
t ->
delta Lwt.tdelta t return the delta. This is a way of letting you keep up with changes to files and folders in a user's Dropbox. Deltas are instructions on how to update your local state to match the server's state.
latest_cursor t return a cursor (as would be returned by delta when has_more is false).
val longpoll_delta : t -> ?timeout:int -> cursor -> longpoll_delta Lwt.tlongpoll_delta t cursor blocks the connection until changes are available or a timeout occurs. In both case, a value r will be returned with r.changes indicating whether new changes are available. If this is the case, you should call delta to retrieve the changes. If this value is false, it means the call to longpoll_delta timed out. In conjunction with delta, this call gives you a low-latency way to monitor an account for file changes.
The cursor is a crusor returned from a call to delta. Note that a cursor returned from a call to delta with include_media_info=true is incompatible with longpoll_delta and an error will be returned.
revisions t name Return the metadata for the previous revisions of a file (in a list of metadata). Only revisions up to thirty days old are available. A return value of None means that the file does not exist.
restore t rev name Restores the file path name to the previous revision rev. Return the metadata of the restored file. A return value of None means that there is no file path name with such rev.
If the revision is not well formed or non-existing, the function will fail throwing Error Dropbox.Invalid_arg.
val search :
t ->
?file_limit:int ->
?include_deleted:bool ->
?locale:string ->
?include_membership:bool ->
?fn:string ->
string ->
metadata list Lwt.tsearch query return the list containing the metadata for all files and folders whose filename contains the given search string as a substring.
copy_ref t fname creates and return a copy_ref to the file or directory fname. A return value of None means that fname does not exist. copy_ref can be used to copy that file to another user's Dropbox by passing it in as the from_copy_ref parameter on copy. All links are currently set to expire far enough in the future so that expiration is effectively not an issue.
The visibility of a shared_link.
shares t path return a shared_link to a file or folder. A return value of None means that the file does not exist.
type link = Dropbox_t.link = {url : string;(*The link URL to the file
*)expires : Date.t;(*The link's expiration date
*)
}media t path return a link directly to a file. A return value of None means that the file does not exist.
Similar to shares. The difference is that this bypasses the Dropbox webserver, used to provide a preview of the file, so that you can effectively stream the contents of your media. This URL should not be used to display content directly in the browser.
Note that the media link expires after four hours, allotting enough time to stream files, but not enough to leave a connection open indefinitely.
shared_folder t Return the metadata about a specific shared folder or the list of all shared folders the authenticated user has access to if shared_folder_id is not specified.
val files_put :
t ->
?locale:string ->
?overwrite:bool ->
?parent_rev:string ->
?autorename:bool ->
string ->
[ `String of string
| `Strings of string list
| `Stream of string Lwt_stream.t
| `Stream_len of string Lwt_stream.t * int ] ->
metadata Lwt.tfiles_put t path content upload the content under the path (the full path is created by Dropbox if necessary) and return the metadata of the uploaded file. The path should not point to a folder.
type chunked_upload = {id : chunked_upload_id;(*The ID of the in-progress upload.
*)ofs : int;(*The byte offset for the next chunk.
*)expires : Date.t;(*The time limit to finish the upload.
*)
}val chunked_upload :
t ->
?id:chunked_upload_id ->
?ofs:int ->
[ `String of string
| `Strings of string list
| `Stream of string Lwt_stream.t ] ->
chunked_upload Lwt.tchunked_upload chunk upload the chunk and return the ID and offset for the subsequent upload of the same file. This allows to upload large files to Dropbox (larger than 150Mb which is the limit for files_put). Chunks can be any size up to 150 MB. A typical chunk is 4 MB. Using large chunks will mean fewer calls to chunked_upload and faster overall throughput. However, whenever a transfer is interrupted, you will have to resume at the beginning of the last chunk, so it is often safer to use smaller chunks.
val commit_chunked_upload :
t ->
?locale:string ->
?overwrite:bool ->
?parent_rev:string ->
?autorename:bool ->
chunked_upload_id ->
string ->
metadata Lwt.tcommit_chunked_upload upload_id path complete the upload initiated by chunked_upload. Save the uploaded data under path and return the metadata for the uploaded file using chunked_upload. upload_id is used to identify the chunked upload session you'd like to commit.
val thumbnails :
t ->
?format:[ `Jpeg | `Png | `Bmp ] ->
?size:[ `Xs | `S | `M | `L | `Xl ] ->
string ->
(metadata * string Lwt_stream.t) option Lwt.tthumbnails t path return the metadata for the thumbnails of path and a stream of the content of the thumbnails. None indicates that the path does not exists or is not an image.
Note that This method currently supports files with the following file extensions: .jpg, .jpeg, .png, .tiff, .tif, .gif, .bmp (it also work on .avi, .mp4, .flv). And photos larger than 20MB in size won't be converted to a thumbnail.
val previews :
t ->
?rev:string ->
string ->
(string * string * string Lwt_stream.t) option Lwt.tpreviews t path Returns a 3-uple which contains the Content-Type whose values are "application/pdf" or "text/html", the Original-Content-Length which is the size of the preview data and the stream of its content. Return None when the file wasn't found the specified path, or wasn't found at the specified rev.
Note previews are only generated for the files with the following extensions: .doc, .docx, .docm, .ppt, .pps, .ppsx, .ppsm, .pptx, .pptm, .xls, .xlsx, .xlsm, .rtf.
File Operations
val copy :
t ->
?locale:string ->
?root:root ->
[ `From_path of string | `From_copy_ref of string ] ->
string ->
[ `Some of metadata | `None | `Invalid of string | `Too_many_files ] Lwt.tcopy t source to_path copy the file or folder. The source can either be:
`From_path: specifies the file or folder to be copied from relative to the root;`From_copy_ref: specifies acopy_refgenerated from a previouscopy_refcall.
The second argument to_path specifies the destination path, including the new name for the file or folder, relative to root. If everything goes well, the metadata of the copy is returned.
`Nonemeans that thesourcewas not found.`Invalidis returned when there is already a file at the given destination, or one is trying to copy a shared folder`Too_many_filesis returned when too many files would be involved in the operation for it to complete successfully. The limit is currently 10,000 files and folders.
val create_folder :
t ->
?locale:string ->
?root:root ->
string ->
[ `Some of metadata | `Invalid of string ] Lwt.tcreate_folder path create the folder path (interpreted relatively to root) and return the metadata for the new folder. Return `Invalid if path already exists.
val delete :
t ->
?locale:string ->
?root:root ->
string ->
[ `Some of metadata | `None | `Too_many_files ] Lwt.tdelete path delete the file or folder path and return the metadata of it. Return `None if path does not exist and `Too_many_files when too many files would be involved in the operation for it to complete successfully. The limit is currently 10,000 files and folders.
val move :
t ->
?locale:string ->
?root:root ->
string ->
string ->
[ `Some of metadata | `None | `Invalid of string | `Too_many_files ] Lwt.tmove from_path to_path move the file or folder from_path to to_path. If everything goes well, the metadata of the moved file is returned.
`Nonemeans that thefrom_pathdoes not exist.`Invalidis returned when there is already a file at the given destination, or one tries to move a shared folder into a shared folder.`Too_many_filesis returned when too many files would be involved in the operation for it to complete successfully. The limit is currently 10,000 files and folders.
On This Page