File Sharing API for PubNub Kotlin 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.

Calling Kotlin methods

Most PubNub Kotlin SDK method invocations return an Endpoint object, which allows you to decide whether to perform the operation synchronously or asynchronously. You must choose one of these or the operation will not be performed at all.

For example, the following code is valid and will compile, but the publish won't be performed:

pubnub.publish(
message = "this sdk rules!",
channel = "my_channel"
)

To successfully publish a message, you must follow the actual method invocation with whether to perform it synchronously or asynchronously, for example:

pubnub.publish(
message = "this sdk rules!",
channel = "my_channel"
).async { result, status ->
if (status.error) {
// handle error
} else {
// handle successful method result
}
}

Send file

Upload file / data to specified channel.

Method(s)

pubnub.sendFile(
channel: String,
fileName: String,
inputStream: InputStream,
message: Any? = null,
meta: Any? = null,
ttl: Int? = null,
shouldStore: Boolean? = null
)
ParameterTypeRequiredDefaultDescription
channelStringYesN/AChannel for the file
fileNameStringYesN/AName of the file to send
inputStreamInputStreamYesN/AInput stream with file content
messageAny?NoN/AMessage which should be sent along with file to specified channel.
metaAny?NoN/AMeta data object which can be used with the filtering ability.
ttlInt?NonullHow long message should be stored in channel's storage.
shouldStoreBoolean?NotrueWhether PubNub published file message should be stored in channel history.
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

pubnub.sendFile(
channel = "my_channel",
fileName = "cat_picture.jpg",
inputStream = inputStream,
message = "Look at this photo!"
).async { result, status ->
if (status.error) {
//handle error
} else if (result != null) {
//handle result
}
}

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
timetokenLongA representation of the timetoken when the message was published.
statusIntRemote call return code.
filePNBaseFileUploaded file information.

PNBaseFile contains the following properties:

Property NameTypeDescription
idLongId of the uploaded file.
nameStringName of the upload file.

List channel files

Retrieve list of files uploaded to Channel.

Method(s)

pubnub.listFiles()
channel: String,
limit: Int,
next: String?
)
ParameterTypeRequiredDefaultDescription
channelStringYesChannel to get list of files.
limitIntNo100Number of files to return. Minimum value is 1, and maximum is 100.
nextString?NonullRandom 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.

Basic usage

pubnub.listFiles(
channel = "my_channel"
).async { result, status ->
if (status.error) {
//handle error
} else if (result != null) {
//handle result
}
}

Response

{
"data":[
{
"name":"cat_picture.jpg",
"id":"fileId",
"size":25778,
"created":"202007 - 26T13:42:06Z"
}],
"status": 200
"totalCount": 1,
"next": null,
"prev": null
}

Returns

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

Property NameTypeDescription
timetokenLongA representation of the timetoken when the message was published.
statusIntRemote call return code.
nextStringRandom 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.
countIntNumber of files returned.
dataList<PNUploadedFile>List of channel files.

PNUploadedFile contains the following properties:

Property NameTypeDescription
idLongId of the uploaded file.
nameStringName of the upload file.
sizeIntSize of the uploaded file.
createdStringTime of creation.

Get File URL

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

Method(s)

pubnub.getFileUrl(
channel: String,
fileName: String,
fileId: String
)
ParameterTypeRequiredDefaultDescription
channelStringYesN/AName of channel to which the file has been uploaded.
fileNameStringYesN/AName under which the uploaded file is stored.
fileIdStringYesN/AUnique identifier for the file, assigned during upload.

Basic usage

pubnub.getFileUrl(
channel = "my_channel",
fileName = "cat_picture.jpg",
fileId = "someFileId"
).async { result, status ->
if (status.error) {
//handle error
} else if (result != null) {
//handle result
}
}

Response

{
"url" : http://ps.pndsn.com/v1/files/demo/channels/my_channel/files/fileID/cat_picture.jpg?pnsdk=PubNub-kotlin-Unified/4.32.0&timestamp=1595771548&uuid=someUuid
}

Returns

The getFileUrl() operation returns a PNFileUrlResult which contains the following properties:

Property NameTypeDescription
urlStringURL to be used to download the requested file.

Download file

Download the specified file.

Method(s)

pubnub.downloadFile(
channel: String,
fileName: String,
fileId: String
)
ParameterTypeRequiredDefaultDescription
channelStringYesN/AName of channel to which the file has been uploaded.
fileNameStringYesN/AName under which the uploaded file is stored.
fileIdStringYesN/AUnique identifier for the file, assigned during upload.
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

pubnub.downloadFile(
channel = "my_channel",
fileName = "cat_picture.jpg",
fileId = "d9515cb7-48a7-41a4-9284-f4bf331bc770"
).async { result, status ->
if (status.error) {
//handle error
} else if (result != null) {
//handle result
}
}

Response

{
"fileName": "cat_picture.jpg",
"byteStream": <file data>
}

Returns

The downloadFile() operation returns a PNDownloadFileResult which contains the following properties:

Property NameTypeDescription
fileNamestringName of the downloaded file.
byteStreamInputStreamInput stream containing all bytes of the downloaded file.

Delete file

Delete a file from the specified channel.

Method(s)

pubnub.deleteFile(
channel: String,
fileName: String,
fileId: String
)
ParameterTypeRequiredDefaultDescription
channelStringYesN/AThe channel from which to delete the file.
fileNameStringYesN/AName of the file to be deleted.
fileIdStringYesN/AUnique identifier of the file to be deleted.

Basic usage

pubnub.deleteFile(
channel = "my_channel",
fileName = "cat_picture.jpg",
fileId = "someFileId"
).async { result, status ->
if (status.error) {
//handle error
} else if (result != null) {
//handle result
}
}

Response

{
"status": 200
}

Returns

The deleteFile() operation returns a PNDeleteFileResult which contains the following property:

Property NameTypeDescription
StatusintReturns a status code

Publish file message

Publish a file message to the specified channel.

Method(s)

pubnub.publishFileMessage(
channel: String,
fileName: String,
fileId: String,
message: Any?,
meta: Any?,
shouldStore: Boolean
)
ParameterTypeRequiredDefaultDescription
channelStringYesN/AName of channel to publish file message.
fileNameStringYesN/AName of the file.
fileIdStringYesN/AUnique identifier of the file.
messageAny?NonullThe payload.
metaAny?NonullMetadata object which can be used with the filtering capability.
shouldStoreBooleanNoTrueSet to False to not store this message in history. By default, messages are stored according to the retention policy you set on your key.

Basic usage

pubnub.publishFileMessage(
channel = "my_channel",
fileName = "cat_picture.jpg",
fileId = "d9515cb7-48a7-41a4-9284-f4bf331bc770",
message = "This is a sample message"
).async { result, status ->
if (status.error) {
//handle error
} else if (result != null) {
//handle result
}
}

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
timetokenLongThe timetoken at which the message was published.
statusIntRemote call return code.
filePNBaseFileUploaded file information.

PNBaseFile contains the following properties:

Property NameTypeDescription
idLongUnique identifier of the uploaded file
nameStringName of the uploaded file
Last updated on