Objective-CiOSiOSCocoaiOS SDK V4 Files API Reference for Realtime Apps

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.

Upload file / data to specified channel.
  1. ParameterTypeRequiredDescription
    request PNSendFileRequestYesSend file request with all information about file and where it should be uploaded.
    blockPNSendFileCompletionBlockNoSend file file request completion block.
    ParameterTypeRequiredDefaultDescription
    fileMessageMetadataNSDictionaryNoNSDictionary with values to be used by PubNub service to filter file messages
    cipherKeyNSStringNoFrom client configurationKey to be used to encrypt uploaded data
    fileMessageTTLNSUIntegerNo0How 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.
    fileMessageStoreBOOLNoYESWhether published file messages should be stored in the channel's history
    messageidNoMessage to be sent along with file to specified channel
    filenameNSStringYesName to be used to store uploaded data.
    This is set by default only if the request is created with requestWithChannel:fileURL:.
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
         * why the request may have failed.
         *
         * Check 'status.data.fileUploaded' to determine whether to resend the
         * request or if only file message publish should be called.
         */
    }
}];
@interface PNSendFileData : PNServiceData

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

// 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
 * send-file request should be resent, or if you just need to call
 * file message publish.
*/
@property (nonatomic, readonly, assign) BOOL fileUploaded;

@end


@interface PNSendFileStatus : PNAcknowledgmentStatus

// Send file request processed information.
@property (nonatomic, readonly, strong) PNSendFileData *data;

@end
  1. 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 {
            /**
             * Handle send file error. Check 'category' property to find out possible issue
             * because of which request did fail.
             *
             * Check 'status.data.fileUploaded' to figure out whether request should be resent or
             * only file message publish should be called.
             */
        }
    }];
  2. 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
             */
        } else {
            /**
             * Handle send file error. Check 'category' property to find out possible issue
             * because of which request did fail.
             *
             * Check 'status.data.fileUploaded' to figure out whether request should be resent or
             * only file message publish should be called.
             */
        }
    }];

Same as from basic usage.

Retrieve list of files uploaded to Channel.
  1. ParameterTypeRequiredDescription
    request PNListFilesRequestYesList files request with all information which should be used to fetch channel's files list.
    blockPNListFilesCompletionBlockYesList files request completion block.
    ParameterTypeRequiredDefaultDescription
    nextNSStringNoPreviously-returned cursor bookmark for fetching the next page.
    limitNSUIntegerNo100Number of files to return in response.
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 - cursor value to navigate to next fetched result page.
         *   result.data.count - total number of files uploaded to channel.
         */
    } else {
        /**
         * Handle fetch files list error. Check 'category' property to find out possible issue
         * because of which request did fail.
         *
         * Request can be resent using: [status retry]
         */
    }
}];
@interface PNListFilesData : PNServiceData

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

// Cursor bookmark for fetching the next page.
@property (nonatomic, nullable, readonly, strong) NSString *next;

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

@end


@interface PNListFilesResult : PNResult

// List files request processed information.
@property (nonatomic, readonly, strong) PNListFilesData *data;

@end

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

  1. ParameterTypeRequiredDescription
    nameNSStringYesName under which uploaded file is stored for channel.
    identifierNSStringYesUnique file identifier which has been assigned during file upload.
    channelNSStringYesName of channel within which file with name has been uploaded.
NSURL *url = [self.client downloadURLForFileWithName:@"user_profile.png"
                                          identifier:@"<file-identifier>"
                                           inChannel:@"lobby"];

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

Download file from specified Channel.
  1. ParameterTypeRequiredDescription
    request PNDownloadFileRequestYesDownload file request with information about file which should be downloaded.
    blockPNDownloadFileCompletionBlockYesDownload file request completion block.
    ParameterTypeRequiredDefaultDescription
    cipherKeyNSStringNoFrom client configurationKey which should be used to decrypt downloaded data.
    targetURLNSURLNoTemporary locationURL where downloaded file should be stored locally.
    File downloaded to temporary location will be removed after completion block return.
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.
         */
    } else {
        /**
         * Handle file download error. Check 'category' property to find out possible issue
         * because of which request did fail.
         *
         * Request can be resent using: [status retry]
         */
    }
}];
@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


@interface PNDownloadFileResult : PNResult

// Download file request processed information.
@property (nonatomic, readonly, strong) PNDownloadFileData *data;

@end
Delete file from specified Channel.
  1. ParameterTypeRequiredDescription
    requestPNDeleteFileRequestYesDelete file request with all information about file for removal.
    blockPNDeleteFileCompletionBlockNoDelete file request completion block.
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]
         */
    }
}];
@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;

@end
Publish file message from specified Channel.
  1. ParameterTypeRequiredDescription
    requestPNPublishFileMessageRequestYesFile message publish request with all information about uploaded file.
    blockPNPublishCompletionBlockNoFile message publish request completion block.
PNPublishFileMessageRequest *request = [PNPublishFileMessageRequest requestWithChannel:@"channel"
                                                                        fileIdentifier:@"fileIdentifier"
                                                                                  name:@"fileName"];

[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];
    }
}];
@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

// Stores reference on publish request processing status information.
@property (nonatomic, readonly, strong) PNPublishData *data;

@end