File Sharing API for 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 the file to a specified channel.

This method covers the entire process of sending a file, including preparation, uploading the file to a cloud storage service, and post-uploading messaging on a channel.

For the last messaging step, sendFile internally calls the publishFileMessage method to publish a message on the channel.

The published message contains metadata about the file, such as the file identifier and name, enabling others on the channel to find out about the file and access it.

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}
)
* required
ParameterDescription
channel *
Type: String
Default:
n/a
Channel to send the file to.
fileName *
Type: String
Default:
n/a
Name of the file.
file *
Type: List<int>
Default:
n/a
File content.
fileMessage
Type: dynamic
Default:
null
The file message which published with the file.
storeFileMessage
Type: bool
Default:
true
If true the messages are stored in history. If not specified, the history configuration on the key is used.
fileMessageTtl
Type: int
Default:
n/a
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 unless you have message retention set to Unlimited on your keyset configuration in the Admin Portal. 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
Type: String
Default:
n/a
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
Type: dynamic
Default:
n/a
Additional information about the message which can be used on stream filtering.
keyset
Type: Keyset
Default:
default keyset
Override for the PubNub default keyset configuration.
using
Type: String
Default:
n/a
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

Reference code

This example is a self-contained code snippet ready to be run. It includes necessary imports and executes methods with console logging. Use it as a reference when working with other examples in this document.

import 'dart:convert';
import 'package:pubnub/pubnub.dart';

void main() async {
// Create PubNub instance with default keyset.
var pubnub = PubNub(
defaultKeyset: Keyset(
subscribeKey: 'demo',
publishKey: 'demo',
userId: UserId('myUniqueUserId'),
),
);

// File details
String channel = 'my_channel';
show all 29 lines

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
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 NameTypeDescription
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}
)
* required
ParameterDescription
channel *
Type: String
Default:
n/a
Channel to send the file to.
limit
Type: int
Default:
n/a
The max number of files that can be returned in the response.
next
Type: String
Default:
n/a
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
Type: Keyset
Default:
default keyset
Override for the PubNub default keyset configuration.
using
Type: String
Default:
n/a
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 NameTypeDescription
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 NameTypeDescription
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})
* required
ParameterDescription
channel *
Type: String
Default:
n/a
Channel to send the file to.
fileId *
Type: String
Default:
n/a
ID of the file.
fileName *
Type: String
Default:
n/a
Name of the file.
keyset
Type: Keyset
Default:
default keyset
Override for the PubNub default keyset configuration.
using
Type: String
Default:
n/a
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})
* required
ParameterDescription
channel *
Type: String
Default:
n/a
Channel to send the file to.
fileId *
Type: String
Default:
n/a
ID of the file.
fileName *
Type: String
Default:
n/a
Name of the file.
keyset
Type: Keyset
Default:
default keyset
Override for the PubNub default keyset configuration.
using
Type: String
Default:
n/a
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.downloadFile(
'my_channel', 'someFileID', 'cat_picture.jpg');

Response

{
"fileContent": <file data>
}

Returns

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

Property NameTypeDescription
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})
* required
ParameterDescription
channel *
Type: String
Default:
n/a
Channel to send the file to.
fileId *
Type: String
Default:
n/a
ID of the file.
fileName *
Type: String
Default:
n/a
Name of the file.
keyset
Type: Keyset
Default:
default keyset
Override for the PubNub default keyset configuration.
using
Type: String
Default:
n/a
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 the uploaded file message to a specified channel.

This method is called internally by sendFile as part of the file-sending process to publish the message with the file (already uploaded in a storage service) on a channel.

This message includes the file's unique identifier and name elements, which are needed to construct download links and inform channel subscribers that the file is available for download.

You can call this method when sendFile fails and returns the status.operation === PNPublishFileMessageOperation error. In that case, you can use the data from the status object to try again and use publishFileMessage to manually resend a file message to a channel without repeating the upload step.

Method(s)

pubnub.files.publishFileMessage(
String channel,
FileMessage message,
{bool? storeMessage,
int? ttl,
dynamic? meta,
Keyset? keyset,
String? using,
String? customMessageType})
* required
ParameterDescription
channel *
Type: String
Default:
n/a
Channel to send the file to.
message *
Type: FileMessage
Default:
n/a
Message to publish.
storeMessage
Type: bool
Default:
true
If true the messages are stored in history. If not specified, the history configuration on the key is used.
ttl
Type: int
Default:
n/a
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 unless you have message retention set to Unlimited on your keyset configuration in the Admin Portal. 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
Type: dynamic
Default:
n/a
Additional information about the message which can be used on stream filtering.
keyset
Type: Keyset
Default:
default keyset
Override for the PubNub default keyset configuration.
using
Type: String
Default:
n/a
Keyset name from the keysetStore to be used for this method call.
customMessageType
Type: String
Default:
n/a
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 NameTypeDescription
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 NameTypeDescription
id
String
id of the uploaded file.
name
String
name of the uploaded file.
url
String
url of the uploaded file.
Last updated on