PFFile Class Reference

Inherits from NSObject
Declared in PFFile.h

Overview

PFFile 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 PFFile

+ fileWithData:

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

+ (nullable instancetype)fileWithData:(NSData *)data

Parameters

data

The contents of the new PFFile.

Return Value

A new PFFile.

Declared In

PFFile.h

+ fileWithName:data:

Creates a file with given data and name.

+ (nullable instancetype)fileWithName:(nullable NSString *)name data:(NSData *)data

Parameters

name

The name of the new PFFile. 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 PFFile.

Return Value

A new PFFile object.

Declared In

PFFile.h

+ fileWithName:contentsAtPath:

Creates a file with the contents of another file.

+ (nullable instancetype)fileWithName:(nullable NSString *)name contentsAtPath:(NSString *)path

Parameters

name

The name of the new PFFile. 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 PFFile instance.

Discussion

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

Declared In

PFFile.h

+ fileWithName:contentsAtPath:error:

Creates a file with the contents of another file.

+ (nullable instancetype)fileWithName:(nullable NSString *)name contentsAtPath:(NSString *)path error:(NSError **)error

Parameters

name

The name of the new PFFile. 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 PFFile instance or nil if the error occured.

Declared In

PFFile.h

+ fileWithName:data:contentType:

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

+ (nullable instancetype)fileWithName:(nullable NSString *)name data:(NSData *)data contentType:(nullable NSString *)contentType

Parameters

name

The name of the new PFFile. 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 PFFile.

contentType

Represents MIME type of the data.

Return Value

A new PFFile instance.

Discussion

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

Declared In

PFFile.h

+ fileWithName:data:contentType:error:

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

+ (nullable instancetype)fileWithName:(nullable NSString *)name data:(NSData *)data contentType:(nullable NSString *)contentType error:(NSError **)error

Parameters

name

The name of the new PFFile. 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 PFFile.

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 PFFile instance or nil if the error occured.

Declared In

PFFile.h

+ fileWithData:contentType:

Creates a file with given data and content type.

+ (instancetype)fileWithData:(NSData *)data contentType:(nullable NSString *)contentType

Parameters

data

The contents of the new PFFile.

contentType

Represents MIME type of the data.

Return Value

A new PFFile object.

Declared In

PFFile.h

File Properties

  name

The name of the file.

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

Discussion

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.

Declared In

PFFile.h

  url

The url of the file.

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

Declared In

PFFile.h

  dirty

Whether the file has been uploaded for the first time.

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

Declared In

PFFile.h

Storing Data with Parse

– save

Saves the file synchronously.

- (BOOL)save

Return Value

Returns whether the save succeeded.

Declared In

PFFile.h

– save:

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

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

Parameters

error

Pointer to an NSError that will be set if necessary.

Return Value

Returns whether the save succeeded.

Declared In

PFFile.h

– saveInBackground

Saves the file asynchronously.

- (BFTask PF_GENERIC ( NSNumber *) *)saveInBackground

Return Value

The task, that encapsulates the work being done.

Declared In

PFFile.h

– saveInBackgroundWithProgressBlock:

Saves the file asynchronously

- (BFTask PF_GENERIC ( NSNumber *) *)saveInBackgroundWithProgressBlock:(nullable PFProgressBlock)progressBlock

Parameters

progressBlock

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

Return Value

The task, that encapsulates the work being done.

Declared In

PFFile.h

– saveInBackgroundWithBlock:

Saves the file asynchronously and executes the given block.

- (void)saveInBackgroundWithBlock:(nullable PFBooleanResultBlock)block

Parameters

block

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

Declared In

PFFile.h

– saveInBackgroundWithBlock:progressBlock:

Saves the file asynchronously and executes the given block.

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

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)

Discussion

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

Declared In

PFFile.h

Getting Data from Parse

  dataAvailable

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

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

Declared In

PFFile.h

– getData

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

- (nullable NSData *)getData

Return Value

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

Declared In

PFFile.h

– getDataStream

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

- (nullable NSInputStream *)getDataStream

Return Value

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

Discussion

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

Declared In

PFFile.h

– getData:

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

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

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.

Declared In

PFFile.h

– getDataStream:

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

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

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.

Declared In

PFFile.h

– getDataInBackground

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

- (BFTask PF_GENERIC ( NSData *) *)getDataInBackground

Return Value

The task, that encapsulates the work being done.

See Also

Declared In

PFFile.h

– getDataInBackgroundWithProgressBlock:

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

- (BFTask PF_GENERIC ( NSData *) *)getDataInBackgroundWithProgressBlock:(nullable PFProgressBlock)progressBlock

Parameters

progressBlock

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

Return Value

The task, that encapsulates the work being done.

Discussion

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

See Also

Declared In

PFFile.h

– getDataStreamInBackground

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

- (BFTask PF_GENERIC ( NSInputStream *) *)getDataStreamInBackground

Return Value

The task, that encapsulates the work being done.

Discussion

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

Declared In

PFFile.h

– getDataDownloadStreamInBackground

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

- (BFTask PF_GENERIC ( NSInputStream *) *)getDataDownloadStreamInBackground

Return Value

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

Discussion

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 on this task from the main thread. It may result in a deadlock.

Declared In

PFFile.h

– getDataStreamInBackgroundWithProgressBlock:

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

- (BFTask PF_GENERIC ( NSInputStream *) *)getDataStreamInBackgroundWithProgressBlock:(nullable PFProgressBlock)progressBlock

Parameters

progressBlock

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

Return Value

The task, that encapsulates the work being done.

Discussion

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

Declared In

PFFile.h

– getDataDownloadStreamInBackgroundWithProgressBlock:

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

- (BFTask PF_GENERIC ( NSInputStream *) *)getDataDownloadStreamInBackgroundWithProgressBlock:(nullable PFProgressBlock)progressBlock

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.

Discussion

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 on this task from the main thread. It may result in a deadlock.

Declared In

PFFile.h

– getDataInBackgroundWithBlock:

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

- (void)getDataInBackgroundWithBlock:(nullable PFDataResultBlock)block

Parameters

block

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

Declared In

PFFile.h

– getDataStreamInBackgroundWithBlock:

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

- (void)getDataStreamInBackgroundWithBlock:(nullable PFDataStreamResultBlock)block

Parameters

block

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

Discussion

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

Declared In

PFFile.h

– getDataInBackgroundWithBlock:progressBlock:

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

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

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)

Discussion

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

Declared In

PFFile.h

– getDataStreamInBackgroundWithBlock:progressBlock:

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

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

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).

Discussion

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

Declared In

PFFile.h

– getFilePathInBackground

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

- (BFTask PF_GENERIC ( NSString *) *)getFilePathInBackground

Return Value

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

Discussion

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.

Declared In

PFFile.h

– getFilePathInBackgroundWithProgressBlock:

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

- (BFTask PF_GENERIC ( NSString *) *)getFilePathInBackgroundWithProgressBlock:(nullable PFProgressBlock)progressBlock

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.

Discussion

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.

Declared In

PFFile.h

– getFilePathInBackgroundWithBlock:

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

- (void)getFilePathInBackgroundWithBlock:(nullable PFFilePathResultBlock)block

Parameters

block

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

Discussion

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.

Declared In

PFFile.h

– getFilePathInBackgroundWithBlock:progressBlock:

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

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

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).

Discussion

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.

Declared In

PFFile.h

Interrupting a Transfer

– cancel

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

- (void)cancel

Declared In

PFFile.h