dropbox-sdk-0.1.1: A (very preliminary) library to access the Dropbox HTTP API.

Dropbox

Contents

Synopsis

Configuration

mkConfigSource

Arguments

:: Locale 
-> String

Your Dropbox app key

-> String

Your Dropbox app secret

-> AccessType

configAccessType

-> IO Config 

A convenience function that constructs a Config

data Config Source

The configuration used to make authentication calls and API calls. You typically create one of these via the config helper function.

Constructors

Config 

Fields

configHosts :: Hosts

The hosts to connect to (just use hostsDefault).

configUserLocale :: Locale

The locale that the Dropbox service should use when returning user-visible strings.

configAppId :: AppId

Your app's key/secret

configAccessType :: AccessType

The type of folder access your Dropbox application uses.

configCertVerifier :: CertVerifier

The server certificate validation routine.

Instances

data CertVerifier Source

How the server's SSL certificate will be verified.

Constructors

CertVerifier 

Fields

certVerifierName :: String

The human-friendly name of the policy (only for debug prints)

certVerifierFunc :: CertVerifierFunc

The function that implements certificate validation.

Instances

certVerifierInsecure :: CertVerifierSource

A dummy implementation that doesn't perform any verification.

certVerifierFromPemFile :: FilePath -> IO (Either ErrorMessage CertVerifier)Source

Reads certificates in PEM format from the given file and uses those as the roots when verifying certificates. This function basically just loads the certificates and delegates to certVerifierFromRootCerts for the actual checking.

certVerifierFromRootCertsSource

Arguments

:: [X509]

The set of trusted root certificates.

-> Ascii

The remove server's domain name.

-> [X509]

The certificate chain provided by the remote server.

-> IO TLSCertificateUsage 

Given a set of root certificates, yields a certificate validation function.

data AppId Source

Your application's Dropbox app key and app secret.

Constructors

AppId String String 

Instances

data Hosts Source

The set of hosts that serve the Dropbox API. Just use hostsDefault.

Constructors

Hosts 

Fields

hostsWeb :: String

The Dropbox API web host (for OAuth step 2)

hostsApi :: String

The Dropbox API endpoint for most non-content-transferring calls.

hostsApiContent :: String

The Dropbox API endpoint for most content-transferring calls.

Instances

hostsDefault :: HostsSource

The standard set of hosts that serve the Dropbox API. Used to create a Config.

data Locale Source

Specifies a locale (the string is a two-letter locale code)

Instances

localeEn :: LocaleSource

The English (American) locale (en).

localeEs :: LocaleSource

The Spanish locale (Locale es).

localeFr :: LocaleSource

The French locale (Locale fr).

localeDe :: LocaleSource

The German locale (Locale de).

localeJp :: LocaleSource

The Japanese locale (Locale jp).

data AccessType Source

