WebRTC

Version 16 (Saúl Ibarra Corretgé, 07/31/2015 02:47 pm)

1 1 Saúl Ibarra Corretgé
h1. SylkServer WebRTC gateway application
2 1 Saúl Ibarra Corretgé
3 2 Saúl Ibarra Corretgé
Starting with version 3.0.0 SylkServer includes a WebRTC gateway application. The application implements a WebSocket protocol which WebRTC endpoints can use in order to interact with the SIP world.
4 2 Saúl Ibarra Corretgé
5 2 Saúl Ibarra Corretgé
6 2 Saúl Ibarra Corretgé
h2. Architecture
7 2 Saúl Ibarra Corretgé
8 1 Saúl Ibarra Corretgé
TODO
9 2 Saúl Ibarra Corretgé
10 2 Saúl Ibarra Corretgé
h2. WebSocket API
11 2 Saúl Ibarra Corretgé
12 5 Saúl Ibarra Corretgé
SylkServer offers the WebSocket API in order to interact with the WebRTC gateway in the @ws(s)://hostname:port/webrtcgateway/ws@ endpoint. Both WebSocket and Secure WebSocket are supported, depending on how SylkServer was configured, check the configuration section.
13 1 Saúl Ibarra Corretgé
14 7 Saúl Ibarra Corretgé
The API uses JSON messages and is modeled around 2 concepts: requests and events.
15 5 Saúl Ibarra Corretgé
16 5 Saúl Ibarra Corretgé
A request represents an action which SylkServer should perform, and it's identified with a transaction ID which the user must provide. SylkServer will reply with either an 'ack' or an 'error' response, with the associated transaction ID. An example transaction is that of adding an account.
17 5 Saúl Ibarra Corretgé
18 5 Saúl Ibarra Corretgé
Events are notifications sent by SylkServer to the client. They are the result of some change triggered by a user action, but they don't have a transaction ID associated with them. An example event would be the connection state changed event.
19 1 Saúl Ibarra Corretgé
20 7 Saúl Ibarra Corretgé
All messages are valid JSON and contain the "sylkrtc" key indicating the message type. A message without the "sylkrtc" key is an invalid message.
21 7 Saúl Ibarra Corretgé
22 5 Saúl Ibarra Corretgé
h3. Establishing the connection
23 1 Saúl Ibarra Corretgé
24 6 Saúl Ibarra Corretgé
In order to connect to SylkServer to begin to use the API a WebSocket connection must be established, using the @sylkRTC-1@ subprotocol. Example:
25 6 Saúl Ibarra Corretgé
26 6 Saúl Ibarra Corretgé
<pre>
27 6 Saúl Ibarra Corretgé
var conn = new WebSocket('wss://example.com/webrtcgateway/ws', 'sylkRTC-1');
28 6 Saúl Ibarra Corretgé
</pre>
29 6 Saúl Ibarra Corretgé
30 6 Saúl Ibarra Corretgé
After the connection is established, a 'ready' event will be sent to the client, indicating that the connection is ready to be used:
31 6 Saúl Ibarra Corretgé
32 6 Saúl Ibarra Corretgé
<pre>
33 6 Saúl Ibarra Corretgé
{
34 6 Saúl Ibarra Corretgé
  "sylkrtc": "event",
35 6 Saúl Ibarra Corretgé
  "event": "ready"
36 6 Saúl Ibarra Corretgé
}
37 6 Saúl Ibarra Corretgé
38 6 Saúl Ibarra Corretgé
</pre>
39 1 Saúl Ibarra Corretgé
40 7 Saúl Ibarra Corretgé
Example:
41 7 Saúl Ibarra Corretgé
42 7 Saúl Ibarra Corretgé
<pre>
43 7 Saúl Ibarra Corretgé
var conn = new WebSocket('wss://example.com/webrtcgateway/ws', 'sylkRTC-1');
44 7 Saúl Ibarra Corretgé
conn.onmessage = function(event) {
45 7 Saúl Ibarra Corretgé
    var message = JSON.parse(event.data);
46 7 Saúl Ibarra Corretgé
    switch (message.sylkrtc) {
47 7 Saúl Ibarra Corretgé
        case 'event':
48 7 Saúl Ibarra Corretgé
            if (message.event === 'ready') {
49 7 Saúl Ibarra Corretgé
                console.log('Ready to rock!');
50 7 Saúl Ibarra Corretgé
            }
51 7 Saúl Ibarra Corretgé
            break;
52 7 Saúl Ibarra Corretgé
        default:
53 7 Saúl Ibarra Corretgé
            console.log('Received message type: ' + message.sylkrtc);
54 7 Saúl Ibarra Corretgé
            break;
55 7 Saúl Ibarra Corretgé
    }
56 7 Saúl Ibarra Corretgé
};
57 7 Saúl Ibarra Corretgé
</pre>
58 7 Saúl Ibarra Corretgé
59 5 Saúl Ibarra Corretgé
h3. Account management
60 5 Saúl Ibarra Corretgé
61 8 Saúl Ibarra Corretgé
Multiple accounts can be managed from a single WebSocket connection. 2 types of requests are used to manage accounts: "add_account" and "remove_account". Once an account has been added it can be registered via SIP using the "register" command, and unregistered using the "unregister" command.
62 8 Saúl Ibarra Corretgé
63 10 Saúl Ibarra Corretgé
Note: it's not necessary to register an account in order to make outgoing calls.
64 10 Saúl Ibarra Corretgé
65 13 Saúl Ibarra Corretgé
h5. add_account
66 8 Saúl Ibarra Corretgé
67 9 Saúl Ibarra Corretgé
Configures an account on the current connection.
68 8 Saúl Ibarra Corretgé
69 8 Saúl Ibarra Corretgé
<pre>
70 8 Saúl Ibarra Corretgé
{'account': 'saghul@sip2sip.info',
71 8 Saúl Ibarra Corretgé
 'password': '884edfee38ed471b8a15006700139485',
72 8 Saúl Ibarra Corretgé
 'sylkrtc': 'add_account',
73 8 Saúl Ibarra Corretgé
 'transaction': '04013f0f-25bb-4082-a02f-44399df492ff'}
