Inherits from NSObject
Declared in DBFile.h

Overview

The file object represents a particular file at a particular version. It has basic file operations such as reading and writing the file’s contents and getting info about the file. It can also tell you the current sync status, whether there’s a newer version available, and allows you to update to the newer version.

Tasks

Basic operations

  • – readHandle:

    Returns a read-only file handle for the file. If the file is not cached then the method will block until the file is downloaded.

  • – readData:

    A wrapper for readHandle: that reads the entire file contents into an NSData object.

  • – readString:

    A wrapper for readHandle: that reads the entire file contents as a UTF8 encoded string.

  • – writeContentsOfFile:shouldSteal:error:

    Updates the file’s contents with the contents of the file at localPath.

  • – writeData:error:

    Updates the contents of the file to be the bytes stored in data.

  • – writeString:error:

    Updates the contents of the file with the parameter string encoded in UTF8.

  • – appendData:error:

    Apppends the data supplied to the end of the file. If the file is not cached, then the method will block until the file is downloaded.

  • – appendString:error:

    Appends the UTF8 encoded string to the file. If the file is not cached, then the method will block until the file is downloaded.

  • – update:

    If there is a newer version of the file available, and it’s cached (determined by the cached property on newerStatus), then this method will update the file object to reference the newer version so it can be read from or written to.

  • – close

    Closes the file, preventing any further operations to occur and allowing the file to be opened again. This happens automatically when the object is deallocated.

Getting the current state

  •   info

    The DBFileInfo for the file.

    property
  •   open

    Whether the file is currently open.

    property
  •   status

    The current sync status for the file or thumbnail version represented by this DBFile.

    property
  •   newerStatus

    The current sync status for the newer version of the file. If the file is the newest version, then this property is nil.

    property
  •   isThumb

    Whether this DBFile represents a thumbnail, rather than the file contents.

    property

Watching for changes

Properties

info

@property (nonatomic, readonly) DBFileInfo *info
Discussion

The DBFileInfo for the file.

Note that the path of a file can change if a conflict occurs, so the value of file.info.path is not always equal to the path the file was opened at.

If this DBFile represents a thumbnail, the info still reflects the full file contents.

Declared In

DBFile.h

isThumb

@property (nonatomic, readonly) BOOL isThumb
Discussion

Whether this DBFile represents a thumbnail, rather than the file contents.

Declared In

DBFile.h

newerStatus

@property (nonatomic, readonly) DBFileStatus *newerStatus
Discussion

The current sync status for the newer version of the file. If the file is the newest version, then this property is nil.

Declared In

DBFile.h

open

@property (nonatomic, readonly, getter=isOpen) BOOL open
Discussion

Whether the file is currently open.

Declared In

DBFile.h

status

@property (nonatomic, readonly) DBFileStatus *status
Discussion

The current sync status for the file or thumbnail version represented by this DBFile.

Declared In

DBFile.h

Instance Methods

addObserver:block:

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

Add block as an observer when a property of the file changes.

Declared In

DBFile.h

appendData:error:

- (BOOL)appendData:(NSData *)data error:(DBError **)error
Discussion

Apppends the data supplied to the end of the file. If the file is not cached, then the method will block until the file is downloaded.

Return Value

YES if the data was appended to the file successfully, or NO if an error occurred.

Declared In

DBFile.h

appendString:error:

- (BOOL)appendString:(NSString *)string error:(DBError **)error
Discussion

Appends the UTF8 encoded string to the file. If the file is not cached, then the method will block until the file is downloaded.

Return Value

YES if the string was appended to the file successfully, or NO if an error occured.

Declared In

DBFile.h

close

- (void)close
Discussion

Closes the file, preventing any further operations to occur and allowing the file to be opened again. This happens automatically when the object is deallocated.

Declared In

DBFile.h

readData:

- (NSData *)readData:(DBError **)error
Discussion

A wrapper for readHandle: that reads the entire file contents into an NSData object.

Return Value

The file’s contents if the file can be read, or nil if an error occurred.

Declared In

DBFile.h

readHandle:

- (NSFileHandle *)readHandle:(DBError **)error
Discussion

Returns a read-only file handle for the file. If the file is not cached then the method will block until the file is downloaded.

Return Value

A file handle if the file can be read, or nil if an error occurred.

Declared In

DBFile.h

readString:

- (NSString *)readString:(DBError **)error
Discussion

A wrapper for readHandle: that reads the entire file contents as a UTF8 encoded string.

Return Value

The file’s contents decoded as UTF8 if the file can be read, or nil if an error occurred.

Declared In

DBFile.h

removeObserver:

- (void)removeObserver:(id)observer
Discussion

Remove all blocks registered for the given observer.

Declared In

DBFile.h

update:

- (BOOL)update:(DBError **)error
Discussion

If there is a newer version of the file available, and it’s cached (determined by the cached property on newerStatus), then this method will update the file object to reference the newer version so it can be read from or written to.

Return Value

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

Declared In

DBFile.h

writeContentsOfFile:shouldSteal:error:

- (BOOL)writeContentsOfFile:(NSString *)localPath shouldSteal:(BOOL)shouldSteal error:(DBError **)error
Discussion

Updates the file’s contents with the contents of the file at localPath.

Parameters

shouldSteal

whether the file at localPath should be moved from its current location (i.e. “stolen”) into management by the Sync SDK, or if it must be copied. If you are done with the file at localPath, then stealing is more efficient, but the behavior of writing to the file after stealing is undefined. Stealing will fail if the source file is not on the same device as the SDK cache, since it relies on the ability to rename without copying.

Return Value

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

Declared In

DBFile.h

writeData:error:

- (BOOL)writeData:(NSData *)data error:(DBError **)error
Discussion

Updates the contents of the file to be the bytes stored in data.

Return Value

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

Declared In

DBFile.h

writeString:error:

- (BOOL)writeString:(NSString *)string error:(DBError **)error
Discussion

Updates the contents of the file with the parameter string encoded in UTF8.

Return Value

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

Declared In

DBFile.h