Files 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

Description

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,
cipherKey: String? = 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.
cipherKeyString?NoPNConfiguration.cipherKeyKey to be used to encrypt uploaded data. If not provided, cipherKey in PNConfiguration will be used, if provided.

Basic usage

pubnub.sendFile(
channel = "my_channel",
fileName = "cat_picture.jpg",
inputStream = inputStream,
cipherKey = "my_cipher_key",
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

Description

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?NonullPreviously-returned cursor bookmark for fetching the next page.

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.
nextStringCursor bookmark for fetching the next page
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

Description

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

Description

Download the specified file.

Method(s)

pubnub.downloadFile(
channel: String,
fileName: String,
fileId: String,
cipherKey: 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.
cipherKeyString?NoPNConfiguration.cipherKeyKey to be used to decrypt downloaded data. If a key is not provided, the SDK uses the CipherKey from the PNConfiguration.

Basic usage

pubnub.downloadFile(
channel = "my_channel",
fileName = "cat_picture.jpg",
fileId = "d9515cb7-48a7-41a4-9284-f4bf331bc770",
cipherKey = "my_cipher_key"
).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

Description

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

Description

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