WebRTC

Version 12 (Saúl Ibarra Corretgé, 07/30/2015 05: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 8 Saúl Ibarra Corretgé
h4. 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 9 Saúl Ibarra Corretgé
h4. 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 9 Saúl Ibarra Corretgé
h4. 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 10 Saúl Ibarra Corretgé
h4. 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 12 Saúl Ibarra Corretgé
h5. Outgoing calls
135 11 Saúl Ibarra Corretgé
136 11 Saúl Ibarra Corretgé
TODO
137 11 Saúl Ibarra Corretgé
138 12 Saúl Ibarra Corretgé
h5. Incoming calls
139 11 Saúl Ibarra Corretgé
140 2 Saúl Ibarra Corretgé
TODO
141 4 Saúl Ibarra Corretgé
142 4 Saúl Ibarra Corretgé
h2. Configuration
143 4 Saúl Ibarra Corretgé
144 4 Saúl Ibarra Corretgé
TODO
145 2 Saúl Ibarra Corretgé
146 2 Saúl Ibarra Corretgé
h2. Client libraries
147 2 Saúl Ibarra Corretgé
148 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.