Statistics
| Branch: | Revision:

janus-gateway / mainpage.dox @ 245ab74b

History | View | Annotate | Download (133 KB)

1
/*!
2
 * \mainpage Janus - General purpose WebRTC Gateway
3
 *
4
 * \par Developer Documentation for the Janus WebRTC Gateway
5
 * This is the main developer documentation for the Janus WebRTC
6
 * Gateway, generated with the help of
7
 * <a href="http://www.doxygen.org">Doxygen</a>. Make sure you
8
 * check the \ref DEPS before attempting a compilation. If you are
9
 * interested in how to compile, install and use the gateway,
10
 * checkout the \ref README information. A \ref FAQ page is also available.
11
 *
12
 * \par A general purpose gateway
13
 * The Janus WebRTC Gateway has been conceived as a <tt>general purpose</tt>
14
 * gateway. As such, it doesn't provide any functionality per se
15
 * other than implementing the means to set up a WebRTC media communication
16
 * with a browser, exchanging JSON messages with it, and relaying RTP/RTCP
17
 * and messages between browsers and the server-side application logic they're attached to. Any specific
18
 * feature/application needs to be implemented in server side plugins,
19
 * that browsers can then contact via the gateway to take advantage of
20
 * the functionality they provide. Example of such plugins can be
21
 * implementations of applications like echo tests, conference bridges,
22
 * media recorders, SIP gateways and the like.
23
 *
24
 * The reason for this is simple: we wanted something that would have a
25
 * <tt>small footprint</tt> (hence a C implementation) and that we could only
26
 * equip with what was <tt>really needed</tt> (hence pluggable modules). That is,
27
 * something that would allow us to deploy either a full-fledged WebRTC
28
 * gateway on the cloud, or a small nettop/box to handle a specific use case.
29
 *
30
 * \par Architecture and APIs
31
 * The core of the gateway is specified in the \ref core section. The protocols
32
 * implemented in the gateway are listed in the \ref protocols group
33
 * instead. A list of plugins made available out of the box by Meetecho
34
 * are available in the \ref plugins group: these plugins can be changed
35
 * or extended to match your requirements, or just used as a simple
36
 * reference should you be interested in writing a new plugin from
37
 * scratch (and you're definitely welcome to!). A \ref pluginapi to
38
 * create new plugins, or understand how they're conceived, is documented
39
 * as well. A documentation on the available API tranports and the
40
 * HTTP/WebSocket JavaScript API to use the gateway and the plugins it
41
 * makes available in your web application can be found in the \ref JS
42
 * and \ref rest pages. New API transports can be created referring to
43
 * the \ref transportapi page. If you're interested in monitoring Janus
44
 * resources, you can refer to the \ref admin page. Event handler plugins
45
 * plugins can also be used for the purpose: refer to the \ref eventhandlerapi
46
 * page if you're interested in creating your own.
47
 *
48
 * Finally, some information on how to deploy Janus and your web
49
 * applications that want to make use of it are provided in the \ref deploy
50
 * page. If you're interested in starting Janus as a service/daemon rather
51
 * than launching it normally, check the information provided in the
52
 * \ref service page. Some additional \ref resources are also listed in
53
 * case you're interested in talking to Janus from different languages
54
 * and platforms.
55
 *
56
 * This is only the first version of the gateway, and as such it is a bit
57
 * rough at the edges: there is definitely room for improvement, there are
58
 * bugs, limitations, and things that need to be done. For a quick glance
59
 * on the most relevant pending stuff check our \ref todo (and, if you're
60
 * willing to help on any of those, get in touch with us!). Make also
61
 * sure you read the \ref debug page for info on how you can help us
62
 * fixing issues you might encounter along the road.
63
 *
64
 * \section copyright Copyright and author
65
 *
66
 * Janus WebRTC Gateway © 2014-2016 <a href="http://www.meetecho.com/">Meetecho</a> (http://www.meetecho.com/)
67
 *
68
 * \author Lorenzo Miniero <lorenzo@meetecho.com> ( \ref CREDITS )
69
 *
70
 * \section license License
71
 * This program is free software, distributed under the terms of
72
 * the GNU General Public License Version 3. For more details and licensing
73
 * options, including a commercial license, see the \ref COPYING page.
74
 *
75
*/
76

    
77
/*! \page DEPS Dependencies
78
 *
79
 * The application and the plugins depend on the following open source
80
 * software and libraries, so make sure you install the related development
81
 * versions before attempting a compilation:
82
 *
83
 * - \b GLib: http://library.gnome.org/devel/glib/
84
 * - \b pkg-config: http://www.freedesktop.org/wiki/Software/pkg-config/
85
 * - \b gengetopt: http://www.gnu.org/software/gengetopt/ (command line)
86
 * - \b libini-config: https://fedorahosted.org/sssd/ (INI configurations)
87
 * - \b Jansson: http://www.digip.org/jansson/ (JSON)
88
 * - \b libnice: http://nice.freedesktop.org/wiki/ (ICE/STUN/TURN)
89
 * - \b OpenSSL: http://www.openssl.org/ (DTLS, at least v1.0.1e)
90
 * - \b libsrtp: https://github.com/cisco/libsrtp (SRTP, at least v1.5 suggested)
91
 * - \b usrsctp: http://code.google.com/p/sctp-refimpl/ (\c optional, Data Channels)
92
 * - \b libmicrohttpd: http://www.gnu.org/software/libmicrohttpd/ (\c optional, Web server)
93
 * - \b libwebsockets: https://libwebsockets.org/ (\c optional, WebSockets)
94
 * - \b rabbitmq-c: https://github.com/alanxz/rabbitmq-c (\c optional, v1.0.4, RabbitMQ)
95
 * - \b paho.mqtt.c: https://eclipse.org/paho/clients/c (\c optional, v1.1.0, MQTT)
96
 * - \b Sofia-SIP: http://sofia-sip.sourceforge.net/ (\c optional, only needed for the SIP plugin)
97
 * - \b libopus: http://opus-codec.org/ (\c optional, only needed for the bridge plugin)
98
 * - \b libogg: http://xiph.org/ogg/ (\c optional, only needed for the voicemail plugin)
99
 * - \b libcurl: https://curl.haxx.se/libcurl/ (\c optional, only needed for the TURN REST API,
100
 * RTSP support in the Streaming plugin and the sample Event Handler plugin)
101
 *
102
 */
103

    
104
/*! \page JS JavaScript API
105
 * The gateway exposes, assuming the HTTP transport has been compiled, a
106
 * pseudo-RESTful interface, and optionally also WebSocket/RabbitMQ/MQTT/UnixSockets
107
 * interfaces as well, all of which based on JSON messages. These
108
 * interfaces are described in more detail in the \ref plainhttp \ref WS
109
 * \ref rabbit \ref mqtt and \ref unix documentation respectively, and all allow clients to
110
 * take advantage of the features provided by Janus and the functionality
111
 * made available by its plugins. Considering most clients will be web browsers,
112
 * a common choice will be to rely on either the REST or the WebSockets
113
 * interface for the purpose. To make things easier for web
114
 * developers, a JavaScript library (\c janus.js) is available that can
115
 * make use of both interfaces using exactly the same API. This library
116
 * eases the task of creating sessions with the gateway, attaching WebRTC
117
 * users to plugins, send and receive requests and events to the plugins
118
 * themselves and so on. For real examples of how this library can be
119
 * used, check the demos in the \b html folder of this package.
120
 *
121
 * \note The current \c janus.js library makes use of jQuery (http://jquery.com/)
122
 * as a support. A version without that dependency is available as
123
 * \c janus.nojquery.js in the same folder, so you can use that one instead
124
 * if required by your web application: all the documentation related to
125
 * \c janus.js applies to \c janus.nojquery.js as well.
126
 *
127
 * In general, when using the gateway features, you would normally do the following:
128
 *
129
 * -# include the Janus JavaScript library in your web page;
130
 * -# initialize the Janus JavaScript library;
131
 * -# connect to the gateway and create a session;
132
 * -# create one or more handles to attach to a plugin (e.g., echo test and/or streaming);
133
 * -# interact with the plugin (sending/receiving messages, negotiating a PeerConnection);
134
 * -# eventually, close all the handles and shutdown the related PeerConnections;  
135
 * -# destroy the session.  
136
 *
137
 * The above steps will be presented in order, describing how you can use
138
 * the low level API to accomplish them. Consider that in the future we might
139
 * provide higher level wrappers to this API to address specific needs, e.g.,
140
 * a higher level API for each plugin: this would make it even easier to use
141
 * the gateway features, as a high level API for the streaming plugin, for
142
 * instance, may just ask you to provide the server address and the ID of
143
 * the \c &lt;video&gt; element to display the stream in, and would take care of all the
144
 * above mentioned steps on your behalf. Needless to say, you're very welcome
145
 * to provide wrapper APIs yourself, if you feel a sudden urge to do so! :-)
146
 *
147
 * <hr>
148
 *
149
 * As a first step, you should include the \c janus.js library in your project:
150
 *
151
\verbatim
152
<script type="text/javascript" src="janus.js" ></script>
153
\endverbatim
154
 *
155
 * The core of the JavaScript API is the \c Janus object. This object needs
156
 * to be initialized the first time it is used in a page. This can be done
157
 * using the static \c init method of the object, which accepts the
158
 * following options:
159
 *
160
 * - \c debug: whether debug should be enabled on the JavaScript console, and what levels
161
 *   - \c true or \c "all": all debuggers enabled (Janus.trace, Janus.debug, Janus.log, Janus.warn, Janus.error)
162
 *   - array (e.g., <code>["trace", "warn"]</code>): only enable selected debuggers (allowed tokens: trace, debug, log, warn, error)
163
 *   - \c false: disable all debuggers
164
 * - \c callback: a user provided function that is invoked when the initialization is complete. 
165
 *
166
 * Here's an example:
167
 *
168
 *
169
 \verbatim
170
Janus.init({
171
   debug: true,
172
   callback: function() {
173
	   // Done!
174
   });
175
 \endverbatim
176
 *
177
 * Once the library has been initialized, you can start creating sessions.
178
 * Normally, each browser tab will need a single session with the gateway: in
179
 * fact, each gateway session can contain several different plugin handles
180
 * at the same time, meaning you can start several different WebRTC sessions
181
 * with the same or different plugins for the same user using the same
182
 * gateway session. That said, you're free to set up different gateway
183
 * sessions in the same page, should you prefer so.
184
 *
185
 * Creating a session is quite easy. You just need to use the \c new constructor
186
 * to create a new \c Janus object that will handle your interaction with the
187
 * gateway. Considering the dynamic and asynchronous nature of Janus sessions
188
 * (events may occur at any time), there are several properties and callbacks you
189
 * can configure when creating a session:
190
 *
191
 * - \c server: the address of the gateway as a specific address (e.g.,
192
 * http://yourserver:8088/janus to use the plain HTTP API or ws://yourserver:8188/
193
 * for WebSockets) or as an array of addresses to try sequentially to allow
194
 * automatic for fallback/failover during setup;
195
 * - \c iceServers: a list of STUN/TURN servers to use (a default STUN server
196
 * will be used if you skip this property);
197
 * - a set of callbacks to be notified about events, namely:
198
 * 		- \c success: the session was successfully created and is ready to be used;
199
 * 		- \c error: the session was NOT successfully created;
200
 * 		- \c destroyed: the session was destroyed and can't be used any more.
201
 *
202
 * These properties and callbacks are passed to the method as properties
203
 * of a single parameter object: that is, the \c Janus constructor takes a
204
 * single parameter, which although acts as a container for all the available
205
 * options. The \c success callback is where you tipically start your application
206
 * logic, e.g., attaching the peer to a plugin and start a media session.
207
 *
208
 * Here's an example:
209
 *
210
 \verbatim
211
var janus = new Janus(
212
	{
213
		server: 'http://yourserver:8088/janus',
214
		success: function() {
215
			// Done! attach to plugin XYZ
216
		},
217
		error: function(cause) {
218
			// Error, can't go on...
219
		},
220
		destroyed: function() {
221
			// I should get rid of this
222
		}
223
	});
224
 \endverbatim
225
 *
226
 * As anticipated, the server may be a specific address, e.g.:
227
 *
228
 \verbatim
229
var janus = new Janus(
230
	{
231
		server: 'http://yourserver:8088/janus',
232
				// or
233
		server: 'ws://yourserver:8188/',
234
		[..]
235
 \endverbatim
236
 *
237
 * or an array of addresses. Such an array can be especially useful if
238
 * you want the library to first check if the WebSockets server is
239
 * reachable and, if not, fallback to plain HTTP, or just to provide
240
 * a link multiple instances to try for failover. This is an example of
241
 * how to pass a 'try websockets and fallback to HTTP' array:
242
 *
243
 \verbatim
244
var janus = new Janus(
245
	{
246
		server: ['ws://yourserver:8188/','http://yourserver:8088/janus'],
247
		[..]
248
 \endverbatim
249
 *
250
 * Once created, this object represents your session with the gateway.
251
 * you can interact with a \c Janus object in several different ways.
252
 * In particular, the following properties and methods are defined:
253
 *
254
 * - \c getServer(): returns the address of the gateway;
255
 * - \c isConnected(): returns \c true if the Janus instance is connected
256
 * to the gateway, \c false otherwise;
257
 * - \c getSessionId(): returns the unique gateway session identifier;
258
 * - \c attach(parameters): attaches the session to a plugin, creating an handle;
259
 * more handles to the same or different plugins can be created at the same time;
260
 * - \c destroy(parameters): destroys the session with the gateway, and closes
261
 * all the handles (and related PeerConnections) the session may have with any plugin as well.
262
 *
263
 * The most important property is obviously the \c attach() method, as
264
 * it's what will allow you to exploit the features of a plugin to manipulate
265
 * the media sent and/or received by a PeerConnection in your web page.
266
 * This method will create a plugin handle you can use for the purpose,
267
 * for which you can configure properties and callbacks when calling the
268
 * \c attach() method itself. As for the \c Janus constructor, the \c attach()
269
 * method takes a single parameter that can contain any of the following
270
 * properties and callbacks:
271
 *
272
 * - \c plugin: the unique package name of the plugin (e.g., \c janus.plugin.echotest );
273
 * - \c opaqueId: an optional opaque string meaningful to your application (e.g., to map all the handles of the same user);
274
 * - \c token , \c apisecret: optional parameters only needed in case you're \ref auth ;
275
 * - a set of callbacks to be notified about events, namely:
276
 * 		- \c success: the handle was successfully created and is ready to be used;
277
 * 		- \c error: the handle was NOT successfully created;
278
 * 		- \c consentDialog: this callback is triggered just before \c getUserMedia is called
279
 * (parameter=<b>true</b>) and after it is completed (parameter=<b>false</b>); this means it can
280
 * be used to modify the UI accordingly, e.g., to prompt the user about the need to accept the device access consent requests;
281
 * 		- \c webrtcState: this callback is triggered with a <b>true</b> value
282
 * when the PeerConnection associated to a handle becomes active (so ICE, DTLS and
283
 * everything else succeeded) from the Janus perspective, while <b>false</b> is
284
 * triggered when the PeerConnection goes down instead; useful to figure out
285
 * when WebRTC is actually up and running between you and Janus (e.g., to notify
286
 * a user they're actually now active in a conference);
287
 * 		- \c mediaState: this callback is triggered when Janus starts or stops
288
 * receiving your media: for instance, a \c mediaState with type=<b>audio</b> and
289
 * on=<b>true</b> means Janus started receiving your audio stream (or started
290
 * getting them again after a pause of more than a second); a \c mediaState with
291
 * type=<b>video</b> and on=<b>false</b> means Janus hasn't received any video
292
 * from you in the last second, after a start was detected before; useful to
293
 * figure out when Janus actually started handling your media, or to detect
294
 * problems on the media path (e.g., media never started, or stopped at some time);
295
 * 		- \c slowLink: this callback is triggered when Janus reports trouble
296
 * either sending or receiving media on the specified PeerConnection, typically
297
 * as a consequence of too many NACKs received from/sent to the user in the
298
 * last second: for instance, a \c slowLink with uplink=<b>true</b> means
299
 * you notified several missing packets from Janus, while uplink=<b>false</b>
300
 * means Janus is not receiving all your packets; useful to figure out when
301
 * there are problems on the media path (e.g., excessive loss), in order to
302
 * possibly react accordingly (e.g., decrease the bitrate if most of our
303
 * packets are getting lost);
304
 * 		- \c onmessage: a message/event has been received from the plugin;
305
 * 		- \c onlocalstream: a local \c MediaStream is available and ready to be displayed;
306
 * 		- \c onremotestream: a remote \c MediaStream is available and ready to be displayed;
307
 * 		- \c ondataopen: a Data Channel is available and ready to be used;
308
 * 		- \c ondata: data has been received through the Data Channel;
309
 * 		- \c oncleanup: the WebRTC PeerConnection with the plugin was closed;
310
 * 		- \c detached: the plugin handle has been detached by the plugin itself,
311
 * and so should not be used anymore.
312
 *
313
 * Here's an example:
314
 *
315
 \verbatim
316
// Attach to echo test plugin, using the previously created janus instance
317
janus.attach(
318
	{
319
		plugin: "janus.plugin.echotest",
320
		success: function(pluginHandle) {
321
			// Plugin attached! 'pluginHandle' is our handle
322
		},
323
		error: function(cause) {
324
			// Couldn't attach to the plugin
325
		},
326
		consentDialog: function(on) {
327
			// e.g., Darken the screen if on=true (getUserMedia incoming), restore it otherwise
328
		},
329
		onmessage: function(msg, jsep) {
330
			// We got a message/event (msg) from the plugin
331
			// If jsep is not null, this involves a WebRTC negotiation
332
		},
333
		onlocalstream: function(stream) {
334
			// We have a local stream (getUserMedia worked!) to display
335
		},
336
		onremotestream: function(stream) {
337
			// We have a remote stream (working PeerConnection!) to display
338
		},
339
		oncleanup: function() {
340
			// PeerConnection with the plugin closed, clean the UI
341
			// The plugin handle is still valid so we can create a new one
342
		},
343
		detached: function() {
344
			// Connection with the plugin closed, get rid of its features
345
			// The plugin handle is not valid anymore
346
		}
347
	});
348
 \endverbatim
349
 *
350
 * So the \c attach() method allows you to attach to a plugin, and specify 
351
 * the callbacks to invoke when anything relevant happens in this interaction.
352
 * To actively interact with the plugin, you can use the \c Handle object
353
 * that is returned by the \c success callback (pluginHandle in the example).
354
 *
355
 * This \c Handle object has several methods you can use to interact with
356
 * the plugin or check the state of the session handle:
357
 *
358
 * - \c getId(): returns the unique handle identifier;
359
 * - \c getPlugin(): returns the unique package name of the attached plugin;
360
 * - \c send(parameters): sends a message (with or without a jsep to
361
 * negotiate a PeerConnection) to the plugin;
362
 * - \c createOffer(callbacks): asks the library to create a WebRTC compliant OFFER;
363
 * - \c createAnswer(callbacks): asks the library to create a WebRTC compliant ANSWER;
364
 * - \c handleRemoteJsep(callbacks): asks the library to handle an incoming WebRTC compliant session description;
365
 * - \c dtmf(parameters): sends a DTMF tone on the PeerConnection;
366
 * - \c data(parameters): sends data through the Data Channel, if available;
367
 * - \c getBitrate(): gets a verbose description of the currently received stream bitrate;
368
 * - \c hangup(sendRequest): tells the library to close the PeerConnection; if the optional \c sendRequest argument is
369
 * set to \c true, then a \c hangup Janus API request is sent to Janus as well (disabled by default, Janus can usually
370
 * figure this out via DTLS alerts and the like but it may be useful to enable it sometimes);
371
 * - \c detach(parameters): detaches from the plugin and destroys the handle, tearing
372
 * down the related PeerConnection if it exists.
373
 *
374
 * While the \c Handle API may look complex, it's actually quite straightforward
375
 * once you get the concept. The only step that may require a little more
376
 * effort to understand is the PeerConnection negotiation, but again, if
377
 * you're familiar with the WebRTC API, the \c Handle actually makes it
378
 * a lot easier.
379
 *
380
 * The idea behind it's usage is the following:
381
 *
382
 * -# you use \c attach() to create a \c Handle object;
383
 * -# in the \c success callback, your application logic can kick in: you may
384
 * want to send a message to the plugin (<code>send({msg})</code>), negotiate
385
 * a PeerConnection with the plugin right away ( \c createOffer followed
386
 * by a <code>send({msg, jsep})</code>) or wait for something to happen to do anything;
387
 * -# the \c onmessage callback tells you when you've got messages from the plugin;
388
 * if the \c jsep parameter is not null, just pass it to the library, which will take
389
 * care of it for you; if it's an \b OFFER use \c createAnswer (followed by a
390
 * <code>send({msg, jsep})</code> to close the loop with the plugin), otherwise use
391
 * \c handleRemoteJsep ;
392
 * -# whether you took the initiative to set up a PeerConnection or the plugin did,
393
 * the \c onlocalstream and/or the \c onremotestream callbacks will provide
394
 * you with a stream you can display in your page;
395
 * -# each plugin may allow you to manipulate what should flow through the
396
 * PeerConnection channel: the \c send method and \c onmessage callback
397
 * will allow you to handle this interaction (e.g., to tell the plugin
398
 * to mute your stream, or to be notified about someone joining a virtual room),
399
 * while the \c ondata callback is triggered whenever data is received
400
 * on the Data Channel, if available (and the \c ondataopen callback
401
 * will tell you when a Data Channel is actually available). 
402
 *
403
 * The following paragraphs will delve a bit deeper in the negotiation
404
 * mechanism provided by the \c Handle API, in particular describing
405
 * the properties and callbacks that may be involved. To follow the approach
406
 * outlined by the W3C WebRTC API, this negotiation mechanism is heavily
407
 * based on asynchronous methods as well.
408
 *
409
 * - \c createOffer takes a single parameter, that can contain any of the
410
 * following properties and callbacks:
411
 *   - \c media: you can use this property to tell the library which media (audio/video/data)
412
 * you're interested in, and whether you're going to send and/or receive any of them; by default
413
 * audio and video are enabled in both directions, while the Data Channels are disabled;
414
 * this option is an object that can take any of the following properties:
415
 *     - \c audioSend: \c true/false (do or do not send audio);
416
 *     - \c audioRecv: \c true/false (do or do not receive audio);
417
 *     - \c audio: \c true/false (do or do not send \b and receive audio, takes precedence on the above);
418
 *     - \c audio: object with \c deviceId property (specify ID of audio device to capture, takes precedence on the above;
419
 * devices list can be accessed with \c Janus.listDevices(callback) );
420
 *     - \c videoSend: \c true/false (do or do not send video);
421
 *     - \c videoRecv: \c true/false (do or do not receive video);
422
 *     - \c video: \c true/false (do or do not send \b and receive video, takes precedence on the above);
423
 *     - \c video: \c "lowres"/"lowres-16:9"/"stdres"/"stdres-16:9"/"hires"/"hires-16:9"
424
 * (send a 320x240/320x180/640x480/640x360/1280x720 video, takes precedence on the above; default is \c "stdres" )
425
 * this property will affect the resulting getUserMedia that the library will issue; please
426
 * notice that Firefox doesn't support the \c "16:9" variants, which will fallback
427
 * to the ones; besides, \c "hires" and \c "hires-16:9" are currently synonymous, as
428
 * there's no 4:3 high resolution constraint as of now;
429
 *     - \c video: \c "screen" (use screensharing for video, disables audio, takes precedence on both audio and video);
430
 *     - \c video: object with \c deviceId , \c width and/or \c height properties (specify ID of video device to capture
431
 * and optionally resolution to use, takes precedence on the above; devices list can be accessed with \c Janus.listDevices(callback) );
432
 *     - \c data: \c true/false (do or do not use Data Channels, default is false)
433
 *     - \c failIfNoAudio: \c true/false (whether a getUserMedia should fail if audio send is asked, but no audio device is available, default is false)
434
 *     - \c failIfNoVideo: \c true/false (whether a getUserMedia should fail if video send is asked, but no video device is available, default is false)
435
 *   - \c trickle: \c true/false, to tell the library whether you want
436
 * Trickle ICE to be used (true, the default) or not (false);
437
 *   - \c stream: optional, only to be passed in case you obtained a MediaStream object yourself with a \c getUserMedia
438
 * request, and that you want the library to use instead of having it get one by itself (makes
439
 * the \c media property useless, as it won't be read for accessing any device);
440
 *   - a set of callbacks to be notified about the result, namely:
441
 *     - \c success: the session description was created (attached as a parameter) and is ready to be sent to the plugin; 
442
 *     - \c error: the session description was NOT successfully created;
443
 * - \c createAnswer takes the same options as createOffer, but requires
444
 * an additional one as part of the single parameter argument:
445
 *   - \c jsep: the session description sent by the plugin (e.g., as received
446
 * in an \c onmessage callback) as its OFFER.
447
 *
448
 * Whether you use \c createOffer or \c createAnswer depending on the scenario,
449
 * you should end up with a valid \c jsep object returned in the \c success
450
 * callback. You can attach this \c jsep object to a message in a \c send request
451
 * to pass it to the plugin, and have the gateway negotiate a PeerConnection
452
 * with your application.
453
 *
454
 * Here's an example of how to use \c createOffer, taken from the Echo Test demo page:
455
 *
456
 \verbatim
457
// Attach to echo test plugin
458
janus.attach(
459
	{
460
		plugin: "janus.plugin.echotest",
461
		success: function(pluginHandle) {
462
			// Negotiate WebRTC
463
			echotest = pluginHandle;
464
			var body = { "audio": true, "video": true };
465
			echotest.send({"message": body});
466
			echotest.createOffer(
467
				{
468
					// No media property provided: by default,
469
						// it's sendrecv for audio and video
470
					success: function(jsep) {
471
						// Got our SDP! Send our OFFER to the plugin
472
						echotest.send({"message": body, "jsep": jsep});
473
					},
474
					error: function(error) {
475
						// An error occurred...
476
					}
477
				});
478
		},
479
		[..]
480
		onmessage: function(msg, jsep) {
481
			// Handle msg, if needed, and check jsep
482
			if(jsep !== undefined && jsep !== null) {
483
				// We have the ANSWER from the plugin
484
				echotest.handleRemoteJsep({jsep: jsep});
485
			}
486
		},
487
		[..]
488
		onlocalstream: function(stream) {
489
			// Invoked after createOffer
490
			// This is our video
491
		},
492
		onremotestream: function(stream) {
493
			// Invoked after handleRemoteJsep has got us a PeerConnection
494
			// This is the remote video
495
		},
496
		[..]
497
  \endverbatim
498
 *
499
 * This, instead, is an example of how to use \c createAnswer, taken from the Streaming demo page:
500
 *
501
 \verbatim
502
// Attach to echo test plugin
503
janus.attach(
504
	{
505
		plugin: "janus.plugin.streaming",
506
		success: function(pluginHandle) {
507
			// Handle created
508
			streaming = pluginHandle;
509
			[..]
510
		},
511
		[..]
512
		onmessage: function(msg, jsep) {
513
			// Handle msg, if needed, and check jsep
514
			if(jsep !== undefined && jsep !== null) {
515
				// We have an OFFER from the plugin
516
				streaming.createAnswer(
517
					{
518
						// We attach the remote OFFER
519
						jsep: jsep,
520
						// We want recvonly audio/video
521
						media: { audioSend: false, videoSend: false },
522
						success: function(ourjsep) {
523
							// Got our SDP! Send our ANSWER to the plugin
524
							var body = { "request": "start" };
525
							streaming.send({"message": body, "jsep": ourjsep});
526
						},
527
						error: function(error) {
528
							// An error occurred...
529
						}
530
					});
531
			}
532
		},
533
		[..]
534
		onlocalstream: function(stream) {
535
			// This will NOT be invoked, we chose recvonly
536
		},
537
		onremotestream: function(stream) {
538
			// Invoked after send has got us a PeerConnection
539
			// This is the remote video
540
		},
541
		[..]
542
  \endverbatim
543
 *
544
 * Of course, these are just a couple of examples where the scenarios
545
 * assumed that one plugin would only receive (Echo Test) or generate
546
 * (Streaming) offers. A more complex example (e.g., a Video Call plugin)
547
 * would involve both, allowing you to either send offers to a plugin,
548
 * or receive some from them. Handling this is just a matter of checking
549
 * the \c type of the \c jsep object and reacting accordingly.
550
 *  
551
 * <hr>
552
 *
553
 * This is it! For more information about the API, have a look at the
554
 * demo pages that are available in the \b html folder in this package.
555
 *
556
 */
