PFFileObject

Objective-C

@interface PFFileObject : NSObject

Swift

class PFFileObject : NSObject

PFFileObject representes a file of binary data stored on the Parse servers. This can be a image, video, or anything else that an application needs to reference in a non-relational way.

Creating a PFFileObject

  • Unavailable

    Declaration

    Objective-C

    - (nonnull instancetype)init;

  • Creates a file with given data. A name will be assigned to it by the server.

    Declaration

    Objective-C

    + (nullable instancetype)fileObjectWithData:(nonnull NSData *)data;

    Swift

    convenience init?(data: Data)

    Parameters

    data

    The contents of the new PFFileObject.

    Return Value

    A new PFFileObject.

  • Creates a file with given data and name.

    Declaration

    Objective-C

    + (nullable instancetype)fileObjectWithName:(nullable NSString *)name
                                       data:(nonnull NSData *)data;

    Swift

    convenience init?(name: String?, data: Data)

    Parameters

    name

    The name of the new PFFileObject. The file name must begin with and alphanumeric character, and consist of alphanumeric characters, periods, spaces, underscores, or dashes.
    data

    The contents of the new PFFileObject.

    Return Value

    A new PFFileObject object.

  • Creates a file with the contents of another file.

    Warning

    This method raises an exception if the file at path is not accessible or if there is not enough disk space left.

    Declaration

    Objective-C

    + (nullable instancetype)fileObjectWithName:(nullable NSString *)name
                             contentsAtPath:(nonnull NSString *)path;

    Parameters

    name

    The name of the new PFFileObject. The file name must begin with and alphanumeric character, and consist of alphanumeric characters, periods, spaces, underscores, or dashes.
    path

    The path to the file that will be uploaded to Parse.

    Return Value

    A new PFFileObject instance.

  • Creates a file with the contents of another file.

    Declaration

    Objective-C

    + (nullable instancetype)fileObjectWithName:(nullable NSString *)name
                             contentsAtPath:(nonnull NSString *)path
                                      error:
                                          (NSError *_Nullable *_Nullable)error;

    Swift

    convenience init(name: String?, contentsAtPath path: String) throws

    Parameters

    name

    The name of the new PFFileObject. The file name must begin with and alphanumeric character, and consist of alphanumeric characters, periods, spaces, underscores, or dashes.
    path

    The path to the file that will be uploaded to Parse.
    error

    On input, a pointer to an error object. If an error occurs, this pointer is set to an actual error object containing the error information. You may specify nil for this parameter if you do not want the error information.

    Return Value

    A new PFFileObject instance or nil if the error occured.

  • Creates a file with given data, name and content type.

    Warning

    This method raises an exception if the data supplied is not accessible or could not be saved.

    Declaration

    Objective-C

    + (nullable instancetype)fileObjectWithName:(nullable NSString *)name
                                       data:(nonnull NSData *)data
                                contentType:(nullable NSString *)contentType;

    Parameters

    name

    The name of the new PFFileObject. The file name must begin with and alphanumeric character, and consist of alphanumeric characters, periods, spaces, underscores, or dashes.
    data

    The contents of the new PFFileObject.
    contentType

    Represents MIME type of the data.

    Return Value

    A new PFFileObject instance.

  • Creates a file with given data, name and content type.

    Declaration

    Objective-C

    + (nullable instancetype)fileObjectWithName:(nullable NSString *)name
                                       data:(nonnull NSData *)data
                                contentType:(nullable NSString *)contentType
                                      error:
                                          (NSError *_Nullable *_Nullable)error;

    Swift

    convenience init(name: String?, data: Data, contentType: String?) throws

    Parameters

    name

    The name of the new PFFileObject. The file name must begin with and alphanumeric character, and consist of alphanumeric characters, periods, spaces, underscores, or dashes.
    data

    The contents of the new PFFileObject.
    contentType

    Represents MIME type of the data.
    error

    On input, a pointer to an error object. If an error occurs, this pointer is set to an actual error object containing the error information. You may specify nil for this parameter if you do not want the error information.

    Return Value

    A new PFFileObject instance or nil if the error occured.

  • Creates a file with given data and content type.

    Declaration

    Objective-C

    + (nonnull instancetype)fileObjectWithData:(nonnull NSData *)data
                               contentType:(nullable NSString *)contentType;

    Swift

    convenience init(data: Data, contentType: String?)

    Parameters

    data

    The contents of the new PFFileObject.
    contentType

    Represents MIME type of the data.

    Return Value

    A new PFFileObject object.

