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}
)
Parameter | Type | Required | Default | Description |
---|---|---|---|---|
channel | String | Yes | Channel to send the file to. | |
fileName | String | Yes | Name of the file. | |
file | List<int> | Yes | File content. | |
cipherKey | CipherKey | Optional | Default keyset's cipherKey | cipherKey to encrypt file content. |
fileMessage | dynamic | Optional | null | The file message which published with the file. |
storeFileMessage | bool | Optional | true | If true the messages are stored in history. If not specified, the history configuration on the key is used. |
fileMessageTtl | int | Optional | Storage 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. | |
fileMessageMeta | dynamic | Optional | Additional information about the message which can be used on stream filtering. | |
keyset | Keyset | Optional | default keyset | Override for the PubNub default keyset configuration. |
using | String | Optional | Keyset 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 Name | Type | Description |
---|---|---|
timetoken | int | A representation of the timetoken when the file was published. |
isError | Boolean | A flag that describes whether there was an error during upload. |
description | String | File publish operation status description. |
fileInfo | FileInfo | Uploaded file information. |
FileInfo
contains the following properties:
Property Name | Type | Description |
---|---|---|
id | String | id of the uploaded file. |
name | String | name of the upload file. |
url | String | url 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}
)
Parameter | Type | Required | Default | Description |
---|---|---|---|---|
channel | String | Yes | Channel to send the file to. | |
limit | int | Optional | The max number of files that can be returned in the response. | |
next | String | Optional | Previously-returned cursor bookmark for fetching the next page. | |
keyset | Keyset | Optional | default keyset | Override for the PubNub default keyset configuration. |
using | String | Optional | Keyset 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 Name | Type | Description |
---|---|---|
filesDetail | List<FileDetail> | List of files information. |
next | String | Cursor bookmark for fetching the next page |
count | int | Number of files returned. |
FileDetail
contains the following properties:
Property Name | Type | Description |
---|---|---|
name | String | name of the upload file. |
id | String | id of the uploaded file. |
size | int | size of the uploaded file. |
created | String | Time 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})
Parameter | Type | Required | Default | Description |
---|---|---|---|---|
channel | String | Yes | Channel to send the file to. | |
fileId | String | Yes | ID of the file. | |
fileName | String | Yes | Name of the file. | |
keyset | Keyset | Optional | default keyset | Override for the PubNub default keyset configuration. |
using | String | Optional | Keyset 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})
Parameter | Type | Required | Default | Description |
---|---|---|---|---|
channel | String | Yes | Channel to send the file to. | |
fileId | String | Yes | ID of the file. | |
fileName | String | Yes | Name of the file. | |
cipherKey | CipherKey | Optional | Default keyset's cipherKey | cipherKey to encrypt file content. |
keyset | Keyset | Optional | default keyset | Override for the PubNub default keyset configuration. |
using | String | Optional | Keyset 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 Name | Type | Description |
---|---|---|
fileContent | dynamic | List 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})
Parameter | Type | Required | Default | Description |
---|---|---|---|---|
channel | String | Yes | Channel to send the file to. | |
fileId | String | Yes | ID of the file. | |
fileName | String | Yes | Name of the file. | |
keyset | Keyset | Optional | default keyset | Override for the PubNub default keyset configuration. |
using | String | Optional | Keyset 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})
Parameter | Type | Required | Default | Description |
---|---|---|---|---|
channel | String | Yes | Channel to send the file to. | |
message | FileMessage | Yes | Message to publish. | |
storeMessage | bool | Optional | true | If true the messages are stored in history. If not specified, the history configuration on the key is used. |
ttl | int | Optional | Storage 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. | |
meta | dynamic | Optional | Additional information about the message which can be used on stream filtering. | |
keyset | Keyset | Optional | default keyset | Override for the PubNub default keyset configuration. |
using | String | Optional | Keyset 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 Name | Type | Description |
---|---|---|
timetoken | int | The timetoken at which the message was published. |
description | String | result description e.g 'sent' for successfull publish |
isError | Boolean | it shows error status of file Message publish operation |
fileInfo | FileInfo | file information |
FileInfo
contains the following properties:
Property Name | Type | Description |
---|---|---|
id | String | id of the uploaded file. |
name | String | name of the uploaded file. |
url | String | url of the uploaded file. |