557

    
558
/*! \page rest RESTful, WebSockets, RabbitMQ, MQTT and UnixSockets API
559
 *
560
 * Since version \c 0.0.6, there are three different ways to interact with a
561
 * Janus instance: a \ref plainhttp (the default), a \ref WS, a \ref rabbit, \ref mqtt
562
 * and a \ref unix (both optional, need an external library to be available). All of
563
 * the interfaces use the same messages (in terms of requests, responses
564
 * and notifications), so almost all the concepts described in the
565
 * \ref plainhttp section apply to the WebSocket/RabbitMQ/MQTT/UnixSockets interfaces as well.
566
 * Besides, since version \c 0.1.0 the transport mechanism for the Janus API
567
 * has been made modular, which means other protocols for transporting
568
 * Janus API messages might become available in the future: considering the
569
 * Janus protocol is supposed to be mostly agnostic to the protocol it is
570
 * transported on, the concepts explained in the following sections should
571
 * apply to those as well.
572
 *
573
 * As it will be explained later in the \ref WS, \ref rabbit and \ref unix sections
574
 * below, the only differences come when addressing specific sessions/handles
575
 * and in part in how you handle notifications using something different than
576
 * the REST interface: in fact, since with WebSockets, RabbitMQ, MQTT and UnixSockets
577
 * (and, as anticipated, with other protocols that may be added in the future too)
578
 * there's no REST-based path involved, you'll need a couple of additional
579
 * identifiers to bridge the gap.
580
 * Some details are also provided in case you're interested in \ref auth.
581
 *
582
 * \section plainhttp Plain HTTP REST Interface
583
 * As anticipated in the \ref JS documentation, the gateway deploys a
584
 * RESTful interface that clients can exploit. The \c janus.js library
585
 * makes use of it in a transparent way, but if you're interested in
586
 * more details about it (e.g., because you want to talk to the gateway
587
 * your own way), this page described the interface and the protocol
588
 * the API exposes and uses.
589
 *
590
 * There are basically three types/levels of endpoints you can meet:
591
 *
592
 * -# \ref root (\c /janus by default, but configurable), which
593
 * you only \b POST to in order to create a gateway session;
594
 * -# \ref sessions (e.g., \c /janus/12345678, using the
595
 * identifier retrieved with a previous create), which you either send
596
 * a \b GET to (long poll for events and messages from plugins) or a \b POST
597
 * (to create plugin handles or manipulate the session);
598
 * -# \ref handles (e.g., \c /janus/12345678/98765432, appending
599
 * the handle identifier to the session one) which you only send \b POST
600
 * messages to (messages/negotiations for a plugin, handle manipulation),
601
 * as all events related to this handle would be received in the session
602
 * endpoint \b GET (the \c janus.js library would redirect the incoming
603
 * messages to the right handle internally).
604
 *
605
 * Messages and requests you can send to and receive from any of the
606
 * above mentioned endpoints are described in the following chapters.
607
 * In general, all messages share at least two fields:
608
 *
609
 * - \c janus: the request/event (e.g., "create", "attach", "message", etc.);
610
 * - \c transaction: a random string that the client can use to match incoming
611
 * messages from the gateway (since, as explained in the \ref plugins
612
 * documentation, all messages are asynchronous).
613
 *
614
 * Different messages will of course add different information to this
615
 * base syntax. Error message, instead, usually have these fields:
616
 *
617
 * - \c janus: this would be "error";
618
 * - \c transaction: this would be the transaction identifier of the request
619
 * that failed;
620
 * - \c error: a JSON object containing two fields:
621
 *   - \c code: a numeric error code, as defined in apierror.h;
622
 *   - \c reason: a verbose string describing the cause of the failure.
623
 *
624
 * An example of an error is presented here:
625
 *
626
\verbatim
627
{
628
	"janus" : "error",
629
	"transaction" : "a1b2c3d4"
630
	"error" : {
631
		"code" : 458
632
		"reason" : "Could not find session 12345678"
633
	}
634
}
635
\endverbatim
636
 *
637
 *
638
 * \section info Getting info about the Janus instance
639
 * The API exposes an \c info endpoint you can query to get information
640
 * about the Janus instance you're talking to. Specifically, it returns
641
 * information about the version of the Janus server, whether some of the
642
 * optional features (e.g., Data Channels or IPv6) are supported or not, 
643
 * and which transports and plugins are available.
644
 *
645
 * To get this information, just send an HTTP \b GET message to the \c info
646
 * endpoint (e.g., http://yourserver:8088/janus/info), which will return
647
 * something like this:
648
 *
649
\verbatim
650
{
651
	"janus": "server_info",
652
	"transaction": "i1bzIL341Kl2",
653
	"name": "Janus WebRTC Gateway",
654
	"version": 10,
655
	"version_string": "0.1.0",
656
	"author": "Meetecho s.r.l.",
657
	"data_channels": "true",	// Data channels are supported
658
	"ipv6": "false",			// IPv6 is not configured
659
	"ice-tcp": "false",			// ICE-TCP support is disabled
660
	"transports": {
661
		"janus.transport.http": {
662
			"name": "JANUS REST (HTTP/HTTPS) transport plugin",
663
			"author": "Meetecho s.r.l.",
664
			"description": "This transport plugin adds REST (HTTP/HTTPS) support to the Janus API via libmicrohttpd.",
665
			"version_string": "0.0.1",
666
			"version": 1
667
		},
668
		[..]	// Other transport plugins
669
	},
670
	"plugins": {
671
		"janus.plugin.sip": {		// The SIP plugin is available
672
			"version_string": "0.0.2",
673
			"description": "This is a simple SIP plugin for Janus, allowing WebRTC peers to register at a SIP server and call SIP user agents through the gateway.",
674
			"author": "Meetecho s.r.l.",
675
			"name": "JANUS SIP plugin",
676
			"version": 2
677
		},
678
		"janus.plugin.videoroom": {	// The Video MCU plugin is available
679
			"version_string": "0.0.3",
680
			"description": "This is a plugin implementing a videoconferencing MCU for Janus, something like Licode.",
681
			"author": "Meetecho s.r.l.",
682
			"name": "JANUS VideoRoom plugin",
683
			"version": 3
684
		},
685
		[..]	// Other plugins
686
	}
687
\endverbatim
688
 *
689
 * You can use this information to selectively enable or disable features
690
 * in your application according to what's available in the Janus instance
691
 * you're trying to contact.
692
 *
693
 *
694
 * \section root The gateway root
695
 * The gateway root is \c /janus by default but, as anticipated, it is
696
 * configurable, either via command line or in the \c janus.cfg configuration.
697
 *
698
 * You can only contact the gateway root when you want to create a new
699
 * session with the gateway. To do so, you need to \b POST the a \c janus "create"
700
 * JSON message to the gateway:
701
 *
702
\verbatim
703
{
704
	"janus" : "create",
705
	"transaction" : "<random alphanumeric string>"
706
}
707
\endverbatim
708
 *
709
 * If the request is successful, you'll receive the unique session identifier
710
 * in a response formatted like this:
711
 *
712
\verbatim
713
{
714
	"janus" : "success",
715
	"transaction" : "<same as the request>",
716
	"data" : {
717
		"id" : <unique integer session ID>
718
	}
719
}
720
\endverbatim
721
 *
722
 * In case of an error, you'll receive an error message as the one introduced
723
 * before. This request, if issued with a POST to the gateway root, can only
724
 * fail if you miss any of the required fields in the request.
725
 *
726
 *
727
 * \section sessions The session endpoint
728
 * Once you've created a session, a new endpoint you can use is created
729
 * in the gateway. Specifically, the new endpoint is constructed by
730
 * concatenating the gateway root and the session identifier you've been
731
 * returned (\c e.g., \c /janus/12345678).
732
 *
733
 * This endpoint can be used in two different ways: 
734
 *
735
 * -# using a parameter-less \b GET request to the endpoint, you'll
736
 * issue a long-poll request to be notified about events and incoming
737
 * messages from this session;
738
 * -# using a \b POST request to send JSON messages, you'll interact
739
 * with the session itself.
740
 *
741
 * <hr>
742
 *
743
 * \par Long-poll requests
744
 * The long-poll will only trigger events related to messages you're
745
 * being sent from plugins, and as such will be clearer to understand
746
 * once you read the \ref handles section. That said, the events are formatted
747
 * this way:
748
 *
749
 * - \c janus: this would be "event";
750
 * - \c sender: this would be the unique numeric plugin handle identifier;
751
 * - \c transaction: this is optional: it is either related to a request
752
 * you sent to a plugin before, or it may be missing in case this is an
753
 * event the plugin sent on its own account;
754
 * - \c plugindata: a JSON object containing the info coming from the plugin itself:
755
 *   - \c plugin: the plugin's unique package name (e.g., \c janus.plugin.echotest);
756
 *   - \c data: an opaque JSON object that is plugin specific.
757
 * - \c jsep: an optional JSON object containing the JSEP SDP (offer or
758
 * answer) the plugin may send to negotiate a WebRTC PeerConnection with
759
 * the client (check the \ref handles section for more details).
760
 *
761
 * An example of such an event (in this case, sent by the janus_echotest.c
762
 * plugin in response to a request) is presented here:
763
 *
764
\verbatim
765
{
766
	"janus" : "event",
767
	"sender" : 1815153248,
768
	"transaction" : "sBJNyUhH6Vc6",
769
	"plugindata" : {
770
		"plugin": "janus.plugin.echotest",
771
		"data" : {
772
			"echotest" : "event",
773
			"result" : "ok"
774
		}
775
	},
776
}
777
\endverbatim
778
 *
779
 * The long-poll request has a 30 seconds timeout. If it has no event to
780
 * report, a simple \em keep-alive message will be triggered:
781
 *
782
\verbatim
783
{
784
	"janus" : "keepalive",
785
}
786
\endverbatim
787
 *
788
 * As with all long-poll based approaches, it's up to your application
789
 * to send a new polling request as soon as an event or a keep-alive
790
 * has been received.
791
 *
792
 * Notice that, by default, the long poll returns a single event: that is,
793
 * as soon as a message becomes available in the session queue, that event
794
 * is returned and the long poll closes. If you want to receive more events
795
 * within the context of the same long poll, you can pass the \c maxev
796
 * query string parameter to the GET, e.g.:
797
 *
798
\verbatim
799
GET http://host:port/janus/<sessionid>?maxev=5
800
\endverbatim
801
 *
802
\verbatim
803
[
804
	{
805
		// Event #1
806
		"janus" : "event",
807
		[..]
808
	},
809
	{
810
		// Event #2
811
		"janus" : "event",
812
		[..]
813
	},
814
	[..]
815
]
816
\endverbatim
817
 *
818
 * This request will instruct the gateway to return at maximum 5 events
819
 * within the context of the same long poll, formatted as a JSON array
820
 * of events. Please beware that this does \b NOT mean that you'll
821
 * always get 5 events this way: it only means that, if a message becomes
822
 * available in the queue and more events are present as well, Janus will
823
 * return more than one without needing you to send multiple long polls
824
 * immediately thereafter to get them. For this reason, don't be surprised
825
 * if even with a \c maxev parameter set, you'll still get a single
826
 * event being notified as the sole object in the returned array.
827
 *
828
 * <hr>
829
 *
830
 * \par Interacting with the session
831
 * To interact with the session, e.g., to create a new handle to attach
832
 * to a plugin or destroy the current session, you need to send a \b POST
833
 * JSON message to the session endpoint.
834
 *
835
 * To attach to a plugin in order to exploit its features, you need to
836
 * \b POST a \c janus "attach" JSON message to the gateway; you'll need
837
 * of course to provide information on the plugin you want to attach to,
838
 * which can be done using the \c plugin field: 
839
 *
840
\verbatim
841
{
842
	"janus" : "attach",
843
	"plugin" : "<the plugin's unique package name>",
844
	"transaction" : "<random string>"
845
}
846
\endverbatim
847
 *
848
 * Notice that you can also provide an optional \c opaque_id string
849
 * identifier (for more details on why this might be useful, read more
850
 * <a href="https://github.com/meetecho/janus-gateway/pull/748">here</a>).
851
 * If the request is successful, you'll receive the unique plugin handle
852
 * identifier in a response formatted the same way as the session create
853
 * one, that is like this:
854
 *
855
\verbatim
856
{
857
	"janus" : "success",
858
	"transaction" : "<same as the request>",
859
	"data" : {
860
		"id" : <unique integer plugin handle ID>
861
	}
862
}
863
\endverbatim
864
 *
865
 * In case of an error, you'll receive an error message as the one introduced
866
 * before. This request, if issued with a POST to a valid session endpoint, can only
867
 * fail if you miss any of the required fields in the request or if the
868
 * plugin you requested is not available in the gateway.
869
 *
870
 * To destroy the current session, instead, just send a "destroy" \c janus
871
 * request:
872
 *
873
\verbatim
874
{
875
	"janus" : "destroy",
876
	"transaction" : "<random string>"
877
}
878
\endverbatim
879
 *
880
 * This will also destroy the endpoint created for this session.
881
 * If your session is currently managing one or more plugin handles, 
882
 * make sure you destroy them first (as explained in the next section).
883
 * The gateway tries to do this automatically when receiving a session
884
 * destroy request, but a cleaner approach on the client side would help 
885
 * nonetheless avoid potential issues.
886
 *
887
 * \section handles The plugin handle endpoint
888
 * Once you've created a plugin handle, a new endpoint you can use is created
889
 * in the gateway. Specifically, the new endpoint is constructed by
890
 * concatenating the gateway root, the session identifier and the new
891
 * plugin handle identifier you've been returned (\c e.g.,
892
 * \c /janus/12345678/98765432).
893
 *
894
 * You can use this plugin handle for everything that is related to the
895
 * communication with a plugin, that is, send the plugin a message,
896
 * negotiate a WebRTC connection to attach to the plugin, and so on.
897
 *
898
 * To send a plugin a message/request, you need to \b POST the handle
899
 * endpoint a \c janus "message" JSON payload. The \c body field will
900
 * have to contain a plugin-specific JSON payload. In case the message
901
 * also needs to convey WebRTC-related negotiation information, a \c jsep
902
 * field containing the JSON-ified version of the JSEP object can be 
903
 * attached as well.
904
 *
905
 * \note If you attach a \c jsep object, whether it's an offer or an answer,
906
 * you're stating your will to negotiate a PeerConnection. This means that
907
 * an empty or invalid \c jsep object will trigger a validation and will
908
 * cause the whole request to fail, so make sure you exclude the field
909
 * completely from your request if all you're interested into is sending
910
 * a message to a plugin.
911
 *
912
 * Here's an example of a message you may send the janus_echotest.c plugin
913
 * to mute your audio:
914
 *
915
\verbatim
916
{
917
	"janus" : "message",
918
	"transaction" : "sBJNyUhH6Vc6",
919
	"body" : {
920
		"audio" : false
921
	}
922
}
923
\endverbatim
924
 *
925
 * The same message containing negotiation information as well, instead,
926
 * (an OFFER, in this example), is presented here:
927
 *
928
\verbatim
929
{
930
	"janus" : "message",
931
	"transaction" : "sBJNyUhH6Vc6",
932
	"body" : {
933
		"audio" : false
934
	},
935
	"jsep" : {
936
		"type" : "offer",
937
		"sdp" : "v=0\r\no=[..more sdp stuff..]"
938
	}
939
}
940
\endverbatim
941
 *
942
 * Please notice that, if for any reason you don't want to use the
943
 * trickling of ICE candidates from your application (which means you'll
944
 * include them all in the SDP OFFER or ANSWER, which is usually not
945
 * recommended), you'll have to add an additional <code>"trickle" : false</code>
946
 * attribute to the "jsep" object, to explicitly tell Janus you won't
947
 * send any \c trickle candidate (by default Janus will always assume
948
 * support for trickle).
949
 *
950
 * If you're going to \c trickle candidates, instead, there is an ad-hoc
951
 * message you can use to do so which is called, unsurprisingly, \c trickle
952
 * and which you can use to send one or more trickle candidates to Janus.
953
 * Since such a message is related to a specific PeerConnection, it will
954
 * need to be addressed to the right Handle just as the \c message introduced
955
 * previously. A \c trickle message can contain three different kind of
956
 * information:
957
 *
958
 *  - a single trickle candidate;
959
 *  - an array of trickle candidates;
960
 *  - a null candidate or a \c completed JSON object to notify the end of the
961
 * candidates.
962
 *
963
 * This is an example of a single candidate being trickled:
964
 *
965
\verbatim
966
{
967
	"janus" : "trickle",
968
	"transaction" : "hehe83hd8dw12e",
969
	"candidate" : {
970
		"sdpMid" : "video",
971
		"sdpMLineIndex" : 1,
972
		"candidate" : "..."
973
	}
974
}
975
\endverbatim
976
 *
977
 * This, instead, is an example of how to group more trickle candidates
978
 * in a single request (particularly useful if you're wrapping Janus in
979
 * your server and want to reduce the number of transactions):
980
 *
981
\verbatim
982
{
983
	"janus" : "trickle",
984
	"transaction" : "hehe83hd8dw12e",
985
	"candidates" : [ 
986
		{
987
			"sdpMid" : "video",
988
			"sdpMLineIndex" : 1,
989
			"candidate" : "..."
990
		},
991
		{
992
			"sdpMid" : "video",
993
			"sdpMLineIndex" : 1,
994
			"candidate" : "..."
995
		},
996
		[..]
997
	]
998
}
999
\endverbatim
1000
 *
1001
 * Finally, this is how you can tell Janus that you sent all the trickle
1002
 * candidates that were gathered:
1003
 *
1004
\verbatim
1005
{
1006
	"janus" : "trickle",
1007
	"transaction" : "hehe83hd8dw12e",
1008
	"candidate" : {
1009
		"completed" : true
1010
	}
1011
}
1012
\endverbatim
1013
 *
1014
 * Plugins may handle this requests synchronously or asynchronously. In
1015
 * the former, plugins would return a response to the request itself
1016
 * immediately; in the latter, instead, the plugin would only notify a
1017
 * successful reception of the request, which it would process later.
1018
 * Considering the asynchronous nature of the Janus API, a successful
1019
 * management of such messages within the gateway would in such case result in
1020
 * a \c janus "ack" messages being sent back to the client. A logical response
1021
 * to those messages, if needed, would be provided as an event in the
1022
 * long-poll interface described previously, and clients would be able
1023
 * to match it to the original request by means of the transaction
1024
 * identifiers. It is worth noting, though, that should a WebRTC negotiation
1025
 * be involved you don't have to expect an ANSWER to your OFFER to be
1026
 * sent back in the same transaction. A plugin may decide, in its
1027
 * application logic, to not provide you with an ANSWER right away, but
1028
 * only after some internal state changes occur. It's up to your application
1029
 * to handle the negotiation state accordingly.
1030
 *
1031
 * An example of an "ack" being sent back to the client, using the previous
1032
 * sample request as a reference, is presented here:
1033
 *
1034
\verbatim
1035
{
1036
	"janus" : "ack",
1037
	"transaction" : "sBJNyUhH6Vc6"
1038
}
1039
\endverbatim
1040
 *
1041
 * If you receive this ack instead of a "success" response, you can be
1042
 * sure the plugin has received the message, and is going to process it soon.
1043
 *
1044
 * In case of an error, instead, you'll receive an error message as the one
1045
 * introduced before. This request, if issued with a POST to a valid plugin
1046
 * handle endpoint, can only fail if you miss any of the required fields
1047
 * in the request, if the plugin you tried to contact is not available in
1048
 * the gateway anymore, if an error occurred in the plugin when trying to
1049
 * receive the message or if the \c jsep SDP you may have provided is
1050
 * invalid.
1051
 *
1052
 * To destroy the plugin handle, instead, just send a "detach" \c janus
1053
 * request:
1054
 *
1055
\verbatim
1056
{
1057
	"janus" : "detach",
1058
	"transaction" : "<random string>"
1059
}
1060
\endverbatim
1061
 *
1062
 * This will also destroy the endpoint created for this plugin handle.
1063
 * If your plugin handle is also managing an ongoing WebRTC connection
1064
 * with the plugin, make sure it is torn down as part of this process.
1065
 * The plugin implementation and the gateway core should do this
1066
 * automatically, but implementing the right behaviour in clients would
1067
 * help avoid potential issues nonetheless.
1068
 *
1069
 * If you're interested in keeping the handle alive but want to hang up
1070
 * the associated PeerConnection, if available, just send a "hangup" \c janus
1071
 * request:
1072
 *
1073
\verbatim
1074
{
1075
	"janus" : "hangup",
1076
	"transaction" : "<random string>"
1077
}
1078
\endverbatim
1079
 *
1080
 * This is usually not required, as you can typically just hangup your
1081
 * WebRTC PeerConnection normally and Janus will figure out it's gone
1082
 * by itself. Anyway, there are cases where this might be useful (e.g.,
1083
 * the connection was stuck in some weird ICE/DTLS state) as it can be
1084
 * used to reset the connection state for the handle.
1085
 *
1086
 * \section events WebRTC-related events
1087
 *
1088
 * As anticipated in the previous sections, Janus can send events and
1089
 * notifications at any time through the long poll channel (or, as it
1090
 * will be explained later, through the related push mechanisms made
1091
 * available by the \ref WS, \ref rabbit and \ref unix ). While this channel is
1092
 * mostly used to convey asynchronous notifications originated by
1093
 * plugins as part of the messaging they may have with the application
1094
 * using it, the same channel is actually used by Janus to trigger
1095
 * events related to different aspects pertaining a specific handle.
1096
 *
1097
 * In particular, for each handle involving a PeerConnection Janus
1098
 * provides notifications about its current state. To do so, the
1099
 * following events may be received as well:
1100
 *
1101
 *  - \c webrtcup: ICE and DTLS succeeded, and so Janus correctly
1102
 * established a PeerConnection with the user/application;
1103
 *  - \c media: whether Janus is receiving (\c receiving: \c true/false)
1104
 * audio/video (\c type: \c "audio/video") on this PeerConnection;
1105
 *  - \c slowlink: whether Janus is reporting trouble sending/receiving
1106
 * (\c uplink: \c true/false) media on this PeerConnection;
1107
 *  - \c hangup: the PeerConnection was closed, either by Janus or by
1108
 * the user/application, and as such cannot be used anymore.
1109
 *
1110
 * As such, to monitor the status of a PeerConnection as seen from
1111
 * Janus you can make use of these events to track what's going on. A
1112
 * correct flow for an active PeerConnection would be one that, after a
1113
 * WebRTC negotiation and setup, results in a \c webrtcup event followed
1114
 * by two \c media events (in case both audio and video have been
1115
 * negotiated) specifying that the first audio/video packets have been
1116
 * received. A \c hangup event would inform the user/application that
1117
 * no media is being exchanged with Janus anymore.
1118
 *
1119
 * Here are a few examples of how these events may look like.
1120
 *
1121
 * A PeerConnection becoming ready:
1122
 *
1123
\verbatim
1124
{
1125
	"janus" : "webrtcup",
1126
	session_id: <the session identifier>,
1127
	sender: <the handle identifier>
1128
}
1129
\endverbatim
1130
 *
1131
 * First audio bytes being received by Janus:
1132
 *
1133
\verbatim
1134
{
1135
	"janus" : "media",
1136
	session_id: <the session identifier>,
1137
	sender: <the handle identifier>,
1138
	"type" : "audio",
1139
	"receiving" : true
1140
}
1141
\endverbatim
1142
 *
1143
 * Audio not getting to Janus anymore for some reason:
1144
 *
1145
\verbatim
1146
{
1147
	"janus" : "media",
1148
	"session_id" : <the session identifier>,
1149
	"sender" : <the handle identifier>
1150
	"type" : "audio",
1151
	"receiving" : false
1152
}
1153
\endverbatim
1154
 *
1155
 * Audio getting to Janus again (same message as first audio):
1156
 *
1157
\verbatim
1158
{
1159
	"janus" : "media",
1160
	"session_id" : <the session identifier>,
1161
	"sender" : <the handle identifier>
1162
	"type" : "audio",
1163
	"receiving" : true
1164
}
1165
\endverbatim
1166
 *
1167
 * Janus reporting problems sending media to a user (user sent many NACKs
1168
 * in the last second; uplink=true is from Janus' perspective):
1169
 *
1170
\verbatim
1171
{
1172
	"janus" : "slowlink",
1173
	"session_id" : <the session identifier>,
1174
	"sender" : <the handle identifier>
1175
	"uplink" : true,
1176
	"nacks" : <number of NACKs in the last second>
1177
}
1178
\endverbatim
1179
 *
1180
 * PeerConnection closed for a DTLS alert (normal shutdown):
1181
 *
1182
\verbatim
1183
{
1184
	"janus" : "hangup",
1185
	"session_id" : <the session identifier>,
1186
	"sender" : <the handle identifier>,
1187
	"reason" : "DTLS alert"
1188
}
1189
\endverbatim
1190
 *
1191
 * It is important to point out that the \c media event notifications
1192
 * only apply if your PeerConnection is going to actually send media to
1193
 * Janus. A \c recvonly PeerConnection, for instance (e.g., as the
1194
 * Streaming plugin would create) would never trigger any \c media
1195
 * event, as Janus would never be receiving media, but only send it.
1196
 *
1197
 * \section WS WebSockets Interface
1198
 * In recent version of Janus we added support for WebSockets to control
1199
 * the gateway, along the already existing (and still the default) REST
1200
 * API. In fact, while WebSockets still present some more issues in terms
1201
 * of reachability when compared to plain HTTP, they definitely provide
1202
 * a more efficient means for implementing a bidirectional communication.
1203
 * This is especially useful if you're wrapping the Janus API on your
1204
 * servers, as it allows you to avoid all the noise and overhead introduced
1205
 * by several concurrent HTTP transactions and long polls by relying on
1206
 * what may be seen as a single "control channel".
1207
 *
1208
 * To interact with Janus using WebSockets you MUST specify a specific
1209
 * subprotocol, named \c janus-protocol, e.g.,
1210
 *
1211
\verbatim
1212
var websocket = new WebSocket('ws://1.2.3.4:8188', 'janus-protocol');
1213
\endverbatim
1214
 *
1215
 * The \c janus.js library does this automatically.
1216
 *
1217
 * As anticipated at the beginning of this section, the actual messages
1218
 * being exchanged are exactly the same. This means that all the concepts
1219
 * introduced before still apply: you still create a session, attach to
1220
 * a plugin and interact with it exactly the same way. What is different
1221
 * is, of course, the REST path approach that becomes unavailable when
1222
 * using a WebSocket as a control channel. To address the idenfitiers
1223
 * that become missing using WebSockets, you'll need to add additional
1224
 * fields to the requests when necessary.
1225
 *
1226
 * So, when you want to create a session using the REST API, you send a
1227
 * POST to the gateway base path: 
1228
 *
1229
\verbatim
1230
{
1231
	"janus" : "create",
1232
	"transaction" : "<random alphanumeric string>"
1233
}
1234
\endverbatim
1235
 *
1236
 * The same applies if you're interested in getting generic info from the
1237
 * Janus instance. Since there's no \b GET you can use, a specific \c janus
1238
 * request type called \c info is available:
1239
 *
1240
\verbatim
1241
{
1242
	"janus" : "info",
1243
	"transaction" : "<random alphanumeric string>"
1244
}
1245
\endverbatim
1246
 *
1247
 * Since you'd contact the base path for both requests, you don't need to add any identifier
1248
 * for this scenario. But if instead you want to attach to a plugin within
1249
 * the context of a specific session, using the REST API you'd send a
1250
 * post to the \c /janus/<session-id> endpoint:
1251
 *
1252
\verbatim
1253
{
1254
	"janus" : "attach",
1255
	"plugin" : "<the plugin's unique package name>",
1256
	"transaction" : "<random string>"
1257
}
1258
\endverbatim
1259
 *
1260
 * To make this work with WebSockets as well, you need to add a further
1261
 * field called \c session_id in the request:
1262
 *
1263
\verbatim
1264
{
1265
	"janus" : "attach",
1266
	"session_id" : <the session identifier>,		// NEW!
1267
	"plugin" : "<the plugin's unique package name>",
1268
	"transaction" : "<random string>"
1269
}
1270
\endverbatim
1271
 *
1272
 * which will allow the WebSocket server to understand which session this
1273
 * request pertains to. At the same time, when you need to address a
1274
 * specific handle (e.g., to send a message to a plugin, or negotiate a
1275
 * WebRTC PeerConnection) you'll need to add a \c handle_id field to the
1276
 * request as well, or the request will be rejected:
1277
 *
1278
\verbatim
1279
{
1280
	"janus" : "message",
1281
	"session_id" : <the session identifier>,		// NEW!
1282
	"handle_id" : <the handle identifier>,		// NEW!
1283
	"transaction" : "sBJNyUhH6Vc6",
1284
	"body" : {
1285
		"audio" : false
1286
	}
1287
}
1288
\endverbatim
1289
 *
1290
 * Considering the bidirectional nature of WebSockets and the fact that
1291
 * the channel will be shared for different requests, you'll need to pay
1292
 * extra attention to the \c transaction identifier, which will allow you
1293
 * to map incoming responses and events to the request you sent that
1294
 * originated them.
1295
 *
1296
 * An \b important aspect to point out is related to keep-alive messages
1297
 * for WebSockets Janus channels. A Janus session is kept alive as long
1298
 * as there's no inactivity for 60 seconds: if no messages have been
1299
 * received in that time frame, the session is torn down by the gateway.
1300
 * A normal activity on a session is usually enough to prevent that;
1301
 * for a more prolonged inactivity with respect to messaging, on plain
1302
 * HTTP the session is usually kept alive through the regular long poll
1303
 * requests, which act as activity as long as the session is concerned.
1304
 * This aid is obviously not possible when using WebSockets, where a single channel is
1305
 * used both for sending requests and receiving events and responses. For
1306
 * this reason, an ad-hoc message for keeping alive a Janus session should
1307
 * to be triggered on a regular basis:
1308
 *
1309
\verbatim
1310
{
1311
	"janus" : "keepalive",
1312
	"session_id" : <the session identifier>,
1313
	"transaction" : "sBJNyUhH6Vc6"
1314
}
1315
\endverbatim
1316
 *
1317
 * This will make sure that the gateway detects activity on the session
1318
 * even when no actual messages are being exchanged with handles.
1319
 *
1320
 * As a last point, another slight difference with WebSockets comes from
1321
 * how push notifications are implemented. In the \ref plainhttp this is
1322
 * done via long polls: that is, you explicitly subscribe to notifications,
1323
 * and have to do that again as soon as an event has been received. With
1324
 * WebSockets, this is not needed: as soon as you create a session on a
1325
 * WebSocket, that channel becomes automatically subscribed for events
1326
 * related to that sessions, and you'll receive them on the same WebSocket.
1327
 * For the same reason, as soon as the WebSocket is closed, all the sessions
1328
 * created within its context are considered closed as well, and so their
1329
 * resources (including all the handles and PeerConnections) will be
1330
 * released as well.
1331
 *
1332
 * \note The same \c janus.js JavaScript library can be used both with the
1333
 * REST and the WebSockets API: all you need to do is provide the right
1334
 * Janus server address during the initialization and the library will
1335
 * use one or the other according to the protocol prefix.
1336
 *
1337
 * \section rabbit RabbitMQ interface
1338
 * The semantics of how the requests have to be built, when compared to
1339
 * the usage of plain HTTP, is exactly the same as for WebSockets, so
1340
 * refer to the \ref WS documentation for details about that.
1341
 *
1342
 * Of course, there are other aspects that differ when making use of
1343
 * RabbitMQ messaging to talk to Janus, rather than using HTTP messages
1344
 * or WebSockets. Specifically, RabbitMQ just basically forwards messages
1345
 * on queues, and as such implementing a pseudo-bidirectional channel
1346
 * as the Janus API requires some precaution.
1347
 *
1348
 * In particular, when configuring Janus to use RabbitMQ you'll have to
1349
 * specify \b two \b queues:
1350
 *
1351
 * - a queue for \b incoming messages (application -> Janus);
1352
 * - a queue for \b outgoing messages (Janus -> application).
1353
 *
1354
 * The proper usage of these queues will allow you to implement the kind
1355
 * of bidirectional channel Janus needs.
1356
 *
1357
 * Another aspect to point out is that Janus requires all requests to
1358
 * have a random \c correlation_id identifier. In fact, as pointed out
1359
 * in the previous sections, the Janus API is conceived as a request/response
1360
 * protocol that can involve asynchronous notifications as well. In order
1361
 * to make sure that an application can match a received response to one
1362
 * of the requests made earlier, Janus copies the \c correlation_id
1363
 * identifier from the original request in the response to it: this is
1364
 * compliant with the
1365
 * <a href="https://www.rabbitmq.com/tutorials/tutorial-six-python.html">RPC pattern</a>
1366
 * as specified in the RabbitMQ documentation. Notifications originated by
1367
 * Janus, instead, will not include a \c correlation_id identifier, and as
1368
 * such applications shouldn't expect any: applications will still be able
1369
 * to match a notification to a request, if the involved plugin was
1370
 * implemented to do so, by looking at the Janus-level \c transaction
1371
 * identifier.
1372
 *
1373
 * \section mqtt MQTT interface
1374
 * The semantics of how the requests have to be built, when compared to
1375
 * the usage of plain HTTP, is exactly the same as for WebSockets, so
1376
 * refer to the \ref WS documentation for details about that.
1377
 *
1378
 * Of course, there are other aspects that differ when making use of
1379
 * MQTT messaging to talk to Janus, rather than using HTTP messages
1380
 * or WebSockets. Similar to RabbitMQ, MQTT just basically forwards messages
1381
 * on queues, and as such implementing a pseudo-bidirectional channel
1382
 * as the Janus API requires some precaution.
1383
 *
1384
 * In particular, when configuring Janus to use MQTT you'll have to
1385
 * specify \b two \b queues:
1386
 *
1387
 * - a queue for \b incoming messages (application -> Janus);
1388
 * - a queue for \b outgoing messages (Janus -> application).
1389
 *
1390
 * The proper usage of these queues will allow you to implement the kind
1391
 * of bidirectional channel Janus needs.
1392
 *
1393
 * \section unix UnixSockets interface
1394
 * The semantics of how the requests have to be built, when compared to
1395
 * the usage of plain HTTP, is exactly the same as for WebSockets, RabbitMQ
1396
 * and MQTT, so refer to the \ref WS documentation for details about that.
1397
 *
1398
 * Apart from that, the only configuration needed is related to the path
1399
 * the client and server will be sharing, and the socket type. Notice that only the
1400
 * \c SOCK_SEQPACKET and \c SOCK_DGRAM types are supported in the plugin.
1401
 *
1402
 */