74 8 Saúl Ibarra Corretgé
</pre>
75 8 Saúl Ibarra Corretgé
76 9 Saúl Ibarra Corretgé
The password MUST be in "HA1 format":https://en.wikipedia.org/wiki/Digest_access_authentication#Overview
77 1 Saúl Ibarra Corretgé
78 13 Saúl Ibarra Corretgé
h5. remove_account
79 9 Saúl Ibarra Corretgé
80 9 Saúl Ibarra Corretgé
Removes an account from the current connection.
81 9 Saúl Ibarra Corretgé
82 8 Saúl Ibarra Corretgé
<pre>
83 9 Saúl Ibarra Corretgé
{'account': 'saghul@sip2sip.info',
84 9 Saúl Ibarra Corretgé
 'sylkrtc': 'remove_account',
85 9 Saúl Ibarra Corretgé
 'transaction': 'bd3ee25d-5f16-4f76-b34e-8ac3fe0a4ac0'}
86 8 Saúl Ibarra Corretgé
</pre>
87 1 Saúl Ibarra Corretgé
88 13 Saúl Ibarra Corretgé
h5. register
89 1 Saúl Ibarra Corretgé
90 9 Saúl Ibarra Corretgé
Triggers the account registration via SIP.
91 1 Saúl Ibarra Corretgé
92 9 Saúl Ibarra Corretgé
<pre>
93 9 Saúl Ibarra Corretgé
{'account': 'saghul@sip2sip.info',
94 9 Saúl Ibarra Corretgé
 'sylkrtc': 'register',
95 9 Saúl Ibarra Corretgé
 'transaction': 'bcb87b0f-0cc7-42a9-897e-81f035910670'}
96 9 Saúl Ibarra Corretgé
</pre>
97 9 Saúl Ibarra Corretgé
98 9 Saúl Ibarra Corretgé
The registration progress will be reported in form of events.
99 9 Saúl Ibarra Corretgé
100 9 Saúl Ibarra Corretgé
<pre>
101 9 Saúl Ibarra Corretgé
{'account': 'saghul@sip2sip.info',
102 9 Saúl Ibarra Corretgé
 'data': {'state': 'registering'},
103 9 Saúl Ibarra Corretgé
 'event': 'registration_state',
104 9 Saúl Ibarra Corretgé
 'sylkrtc': 'account_event'}
105 9 Saúl Ibarra Corretgé
106 9 Saúl Ibarra Corretgé
{'account': 'saghul@sip2sip.info',
107 9 Saúl Ibarra Corretgé
 'data': {'state': 'registered'},
108 9 Saúl Ibarra Corretgé
 'event': 'registration_state',
109 9 Saúl Ibarra Corretgé
 'sylkrtc': 'account_event'}
110 9 Saúl Ibarra Corretgé
</pre>
111 9 Saúl Ibarra Corretgé
112 9 Saúl Ibarra Corretgé
Example of failed registration:
113 9 Saúl Ibarra Corretgé
114 9 Saúl Ibarra Corretgé
<pre>
115 9 Saúl Ibarra Corretgé
{'account': 'saghul@sip2sip.info',
116 9 Saúl Ibarra Corretgé
 'data': {'reason': '904 Operation has no matching challenge ',
117 9 Saúl Ibarra Corretgé
          'state': 'failed'},
118 9 Saúl Ibarra Corretgé
 'event': 'registration_state',
119 9 Saúl Ibarra Corretgé
 'sylkrtc': 'account_event'}
