File Sharing API for PubNub Objective-C SDK

Allows users to upload and share files. You can upload any file of up to 5 MB in size. This feature is commonly used in social apps to share images, or in medical apps to share medical records for patients.

When a file is uploaded on a channel, it's stored and managed using a storage service, and associated with your key. Subscribers to that channel receive a file event which contains a file ID, filename, and optional description.

Send file

Upload file / data to specified channel.

Method(s)

- (void)sendFileWithRequest:(PNSendFileRequest *)request 
                 completion:(nullable PNSendFileCompletionBlock)block;

Parameter	Type	Required	Description
`request`	PNSendFileRequest	Yes	`Send file` request with all information about file and where it should be uploaded.
`block`	PNSendFileCompletionBlock	No	`Send file` file request completion block.

PNSendFileRequest

Parameter	Type	Required	Default	Description
`fileMessageMetadata`	NSDictionary	No		`NSDictionary` with values to be used by PubNub service to filter file messages
`fileMessageTTL`	NSUInteger	No	0	How long message should be stored in channel's storage. Set to `0` (zero) to store message according to the retention policy you have set on your key.
`fileMessageStore`	BOOL	No	YES	Whether published file messages should be stored in the channel's history
`message`	id	No		Message to be sent along with file to specified `channel`
`filename`	NSString	Yes		Name to be used to store uploaded data. This is set by default only if the request is created with `requestWithChannel:fileURL:`.

Deprecated parameter

The cipherKey parameter in this method is deprecated. We recommend that you configure the crypto module on your PubNub instance instead.

If you pass cipherKey as an argument, it overrides the crypto module configuration and the legacy encryption with 128-bit cipher key entropy is used.

Basic Usage

NSURL *localFileURL = ...;
PNSendFileRequest *request = [PNSendFileRequest requestWithChannel:@"channel"
                                                           fileURL:localFileURL];