File Properties

  • The name of the file.

    Before the file is saved, this is the filename given by the user. After the file is saved, that name gets prefixed with a unique identifier.

    Declaration

    Objective-C

    @property (nonatomic, copy, readonly) NSString *_Nonnull name;

    Swift

    var name: String { get }
  • url

    The url of the file.

    Declaration

    Objective-C

    @property (nonatomic, copy, readonly, nullable) NSString *url;

    Swift

    var url: String? { get }

  • Whether the file has been uploaded for the first time.

    Declaration

    Objective-C

    @property (nonatomic, readonly, getter=isDirty) BOOL dirty;

    Swift

    var isDirty: Bool { get }

Storing Data with Parse

  • Saves the file asynchronously.

    Declaration

    Objective-C

    - (nonnull BFTask<NSNumber *> *)saveInBackground;

    Swift

    func saveInBackground() -> Any!

    Return Value

    The task, that encapsulates the work being done.

  • Saves the file asynchronously

    Declaration

    Objective-C

    - (nonnull BFTask<NSNumber *> *)saveInBackgroundWithProgressBlock:
    (nullable PFProgressBlock)progressBlock;

    Swift

    func saveInBackground(progressBlock: PFProgressBlock? = nil) -> Any!

    Parameters

    progressBlock

    The block should have the following argument signature: ^(int percentDone)

    Return Value

    The task, that encapsulates the work being done.

  • Saves the file asynchronously and executes the given block.

    Declaration

    Objective-C

    - (void)saveInBackgroundWithBlock:(nullable PFBooleanResultBlock)block;

    Swift

    func saveInBackground() async throws -> Bool

    Parameters

    block

    The block should have the following argument signature: ^(BOOL succeeded, NSError *error).

  • Saves the file asynchronously and executes the given block.

    This method will execute the progressBlock periodically with the percent progress. progressBlock will get called with 100 before resultBlock is called.

    Declaration

    Objective-C

    - (void)saveInBackgroundWithBlock:(nullable PFBooleanResultBlock)block
                    progressBlock:(nullable PFProgressBlock)progressBlock;

    Swift

    func saveInBackground(_ block: PFBooleanResultBlock?, progressBlock: PFProgressBlock? = nil)

    Parameters

    block

    The block should have the following argument signature: ^(BOOL succeeded, NSError *error)
    progressBlock

    The block should have the following argument signature: ^(int percentDone)

