File Share: Web SDK – Video API

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.

Upload File to Share
Download File
Initiate File Download
Cancel File Upload
Cancel File Download

Upload File to share

The EnxRoom.sendFiles() method is used to initiate a file transfer to Video 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).If broadcast is set to true, clientList is ignored.
callback – To receive the status response of sendFiles() 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.recvFiles() method is used to initiate the file download using the file information received above.

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 via sendFiles() 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 via recvFiles() 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
});

← Send Message

Index

Screen Share →

Table of Contents

Upload File to share

Download shared File

Know files available for download

Initiate File Download

Cancel File Upload

Cancel File Download