File Sharing API for Kotlin SDK

Breaking changes in v9.0.0

PubNub Kotlin SDK version 9.0.0 unifies the codebases for Kotlin and Java SDKs, introduces a new way of instantiating the PubNub client, and changes asynchronous API callbacks and emitted status events. These changes can impact applications built with previous versions (< 9.0.0 ) of the Kotlin SDK.

For more details about what has changed, refer to Java/Kotlin SDK migration guide.

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.

Request execution

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 invoke the .sync() or .async() method on the Endpoint to execute the request, or the operation will not be performed.

val channel = pubnub.channel("channelName")

channel.publish("This SDK rules!").async { result ->
    result.onFailure { exception ->
        // Handle error
    }.onSuccess { value ->
        // Handle successful method result
    }
}

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.sendFile(
    channel: String,
    fileName: String,
    inputStream: InputStream,
    message: Any? = null,
    meta: Any? = null,
    ttl: Int? = null,
    shouldStore: Boolean? = null
    customMessageType: String
)
* required
ParameterDescription
channel *
Type: String
Default:
N/A
Channel for the file
fileName *
Type: String
Default:
N/A
Name of the file to send
inputStream *
Type: InputStream
Default:
N/A
Input stream with file content
message
Type: Any?
Default:
N/A
Message which should be sent along with file to specified channel.
meta
Type: Any?
Default:
N/A
Meta data object which can be used with the filtering ability.
ttl
Type: Int?
Default:
null
How long message should be stored in channel's storage.
shouldStore
Type: Boolean?
Default:
true
Whether PubNub published file message should be stored in channel history.
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.
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 com.pubnub.api.PubNub
import com.pubnub.api.UserId
import com.pubnub.api.v2.PNConfiguration
import com.pubnub.api.enums.PNLogVerbosity
import java.io.File
import java.io.FileInputStream
import java.io.FileOutputStream

/**
 * This example demonstrates how to use the sendFile method in PubNub Kotlin SDK.
 * 
 * The sendFile method allows you to upload files (up to 5MB) to a PubNub channel
 * where they can be shared with subscribers.
 */
fun main() {
show all 108 lines

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
timetoken
Long
A representation of the timetoken when the message was published.
status
Int
Remote call return code.
file
PNBaseFile
Uploaded file information.

PNBaseFile contains the following properties:

Property NameTypeDescription
id
Long
Id of the uploaded file.
name
String
Name of the upload file.

List channel files​

Retrieve list of files uploaded to Channel.

Method(s)​

pubnub.listFiles()
    channel: String,
    limit: Int,
    next: String?
)
* required
ParameterDescription
channel *
Type: String
Default:
n/a
Channel to get list of files.
limit
Type: Int
Default:
100
Number of files to return. Minimum value is 1, and maximum is 100.
next
Type: String?
Default:
null
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.

Basic usage​

pubnub.listFiles(
    channel = "my_channel"
).async { result ->
    result.onFailure { exception ->
        // Handle error
    }.onSuccess { value ->
        // Handle successful method 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
timetoken
Long
A representation of the timetoken when the message was published.
status
Int
Remote call return code.
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.
data
List<PNUploadedFile>
List of channel files.

PNUploadedFile contains the following properties:

Property NameTypeDescription
id
Long
Id of the uploaded file.
name
String
Name of the upload 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.getFileUrl(
    channel: String,
    fileName: String,
    fileId: String
)
* required
ParameterDescription
channel *
Type: String
Default:
N/A
Name of channel to which the file has been uploaded.
fileName *
Type: String
Default:
N/A
Name under which the uploaded file is stored.
fileId *
Type: String
Default:
N/A
Unique identifier for the file, assigned during upload.

Basic usage​

pubnub.getFileUrl(
    channel = "my_channel",
    fileName = "cat_picture.jpg",
    fileId = "someFileId"
).async { result ->
    result.onFailure { exception ->
        // Handle error
    }.onSuccess { value ->
        // Handle successful method 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
url
String
URL to be used to download the requested file.

Download file​

Download the specified file.

Method(s)​

pubnub.downloadFile(
    channel: String,
    fileName: String,
    fileId: String
)
* required
ParameterDescription
channel *
Type: String
Default:
N/A
Name of channel to which the file has been uploaded.
fileName *
Type: String
Default:
N/A
Name under which the uploaded file is stored.
fileId *
Type: String
Default:
N/A
Unique 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 ->
    result.onFailure { exception ->
        // Handle error
    }.onSuccess { value ->
        // Handle successful method result
    }
}

Response​

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

Returns​

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

Property NameTypeDescription
fileName
string
Name of the downloaded file.
byteStream
InputStream
Input 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
)
* required
ParameterDescription
channel *
Type: String
Default:
N/A
The channel from which to delete the file.
fileName *
Type: String
Default:
N/A
Name of the file to be deleted.
fileId *
Type: String
Default:
N/A
Unique identifier of the file to be deleted.

Basic usage​

pubnub.deleteFile(
    channel = "my_channel",
    fileName = "cat_picture.jpg",
    fileId = "someFileId"
).async { result ->
    result.onFailure { exception ->
        // Handle error
    }.onSuccess { value ->
        // Handle successful method result
    }
}

Response​

{
    "status": 200
}

Returns​

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

Property NameTypeDescription
Status
int
Returns a status code

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.publishFileMessage(
    channel: String,
    fileName: String,
    fileId: String,
    message: Any?,
    meta: Any?,
    shouldStore: Boolean,
    customMessageType: String
)
* required
ParameterDescription
channel *
Type: String
Default:
N/A
Name of channel to publish file message.
fileName *
Type: String
Default:
N/A
Name of the file.
fileId *
Type: String
Default:
N/A
Unique identifier of the file.
message
Type: Any?
Default:
null
The payload.
meta
Type: Any?
Default:
null
Metadata object which can be used with the filtering capability.
shouldStore
Type: Boolean
Default:
True
Set to False to not store this message in history. By default, messages are stored according to the retention policy you set on your 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.

Basic usage​

pubnub.publishFileMessage(
    channel = "my_channel",
    fileName = "cat_picture.jpg",
    fileId = "d9515cb7-48a7-41a4-9284-f4bf331bc770",
    message = "This is a sample message",
    customMessageType = "file-message"
).async { result ->
    result.onFailure { exception ->
        // Handle error
    }.onSuccess { value ->
        // Handle successful method 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
timetoken
Long
The timetoken at which the message was published.
status
Int
Remote call return code.
file
PNBaseFile
Uploaded file information.

PNBaseFile contains the following properties:

Property NameTypeDescription
id
Long
Unique identifier of the uploaded file
name
String
Name of the uploaded file
Last updated on
On this page