File Sharing API for 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 the file to a specified channel.

This method covers the entire process of sending a file, including preparation, uploading the file to a cloud storage service, and post-uploading messaging on a channel.

For the last messaging step, SendFile internally calls the PublishFileMessage method to publish a message on the channel.

The published message contains metadata about the file, such as the file identifier and name, enabling others on the channel to find out about the file and access it.

Method(s)​

pubnub.SendFile()
    .Channel(string)
    .File(string|byte[])
    .Texture(Texture2D | RenderTexture)
    .FileName(string)
    .Ttl(int)
    .ShouldStore(bool)
    .Message(string)
    .Meta(Dictionary<string, object>)
    .CustomMessageType(string)
    .Execute(System.Action<PNFileUploadResult, PNStatus>)
* required
ParameterDescription
Channel *
Type: string
Channel for the file.
File
Type: string or byte[]
Full path of the file with file name or an array of bytes.
When using an array of bytes, you must set FileName.
Texture
Type: Texture2D or RenderTexture
An instance of a Texture object. When you send a Texture, a Message with its size and format is added automatically.
FileName
Type: string
Name of the file to send. You can use it to override the default file name.
TtL
Type: int
How long message should be stored in channel's storage.
ShouldStore
Type: bool
Whether PubNub published file message should be stored in channel history.
Message
Type: string
Message which should be sent along with file to specified channel.
Meta
Type: Dictionary<string, object>
Dictionary<string, object> with values which should be used by PubNub service to filter file messages.
CustomMessageType
Type: string
A case-sensitive, alphanumeric string from 3 to 50 characters describing the business-specific label or category of the message. Dashes - and underscores _ are allowed. The value cannot start with special characters or the string pn_ or pn-.

Examples: text, action, poll.
Execute *
Type: System.Action
System.Action of type PNFileUploadResult.
ExecuteAsync
Type: None
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!")
    .CustomMessageType("file-message")
    .ExecuteAsync();
PNFileUploadResult fileUploadResult = fileUploadResponse.Result;
PNStatus fileUploadStatus = fileUploadResponse.Status;
if (!fileUploadStatus.Error && fileUploadResult != null)
{
    Debug.Log(pubnub.JsonPluggableLibrary.SerializeToJsonString(fileUploadResult));
}
else
{
show all 17 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 NameTypeDescription
Result
PNFileUploadResult
Returns a PNFileUploadResult object.
Status
PNStatus
Returns a PNStatus object.

PNFileUploadResult contains the following properties:

Property NameTypeDescription
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>)
* required
ParameterDescription
Channel *
Type: string
Default:
n/a
Channel to get list of files.
Limit
Type: int
Default:
100
Number of files to return.
Next
Type: string
Default:
n/a
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
Type: Dictionary<string, object>
Default:
n/a
Dictionary object to pass name/value pairs as query string params with PubNub URL request for debug purpose.
Execute *
Type: System.Action
Default:
n/a
System.Action of type PNListFilesResult.
ExecuteAsync
Type: None
Default:
n/a
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 NameTypeDescription
Result
PNListFilesResult
Returns a PNListFilesResult object.
Status
PNStatus
Returns a PNStatus object.

PNListFilesResult contains the following properties:

Property NameTypeDescription
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 NameTypeDescription
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>)
* required
ParameterDescription
Channel *
Type: string
Name of channel within which file with name has been uploaded.
FileId *
Type: string
Unique file identifier which has been assigned during file upload.
FileName *
Type: string
Name under which uploaded file is stored for channel.
Execute *
Type: System.Action
System.Action of type PNFileUrlResult.
ExecuteAsync
Type: None
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 NameTypeDescription
Result
PNFileUrlResult
Returns a PNFileUrlResult object.
Status
PNStatus
Returns a PNStatus object.

PNFileUrlResult contains the following properties:

Property NameTypeDescription
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>)
* required
ParameterDescription
Channel *
Type: string
Name of channel within which file with name has been uploaded.
FileId *
Type: string
Unique file identifier which has been assigned during file upload.
FileName *
Type: string
Name under which uploaded file is stored for channel.
Execute *
Type: System.Action
System.Action of type PNDownloadFileResult.
ExecuteAsync
Type: None
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 NameTypeDescription
Result
PNDownloadFileResult
Returns a PNDownloadFileResult object.
Status
PNStatus
Returns a PNStatus object.

PNDownloadFileResult contains the following properties:

Property NameTypeDescription
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>)
* required
ParameterDescription
Channel *
Type: string
Name of channel within which file with name needs to be deleted.
FileId *
Type: string
Unique file identifier of the file to be deleted.
FileName *
Type: string
Name of the file to be deleted from the channel.
Execute *
Type: System.Action
System.Action of type PNDeleteFileResult.
ExecuteAsync
Type: None
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 NameTypeDescription
Result
PNDeleteFileResult
Returns a PNDeleteFileResult object.
Status
PNStatus
Returns a PNStatus object.

PNDeleteFileResult returns empty object

Publish file message​

Publish the uploaded file message to a specified channel.

This method is called internally by SendFile as part of the file-sending process to publish the message with the file (already uploaded in a storage service) on a channel.

This message includes the file's unique identifier and name elements, which are needed to construct download links and inform channel subscribers that the file is available for download.

You can call this method when SendFile fails and returns the status.operation === PNPublishFileMessageOperation error. In that case, you can use the data from the status object to try again and use PublishFileMessage to manually resend a file message to a channel without repeating the upload step.

Method(s)​

pubnub.PublishFileMessage()
    .Channel(string)
    .FileId(string)
    .FileName(string)
    .Message(object)
    .Meta(Dictionary<string, object>)
    .ShouldStore(bool)
    .CustomMessageType(string)
    .Execute(System.Action<PNPublishFileMessageResult, PNStatus>)
* required
ParameterDescription
Channel *
Type: string
Default:
n/a
Name of channel to publish file message
FileId *
Type: string
Default:
n/a
Unique file identifier of the file.
FileName *
Type: string
Default:
n/a
Name of the file.
Message
Type: string
Default:
n/a
The payload.
Meta
Type: string
Default:
n/a
Meta data object which can be used with the filtering ability.
ShouldStore
Type: bool
Default:
true
Store in history.
CustomMessageType
Type: string
Default:
n/a
A case-sensitive, alphanumeric string from 3 to 50 characters describing the business-specific label or category of the message. Dashes - and underscores _ are allowed. The value cannot start with special characters or the string pn_ or pn-.

Examples: text, action, poll.
Execute *
Type: System.Action
Default:
n/a
System.Action of type PNPublishFileMessageResult.
ExecuteAsync
Type: None
Default:
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")
    .CustomMessageType("file-message")
    .ExecuteAsync();
PNPublishFileMessageResult publishFileMsgResult = publishFileMsgResponse.Result;
PNStatus publishFileMsgStatus = publishFileMsgResponse.Status;
if (!publishFileMsgStatus.Error && publishFileMsgResult != null)
{
    Debug.Log(pubnub.JsonPluggableLibrary.SerializeToJsonString(publishFileMsgResult));
}
else
{
show all 17 lines

Response​

{
    "Timetoken":15957738720237858
}

Returns​

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

Property NameTypeDescription
Result
PNPublishFileMessageResult
Returns a PNPublishFileMessageResult object.
Status
PNStatus
Returns a PNStatus object.

PNPublishFileMessageResult contains the following properties:

Property NameTypeDescription
Timetoken
long
Returns a long representation of the timetoken when the message was published.
Last updated on
On this page