1403

    
1404
/*! \page auth Authenticating the Janus API
1405
 * By default no authentication is involved when using the Janus API.
1406
 * This means that the API is completely open, and that everybody can
1407
 * talk to Janus and its plugins and set up media connections. There are
1408
 * times, though, where limiting access to Janus may be desirable, e.g.,
1409
 * when you want to prevent unauthorized users to join a service you
1410
 * created, or when you wrap the Janus API in your server and you want
1411
 * your application to be the only one to be able to interact with
1412
 * Janus from a messaging perspective.
1413
 *
1414
 * There are a couple of ways to authenticate requests in Janus:
1415
 *
1416
 * - using a \ref token (useful for web users);
1417
 * - using a \ref secret (useful when wrapping the Janus API).
1418
 *
1419
 * \section token Token based authentication mechanism
1420
 * The token based authentication mechanism expects all users to provide,
1421
 * in each request, a \c token string attribute: if this token is
1422
 * known to Janus, the request will be accepted, otherwise it will be
1423
 * rejected as an \c unauthorized response. Configuring the token based
1424
 * authentication mechanism is easy enough: you can do that either via
1425
 * the command line (\c -A or \c --token-auth ) or in the \c janus.cfg
1426
 * configuration (\c token_auth value in the \c general section).
1427
 *
1428
 * These tokens are completely opaque to Janus, meaning they can be
1429
 * pretty much anything that you want. Janus does not do any form of
1430
 * authorization/authentication itself: it's up to you to provide it
1431
 * with valid tokens users can use, e.g., as part of your server-side
1432
 * application handling users. You can add and remove tokens
1433
 * dynamically using the \ref admin, which means you will need to enable
1434
 * it if you want to use tokens, or otherwise all requests will fail
1435
 * (Janus will never have a valid token, so all requests will be rejected).
1436
 *
1437
 * You add tokens using the \c add_token admin request, while you
1438
 * remove them using \c remove_token. You can also limit the scope of tokens
1439
 * to specific plugins, by passing a list of plugins to \c add_token or
1440
 * modifying the token properties via \c allow_token and \c disallow_token.
1441
 * By default (\c add_token without any plugin specified) Janus assumes
1442
 * a new token is allowed to access all plugins. A list of all the
1443
 * existing tokens can be retrieved with a \c list_tokens request.
1444
 *
1445
 * Here are a couple of examples of how you can use the requests:
1446
 *
1447
\verbatim
1448
{
1449
	"janus" : "add_token",
1450
	"token": "a1b2c3d4",
1451
	"transaction" : "sBJNyUhH6Vc6",
1452
	"admin_secret": "adminpassword"
1453
}
1454
\endverbatim
1455
 *
1456
 * This adds a new token (a1b2c3d4) that is allowed to access all the
1457
 * plugins in Janus (no limitation provided in \c add_token ). To create
1458
 * a new token and limit the scope to a few selected plugins, you can
1459
 * use this other syntax instead (notice the extra \c plugins array):
1460
 *
1461
\verbatim
1462
{
1463
	"janus" : "add_token",
1464
	"token": "a1b2c3d4",
1465
	"plugins": [
1466
		"janus.plugin.streaming",
1467
		"janus.plugin.videoroom"
1468
	],
1469
	"transaction" : "sBJNyUhH6Vc6",
1470
	"admin_secret": "adminpassword"
1471
}
1472
\endverbatim
1473
 *
1474
 * In this other example, we're creating a new token, and also telling
1475
 * Janus that the only plugins a user with this token can access are
1476
 * the Streaming and Videoroom plugins. An attempt to attach to a
1477
 * different plugin (e.g., EchoTest) will result in an error.
1478
 *
1479
 * You can change the permissions a token has with respect to plugin
1480
 * access at any time. In the following example, we add a new plugin
1481
 * to the permissions for an existing token:
1482
 *
1483
\verbatim
1484
{
1485
	"janus" : "allow_token",
1486
	"token": "a1b2c3d4",
1487
	"plugins": [
1488
		"janus.plugin.echotest"
1489
	],
1490
	"transaction" : "sBJNyUhH6Vc6",
1491
	"admin_secret": "adminpassword"
1492
}
1493
\endverbatim
1494
 *
1495
 * This way, the provided token is now also allowed to access the EchoTest
1496
 * plugin. To remove a permission, the syntax is this one instead:
1497
 *
1498
\verbatim
1499
{
1500
	"janus" : "disallow_token",
1501
	"token": "a1b2c3d4",
1502
	"plugins": [
1503
		"janus.plugin.videoroom"
1504
	],
1505
	"transaction" : "sBJNyUhH6Vc6",
1506
	"admin_secret": "adminpassword"
1507
}
1508
\endverbatim
1509
 *
1510
 * To retrieve a list of all the valid tokens Janus is aware of, together
1511
 * with the plugins each of them is allowed to access, a \c list_tokens
1512
 * request can be used:
1513
 *
1514
\verbatim
1515
{
1516
	"janus" : "list_tokens",
1517
	"transaction" : "sBJNyUhH6Vc6",
1518
	"admin_secret": "adminpassword"
1519
}
1520
\endverbatim
1521
 *
1522
 * Finally, you can get rid of a token using a \c remove_token request:
1523
 *
1524
\verbatim
1525
{
1526
	"janus" : "remove_token",
1527
	"token": "a1b2c3d4",
1528
	"transaction" : "sBJNyUhH6Vc6",
1529
	"admin_secret": "adminpassword"
1530
}
1531
\endverbatim
1532
 *
1533
 * As anticipated, with the token based mechanism enabled, all users
1534
 * will need to provide a valid token as part of their requests. This is
1535
 * done by adding a \c token attribute to the request root, e.g.:
1536
 *
1537
\verbatim
1538
{
1539
	"janus" : "create",
1540
	"transaction" : "sBJNyUhH6Vc6",
1541
	"token": "usertoken"
1542
}
1543
\endverbatim
1544
 *
1545
 * The same applies for the long poll GET messages as well, which will
1546
 * need to contain the \c token as a query string parameter.
1547
 *
1548
 * A valid token will mean the request will be accepted and processed
1549
 * normally. A missing or invalid token, instead, will result in an
1550
 * error being returned:
1551
 *
1552
\verbatim
1553
{
1554
	"janus" : "error",
1555
	"transaction" : "sBJNyUhH6Vc6",
1556
	"error" : {
1557
		"code" : 403,
1558
		"reason" : "Unauthorized request (wrong or missing secret/token)"
1559
	}
1560
}
1561
\endverbatim
1562
 *
1563
 * An attempt to use a valid token to attach to a plugin it is not
1564
 * allowed to access, instead, will result in a different error:
1565
 *
1566
\verbatim
1567
{
1568
	"janus" : "error",
1569
	"transaction" : "sBJNyUhH6Vc6",
1570
	"error" : {
1571
		"code" : 405,
1572
		"reason" : "Provided token can't access plugin 'janus.plugin.echotest'"
1573
	}
1574
}
1575
\endverbatim
1576
 *
1577
 * \section secret Shared static secret
1578
 * Several deployers showed an interested in wrapping the Janus API on
1579
 * their server side: this allows them to keep the interaction with their
1580
 * users the way it was before, while still benefiting from the features
1581
 * Janus provides. This is an easy enough step, as it just needs developers
1582
 * to relay the involved SDP, and implementing the Janus API messages to
1583
 * handle the logic.
1584
 *
1585
 * That said, since in this case Janus would be contacted, through the API,
1586
 * just by a limited number of applications (e.g., application servers
1587
 * made in node.js, Ruby, Java Servlets or whatever) and not random
1588
 * browsers, it is reasonable to involve a mechanism to control who is
1589
 * allowed to contact and control it. The previous section described
1590
 * how you can exploit a token based mechanism for authenticating
1591
 * requests, but since in this case you only need a single application,
1592
 * or a limited set of them,
1593
 * to be able to talk to Janus, it's worthwhile to resort to something
1594
 * simpler and more static. To allow for that, Janus also exposes a
1595
 * shared API secret mechanism: that is, you configure Janus with a string
1596
 * applications need to present when sending requests, and if they don't,
1597
 * Janus rejects them with an \c unauthorized message.
1598
 *
1599
 * Configuring the API secret mechanism is easy enough: you can do that
1600
 * either via the command line (\c -a or \c --apisecret ) or in the
1601
 * \c janus.cfg configuration (\c api_secret value in the \c general section).
1602
 * When enabled, all requests addressed to that Janus instance \b MUST
1603
 * also contain an \c apisecret field in the Janus message headers. For
1604
 * instance, this message presented above would fail:
1605
 *
1606
\verbatim
1607
{
1608
	"janus" : "create",
1609
	"transaction" : "<random alphanumeric string>"
1610
}
1611
\endverbatim
1612
 *
1613
\verbatim
1614
{
1615
	"janus" : "error",
1616
	"transaction" : "<same as request>"
1617
	"error" : {
1618
		"code" : 403,
1619
		"reason" : "Unauthorized request (wrong or missing secret/token)"
1620
	}
1621
}
1622
\endverbatim
1623
 *
1624
 * For a successful transaction, the message would have to look like this:
1625
 *
1626
\verbatim
1627
{
1628
	"janus" : "create",
1629
	"apisecret" : "<API secret configured in Janus>",
1630
	"transaction" : "<random alphanumeric string>"
1631
}
1632
\endverbatim
1633
 *
1634
 * The same applies for the long poll GET messages as well, which will
1635
 * need to contain the \c apisecret as a query string parameter.
1636
 *
1637
 */
