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).Ifbroadcast
is set to true,clientList
is 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
.jobId
of 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 });