The type of folder access your Dropbox application uses (https://www.dropbox.com/developers/start/core).

Constructors

AccessTypeDropbox

Full access to the user's entire Dropbox

AccessTypeAppFolder

Access to an application-specific app folder within the user's Dropbox

Manager

OAuth

data RequestToken Source

An OAuth request token (returned by authStart)

Constructors

RequestToken String String 

authStartSource

Arguments

:: Manager

The HTTP connection manager to use.

-> Config 
-> Maybe URL

The callback URL (optional)

-> IO (Either ErrorMessage (RequestToken, URL)) 

OAuth step 1. If successful, returns a RequestToken (to be used with authFinish eventually) and an authorization URL that you should redirect the user to next. If you provide a callback URL (optional), then the authorization URL you send the user to will redirect to your callback URL after the user authorizes your application.

data AccessToken Source

An OAuth request token (returned by authFinish, used to construct a Session)

Constructors

AccessToken String String 

authFinishSource

Arguments

:: Manager

The HTTP connection manager to use.

-> Config 
-> RequestToken

The RequestToken obtained from authStart

-> IO (Either ErrorMessage (AccessToken, String))

The AccessToken used to make Dropbox API calls and the user's Dropbox user ID.

OAuth step 3. Once you've directed the user to the authorization URL from authStart and the user has authorized your app, call this function to get a RequestToken, which is used to make Dropbox API calls.

data Session Source

Contains a Config and an AccessToken. Every API call (after OAuth is complete) requires this as an argument.

Get user account info

getAccountInfoSource

Arguments

:: Manager

The HTTP connection manager to use.

-> Session 
-> IO (Either ErrorMessage AccountInfo) 

Retrieve information about the user account your AccessToken is connected to.

data AccountInfo Source

Information about a user account.

Constructors

AccountInfo 

Fields

accountInfoUid :: Word64

Dropbox user ID

accountInfoDisplayName :: String

Full name (when displayed as a single string)

accountInfoCountry :: Maybe String

Two-letter country code, if available

accountInfoReferralUrl :: String

Dropbox referral link

accountInfoQuota :: Quota

Information about the storage quota

Basic file access API

Get metadata

getMetadataSource

Arguments

:: Manager

The HTTP connection manager to use.

-> Session 
-> Path

The full path (relative to your DbAccessType root)

-> IO (Either ErrorMessage Meta) 

Get the metadata for the file or folder at the given path.

getMetadataWithChildrenSource

Arguments

:: Manager

The HTTP connection manager to use.

-> Session 
-> Path

The full path (relative to your DbAccessType root)

-> Maybe Integer

A limit on folder contents (max: 10,000). If the path refers to a folder and this folder has more than the specified number of immediate children, the entire getMetadataWithChildren call will fail with an HTTP 406 error code. If unspecified, or if set to zero, the server will set this to 10,000.

-> IO (Either ErrorMessage (Meta, Maybe FolderContents)) 

Get the metadata for the file or folder at the given path. If it's a folder, return the first-level folder contents' metadata entries as well.

getMetadataWithChildrenIfChangedSource

Arguments

:: Manager

The HTTP connection manager to use.

-> Session 
-> Path 
-> Maybe Integer 
-> FolderHash

For folders, the returned child metadata will include a folderHash field that is a short identifier for the current state of the folder. If the FolderHash for the specified path hasn't change, this call will return Nothing, which indicates that the previously-retrieved metadata is still the latest.

-> IO (Either ErrorMessage (Maybe (Meta, Maybe FolderContents))) 

Same as getMetadataWithChildren except it'll return Nothing if the FolderHash of the folder on Dropbox is the same as the FolderHash passed in.

data Meta Source

The metadata for a file or folder. MetaBase contains the metadata common to files and folders. MetaExtra contains the file-specific or folder-specific data.

Constructors

Meta MetaBase MetaExtra 

Instances

data MetaBase Source

Metadata common to both files and folders.

Constructors

MetaBase 

Fields

metaRoot :: AccessType

Matches the AccessType of the app that retrieved the metadata.

metaPath :: String

The full path (starting with a /) of the file or folder, relative to metaRoot

metaIsDeleted :: Bool

Whether this metadata entry refers to a file that had been deleted when the entry was retrieved.

metaThumbnail :: Bool

Will be True if this file might have a thumbnail, and False if it definitely doesn't.

metaIcon :: String

The name of the icon used to illustrate this file type in Dropbox's icon library (https://www.dropbox.com/static/images/dropbox-api-icons.zip).

Instances

data MetaExtra Source

Metadata that's specific to either files or folders.

Constructors

File FileExtra

Files have additional metadata

Folder

Folders do not

data FolderContents Source

The single-level contents of a folder.

Constructors

FolderContents 

Fields

folderHash :: FolderHash

An identifier for the folder's metadata and contents.

folderChildren :: [Meta]

The metadata for the immediate children of a folder.

data FileExtra Source

Extra metadata specific to files (and not folders)

Constructors

FileExtra 

Fields

fileBytes :: Integer

The file size (bytes)

fileHumanSize :: String

A human-readable representation of the file size, for example 15 bytes (localized according to Locale in Config)

fileRevision :: FileRevision

The revision of the file

fileModified :: UTCTime

When this file was added or last updated

newtype FolderHash Source

Represents an identifier for a folder's metadata and contents. Can be used with getMetadataWithChildrenIfChanged to avoid downloading a folder's metadata and contents if it hasn't changed.

Constructors

FolderHash String 

newtype FileRevision Source

Represents a file's revision (fileRevision).

Constructors

FileRevision String 

Uploading files

addFileSource

Arguments

:: Manager

The HTTP connection manager to use.

-> Session 
-> Path

The full path (relative to your DbAccessType root)

-> RequestBody

The file contents.

-> IO (Either ErrorMessage Meta) 

Add a new file. If a file or folder already exists at the given path, your file will be automatically renamed. If successful, you'll get back the metadata for your newly-uploaded file.

forceFileSource

Arguments

:: Manager

The Network.HTTP.Enumerator.Manager to use.

-> Session 
-> Path

The full path (relative to your DbAccessType root)

-> RequestBody

The file contents.

-> IO (Either ErrorMessage Meta) 

Add a file. If a file already exists at the given path, that file will be overwritten. If successful, you'll get back the metadata for your newly-uploaded file.

updateFileSource

Arguments

:: Manager

The HTTP connection manager to use.

-> Session 
-> Path

The full path (relative to your DbAccessType root)

-> RequestBody

The file contents.

-> FileRevision

The revision of the file you expect to be writing to.

-> IO (Either ErrorMessage Meta) 

Overwrite a file, assuming it is the version you expect. Specify the version you expect with the FileRevision. If the file on Dropbox matches the given revision, the file will be replaced with the contents you specify. If the file on Dropbox doesn't have the specified revision, it will be left alone and your file will be automatically renamed. If successful, you'll get back the metadata for your newly-uploaded file.

Common data types

type Path = StringSource

Dropbox file and folder paths. Should always start with /.

data RequestBody Source

An HTTP request body: an Int64 for the length and an Enumerator that yields the actual data.