Getting Data from Parse

  • Whether the data is available in memory or needs to be downloaded.

    Declaration

    Objective-C

    @property (nonatomic, assign, unsafe_unretained, readonly,
          getter=isDataAvailable) BOOL dataAvailable;

    Swift

    var isDataAvailable: Bool { get }

  • This method is like -getData but it fetches asynchronously to avoid blocking the current thread.

    See

    getData

    Declaration

    Objective-C

    - (nonnull BFTask<NSData *> *)getDataInBackground;

    Swift

    func getDataInBackground() -> Any!

    Return Value

    The task, that encapsulates the work being done.

  • This method is like -getData but it fetches asynchronously to avoid blocking the current thread.

    This can help applications with many large files avoid memory warnings.

    See

    getData

    Declaration

    Objective-C

    - (nonnull BFTask<NSData *> *)getDataInBackgroundWithProgressBlock:
    (nullable PFProgressBlock)progressBlock;

    Swift

    func getDataInBackground(progressBlock: PFProgressBlock? = nil) -> Any!

    Parameters

    progressBlock

    The block should have the following argument signature: ^(int percentDone)

    Return Value

    The task, that encapsulates the work being done.

  • This method is like -getDataInBackground but avoids ever holding the entire PFFileObject contents in memory at once.

    This can help applications with many large files avoid memory warnings.

    Declaration

    Objective-C

    - (nonnull BFTask<NSInputStream *> *)getDataStreamInBackground;

    Swift

    func getDataStreamInBackground() -> Any!

    Return Value

    The task, that encapsulates the work being done.

  • This method is like -getDataStreamInBackground, but yields a live-updating stream.

    Instead of -getDataStream, which yields a stream that can be read from only after the request has completed, this method gives you a stream directly written to by the HTTP session. As this stream is not pre-buffered, it is strongly advised to use the NSStreamDelegate methods, in combination with a run loop, to consume the data in the stream, to do proper async file downloading.

    Note

    You MUST open this stream before reading from it.

    Note

    Do NOT call waitUntilFinished on this task from the main thread. It may result in a deadlock.

    Declaration

    Objective-C

    - (nonnull BFTask<NSInputStream *> *)getDataDownloadStreamInBackground;

    Swift

    func getDataDownloadStreamInBackground() -> Any!

    Return Value

    A task that produces a live stream that is being written to with the data from the server.

  • This method is like -getDataInBackground but avoids ever holding the entire PFFileObject contents in memory at once.

    This can help applications with many large files avoid memory warnings.

    Declaration

    Objective-C

    - (nonnull BFTask<NSInputStream *> *)getDataStreamInBackgroundWithProgressBlock:
    (nullable PFProgressBlock)progressBlock;

    Swift

    func getDataStreamInBackground(progressBlock: PFProgressBlock? = nil) -> Any!

    Parameters

    progressBlock

    The block should have the following argument signature: ^(int percentDone)

    Return Value

    The task, that encapsulates the work being done.

  • This method is like -getDataStreamInBackgroundWithProgressBlock:, but yields a live-updating stream.

    Instead of -getDataStream, which yields a stream that can be read from only after the request has completed, this method gives you a stream directly written to by the HTTP session. As this stream is not pre-buffered, it is strongly advised to use the NSStreamDelegate methods, in combination with a run loop, to consume the data in the stream, to do proper async file downloading.

    Note

    You MUST open this stream before reading from it.

    Note

    Do NOT call waitUntilFinished on this task from the main thread. It may result in a deadlock.

    Declaration

    Objective-C

    - (nonnull BFTask<NSInputStream *> *)
    getDataDownloadStreamInBackgroundWithProgressBlock:
        (nullable PFProgressBlock)progressBlock;

    Swift

    func getDataDownloadStreamInBackground(progressBlock: PFProgressBlock? = nil) -> Any!

    Parameters

    progressBlock

    The block should have the following argument signature: ^(int percentDone)

    Return Value

    A task that produces a live stream that is being written to with the data from the server.

  • Asynchronously gets the data from cache if available or fetches its contents from the network.

    Declaration

    Objective-C

    - (void)getDataInBackgroundWithBlock:(nullable PFDataResultBlock)block;

    Swift

    func dataInBackground() async throws -> Data

    Parameters

    block

    The block should have the following argument signature: ^(NSData *result, NSError *error)

  • This method is like -getDataInBackgroundWithBlock: but avoids ever holding the entire PFFileObject contents in memory at once.

    This can help applications with many large files avoid memory warnings.

    Declaration

    Objective-C

    - (void)getDataStreamInBackgroundWithBlock:
    (nullable PFDataStreamResultBlock)block;

    Swift

    func dataStreamInBackground() async throws -> InputStream

    Parameters

    block

    The block should have the following argument signature: (NSInputStream *result, NSError *error)

  • Asynchronously gets the data from cache if available or fetches its contents from the network.

    This method will execute the progressBlock periodically with the percent progress. progressBlock will get called with 100 before resultBlock is called.

    Declaration

    Objective-C

    - (void)getDataInBackgroundWithBlock:(nullable PFDataResultBlock)resultBlock
                       progressBlock:(nullable PFProgressBlock)progressBlock;

    Swift

    func getDataInBackground(_ resultBlock: PFDataResultBlock?, progressBlock: PFProgressBlock? = nil)

    Parameters

    resultBlock

    The block should have the following argument signature: ^(NSData *result, NSError *error)
    progressBlock

    The block should have the following argument signature: ^(int percentDone)

  • This method is like -getDataInBackgroundWithBlock:progressBlock: but avoids ever holding the entire PFFileObject contents in memory at once.

    This can help applications with many large files avoid memory warnings.

    Declaration

    Objective-C

    - (void)getDataStreamInBackgroundWithBlock:
            (nullable PFDataStreamResultBlock)resultBlock
                             progressBlock:
                                 (nullable PFProgressBlock)progressBlock;

    Swift

    func getDataStreamInBackground(_ resultBlock: PFDataStreamResultBlock?, progressBlock: PFProgressBlock? = nil)

    Parameters

    resultBlock

    The block should have the following argument signature: ^(NSInputStream *result, NSError *error).
    progressBlock

    The block should have the following argument signature: ^(int percentDone).

  • Asynchronously gets the file path for file from cache if available or fetches its contents from the network.

    Note

    The file path may change between versions of SDK.

    Note

    If you overwrite the contents of the file at returned path it will persist those change until the file cache is cleared.

    Declaration

    Objective-C

    - (nonnull BFTask<NSString *> *)getFilePathInBackground;

    Swift

    func getFilePathInBackground() -> Any!

    Return Value

    The task, with the result set to NSString representation of a file path.

  • Asynchronously gets the file path for file from cache if available or fetches its contents from the network.

    Note

    The file path may change between versions of SDK.

    Note

    If you overwrite the contents of the file at returned path it will persist those change until the file cache is cleared.

    Declaration

    Objective-C

    - (nonnull BFTask<NSString *> *)getFilePathInBackgroundWithProgressBlock:
    (nullable PFProgressBlock)progressBlock;

    Swift

    func getFilePathInBackground(progressBlock: PFProgressBlock? = nil) -> Any!

    Parameters

    progressBlock

    The block should have the following argument signature: ^(int percentDone).

    Return Value

    The task, with the result set to NSString representation of a file path.

  • Asynchronously gets the file path for file from cache if available or fetches its contents from the network.

    Note

    The file path may change between versions of SDK.

    Note

    If you overwrite the contents of the file at returned path it will persist those change until the file cache is cleared.

    Declaration

    Objective-C

    - (void)getFilePathInBackgroundWithBlock:(nullable PFFilePathResultBlock)block;

    Swift

    func filePathInBackground() async throws -> String

    Parameters

    block

    The block should have the following argument signature: ^(NSString *filePath, NSError *error).

  • Asynchronously gets the file path for file from cache if available or fetches its contents from the network.

    Note

    The file path may change between versions of SDK.

    Note

    If you overwrite the contents of the file at returned path it will persist those change until the file cache is cleared.

    Declaration

    Objective-C

    - (void)getFilePathInBackgroundWithBlock:(nullable PFFilePathResultBlock)block
                           progressBlock:
                               (nullable PFProgressBlock)progressBlock;

    Swift

    func getFilePathInBackground(_ block: PFFilePathResultBlock?, progressBlock: PFProgressBlock? = nil)

    Parameters

    block

    The block should have the following argument signature: ^(NSString *filePath, NSError *error).
    progressBlock

    The block should have the following argument signature: ^(int percentDone).

