About the Default Messaging Mechanism Used by Your Applications

When your application needs to perform an action such as creating a session, a call or message alert package, starting a call or responding to a notification, it sends a JavaScript message associated with that action to the WebRTC Session Controller JavaScript API library. For its part, the WebRTC Session Controller JavaScript API library converts these messages (for example, Call.start) into signaling messages using a protocol based on JavaScript Object Notation (JSON). For more information, see WebRTC Session Controller Extension Developer's Guide.

The WebRTC Session Controller JavaScript API library contains classes and methods that have a default behavior and others that can be extended. When you use the default classes and methods, the WebRTC Session Controller JavaScript API library handles all of the signaling messages for all the resulting default commands.

When you need to broaden or extend your application logic, you may need to extend the JavaScript message sent by your application. To do so, use those objects and methods in the WebRTC Session Controller JavaScript API that are extensible.

About Extending the WSC Namespace

Your applications can support additional communication-related services in audio, video, and data transfer flows. For example:

Custom calls

In order to handle custom call flows you can implement logic to prepare the calls, setting up the logic to accept prepared calls, and manage the sequence of messages associated with the prepared calls.

Custom packages

To support custom services in calls of custom call flows, your application may need to extend the application session.

The WebRTC Session Controller JavaScript API library provides the following objects and functions for this purpose:

Extending Objects Using the wsc.extend Method

The wsc.extend method is a utility you use when you wish to extend a WebRTC Session Controller JavaScript API class object exposed through wsc namespace. The wsc.extend method takes two parameters, child and parent, in that order. The syntax is:

wsc.extend(child, parent);

When you call the wsc.extend method, the constructor of the child object calls the constructor of the parent. All the members that are attached to the prototype object of the parent entry are copied to the prototype object of the child entry. The objects initialized in the parent's constructor code become available and the child can now make use of the objects in the parent class object. You can then override any function in the child object without impacting the parent.

The code sample in Example 8-1 creates the wsc.CallExtension object which extends the wsc.Call object.

At this point, the inherited members of CallExtension can be overridden without affecting the corresponding members in the parent Call object.

See "Working with Extended Calls" for a description of how the onMessage function is overridden in this newly-created CallExtension class object.

Extending Sessions with wsc.ExtensibleSession Class

The wsc.ExtensibleSession class object provides many critical functions required to extend packages. Use the methods in wsc.ExtensibleSession to access and retrieve information about a subsession using its identifier (sessionId), retrieve a specific package by its type and manage it, and configure custom packages in your application to handle specific set of tasks. See "Creating Custom Packages Using the ExtensibleSession Object".

Handling Extended Call Sessions with CallPackage.onMessage

If your application logic uses extended call sessions, set up the required actions in a callback function for the application's CallPackage.onMessage event handler. When call-related messages come in to your application, this callback function will be invoked enabling you to inspect the incoming message and take further action on the call.

Here, an application has set up the caller, callee, and callConfig objects and uses the CallPackage.prepareCall method to prepare a call called mycall with reference to a specific session, mysession.

Inserting Calls into a Session with CallPackage.putCall

Use the CallPackage.putCall method to place a prepared call object in a specific point in the flow for that call session. To do so, you need:

The subsession Id (id) for the call session

The prepared call object.

You can now place the call with the following statement:

putCall(id, call);

Processing Custom Messages for a Call with Call.onMessage

Process custom message content that your application receives for the current call by using the Call.onMessage method. Extend the Call object to do so. See "Working with Extended Calls".

Extending Headers in Call Messages

When you use an extension header in a call session, set up the extension header in the following JavaScript format:

{'label1':'value1','label2':'value2'}

Place the extension header as the last parameter when you invoke the methods that support extension headers. See "Handling Additional Headers" for the complete of objects and methods that support extension headers.

Handling Custom Message Notifications

If the received notification message is not a message summary, your application receives a wsc.Notification object as the parameter to its Subscription.onNotification event handler.

In the callback function you assign to your application's Subscription.onNotification event handler, use this incoming notification to instantiate an extended wsc.Notification class object. Use the methods of the extended class object to parse the supported types of notification messages.

Handling Extensions to Notifications with MessageAlertPackage.onMessage

