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.