Interrupting a Transfer

  • Cancels the current request (upload or download of file).

    Declaration

    Objective-C

    - (void)cancel;

    Swift

    func cancel()

Cache

  • Clears all cached data for this file.

    Declaration

    Objective-C

    - (nonnull BFTask *)clearCachedDataInBackground;

    Swift

    func clearCachedDataInBackground() -> Any!

    Return Value

    The task, with the result set to nil if the operation succeeds.

  • Clears all cached data for all downloaded files.

    Declaration

    Objective-C

    + (nonnull BFTask *)clearAllCachedDataInBackground;

    Swift

    class func clearAllCachedDataInBackground() -> Any!

    Return Value

    The task, with the result set to nil if the operation succeeds.

Saving Files

  • Deprecated

    Please use PFFileObject.-saveInBackgroundWithBlock: instead.

    Saves the file asynchronously and invokes the given selector on a target.

    @deprecated Please use PFFileObject.-saveInBackgroundWithBlock: instead.

    Declaration

    Objective-C

    - (void)saveInBackgroundWithTarget:(nullable id)target
                          selector:(nullable SEL)selector;

    Swift

    func saveInBackground(withTarget target: Any?, selector: Selector?)

    Parameters

    target

    The object to call selector on.
    selector

    The selector to call. It should have the following signature: (void)callbackWithResult:(NSNumber *)result error:(NSError *)error. error will be nil on success and set if there was an error. [result boolValue] will tell you whether the call succeeded or not.