If your application's MessageAlertPackage object manages an array of subscriptions, then, when a notification comes to your application, the MessageAlertPackage.onMessage event handler is invoked. In the callback function you assign to this event handler, you can process the incoming message notification to identify the subscription object and invoke the appropriate Subscription.onNotification event handler for further processing of that notification.

Handling Additional Headers in Messages

Your application may need to allow users to send or receive additional data in the form of an extra header field.

About Additional Headers in Messages

Some methods in the Call and CallPackage class objects can accept an additional argument, as long as it is a JSON object. This additional data is sent as an extension header in the message and received as an extra parameter by the event handler of the incoming call.

For example, when a user navigates your application page designed for an auto dealership, your application may have gathered data on the user's preferences for the make, model, and deal preferences, such as carMaker, Convertible), and Lease.

When the user calls the dealership from your page, your application can pass this information to the dealer in the call. Your application sets up this information as a JSON object.

Perform any actions based on the additional data in the extension header.

If the application user accepts the call, do the following:

Set up the extension header as a JSON object.

Include the JSON object when your application invokes the outgoing call object's start method to start the call.

For example, if call is the call object, callConfig the local media stream and data transfer capability for calls, lmedstrm is the local media stream object, and extHeader is the extension header in your application, use the following statement to accept the call:

For example, if extCall is the extended call object, reason the reason the call was declined, and extHeader is the extension header:

extCall.decline(reason,extHeader)

Whether your application user is the caller or the callee, your application may need to handle incoming messages and set up outgoing messages associated with the following events. In each case, set up the extension header as described and place it as the last parameter when you invoke the associated function for the extended call.

Your application user ends the call.

Set up the extension header as described earlier and include it when you invoke the end method for the extended call.

The call is updated.

If your application user:

Requests the update.

Set up the extension header as described earlier and include it when you invoke the update method for the extended call.

Receives the update request.

Process any data in the extension header in the onUpdate event handler. Set up the extension header as described earlier and include it when you invoke the accept or decline method of the extended call object, as appropriate.

The call state changes.

Process any data in the extension header in the Call.onCallStateChange event handler. Set up the additional data as the extension header in the method for the outgoing call.

Working with wsc.ExtensibleSession

Your applications can use custom session objects to enable users to subscribe to the presence of other users, chat with SIP users, or set up calls that can be transferred to other users. Configure and manage custom flows in your applications by using the wsc.ExtendedSession object.

successCallback, the function to call if the session object was created successfully.

failureCallback, the function to call if the session object was not created.

sessionId, if you are refreshing an existing session.

Creating Custom Packages Using the ExtensibleSession Object

You can create custom packages in your application to handle specific set of tasks and expand the scope of your application. To add custom packages, your application needs to use the following objects:

The ExtensibleSession:

Use this object to do one or more of the following

Creating an extended session object using the ExtensibleSession method of wsc.

Retrieving all sub-sessions by using the getAllSubSessions method of your application's ExtensibleSession object.

Saving session data to the web browser's sessionStorage by using the saveToStorage method of your application's ExtensibleSession object.

Saving Your Custom Session

When you create applications using the default or custom behavior of WebRTC Session Controller JavaScript API, the library automatically saves the data for the sessions.

If you need your application to handle the data associated with custom sessions or subsessions, save the corresponding data in the HTML SessionStorage area using the ExtensibleSession.saveToStorage method. Your session data should be stored in JSON format. Ensure that your application saves the session data such that it captures the changes so as to maintain the session's current state for use in dealing with connectivity issues.

Important:

When your application uses a custom package and/or subsession object save the subsession's state to support rehydration. Monitor the change in the subsession's state and call your application's ExtensibleSession.saveToStorage() method to save the data.

Sending And Receiving Custom Messages

When you create messages independent of the default call or message alert package, you need to set up logic to handle the flow of such messages and the resulting actions your application needs to take.

You can send custom messages within a sub-session by providing a Message object as an argument when you call your application's ExtensibleSession#sendMessage method. Ensure that your application's Message object has the control, header, and payload blocks. For example, to send INFO messages as part of an ongoing call, your application can extend its Call and CallPackage objects and use them to support sending and receiving INFO messages while delegating all other functionality to the existing Call and CallPackage. See the discussion on extension points in WebRTC Session Controller JavaScript API Reference.

About the API Classes Used to Create Custom Message

At times, you may need to create you create custom packages and use custom message flows in your applications. Use the following:

