Inherits from NSObject
Declared in DBFilesystem.h

Overview

The filesystem object provides a files and folder view of a user’s Dropbox. The most basic operations are listing a folder and opening a file, but it also allows you to move, delete, and create files and folders. The filesystem automatically synchronizes changes with the Dropbox server in the background.

File and folder info for a user’s Dropbox is mirrored locally and synced in the background. The content of a file is not downloaded until the file is opened, after which it is cached locally, up to a configured maximum size (defaulting to 500MB). If the file cache grows beyond the maximum size, the least recently used files will be removed from the cache to free space. Cached files will never be removed while in use: i.e. when a DBFile is open, or when there is an outstanding upload or download, so it is possible for the cache to temporarily exceed the limit. The cache size can be set to zero, in which case files are removed from the cache as soon as they are no longer in-use.

Background syncing will remain active if there are outstanding changes to upload or download, if there are open files, or if there are any observers registered for paths. Otherwise, syncing will be paused to preserve battery life until you access the filesystem again.

A DBFilesystem instance is tied to a linked user account, and will be shut down if the account is unlinked. In this case, most methods will fail with an error code of DBErrorAuth.

Tasks

Creating a filesystem object

Getting file information

Operations

Getting the current state

  •   account

    The account object this filesystem was created with.

    property
  •   completedFirstSync

    When a user’s account is first linked, the filesystem needs to be synced with the server before it can be used. This property indicates whether the first sync has completed and the filesystem is ready to use.

    property
  •   shutDown

    Whether the filesystem is currently shut down. The filesystem will shut down if the account associated with this filesystem becomes unlinked.

    property
  •   status

    The status of background synchronization.

    property

Watching for changes

Cache Configuration

Properties

account

@property (nonatomic, readonly) DBAccount *account
Discussion

The account object this filesystem was created with.

Declared In

DBFilesystem.h

completedFirstSync

@property (nonatomic, readonly) BOOL completedFirstSync
Discussion

When a user’s account is first linked, the filesystem needs to be synced with the server before it can be used. This property indicates whether the first sync has completed and the filesystem is ready to use.

Declared In

DBFilesystem.h

fileCacheSize

@property (nonatomic, readonly) unsigned long long fileCacheSize
Discussion

The current total disk space consumed by files in the cache.

Declared In

DBFilesystem.h

maxFileCacheSize

@property (nonatomic, assign) unsigned long long maxFileCacheSize
Discussion

The configured maximum size of files in the cache.

Once set, this setting will remain in effect across app restarts. When the cache size is lowered, this method will immediately clean up the cache based on the new limit. See the class documentation for more information on cache management.

Declared In

DBFilesystem.h

shutDown

@property (nonatomic, readonly, getter=isShutDown) BOOL shutDown
Discussion

Whether the filesystem is currently shut down. The filesystem will shut down if the account associated with this filesystem becomes unlinked.

Declared In

DBFilesystem.h

status

@property (nonatomic, readonly) DBSyncStatus *status
Discussion

The status of background synchronization.

Declared In

DBFilesystem.h

Class Methods

setSharedFilesystem:

+ (void)setSharedFilesystem:(DBFilesystem *)filesystem
Discussion

A convienent place to store your app’s filesystem

Declared In

DBFilesystem.h

sharedFilesystem

+ (DBFilesystem *)sharedFilesystem
Discussion

A convienent place to get your app’s filesystem

Declared In

DBFilesystem.h

Instance Methods

addObserver:block:

- (BOOL)addObserver:(id)observer block:(DBObserver)block
Discussion

Add an observer to be notified any time a property of the filesystem changes.

The block will be called anytime completedFirstSync, shutDown, or status changes.

Declared In

DBFilesystem.h

addObserver:forPath:block:

- (BOOL)addObserver:(id)observer forPath:(DBPath *)path block:(DBObserver)block
Discussion

Add an observer to be notified any time the file or folder at path changes.

Declared In

DBFilesystem.h

addObserver:forPathAndChildren:block:

- (BOOL)addObserver:(id)observer forPathAndChildren:(DBPath *)path block:(DBObserver)block
Discussion

Add an observer to be notified any time the folder at path changes or a file or folder directly contained in path changes.

Declared In

DBFilesystem.h

addObserver:forPathAndDescendants:block:

- (BOOL)addObserver:(id)observer forPathAndDescendants:(DBPath *)path block:(DBObserver)block
Discussion

Add an observer to be notified any time the folder at path changes or a file or folder contained somewhere beneath path changes.

Declared In

DBFilesystem.h

createFile:error:

- (DBFile *)createFile:(DBPath *)path error:(DBError **)error
Discussion

Creates a new file at path and returns a file object open at that path.

Return Value

