File Sharing API for PubNub Kotlin SDK
Breaking changes since 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 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
.
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 ->
result.onFailure { exception ->
// Handle error
}.onSuccess { value ->
// 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
)
Parameter | Type | Required | Default | Description |
---|---|---|---|---|
channel | String | Yes | N/A | Channel for the file |
fileName | String | Yes | N/A | Name of the file to send |
inputStream | InputStream | Yes | N/A | Input stream with file content |
message | Any? | No | N/A | Message which should be sent along with file to specified channel . |
meta | Any? | No | N/A | Meta data object which can be used with the filtering ability. |
ttl | Int? | No | null | How long message should be stored in channel's storage. |
shouldStore | Boolean? | No | true | Whether 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 Name | Type | Description |
---|---|---|
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 Name | Type | Description |
---|---|---|
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?
)
Parameter | Type | Required | Default | Description |
---|---|---|---|---|
channel | String | Yes | Channel to get list of files. | |
limit | Int | No | 100 | Number of files to return. Minimum value is 1, and maximum is 100. |
next | String? | No | 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, 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 Name | Type | Description |
---|---|---|
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 Name | Type | Description |
---|---|---|
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
)
Parameter | Type | Required | Default | Description |
---|---|---|---|---|
channel | String | Yes | N/A | Name of channel to which the file has been uploaded. |
fileName | String | Yes | N/A | Name under which the uploaded file is stored. |
fileId | String | Yes | 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, 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×tamp=1595771548&uuid=someUuid
}
Returns
The getFileUrl()
operation returns a PNFileUrlResult
which contains the following properties:
Property Name | Type | Description |
---|---|---|
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
)
Parameter | Type | Required | Default | Description |
---|---|---|---|---|
channel | String | Yes | N/A | Name of channel to which the file has been uploaded. |
fileName | String | Yes | N/A | Name under which the uploaded file is stored. |
fileId | String | Yes | 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, 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 Name | Type | Description |
---|---|---|
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
)
Parameter | Type | Required | Default | Description |
---|---|---|---|---|
channel | String | Yes | N/A | The channel from which to delete the file. |
fileName | String | Yes | N/A | Name of the file to be deleted. |
fileId | String | Yes | 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, 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 Name | Type | Description |
---|---|---|
Status | int | Returns 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
)
Parameter | Type | Required | Default | Description |
---|---|---|---|---|
channel | String | Yes | N/A | Name of channel to publish file message. |
fileName | String | Yes | N/A | Name of the file . |
fileId | String | Yes | N/A | Unique identifier of the file. |
message | Any? | No | null | The payload. |
meta | Any? | No | null | Metadata object which can be used with the filtering capability. |
shouldStore | Boolean | No | 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. |
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 Name | Type | Description |
---|---|---|
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 Name | Type | Description |
---|---|---|
id | Long | Unique identifier of the uploaded file |
name | String | Name of the uploaded file |