For information on the wsc.Map utility you can use when you set up custom messages, see Oracle Communications WebRTC Session Controller JavaScript API Reference.

wsc.Message

The wsc.Message class object encapsulates a message and contains two sections of headers and the payload, if necessary. All messages between your application and WebRTC Session Controller are sent in this format. Create the control header, general header and the payload sections of message object in your application. Example 8-2 shows the header sections of a message object which initiates a WebSocket connection:

When you need to create messages independent of the default call or message alert package, use the wsc.Message object and manage the messaging workflow using the wsc.ExtensibleSession object. See "Working with wsc.ExtensibleSession".

wsc.Message#control

Use the wsc.Message#control object to define the control header in a message.

A control header contains information required for WebSocket reconnection, reliability, timeouts, error, the state of the message, type of the message, and so on. For information on the headers supported in the Control section, see WebRTC Session ControllerJavaScript API Reference and WebRTC Session ControllerExtension Developer's Guide.

wsc.Message#header

Use the wsc.Message#header object to specify the specific action involved in the message. For example, for a START request, such information would contain who initiated the request, for whom it is intended, and so on. Your application can add additional headers to the this section. Such headers may be mapped by a gateway server to a SIP header or a parameter. For information on the headers supported in the Header section, see WebRTC Session ControllerJavaScript API Reference and WebRTC Session ControllerExtension Developer's Guide.

wsc.Message#payload

Use the wsc.Message#payload object to specify the payload section of the protocol specific to the "package". For:

CallPackage, the payload contains the offer or answer in Session Description Protocol (SDP)

If you create a "Presence" package, the payload for messages associated with this package should contain the presence information.

Managing Custom Message Data Flows

When you use custom message flows, set up your application with the appropriate logic required to send and receive messages from Signaling Engine. Ensure that the correlation Ids, the sequencing and other details of the outgoing message are appropriate.

Sending a Custom Message to Signaling Engine

Complete the following tasks to send a custom message to Signaling Engine:

Set up the data as "key" : "value" pairs in

wsc.Message#control()

wsc.Message#header()

Set up the payload using wsc.Message#payload

Use JSON.stringify method to set up the message data in msg.

Create the message to be sent using wsc.Message(msg), where msg is message data.

Send the message using the sendMessage method of your application's ExtensibleSession object.

Registering the Extended Package with the Session

Call objects created from this extended call package can handle additional headers.

Extending the Methods and Event Handlers in the Extended Call Package

When you extend the call package, extend the required methods and event handlers:

prepareCall

putCall

onMessage

onRehydration. Extend this event handler so that your application can re-create the subsession object based on the rehydrated data your application receives through this event handler. When the subsession object is recreated, WebRTC Session Controller JavaScript API library invokes the onResurrect event handler of the call object.

Working with Extended Calls

To work with extended calls:

Extend the CallPackage object:

wsc.extend(CallPackageExtension, wsc.CallPackage);

Create an instance of the extended call package CallPackageExtension and register it with the session.

CallPackage = new CallPackageExtension(wscSession);

Use this instance of the call package to expand the way your application handles calls.

The code sample in Example 8-4 adds support to handle INFO messages as part of a call by extending the Call and CallPackage objects. If the incoming message has extra data, the prepareCall function is overridden.

Extending the Methods and Event Handlers

When you extend the MessageAlertPackage class object, extend the required methods and event handlers:

onMessage

onRehydration. Extend this event handler so that your application can re-create the subsession object based on the rehydrated data your application receives through this event handler. When the subsession object is recreated, WebRTC Session Controller JavaScript API library invokes the onResurrect event handler of the rehydrated Subscription object.

Extending the MessageAlertPackage to Support Other Message Events

You can extend the wsc.MessageAlertPackage class object to support other message event types.

To do so:

Use wsc.extend method to set up an extended MessageAlertPackage object.

Override the onMessage event handler of the extended MessageAlertPackage object. Your application can now handle notifications other than the default MessageSummary type.

Assign a callback function to handle the overridden onMessage event handler of the extended MessageAlertPackage object. In this callback function, process the new type of notification message.

Define a custom class extended from the Notification class object. This new type of notification object will store the notification messages made available by the overridden onMessage event handler.

Define a new class similar to MessageCounts and set it up to store the information on the new notification messages.