File Sharing 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

Upload file / data to specified channel.

Method(s)

pubnub.sendFile()
    .channel(String)
    .fileName(String)
    .inputStream(InputStream)
    .cipherKey(String)
    .ttl(Integer)
    .shouldStore(Boolean)
    .message(Object)
    .meta(Object)

| Parameter | Type | Required | Default | Description | | :-------- | :-------- | :-------- |: --- | :--- | | channel | String | Yes | | Channel for the file. | | fileName | String | Yes | | Name of the file to send. | | inputStream | InputStream | Yes | | Input stream with file content. | | cipherKey | String | Optional | PNConfiguration#cipherKey | Key to be used to encrypt uploaded data. If not provided, cipherKey in PNConfiguration will be used, if provided. | | ttl | Integer | Optional | | How long message should be stored in channel's storage. | | shouldStore | Boolean | Optional | true | Whether PubNub published file message should be stored in channel history. | | message | Object | Optional | | Message which should be sent along with file to specified channel. | | meta | Object | Optional | | Meta 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 Name	Type	Description
timetoken	Long	A representation of the timetoken when the message was published.
status	Integer	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(Integer)
    .next(String)

Parameter	Type	Required	Default	Description
channel	String	Yes		Channel to get list of files.
limit	Integer	Optional	100	Number of files to return. Minimum value is 1, and maximum is 100.
next	String	Optional		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(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 Name	Type	Description
timetoken	Long	A representation of the timetoken when the message was published.
status	Integer	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	Integer	Number of files returned.
data	List	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	Integer	Size of the uploaded file.
created	String	Time of creation.

Get File Url

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

Method(s)

pubnub.getFileUrl()
    .channel(String)
    .fileName(String)
    .fileId(String)

Parameter	Type	Required	Description
channel	String	Yes	Name of channel to which the file has been uploaded.
fileName	String	Yes	Name under which the uploaded file is stored.
fileId	String	Yes	Unique 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 Name	Type	Description
url	String	URL to be used to download the requested file.

Download file

Download file from specified Channel.

Method(s)

pubnub.downloadFile()
    .channel(String)
    .fileName(String)
    .fileId(String)
    .cipherKey(String)

Parameter	Type	Required	Description
channel	String	Yes	Name of channel to which the file has been uploaded.
fileName	String	Yes	Name under which the uploaded file is stored.
fileId	String	Yes	Unique identifier for the file, assigned during upload.
cipherKey	String	Optional	Key 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 Name	Type	Description
fileName	String	Name of the downloaded file.
byteStream	InputStream	Input stream containing all bytes of the downloaded file.

Delete file

Delete file from specified Channel.

Method(s)

pubnub.deleteFile()
    .channel(String)
    .fileName(String)
    .fileId(String)

Parameter	Type	Required	Description
channel	String	Yes	The channel from which to delete the file.
fileName	String	Yes	Name of the file to be deleted.
fileId	String	Yes	Unique 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 Name	Type	Description
Status	Integer	Returns a status code.

Publish file message

Publish file message from specified Channel.

Method(s)

pubnub.publishFileMessage()
    .channel(String)
    .fileName(String)
    .fileId(String)
    .message(Object)
    .meta(Object)
    .shouldStore(Boolean)

Parameter	Type	Required	Default	Description
channel	String	Yes		Name of channel to publish file message.
fileName	String	Yes		Name of the file.
fileId	String	Yes		Unique identifier of the file.
message	Object	Optional		The payload.
meta	Object	Optional		Meta data object which can be used with the filtering ability.
shouldStore	Boolean	Optional	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(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 Name	Type	Description
timetoken	Long	The timetoken at which the message was published.
status	Integer	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