File Sharing API for PubNub Unity 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)
    .File(string|byte[])
    .Texture(Texture2D | RenderTexture)
    .FileName(string)
    .Ttl(int)
    .ShouldStore(bool)
    .Message(string)
    .Meta(Dictionary<string, object>)
    .Execute(System.Action<PNFileUploadResult, PNStatus>)

Parameter	Type	Required	Description
Channel	string	Yes	Channel for the file.
File	string or byte[]	Yes You can either use File or Texture.	Full path of the file with file name or an array of bytes. When using an array of bytes, you must set FileName.
Texture	Texture2D or RenderTexture	Yes You can either use File or Texture.	An instance of a Texture object. When you send a Texture, a Message with its size and format is added automatically.
FileName	string	Required when sending a file by byte[]	Name of the file to send. You can use it to override the default file name.
TtL	int	Optional	How long message should be stored in channel's storage.
ShouldStore	bool	Optional	Whether PubNub published file message should be stored in channel history.
Message	string	Optional	Message which should be sent along with file to specified channel.
Meta	Dictionary<string, object>	Optional	Dictionary<string, object> with values which should be used by PubNub service to filter file messages.
Execute	System.Action	Yes	System.Action of type PNFileUploadResult.
ExecuteAsync	None	Optional	Returns Task<PNResult<PNFileUploadResult>>.

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

PNResult<PNFileUploadResult> fileUploadResponse = await pubnub.SendFile()
    .Channel("my_channel")
    .File("cat_picture.jpg") //checks the bin folder if no path is provided
    .CipherKey("my_cipher_key")
    .Message("Look at this photo!")
    .ExecuteAsync();
