In-Session Communication

The Cordova SDK provides the following methods for obtaining information about the in-session communication:

sendMessage(): To enable session participants to exchange messages.
sendFiles(): To initiate a file transfer to the EnableX server.
cancelUploads(): To cancel an ongoing file upload job.
cancelAllUploads(): To cancel all ongoing file upload job.
getAvailableFiles(): To get all files that are available for download.
downloadFile(): To initiate the file downloading process individually.
cancelDownloads(): To cancel the ongoing file download job.
cancelAllDownloads(): To cancel all the ongoing file download job.
sendUserData(): To send customized data adhering to a structure which is not bound by the EnableX message structure.
startAnnotation(): To start annotation on a given stream object.
stopAnnotation(): To stop annotation.
addScreenShare(): To start a screen sharing process.
removeScreenShare(): To stop the ongoing screen sharing process.
addCanvasScreen(): To start the canvas streaming.
removeCanvasScreen(): To stop the canvas streaming.

Chat

Messaging is an advanced feature between session participants. It allows to exchange the following types of messages among session participants:

Public Messaging: To send messages to all connected users.
Private Messaging: To send messages to a specific user.
Group Messaging: To send messages to more than one user.

The Messaging feature does not require the sender of a message to publish the local stream or the receiver of the message to subscribe to a remote stream.

Method: sendMessage( message, isBroadcast, recipientIDs )
Parameters:
- message : String. Text message to be sent.
- isBroadcast : Boolean. Set it to true for public broadcast. Set it to false for private messaging to one or more recipients.
- recipientIDs : Array. Array of Client IDs to receive messages. Applicable for group and private messaging.
Event Listeners:
- onAcknowledgedSendData : Notification to everyone when the message is successfully sent to another user or group of users.
- onMessageReceived : Notification at the receivers end that a new message has arrived.

Sample Code

// To send message
message = "hi";
var broadcast = true;		// For public messaging
Var broadcast = false;		// For private messaging.
var recipients = [];		// For public messaging 
Var recipients = [client_id];	// For private & group messaging.

// To send, call Method
window.EnxRtc.sendMessage( message,true,array); 

// To receive acknowledgement 
window.EnxRtc.addEventListner("onAcknowledgedSendData", function(data) {
	console.log(JSON.stringify(data.data));
});

// To receive incoming message
window.EnxRtc.addEventListner("onMessageReceived",function(data) {
	console.log(JSON.stringify(data.data));
});

The following APIs allow users in an RTC session to send and receive files with each other. Users can also initiate a file transfer, cancel a file transfer, be notified of the availability of a file for download, and receive and download a shared file.

The window.EnxRtc.sendFiles() method initiates a file transfer to the EnableX server.

Method: sendFiles( isBroadcast, recipientIDs)
Parameters:
- isBroadcast : Boolean. Set it to true to share a file between all the participants in the session.
  Set it to false to share a file to the specific user.
- recipientIDs : Array. List of ClientIDs.
  This is to share the file among specified clients only.
  If broadcast is set to true, recipientIDs is ignored.
