Files API for PubNub Dart 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

Description

Upload file / data to specified channel.

Method(s)

pubnub.files.sendFile(
String channel,
String fileName,
List<int> file,
{CipherKey? cipherKey,
dynamic? fileMessage,
bool? storeFileMessage,
int? fileMessageTtl,
dynamic? fileMessageMeta,
Keyset? keyset,
String? using}
)
ParameterTypeRequiredDefaultDescription
channelStringYesChannel to send the file to.
fileNameStringYesName of the file.
fileList<int>YesFile content.
cipherKeyCipherKeyOptionalDefault keyset's cipherKeycipherKey to encrypt file content.
fileMessagedynamicOptionalnullThe file message which published with the file.
storeFileMessageboolOptionaltrueIf true the messages are stored in history. If not specified, the history configuration on the key is used.
fileMessageTtlintOptionalStorage time to live for each message. If storeFileMessage is true, and ttl is set to 0, the message is stored with no expiry time. If storeFileMessage is true and ttl is x (x is an Integer value), the message is stored with an expiry time of x hours. If storeFileMessage is false, the ttl parameter is ignored. If ttl is not specified, then expiration of the message defaults back to the expiry value for the key.
fileMessageMetadynamicOptionalAdditional information about the message which can be used on stream filtering.
keysetKeysetOptionaldefault keysetOverride for the PubNub default keyset configuration.
usingStringOptionalKeyset name from the keysetStore to be used for this method call.

Basic usage

var result = await pubnub.files.sendFile(
'my_channel', 'cat_picture.jpg', inputFile,
fileMessage: 'Look at this photo!',
cipherKey: CipherKey.fromUtf8('cipher_key'));

print(
'File uploaded and file message published - timetoken ${result.timetoken}');

Response

{
"timetoken": 15957709330808500,
"status": 200,
"file": {
"id": "d9515cb7-48a7-41a4-9284-f4bf331bc770",
"name": "cat_picture.jpg"
}
}

Returns

The sendFile() operation returns a PublishFileMessageResult which contains the following properties:

Property NameTypeDescription
timetokenintA representation of the timetoken when the file was published.
isErrorBooleanA flag that describes whether there was an error during upload.
descriptionStringFile publish operation status description.
fileInfoFileInfoUploaded file information.

FileInfo contains the following properties:

Property NameTypeDescription
idStringid of the uploaded file.
nameStringname of the upload file.
urlStringurl of the uploaded file.

List channel files

Description

Retrieve list of files uploaded to Channel.

Method(s)

pubnub.files.listFiles(
String channel,
{int? limit,
String? next,
Keyset? keyset,
String? using}
)
ParameterTypeRequiredDefaultDescription
channelStringYesChannel to send the file to.
limitintOptionalThe max number of files that can be returned in the response.
nextStringOptionalPreviously-returned cursor bookmark for fetching the next page.
keysetKeysetOptionaldefault keysetOverride for the PubNub default keyset configuration.
usingStringOptionalKeyset name from the keysetStore to be used for this method call.

Basic usage

var result = await pubnub.files.listFiles('my_channel');

print('There are ${result.count} no. of files uploaded');

Response

{
"data":[
{
"name":"cat_picture.jpg",
"id":"d9515cb7-48a7-41a4-9284-f4bf331bc770",
"size":25778,
"created":"202007 - 26T13:42:06Z"
}],
"status": 200
"totalCount": 1,
"next": null,
"prev": null
}

Returns

The listFiles() operation returns a ListFilesResult which contains the following properties:

Property NameTypeDescription
filesDetailList<FileDetail>List of files information.
nextStringCursor bookmark for fetching the next page
countintNumber of files returned.

FileDetail contains the following properties:

Property NameTypeDescription
nameStringname of the upload file.
idStringid of the uploaded file.
sizeintsize of the uploaded file.
createdStringTime of creation.

Get File URL

Description

Generate a URL to be used to download a file from the target channel.

Method(s)

pubnub.files.getFileUrl(
String channel,
String fileId,
String fileName,
{Keyset? keyset,
String? using})
ParameterTypeRequiredDefaultDescription
channelStringYesChannel to send the file to.
fileIdStringYesID of the file.
fileNameStringYesName of the file.
keysetKeysetOptionaldefault keysetOverride for the PubNub default keyset configuration.
usingStringOptionalKeyset name from the keysetStore to be used for this method call.