The newly created file object if the file was opened successfuly, or nil if an error occurred.

Declared In

DBFilesystem.h

createFolder:error:

- (BOOL)createFolder:(DBPath *)path error:(DBError **)error
Discussion

Creates a new folder at path.

Return Value

YES if the folder was created successfully, or NO if an error occurred.

Declared In

DBFilesystem.h

deletePath:error:

- (BOOL)deletePath:(DBPath *)path error:(DBError **)error
Discussion

Deletes the file or folder at path.

Return Value

YES if the file or folder was deleted successfully, or NO if an error occurred.

Declared In

DBFilesystem.h

fetchShareLinkForPath:shorten:error:

- (NSString *)fetchShareLinkForPath:(DBPath *)path shorten:(BOOL)shorten error:(DBError **)error
Discussion

Returns a link to the file or folder at path, suitable for sharing. The link will optionally be shortened using the Dropbox URL shortener.

If the file or folder was created locally but not yet uploaded, a link will be created, and viewing it before the upload is complete will result in a status page indicating the pending upload.

This requires a server request. It will fail if the app is offline. It shouldn’t be called on the main thread.

Return Value

the link URL, or nil if an error occurred.

Declared In

DBFilesystem.h

fileInfoForPath:error:

- (DBFileInfo *)fileInfoForPath:(DBPath *)path error:(DBError **)error
Discussion

Returns the file info for the file or folder at path, or nil if an error occurred. If there is no file or folder at path, returns nil and sets error to DBErrorParamsNotFound.

Declared In

DBFilesystem.h

initWithAccount:

- (id)initWithAccount:(DBAccount *)account
Discussion

Create a new filesystem object with a linked account from the account manager.

Declared In

DBFilesystem.h

listFolder:error:

- (NSArray *)listFolder:(DBPath *)path error:(DBError **)error
Discussion

Returns a list of DBFileInfo objects representing the files contained in the folder at path. If completedFirstSync is false, then this call will block until the first sync completes or an error occurs.

Return Value

An array of DBFileInfo objects if successful, or nil if an error occurred.

Declared In

DBFilesystem.h

movePath:toPath:error:

- (BOOL)movePath:(DBPath *)fromPath toPath:(DBPath *)toPath error:(DBError **)error
Discussion

Moves a file or folder at fromPath to toPath.

Return Value

YES if the file or folder was moved successfully, or NO if an error occurred.

Declared In

DBFilesystem.h

openFile:error:

- (DBFile *)openFile:(DBPath *)path error:(DBError **)error
Discussion

Opens an existing file and returns a file object representing the file at path.

Files are opened at the newest cached version if the file is cached. Otherwise, the file will open at the latest server version and start downloading. Check the status property of the returned file object to determine whether it’s cached. Only 1 file can be open at a given path at the same time.

Return Value

The file object if the file was opened successfully, or nil if an error occurred.

Declared In

DBFilesystem.h

openThumbnail:ofSize:inFormat:error:

- (DBFile *)openThumbnail:(DBPath *)path ofSize:(DBThumbSize)size inFormat:(DBThumbFormat)format error:(DBError **)error
Discussion

Opens a thumbnail for an existing file and returns a file object representing a thumbnail for the file at path.

Thumbnails are opened at the newest cached version if the thumbnail is cached. Otherwise, the thumbnail will open at the latest version and start downloading. Check the status property of the returned file object to determine whether it’s cached.

Thumbnails are generated on the server and cached separately. When offline a thumbnail might be unavailable even if the file contents are available. If a file is modified locally, the thumbnail will not be available until its upload completes. Check the thumbExists property of the file’s info to find out if a thumbnail is available for download.

The DBFile object representing a thumbnail is unrelated to any DBFile opened on the file itself. Thumbnails are read-only - any attempt to write will fail. It is possible to open multiple thumbnails (for instance, of different sizes) on the same path.

Thumbnails are scaled (not cropped) in a way which preserves the original images aspect ratio, to a size which fits within a bounding box defined by the size parameter.

Return Value

The file object if the thumbnail was opened successfully, or nil if an error occurred.

Declared In

DBFilesystem.h

removeObserver:

- (void)removeObserver:(id)observer
Discussion

Unregister all blocks associated with observer from receiving updates.

Declared In

DBFilesystem.h

shutDown

- (void)shutDown
Discussion

Shuts down the filesystem, which stops all syncing.

All associated DBFiles will be closed. Changes that were made to files before shutdown will be uploaded the next time a DBFilesystem is created.

After this call, the DBFilesystem and its DBFiles can no longer be used. You should get a new DBFilesystem via initWithAccount:.

The filesystem will be automatically shut down if the app is unlinked remotely.

Declared In

DBFilesystem.h