Event Listeners: (At Sender's End)
- onInitFileUpload : Notification to the sender that the file upload process has been initiated.
- onFileUploaded : Notification to the sender that the file has been uploaded.
- onFileUploadFailed : Notification to the sender that the file upload process has failed.
Event Listeners: (At Receive's End)
onFileUploadStarted : Not Applicable. JSON Object. Notification to the intended receiver that a file is being uploaded.
onFileAvailable : Not Applicable. JSON Object. Notification to the intended receiver that a file is ready to download.

Sample Code

var broadcast = true;		// For public messaging
Var broadcast = false;		// For private messaging.
var recipients = [];		// For public messaging 
Var recipients = [client_id];	// For private & group messaging.

// To send file, call Method
window.EnxRtc.sendFiles(broadcast, array);

// Event Listeners - at Receiver's end

// A new file upload started
window.EnxRtc.addEventListner("onFileUploadStarted", function(data){
	console.log(JSON.stringify(data.data));
});

//A file is avilable for download
window.EnxRtc.addEventListner("onFileAvailable", function(data) {
	console.log(JSON.stringify(data.data));
});

// Event Listeners - at Sender's end

// File upload process has initialized.
window.EnxRtc.addEventListner("onInitFileUpload", function(data) {
	console.log(JSON.stringify(data.data));
});

// File upload is complete.
window.EnxRtc.addEventListner("onFileUploaded", function(data) {
	console.log(JSON.stringify(data.data));
});

// File upload has failed.
window.EnxRtc.addEventListner("onFileUploadFailed", function(data) {
	console.log(JSON.stringify(data.data));
});

Note: If the upload process encounter errors, refer to the following error codes to troubleshoot them:

Error Codes

Error Code	Description
5089	Storage access denied.
5091	File-Sharing is not available in this context.
1185	The file is too large. The maximum allowed size is NNNN.
1182	Failed to upload the file.

Cancel a File Upload

The cancelUpload() method is used to cancel the file uploading process.

Method: cancelUpload(jobId)
Parameters:
- jobId : String. The ID of the job to be canceled.
Event Listeners:
- onFileUploadCancelled : Notification when the file upload has been canceled successfully.

Sample Code

// To cancel single uploading file
window.EnxRtc.cancelUpload(jobId);

// Add Event Listeners
// File uploading is canceled
window.EnxRtc.addEventListner(" onFileUploadCancelled ", function(data) {
	console.log(JSON.stringify(data.data));
});

Cancel All Uploaded Files

The cancelAllUploads() method is used to cancel all the file uploading process.

Method: cancelAllUploads()
Event Lisnteners:
- onFileUploadCancelled : Notification to the user when the file upload has been canceled successfully.

Sample Code

// To cancel all uploading file
window.EnxRtc.cancelAllUploads();

// Add Event Listeners
// File uploading is cancelled.
window.EnxRtc.addEventListner(" onFileUploadCancelled ", function(data){
	console.log(JSON.stringify(data.data));
});

Download a Shared File

The process of downloading a shared file comprises of two steps:

Know about the files available for download.
Initiate the download of the available files.

Locate the Files available for Download

The window.EnxRtc.getAvailableFiles() method is used to get all files that are available for download. It returns an array of JSON objects carrying file information.

Method: getAvailableFiles( successCallback, errorCallback )
Paramters:
- successCallback: Callable Function. Success Notification.
- errorCallback: Callable Function. Error Notification.

Sample Code

window.EnxRtc.getAvailableFiles(function(data) {
		console.log('Excelsior success! ' + JSON.stringify(data.data));
	}, function(err) {
		console.log('Uh oh… error' + JSON.stringify(err));
	}
);

When a new file is available for download, the receiving endpoint is notified through the onFileAvailable event listener.

Initiate a File Download

The window.EnxRtc.downloadFile() method initiates the file download when the information about the downloadable file is available.

Method: downloadFile( fileInfo, isAutoSave )
Paramters:
- fileInfo : JSON Object. Map of the file to download.
- isAutoSave : Boolean. Whether to save the file automatically
  If the file is not saved automatically then the user receives Base64 encoded raw data to handle file saving processes manually.
  If auto-saving is on then the user receives the saved file path.
Event Listeners: (At Receiver's End)
- onInitFileDownload : Notification to the user that the file download process has been initiated.
- onFileDownloaded : Notification that the file is downloaded with either Base64 raw data to be saved (When auto-saving is false) or saved file path.
- OnFileDownloadFailed : Notification to the user that the downloading is failed.

Sample Code

// To download
window.EnxRtc.downloadFile(fileInfo, isAutoSave);

// Add Event Listeners (For intended receivers)
// File download process has initialized
window.EnxRtc.addEventListner(" onInitFileDownload ", function(data) {
	console.log(JSON.stringify(data.data));
});

// File download has failed
window.EnxRtc.addEventListner("onFileDownloadFailed", function(data) {
	console.log(JSON.stringify(data.data));
});

// File has been downloaded
window.EnxRtc.addEventListner("onFileDownloaded", function(data) {
	console.log(JSON.stringify(data.data));
});

Error Codes

The download process may encounter an error that shall send the notification with a JSON object containing one of the following error codes:

Error Code	Description
5089	Storage access denied.
5090	Failed to save file.
1183	Failed to download file.
1181	File download not available in this context.

Cancel a File Download

The window.EnxRtc.cancelDownload() method allows you to cancel an ongoing file download job running at your endpoint.

Method: cancelDownload (jobId)
Parameters:
- jobId : String. Job ID that is to be canceled.
Event Listeners:
- onFileDownloadCancelled : Notification to the user when the file download is canceled.

Sample Code

// To cancel downloading file
window.EnxRtc.cancelDownload(jobId);

// Add Event Listeners
// File downloading is cancelled
window.EnxRtc.addEventListner("onFileDownloadCancelled", function(data) {
	console.log(JSON.stringify(data.data));
});

Cancel all Downloaded Files

The window.EnxRtc.cancelAllDownloads() allows you to cancel all ongoing file download job running at your endpoint.

Method: cancelAllDownloads()
Event Listeners: (At Receiver's End)
- onFileDownloadCancelled: Notification to the user when the file downloading is canceled.

Sample Code

// To cancel all downloading file
window.EnxRtc.cancelAllDownloads();

// Add Event Listeners (At intended receivers)
// File downloading is cancelled.
window.EnxRtc.addEventListner("onFileDownloadCancelled", function(data) {
	console.log(JSON.stringify(data.data));
});

Custom Signaling

Your application might need to send instructions and data to one or more recipients connected in a session to deploy new features and business workflow. For example, if you want to create a polling mechanism among participants, EnableX supports the custom signalling method through which you can build such a utility that requires passing messages among participants.

Using custom signaling method, you might send messages to all or selected participants in a room. You can define your custom data structure to pass to meet your business requirement.

Method: sendUserData( message, isBroadcast, RecipientIDs )
Parameters:
- message : JSON Object. It contains keys like sender, message, and custom_key. This object is passed to recipients in its original form. EnableX doesn't enforce its structure. Be advised to define keys effectively for signaling needs.
  - sender: String. Sender Name
  - message : Sgtring. Message body
  - custom_key : String. Your own custom data. You can add any key name to define your data. You can add multiple keys.
- isBroadcast : Boolean. Set it to true for public broadcast. Set it to false for signaling to one or more recipients.
- recipientIDs : Array. Array of Client IDs to receive signal. Applicable for group and private signalling.
**Event Listerners:
- onReceivedChatDataRoom : Receives signaling in JSON Object.
- onUserDataReceived : Receives signaling in a JSON object.

Sample Code

// To send message
message = {			// Signalling Content
	"sender": "John",
	"message": "Voting for you",
	"candidate": 5
	"rating": 3
};
var broadcast = true;		// For public signalling
Var broadcast = false;		// For private signalling
var recipients = [];		// For public signalling 
Var recipients = [client_id];	// For private & group signalling

window.EnxRtc.sendUserData( message, broadcast, recipients);

// Add Event Listeners
window.EnxRtc.addEventListner("onAcknowledgedSendData", function(data) {
	console.log(JSON.stringify(data.data));
});

window.EnxRtc.addEventListner("onUserDataReceived",function(data) {
	console.log(JSON.stringify(data.data));
});

Annotations

Start Annotation

The startAnnotation() method is sued to start annotation on a remote stream.

Method: startAnnotation( clientId )
Parameters:
- clientid: String. The client ID on which the stream needs to be annotated.
Event Listeners:
- onStartAnnotationAck : Acknowledgment to the annotator that the annotation has started.
- onAnnotationStarted : Notification to all the participants an the room that the annotation has started.

Sample Code

window.EnxRtc.startAnnotation( clientId );

// Add Event Listener: Acknowledgement of starting
window.EnxRtc.addEventListner("onStartAnnotationAck", function(data) {
	console.log(JSON.stringify(data.data));
});

// Add Event Listener: Notification to others on starting
window.EnxRtc.addEventListner("onAnnotationStarted",function(data) {
	console.log(JSON.stringify(data.data));
});

Stop Annotation

The stopAnnotation() method is used to stop annotation on a remote stream.

Method: stopAnnotation()
Event Listeners:
- onStoppedAnnotationAck : Acknowledgment to the annotator that the annotation has stopped.
- onAnnotationStopped : Notification to all the participants in the room that the annotation has stopped.

Sample Code

window.EnxRtc.stopAnnotation();

// Add Event Listener: Acknowledgement of stopping
window.EnxRtc.addEventListner("onStoppedAnnotationAck", function(data) {
	console.log(JSON.stringify(data.data));
});

// Add Event Listener: Notification to others on stopping
window.EnxRtc.addEventListner("onAnnotationStopped",function(data) {
	console.log(JSON.stringify(data.data));
});

The window.EnxRtc.addScreenShare() method is used to start screen sharing at a client endpoint. This method creates a stream of Mobile Screen @ 6fps to publish to the room.

When the screen sharing starts, other connected users receive a notification with onScreenSharedStarted listener.

As screen-sharing is also a Stream, you can play it using a video player. Screen sharing carries on stream ID# 101. Client endpoint must subscribe to this stream ID to receive and play it.

Note: To support screen sharing in a room, define your room with { settings: { screen_share: true; }} in the JSON payload to create a room. For detail in Room Creation API.

Method: addScreenShare( viewOptions, successCallback, errorCallback )
Parameters:
- viewOptions: JSON Object. View Settings.
  - height: Number. View Height.
  - width: Number. View Width.
  - margin_top: Number. Top Margin. Not Applicable.
  - margin_bottom: Number. Bottom Margin. Not Applicable.
  - margin_left: Number. Left Margin. Not Applicable.
  - margin_right: Number. Right Margin. Not Applicable.
  - position: String. Not Applicable.
- successCallback: Callable Function. Success Notification.
- errorCallback: Callable Function. Error Notification.
Event Listeners:
- onScreenSharedStarted: Notifies all users that the presenter has started Screen Share.

Sample Code

var ViewOptions = {
	height: 130,
	width: 100,
	margin_top: 50,
	margin_left: 0,
	margin_right: 15,
	margin_bottom: 10,
	position: "top"
};

// Start Screen Share
window.EnxRtc.addScreenShare(options, function(data) {
		console.log('Excelsior succuss! ' + JSON.stringify(data.data));
	}, function(err) {
		console.log('Uh oh… error' + JSON.stringify(err));
	}
);

// Add Event Listener: Share has started 
window.EnxRtc.addEventListner("onScreenSharedStarted", function(data) {
	console.log(JSON.stringify(data.data));
	addScreenShare();
});

The window.EnxRtc.removeScreenShare() method stops the ongoing screen sharing. Screen share continues even when the application goes into the background.

When screen sharing starts or stops by the user, other connected users receive a notification with onScreenSharedStopped listeners. As screen sharing is also a stream, you can play it using a video player. Screen sharing carries on a stream ID# 101. Client endpoint must subscribe to this stream ID to receive and play it.

Method: removeScreenShare( successCallback, errorCallback )
Parameters:
- successCallback: Callable Function. Success Notification.
- errorCallback: Callable Function. Error Notification.
Event Listeners:
- onScreenSharedStopped: Notification to all the participants in the room that screen sharing has stopped. To remove the shared screen from the room, call the removeScreenShare() method inside this event listener.

Sample Code

// To Remove Screen Share
window.EnxRtc.removeScreenShare(function(data) {
		console.log('Excelsior succuss! ' + JSON.stringify(data.data));
	}, function(err) {
		console.log('Uh oh… error' + JSON.stringify(err));
	}
);

// Add Event Listener: Share has stopped
window.EnxRtc.addEventListner("onScreenSharedStopped", function(data) {
	console.log(JSON.stringify(data.data));
	removeScreenShare(); // Stop Screen Share
});

Canvas Streaming

Start Canvas Streaming

Canvas Streaming helps you to publish any UIView into the room. The addCanvasScreen() method is used to start the canvas streaming.

Note:

You need to enable a room to use canvas streaming in it. To enable canvas streaming, use { settings: { canvas: true; }} in the JSON payload to create a room.
Canvas streaming is carried on Stream ID# 102. The client endpoint must subscribe to this stream ID to receive and play it.
Method: addCanvasScreen( viewOptions, successCallback, errorCallback )
Parameters:
- viewOptions: JSON Object. View Settings.
  - height: Number. View Height.
  - width: Number. View Width.
  - margin_top: Number. Top Margin. Not Applicable.
  - margin_bottom: Number. Bottom Margin. Not Applicable.
  - margin_left: Number. Left Margin. Not Applicable.
  - margin_right: Number. Right Margin. Not Applicable.
  - position: String. Not Applicable.
- successCallback: Callable Function. Success Notification.
- errorCallback: Callable Function. Error Notification.

Sample Code

var options = {
	height: 130,
	width: 100,
	margin_top: 50,
	margin_left: 0,
	margin_right: 15,
	margin_bottom: 10,
	position: "top"
};

// Start Canvas Streaming
window.EnxRtc.addCanvasScreen(options, function(data) {
		console.log('Excelsior succuss! ' + JSON.stringify(data.data));
	}, function(err) {
		console.log('Uh oh… error' + JSON.stringify(err));
	}
);

// Add Event Listener: Canvas Streaming has started
window.EnxRtc.addEventListner("onCanvasStarted", function(data) {
	console.log(JSON.stringify(data.data));
	addCanvasScreen();			// Add Canvas
});

Stop Canvas Streaming

The removeCanvasScreen() method is used to stop canvas streaming.

Method: removeCanvasScreen( successCallback, errorCallback )
Parameters:
- successCallback: Callable Function. Success Notification.
- errorCallback: Callable Function. Error Notification.
Event Listeners:
- onCanvasStopped: Notification to all the participants in the room that the canvas has stopped. To remove the canvas, call removeCanvasScreen() method inside this event listener.

Sample Code

// To Remove Canvas
window.EnxRtc.removeCanvasScreen(function(data) {
		console.log('Excelsior succuss! ' + JSON.stringify(data.data));
	}, function(err) {
		console.log('Uh oh… error' + JSON.stringify(err));
	}
);

// Add Event Listener: Canvas Streaming has stopped
window.EnxRtc.addEventListner("onCanvasStopped",function(data){
	console.log(JSON.stringify(data.data));
	removeCanvasScreen();	// Remove Canvas Stream View
});

Get Room Information Session Management

In-Session Communication

Chat

File Sharing

Upload a File for Sharing

Cancel a File Upload

Cancel All Uploaded Files

Download a Shared File

Locate the Files available for Download

Initiate a File Download

Cancel a File Download

Cancel all Downloaded Files

Custom Signaling

Annotations

Start Annotation

Stop Annotation

Screen Sharing

Start Screen Sharing

Stop Screen Sharing

Canvas Streaming

Start Canvas Streaming

Stop Canvas Streaming