Project

General

Profile

WebRTC » History » Version 8

Saúl Ibarra Corretgé, 07/30/2015 05:32 PM

1 1 Saúl Ibarra Corretgé
h1. SylkServer WebRTC gateway application
2
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
5
6
h2. Architecture
7
8 1 Saúl Ibarra Corretgé
TODO
9 2 Saúl Ibarra Corretgé
10
h2. WebSocket API
11
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
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
18
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
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
26
<pre>
27
var conn = new WebSocket('wss://example.com/webrtcgateway/ws', 'sylkRTC-1');
28
</pre>
29
30
After the connection is established, a 'ready' event will be sent to the client, indicating that the connection is ready to be used:
31
32
<pre>
33
{
34
  "sylkrtc": "event",
35
  "event": "ready"
36
}
37
38
</pre>
39 1 Saúl Ibarra Corretgé
40 7 Saúl Ibarra Corretgé
Example:
41
42
<pre>
43
var conn = new WebSocket('wss://example.com/webrtcgateway/ws', 'sylkRTC-1');
44
conn.onmessage = function(event) {
45
    var message = JSON.parse(event.data);
46
    switch (message.sylkrtc) {
47
        case 'event':
48
            if (message.event === 'ready') {
49
                console.log('Ready to rock!');
50
            }
51
            break;
52
        default:
53
            console.log('Received message type: ' + message.sylkrtc);
54
            break;
55
    }
56
};
57
</pre>
58
59 5 Saúl Ibarra Corretgé
h3. Account management
60
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
63
h4. add_account
64
65
Configuring an account, request:
66
67
<pre>
68
{'account': 'saghul@sip2sip.info',
69
 'password': '884edfee38ed471b8a15006700139485',
70
 'sylkrtc': 'add_account',
71
 'transaction': '04013f0f-25bb-4082-a02f-44399df492ff'}
72
</pre>
73
74
Response:
75
76
<pre>
77
{'sylkrtc': 'ack',
78
 'transaction': '04013f0f-25bb-4082-a02f-44399df492ff'}
79
</pre>
80
81
The password MUST be in "HA1 format":https://en.wikipedia.org/wiki/Digest_access_authentication#Overview
82
83
84 5 Saúl Ibarra Corretgé
85
h3. Calling
86
87
TODO
88 2 Saúl Ibarra Corretgé
89 4 Saúl Ibarra Corretgé
h2. Configuration
90
91
TODO
92
93 2 Saúl Ibarra Corretgé
h2. Client libraries
94
95
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.