120 10 Saúl Ibarra Corretgé
</pre>
121 10 Saúl Ibarra Corretgé
122 13 Saúl Ibarra Corretgé
h5. unregister
123 10 Saúl Ibarra Corretgé
124 10 Saúl Ibarra Corretgé
Unregister the account, via SIP.
125 10 Saúl Ibarra Corretgé
126 10 Saúl Ibarra Corretgé
<pre>
127 10 Saúl Ibarra Corretgé
{'account': 'saghul@sip2sip.info',
128 10 Saúl Ibarra Corretgé
 'sylkrtc': 'unregister',
129 10 Saúl Ibarra Corretgé
 'transaction': '1c81eea0-b247-4ced-b3b3-3ced1eba810e'}
130 9 Saúl Ibarra Corretgé
</pre>
131 5 Saúl Ibarra Corretgé
132 5 Saúl Ibarra Corretgé
h3. Calling
133 5 Saúl Ibarra Corretgé
134 1 Saúl Ibarra Corretgé
h5. Incoming calls
135 1 Saúl Ibarra Corretgé
136 14 Saúl Ibarra Corretgé
Incoming calls are received via an *incoming_call* event:
137 14 Saúl Ibarra Corretgé
138 14 Saúl Ibarra Corretgé
<pre>
139 14 Saúl Ibarra Corretgé
{'account': 'saghul@sip2sip.info',
140 14 Saúl Ibarra Corretgé
 'data': {'caller': '31208005163@ag-projects.com', 'sdp': '...'},
141 14 Saúl Ibarra Corretgé
 'event': 'incoming_call',
142 14 Saúl Ibarra Corretgé
 'session': '509b256aa6a14540a2a37553e6bd33e1',
143 1 Saúl Ibarra Corretgé
 'sylkrtc': 'account_event'}
144 14 Saúl Ibarra Corretgé
145 1 Saúl Ibarra Corretgé
</pre>
146 1 Saúl Ibarra Corretgé
147 15 Saúl Ibarra Corretgé
The "answer" request can be used in order to answer an incoming call:
148 1 Saúl Ibarra Corretgé
149 15 Saúl Ibarra Corretgé
<pre>
150 15 Saúl Ibarra Corretgé
{'sdp': '...',
151 15 Saúl Ibarra Corretgé
 'session': '38dffdf81acb44b2b11b61f4488c4ca9',
152 15 Saúl Ibarra Corretgé
 'sylkrtc': 'answer',
153 15 Saúl Ibarra Corretgé
 'transaction': '179a855f-75a0-45a4-b5ef-0be8eb8389d1'}
154 15 Saúl Ibarra Corretgé
</pre>
155 15 Saúl Ibarra Corretgé
156 14 Saúl Ibarra Corretgé
h5. Outgoing calls
157 14 Saúl Ibarra Corretgé
158 14 Saúl Ibarra Corretgé
In order to create an outgoing call the "call" request is used, by passing the SDP returned by the web browser. There is no need to wait for all ICE candidates since trickle ICE is used.
159 14 Saúl Ibarra Corretgé
160 14 Saúl Ibarra Corretgé
<pre>
161 14 Saúl Ibarra Corretgé
{'account': 'saghul@sip2sip.info',
162 14 Saúl Ibarra Corretgé
 'sdp': '...',
163 14 Saúl Ibarra Corretgé
 'session': '20c40185-1ef2-419e-b91a-70415778acb4',
164 14 Saúl Ibarra Corretgé
 'sylkrtc': 'call',
165 1 Saúl Ibarra Corretgé
 'transaction': '7afcb91a-8a64-4664-9448-8cb760492e1f',
166 1 Saúl Ibarra Corretgé
 'uri': '3333@sip2sip.info'}
167 14 Saúl Ibarra Corretgé
</pre>
168 14 Saúl Ibarra Corretgé
169 15 Saúl Ibarra Corretgé
h5. Trickle ICE
170 15 Saúl Ibarra Corretgé
171 14 Saúl Ibarra Corretgé
As new candidates are discovered they must be sent to the server using 'trickle' requests:
172 14 Saúl Ibarra Corretgé
173 14 Saúl Ibarra Corretgé
<pre>
174 14 Saúl Ibarra Corretgé
{'candidates': [{'candidate': 'candidate:0 1 UDP 2130379007 192.168.99.44 59051 typ host',
175 14 Saúl Ibarra Corretgé
                 'sdpMLineIndex': 0,
176 14 Saúl Ibarra Corretgé
                 'sdpMid': ''}],
177 1 Saúl Ibarra Corretgé
 'session': '20c40185-1ef2-419e-b91a-70415778acb4',
178 1 Saúl Ibarra Corretgé
 'sylkrtc': 'trickle',
179 1 Saúl Ibarra Corretgé
 'transaction': 'ecf777d8-7d26-4f16-bace-18f6fae5d8f8'}