1638

    
1639
/*! \page admin Admin/Monitor API
1640
 * Recent versions of Janus introduced a new feature: an Admin/Monitor
1641
 * API that can be used to ask Janus for more specific information
1642
 * related to sessions and handles. This is especially useful when you
1643
 * want to debug issues at the media level.
1644
 *
1645
 * \note Right now, this new API mostly allows you to retrieve information,
1646
 * but only act on part of it: for more interaction (e.g., to force a
1647
 * session removal), you can rely on the existing \ref rest for the purpose.
1648
 *
1649
 * The API, for security reasons, is typically noy enabled by default in any of the
1650
 * transport plugins: that's definitely the case for the stock transport
1651
 * plugins, for instance, while additional, third party plugins may choose
1652
 * to expose the functionality without requiring any tweaking. As to the
1653
 * existing transport, you can enable the admin API by editing the \c [ \c admin \c ]
1654
 * section in the related transport configuration file (e.g., \c janus.transport.http.cfg
1655
 * for the REST interface, to use the admin API over HTTP). The configuration
1656
 * is pretty much the same as the one for the Janus API. In addition, you
1657
 * can configure restrictions in the form of a password/secret that clients
1658
 * need to provide or other transport-specific ones.
1659
 *
1660
 * For what concerns the syntax, it's very similar to the \ref rest and
1661
 * so this page will briefly discuss the differences. At the moment, a few
1662
 * different methods are exposed:
1663
 *
1664
 * - \c list_sessions: list all the sessions currently active in Janus
1665
 * (returns an array of session identifiers);
1666
 * - \c list_handles: list all the ICE handles currently active in a Janus
1667
 * session (returns an array of handle identifiers);
1668
 * - \c handle_info: list all the available info on a specific ICE handle;
1669
 * - \c set_log_level: change the log level in Janus on the fly;
1670
 * - \c set_locking_debug: selectively enable/disable a live debugging of
1671
 * the locks in Janus on the fly (useful if you're experiencing deadlocks
1672
 * and want to investigate them);
1673
 * - \c add_token: add a valid token (only available if you enabled the \ref token);
1674
 * - \c allow_token: give a token access to a plugin (only available if you enabled the \ref token);
1675
 * - \c disallow_token: remove a token access from a plugin (only available if you enabled the \ref token);
1676
 * - \c list_tokens: list the existing tokens (only available if you enabled the \ref token);
1677
 * - \c remove_token: remove a token (only available if you enabled the \ref token).
1678
 *
1679
 * Following the same spirit of the \ref rest these methods need to be
1680
 * invoked on the right path and/or providing the right \c session_id and
1681
 * \c handle_id identifiers. Specifically, \c list_sessions must be invoked
1682
 * without any session/handle information, as it's a global request. Here's
1683
 * an example of how such a request and its related response might look like:
1684
 *
1685
\verbatim
1686
POST /admin
1687
{
1688
	"janus" : "list_sessions",
1689
	"transaction" : "<random alphanumeric string>",
1690
	"admin_secret" : "<password specified in janus.cfg, if any>"
1691
}
1692
\endverbatim
1693
 *
1694
 *
1695
\verbatim
1696
{
1697
	"janus" : "success",
1698
	"transaction" : "<same as the request>",
1699
	"sessions" : [
1700
		<session ID #1>,
1701
		<session ID #2>,
1702
		[..]
1703
		<session ID #n>
1704
	]
1705
}
1706
\endverbatim
1707
 *
1708
 * On the other hand, since \c list_handles is related to a specific session,
1709
 * a session must be referenced correctly. Using the REST API, this can
1710
 * be done by appending the session identifier (e.g., one of the IDs
1711
 * returned by the previous call) to the API root:
1712
 *
1713
\verbatim
1714
POST /admin/12345678
1715
{
1716
	"janus" : "list_handles",
1717
	"transaction" : "<random alphanumeric string>",
1718
	"admin_secret" : "<password specified in janus.cfg, if any>"
1719
}
1720
\endverbatim
1721
 *
1722
 *
1723
\verbatim
1724
{
1725
	"janus" : "success",
1726
	"transaction" : "<same as the request>",
1727
	"session_id" : 12345678,
1728
	"handles" : [
1729
		<handle ID #1>,
1730
		<handle ID #2>,
1731
		[..]
1732
		<handle ID #n>
1733
	]
1734
}
1735
\endverbatim
1736
 *
1737
 * Once a list of handles is available, detailed info on any of them can
1738
 * be obtained by means of a \c handle_info call. Since this is a
1739
 * handle-specific request, the correct handle identifier must be
1740
 * referenced, e.g., by appending the ID to the session it belongs to:
1741
 *
1742
\verbatim
1743
POST /admin/12345678/98765432
1744
{
1745
	"janus" : "handle_info",
1746
	"transaction" : "<random alphanumeric string>",
1747
	"admin_secret" : "<password specified in janus.cfg, if any>"
1748
}
1749
\endverbatim
1750
 *
1751
 *
1752
\verbatim
1753
{
1754
	"janus" : "success",
1755
	"transaction" : "<same as the request>",
1756
	"session_id" : 12345678,
1757
	"handle_id" : 98765432,
1758
	"info" : {
1759
		"session_id" : 12345678,
1760
		"session_last_activity": 7927759122,
1761
		"session_transport": "janus.transport.websockets",
1762
		"handle_id" : 98765432,
1763
		"plugin": "janus.plugin.echotest",
1764
		"plugin_specific": {
1765
			// plugin specific (e.g., EchoTest internals)
1766
		},
1767
		"flags": {
1768
			// flags
1769
		},
1770
		"sdps": {
1771
			"local": "v=0[..]",
1772
			"remote": "v=0[..]"
1773
		},
1774
		"streams": [
1775
			// streams, components, etc.
1776
		]
1777
	}
1778
}
1779
\endverbatim
1780
 *
1781
 * The actual content of the last response is omitted for brevity, but
1782
 * you're welcome to experiment with it in order to check whether more
1783
 * information (of a different nature, maybe) may be useful to have. In
1784
 * particular, you may want to play with the plugin-specific details, as
1785
 * different plugins will return different information according to what
1786
 * they provide: for instance, the videoroom plugin might clarify whether
1787
 * a handle is being used for publishing media or for receiving it, and
1788
 * what are the involved IDs, the current status of the delivery, and so on.
1789
 * At the same time, the \c streams object will contain invaluable details
1790
 * related to the WebRTC PeerConnection associated with the handle, as
1791
 * in input/output statistics statistics (bytes, bytes per seconds, NACKs,
1792
 * etc.) or the SDP/ICE/DTLS states.
1793
 *
1794
 * Finally, the syntax for the \c set_log_level and \c set_locking_debug
1795
 * commands is quite straightforward:
1796
 *
1797
\verbatim
1798
POST /admin
1799
{
1800
	"janus" : "set_log_level",
1801
	"level" : <integer between 0 and 7, see debug.h>,
1802
	"transaction" : "<random alphanumeric string>",
1803
	"admin_secret" : "<password specified in janus.cfg, if any>"
1804
}
1805
\endverbatim
1806
 *
1807
\verbatim
1808
POST /admin
1809
{
1810
	"janus" : "set_locking_debug",
1811
	"debug" : <0 to disable, 1 to enable>,
1812
	"transaction" : "<random alphanumeric string>",
1813
	"admin_secret" : "<password specified in janus.cfg, if any>"
1814
}
1815
\endverbatim
1816
 *
1817
 * Both commands will return the updated level/debug setting if successful,
1818
 * and an error otherwise.
1819
 *
1820
 * To conclude, all of the above mentioned examples have assumed an usage
1821
 * of HTTP to interact with the Admin API. The same considerations already
1822
 * made for the Janus API as to the usage of different transports (WebSockets,
1823
 * RabbitMQ, MQTT or others) apply here as well, particularly with respect to
1824
 * the explicit \c session_id and \c handle_id in the JSON payload. Besides,
1825
 * to use the Admin API over WebSockets you'll have to use <code>janus-admin-protocol</code>
1826
 * as the subprotocol, instead of the <code>janus-protocol</code> of the
1827
 * regular Janus API.
1828
 *
1829
 */