Basic usage

var fileURL = pubnub.files.getFileUrl(
'my_channel', 'someFileID', 'cat_picture.jpg'
);
print('URI to download file is ${fileURL}');

Response

https://ps.pndsn.com/v1/files/demo/channels/my_channel/files/someFileId/cat_picture.jpg?pnsdk=PubNub-Dart%2F1.2.0

Returns

The getFileUrl() operation returns a Uri.

Download file

Description

Download the specified file.

Method(s)

pubnub.files.downloadFile(
String channel,
String fileId,
String fileName,
{CipherKey? cipherKey,
Keyset? keyset,
String? using})
ParameterTypeRequiredDefaultDescription
channelStringYesChannel to send the file to.
fileIdStringYesID of the file.
fileNameStringYesName of the file.
cipherKeyCipherKeyOptionalDefault keyset's cipherKeycipherKey to encrypt file content.
keysetKeysetOptionaldefault keysetOverride for the PubNub default keyset configuration.
usingStringOptionalKeyset name from the keysetStore to be used for this method call.

Basic usage

var result = await pubnub.files.downloadFile(
'my_channel', 'someFileID', 'cat_picture.jpg',
cipherKey: CipherKey.fromUtf8('cipher_key'));

Response

{
"fileContent": <file data>
}

Returns

The downloadFile() operation returns a DownloadFileResult which contains the following property:

Property NameTypeDescription
fileContentdynamicList of all bytes of the downloaded file.

Delete file

Description

Delete a file from the specified channel.

Method(s)

pubnub.files.deleteFile(
String channel,
String fileId,
String fileName,
{Keyset? keyset,
String? using})
ParameterTypeRequiredDefaultDescription
channelStringYesChannel to send the file to.
fileIdStringYesID of the file.
fileNameStringYesName of the file.
keysetKeysetOptionaldefault keysetOverride for the PubNub default keyset configuration.
usingStringOptionalKeyset name from the keysetStore to be used for this method call.

Basic usage

await pubnub.files.deleteFile(
'my_channel', 'someFileID', 'cat_picture.jpg');

Response

{
"status": 200
}

Returns

The deleteFile() operation returns a DeleteFileResult.

Publish file message

Description

Publish a file message to the specified channel.

Method(s)

pubnub.files.publishFileMessage(
String channel,
FileMessage message,
{bool? storeMessage,
int? ttl,
dynamic? meta,
CipherKey? cipherKey,
Keyset? keyset,
String? using})
ParameterTypeRequiredDefaultDescription
channelStringYesChannel to send the file to.
messageFileMessageYesMessage to publish.
storeMessageboolOptionaltrueIf true the messages are stored in history. If not specified, the history configuration on the key is used.
ttlintOptionalStorage time to live for each message. If storeMessage is true, and ttl is set to 0, the message is stored with no expiry time. If storeMessage is true and ttl is x (x is an Integer value), the message is stored with an expiry time of x hours. If storeMessage is false, the ttl parameter is ignored. If ttl is not specified, then expiration of the message defaults back to the expiry value for the key.
metadynamicOptionalAdditional information about the message which can be used on stream filtering.
keysetKeysetOptionaldefault keysetOverride for the PubNub default keyset configuration.
usingStringOptionalKeyset name from the keysetStore to be used for this method call.

Basic usage

var fileInfo = {
'id': 'someFileID',
'name': 'cat_picture.jpg'
};

var message = FileMessage(fileInfo, message: 'Look at this photo!');
var result =
await pubnub.files.publishFileMessage('my_channel', message);

print('file message published - timetoken ${result.timetoken}');

Response

{
"timetoken": 15957709330808500,
"status": 200,
"file": {
"id": "d9515cb7-48a7-41a4-9284-f4bf331bc770",
"name": "cat_picture.jpg",
}
}

Returns

The sendFile() operation returns a PNFileUploadResult which contains the following properties:

Property NameTypeDescription
timetokenintThe timetoken at which the message was published.
descriptionStringresult description e.g 'sent' for successfull publish
isErrorBooleanit shows error status of file Message publish operation
fileInfoFileInfofile information

FileInfo contains the following properties:

Property NameTypeDescription
idStringid of the uploaded file.
nameStringname of the uploaded file.
urlStringurl of the uploaded file.