Getting Files

  • Deprecated

    Please use PFFileObject.-getDataInBackgroundWithBlock: instead.

    Asynchronously gets the data from cache if available or fetches its contents from the network.

    @deprecated Please use PFFileObject.-getDataInBackgroundWithBlock: instead.

    Declaration

    Objective-C

    - (void)getDataInBackgroundWithTarget:(nullable id)target
                             selector:(nullable SEL)selector;

    Swift

    func getDataInBackground(withTarget target: Any?, selector: Selector?)

    Parameters

    target

    The object to call selector on.
    selector

    The selector to call. It should have the following signature: (void)callbackWithResult:(NSData *)result error:(NSError *)error. error will be nil on success and set if there was an error.

Storing Data with Parse

  • Saves the file synchronously.

    Declaration

    Objective-C

    - (BOOL)save;

    Return Value

    Returns whether the save succeeded.

  • Saves the file synchronously and sets an error if it occurs.

    Declaration

    Objective-C

    - (BOOL)save:(NSError *_Nullable *_Nullable)error;

    Swift

    func save() throws

    Parameters

    error

    Pointer to an NSError that will be set if necessary.

    Return Value

    Returns whether the save succeeded.

Getting Data from Parse

  • Synchronously gets the data from cache if available or fetches its contents from the network.

    Declaration

    Objective-C

    - (nullable NSData *)getData;

    Return Value

    The NSData object containing file data. Returns nil if there was an error in fetching.

  • Synchronously gets the data from cache if available or fetches its contents from the network. Sets an error if it occurs.

    Declaration

    Objective-C

    - (nullable NSData *)getData:(NSError *_Nullable *_Nullable)error;

    Swift

    func getData() throws -> Data

    Parameters

    error

    Pointer to an NSError that will be set if necessary.

    Return Value

    The NSData object containing file data. Returns nil if there was an error in fetching.

  • This method is like -getData but avoids ever holding the entire PFFileObject contents in memory at once.

    This can help applications with many large files avoid memory warnings.

    Declaration

    Objective-C

    - (nullable NSInputStream *)getDataStream;

    Return Value

    A stream containing the data. Returns nil if there was an error in fetching.

  • This method is like -getData but avoids ever holding the entire PFFileObject contents in memory at once.

    Declaration

    Objective-C

    - (nullable NSInputStream *)getDataStream:(NSError *_Nullable *_Nullable)error;

    Swift

    func getDataStream() throws -> InputStream

    Parameters

    error

    Pointer to an NSError that will be set if necessary.

    Return Value

    A stream containing the data. Returns nil if there was an error in fetching.