6 Setting Up Data Transfers in Your Applications

This chapter shows how you can use the Oracle Communications WebRTC Session Controller JavaScript application programming interface (API) library to send and receive data over the data channel established in calls from your applications, when your applications run on WebRTC-enabled browsers.

Note:

See WebRTC Session Controller JavaScript API Reference for more information on the individual WebRTC Session Controller JavaScript API classes.

About Data Transfers and Signaling Engine

The WebRTC Session Controller JavaScript data transfer API sets up peer to peer data channels based on the WebRTC data channel definition and manages the workflow of the message exchanges such as chat sessions in web applications.

The data being transferred could be a raw data object such as a binary large object (BLOB), DOMString, ArrayBuffer, ArrayBufferView. The WebRTC Session Controller JavaScript API library manages the data transfer only. It does not access the contents of the data object that it transfers.

This chapter describes how you can use the WebRTC Session Controller JavaScript API library to set up and manage call sessions that support data transfers by managing the flow of the data element in the communication, detecting changes in the data flow state, and responding accordingly to the changes.

About Setting Up Data Transfers in Your Applications

The WebRTC Session Controller JavaScript API related to data transfers support text-based communications such as text messaging and chat sessions when data channels are configured in calls connecting browser phones located on web applications hosted at other WebRTC-enabled browsers.

To support data transfers, do the following in your application:

• Set up the required user interface elements, such as for the chat session to display optimally on the application page.

• Enable users to make or receive data transfers in calls.

• Manage calls with data transfers by doing the following:

  • Monitoring the state of the data channel.

  • Handling the incoming data; and displaying it, if necessary.

  • Sending the data object provided by the user.

• Adjust the display elements when the call with data transfer ends.

About the API Used to Manage the Transfer of Data

The following WebRTC Session Controller JavaScript API classes are used to manage the transfer of data in calls made from or received by your web application:

• The dataChannelConfigs parameter associated with the CallConfig class

• The CallPackage.onIncomingCall event handler

• The Call.onDataTransfer event handler

• The data transfer object, wsc.DataTransfer. See "Managing Data Channels Using wsc.DataTransfer".

• The data sender object, wsc.DataSender. See "Sending Data Using wse.DataSender".

• The data receiver object, wsc.DataReceiver. See "Handling Incoming Data Using wsc.DataReceiver".

Managing Data Channels Using wsc.DataTransfer

Set up an instance of the data transfer object, wsc.DataTransfer, to manage data channels between two peers. Table 6-1 lists its states.

Table 6-1 Data Transfer States

Setting for State	Description
none	The DataTransfer object has been created but no data channel has been established or is initializing.
starting	The data channel of DataTransfer object is initializing or is in negotiation to be established.
open	The data channel of DataTransfer object is established. The data channel is ready to send or receive data and data transfers can take place.
closed	The data channel of the DataTransfer object is closed.

Obtain information on the state of the data transfer object using the following:

• DataTransfer.getReceiver()

  This method returns data on the receiver as an instance of the DataReceiver class.

• DataTransfer.onOpen

  This event handler is invoked when the data channel of the DataTransfer object is open. Data can be sent over or received from the data channel. Assign and define a callback function to this event handler.

• DataTransfer.onClose

  This event handler is invoked when the data channel of the DataTransfer object is closed. Data cannot be transferred. Assign and define a callback function to this event handler.

• DataTransfer.onError

  This event handler is invoked when the data channel of the DataTransfer object has an error. Assign and define a callback function to this event handler.

See WebRTC Session Controller JavaScript API Reference for more information on the wsc.DataTransfer class.

Sending Data Using wse.DataSender

Use the wsc.DataSender class object to send raw data.

Obtain the DataSender object from the DataTransfer object by calling the application's DataTransfer.getSender method. This method returns the DataSender object to your application.

Use the DataSender.send method to send raw data such as a text string or a BLOB using the data channel in the data transfer object.

Handling Incoming Data Using wsc.DataReceiver

Use the wsc.DataReciever class object to handle incoming raw data.