180 1 Saúl Ibarra Corretgé
</pre>
181 1 Saúl Ibarra Corretgé
182 15 Saúl Ibarra Corretgé
This applies to both incoming and outgoing calls.
183 15 Saúl Ibarra Corretgé
184 15 Saúl Ibarra Corretgé
There is no need to wait for the acknowledgement for the "call" or "answer" request before sending "trickle" requests.
185 15 Saúl Ibarra Corretgé
186 15 Saúl Ibarra Corretgé
h5. Terminating calls
187 15 Saúl Ibarra Corretgé
188 15 Saúl Ibarra Corretgé
A call can be terminated at any time by sending the "terminate" request:
189 15 Saúl Ibarra Corretgé
190 15 Saúl Ibarra Corretgé
<pre>
191 15 Saúl Ibarra Corretgé
{'session': '38dffdf81acb44b2b11b61f4488c4ca9',
192 15 Saúl Ibarra Corretgé
 'sylkrtc': 'terminate',
193 15 Saúl Ibarra Corretgé
 'transaction': '4d169de8-fe55-41f8-9a5c-c5f66c0a23c7'}
194 15 Saúl Ibarra Corretgé
</pre>
195 15 Saúl Ibarra Corretgé
196 15 Saúl Ibarra Corretgé
h5. Events
197 15 Saúl Ibarra Corretgé
198 16 Saúl Ibarra Corretgé
Call state related events are reported via the "session_event" event:
199 16 Saúl Ibarra Corretgé
200 16 Saúl Ibarra Corretgé
<pre>
201 16 Saúl Ibarra Corretgé
'data': {'state': 'established'},
202 16 Saúl Ibarra Corretgé
 'event': 'state',
203 16 Saúl Ibarra Corretgé
 'session': '38dffdf81acb44b2b11b61f4488c4ca9',
204 16 Saúl Ibarra Corretgé
 'sylkrtc': 'session_event'}
205 16 Saúl Ibarra Corretgé
</pre>
206 16 Saúl Ibarra Corretgé
207 16 Saúl Ibarra Corretgé
<pre>
208 16 Saúl Ibarra Corretgé
{'data': {'sdp': '...', 'state': 'accepted'},
209 16 Saúl Ibarra Corretgé
 'event': 'state',
210 16 Saúl Ibarra Corretgé
 'session': '20c40185-1ef2-419e-b91a-70415778acb4',
211 16 Saúl Ibarra Corretgé
 'sylkrtc': 'session_event'}
212 16 Saúl Ibarra Corretgé
</pre>
213 16 Saúl Ibarra Corretgé
214 16 Saúl Ibarra Corretgé
<pre>
215 16 Saúl Ibarra Corretgé
{'data': {'reason': '200 to BYE', 'state': 'terminated'},
216 16 Saúl Ibarra Corretgé
 'event': 'state',
217 16 Saúl Ibarra Corretgé
 'session': '20c40185-1ef2-419e-b91a-70415778acb4',
218 16 Saúl Ibarra Corretgé
 'sylkrtc': 'session_event'}
219 16 Saúl Ibarra Corretgé
</pre>
220 16 Saúl Ibarra Corretgé
221 16 Saúl Ibarra Corretgé
Valid call states:
222 16 Saúl Ibarra Corretgé
223 16 Saúl Ibarra Corretgé
* calling: on outgoing calls, when the call is in progress.
224 16 Saúl Ibarra Corretgé
* accepted: both for incoming and outgoing, when the call has been accepted by the remote party. For incoming calls, an "sdp" attribute will be present in the "data" section, as shown in the example above. 
225 16 Saúl Ibarra Corretgé
* established: the call has been established media-wise.
226 16 Saúl Ibarra Corretgé
* terminated: call was terminated, the "reason" attribute indicates the termination reason.
227 15 Saúl Ibarra Corretgé
228 4 Saúl Ibarra Corretgé
229 4 Saúl Ibarra Corretgé
h2. Configuration
230 4 Saúl Ibarra Corretgé
231 4 Saúl Ibarra Corretgé
TODO
232 2 Saúl Ibarra Corretgé
233 2 Saúl Ibarra Corretgé
h2. Client libraries
234 2 Saúl Ibarra Corretgé
235 1 Saúl Ibarra Corretgé
In order to interact with SylkServer's WebRTC gateway, we provide the "sylkrtc.js":http://projects.ag-projects.com/projects/sylkrtc JavaScript library. It implements the API described in this document in an easy to use manner. Check the README file in the project for the JavaScript API documentation.