Files API for PubNub Android 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.

Send file

Description

Upload file / data to specified channel.

Method(s)

pubnub.sendFile().channel(String).fileName(String).inputStream(InputStream).cipherKey(String).message(Object).shouldStore(Boolean).meta(Object).ttl(Integer)
ParameterTypeRequiredDefaultDescription
channelStringYesChannel for the file.
fileNameStringYesName of the file to send.
inputStreamInputStreamYesInput stream with file content.
cipherKeyStringOptionalPNConfiguration#cipherKeyKey to be used to encrypt uploaded data. If not provided, cipherKey in PNConfiguration will be used, if provided.
ttlIntegerOptionalHow long message should be stored in channel's storage.
shouldStoreBooleanOptionaltrueWhether PubNub published file message should be stored in channel history.
messageObjectOptionalMessage which should be sent along with file to specified channel.
metaObjectOptionalMeta data object which can be used with the filtering ability.

Basic Usage

pubnub.sendFile()
.channel("my_channel"
.fileName("cat_picture.jpg")
.inputStream(inputStream)
.cipherKey("my_cipher_key")
.message("Look at this photo!")
.async(new PNCallback<PNFileUploadResult>() {
@Override
public void onResponse(PNFileUploadResult result, PNStatus status) {
if (!status.isError()) {
System.out.println("send timetoken: " + result.getTimetoken());
System.out.println("send status: " + result.getStatus());
System.out.println("send fileId: " + result.downloadFile().getId());
System.out.println("send fileName: " + result.downloadFile().getName());
}
show all 18 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
timetokenLongA representation of the timetoken when the message was published.
statusIntegerRemote 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(Integer).next(String)
ParameterTypeRequiredDefaultDescription
channelStringYesChannel to get list of files.
limitIntegerOptional100Number of files to return. Minimum value is 1, and maximum is 100.
nextStringOptionalPreviously-returned cursor bookmark for fetching the next page.

Basic Usage

pubnub.listFiles()
.channel("my_channel")
.async(new PNCallback<PNListFilesResult>() {
@Override
public void onResponse(PNListFilesResult result, PNStatus status) {
if (!status.isError()) {
System.out.println("files status: " + result.getStatus());
System.out.println("files status: " + result.getNext());
System.out.println("files status: " + result.getCount());
System.out.println("files status: " + result.getCount());
for (PNUploadedFile file : result.getData()) {
System.out.println("files fileId: " + file.getId());
System.out.println("files fileName: " + file.getName());
System.out.println("files fileSize: " + file.getSize());
System.out.println("files fileCreated: " + file.getCreated());
show all 20 lines

Response

{
"data":[
{
"name":"cat_picture.jpg",
"id":"d9515cb7-48a7-41a4-9284-f4bf331bc770",
"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.
statusIntegerRemote call return code.
nextStringCursor bookmark for fetching the next page
countIntegerNumber of files returned.
dataListList of channel files.

PNUploadedFile contains the following properties:

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

Get File Url

Description

Generate URL which can be used to download file from target Channel.

Method(s)

pubnub.getFileUrl().channel(String).fileName(String).fileId(String)
ParameterTypeRequiredDescription
channelStringYesName of channel to which the file has been uploaded.
fileNameStringYesName under which the uploaded file is stored.
fileIdStringYesUnique identifier for the file, assigned during upload.

Basic Usage

pubnub.getFileUrl()
.channel("my_channel")
.fileName("cat_picture.jpg")
.fileId("d9515cb7-48a7-41a4-9284-f4bf331bc770")
.async(new PNCallback<PNFileUrlResult>() {
@Override
public void onResponse(PNFileUrlResult result, PNStatus status) {
if (!status.isError()) {
System.out.println("getUrl fileUrl: " + result.getUrl());
}
System.out.println("getUrl status code: " + status.getStatusCode());
}
});

Response

{
"url":"http://ps.pndsn.com/v1/files/demo/channels/my_channel/files/d9515cb7-48a7-41a4-9284-f4bf331bc770/cat_picture.jpg?pnsdk=PubNub-Java-Unified/4.32.0&timestamp=1595771548&uuid=pn-9ce9e988-8e04-40bf-90c4-ebe170478f7d"
}

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 file from specified Channel.

Method(s)

pubnub.downloadFile().channel(String).fileName(String).fileId(String).cipherKey(String)
ParameterTypeRequiredDescription
channelStringYesName of channel to which the file has been uploaded.
fileNameStringYesName under which the uploaded file is stored.
fileIdStringYesUnique identifier for the file, assigned during upload.
cipherKeyStringOptionalKey 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(new PNCallback<PNDownloadFileResult>() {
@Override
public void onResponse(PNDownloadFileResult result, PNStatus status) {
if (!status.isError()) {
System.out.println("downloadFile fileName: " + result.getFileName());
System.out.println("downloadFile byteStream: " + result.getByteStream());
}
System.out.println("downloadFile status code: " + status.getStatusCode());
}
});

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 file from specified Channel.

Method(s)

pubnub.deleteFile().channel(String).fileName(String).fileId(String)
ParameterTypeRequiredDescription
channelStringYesThe channel from which to delete the file.
fileNameStringYesName of the file to be deleted.
fileIdStringYesUnique identifier of the file to be deleted.

Basic Usage

pubnub.deleteFile()
.channel("my_channel")
.fileName("cat_picture.jpg")
.fileId("d9515cb7-48a7-41a4-9284-f4bf331bc770")
.async(new PNCallback<PNDeleteFileResult>() {
@Override
public void onResponse(PNDeleteFileResult result, PNStatus status) {
if (!status.isError()) {
System.out.println("delete status code: " + result.getStatus());
}
System.out.println("delete status code: " + status.getStatusCode());
}
});

Response

{
"status": 200
}

Returns

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

Property NameTypeDescription
StatusIntegerReturns a status code.

Publish file message

Description

Publish file message from specified Channel.

Method(s)

pubnub.publishFileMessage().channel(String).fileName(String).fileId(String).message(Object).meta(Object).shouldStore(Boolean)
ParameterTypeRequiredDefaultDescription
channelStringYesName of channel to publish file message.
fileNameStringYesName of the file.
fileIdStringYesUnique identifier of the file.
messageObjectOptionalThe payload.
metaObjectOptionalMeta data object which can be used with the filtering ability.
shouldStoreBooleanOptionaltrueSet 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(new PNCallback<PNFileUploadResult>() {
@Override
public void onResponse(PNFileUploadResult result, PNStatus status) {
if (!status.isError()) {
System.out.println("send timetoken: " + result.getTimetoken());
System.out.println("send status: " + result.getStatus());
System.out.println("send fileId: " + result.downloadFile().getId());
System.out.println("send fileName: " + result.downloadFile().getName());
}
System.out.println("send status code: " + status.getStatusCode());
show all 17 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
timetokenLongThe timetoken at which the message was published.
statusIntegerRemote call return code.
filePNBaseFileUploaded file information.

PNBaseFile contains the following properties:

Property NameTypeDescription
idLongUnique identifier of the uploaded file
nameStringName of the uploaded file