This appendix provides reference information for the WebRTC Session Controller JSONRTC Protocol used by WebRTC Session Controller Signaling Engine (Signaling Engine).
WebRTC Session Controller uses this protocol to communicate with WebRTC-enabled browser client applications. It establishes the sessions and subsessions that you use to pass messages between WebRTC Session Controller and its client applications inside WebSocket connections.
You can also use this protocol to create new WebRTC Session Controller packages for your WebRTC Session Controller implementation.
See "About Building JSON to SIP Communication" for more information about how WebRTC Session Controller handles WebSocket connections, sessions, and subsessions.
While WebRTC Session Controller uses this protocol to communicate with JavaScript-based applications by default, this protocol also communicates with client applications based on different operating systems. Your client application must open the WebSockets necessary for the JSONRTC protocol subsessions to communicate with.
The JSONRTC protocol is a sub protocol of the WebSocket protocol, and you establish a handshake with a WebSocket protocol to initiate communication between the two. The handshake establishes a connection between the client (usually an application in a browser) and the Signaling Engine server inside HTTP/HTTPS. Once the client receives the handshake response, communication can proceed. The handshake is an HTTP GET /chat message using webrtc.oracle.com as the value for Sec-WebSocket-Protocol. For Example:
GET /chat HTTP/1.1 Host: server.wsc_IP.com Upgrade: websocket Connection: Upgrade Sec-WebSocket-Key: dGhlIHNhbXBsZSBub25jZQ== Origin: http://client_IP.com Sec-WebSocket-Protocol: webrtc.oracle.com Sec-WebSocket-Version: 13
Where:
wsc_IP is the domain name of the Signaling Engine server.
client_IP is the domain name of the client.
The handshake reply must include a 101 Switching Protocols entry to allow the connection, as shown in this example handshake reply:
HTTP/1.1 101 Switching Protocols Upgrade: websocket Connection: Upgrade Sec-WebSocket-Accept: s3pPLMBiTxaQ9kYGzzhZRbK+xOo= Sec-WebSocket-Protocol: webrtc.oracle.com
Once the client receives the handshake response, the client and Signaling Engine server can communicate further.
Immediately after establishing a WebSocket connection, the client sends a JSONRTC connect message to establish the WebRTC Session Controller JSONRTC session. Once WebRTC Signaling Controller accepts the connect message, it responds by sending back a session_id. If the WebSocket connection is broken unexpectedly, for example by a network problem, the client can re-establish the session by starting a new websocket connection with the original session_id in a connect message.
See "About Sessions and Subsessions" for details on how this protocol establishes and manipulates sessions and subsessions.
JSONRTC uses a session_id field instead of a Message Broker WebSocket Subprotocol (MBWS) connection_name to identify the WebSocket session. The session_id field value must be unique across time and space to work with geographically redundant clusters.
The subsession_id is the session_id value with a c or s prefix added to it.
Also see "Initiating a HTTP/HTTPS Handshake with Signaling Engine" for more information about using session_id to reconnect a session.
This protocol uses the MessageBroker WebSocket Subprotocol (MBWS) as basis for message reliability. For more information on MBWS, see the MBWS specification:
http://tools.ietf.org/html/draft-hapner-hybi-messagebroker-subprotocol-03
The basic communication unit used between a WebRTC-enabled client application and the WebRTC Session Controller JSONRTC protocol is a message. Signaling Engine communication can be synchronous or asynchronous. Each messages includes these components:
This section also includes "Example Message Bodies" that you can use for reference.
The control header specifies information that the client and server use to handle (control) the message. It includes the message type, session ID, message state, and so on. Typically Signaling Engine uses this information itself, not applications or Groovy scripts.
The control type of JSON message. Can be one of:
A message that requires a response. A protocol frame with control type request may also contain a payload header.
This message is a response to a request message. A protocol frame with control type request may also contain a payload header.
A message that does not require a response. For example notification, or publish. A protocol frame with control type request may also contain a payload header.
A message that acknowledges another message. Can not contain a payload header.
Indicates that an error has arrived. Can not contain a payload header.
Optional. The register, call, message_notification, capability, messaging, chat, and file_transfer types are defined by default. Identifies the Signaling Engine package that the message applies to. If no package_type is specified, Signaling Engine assumes that the default call package is used for all messages except messages with a connect action. The connect action messages attempt to establish a session and are not associated with a package. See "Creating Packages" for details about the Signaling Engine packages.
Identifies a WebSocket session. The server creates the session ID and returns it to the client in the CONNECT response. A CONNECT message containing a session ID reestablishes a JSONRTC session. This value must be completely unique so that it may be used across redundant clusters. This has the same role as the MessageBroker WebSocket Subprotocol (MBWS) connection-name.
A serial number that uniquely identifies a message in a JSONRTC session. Both the client and server keep their own serial number counts, starting with 1.
Optional. Acknowledges that a specified server message has been received by the client or, likewise, that a specified client message has been received by the server. For example, if a client receives a message with ack_sequence=2, it means that the sever has received the second message sent by the client. All messages with a lower value than specified by ack_sequence are also considered acknowledged.
Identifies a subsession within a session. The sequence numbers are incremented each time a new session is started. The client and server keep separate subsession ID counts. This subsession ID typically includes a c prefix if the subsession originated with the client and an s prefix if it originated with the server. An implementation can also choose to use a globally unique identifier as the subsession ID.
For example the second client-originated subsession has the value "subsession_id":"c2". The seventh server-originated session uses the value "subsession_id":"s7".
A string that identifies a specific message within a session. It can simply be a sequence number incremented each time a new message is sent. The client and server keep separate message counts. Messages from the client have a ”c” suffix and messages from the server have an ”s" suffix.
For example the third client-originated message has the value ”correlation_id”:"c3". The sixth server-originated message has the value "correlation_id":"s6".
Identifies the message state as subsequent, or final. Only subsequent or final messages need specify the message_state.
For example: "message_state":"final"
Identifies the JSONRTC protocol version that message sender supports (client or server). If none is present in the message version "1.0" is assumed.
The general header (header) includes fields that Signaling Engine uses to build up and tear down calls. These fields are specific to one or more packages and are available to use in both client applications and Groovy scripts.
The purpose of the message. Can be one of:
Establishes a session with the server. These general headers are only used with the CONNECT action.
Optional. Sent with the session_id of a session to reconnect. Uses the sequence number of the last message received from the client to identify the session.
Optional. Sent with the session_id of a session to reconnect. Uses the lower bound of the messages in the client's retained window to identify the session.
Optional. Sent with the session_id of a session to reconnect. Uses the upper bound of the messages in the client's retained window to identify the session.
Optional. Sent with the session_id of a session to reconnect. Uses the sequence number of the last message received by the server to identify the session.
Starts a session with a specific package.
Announces that the media session has been established.
Equivalent to Notification of Notification Server.
Shuts down session opened by a specific request.
Pre-acknowledges provisional responses.
Queries information from the peer side.
Sends out data.
Sends out ICE candidates.
Optional. Identifies the URI of the user initiating the HTTP request. If this value exists, it may be set by the client or the HTTP session.
Optional. Identifies the URI of the Signaling Engine server that is targeted by the message.
Optional. In error type messages, lists the error message.
Optional. Specifies the result for a response message, especially in the call package. Example: "180", "200", etc.
Optional. This is the enquiry data that is the result of an enquiry action. In most cases it is for the capability package.
Package-Specific General Headers
Some headers are specified only for certain packages.
Optional. Represents the subscription's expiration time for receiving message-summary notifications.
Authentication-Specific General Headers
The authentication headers are specific to client authentication and authorization.
Optional. Represents authentication information from the server. If the server leverages DIGEST for authentication, this header contains {scheme, username, realm, qop, opaque, nonce, cnonce, ha1, challenge_code, algorithm}.
Optional. This header represents the authorization response to the server. If DIGEST is leveraged, this header contains {scheme, username, realm, qop, opaque, nonce, cnonce, ha1, challenge_code, algorithm}. For more details on this header, see https://www.ietf.org/rfc/rfc2617.txt.
The ha1 value is calculated with the following steps:
A1 calculation:
If algorithm=MD5 or is unspecified
A1 = username-value ":" realm-value ":" password
If algorithm=MD5-sess
A1 = H(username-value ":" realm-value ":" password) ":" nonce-value ":" cnonce-value
ha1=H(A1)
Where username-value, realm-value, nonce-value, and cnonce-value are strings without quote marks and H means the string obtained by applying the checksum algorithm to A1.
The message payload is specific to the Signaling Engine package for which the message is used. For the call, chat, and file_transfer packages, the default payload is an SDP offer or answer. For the messaging package, the payload is content that represents the text message. The default message-notification package includes JSON data with message text.
The following sections show message body examples.
{
"control": {
"type":"request",
"sequence":"1"
},
"header": {
"action":"connect",
"initator":"bob@example.com",
}
}
{
"control": {
"type":"response",
"sequence":"1",
"correlation_id":"c1",
"subsession_id":"c1",
"session_id":"Hyi89JUThhjjR"
},
"header": {
"action":"connect"
}
}
{
"control": {
"package_type": "call",
"type":"request",
"sequence":"2",
},
"header": {
"action":"start",
"initator":"bob@example.com",
"target":"alice@example.com",
},
"payload": {
"<offer_sdp>"
}
}
{
"control": {
"package_type": "call",
"type":"response"
"message_state":"final"
"sequence":"2",
"correlation_id":"c2"
"subsession_id":"c2"
},
"header": {
"action":"start"
},
"payload": {
"<pranswer_sdp>"
}
}
{
"control": {
"package_type": "call",
"type":"message"
"sequence":"4",
"subsession_id":"c2"
},
"header": {
"action":"shutdown"
}
}
{
"control": {
"package_type": "call"
"type":"error"
"sequence":"6",
"correlation_id":"c2"
"subsession_id":"c2"
"error_code":"480"
}
}
{
"package_type": "capability"
"type":"request",
"sequence":"1",
"correlation_id":"c1"
"subsession_id":"c1"
}
"header": {
"action":"enquiry",
"enquiry_data":"IM/CHAT,VS",
"initiator":"bob@att.com",
"target":"alice@att.com",
}
}
{
"control": {
"package_type": "capability",
"type":"response",
"message_state":"final",
"sequence":"1",
"correlation_id":"c1"
"subsession_id":"c1"
}
"header": {
"action":"enquiry",
"enquiry_data""IM/CHAT, FT",
"initator":"bob@att.com",
"target":"alice@att.com",
}
}
{
"control": {
"package_type": "messaging"
"type":"message"
"sequence":"1",
"correlation_id":"c1"
"subsession_id":"c1"
}
"header": {
"action":"send"
"initiator":"bob@att.com",
"target":"alice@att.com",
}
"payload": {
"content": <message content>
}
}