Availability: Web Toolkit v1.5.3+
The following APIs allow users in an RTC session to send and receive file(s) with each other. Using these APIs, you can initiate a file transfer, cancel a file transfer, be notified of the availability of a file for download, and receive/download a shared file.
Table of Contents
Upload File to share
The EnxRoom.sendFiles() method is used to initiate a file transfer to EnableX Server.
Method: EnxRoom.sendFiles(files, options, callback)
Parameters:
files– FileList. An array of File Type Objects. This object is returned by the files property of the HTML<input>element that lets you access the list of files selected with the<input type="file">element. For more details check this.options– JSON Object. This to define file sharing process, scope of file transfer etc. Following keys may be used:isMobile–Boolean. Default: false. Set to true to develop Web View based Mobile Apps.broadcast–Boolean. Default: true. The value true allows you to share file with all the users in the Session. Set to false to share the file with specific user(s).clientList– Array of Client IDs who are intended to receieve the file(s).Ifbroadcastis set to true,clientListis ignored.
callback– To receive the status response ofsendFiles()method.
Event Listener:
fs-upload-result – Notification to the Sender on the file upload process such as when the file upload starts, completes or fails.
var clientList = [];
var shareOptions = {
"isMobile": false,
"broadcast": true,
"clientList": clientList
};
room.sendFiles(FileList, shareOptions, functions(resp) {
if (resp.result == "0") { // Success JSON Example given below
} else { // Error JSON Example given below
}
});
room.addEventListener('fs-upload-result', function (event) {
var msg = event.message;
switch (msg.messageType) {
case 'upload-started':
// Note msg.upJobId for management
// upload-started event JSON Example given below
break;
case 'upload-completed':
// Know msg.upJobId is completed
// upload-completed event JSON Example given belowbreak;
break;
case 'upload-failed':
// Know msg.upJobId has failed
// upload-failed event JSON Example given belowbreak;
break;
default:
break;
}
});
Success JSON on sendFiles() Callback:
{
messageType: 'upload-completed',
result: 0,
description: 'upload completed',
response: {
uploadStatus: 'completed',
upJobId: 1, // #ID of the File Upload Job
uploadInfo: { // SDK May provide additional information
upJobId: 1,
name: 'xyz.txt',
size: 100, // in bytes
type: text, // type of the file
}
}
}
Error JSON on sendFiles() Callback:
{
"result": 1185, // A non zero error code
"error": "file upload failed ", // error
"desc": "file upload failed because file list is empty"
}
Event fs-upload-result – upload-started status JSON
{
messageType: "upload-started",
result: 0,
description: "upload started",
response: {
uploadStatus: "started",
upJobId: 1,
uploadInfo: {
upJobId: 1
name: "ks (9).txt"
size: 168
type: "text/plain"
}
}
}
Event fs-upload-result – upload-completed status JSON
{
messageType: "upload-completed",
result: 0,
description: "upload completed",
response: {
uploadStatus: "completed",
upJobId: 1,
uploadInfo: {
upJobId: 1
name: "ks (9).txt"
size: 168
type: "text/plain"
}
}
}
Event fs-upload-result – upload-failed status JSON
{
messageType: "upload-failed",
result: 1185,
description: "upload failed",
response: {
uploadStatus: "failed",
upJobId: 1,
uploadInfo: {
upJobId: 1
name: "ks (9).txt"
}
}
}
Download shared File
The process of downloading shared file(s) comprises two steps:
- Know file(s) available for download.
- Initiate download on the available file(s).
Know files available for download
Room Lookup: Get the files available for download using roomObject.availableFiles, an array of JSON objects carrying file information.
let myFiles = room.availableFiles;
// myFile contains array of File Information
[
{
name: "DP1.pdf",
size: 191002,
index: 0 // ID or File Reference
}
]
When a New File is available: The intended receiver is notified via the event fs-download-result with event.message.messageType='download-available', when a file is available for download.
room.addEventListener('fs-download-result', function (event) {
var msg = event.message;
switch (msg.messageType) {
case 'download-available':
// Look for JSON Object for file infomration
break;
}
});
Initiate File Download
The EnxRoom. method is used to initiate the file download using the file information received above.recvFiles()
Class: EnxRoom
Method: EnxRoom.recvFiles(index, options, callback)
Parameters:
index– ID of the file to be downloaded.options– JSON Object to define file download process. The JSON keys are given below:isMobile–Boolean. Default: false. Set to true to develop Web View based Mobile Apps.
callback– To receive the status response of the method.
Event Listener:
fs-download-result – Notification to the Receiver on the file download process such as when the file download starts, completes or fails.
let myFiles = room.availableFiles;
room.recvFiles(myFiles[0].index, {}, function(resp){
if (resp.result == "0") { // Success JSON Example given below
} else { // Error JSON Example given below
}
});
room.addEventListener('fs-download-result', function (event) {
var msg = event.message;
switch (msg.messageType) {
case 'download-started':
// Note msg.jobId for cancellation
// download-started event JSON Example given below
break;
case 'download-completed':
// Know msg.jobId is completed
// download-completed event JSON Example given belowbreak;
break;
case 'download-failed':
// Know msg.jobId has failed
// download-failed event JSON Example given belowbreak;
break;
default:
break;
}
});
Success JSON on recvFiles() Callback
{
messageType: 'download-success',
result: 0, // Succes
description: 'download-success',
response: { // SDK May provide additional information
downloadStatus: 'success',
name: xyz.txt,
type: text,
size: 100 // in bytes
}
}
Error JSON on recvFiles() Callback
{
"result": 1180, // A Non-Zero error code
"error": "room is disconected",
"desc": "File sharing is not allowed on disconnected rooms"
}
Event fs-download-result – download-started status JSON
{
messageType: "download-started",
result: 0, // Success
description: "download-started",
response: {
downloadStatus: "started",
jobId: "0", // Job ID for downloads in progress
downloadInfo: { // SDK May provide additional information
name: "ks (4).txt",
size: 168, // In bytes
index: 0,
}
}
}
Event fs-download-result – download-completed status JSON
{
messageType: "download-completed",
result: 0, // Success
description: "download-completed",
response: {
downloadStatus: "completed",
jobId: "0", // Job ID for completed download
downloadInfo: { // SDK May provide additional information
name: "ks (4).txt",
size: 168, // In bytes
index: 0
}
}
}
Event fs-download-result – download-failed status JSON
{
messageType: "download-failed",
result: 0, // failed
description: "download-failed",
response: {
downloadStatus: "failed",
jobId: "0", // Job ID for completed download
downloadInfo: { // SDK May provide additional information
name: "ks (4).txt",
size: 168, // In bytes
index: 0
}
}
}
Cancel File Upload
The EnxRoom.cancelUploads() method allows you to cancel an ongoing file upload job initiated by you.
Method: EnxRoom.cancelUploads(id, cancelAll, callback)
Parameters:
id–Numeric. upJobId of the file being uploaded. This Id is received viasendFiles()method.cancelAll–Boolean. Default: false. Set to true to cancel all file uploads.callback– To receive status of cancelation request.
room.cancelUploads(id, false, function(resp) {
// Handle response here
});
Cancel File Download
The EnxRoom.cancelDownloads() allows you to cancel the ongoing file download job taking place at your endpoint.
Class: EnxRoom
Method: EnxRoom.cancelDownloads(id, cancelAll, callback)
Parameters:
id–Numeric.jobIdof the file being downloaded. This jobId is received viarecvFiles()method.cancelAll–Boolean. Default: false. Set to true to cancel all files being downloaded.callback– To receive status of the cancelation request.
room.cancelDownloads(id, false, function(resp) {
// Handle response here
});