| Oracle® Communications WebRTC Session Controller Extension Developer's Guide Release 7.0 E40977-01 |
|
|
PDF · Mobi · ePub |
| Oracle® Communications WebRTC Session Controller Extension Developer's Guide Release 7.0 E40977-01 |
|
|
PDF · Mobi · ePub |
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.r.
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 call, presence, and message_notification 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 those with a CONNECT action. CONNECT 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. Identifies a message to acknowledge. Used to confirm that the client received the message with the ack_sequence value. A value if 0 means the message was not received. All messages with a lower value than the ack_sequence are also considered acknowledged.
Identifies a subsession with 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 Initial, Subsequent, or Final. A state of Initial is assumed if no state is present. 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.
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 being targeted by the message.
Optional. In error type messages, lists the error message.
The message payload is specific to Signaling Engine package that the message is used for. The default call package the payload is an SDP offer or answer. The default message-notification package includes JSON data with message text. If you created a presence package, that package probably includes presence data.
The following sections show message body examples.
{
"control": {
"type":"request",
"sequence":"1",
"version":"1.0"
},
"header": {
"action":"connect",
"initator":"bob@example.com",
}
}
{
"control": {
"type":"response",
"sequence":"1",
"correlation_id":"c1",
"subsession_id":"c1",
"session_id":"Hyi89JUThhjjR",
"version":"1.0"
},
"header": {
"action":"connect"
}
}
{
"control": {
"type":"request",
"sequence":"2",
},
"header": {
"action":"start",
"initator":"bob@example.com",
"target":"alice@example.com",
},
"payload": {
"<offer_sdp>"
}
}
{
"control": {
"type":"response"
"sequence":"2",
"correlation_id":"c2"
"subsession_id":"c2"
},
"header": {
"action":"start"
},
"payload": {
"<pranswer_sdp>"
}
}
{
"control": {
"type":"message"
"sequence":"4",
"subsession_id":"c2"
},
"header": {
"action":"shutdown"
}
}
{
"control": {
"type":"error"
"sequence":"6",
"correlation_id":"c2"
"subsession_id":"c2"
"error_code":"480"
}
}
|
 Copyright © 2013, Oracle and/or its affiliates. All rights reserved. Legal Notices |
|