1830

    
1831
/*! \page deploy Deploying Janus
1832
 *
1833
 * When you're going to deploy Janus (e.g., to try the demos we made
1834
 * available out-of-the-box), there's one thing that is important to point
1835
 * out: while Janus does indeed provide an HTTP RESTful interface (documented
1836
 * in \ref rest), it does \b NOT also act as a webserver for static files.
1837
 * This means you'll need a different webserver to host static files, including
1838
 * HTML/PHP/JSP/etc. pages, JavaScript files, images and whatever is part
1839
 * of your web application.
1840
 *
1841
 * That said, deploying Janus is, in principle, quite simple: just start Janus on a
1842
 * machine, put the HTML and JavaScript that will make use of it on a webserver
1843
 * somewhere, make sure the JavaScript code is configured with the right
1844
 * address for the gateway and you're done!
1845
 *
1846
 * Let's assume, for the sake of simplicity, that your webserver is serving
1847
 * files on port \c 80. By default, Janus binds on the \c 8088 port for HTTP.
1848
 * So, if Janus and the webserver hosting the are co-located, all you need to get your 
1849
 * application working is configure the web application to point to the right
1850
 * address for the gateway. In the demos provided with these packages, this
1851
 * is done by means of the \c server variable:
1852
 *
1853
 \verbatim
1854
var server = "http://" + window.location.hostname + ":8088/janus";
1855
 \endverbatim
1856
 *
1857
 * which basically tells the JavaScript application that the Janus API can be
1858
 * contacted at the same host as the website but at a different port (8088) and path (/janus). 
1859
 * In case you configured the gateway differently, e.g., 7000 as the port 
1860
 * for HTTP and /my/custom/path as the API endpoint, the \c server variable
1861
 * could be built this way:
1862
 *
1863
 \verbatim
1864
var server = "http://" + window.location.hostname + ":7000/my/custom/path";
1865
 \endverbatim
1866
 *
1867
 * In case the webserver and Janus are <b>NOT</b> colocated, instead, just
1868
 * replace the \c window.location.hostname part with the right address of
1869
 * the gateway, e.g.:
1870
 *
1871
 \verbatim
1872
var server = "http://www.example.com:8088/janus";
1873
 \endverbatim
1874
 *
1875
 * It's important to point out, though, that this more "static" approach
1876
 * only works if the webserver is serving files via HTTP. As soon as you
1877
 * start involving \b HTTPS, things start to get more complicated: in fact,
1878
 * for security reasons you cannot contact an HTTP backend if the page is
1879
 * made available via HTTPS. This means that if you're interested in serving
1880
 * your web application via HTTPS, you'll need to enable the HTTPS embedded
1881
 * webserver in Janus as well, and configure the JavaScript code to refer to
1882
 * that itself, e.g.:
1883
 *
1884
 \verbatim
1885
var server = "https://" + window.location.hostname + ":8089/janus";
1886
 \endverbatim
1887
 *
1888
 * assuming \c 8089 is the port you configured Janus to use for HTTPS.
1889
 * To make this more "dynamic", e.g., allow both HTTP and HTTPS instead of
1890
 * just sticking to one, you might make use of something like this:
1891
 *
1892
 \verbatim
1893
var server = null;
1894
if(window.location.protocol === 'http:')
1895
	server = "http://" + window.location.hostname + ":8088/janus";
1896
else
1897
	server = "https://" + window.location.hostname + ":8089/janus";
1898
 \endverbatim
1899
 *
1900
 * that is evaulate the right address to use at runtime.
1901
 *
1902
 * Anyway, there's a much easier way to address these scenarios, which
1903
 * is explained in the next section.
1904
 *
1905
 * \section apache Deploying Janus behind a web frontend
1906
 *
1907
 * To avoid most of the issues explained above, an easy approach can be
1908
 * deploying Janus behind a frontend (e.g., Apache HTTPD, nginx, lighttpd
1909
 * or others) that would act as a reverse proxy for incoming requests.
1910
 * This would allow you to make the Janus API available as a relative path 
1911
 * of your web application, rather than a service reachable at a different
1912
 * port and/or domain.
1913
 *
1914
 * Configuring the web application, as a consequence, would be even easier,
1915
 * as all you'd need to do would be to provide a relative path for the API,
1916
 * e.g.:
1917
 *
1918
 \verbatim
1919
var server = "/janus";
1920
 \endverbatim
1921
 *
1922
 * which would automatically work whether the page is served via HTTP or
1923
 * HTTPS. In fact, all the HTTPS requests would be terminated at the webserver,
1924
 * which would then always send simple HTTP messages to the gateway itself.
1925
 *
1926
 * An easy way to do so in Apache HTTPD is by means of the following directives:
1927
 *
1928
 \verbatim
1929
ProxyRequests Off
1930
ProxyVia Off
1931
ProxyPass /janus http://127.0.0.1:8088/janus retry=0
1932
ProxyPassReverse /janus http://127.0.0.1:8088/janus
1933
 \endverbatim
1934
 *
1935
 * Different versions of HTTPD or different webservers may require a
1936
 * different syntax, but the principle is usually always the same: you instruct
1937
 * the webserver to act as a proxy for a local endpoint, in this case a
1938
 * Janus instance colocated at the webserver and configured with the
1939
 * default settings.
1940
 *
1941
 * A way to do the same with nginx, as explained by some Janus users
1942
 * <a href="https://groups.google.com/forum/#!topic/meetecho-janus/dIv-4s0HOdw">here</a>,
1943
 * is the following directive:
1944
 *
1945
 \verbatim
1946
location /janus {
1947
	proxy_pass http://127.0.0.1:8088/janus;
1948
}
1949
 \endverbatim
1950
 *
1951
 * \section webserver A quick and easy web server
1952
 * While opening WebRTC-powered web applications by just opening the
1953
 * application HTML files from file system works with some browsers, it
1954
 * doesn't in others. Specifically, this works in Firefox but not in Chrome
1955
 * (see <a href="https://github.com/meetecho/janus-gateway/issues/291">issue #291</a>).
1956
 * Anyway, considering that you will eventually want other people besides
1957
 * you to use your Janus services, this means that to test and use Janus
1958
 * you'll want/need to host your applications on a webserver.
1959
 *
1960
 * If you're not interested in configuring a full-fledged webserver, but
1961
 * are only interested in a quick and easy way to test the demos, you can
1962
 * make use of the embedded webservers some frameworks like PHP and Python
1963
 * provide. To start a webserver for the demos, for instance, just open a
1964
 * terminal in the \c html folder of the project, and type:
1965
 *
1966
 *\verbatim
1967
php -S 0.0.0.0:8000
1968
 \endverbatim
1969
 *
1970
 * or:
1971
 *
1972
 *\verbatim
1973
python -m SimpleHTTPServer 8000
1974
 \endverbatim
1975
 *
1976
 * This will setup a webserver on port \c 8000 for you to use, meaning you'll
1977
 * just need to have your browser open a local connection to that port to 
1978
 * try the demos:
1979
 *
1980
 *\verbatim
1981
http://yourlocaliphere:8000
1982
 \endverbatim
1983
 *
1984
 * You can do the same on a different port to also access the HTML version of the Doxygen generated
1985
 * documentation, starting the embedded webservers from the \c docs/html
1986
 * folder instead:
1987
 *
1988
 *\verbatim
1989
php -S 0.0.0.0:9000
1990
 \endverbatim
1991
 *
1992
 * or:
1993
 *
1994
 *\verbatim
1995
python -m SimpleHTTPServer 9000
1996
 \endverbatim
1997
 *
1998
 * \section deplyws Using Janus with WebSockets 
1999
 *
2000
 * Configuring the usae of WebSockets rather than the REST API in the JavaScript
2001
 * library is quite trivial, as it's a matter of passing a \c ws:// address
2002
 * instead of an \c http:// one to the constructor. That said, most of the same
2003
 * considerations provided for the REST API apply here as well, e.g.,
2004
 * to just use \c window.location.hostname if the webserver and Janus are
2005
 * colocated:
2006
 *
2007
 \verbatim
2008
var server = "ws://" + window.location.hostname + ":8188/";
2009
 \endverbatim
2010
 *
2011
 * to specify the port if you change it:
2012
 *
2013
 \verbatim
2014
var server = "ws://" + window.location.hostname + ":7000/";
2015
 \endverbatim
2016
 *
2017
 * and/or the right address of the gateway in case the webserver and Janus
2018
 * are <b>NOT</b> colocated:
2019
 *
2020
 \verbatim
2021
var server = "ws://www.example.com:8188/";
2022
 \endverbatim
2023
 *
2024
 * Notice how the path (\c /janus by default for HTTP) is not provided
2025
 * for WebSockets, as it is ignored by the gateway.
2026
 *
2027
 * The considerations for deploying Janus behind a proxy/webserver, though,
2028
 * differ if you use WebSockets, as most webservers don't provide an easy
2029
 * way to proxy WebSocket requests, and usually require custom modifications
2030
 * for the purpose. Recent versions of HTTPD (>= 2.4.5), with the right
2031
 * module (proxy_wstunnel), do allow you to also proxy WebSockets requests the
2032
 * same way you do with HTTP, which can be useful to do the same
2033
 * WSS-to-WS proxying in a frontend. Here's a sample configuration:
2034
 *
2035
 \verbatim
2036
<IfModule mod_proxy_wstunnel.c>
2037
	ProxyPass /janus-ws ws://127.0.0.1:8188 retry=0
2038
	ProxyPassReverse /janus-ws ws://127.0.0.1:8188
2039
</IfModule>
2040
 \endverbatim
2041
 *
2042
 * that will allow you to expose a <code>wss://myserver/janus-ws</code>
2043
 * or <code>ws://myserver/janus-ws</code> address, and have all communication
2044
 * forwarded to and from Janus at <code>ws://127.0.0.1:8188</code>.
2045
 *
2046
 * Similar configurations are probably available for other systems as well,
2047
 * so in case this is something you're interested in, we recommend you
2048
 * follow the best practices related to that made available by the web server developers.
2049
 *
2050
 * \section both Using fallback addresses 
2051
 * As anticipated in the \ref JS section, you can also pass an array of servers
2052
 * to the Janus library initialization. This allows you, for instance, to
2053
 * pass a link to both the WebSockets and REST interfaces, and have the
2054
 * library try them both to see which one is reachable, e.g.:
2055
 *
2056
 \verbatim
2057
var ws_server = "ws://" + window.location.hostname + ":8188/";
2058
var http_server = "http://" + window.location.hostname + ":8088/janus";
2059
var servers = [ws_server, http_server];
2060
 \endverbatim
2061
 *
2062
 * which is especially useful if you're not sure whether or not WebSockets
2063
 * will work in some specific networks. Please notice that, for the individual
2064
 * servers listed in the array, the same considerations given above (e.g.,
2065
 * in terms of relative vs. absolute linking) still apply.
2066
 *
2067
 * Such an approach can also be used when you've deployed several different
2068
 * instances of Janus, and you want the library to try some and fallback
2069
 * to others if any of them is not reachable for any reason.
2070
 *
2071
 */
