DBFile Class Reference
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
propertynil
.
Watching for changes
-
– addObserver:block:
Add
block
as an observer when a property of the file changes. -
– removeObserver:
Remove all blocks registered for the given
observer
.
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
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 atlocalPath
, 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