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. 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&timestamp=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

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

Breaking changes since v9.0.0

Calling Kotlin methods

Send file​

Method(s)​

Deprecated parameter

Basic usage​

Response​

Returns​

List channel files​

Method(s)​

Basic usage​

Response​

Returns​

Get File URL​

Method(s)​

Basic usage​

Response​

Returns​

Download file​

Method(s)​

Deprecated parameter

Basic usage​

Response​

Returns​

Delete file​

Method(s)​

Basic usage​

Response​

Returns​

Publish file message​

Method(s)​

Basic usage​

Response​

Returns​

Send file

Method(s)

Basic usage

Response

Returns

List channel files

Method(s)

Basic usage

Response

Returns

Get File URL

Method(s)

Basic usage

Response

Returns

Download file

Method(s)

Basic usage

Response

Returns

Delete file

Method(s)

Basic usage

Response

Returns

Publish file message

Method(s)

Basic usage

Response

Returns