2072

    
2073
/*! \page service Janus as a daemon/service
2074
 *
2075
 * By default, Janus starts in foreground, and as such works as a server
2076
 * application that you start normally and displays output on the console.
2077
 * That said, there are several reasons why you may not want to keep
2078
 * Janus in the foreground, while still being interested in checking
2079
 * the console to see what's happening.
2080
 *
2081
 * There are different ways to "daemonize" it and have it run as a service,
2082
 * though. This page tries to summarize a few ways to do so, starting
2083
 * from "dumb" approaches like sending to background and/or using screen/tmux,
2084
 * to more sophisticated approaches involving \c systemd, \c upstart
2085
 * and others.
2086
 *
2087
 * \section daemon Running Janus as a daemon
2088
 * Since version \c 0.1.0, you can run Janus as a daemon application. To
2089
 * do so, just pass either \c -b or <code>\--daemon</code> as a command line
2090
 * argument, and Janus will be daemonized. Just beware, though, that
2091
 * since this results in stdout/stdin/stderr being closed, you MUST
2092
 * specify a log file for Janus to use, either via command line (\c -L
2093
 * or <code>\--log-file</code>) or in \c janus.cfg.
2094
 *
2095
 * \section bg Running in background
2096
 * Another simple way to run Janus in the background is to just append the
2097
 * \c & character to the command line. Anyway, this will still "flood" the console
2098
 * with output from Janus. While there are ways to handle it (e.g., as
2099
 * explained <a href="http://www.thegeekstuff.com/2010/05/unix-background-job/">here</a>),
2100
 * a nice and easy way to handle this is redirecting the output to a 
2101
 * separate file, e.g., a dedicated log:
2102
 *
2103
 \verbatim
2104
/opt/janus/bin/janus -d 5 -6 >/path/to/mylogfile 2>&1 &
2105
 \endverbatim
2106
 *
2107
 * This is especially useful in case you want to keep a log of what
2108
 * happened when Janus was running, and can also be used as a simple and
2109
 * effective way to watch the console "live" using \c tail:
2110
 \verbatim
2111
tail -f /path/to/mylogfile
2112
 \endverbatim
2113
 *
2114
 * \section screen Terminal multiplexers
2115
 * Another easy way to run Janus in the background is using terminal
2116
 * multiplexers like \c screen or \c tmux. If you're not familiar with
2117
 * such applications, you can find a quick overview
2118
 * <a href="https://en.wikipedia.org/wiki/Terminal_multiplexer">here</a>.
2119
 *
2120
 * The following is a simple example with \c screen:
2121
 *
2122
 \verbatim
2123
screen -S janus -d -m
2124
screen -r janus -X stuff $'/opt/janus/bin/janus -d 5 -6\n'
2125
 \endverbatim
2126
 *
2127
 * This will create a session called "janus" and launch Janus in it with
2128
 * a few command line options (in this case, just the option to enable
2129
 * IPv6 support and set the debug to verbose). Janus will then be running
2130
 * in the background: accessing the console is just a matter of attaching
2131
 * to the "janus" screen: 
2132
 *
2133
 \verbatim
2134
screen -r janus
2135
[CTRL+A+D to detach again]
2136
 \endverbatim
2137
 *
2138
 * Terminal multiplexers usually allow for logging the output to file
2139
 * as well, if you want to keep an history of what happened during the
2140
 * Janus lifetime.
2141
 *
2142
 * \section systemd systemd
2143
 * This section shows how you can add Janus as a service to
2144
 * <a href="https://en.wikipedia.org/wiki/Systemd">systemd</a>.
2145
 *
2146
 \verbatim
2147
[Unit]
2148
Description=Janus WebRTC gateway
2149
After=network.target
2150

    
2151
[Service]
2152
Type=simple
2153
ExecStart=/opt/janus/bin/janus -o
2154
Restart=on-abnormal
2155
LimitNOFILE=65536
2156

    
2157
[Install]
2158
WantedBy=multi-user.target
2159
 \endverbatim
2160
 *
2161
 * \note Remember to adjust the path in ExecStart to match the Janus binary path.
2162
 *
2163
 * \warning Please beware that, per the default \c RateLimitInterval and
2164
 * and \c RateLimitBurst values in the default sytemd configuration, logger
2165
 * messages are dropped if they arrive faster than ~33 per second. You
2166
 * may want to configure them accordingly, or otherwise Janus log messages
2167
 * may be missing. To fix this, setting <code>RateLimitInterval=1s</code>
2168
 * and <code>RateLimitBurst=2000</code> in
2169
 * <code>/etc/systemd/journald.conf</code> is usually enough.
2170
 *
2171
 * \note systemd example provided by
2172
 * <a href="https://github.com/meetecho/janus-gateway/pull/306">\@saghul</a> 
2173
 *
2174
 * \section upstart upstart
2175
 * This section shows how you can add Janus as a daemon to
2176
 * <a href="http://upstart.ubuntu.com/">upstart</a>, which is
2177
 * typically available on Ubuntu systems.
2178
 *
2179
 \verbatim
2180
description "janus"
2181

    
2182
start on filesystem or runlevel [2345]
2183
stop on runlevel [!2345]
2184
limit nofile 50000 50000
2185
limit core unlimited unlimited
2186

    
2187
respawn
2188
respawn limit 10 5
2189

    
2190
exec /opt/janus/bin/janus
2191
 \endverbatim
2192
 *
2193
 * \note upstart example provided by
2194
 * <a href="https://github.com/meetecho/janus-gateway/pull/306">\@ploxiln</a> 
2195
 *
2196
 * \warning In case starting Janus depends on some external conditions, you
2197
 * may need to modify the \c start and \c stop lines accordingly. Here you can
2198
 * find an <a href="https://github.com/meetecho/janus-gateway/pull/455">example</a>,
2199
 * provided by <a href="https://github.com/meetecho/janus-gateway/pull/455">\@stormbkk87</a>,
2200
 * showing how you can wait, for instance, for RabbitMQ to start before starting Janus too.
2201
 *
2202
 * \section sysvinit sysvinit
2203
 * This section shows how you can add Janus as a daemon to
2204
 * SysVinit based systems.
2205
 *
2206
 \verbatim
2207
#!/bin/sh
2208

    
2209
### BEGIN INIT INFO
2210
# Provides:          Janus
2211
# Required-Start:    $remote_fs $syslog
2212
# Required-Stop:     $remote_fs $syslog
2213
# Default-Start:     2 3 4 5
2214
# Default-Stop:      0 1 6
2215
# Short-Description: Janus WebRTC gateway
2216
# Description:       Janus WebRTC gateway
2217
### END INIT INFO
2218

    
2219
DAEMON=/usr/bin/janus
2220
DAEMON_NAME=janus
2221

    
2222
# Add any command line options for your daemon here
2223
DAEMON_OPTS="-D -o"
2224

    
2225
# This next line determines what user the script runs as.
2226
# Root generally not recommended but necessary if you are using the Raspberry Pi GPIO from Python.
2227
DAEMON_USER=root
2228

    
2229
# The process ID of the script when it runs is stored here:
2230
PIDFILE=/var/run/$DAEMON_NAME.pid
2231

    
2232
. /lib/lsb/init-functions
2233

    
2234
do_start () {
2235
    log_daemon_msg "Starting system $DAEMON_NAME daemon"
2236
    start-stop-daemon --start --background --no-close --pidfile $PIDFILE --make-pidfile --user $DAEMON_USER --chuid $DAEMON_USER --startas $DAEMON -- $DAEMON_OPTS >> /var/log/$DAEMON_NAME.log 2>&1
2237
    log_end_msg $?
2238
}
2239
do_stop () {
2240
    log_daemon_msg "Stopping system $DAEMON_NAME daemon"
2241
    start-stop-daemon --stop --pidfile $PIDFILE --retry 10
2242
    log_end_msg $?
2243
}
2244

    
2245
case "$1" in
2246

    
2247
    start|stop)
2248
        do_${1}
2249
        ;;
2250

    
2251
    restart|reload|force-reload)
2252
        do_stop
2253
        do_start
2254
        ;;
2255

    
2256
    status)
2257
        status_of_proc "$DAEMON_NAME" "$DAEMON" && exit 0 || exit $?
2258
        ;;
2259

    
2260
    *)
2261
        echo "Usage: /etc/init.d/$DAEMON_NAME {start|stop|restart|status}"
2262
        exit 1
2263
        ;;
2264

    
2265
esac
2266
exit 0
2267
 \endverbatim
2268
 *
2269
 * \note sysvinit example provided by
2270
 * <a href="https://github.com/saghul">\@saghul</a> 
2271
 *
2272
 * \section supervisor supervisor
2273
 * This section shows how you can add Janus to
2274
 * <a href="http://supervisord.org/">supervisor</a>, which is
2275
 * typically available on Ubuntu systems.
2276
 *
2277
 \verbatim
2278
[program:janus]
2279
command=/opt/janus/bin/janus
2280
user=root
2281
autostart=true
2282
autorestart=true
2283
stderr_logfile=/var/log/janus.err.log
2284
stdout_logfile=/var/log/janus.out.log
2285
 \endverbatim
2286
 *
2287
 * \note The above configuration file should be added to
2288
 * <code>/etc/supervisor/conf.d/janus.conf</code>. Then the following commands
2289
 * should be run:
2290
 *
2291
 \verbatim
2292
sudo supervisorctl reread
2293
sudo supervisorctl update
2294
 \endverbatim
2295
 *
2296
 * \section Others
2297
 * TODO.
2298
 *
2299
 */
2300
 
2301
/*! \page debug Debugging Janus
2302
 *
2303
 * In the magical world of fairies and unicorns, the sun always shines
2304
 * and everything always works smoothly and without issues. Unfortunately,
2305
 * this is not the world we live in, and so you might still encounter
2306
 * issues using Janus, e.g., unexpected crashes and the like. We always
2307
 * try and tackle bugs as soon as we spot them, but some issues may be
2308
 * always lingering in the background.
2309
 *
2310
 * Should you encounter a bug or a crash, open a new
2311
 * <a href="https://github.com/meetecho/janus-gateway/issues/new">issue</a>
2312
 * on GitHub. Make sure you carefully read the
2313
 * <a href="https://github.com/meetecho/janus-gateway/blob/master/CONTRIBUTING.md">guidelines</a>
2314
 * for contributing, or otherwise we may decide to close the issue and
2315
 * not even look at it.
2316
 *
2317
 * What's important for us to look into issues and bugs definitely is
2318
 * having enough information to do so. As such, whenever possible try to
2319
 * provide as many details and data as possible. Quite useful to us are
2320
 * GDB stacktraces and/or AddressSanitizer output. The following sections
2321
 * give a quick overview on how you can collect this information after
2322
 * a crash, but for a more detailed description of the tools you should
2323
 * refer to the related documentation pages and tutorials.
2324
 *
2325
 * \section gdb GDB
2326
 * GDB is the <a href="http://www.gnu.org/software/gdb/">GNU Project Debugger</a>
2327
 * and is an effective tool for looking at what has happened (or is
2328
 * happening) inside an application. As such, it's quite useful to spot
2329
 * bugs and the like, as it can provide information about the values of
2330
 * variables when they were used and the application crashed.
2331
 *
2332
 * When Janus crashes, you should get a core dump file somewhere. This is
2333
 * a recorded state of the application memory at the time of crashing, and
2334
 * so a backtrace of what lead to an issue can help. You can open such
2335
 * a core dump file via gdb this way:
2336
 *
2337
 \verbatim
2338
gdb /path/to/bin/janus /path/to/coredump
2339
gdb bt
2340
 \endverbatim
2341
 *
2342
 * The \c bt command retrieves the backtrace, and is what you should provide
2343
 * as part of your new issue.
2344
 *
2345
 * \note Please \c DON'T paste this backtrace in the issue text. Use a
2346
 * service like <a href="https://gist.github.com/">Gist</a> or
2347
 * <a href="http://pastebin.com/">Pastebin</a> and pass the generated
2348
 * link instead.
2349
 *
2350
 * \section sanitizer Address Sanitizer
2351
 * An even better tool for spotting issues is
2352
 * <a href="https://code.google.com/p/address-sanitizer/">Address Sanitizer</a>,
2353
 * a fast memory error detector. Since it can spot memory errors, it's
2354
 * very useful to find out about hidden race conditions and the like.
2355
 *
2356
 * Unlike GDB which can be used as is, though, to use Address Sanitizer
2357
 * you'll first need to recompile Janus with some new settings, as it
2358
 * requires a specific dependency on a library, libasan, which you'll need
2359
 * to install through your repository manager if needed. Besides, you'll
2360
 * need at least gcc 4.8 for this to work: older versions of gcc won't
2361
 * work.
2362
 *
2363
 * Once you've installed libasan, reconfigure Janus like this:
2364
 *
2365
 \verbatim
2366
CFLAGS="-fsanitize=address -fno-omit-frame-pointer" LDFLAGS="-lasan" ./configure --prefix=/opt/janus
2367
 \endverbatim
2368
 *
2369
 * Of course you're free to add whatever additional configuration parameter
2370
 * you were using before: the important parts are the environment variables
2371
 * before that. Once done configuring, do a \c make \c clean (to make sure
2372
 * everything is recompiled from scratch) and then a \c make and \c make \c install
2373
 * as usual.
2374
 *
2375
 * At this point, your Janus version should be Address Sanitizer compliant.
2376
 * To make sure, try using \c ldd to check whether libasan is indeed a
2377
 * dependency or not:
2378
 *
2379
 \verbatim
2380
ldd janus | grep asan
2381
 \endverbatim
2382
 *
2383
 * If it is, you're done: whenever Janus crashes for any reason, you'll
2384
 * get additional output from Address Sanitizer automatically with details
2385
 * on what went wrong, and that's what you should provide as part of the
2386
 * issue content. Just as a side note, please beware that using Address
2387
 * Sanitizer Janus will run just a bit slower, even though not to the
2388
 * point of being unusable (as when using, e.g., valgrind).
2389
 *
2390
 * \note Please \c DON'T paste Address Sanitizer output in the issue text.
2391
 * Use a service like <a href="https://gist.github.com/">Gist</a> or
2392
 * <a href="http://pastebin.com/">Pastebin</a> and pass the generated
2393
 * link instead.
2394
 *
2395
 */
2396

    
2397
/*! \page resources Resources
2398
 * This page contains pointers to some third-party resources, in particular
2399
 * distro repos for an easier installation of Janus, where available,
2400
 * client stacks, libraries and bindings in other languages, that is
2401
 * tools that you find helpful to interact with Janus outside of the
2402
 * context of the \c janus.js JavaScript library we provide. It is not
2403
 * a complete list, but just a summary of the material that has been
2404
 * shared so far on the <a href="https://groups.google.com/forum/#!forum/meetecho-janus">meetecho-janus</a>
2405
 * Google group. 
2406
 *
2407
 * If you've developed anything related to Janus (client stacks, plugins,
2408
 * transports, etc.) and you're willing to share them with the community,
2409
 * or you know any such effort that is not listed here, just let us know
2410
 * and we'll add it on this page.
2411
 * <br/><br/>
2412
 *
2413
 * \section repos Distro repositories
2414
 *
2415
 * <table class="table table-striped">
2416
 * <tr><th>Distro</th><th>Author</th><th>Repo</th><th>Description</th></tr>
2417
 * <tr>
2418
 * 		<td>Debian/Ubuntu</td>
2419
 * 		<td><a href="https://github.com/saghul">Saúl Ibarra Corretgé </a></td>
2420
 * 		<td><a href="http://projects.ag-projects.com/projects/documentation/wiki/Repositories">AG Projects Repo</a></td>
2421
 *		<td>Debian Jessie, Ubuntu Trusty and Ubuntu Xenial</td>
2422
 * </tr>
2423
 * </table>
2424
 * <br/>
2425
 *
2426
 * \section stacks Client-side stacks
2427
 *
2428
 * <table class="table table-striped">
2429
 * <tr><th>Language</th><th>Author</th><th>Project</th><th>Description</th></tr>
2430
 * <tr>
2431
 * 		<td>node-js</td>
2432
 * 		<td><a href="https://github.com/ndarilek">Nolan Darilek</a></td>
2433
 * 		<td><a href="https://github.com/ndarilek/node-janus">node-janus</a></td>
2434
 *		<td>node and browserify compatible integration layer for the Janus WebRTC gateway</td>
2435
 * </tr>
2436
 * <tr>
2437
 * 		<td>node-js</td>
2438
 * 		<td><a href="https://github.com/DamonOehlman">Damon Oehlman</a></td>
2439
 * 		<td><a href="https://github.com/rtc-io/rtc-janus">rtc-janus</a></td>
2440
 *		<td>node and browserify compatible integration layer for the Janus WebRTC gateway:
2441
 * experimental and incomplete as per the author words, but a good starting point</td>
2442
 * </tr>
2443
 * <tr>
2444
 * 		<td>node-js</td>
2445
 * 		<td><a href="https://github.com/cargomedia">Cargo Media</a></td>
2446
 * 		<td><a href="https://github.com/cargomedia/janus-gateway-js">janus-gateway-js</a></td>
2447
 * 		<td>Simple JavaScript client for janus-gateway that runs in the browser as well as in Node.js</td>
2448
 * </tr>
2449
 * <tr>
2450
 * 		<td>node-js</td>
2451
 * 		<td><a href="https://www.sipwise.com/">sip:wise</a></td>
2452
 * 		<td><a href="https://www.npmjs.com/~sipwise">admin/videoroom client</a></td>
2453
 * 		<td>Node.js clients that implement the Admin API and VideoRoom functionality</td>
2454
 * </tr>
2455
 * <tr>
2456
 * 		<td>ruby</td>
2457
 * 		<td><a href="https://github.com/cargomedia">Cargo Media</a></td>
2458
 * 		<td><a href="https://github.com/cargomedia/janus-gateway-ruby">janus-gateway-ruby</a></td>
2459
 * 		<td>ruby client side API wrapper for the Janus API (websocket only at the moment)</td>
2460
 * </tr>
2461
 * <tr>
2462
 * 		<td>C#/.NET</td>
2463
 * 		<td><a href="https://github.com/Computician">Benjamin Trent</a></td>
2464
 * 		<td><a href="https://github.com/Computician/JanusSharp">JanusSharp</a></td>
2465
 * 		<td>C#/.Net client side API wrapper for the Janus API</td>
2466
 * </tr>
2467
 * <tr>
2468
 * 		<td>PHP</td>
2469
 * 		<td><a href="https://github.com/BenJaziaSadok">Mohamed Sadok Ben Jazia</a></td>
2470
 * 		<td><a href="https://github.com/BenJaziaSadok/janus-gateway-php">janus-gateway-php</a></td>
2471
 * 		<td>Client-side PHP/javascript implementation of the Janus and Admin APIs</td>
2472
 * </tr>
2473
 * <tr>
2474
 * 		<td>Golang</td>
2475
 * 		<td><a href="https://github.com/nowylie">Nicholas Wylie</a></td>
2476
 * 		<td><a href="https://github.com/nowylie/go-janus">go-janus</a></td>
2477
 * 		<td>Golang library to the Janus API (Unix Sockets/SOCK_DGRAM only at the moment)</td>
2478
 * </tr>
2479
 * </table>
2480
 * <br/>
2481
 *
2482
 * \section mobile Mobile resources
2483
 *
2484
 * <table class="table table-striped">
2485
 * <tr><th>OS</th><th>Author</th><th>Project</th><th>Description</th></tr>
2486
 * <tr>
2487
 * 		<td>Android</td>
2488
 * 		<td><a href="https://github.com/Computician">Benjamin Trent</a></td>
2489
 * 		<td><a href="https://github.com/Computician/janus-gateway-android">janus-gateway-android</a></td>
2490
 *		<td>API wrapper that utilizes the native WebRTC build and is made to ease communication with Janus</td>
2491
 * </tr>
2492
 * <tr>
2493
 * 		<td>iOS</td>
2494
 * 		<td><a href="https://github.com/davibe">Davide Bertola</a></td>
2495
 * 		<td><a href="https://github.com/davibe/cordova-webrtc-janus-gateway">cordova-webrtc-janus-gateway</a></td>
2496
 * 		<td>cordova application that interfaces with Janus and is based on the PhoneRTC cordova plugin</td>
2497
 * </tr>
2498
 * </table>
2499
 * <br/>
2500
 *
2501
 * \section pi Raspberry Pi resources
2502
 *
2503
 * <table class="table table-striped">
2504
 * <tr><th>Author</th><th>Project</th><th>Description</th></tr>
2505
 * <tr>
2506
 * 		<td><a href="http://linux-projects.org">Linux Projects</a></td>
2507
 * 		<td><a href="http://www.linux-projects.org/rpi-videoconference-demo-os/">Rpi VideoConference OS</a></td>
2508
 *		<td>Ready-to-use OS for video conferences over the web from a Raspberry Pi</td>
2509
 * </tr>
2510
 * <tr>
2511
 * 		<td><a href="http://linux-projects.org">Linux Projects</a></td>
2512
 * 		<td><a href="http://www.linux-projects.org/uv4l/tutorials/janus-gateway/">UV4L, User Space Video Collection</a></td>
2513
 * 		<td>Software modules providing solutions for encrypted live data, audio and video streaming, mirroring, conferencing</td>
2514
 * </tr>
2515
 * </table>
2516
 * <br/>
2517
 *
2518
 * \section docker Docker resources
2519
 *
2520
 * <table class="table table-striped">
2521
 * <tr><th>Author</th><th>Project</th><th>Description</th></tr>
2522
 * <tr>
2523
 * 		<td><a href="https://github.com/krull">Brendan Jocson</a></td>
2524
 * 		<td><a href="https://github.com/krull/docker-janus">docker-janus</a></td>
2525
 *		<td>Debian 8 based docker image for Meetecho's Janus Gateway</td>
2526
 * </tr>
2527
 * </table>
2528
 * <br/>
2529
 *
2530
 * \section thirdplugins Third-party plugins
2531
 *
2532
 * <table class="table table-striped">
2533
 * <tr><th>Author</th><th>Project</th><th>Description</th></tr>
2534
 * <tr>
2535
 * 		<td><a href="https://github.com/cargomedia">Cargo Media</a></td>
2536
 * 		<td><a href="https://github.com/cargomedia/janus-gateway-rtpbroadcast">janus-gateway-rtpbroadcast</a></td>
2537
 * 		<td>Janus-gateway plugin to broadcast RTP video</td>
2538
 * </tr>
2539
 * </table>
2540
 * <br/>
2541
 *
2542
 * \section thirdtrasports Third-party transports
2543
 *
2544
 * <table class="table table-striped">
2545
 * <tr><th>Author</th><th>Project</th><th>Description</th></tr>
2546
 * <tr>
2547
 * 		<td><a href="https://github.com/nowylie">Nicholas Wylie</a></td>
2548
 * 		<td><a href="https://github.com/nowylie/janus-ud-transport">janus-ud-transport</a></td>
2549
 * 		<td>Janus transport plugin that adds support for Datagram messages over Unix Domain Sockets</td>
2550
 * </tr>
2551
 * </table>
2552
 * <br/>
2553
 *
2554
 */