Obtain the DataReceiver object from the DataTransfer object by calling the application's DataTransfer.getReceiver method. This method returns the DataReceiver object to your application.

Assign and define a callback function to the DataReceiver.onMessage event handler. This event handler is called when a raw data object is received by the data channel of the DataTransfer object.

In the following example, an application retrieves an instance of the DataTransfer class in receiver. The callback function assigned to the onMessage event handler of the receiver object processes the incoming data.

onDCOpen = function(){
    // Set up the receiver object
    receiver = dataTransfer.getReceiver();
    if(receiver){
        receiver.onMessage = function (evt){
        // Retrieve the data and assign it.
        var rcvdDataElm = document.getElementById("rcvData");
        rcvdDataElm.value = evt.data
    }
}

See "Sample Event Handler Invoked When the Data Channel is Open" for more information.

The next section uses a chat session to show how the WebRTC Session Controller JavaScript API library can be used to support data transfers in your web applications.

Setting up Data Transfers in Your Application

You can use the WebRTC Session Controller JavaScript API library to set up data transfers in your application to suit your deployment environment. The specific logic, web application elements, and controls you implement for calls with data transfers in your applications are predicated upon how the data transfer feature is used in your web application.

The logic to set up data transfers in calls is based on the basic logic described in "Overview of Setting Up the Audio Call Feature in Your Application". Supporting data transfers in calls becomes a matter of modifying that basic logic to set up, manage, and close data channels using the WebRTC Session Controller JavaScript API library and providing the associated display elements and controls on the application page.

If the callee is not available, you can implement additional logic in your application to store the incoming data transfer (such as a text message) and provide a notification for the receiver. See "Setting Up Message Alert Notifications".

To support video calls in your applications, augment your application's audio call logic by implementing the following logic specific to data transfers:

• Declaring Variables Specific to the Chat Sessions

• Setting Up the Configuration for Data Transfers in Chat Sessions

• Assigning the Data Transfer Event Handler to the Call Package

• Obtaining the Callee Information

• Starting the Call with the Data Transfer Feature in the Call

• Responding to Your User's Actions on an Incoming Call

• Setting Up the Chat Session User Interface

• Setting Up the Data Transfer State Event Handler for the Chat Session

• Managing the Flow of Data

• Monitoring the Chat Session

Declaring Variables Specific to the Chat Sessions

For each data channel configured in your application's CallConfig object, your application needs a wsc.DataTransfer class object. And each wsc.DataTransfer class object is associated with a wsc.DataSender and a wsc.DataReceiver class object. Declare the variables necessary for the data channels supported by the calls made from or received by your application.

In Example 6-1, an application declares these objects at the start of the application.

Example 6-1 Sample Data Transfer Variables

var dataTransfer, sender, receiver;
var target, buddy1, buddy2;

Setting Up the Configuration for Data Transfers in Chat Sessions

The WebRTC Session Controller JavaScript API library provides the dataChannelConfigs parameter to define the data channel for calls in the CallConfig class object. This dataChannelConfigs parameter is an array of JavaScript Object Notation (JSON) objects that describe the configuration of the data channel.

In order to define just the data channel in the call configuration for the application, input the data channel capability in the dataChannelConfigs parameter when you create the CallConfig object in your application.

In Example 6-2, an application enables the user to send and receive data by setting the data channel capability in the dataChannelConfigs object when it creates its CallConfig object:

Example 6-2 Sample Call Configuration Object for Data Transfers

// create a CallConfig object.
 var dtConfigs = new Array();
 dtConfigs[0] = {"label":"ChatOverDataChannel", "reliable" : false };
 var callConfig = new wsc.CallConfig(null,null,dtConfigs);

Assigning the Data Transfer Event Handler to the Call Package

When the WebRTC Session Controller JavaScript API library receives data transfer object for the user, it invokes the CallPackage.onIncomingCall event handler in your application. Assign a callback function to handle the data transfer object received by your application.

Alternatively, you can assign a single callback function to your application's CallPackage.onIncomingCall event handler and within that callback function implement the logic to handle the incoming audio, video calls or data transfers.

In Example 6-3, an application creates its CallPackage object within a callback function called sessionSuccessHandler which is called when the application Session object is created. In the sessionSuccessHandler function, the application assigns a callback function named onIncomingDataTransferCall to its Call.onIncomingCall event handler.

Example 6-3 Sample sessionSuccessHandler for Data Transfers

function sessionSuccessHandler() {
    // Create the CallPackage. 
    callPackage = new wsc.CallPackage(wseSession);
    // Bind event handler of incoming call.
    if(callPackage){
      callPackage.onIncomingCall = onIncomingDataTransferCall;
    }
    // Other application-specific logic.
    ...
  }

See Example 6-6 for a description of the onIncomingDataTransferCall function.

Obtaining the Callee Information

Define the user interface to enable the caller to input the callee ID of the person with whom the chat session is to be established. And provide the underlying logic for the appropriate functions to be called when the caller enters text or selects the control buttons. You need to set up the function that will start the chat session.

In Example 6-4, an application calls a function named displayInitialControls to provide the user interface and controls for calls with data transfers. As with the sample audio call application, this application calls the displayInitialControls function when the session state is CONNECTED.

In this function:

• An input field is provided for the callee ID along with the Start a Chat Session control button.

• The onclick= action for the Start a Chat Session control button triggers a function called startDataTransfer to start the setup for the chat session. In addition, it also defines other functions to invoke when the user selects to cancel or log out.

Example 6-4 Sample Code to Receive Callee Information

function displayInitialControls() {
    ...
    var controls = "Enter the Name of Your Chat Buddy: <input type='text' name='dataTarget' id='dataTarget'/><br>"
    + "<input type='button' name='startDataTransfer' id='startDataTransfer' value='Start a Chat Session ' onclick='startDataTransfer()'/><br><br>"
    + "<input type='button' name='cancelButton' id='cancelButton' value='Cancel Chat' onclick='' disabled ='false'/>"
    + "<br><br><br>"
    + "<input type='button' name='logoutButton' id='logoutButton' value='Logout' onclick='logout()'/>"
    + "<hr>";

    setControls(controls);
    // Verify the input is not blank or invalid number..
    ...
   ...
}

Starting the Call with the Data Transfer Feature in the Call

When you receive the callee information, you need to start the setup for the call by creating the Call object, implementing the logic to handle events associated with the Call object, invoking Call.Start, and setting up the required user interface and controls for the chat session.

In Example 6-5, an application uses a function called startDataTransfer to perform these actions. The basic logic is similar to the onCallSomeOne function used in the sample audio call application. See "Starting a Call From Your Application". The application invokes startDataTransfer when it receives the callee information and the user's request to start a chat session.

Example 6-5 Sample startDataTransfer Function

function startDataTransfer() {
   // Store the caller and callee names.
   ...
   // Check to see if the user gave a valid input. Omitted here. 
   ...
   // Create the  call object.
   var call = callPackage.createCall(target, callConfig, doCallError);
   // Set up the call object's components.
   if (call != null) {  
 
       //Call object is valid. Call the required event handlers. 
       setEventHandlers(call);
       ....
 
       //Set the event handler to call when a data transfer object is created. 
       call.onDataTransfer = onDataTransfer;
 
       // Then start the call.
       call.start();
 
       // Allow the user to cancel call before it is set up.
       // Disable "Start a Chat Session" button and enable "Cancel" button.
       // If user clicks Cancel, call end() for the call object.
       // Call displayInitialControls() to display the initial input fields.
       ....
    } 
}

Responding to Your User's Actions on an Incoming Call

When a user who is logged in to your application receives an in-browser call from another user, the WebRTC Session Controller JavaScript API library invokes the CallPackage.onIncomingCall event handler in your application. It sends the incoming call object and the call configuration for that incoming call object as parameters to your application's CallPackage.onIncomingCall event handler.

Define the actions to the incoming call in the callback function assigned to your application's CallPackage.onIncomingCall event handler in the following way:

• Provide the user interface and logic necessary for the callee to accept or decline the call.

• Provide logic for the following events:

  • User accepts the call. Run the accept method for the incoming call object. This will return the success response to the caller.

  • User declines the call. Run the decline method for the incoming call object. This will return the failure response to the caller.

• Set up the user interface for the data transfers in the call.

• Assign the callback functions to the event handlers of the incoming call object. These should already have been defined.

In Example 6-6, an application uses the onIncomingDataTransferCall callback function assigned to its Call.onDataTransfer event handler. The basic logic is similar to the onCallSomeOne function used in the sample audio call application. See "Responding to Your User's Actions on an Incoming Call". The application uses the incoming call object (dtCall) and the call configuration for that incoming call object (callConfig):

Example 6-6 Sample onIncomingDataTransferCall Function

function onIncomingDataTransferCall(dTCall, callConfig) {                          

    //assign the event handler onDataTransfer to the call object
    dTCall.onDataTransfer = onDataTransfer;
    
    var dElement = document.getElementById("dataTarget");

    // We need the user's response.
    //Display an interface that lets a user decline or accept a call
    // Attach event handlers to these events.
    ...
    document.getElementById("acceptDTBtn").onclick = function() {
        // Chat session accepted
        dTCall.accept(callConfig, null);

        // At this point, update the user interface for the callee
        // Display the fields, controls for text and ending the chat session.
        ...
    }
    document.getElementById("declineDTBtn").onclick = function() {
        dTCall.decline(null);
    }
    setEventHandlers(dTCall);
    call = dTCall;
   
}  

Setting Up the Chat Session User Interface

The design of your application's page determines the type of user interface for the chat session. Use your application's DataSender object and its send method to send the data entered by the user. Assign callback functions for the controls you use in the interface and set up the actions within those callback functions.

Setting Up the Data Transfer State Event Handler for the Chat Session

The DataTransfer class object contains three event handlers:

• onClose which indicates that the data channel of a DataTransfer object is closed.

• onOpen which indicates that the data channel of a DataTransfer object is open.

• onError which indicates that the data channel of a DataTransfer object is in error.

Assign the callback function to handle each of the events and provide the logic for each callback function.

In Example 6-7, an application shows the callback function onDataTransfer which was assigned to Call.onDataTransfer event handler. In this onDataTransfer function, the application assigns a callback function to each of the onOpen, onClose and onError event handlers of the data transfer object.

Example 6-7 Sample onDataTransfer Callback Function

onDataTransfer = function(dT) {
    dataTransfer = dT;
    dataTransfer.onOpen = onDCOpen;
    dataTransfer.onError = onDCError;
    dataTransfer.onClose = onDCClose;
};

Managing the Flow of Data

To maintain and manage the flow of data in the data channel, implement the logic in the callback functions to handle the Open, Close, and Error states of the data transfer object.

To do so, provide the logic required to handle the following in your application:

1. The Open state for the data channel. See "Handling the Open State of the Data Channel".

2. The received text. See "Handling the Received Text".

3. Sending the text entered in the text field. See "Sending the Text".

4. The Close state for the data channel. See "Handling the Closed State of the Data Channel".

5. The Error state for the data channel. See "Handling Errors Related to Data Transfers".

Handling the Open State of the Data Channel

When the data channel is open, your application can do the following:

• Retrieve its Datasender and DataReceiver objects from its DataTransfer object.

  The DataSender and DataReceiver objects are returned when you call your application's DataTransfer.getSender and DataTransfer.getReceiver methods. For the receiver, the data is from the remote peer of the current data channel session.

• For the receiver of the data, retrieve the data from the remote peer of current data channel session, and display it.

• Other actions as necessary. Your application sets up the logic necessary to save the incoming and outgoing text to display the chat session appropriately.

Provide the logic for your application's DataTransfer.onOpen event handler as required by your application.

In Example 6-8, when the data channel is open in an application, the callback function assigned as the event handler assigned to the application's DataTransfer.onOpen event handler processes the data transfer object.

Example 6-8 Sample Event Handler Invoked When the Data Channel is Open

onDCOpen = function(){
    // Set up the receiver object
    receiver = dataTransfer.getReceiver();
    if(receiver){
        receiver.onMessage = function (evt){
            // Retrieve the data and assign it.
            var rcvdDataElm = document.getElementById("rcvData");
            rcvdDataElm.value = evt.data;
        }
    }
 
    // Retrieve the sender
    sender = dataTransfer.getSender();
 
    var dcReadyState = dataTransfer.state;

    // Set up the control buttons appropriately
    var sendDataBtn = document.getElementById("sendData");
    sendDataBtn.hidden = false;
    var dataForChannel = document.getElementById("dataForChannel");
    dataForChannel.hidden = false;
    dataForChannel.value="";
    var endButton = document.getElementById("endDataChannel");
    endButton.hidden = false;
    var rcvdDataElm = document.getElementById("rcvData");
    rcvdDataElm.value = "";
    rcvdDataElm.hidden = false;

    var acceptBtn = document.getElementById("acceptDTBtn");
    if(acceptBtn){
        acceptBtn.hidden = true;
        var declineBtn = document.getElementById("declineDTBtn");
        declineBtn.hidden = true;
    }
}

Handling the Received Text

Set up the logic to handle the text that is received by your application user.

In Example 6-9, an application uses a utility function named onReceiveDTMsg to handle the received text.

Example 6-9 Sample Function to Assign Received Text

onReceiveDTMsg = function(data) {
    var rcvdDataElm = document.getElementById("rcvData");
    rcvdDataElm.value = data;
}

Sending the Text

When the user enters text and clicks the control to send the text, provide the logic to send the text entered in the text field using your application's DataSender.send method.

In Example 6-10, an application uses a utility function named send to retrieve the data from the Document Object Model (DOM) object. It calls the method of the application's DataSender.send method with this data.

Example 6-10 Sample Send Function

 send = function(){
    // get the data from the text field
    var data = document.getElementById("dataForChannel").value;
    if(sender) {
        sender.send(data);
        document.getElementById("dataForChannel").value = "";
    } else {
       console.log("sender is null");
    }
}

Handling the Closed State of the Data Channel

Set up the logic to handle the closed state of the data channel.

Example 6-11 shows the function expression for onDCClose to handle the Close state for the data channel.

Example 6-11 Sample Event Handler Invoked When the Data Channel is Closed

onDCClose = function(){
    var dcReadyState = dataTransfer.state;
}

Monitoring the Chat Session

Update the logic used to monitor the call by providing some way for both parties to end the chat session.

In the audio call application described in "Setting Up Audio Calls in Your Applications", a function named callMonitor is called by the callback function assigned to the application's Call.onCallStateChange event handler. As shown in Example 4-11, the callMonitor function is called when the call state is WSC.CALLSTATE.ESTABLISHED.

At this point, do the following in your application:

• Display the user interface necessary for the chat session.

• Provide the logic for the actions to take when the chat session ends.

  Note:

  A chat session can be ended by the caller or the callee.

In Example 6-12, an application does the following:

• Displays the user interface for the chat session.

• Responds to the selection:

  • If End Chat Session is clicked, ends the call (which ends the chat session and releases the call resources).

  • If Logout is selected, ends the session (which releases the session's resources).

Example 6-12 Monitoring the Chat Session

function callMonitor(callObj) {

    // Draw up the user interface for the callee.
    ...

    //set the button of ending a dataTransfer call
    var endBtn = document.getElementById("endDataChannel");
    if (endBtn){
       //set the event handler when clicking the end button
       endBtn.onclick = function() {
           if(dataTransfer != null) {
               // There is some data. 
               // This function merely sets the text to blank.
               document.getElementById("dataForChannel").value = "";
           }

           // End the data channel call.
           callObj.end();
        };
    }
}