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. If the file is not cached then an error will be generated.

  • – writeData:error:

    Updates the contents of the file to be the bytes store in data. If the file is not cached then an error will be generated.

  • – writeString:error:

    Updates the contents of the file with the parameter string encoded in UTF8. If the file is not cached then an error will be generated.

  • – 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.

    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

Watching for changes

Properties

info

The DBFileInfo for the file.

@property (nonatomic, readonly) DBFileInfo *info

Discussion

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.

Declared In

DBFile.h

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 (nonatomic, readonly) DBFileStatus *newerStatus

Declared In

DBFile.h

open

Whether the file is currently open.

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

Declared In

DBFile.h

status

The current sync status for the file.

@property (nonatomic, readonly) DBFileStatus *status

Declared In

DBFile.h

Instance Methods

addObserver:block:

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

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

Declared In

DBFile.h

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.

- (void)close

Declared In

DBFile.h

readData:

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

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

Return Value

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

Declared In

DBFile.h

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.

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

Return Value

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

Declared In

DBFile.h

readString:

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

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

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:

Remove all blocks registered for the given observer.

- (void)removeObserver:(id)observer

Declared In

DBFile.h

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.

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

Return Value

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

Declared In

DBFile.h

writeContentsOfFile:shouldSteal:error:

Updates the file’s contents with the contents of the file at localPath. If the file is not cached then an error will be generated.

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

Parameters

shouldSteal

whether the file at localPath should be copied or if it can be moved from its current location into management by the Sync SDK. 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.

Return Value

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

Declared In

DBFile.h

writeData:error:

Updates the contents of the file to be the bytes store in data. If the file is not cached then an error will be generated.

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

Return Value

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

Declared In

DBFile.h

writeString:error:

Updates the contents of the file with the parameter string encoded in UTF8. If the file is not cached then an error will be generated.

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

Return Value

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

Declared In

DBFile.h