2555

    
2556

    
2557
/*! \page README README
2558
 *  \verbinclude README.md
2559
 */
2560

    
2561
/*! \page CREDITS Credits
2562
 *
2563
 * Janus WebRTC Gateway © 2014-2016 <a href="http://www.meetecho.com/">Meetecho</a> (http://www.meetecho.com/)
2564
 *
2565
 * \b Author:
2566
 *         Lorenzo Miniero <lorenzo@meetecho.com>
2567
 *
2568
 * Several open source components have been used to implement this software:
2569
 *
2570
 * - \b GLib: http://library.gnome.org/devel/glib/
2571
 * - \b pkg-config: http://www.freedesktop.org/wiki/Software/pkg-config/
2572
 * - \b gengetopt: http://www.gnu.org/software/gengetopt/ (command line)
2573
 * - \b libini-config: https://fedorahosted.org/sssd/ (INI configurations)
2574
 * - \b Jansson: http://www.digip.org/jansson/ (JSON)
2575
 * - \b libnice: http://nice.freedesktop.org/wiki/ (ICE/STUN/TURN)
2576
 * - \b OpenSSL: http://www.openssl.org/ (DTLS, at least v1.0.1e)
2577
 * - \b libsrtp: https://github.com/cisco/libsrtp (SRTP, at least v1.5 suggested)
2578
 * - \b usrsctp: http://code.google.com/p/sctp-refimpl/ (Data Channels)
2579
 * - \b libmicrohttpd: http://www.gnu.org/software/libmicrohttpd/ (Web server)
2580
 * - \b libwebsockets: https://libwebsockets.org/ (WebSockets)
2581
 * - \b rabbitmq-c: https://github.com/alanxz/rabbitmq-c (RabbitMQ)
2582
 * - \b Sofia-SIP: http://sofia-sip.sourceforge.net/ (only needed for the SIP plugin)
2583
 * - \b libopus: http://opus-codec.org/ (only needed for the bridge plugin)
2584
 * - \b libogg: http://xiph.org/ogg/ (only needed for the voicemail plugin)
2585
 *
2586
 */
2587
  
2588
/*! \page COPYING License
2589
 * This program is free software, distributed under the terms of the GNU
2590
 * General Public License Version 3.
2591
 *
2592
 * If you're interested in a commercial license (e.g., because GPLv3 is
2593
 * not suited for what you need, you're interested in technical support
2594
 * or want to sponsor the development of new features), feel free to
2595
 * <a href="https://janus.conf.meetecho.com/support">contact us</a>.
2596
 *
2597
 *  \verbinclude COPYING
2598
 */