[self.client sendFileWithRequest:request completion:^(PNSendFileStatus *status) {
    if (!status.isError) {
        /**
         * File upload successfully completed.
         * Uploaded file information is available here:
         *   status.data.fileIdentifier is the unique file identifier
         *   status.data.fileName is the name used to store the file
         */
    } else {
        /**
         * Handle send file error. Check the 'category' property for reasons
show all 22 lines

Response

@interface PNSendFileData : PNServiceData

// Unique identifier assigned to the file during upload
@property (nonatomic, nullable, readonly, strong) NSString *fileIdentifier;

// Time at which the file information message was published.
@property (nonatomic, nullable, readonly, strong) NSNumber *timetoken;

// Name under which the uploaded file is stored
@property (nonatomic, nullable, readonly, strong) NSString *fileName;

/**
 * Whether the file uploaded or not.
 *
 * This property should be used during error handling to identify whether the
show all 28 lines

Other Examples

Upload binary data

NSData *data = [[NSUUID UUID].UUIDString dataUsingEncoding:NSUTF8StringEncoding];
PNSendFileRequest *request = [PNSendFileRequest requestWithChannel:@"channel"
                                                          fileName:@"cat_picture.jpg"
                                                              data:data];

[self.client sendFileWithRequest:request completion:^(PNSendFileStatus *status) {
    if (!status.isError) {
        /**
         * File upload successfully completed.
         * Uploaded file information available here:
         *   status.data.fileIdentifier - unique file identifier
         *   status.data.fileName - name which has been used to store file
         */
    } else {
        /**
show all 23 lines

Upload using stream

NSInputStream *stream = ...;
NSUInteger streamSize = /* size of data in stream */;
PNSendFileRequest *request = [PNSendFileRequest requestWithChannel:@"channel"
                                                          fileName:@"image.png"
                                                            stream:stream
                                                              size:streamSize];

[self.client sendFileWithRequest:request completion:^(PNSendFileStatus *status) {
    if (!status.isError) {
        /**
         * File upload successfully completed.
         * Uploaded file information available here:
         *   status.data.fileIdentifier - unique file identifier
         *   status.data.fileName - name which has been used to store file
         */
show all 25 lines

Returns

Same as from basic usage.

List channel files

Retrieve list of files uploaded to Channel.

Method(s)

- (void)listFilesWithRequest:(PNListFilesRequest *)request 
                  completion:(PNListFilesCompletionBlock)block;

Parameter	Type	Required	Description
`request`	PNListFilesRequest	Yes	`List files` request with all information which should be used to fetch channel's files list.
`block`	PNListFilesCompletionBlock	Yes	`List files` request completion block.

PNListFilesRequest

Parameter	Type	Required	Default	Description
`next`	NSString	No		Random string returned from the server, indicating a specific position in a data set. Used for forward pagination, it fetches the next page, allowing you to continue from where you left off.
`limit`	NSUInteger	No	100	Number of files to return in response.

Basic Usage

PNListFilesRequest *request = [PNListFilesRequest requestWithChannel:@"channel"];
request.limit = 20;
request.next = ...;

[self.client listFilesWithRequest:request
                       completion:^(PNListFilesResult *result, PNErrorStatus *status) {
    if (!status.isError) {
        /**
         * Uploaded files list successfully fetched.
         *   result.data.files - List of uploaded files (information).
         *   result.data.next - Random string returned from the server, indicating a specific position in a data set. Used for forward pagination, it fetches the next page, allowing you to continue from where you left off.
         *   result.data.count - Total number of files uploaded to channel.
         */
    } else {
        /**
show all 22 lines

Response

@interface PNListFilesData : PNServiceData

// List of channel files.
@property (nonatomic, nullable, readonly, strong) NSArray<PNFile *> *files;

// Random string returned from the server, indicating a specific position in a data set. Used for forward pagination, it fetches the next page, allowing you to continue from where you left off.
@property (nonatomic, nullable, readonly, strong) NSString *next;

// How many files has been returned.
@property (nonatomic, readonly, assign) NSUInteger count;

@end

@interface PNListFilesResult : PNResult

show all 19 lines

Get File Url

Generate URL which can be used to download file from target Channel.

Method(s)

- (nullable NSURL *)downloadURLForFileWithName:(NSString *)name 
                                    identifier:(NSString *)identifier 
                                     inChannel:(NSString *)channel;

Parameter	Type	Required	Description
`name`	NSString	Yes	Name under which uploaded `file` is stored for `channel`.
`identifier`	NSString	Yes	Unique `file` identifier which has been assigned during `file` upload.
`channel`	NSString	Yes	Name of channel within which `file` with `name` has been uploaded.

Basic Usage

NSURL *url = [self.client downloadURLForFileWithName:@"user_profile.png"
                                          identifier:@"<file-identifier>"
                                           inChannel:@"lobby"];

Returns

URL which can be used to download remote file with specified name and identifier.

Download file

Download file from specified Channel.

Method(s)

- (void)downloadFileWithRequest:(PNDownloadFileRequest *)request 
                     completion:(PNDownloadFileCompletionBlock)block;

Parameter	Type	Required	Description
`request`	PNDownloadFileRequest	Yes	`Download file` request with information about file which should be downloaded.
`block`	PNDownloadFileCompletionBlock	Yes	`Download file` request completion block.

PNDownloadFileRequest

Parameter	Type	Required	Default	Description
`targetURL`	NSURL	No	Temporary location	URL where downloaded file should be stored locally. File downloaded to temporary location will be removed after completion block return.

Deprecated parameter

Basic Usage

PNDownloadFileRequest *request = [PNDownloadFileRequest requestWithChannel:@"lobby"
                                                                identifier:@"<file-identifier>"
                                                                      name:@"user_profile.png"];
request.targetURL = ...;

[self.client downloadFileWithRequest:request
                          completion:^(PNDownloadFileResult *result, PNErrorStatus *status) {

    if (!status.isError) {
        /**
         * File successfully has been downloaded.
         *   status.data.location - location where downloaded file can be found
         *   status.data.temporary - whether file has been downloaded to temporary storage and
         *                           will be removed on completion block return.
         */
show all 24 lines

Response

@interface PNDownloadFileData : PNServiceData

/**
 * Whether file is temporary or not.
 *
 * Temporary file will be removed as soon as completion block will exit. Make sure
 * to move temporary files (w/o scheduling task on secondary thread) to persistent
 * location.
 */
@property (nonatomic, readonly, assign, getter = isTemporary) BOOL temporary;

// Location where downloaded file can be found.
@property (nonatomic, readonly, nullable, readonly, strong) NSURL *location;

@end
show all 22 lines

Delete file

Delete file from specified Channel.

Method(s)

- (void)deleteFileWithRequest:(PNDeleteFileRequest *)request 
                   completion:(nullable PNDeleteFileCompletionBlock)block;

Parameter	Type	Required	Description
`request`	PNDeleteFileRequest	Yes	`Delete file` request with all information about file for removal.
`block`	PNDeleteFileCompletionBlock	No	`Delete file` request completion block.

Basic Usage

PNDeleteFileRequest *request = [PNDeleteFileRequest requestWithChannel:@"channel"
                                                            identifier:@"<file-identifier>"
                                                                  name:@"greetings.txt"];

[self.client deleteFileWithRequest:request completion:^(PNAcknowledgmentStatus *status) {
    if (!status.isError) {
        // File successfully has been deleted.
    } else {
        /**
         * Handle file delete error. Check 'category' property to find out possible issue
         * because of which request did fail.
         *
         * Request can be resent using: [status retry]
         */
    }
show all 16 lines

Response

@interface PNErrorData : PNServiceData

// Stringified error information.
@property (nonatomic, readonly, strong) NSString *information;

@end

@interface PNAcknowledgmentStatus : PNErrorStatus

// Whether status object represent error or not.
@property (nonatomic, readonly, assign, getter = isError) BOOL error;

// Additional information related to error status object.
@property (nonatomic, readonly, strong) PNErrorData *errorData;

show all 16 lines

Publish file message

Publish file message from specified Channel.

Method(s)

- (void)publishFileMessageWithRequest:(PNPublishFileMessageRequest *)request 
                           completion:(nullable PNPublishCompletionBlock)block;

Parameter	Type	Required	Description
`request`	PNPublishFileMessageRequest	Yes	`File message publish` request with all information about uploaded file.
`block`	PNPublishCompletionBlock	No	`File message publish` request completion block.

PNPublishFileMessageRequest

Property	Type	Description
`identifier`	NSString*	Unique identifier provided during file upload.
`filename`	NSString*	Name with which uploaded data has been stored.
`customMessageType`	NSString*	A case-sensitive, alphanumeric string from 3 to 50 characters describing the business-specific label or category of the message. Dashes `-` and underscores `_` are allowed. The value cannot start with special characters or the string `pn_` or `pn-`. Examples: `text`, `action`, `poll`.

You can also set any parameters from the PNBasePublishRequest request:

Property	Type	Description
`arbitraryQueryParameters`	NSDictionary*	Arbitrary percent-encoded query parameters which should be sent along with the original API call.
`preparedMetadata`	NSString*	Serialized `NSDictionary` with values used by PubNub service to filter messages.
`replicate`	BOOL	Whether the message should be replicated across the PubNub Real-Time Network and sent simultaneously to all subscribed clients on a channel.
`store`	BOOL	Whether `published` data should be stored and available with the history API or not.
`metadata`	NSDictionary*	`NSDictionary` with values used by PubNub service to filter messages.
`channel`	NSString*	Name of channel to which the message should be published.
`message`	id	Message to be published. The object is serialized into JSON (supports `NSString`, `NSNumber`, `NSArray`, `NSDictionary`). If you configured a crypto module, the message is encrypted.
`ttl`	NSUInteger	Duration for which the message should be stored in the channel's storage. Passing \b 0 will store the message according to retention policy.
`retried`	BOOL	Indicates whether the request is repeatedly sent to retry after a recent failure.

Basic Usage

PNPublishFileMessageRequest *request = [PNPublishFileMessageRequest requestWithChannel:@"channel"
                                                                        fileIdentifier:@"fileIdentifier"
                                                                                  name:@"fileName"];
request.customMessageType = @"file-message";

[self.client publishFileMessageWithRequest:request completion:^(PNPublishStatus *status) {
    if (!status.isError) {
        // File message successfully published.
    } else {
        // Handle file message publish error. Check 'category' property to find out possible
        // issue because of which request did fail.
        //
        // Request can be resent using: [status retry];
    }
}];

Response

@interface PNPublishData : PNServiceData

/**
 * Service-provided time stamp at which message has been pushed to remote
 * data object live feed.
 */
@property (nonatomic, readonly, strong) NSNumber *timetoken;

// Service-provide information about service response message.
@property (nonatomic, readonly, strong) NSString *information;

@end

@interface PNPublishStatus : PNAcknowledgmentStatus

show all 19 lines

Send file​

Method(s)​

PNSendFileRequest​

Deprecated parameter

Basic Usage​

Response​

Other Examples​

Upload binary data​

Upload using stream​

Returns​

List channel files​

Method(s)​

PNListFilesRequest​

Basic Usage​

Response​

Get File Url​

Method(s)​

Basic Usage​

Returns​

Download file​

Method(s)​

PNDownloadFileRequest​

Deprecated parameter

Basic Usage​

Response​

Delete file​

Method(s)​

Basic Usage​

Response​

Publish file message​

Method(s)​

PNPublishFileMessageRequest​

Basic Usage​

Response​

Send file

Method(s)

PNSendFileRequest

Basic Usage

Response

Other Examples

Upload binary data

Upload using stream

Returns

List channel files

Method(s)

PNListFilesRequest

Basic Usage

Response

Get File Url

Method(s)

Basic Usage

Returns

Download file

Method(s)

PNDownloadFileRequest

Basic Usage

Response

Delete file

Method(s)

Basic Usage

Response

Publish file message

Method(s)

PNPublishFileMessageRequest

Basic Usage

Response