573 lines
19 KiB
Plaintext
573 lines
19 KiB
Plaintext
namespace sharing
|
|
|
|
import common
|
|
import files
|
|
import users
|
|
|
|
alias Id = files.Id
|
|
alias Path = files.Path
|
|
alias Rev = files.Rev
|
|
alias TeamInfo = users.Team
|
|
alias ReadPath = files.ReadPath
|
|
|
|
#
|
|
# Link Metadata definitions and route
|
|
#
|
|
|
|
struct GetSharedLinkMetadataArg
|
|
url String
|
|
"URL of the shared link."
|
|
path Path?
|
|
"If the shared link is to a folder, this parameter can be used to retrieve the metadata for
|
|
a specific file or sub-folder in this folder. A relative path should be used."
|
|
link_password String?
|
|
"If the shared link has a password, this parameter can be used."
|
|
|
|
example default
|
|
url = "https://www.dropbox.com/s/2sn712vy1ovegw8/Prime_Numbers.txt?dl=0"
|
|
path = "/Prime_Numbers.txt"
|
|
|
|
union_closed RequestedVisibility
|
|
"The access permission that can be requested by the caller for the shared link.
|
|
Note that the final resolved visibility of the shared link takes into account other aspects,
|
|
such as team and shared folder settings.
|
|
Check the :type:`ResolvedVisibility` for more info on the possible resolved visibility values
|
|
of shared links."
|
|
|
|
public
|
|
"Anyone who has received the link can access it. No login required."
|
|
team_only
|
|
"Only members of the same team can
|
|
access the link. Login is required."
|
|
password
|
|
"A link-specific password is required to access the
|
|
link. Login is not required."
|
|
|
|
union ResolvedVisibility extends RequestedVisibility
|
|
"The actual access permissions values of shared links after taking into account user
|
|
preferences and the team and shared folder settings.
|
|
Check the :type:`RequestedVisibility` for more info on the possible visibility values
|
|
that can be set by the shared link's owner."
|
|
|
|
team_and_password
|
|
"Only members of the same team who
|
|
have the link-specific password can access the link. Login is required."
|
|
shared_folder_only
|
|
"Only members of the shared folder containing the linked file
|
|
can access the link. Login is required."
|
|
|
|
union SharedLinkAccessFailureReason
|
|
login_required
|
|
"User is not logged in."
|
|
email_verify_required
|
|
"User's email is not verified."
|
|
password_required
|
|
"The link is password protected."
|
|
team_only
|
|
"Access is allowed for team members only."
|
|
owner_only
|
|
"Access is allowed for the shared link's owner only."
|
|
|
|
struct LinkPermissions
|
|
resolved_visibility ResolvedVisibility?
|
|
"The current visibility of the link after considering the shared links policies of the
|
|
the team (in case the link's owner is part of a team) and the shared folder (in case the
|
|
linked file is part of a shared folder). This field is shown only if the caller has access
|
|
to this info (the link's owner always has access to this data)."
|
|
|
|
requested_visibility RequestedVisibility?
|
|
"The shared link's requested visibility. This can be overridden by the team and shared
|
|
folder policies. The final visibility, after considering these policies, can be found in
|
|
:field:`resolved_visibility`. This is shown only if the caller is the link's
|
|
owner."
|
|
|
|
can_revoke Boolean
|
|
"Whether the caller can revoke the shared link."
|
|
revoke_failure_reason SharedLinkAccessFailureReason?
|
|
"The failure reason for revoking the link. This field will only be present if the
|
|
:field:`can_revoke` is :val:`false`."
|
|
|
|
example default
|
|
resolved_visibility = public
|
|
can_revoke = false
|
|
revoke_failure_reason = owner_only
|
|
|
|
struct TeamMemberInfo
|
|
"Information about a team member."
|
|
|
|
team_info TeamInfo
|
|
"Information about the member's team."
|
|
|
|
display_name String
|
|
"The display name of the user."
|
|
|
|
member_id String?
|
|
"ID of user as a member of a team. This field will only be present if the member is in the
|
|
same team as current user."
|
|
|
|
example default
|
|
team_info = default
|
|
display_name = "Roger Rabbit"
|
|
member_id = "dbmid:abcd1234"
|
|
|
|
struct SharedLinkMetadata
|
|
"The metadata of a shared link."
|
|
|
|
union
|
|
file FileLinkMetadata
|
|
folder FolderLinkMetadata
|
|
|
|
url String
|
|
"URL of the shared link."
|
|
|
|
id Id?
|
|
"A unique identifier for the linked file."
|
|
|
|
name String
|
|
"The linked file name (including extension).
|
|
This never contains a slash."
|
|
|
|
expires common.DropboxTimestamp?
|
|
"Expiration time, if set. By default the link won't expire."
|
|
|
|
path_lower String?
|
|
"The lowercased full path in the user's Dropbox. This always starts with a slash.
|
|
This field will only be present only if the linked file is in the authenticated user's
|
|
dropbox."
|
|
|
|
link_permissions LinkPermissions
|
|
"The link's access permissions."
|
|
|
|
team_member_info TeamMemberInfo?
|
|
"The team membership information of the link's owner. This field will only be present
|
|
if the link's owner is a team member."
|
|
|
|
content_owner_team_info TeamInfo?
|
|
"The team information of the content's owner. This field will only be present if
|
|
the content's owner is a team member and the content's owner team is different from the
|
|
link's owner team."
|
|
|
|
example default
|
|
file = default
|
|
|
|
example folder_link_metadata
|
|
folder = default
|
|
|
|
struct FileLinkMetadata extends SharedLinkMetadata
|
|
"The metadata of a file shared link."
|
|
|
|
client_modified common.DropboxTimestamp
|
|
"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."
|
|
server_modified common.DropboxTimestamp
|
|
"The last time the file was modified on Dropbox."
|
|
rev Rev
|
|
"A unique identifier for the current revision of a file. This field is
|
|
the same rev as elsewhere in the API and can be used to detect changes
|
|
and avoid conflicts."
|
|
size UInt64
|
|
"The file size in bytes."
|
|
|
|
example default
|
|
url = "https://www.dropbox.com/s/2sn712vy1ovegw8/Prime_Numbers.txt?dl=0"
|
|
id = "id:a4ayc_80_OEAAAAAAAAAXw"
|
|
name = "Prime_Numbers.txt"
|
|
path_lower = "/homework/math/prime_numbers.txt"
|
|
link_permissions = default
|
|
team_member_info = default
|
|
client_modified = "2015-05-12T15:50:38Z"
|
|
server_modified = "2015-05-12T15:50:38Z"
|
|
rev = "a1c10ce0dd78"
|
|
size = 7212
|
|
|
|
struct FolderLinkMetadata extends SharedLinkMetadata
|
|
"The metadata of a folder shared link."
|
|
|
|
example default
|
|
url = "https://www.dropbox.com/sh/s6fvw6ol7rmqo1x/AAAgWRSbjmYDvPpDB30Sykjfa?dl=0"
|
|
id = "id:a4ayc_80_OEAAAAAAAAAXw"
|
|
name = "Math"
|
|
path_lower = "/homework/math"
|
|
team_member_info = default
|
|
link_permissions = default
|
|
|
|
union SharedLinkError
|
|
shared_link_not_found
|
|
"The shared link wasn't found."
|
|
shared_link_access_denied
|
|
"The caller is not allowed to access this shared link."
|
|
unsupported_link_type
|
|
"This type of link is not supported."
|
|
|
|
route get_shared_link_metadata(GetSharedLinkMetadataArg, SharedLinkMetadata, SharedLinkError)
|
|
"Get the shared link's metadata."
|
|
|
|
attrs
|
|
owner = "sharing"
|
|
allow_app_folder_app = true
|
|
|
|
#
|
|
# List Shared links definitions and route
|
|
#
|
|
|
|
struct ListSharedLinksArg
|
|
path ReadPath?
|
|
"See :route:`list_shared_links` description."
|
|
cursor String?
|
|
"The cursor returned by your last call to :route:`list_shared_links`."
|
|
direct_only Boolean?
|
|
"See :route:`list_shared_links` description."
|
|
|
|
example default
|
|
"List all links."
|
|
cursor = "ZtkX9_EHj3x7PMkVuFIhwKYXEpwpLwyxp9vMKomUhllil9q7eWiAu"
|
|
|
|
example path
|
|
path = "/Homework/Math"
|
|
|
|
example id
|
|
path = "id:a4ayc_80_OEAAAAAAAAAYa"
|
|
|
|
example rev
|
|
path = "rev:a1c10ce0dd78"
|
|
|
|
example id_no_parent_links
|
|
path = "id:a4ayc_80_OEAAAAAAAAAYa"
|
|
direct_only = true
|
|
|
|
struct ListSharedLinksResult
|
|
links List(SharedLinkMetadata)
|
|
"Shared links applicable to the path argument."
|
|
has_more Boolean
|
|
"Is true if there are additional shared links that have not been returned
|
|
yet. Pass the cursor into :route:`list_shared_links` to retrieve them."
|
|
cursor String?
|
|
"Pass the cursor into :route:`list_shared_links` to obtain the additional links. Cursor is
|
|
returned only if no path is given."
|
|
|
|
example default
|
|
links = [default]
|
|
cursor = "ZtkX9_EHj3x7PMkVuFIhwKYXEpwpLwyxp9vMKomUhllil9q7eWiAu"
|
|
has_more = true
|
|
|
|
union ListSharedLinksError
|
|
path files.LookupError
|
|
reset
|
|
"Indicates that the cursor has been invalidated. Call
|
|
:route:`list_shared_links` to obtain a new cursor."
|
|
|
|
route list_shared_links(ListSharedLinksArg, ListSharedLinksResult, ListSharedLinksError)
|
|
"List shared links of this user.
|
|
|
|
If no path is given, returns a list of all shared links for the current user.
|
|
|
|
If a non-empty path is given, returns a list of all shared links
|
|
that allow access to the given path - direct links to the given path and links to parent folders
|
|
of the given path. Links to parent folders can be suppressed by setting
|
|
direct_only to true."
|
|
|
|
attrs
|
|
owner = "sharing"
|
|
allow_app_folder_app = true
|
|
|
|
#
|
|
# Modify shared link settings definitions and route
|
|
#
|
|
|
|
struct SharedLinkSettings
|
|
requested_visibility RequestedVisibility?
|
|
"The requested access for this shared link."
|
|
|
|
link_password String?
|
|
"If :field:`requested_visibility` is :field:`RequestedVisibility.password` this is needed
|
|
to specify the password to access the link."
|
|
|
|
expires common.DropboxTimestamp?
|
|
"Expiration time of the shared link. By default the link won't expire."
|
|
|
|
example default
|
|
requested_visibility = public
|
|
|
|
struct ModifySharedLinkSettingsArgs
|
|
url String
|
|
"URL of the shared link to change its settings."
|
|
settings SharedLinkSettings
|
|
"Set of settings for the shared link."
|
|
remove_expiration Boolean = false
|
|
"If set to true, removes the expiration of the shared link."
|
|
|
|
example default
|
|
url = "https://www.dropbox.com/s/2sn712vy1ovegw8/Prime_Numbers.txt?dl=0"
|
|
settings = default
|
|
|
|
union_closed SharedLinkSettingsError
|
|
invalid_settings
|
|
"The given settings are invalid
|
|
(for example, all attributes of the :type:`SharedLinkSettings` are empty,
|
|
the requested visibility is :field:`RequestedVisibility.password` but the
|
|
:field:`SharedLinkSettings.link_password` is missing, :field:`SharedLinkSettings.expires`
|
|
is set to the past, etc.)."
|
|
|
|
not_authorized
|
|
"User is not allowed to modify the settings of this link. Note that basic
|
|
users can only set :field:`RequestedVisibility.public`
|
|
as the :field:`SharedLinkSettings.requested_visibility` and cannot
|
|
set :field:`SharedLinkSettings.expires`."
|
|
|
|
|
|
union ModifySharedLinkSettingsError extends SharedLinkError
|
|
settings_error SharedLinkSettingsError
|
|
"There is an error with the given settings."
|
|
email_not_verified
|
|
"The caller's email should be verified."
|
|
|
|
route modify_shared_link_settings(ModifySharedLinkSettingsArgs, SharedLinkMetadata, ModifySharedLinkSettingsError)
|
|
"Modify the shared link's settings.
|
|
|
|
If the requested visibility conflict with the shared links policy of the team or the
|
|
shared folder (in case the linked file is part of a shared folder) then the
|
|
:field:`LinkPermissions.resolved_visibility` of the returned :type:`SharedLinkMetadata` will
|
|
reflect the actual visibility of the shared link and the
|
|
:field:`LinkPermissions.requested_visibility` will reflect the requested visibility."
|
|
|
|
attrs
|
|
owner = "sharing"
|
|
allow_app_folder_app = true
|
|
|
|
#
|
|
# Create shared link with settings definitions and route
|
|
#
|
|
|
|
struct CreateSharedLinkWithSettingsArg
|
|
path ReadPath
|
|
"The path to be shared by the shared link."
|
|
settings SharedLinkSettings?
|
|
"The requested settings for the newly created shared link."
|
|
|
|
example default
|
|
path = "/Prime_Numbers.txt"
|
|
settings = default
|
|
|
|
union_closed CreateSharedLinkWithSettingsError
|
|
path files.LookupError
|
|
email_not_verified
|
|
"User's email should be verified."
|
|
shared_link_already_exists
|
|
"The shared link already exists. You can call :route:`list_shared_links` to get the existing link."
|
|
settings_error SharedLinkSettingsError
|
|
"There is an error with the given settings."
|
|
access_denied
|
|
"Access to the requested path is forbidden."
|
|
|
|
route create_shared_link_with_settings(CreateSharedLinkWithSettingsArg, SharedLinkMetadata, CreateSharedLinkWithSettingsError)
|
|
"Create a shared link with custom settings.
|
|
If no settings are given then the default visibility is :field:`RequestedVisibility.public`
|
|
(The resolved visibility, though, may depend on other aspects such as team and shared folder
|
|
settings)."
|
|
|
|
attrs
|
|
owner = "sharing"
|
|
allow_app_folder_app = true
|
|
select_admin_mode = "team_admin"
|
|
|
|
|
|
#
|
|
# Revoke shared link
|
|
#
|
|
|
|
struct RevokeSharedLinkArg
|
|
url String
|
|
"URL of the shared link."
|
|
|
|
example default
|
|
url = "https://www.dropbox.com/s/2sn712vy1ovegw8/Prime_Numbers.txt?dl=0"
|
|
|
|
union RevokeSharedLinkError extends SharedLinkError
|
|
shared_link_malformed
|
|
"Shared link is malformed."
|
|
|
|
route revoke_shared_link(RevokeSharedLinkArg, Void, RevokeSharedLinkError)
|
|
"Revoke a shared link.
|
|
|
|
Note that even after revoking a shared link to a file, the file may be accessible if there are
|
|
shared links leading to any of the file parent folders. To list all shared links that enable
|
|
access to a specific file, you can use the :route:`list_shared_links` with the file as the
|
|
:field:`ListSharedLinksArg.path` argument."
|
|
|
|
attrs
|
|
owner = "sharing"
|
|
allow_app_folder_app = true
|
|
select_admin_mode = "team_admin"
|
|
|
|
#
|
|
# NSLR endpoints
|
|
#
|
|
|
|
union GetSharedLinkFileError extends SharedLinkError
|
|
shared_link_is_directory
|
|
"Directories cannot be retrieved by this endpoint."
|
|
|
|
alias GetSharedLinkFileArg = GetSharedLinkMetadataArg
|
|
|
|
route get_shared_link_file(GetSharedLinkFileArg, SharedLinkMetadata, GetSharedLinkFileError)
|
|
"Download the shared link's file from a user's Dropbox."
|
|
|
|
attrs
|
|
host="content"
|
|
style="download"
|
|
owner = "sharing"
|
|
allow_app_folder_app = true
|
|
|
|
#
|
|
# Depracated endpoints
|
|
#
|
|
|
|
|
|
union Visibility
|
|
"Who can access a shared link.
|
|
The most open visibility is :field:`public`.
|
|
The default depends on many aspects, such as team and user
|
|
preferences and shared folder settings."
|
|
|
|
public
|
|
"Anyone who has received the link can access it. No login required."
|
|
team_only
|
|
"Only members of the same team can
|
|
access the link. Login is required."
|
|
password
|
|
"A link-specific password is required to access the
|
|
link. Login is not required."
|
|
team_and_password
|
|
"Only members of the same team who
|
|
have the link-specific password can access the link."
|
|
shared_folder_only
|
|
"Only members of the shared folder containing the linked file
|
|
can access the link. Login is required."
|
|
|
|
struct LinkMetadata
|
|
"Metadata for a shared link. This can be either a
|
|
:type:`PathLinkMetadata` or :type:`CollectionLinkMetadata`."
|
|
|
|
union
|
|
path PathLinkMetadata
|
|
collection CollectionLinkMetadata
|
|
|
|
url String
|
|
"URL of the shared link."
|
|
visibility Visibility
|
|
"Who can access the link."
|
|
expires common.DropboxTimestamp?
|
|
"Expiration time, if set. By default the link won't expire."
|
|
|
|
example default
|
|
path = default
|
|
|
|
struct PathLinkMetadata extends LinkMetadata
|
|
"Metadata for a path-based shared link."
|
|
|
|
path String
|
|
"Path in user's Dropbox."
|
|
|
|
example default
|
|
url = "https://www.dropbox.com/s/2sn712vy1ovegw8/Prime_Numbers.txt?dl=0"
|
|
path = "/Homework/Math/Prime_Numbers.txt"
|
|
expires = null
|
|
visibility = public
|
|
|
|
struct CollectionLinkMetadata extends LinkMetadata
|
|
"Metadata for a collection-based shared link."
|
|
|
|
example default
|
|
url = "https://www.dropbox.com/sh/s6fvw6ol7rmqo1x/AAAgWRSbjmYDvPpDB30Sykjfa?dl=0"
|
|
expires = null
|
|
visibility = public
|
|
|
|
struct GetSharedLinksArg
|
|
|
|
path String?
|
|
"See :route:`get_shared_links` description."
|
|
|
|
example default
|
|
"Get all links, including collection links."
|
|
path = ""
|
|
|
|
example math_homework_links
|
|
"Get links giving access to /Homework/Math."
|
|
path = "/Homework/Math"
|
|
|
|
struct GetSharedLinksResult
|
|
links List(LinkMetadata)
|
|
"Shared links applicable to the path argument."
|
|
|
|
example default
|
|
links = [default]
|
|
|
|
union GetSharedLinksError
|
|
path files.MalformedPathError
|
|
|
|
route get_shared_links(GetSharedLinksArg, GetSharedLinksResult, GetSharedLinksError) deprecated by list_shared_links
|
|
"Returns a list of :type:`LinkMetadata` objects for this user,
|
|
including collection links.
|
|
|
|
If no path is given, returns a list of all shared links for the current
|
|
user, including collection links, up to a maximum of 1000 links.
|
|
|
|
If a non-empty path is given, returns a list of all shared links
|
|
that allow access to the given path. Collection links are never
|
|
returned in this case.
|
|
|
|
Note that the url field in the response is never the shortened URL."
|
|
|
|
attrs
|
|
owner = "sharing"
|
|
allow_app_folder_app = true
|
|
|
|
union_closed PendingUploadMode
|
|
"Flag to indicate pending upload default (for linking to not-yet-existing paths)."
|
|
|
|
file
|
|
"Assume pending uploads are files."
|
|
folder
|
|
"Assume pending uploads are folders."
|
|
|
|
struct CreateSharedLinkArg
|
|
|
|
path String
|
|
"The path to share."
|
|
|
|
short_url Boolean = false
|
|
"Whether to return a shortened URL."
|
|
|
|
pending_upload PendingUploadMode?
|
|
"If it's okay to share a path that does not yet exist, set this to
|
|
either :field:`PendingUploadMode.file` or :field:`PendingUploadMode.folder`
|
|
to indicate whether to assume it's a file or folder."
|
|
|
|
example default
|
|
path = "/Homework/Math/Prime_Numbers.txt"
|
|
|
|
union CreateSharedLinkError
|
|
path files.LookupError
|
|
|
|
route create_shared_link(CreateSharedLinkArg, PathLinkMetadata, CreateSharedLinkError) deprecated by create_shared_link_with_settings
|
|
"Create a shared link.
|
|
|
|
If a shared link already exists for the given path, that link is returned.
|
|
|
|
Note that in the returned :type:`PathLinkMetadata`, the
|
|
:field:`PathLinkMetadata.url` field is the shortened URL if
|
|
:field:`CreateSharedLinkArg.short_url` argument is set to :val:`true`.
|
|
|
|
Previously, it was technically possible to break a shared link by moving or
|
|
renaming the corresponding file or folder. In the future, this will no
|
|
longer be the case, so your app shouldn't rely on this behavior. Instead, if
|
|
your app needs to revoke a shared link, use :route:`revoke_shared_link`."
|
|
|
|
attrs
|
|
owner = "sharing"
|
|
allow_app_folder_app = true
|
|
select_admin_mode = "team_admin"
|