2599

    
2600
/*! \page FAQ Frequently Asked Questions
2601
 * This page contains a list of FAQ as gathered on the
2602
 * <a href="https://groups.google.com/forum/?pli=1#!forum/meetecho-janus">meetecho-janus</a>
2603
 * Google group and the 
2604
 * <a href="https://github.com/meetecho/janus-gateway/issues">Issues</a>
2605
 * page on GitHub. It obviously also includes things we're being asked all the
2606
 * time in general! If your question is not listed here or not available
2607
 * anywhere in this documentation, feel free to refer to the group for
2608
 * generic help, or to the Issues page for bugs in the implementation.\n\n
2609
 *
2610
 * -# <b>What is Janus?</b>\n
2611
 *    .
2612
 *    Janus is an open source WebRTC gateway and server written by <a href="http://www.meetecho.com">Meetecho</a>,
2613
 *    conceived as modular and, as much as possible,
2614
 *    general purpose. It acts as a WebRTC endpoint browsers can interact
2615
 *    with, and different modules can determine what should be done with
2616
 *    the media. This means that you can do SIP, videoconferencing, streaming
2617
 *    and tons of other stuff using the same box! And if what you need is
2618
 *    not there, you can always write your own module and expand Janus.\n\n
2619
 *    .
2620
 * -# <b>What is Meetecho?</b>\n
2621
 *    .
2622
 *    Meetecho is a company founded by a few researchers, post-docs and
2623
 *    Ph.Ds coming from the Universty of Napoli Federico II. We've been
2624
 *    working on real-time multimedia applications over the Internet for
2625
 *    years, and at one point we decided to try and make products out
2626
 *    of our research efforts. Our web conferencing platform and Janus
2627
 *    are part of those efforts.\n\n
2628
 *    .
2629
 * -# <b>Now that we're at it, how is Meetecho pronounced??</b>\n
2630
 *    .
2631
 *    We're being asked that a lot! We've heard so many variants and different
2632
 *    pronounciations of the name that we could make a book out of it!
2633
 *    When we chose the name, we wanted it to sound like
2634
 *    <a href="https://www.youtube.com/watch?v=TkgDOMSv9PE">this</a>,
2635
 *    which means \a awesome! in Italian. The extra H was a mistake on our
2636
 *    side, as obviously \a echo is pronouced differently than \a eco! Long
2637
 *    story short, it doesn't really matter how you pronounce it: just
2638
 *    do it and help us be famous! :-)\n\n
2639
 *    .
2640
 * -# <b>I just started with Janus and am overwhelmed by the amount of info, documentation, etc... any easy way to dive in?</b>\n
2641
 *    .
2642
 *    Fair point! Janus and its concepts/APIs can be a lot to digest in a short time...
2643
 *    An easy way to start is watching one of the several presentations we've done
2644
 *    on Janus these last months. Most if not all of them try to provide a
2645
 *    complete introduction to the context Janus was built in, how it was
2646
 *    born, the architecture we chose for it and so on. As such, it should
2647
 *    be a useful starting point for whoever is interested in learning
2648
 *    what Janus can do and how to use it.\n\n
2649
 *    There are several videos available that you can find online, here
2650
 *    are some of them as quick pointers:
2651
 *    - Presentations at <a href="https://www.youtube.com/watch?v=u0PyXgAC8m4">#vuc485</a>
2652
 *    and <a href="https://www.youtube.com/watch?v=VnflQF7oCLA">#vuc584</a>;
2653
 *    - Presentation at <a href="https://www.youtube.com/watch?v=SFeWYewoL7Q">OpenSIPS summit</a>;
2654
 *    - Presentation at <a href="https://www.youtube.com/watch?v=yvt-vMHW83c">Kamailio World</a>;
2655
 *    - Presentation at <a href="https://www.youtube.com/watch?v=WfNciKbsP80">WebRTC Meetup Tokyo #12</a>. \n\n
2656
 *    .
2657
 * -# <b>Why is Janus called like that?</b>\n
2658
 *    .
2659
 *    Quoting <a href="http://en.wikipedia.org/wiki/Janus">Wikipedia</a>:
2660
 *    "<i>In ancient Roman religion and myth, Janus (Latin: Ianus, pronounced
2661
 *    [ˈiaː.nus]) is the god of beginnings and transitions, and thereby of
2662
 *    gates, doors, passages, endings and time. He is usually depicted as
2663
 *    having two faces, since he looks to the future and to the past.</i>"
2664
 *    Considering the general purpose nature of our gateway, where one face always looks
2665
 *    at the future (WebRTC) and the other at the past (whatever the modules
2666
 *    allows you to do, be it legacy stuff or not), Janus looked like the
2667
 *    perfect name for it! And besides, we're Italian, Ancient Rome was
2668
 *    awesome and mythology rules... ;-)  
2669
 *    \n\n
2670
 *    .
2671
 * -# <b>Is the license AGPLv3 or GPLv3? Do you provide alternative license mechanisms as well?</b>\n
2672
 *    .
2673
 *    Janus is licensend under the GPLv3 licence. At the very beginning
2674
 *    we chose AGPLv3 for a simple reason: we wanted our work to be open source,
2675
 *    and we wanted interested people to play with it and contribute back
2676
 *    whatever improvement they could provide to the core. This is not always
2677
 *    the case with open source software, which is sometimes just seen as
2678
 *    free stuff you can exploit without helping back, and AGPLv3 looked like
2679
 *    the easiest way to do that. That said, we were almost immediately
2680
 *    made aware that this license mechanism is
2681
 *    <a href="https://groups.google.com/forum/?pli=1#!searchin/discuss-webrtc/janus/discuss-webrtc/LJHXkIsAaEU/fHgJ2z0sxfoJ">not very appreciated</a>
2682
 *    around, especially because of some
2683
 *    interpretations about it that could affect the way proprietary stuff
2684
 *    is deployed. We obviously cared about these concerns, and that's what
2685
 *    eventually lead us to pick GPLv3 as a license, which should make it
2686
 *    easier for Janus to be integrated in heterogeneous scenarios.\n\n
2687
 *    Anyway, if for some reason you're not comfortable with GPLv3 for your
2688
 *    needs, we have a <a href="https://janus.conf.meetecho.com/support">commercial license</a>
2689
 *    offering as well.\n\n
2690
 *    .
2691
 * -# <b>On what OS can I install Janus?</b>\n
2692
 *    .
2693
 *    At the moment only Linux is officially supported. Anyway, Janus does
2694
 *    compile on Mac OS as well, thanks to contributions from the community,
2695
 *    and so should work fine there as well. Windows support is also provided
2696
 *    as a <a href="https://github.com/meetecho/janus-gateway/pull/597">pull request</a>
2697
 *    by a Janus contributor: anyway, please beware that Windows support is behind the current
2698
 *    version of development.\n\n
2699
 *    .
2700
 * -# <b>Are Data Channels supported?</b>\n
2701
 *    .
2702
 *    Yes they are! Starting from version \c 0.0.3 of Janus, we added a first
2703
 *    experimental support to Data Channels, that can as such be used in
2704
 *    plugins that choose to support them. Right now, they are handled in
2705
 *    several plugins like the Echo Test, VideoCall, VideoRoom and TextRoom plugins.\n\n
2706
 *    Please notice that right now we only support text data: hopefully support
2707
 *    for binary streams will be available soon as well. Until that happens,
2708
 *    you'll have to resort to text-based encodings like Base64 to share
2709
 *    binary data through Janus.\n\n
2710
 *    .
2711
 * -# <b>I don't care about Data Channels, do I have to compile usrsctp anyway?</b>\n
2712
 *    .
2713
 *    Support for Data Channels is optional, so if you didn't install the library
2714
 *    the configure script will go around them and compile Janus without Data Channels
2715
 *    support. If you did install the library and don't care about Data Channels,
2716
 *    but only about audio and/or video, pass the \c --disable-data-channels
2717
 *    option to the configure script to explicitly disable them. If you're updating
2718
 *    an existing install, issue a \c make \c clean before compiling again, or
2719
 *    you might encounter issues with pre-existing symbols.\n\n
2720
 *    .
2721
 * -# <b>I can't install usrsctp, I'm getting errors about dereferencing pointers?</b>\n
2722
 *    .
2723
 *    Apparently recent compilers are stricter with respect to some code
2724
 *    syntaxes, and this seems to be affecting the way \c usrsctp is written
2725
 *    as of now. Some users managed to fix this issue by passing an export
2726
 *    before the \c bootstrap and \c configure steps in the \c usrsctp
2727
 *    compilation:\n\n
2728
 *\verbatim
2729
   export CFLAGS="-fno-strict-aliasing" ./boostrap
2730
   export CFLAGS="-fno-strict-aliasing" ./configure --prefix=/usr
2731
   make && make install
2732
 \endverbatim
2733
 *    Another solution seems to be removing all the \c -O2 occurrences
2734
 *    in the generated \c configure script.\n\n
2735
 *    .
2736
 * -# <b>Can I use Janus as a gateway to my Freeswitch/Kamailio/Asterisk/other SIP infrastructure?</b>\n
2737
 *    .
2738
 *    Of course! One of the modules we provide out of the box is a SIP
2739
 *    gateway plugin based on the <a href="http://sofia-sip.sourceforge.net/">Sofia-SIP</a>
2740
 *    library stack. These plugin allows a web user to register at a SIP
2741
 *    proxy/server either as an authenticated user or as a guest, and
2742
 *    start or receive calls from other SIP users, including other web users
2743
 *    exploiting the same plugin. Janus will take care of all the WebRTC-related
2744
 *    stuff (ICE, DTLS, SRTP), which means that on the SIP side it will
2745
 *    be plain RTP only, much easier and lighter to handle for legacy
2746
 *    implementations. SDES-SRTP is also supported on the SIP side in case
2747
 *    it is required.\n\n
2748
 *    .
2749
 * -# <b>Can I use existing SIP stacks (e.g., JsSIP) with Janus?</b>\n
2750
 *    .
2751
 *    Janus uses a custom JSON-based protocol for all the communication
2752
 *    between web users and plugins in the gateway, so no, that's not
2753
 *    possible right now. While there are some controls that give you access
2754
 *    to some of the SIP details (e.g., requesting SRTP negotiation or injecting
2755
 *    custom headers), the SIP plugin in Janus only exposes some very
2756
 *    high level information to web users (e.g., registration failed/succeeded,
2757
 *    incoming call, decline, hangup, etc.), without delving in any SIP-related
2758
 *    detail, which is instead completely demanded to the server-side plugin
2759
 *    itself. This ensures that web users can take advantage of SIP functionality
2760
 *    in an easy way, without having to worry about the details and complexity
2761
 *    of SIP within JavaScript.\n\n
2762
 *    .
2763
 * -# <b>Does Janus support transcoding?</b>\n
2764
 *    .
2765
 *    Janus is a simple intermediary between WebRTC users and server-side
2766
 *    plugins providing application logic, so no, it doesn't provide any
2767
 *    transcoding functionality per-se. If transcoding is needed, this is
2768
 *    supposed to be implemented within plugins themselves. That said,
2769
 *    apart from the AudioBridge plugin which acts as an audio MCU,
2770
 *    none of the plugins we provide out-of the box does transcoding,
2771
 *    since we wanted the implementation to be lightweight and besides
2772
 *    there are several existing tools and third-party implementations that
2773
 *    could be leveraged for the purpose.\n\n
2774
 *    .
2775
 * -# <b>Does Janus support recording?</b>\n
2776
 *    .
2777
 *    Yep! The Janus core provides an integrated way of recording all
2778
 *    the media streams that go through it, whether it's audio, video or
2779
 *    data, and almost all stock plugins do exploit it one way or another.
2780
 *    Recording is implemented as a structured dump of all RTP and data
2781
 *    files exactly as they were transmitted or sent: as such, no manipulation
2782
 *    is done while recording, and all post-processing is demanded to
2783
 *    an external tool. For more information on this, check the
2784
 *    <a href="https://janus.conf.meetecho.com/docs/janus-pp-rec_8c.html#details">documentation</a>.\n\n
2785
 *    .
2786
 * -# <b>Can I use WebSockets instead of plain HTTP to interact with Janus?</b>\n
2787
 *    .
2788
 *    Since version \c 0.0.4, you can! At first we chose a REST-based plain HTTP communication
2789
 *    for a simple reason: we noticed that there were some scenarios (e.g.,
2790
 *    client firewalls) where websockets wouldn't work, even though WebRTC
2791
 *    did. To improve the chances of success in the communication, we
2792
 *    then chose this simpler approach with respect to signalling. Besides,
2793
 *    plain HTTP is much easier to proxy and/or place behind frontends
2794
 *    like Apache HTTPD or nginx than WebSockets, another aspect that
2795
 *    played a decisive role in our decision, as we were also very interested
2796
 *    in making the integration of Janus in heterogeneous environments
2797
 *    as easy as possible. That said, WebSockets also provide substantial
2798
 *    benefits when compared to plain HTTP, and definitely make life easier to
2799
 *    server side integrators as well, e.g., in terms of overhead and use of
2800
 *    resources. For more information, check the \ref WS page. \n\n
2801
 *    .
2802
 * -# <b>Can I use RabbitMQ instead of HTTP/WebSockets to interact with Janus?</b>\n
2803
 *    .
2804
 *    Since version \c 0.0.6, you can! This is a feature that several
2805
 *    developers asked for, especially those that are interested in wrapping
2806
 *    the Janus API on the server side, and implement the communication
2807
 *    on the client side their own way. Specificaly, Janus now supports
2808
 *    RabbitMQ based messaging as an alternative "transport" for API
2809
 *    requests, responses and notifications, meaning it can be used with
2810
 *    or without HTTP and WebSockets, depending on your requirements.
2811
 *    For more information, check the \ref rabbit page. \n\n
2812
 *    .
2813
 * -# <b>Can I use Unix Sockets instead of HTTP/WebSockets/RabbitMQ to interact with Janus?</b>\n
2814
 *    .
2815
 *    Since version \c 0.2.1, you can! More specifically, you can use a
2816
 *    \c SOCK_SEQPACKET or a \c SOCK_DGRAM socket to control a Janus instance.
2817
 *    Notice that this feature is only available when installing Janus on a Linux machine.
2818
 *    For more information, check the \ref unix page. \n\n
2819
 *    .
2820
 * -# <b>Can I use MQTT instead of HTTP/WebSockets/RabbitMQ/Unix Sockets to interact with Janus?</b>\n
2821
 *    .
2822
 *    Since version \c 0.2.1, you can! This was a very welcome contribution by
2823
 *    a Janus user, as it makes it even easier to have Janus interact with IoT deployments.
2824
 *    For more information, check the \ref mqtt page. \n\n
2825
 *    .
2826
 * -# <b>What about \<my favourite control protocol\> instead?</b>\n
2827
 *    .
2828
 *    Since version \c 0.1.0, the transports for the Janus API have been made
2829
 *    modular. This means that, assuming a transport plugin implementing
2830
 *    support for your favourite protocol has been made available, you
2831
 *    can just add it to the Janus transport modules folder and it should
2832
 *    work. If no plugin has been implemented, you may even want to do so
2833
 *    yourself, or ask for ours or others help.\n\n
2834
 *    .
2835
 * -# <b>I've launched Janus, how do I try the demos?</b>\n
2836
 *    .
2837
 *    The demos are available in the \c html folder in the project. That
2838
 *    said, the integrated web server in Janus does not serve static files
2839
 *    as well, so you'll have to make them available using a different
2840
 *    webserver. Details about how to deploy Janus are provided in
2841
 *    \ref deploy.\n\n
2842
 *    .
2843
 * -# <b>I'm trying the demos, but I get "Janus down" or certificate errors!</b>\n
2844
 *    .
2845
 *    Again, make sure you've read and are following the instructions on how to
2846
 *    effectively deploy Janus in \ref deploy. Most likely you're either trying
2847
 *    to open the WebRTC demos using HTTP instead of HTTPS (something that
2848
 *    browsers will not allow, if not on localhost for testing), trying
2849
 *    to contact Janus via an insecure protocol through a secure page, or
2850
 *    using an insecure certificate for Janus itself. All of these problems
2851
 *    are explained and solved easily in the \ref deploy documentation.\n\n
2852
 *    .
2853
 * -# <b>Can I use Janus with node.js or other frameworks?</b>\n
2854
 *    .
2855
 *    Not natively, but since interaction with Janus is demanded to
2856
 *    a JSON based communication transported on a network protocol (HTTP,
2857
 *    WebSockets, RabbitMQ and others), this can be abstracted quite easily
2858
 *    in several different ways. A common approach is implementing the Janus
2859
 *    API in a server-side application, so that you handle users your own way
2860
 *    and with your own API, while controlling Janus as a media server yourself
2861
 *    by wrapping its API. Check the \ref resources documentation page
2862
 *    for a list of Janus API wrappers in different programming languages
2863
 *    that ou can use within your application
2864
 *    to control a Janus instance from there instead of the browser. Should
2865
 *    you decide to write your own Janus API wrapper, don't hesitate to let
2866
 *    us know so that we can advertise yours there too!\n\n
2867
 *    .
2868
 * -# <b>How do I monitor/manage my Janus instance?</b>\n
2869
 *    Since version \c 0.2.2 there are a couple of different ways you can do
2870
 *    that. The first and most immediate one is making use of the Admin API,
2871
 *    which you can find documented in the \ref admin page. It is a request/response
2872
 *    protocol that can be used to poll information on existing sessions and
2873
 *    handles, and which also provides a lot of useful WebRTC-related information
2874
 *    on PeerConnections Janus is managing. You can also find a very useful
2875
 *    <a href="http://www.meetecho.com/blog/understanding-the-janus-admin-api">blog post</a>
2876
 *    where we describe in detail how the Admin API can be used to investigate issues. \n\n
2877
 *    A more recent, and potentially much more powerful, addition to Janus
2878
 *    are the Event Handlers. Unlike the Admin API, which is query-based,
2879
 *    Event Handlers provide a mechanism to dynamically feed you with real-time
2880
 *    and live data on whatever is happening within Janus, whether it's the
2881
 *    core or any of the plugins. You can find more information, along with
2882
 *    an example of how to receive such events, in the
2883
 *    <a href="https://github.com/meetecho/janus-gateway/pull/536">pull request</a>
2884
 *    page from where this effort was merged. More guidelines and implementations
2885
 *    will definitely follow. \n\n
2886
 *    .
2887
 * -# <b>I want to write my own plugin, where do I start?</b>\n
2888
 *    .
2889
 *    Great! Depending on the kind of plugin you want to implement (application plugin,
2890
 *    transport plugin, event handler plugin), some of the details may change,
2891
 *    but the concept is typically the same. There are APIs you can refer to,
2892
 *    documented in \ref pluginapi , \ref transportapi and \ref eventhandlerapi.
2893
 *    The existing plugins are also an excellent way to start to get
2894
 *    comfortable with the API: a good starting point may be the Echo Test
2895
 *    plugin, which is a very simple and barebone implementation that
2896
 *    simply bounces back whatever it is sent, and also involves some
2897
 *    rough application logic to determine its behaviour (e.g., messages
2898
 *    coming from web users that selectively enable or disable video).
2899
 *    You may want to check third-party plugins as well in the \ref resources
2900
 *    as well, as they'll give you an idea of how other users did the same.
2901
 *    If you need any help with this, feel free to ask for help on the Google group:
2902
 *    we're always excited whenever new Janus plugins are realized!\n\n
2903
 *    .
2904
 * -# <b>I'm using the VideoRoom plugin and, when several users are handled, I get
2905
 *    a "Too many open files" errors and Janus crashes</b>\n
2906
 *    .
2907
 *    As all applications on Linux environments, Janus is bound to the
2908
 *    constraints imposed by the OS and/or the user. One of these constraints
2909
 *    is related to how many file descriptors the application, or all the
2910
 *    applications, can open. On several distributions this number is, by
2911
 *    default, quite low, which can cause the issue you experienced. This
2912
 *    value, together with others, can be modified, per-user or for all users,
2913
 *    using the \c ulimit application. For a simple and quick way to handle
2914
 *    this refer to the guide provided by the MongoDB developers:
2915
 *    http://docs.mongodb.org/manual/reference/ulimit/ \n\n
2916
 *    .
2917
 * -# <b>When I enable the HTTPS web server in Janus, the CPU goes crazy</b>\n
2918
 *    .
2919
 *    As discussed in a recent <a href="https://groups.google.com/forum/?pli=1#!topic/meetecho-janus/lD8A0VqXsNs">post</a>
2920
 *    on our Google group, this is caused by an occasional problem within
2921
 *    libmicrohttpd, the library we use to implement an embedded web server
2922
 *    in Janus. This is not deterministic, as the high CPU usage does happen
2923
 *    on some distributions (e.g., Ubuntu 12.04), while it doesn't on
2924
 *    others (e.g., Ubuntu 14.04). Anyway, this only can happen if you enable
2925
 *    HTTPS support within Janus itself: you can still have a safe HTTPS
2926
 *    usage with Janus if you deploy it behind a frontend (e.g., Apache HTTPD)
2927
 *    that takes care of this on its behalf. Refer to the \ref deploy section
2928
 *    for more details about this.\n\n
2929
 *    .
2930
 * -# <b>I enabled TURN in the Janus configuration, but my clients behind a firewall can't connect</b>\n
2931
 *    .
2932
 *    As explained in the \c janus.cfg documentation, the TURN settings you
2933
 *    configure there refer to Janus \b itself, \b not the clients that make use
2934
 *    of its services. This means that, whether you configure a static TURN
2935
 *    server and the related credentials, or the REST API client stack to
2936
 *    retrieve them dynamically, you're asking Janus to gather relay candidates
2937
 *    for ITSELF. This is only useful if you know that your Janus instance
2938
 *    will not be deployed on a public address (as it usually will) but will
2939
 *    instead potentially sit behind a restrictive component like a firewall,
2940
 *    or if you simply want to limit the number of open ports and so force
2941
 *    all media traffic to go through the TURN server port alone.\n\n
2942
 *    If you want your clients to gather relay candidates, instead, this
2943
 *    needs to be done on the client side (e.g., in JavaScript, if your
2944
 *    clients are web applications). If you're using our \ref JS check
2945
 *    the \c echotest.js code, which has a commented portion that explains
2946
 *    how to provide one or more TURN servers to make use of. If you're
2947
 *    handling the WebRTC-related stuff on your own and are contacting
2948
 *    Janus some other way, please refer to the related way of specifying
2949
 *    STUN and TURN servers instead.\n\n
2950
 *    .
2951
 * -# <b>Is there any benchmark on Janus performances?</b>\n
2952
 *    .
2953
 *    Benchmarking Janus is not an easy task, especially if we consider
2954
 *    its general purpose nature. In fact, Janus by itself does not much
2955
 *    more than negotiating WebRTC PeerConnections and relaying frames
2956
 *    around, while most of the application login is in the modules. As
2957
 *    you can imagine, different modules may have very different requirements
2958
 *    and impact on the performances. For instance, the Echo Test is probably
2959
 *    much lighter than the Video MCU, even if they're handling the same
2960
 *    number of users. This means that such a benchmarking does not have
2961
 *    much sense unless you contextualise the scenarios.\n\n
2962
 *    You can find some results on tests we made ourselves in a couple of
2963
 *    publications we wrote and available
2964
 *    <a href="http://janus.conf.meetecho.com/citeus">here</a>. One of those
2965
 *    introduces a WebRTC stress testing tool we implemented called Jattack,
2966
 *    for which a <a href="https://www.youtube.com/watch?v=UwNq8p0m1js">video of the presentation</a>
2967
 *    is available. You can find some more details and considerations in an older
2968
 *    <a href="https://groups.google.com/forum/?pli=1#!topic/meetecho-janus/ydGcbMt7IX0">post</a>
2969
 *    on our Google group too.\n\n
2970
 *    .
2971
 * -# <b>How do I scale Janus?</b>\n
2972
 *    This question is way too generic to answer here. As explained in the previous
2973
 *    point, Janus is not an easily measurable entity, as it very much depends
2974
 *    on which of the plugins you're involving in the scenarios that interest you
2975
 *    and how. The same considerations also apply to scaling the scenario you
2976
 *    implemented, as different plugins may require different approaches to
2977
 *    do that. \n\n
2978
 *    In general, Janus does not have any built-in multi-tenant support. Each
2979
 *    Janus instance is conceived to be standalone, and works by itself. That
2980
 *    said, there are different ways in which you can implement scalability in
2981
 *    your service. One of them is implementing a wrapper/controller application
2982
 *    that is in charge of multiple Janus instances, so that it can distribute
2983
 *    the load depending on the requests. If the scenario allows for it,
2984
 *    you can also mix concepts from different plugins on different Janus
2985
 *    instances (e.g., use the RTP forwardiing feature of the VideoRoom plugin
2986
 *    to make the same VideoRoom publisher available as a Streaming mountpoint
2987
 *    on other Janus machines). Anyway, as explained each application may have
2988
 *    very different requirements when it comes to scalability. \n\n
2989
 *    Should you be interested in implementing scalability in your application and
2990
 *    need help, <a href="https://janus.conf.meetecho.com/support">contact us</a>.\n\n
2991
 *    .
2992
 * -# <b>Can you implement a feature/plugin/application I want?</b>\n
2993
 *    .
2994
 *    We're constantly working on new features and on improving what's
2995
 *    already there, and we do love feedback from users. That said, we're
2996
 *    a small team and we do have to pay our bills, so we always have to
2997
 *    reserve our resources wisely. If there's a feature you'd like to
2998
 *    see implemented, tell us on our Google group, and discuss it with
2999
 *    other users: it may be on our schedule, or someone else may be
3000
 *    already working on it to contribute it back to the project. You
3001
 *    may even want to try and build it yourself and help us make Janus
3002
 *    even better! \n\n
3003
 *    If you really need something that isn't there, you may also want to consider
3004
 *    <a href="https://janus.conf.meetecho.com/support">contacting us</a>
3005
 *    for a sponsored development or consulting.\n\n
3006
 *    .
3007
 * -# <b>I want to learn more on Janus!</b>\n
3008
 *    That's great! The first obvious suggestion is of course to carefully
3009
 *    read the documentation here: we worked hard on it and are constantly
3010
 *    expanding it, so it should always be the first source of information
3011
 *    whenever in doubt. We have a great Google group as well where the
3012
 *    <a href="https://groups.google.com/forum/#!forum/meetecho-janus">community</a>
3013
 *    shares questions, data and more everyday, so make sure you join too! \n\n
3014
 *    We also provide training on Janus and WebRTC in general, so if interested
3015
 *    just <a href="https://janus.conf.meetecho.com/support">contact us</a>.\n\n
3016
 *    .
3017
 */
3018

    
3019
/*! \defgroup core Core
3020
 * \brief Core implementation of the gateway
3021
 * \details The Janus WebRTC Gateway is founded on a core that glues the
3022
 * involved parts together. The main code is janus.c that implements
3023
 * the logic behind the gateway itself: it implements the web server that
3024
 * interacts with browsers, and handles sessions with them. This includes
3025
 * taking care of media signalling and negotiation, and bridging peers
3026
 * with available plugins.
3027
 */
3028

    
3029
/*! \defgroup protocols Protocols
3030
 * \brief Implementations of the WebRTC protocols
3031
 * \details The WebRTC specification (WEBRTC/RTCWEB) currently mandates
3032
 * the usage of a few protocols and techniques. The code in this group
3033
 * takes care of them all (SDP, ICE, DTLS-SRTP, RTP/RTCP). 
3034
 * \ingroup core
3035
 */
3036

    
3037
/*! \defgroup plugins Plugins
3038
 * \brief Gateway plugins available out of the box
3039
 * \details In order to showcase how different plugins can implement
3040
 * completely different applications on top of the Janus core, a few
3041
 * plugin implementations are provided out of the box. The API for
3042
 * writing a new plugin is specified in the \ref pluginapi section.
3043
 */
3044

    
3045
/*! \defgroup pluginapi Plugin API
3046
 * \brief Plugin API (aka, how to write your own plugin)
3047
 * \details The plugin.h header specifies the API a plugin needs to
3048
 * implement and make available in order to be used by the gateway and
3049
 * exposed to browsers. 
3050
 * \ingroup plugins
3051
 */
3052

    
3053
/*! \defgroup transports Transports
3054
 * \brief Transport plugins available out of the box
3055
 * \details In order to showcase how different transport plugins can implement
3056
 * support for the Janus API over different transport protocols, a few
3057
 * plugin implementations are provided out of the box. The API for
3058
 * writing a new plugin is specified in the \ref transportapi section.
3059
 */
3060

    
3061
/*! \defgroup transportapi Transport API
3062
 * \brief Transport API (aka, how to write your own transport plugin)
3063
 * \details The transport.h header specifies the API a plugin needs to
3064
 * implement and make available in order to expose a new transport protocol
3065
 * that can be used by the gateway for talking the Janus API.
3066
 * \ingroup transports
3067
 */
3068

    
3069
/*! \defgroup eventhandlers Event Handlers
3070
 * \brief Event handler plugins available out of the box
3071
 * \details In order to showcase how different plugins can handle events
3072
 * originated by the Janus core or any of its plugins, a sample plugin
3073
 * implementation is provided out of the box. The API for writing a new
3074
 * event handler plugin is specified in the \ref eventhandlerapi section.
3075
 */
3076

    
3077
/*! \defgroup eventhandlerapi Event Handler API
3078
 * \brief Event Handler API (aka, how to write your own event handler plugin)
3079
 * \details The eventhandler.h header specifies the API a plugin needs to
3080
 * implement and make available in order to receive events from Janus.
3081
 * \ingroup eventhandlers
3082
 */
3083

    
3084
/*! \defgroup tools Tools and utilities
3085
 * \brief Tools and utilities
3086
 * \details Set of simple tools and utilities that may be of help when
3087
 * used in conjunction with Janus. 
3088
 */
3089

    
3090
/*! \defgroup postprocessing Recordings post-processing utility
3091
 * \brief Recordings post-processing utility
3092
 * \details This simple utility (janus-pp-rec.c) allows you to
3093
 * post-process recordings generated by the janus_recorder helper (e.g.,
3094
 * in the Video MCU plugin). 
3095
 * \ingroup tools
3096
 */