PNFileUploadResult fileUploadResult = fileUploadResponse.Result;
PNStatus fileUploadStatus = fileUploadResponse.Status;
if (!fileUploadStatus.Error && fileUploadResult != null)
{
    Debug.Log(pubnub.JsonPluggableLibrary.SerializeToJsonString(fileUploadResult));
}
else
{
    Debug.Log(pubnub.JsonPluggableLibrary.SerializeToJsonString(fileUploadStatus));

show all 16 lines

Response

{
    "Timetoken":15957709330808500,
    "FileId":"d9515cb7-48a7-41a4-9284-f4bf331bc770",
    "FileName":"cat_picture.jpg"
}

Returns

The SendFile() operation returns a PNResult``<PNFileUploadResult> which contains the following properties:

Property Name	Type	Description
Result	PNFileUploadResult	Returns a PNFileUploadResult object.
Status	PNStatus	Returns a PNStatus object.

PNFileUploadResult contains the following properties:

Property Name	Type	Description
Timetoken	long	Returns a PNFileUploadResult object.
FileId	string	Returns the ID of the file.
FileName	string	Returns the name of the file.

List channel files

Retrieve list of files uploaded to Channel.

Method(s)

pubnub.ListFiles()
    .Channel(string)
    .Limit(int)
    .Next(string)
    .QueryParam(Dictionary<string, object>)
    .Execute(System.Action<PNListFilesResult, PNStatus>)

Parameter	Type	Required	Default	Description
Channel	string	Yes		Channel to get list of files.
Limit	int	Optional	100	Number of files to return.
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.
QueryParam	Dictionary<string, object>	Optional		Dictionary object to pass name/value pairs as query string params with PubNub URL request for debug purpose.
Execute	System.Action	Yes		System.Action of type PNListFilesResult.
ExecuteAsync	None	Optional		Returns Task<PNResult<PNListFilesResult>>.

Basic Usage

PNResult<PNListFilesResult> listFilesResponse = await pubnub.ListFiles()
    .Channel("my_channel")
    .ExecuteAsync();
PNListFilesResult listFilesResult = listFilesResponse.Result;
PNStatus listFilesStatus = listFilesResponse.Status;
if (!listFilesStatus.Error && listFilesResult != null)
{
    Debug.Log(pubnub.JsonPluggableLibrary.SerializeToJsonString(listFilesResult));
}
else
{
    Debug.Log(pubnub.JsonPluggableLibrary.SerializeToJsonString(listFilesStatus));
}

Response

{
    "FilesList":[
    {
        "Name":"cat_picture.jpg",
        "Id":"d9515cb7-48a7-41a4-9284-f4bf331bc770",
        "Size":25778,
        "Created":"2020-07-26T13:42:06Z"
    }],
    "Count":1,
    "Next":null
}

Returns

The ListFiles() operation returns a PNResult<PNListFilesResult> which contains the following properties:

Property Name	Type	Description
Result	PNListFilesResult	Returns a PNListFilesResult object.
Status	PNStatus	Returns a PNStatus object.

PNListFilesResult contains the following properties:

Property Name	Type	Description
FilesList	list<PNFileResult>	List of channel files.
Count	int	Number of files returned.
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.

PNFileResult contains the following properties:

Property Name	Type	Description
Name	string	Name of the file.
Id	string	ID of the file.
Size	int	Size of the file.
Created	string	Create date of the file.

Get File Url

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

Method(s)

pubnub.GetFileUrl()
    .Channel(string)
    .FileId(string)
    .FileName(string)
    .Execute(System.Action<PNFileUrlResult, PNStatus>)

Parameter	Type	Required	Description
Channel	string	Yes	Name of channel within which file with name has been uploaded.
FileId	string	Yes	Unique file identifier which has been assigned during file upload.
FileName	string	Yes	Name under which uploaded file is stored for channel.
Execute	System.Action	Yes	System.Action of type PNFileUrlResult.
ExecuteAsync	None	Optional	Returns Task<PNResult<PNFileUrlResult>>.

Basic Usage

PNResult<PNFileUrlResult> getFileUrlResponse = await pubnub.GetFileUrl()
    .Channel("my_channel")
    .FileId("d9515cb7-48a7-41a4-9284-f4bf331bc770")
    .FileName("cat_picture.jpg")
    .ExecuteAsync();
PNFileUrlResult getFileUrlResult = getFileUrlResponse.Result;
PNStatus getFileUrlStatus = getFileUrlResponse.Status;
if (!getFileUrlStatus.Error && getFileUrlResult != null)
{
    Debug.Log(pubnub.JsonPluggableLibrary.SerializeToJsonString(getFileUrlResult));
}
else
{
    Debug.Log(pubnub.JsonPluggableLibrary.SerializeToJsonString(getFileUrlStatus));
}

Response

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

Returns

The GetFileUrl() operation returns a PNResult<PNFileUrlResult> which contains the following properties:

Property Name	Type	Description
Result	PNFileUrlResult	Returns a PNFileUrlResult object.
Status	PNStatus	Returns a PNStatus object.

PNFileUrlResult contains the following properties:

Property Name	Type	Description
Url	string	URL which can be used to download remote file with specified name and identifier.

Download file

Download file from specified Channel.

Method(s)

pubnub.DownloadFile()
    .Channel(string)
    .FileId(string)
    .FileName(string)
    .Execute(System.Action<PNDownloadFileResult, PNStatus>)

Parameter	Type	Required	Description
Channel	string	Yes	Name of channel within which file with name has been uploaded.
FileId	string	Yes	Unique file identifier which has been assigned during file upload.
FileName	string	Yes	Name under which uploaded file is stored for channel.
Execute	System.Action	Yes	System.Action of type PNDownloadFileResult.
ExecuteAsync	None	Optional	Returns Task<PNResult<PNDownloadFileResult>>.

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

PNResult<PNDownloadFileResult> fileDownloadResponse = await pubnub.DownloadFile()
    .Channel("my_channel")
    .FileId("d9515cb7-48a7-41a4-9284-f4bf331bc770")
    .FileName("cat_picture.jpg")
    .CipherKey("my_cipher_key")
    .ExecuteAsync();
PNDownloadFileResult fileDownloadResult = fileDownloadResponse.Result;
PNStatus fileDownloadStatus = fileDownloadResponse.Status;
if (!fileDownloadStatus.Error && fileDownloadResult != null)
{
    fileDownloadResult.SaveFileToLocal(downloadUrlFileName); //saves to bin folder if no path is provided
    Debug.Log(pubnub.JsonPluggableLibrary.SerializeToJsonString(fileDownloadResult.FileName));
}
else
{

show all 17 lines

Response

{
    //Call fileDownloadResult.SaveFileToLocal(<destination path>) to save file.
    "FileBytes":"/9j/4AAQSkZJRgABAQEAkACQAAD/4RCERXhpZgAATU0AKgAAAAgABAE7AAIAAAAGAAAISodpAAQAAAABAAAIUJydAAEAAAA...<truncated due to lengthy data",
    "FileName":"cat_picture.jpg"
}

Returns

The DownloadFile() operation returns a PNResult<PNDownloadFileResult> which contains the following properties:

Property Name	Type	Description
Result	PNDownloadFileResult	Returns a PNDownloadFileResult object.
Status	PNStatus	Returns a PNStatus object.

PNDownloadFileResult contains the following properties:

Property Name	Type	Description
FileBytes	byte[]	byte array of the downloaded file. Use SaveFileToLocal method to copy file to local.
FileName	string	Name of the downloaded file from channel.
SaveFileToLocal(string)		Provide full destination path to SaveFileToLocal for saving the downloaded file locally.

Delete file

Delete file from specified Channel.

Method(s)

pubnub.DeleteFile()
    .Channel(string)
    .FileId(string)
    .FileName(string)
    .Execute(System.Action<PNDeleteFileResult, PNStatus>)

Parameter	Type	Required	Description
Channel	string	Yes	Name of channel within which file with name needs to be deleted.
FileId	string	Yes	Unique file identifier of the file to be deleted.
FileName	string	Yes	Name of the file to be deleted from the channel.
Execute	System.Action	Yes	System.Action of type PNDeleteFileResult.
ExecuteAsync	None	Optional	Returns Task<PNResult<PNDeleteFileResult>>.

Basic Usage

PNResult<PNDeleteFileResult> deleteFileResponse = await pubnub.DeleteFile()
    .Channel("my_channel")
    .FileId("d9515cb7-48a7-41a4-9284-f4bf331bc770")
    .FileName("cat_picture.jpg")
    .ExecuteAsync();
PNDeleteFileResult deleteFileResult = deleteFileResponse.Result;
PNStatus deleteFileStatus = deleteFileResponse.Status;
if (!deleteFileStatus.Error && deleteFileResult != null)
{
    Debug.Log(pubnub.JsonPluggableLibrary.SerializeToJsonString(deleteFileResult));
}
else
{
    Debug.Log(pubnub.JsonPluggableLibrary.SerializeToJsonString(deleteFileStatus));
}

Response

{}

Returns

The DeleteFile() operation returns a PNResult<PNDeleteFileResult> which contains the following properties:

Property Name	Type	Description
Result	PNDeleteFileResult	Returns a PNDeleteFileResult object.
Status	PNStatus	Returns a PNStatus object.

PNDeleteFileResult returns empty object

Publish file message

Publish file message from specified Channel.

Method(s)

pubnub.PublishFileMessage()
    .Channel(string)
    .FileId(string)
    .FileName(string)
    .Message(object)
    .Meta(Dictionary<string, object>)
    .ShouldStore(bool)
    .Execute(System.Action<PNPublishFileMessageResult, PNStatus>)

Parameter	Type	Required	Default	Description
Channel	string	Yes	n/a	Name of channel to publish file message
FileId	string	Yes	n/a	Unique file identifier of the file.
FileName	string	Yes	n/a	Name of the file.
Message	string	Optional	n/a	The payload.
Meta	string	Optional	n/a	Meta data object which can be used with the filtering ability.
ShouldStore	bool	Optional	true	Store in history.
Execute	System.Action	Yes	n/a	System.Action of type PNPublishFileMessageResult.
ExecuteAsync	None	Optional	n/a	Returns Task<PNResult<PNPublishFileMessageResult>>.

Basic Usage

PNResult<PNPublishFileMessageResult> publishFileMsgResponse = await pubnub.PublishFileMessage()
    .Channel("my_channel")
    .FileId("d9515cb7-48a7-41a4-9284-f4bf331bc770")
    .FileName("cat_picture.jpg") //checks the bin folder if no path is provided
    .Message("This is a sample message")
    .ExecuteAsync();
PNPublishFileMessageResult publishFileMsgResult = publishFileMsgResponse.Result;
PNStatus publishFileMsgStatus = publishFileMsgResponse.Status;
if (!publishFileMsgStatus.Error && publishFileMsgResult != null)
{
    Debug.Log(pubnub.JsonPluggableLibrary.SerializeToJsonString(publishFileMsgResult));
}
else
{
    Debug.Log(pubnub.JsonPluggableLibrary.SerializeToJsonString(publishFileMsgStatus));

show all 16 lines

Response

{
    "Timetoken":15957738720237858
}

Returns

The PublishFileMessage() operation returns a PNResult<PNPublishFileMessageResult> which contains the following properties:

Property Name	Type	Description
Result	PNPublishFileMessageResult	Returns a PNPublishFileMessageResult object.
Status	PNStatus	Returns a PNStatus object.

PNPublishFileMessageResult contains the following properties:

Property Name	Type	Description
Timetoken	long	Returns a long representation of the timetoken when the message was published.