File Sharing 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

Upload file / data to specified channel.

Method(s)

pubnub.files.sendFile(
  String channel, 
  String fileName, 
  List<int> file,
  {dynamic? fileMessage,
  bool? storeFileMessage,
  int? fileMessageTtl,
  String? customMessageType
  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.
`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.
`customMessageType`	String	No		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`.
`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.

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

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

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

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		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.
`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	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.
`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

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

Download the specified file.

Method(s)

pubnub.files.downloadFile(
  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.

Deprecated parameter

Basic usage

var result = await pubnub.files.downloadFile(
  'my_channel', 'someFileID', 'cat_picture.jpg');

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

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

Publish a file message to the specified channel.

Method(s)

pubnub.files.publishFileMessage(
  String channel, 
  FileMessage message,
  {bool? storeMessage,
  int? ttl,
  dynamic? meta,
  Keyset? keyset,
  String? using,
  String? customMessageType})

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.
`customMessageType`	String	No		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`.

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, customMessageType: 'file-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 publishFileMessage() 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.

Send file​

Method(s)​

Deprecated parameter

Basic usage​

Response​

Returns​

List channel files​

Method(s)​

Basic usage​

Response​

Returns​

Get File URL​

Method(s)​

Basic usage​

Response​

Returns​

Download file​

Method(s)​

Deprecated parameter

Basic usage​

Response​

Returns​

Delete file​

Method(s)​

Basic usage​

Response​

Returns​

Publish file message​

Method(s)​

Basic usage​

Response​

Returns​

Send file

Method(s)

Basic usage

Response

Returns

List channel files

Method(s)

Basic usage

Response

Returns

Get File URL

Method(s)

Basic usage

Response

Returns

Download file

Method(s)

Basic usage

Response

Returns

Delete file

Method(s)

Basic usage

Response

Returns

Publish file message

Method(s)

Basic usage

Response

Returns