Statistics
| Branch: | Revision:

janus-gateway / mainpage.dox @ e67b71f9

History | View | Annotate | Download (134 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
 * - \c ipv6: whether IPv6 candidates should ge gathered or not;
198
 * - \c withCredentials: whether the \c withCredentials property of XHR requests
199
 * should be enabled or not (false by default, and only valid when using HTTP
200
 * as a transport, ignored for WebSockets);
201
 * - \c max_poll_events: the number of events that should be returned when polling;
202
 * the default is 1 (polling returns an object), passing a higher number will
203
 * have the backend return an array of objects instead (again, only valid for
204
 HTTP usage as this is strictly related to long polling, ignored for WebSockets);
205
 * - \c destroyOnUnload: whether we should destroy automatically try and
206
 * destroy this session via Janus API when \c onbeforeunload is called (true by default);
207
 * - \c token , \c apisecret: optional parameters only needed in case you're \ref auth ;
208
 * - a set of callbacks to be notified about events, namely:
209
 * 		- \c success: the session was successfully created and is ready to be used;
210
 * 		- \c error: the session was NOT successfully created;
211
 * 		- \c destroyed: the session was destroyed and can't be used any more.
212
 *
213
 * These properties and callbacks are passed to the method as properties
214
 * of a single parameter object: that is, the \c Janus constructor takes a
215
 * single parameter, which although acts as a container for all the available
216
 * options. The \c success callback is where you tipically start your application
217
 * logic, e.g., attaching the peer to a plugin and start a media session.
218
 *
219
 * Here's an example:
220
 *
221
 \verbatim
222
var janus = new Janus(
223
	{
224
		server: 'http://yourserver:8088/janus',
225
		success: function() {
226
			// Done! attach to plugin XYZ
227
		},
228
		error: function(cause) {
229
			// Error, can't go on...
230
		},
231
		destroyed: function() {
232
			// I should get rid of this
233
		}
234
	});
235
 \endverbatim
236
 *
237
 * As anticipated, the server may be a specific address, e.g.:
238
 *
239
 \verbatim
240
var janus = new Janus(
241
	{
242
		server: 'http://yourserver:8088/janus',
243
				// or
244
		server: 'ws://yourserver:8188/',
245
		[..]
246
 \endverbatim
247
 *
248
 * or an array of addresses. Such an array can be especially useful if
249
 * you want the library to first check if the WebSockets server is
250
 * reachable and, if not, fallback to plain HTTP, or just to provide
251
 * a link multiple instances to try for failover. This is an example of
252
 * how to pass a 'try websockets and fallback to HTTP' array:
253
 *
254
 \verbatim
255
var janus = new Janus(
256
	{
257
		server: ['ws://yourserver:8188/','http://yourserver:8088/janus'],
258
		[..]
259
 \endverbatim
260
 *
261
 * Once created, this object represents your session with the gateway.
262
 * you can interact with a \c Janus object in several different ways.
263
 * In particular, the following properties and methods are defined:
264
 *
265
 * - \c getServer(): returns the address of the gateway;
266
 * - \c isConnected(): returns \c true if the Janus instance is connected
267
 * to the gateway, \c false otherwise;
268
 * - \c getSessionId(): returns the unique gateway session identifier;
269
 * - \c attach(parameters): attaches the session to a plugin, creating an handle;
270
 * more handles to the same or different plugins can be created at the same time;
271
 * - \c destroy(parameters): destroys the session with the gateway, and closes
272
 * all the handles (and related PeerConnections) the session may have with any plugin as well.
273
 *
274
 * The most important property is obviously the \c attach() method, as
275
 * it's what will allow you to exploit the features of a plugin to manipulate
276
 * the media sent and/or received by a PeerConnection in your web page.
277
 * This method will create a plugin handle you can use for the purpose,
278
 * for which you can configure properties and callbacks when calling the
279
 * \c attach() method itself. As for the \c Janus constructor, the \c attach()
280
 * method takes a single parameter that can contain any of the following
281
 * properties and callbacks:
282
 *
283
 * - \c plugin: the unique package name of the plugin (e.g., \c janus.plugin.echotest );
284
 * - \c opaqueId: an optional opaque string meaningful to your application (e.g., to map all the handles of the same user);
285
 * - a set of callbacks to be notified about events, namely:
286
 * 		- \c success: the handle was successfully created and is ready to be used;
287
 * 		- \c error: the handle was NOT successfully created;
288
 * 		- \c consentDialog: this callback is triggered just before \c getUserMedia is called
289
 * (parameter=<b>true</b>) and after it is completed (parameter=<b>false</b>); this means it can
290
 * be used to modify the UI accordingly, e.g., to prompt the user about the need to accept the device access consent requests;
291
 * 		- \c webrtcState: this callback is triggered with a <b>true</b> value
292
 * when the PeerConnection associated to a handle becomes active (so ICE, DTLS and
293
 * everything else succeeded) from the Janus perspective, while <b>false</b> is
294
 * triggered when the PeerConnection goes down instead; useful to figure out
295
 * when WebRTC is actually up and running between you and Janus (e.g., to notify
296
 * a user they're actually now active in a conference);
297
 * 		- \c mediaState: this callback is triggered when Janus starts or stops
298
 * receiving your media: for instance, a \c mediaState with type=<b>audio</b> and
299
 * on=<b>true</b> means Janus started receiving your audio stream (or started
300
 * getting them again after a pause of more than a second); a \c mediaState with
301
 * type=<b>video</b> and on=<b>false</b> means Janus hasn't received any video
302
 * from you in the last second, after a start was detected before; useful to
303
 * figure out when Janus actually started handling your media, or to detect
304
 * problems on the media path (e.g., media never started, or stopped at some time);
305
 * 		- \c slowLink: this callback is triggered when Janus reports trouble
306
 * either sending or receiving media on the specified PeerConnection, typically
307
 * as a consequence of too many NACKs received from/sent to the user in the
308
 * last second: for instance, a \c slowLink with uplink=<b>true</b> means
309
 * you notified several missing packets from Janus, while uplink=<b>false</b>
310
 * means Janus is not receiving all your packets; useful to figure out when
311
 * there are problems on the media path (e.g., excessive loss), in order to
312
 * possibly react accordingly (e.g., decrease the bitrate if most of our
313
 * packets are getting lost);
314
 * 		- \c onmessage: a message/event has been received from the plugin;
315
 * 		- \c onlocalstream: a local \c MediaStream is available and ready to be displayed;
316
 * 		- \c onremotestream: a remote \c MediaStream is available and ready to be displayed;
317
 * 		- \c ondataopen: a Data Channel is available and ready to be used;
318
 * 		- \c ondata: data has been received through the Data Channel;
319
 * 		- \c oncleanup: the WebRTC PeerConnection with the plugin was closed;
320
 * 		- \c detached: the plugin handle has been detached by the plugin itself,
321
 * and so should not be used anymore.
322
 *
323
 * Here's an example:
324
 *
325
 \verbatim
326
// Attach to echo test plugin, using the previously created janus instance
327
janus.attach(
328
	{
329
		plugin: "janus.plugin.echotest",
330
		success: function(pluginHandle) {
331
			// Plugin attached! 'pluginHandle' is our handle
332
		},
333
		error: function(cause) {
334
			// Couldn't attach to the plugin
335
		},
336
		consentDialog: function(on) {
337
			// e.g., Darken the screen if on=true (getUserMedia incoming), restore it otherwise
338
		},
339
		onmessage: function(msg, jsep) {
340
			// We got a message/event (msg) from the plugin
341
			// If jsep is not null, this involves a WebRTC negotiation
342
		},
343
		onlocalstream: function(stream) {
344
			// We have a local stream (getUserMedia worked!) to display
345
		},
346
		onremotestream: function(stream) {
347
			// We have a remote stream (working PeerConnection!) to display
348
		},
349
		oncleanup: function() {
350
			// PeerConnection with the plugin closed, clean the UI
351
			// The plugin handle is still valid so we can create a new one
352
		},
353
		detached: function() {
354
			// Connection with the plugin closed, get rid of its features
355
			// The plugin handle is not valid anymore
356
		}
357
	});
358
 \endverbatim
359
 *
360
 * So the \c attach() method allows you to attach to a plugin, and specify 
361
 * the callbacks to invoke when anything relevant happens in this interaction.
362
 * To actively interact with the plugin, you can use the \c Handle object
363
 * that is returned by the \c success callback (pluginHandle in the example).
364
 *
365
 * This \c Handle object has several methods you can use to interact with
366
 * the plugin or check the state of the session handle:
367
 *
368
 * - \c getId(): returns the unique handle identifier;
369
 * - \c getPlugin(): returns the unique package name of the attached plugin;
370
 * - \c send(parameters): sends a message (with or without a jsep to
371
 * negotiate a PeerConnection) to the plugin;
372
 * - \c createOffer(callbacks): asks the library to create a WebRTC compliant OFFER;
373
 * - \c createAnswer(callbacks): asks the library to create a WebRTC compliant ANSWER;
374
 * - \c handleRemoteJsep(callbacks): asks the library to handle an incoming WebRTC compliant session description;
375
 * - \c dtmf(parameters): sends a DTMF tone on the PeerConnection;
376
 * - \c data(parameters): sends data through the Data Channel, if available;
377
 * - \c getBitrate(): gets a verbose description of the currently received stream bitrate;
378
 * - \c hangup(sendRequest): tells the library to close the PeerConnection; if the optional \c sendRequest argument is
379
 * set to \c true, then a \c hangup Janus API request is sent to Janus as well (disabled by default, Janus can usually
380
 * figure this out via DTLS alerts and the like but it may be useful to enable it sometimes);
381
 * - \c detach(parameters): detaches from the plugin and destroys the handle, tearing
382
 * down the related PeerConnection if it exists.
383
 *
384
 * While the \c Handle API may look complex, it's actually quite straightforward
385
 * once you get the concept. The only step that may require a little more
386
 * effort to understand is the PeerConnection negotiation, but again, if
387
 * you're familiar with the WebRTC API, the \c Handle actually makes it
388
 * a lot easier.
389
 *
390
 * The idea behind it's usage is the following:
391
 *
392
 * -# you use \c attach() to create a \c Handle object;
393
 * -# in the \c success callback, your application logic can kick in: you may
394
 * want to send a message to the plugin (<code>send({msg})</code>), negotiate
395
 * a PeerConnection with the plugin right away ( \c createOffer followed
396
 * by a <code>send({msg, jsep})</code>) or wait for something to happen to do anything;
397
 * -# the \c onmessage callback tells you when you've got messages from the plugin;
398
 * if the \c jsep parameter is not null, just pass it to the library, which will take
399
 * care of it for you; if it's an \b OFFER use \c createAnswer (followed by a
400
 * <code>send({msg, jsep})</code> to close the loop with the plugin), otherwise use
401
 * \c handleRemoteJsep ;
402
 * -# whether you took the initiative to set up a PeerConnection or the plugin did,
403
 * the \c onlocalstream and/or the \c onremotestream callbacks will provide
404
 * you with a stream you can display in your page;
405
 * -# each plugin may allow you to manipulate what should flow through the
406
 * PeerConnection channel: the \c send method and \c onmessage callback
407
 * will allow you to handle this interaction (e.g., to tell the plugin
408
 * to mute your stream, or to be notified about someone joining a virtual room),
409
 * while the \c ondata callback is triggered whenever data is received
410
 * on the Data Channel, if available (and the \c ondataopen callback
411
 * will tell you when a Data Channel is actually available). 
412
 *
413
 * The following paragraphs will delve a bit deeper in the negotiation
414
 * mechanism provided by the \c Handle API, in particular describing
415
 * the properties and callbacks that may be involved. To follow the approach
416
 * outlined by the W3C WebRTC API, this negotiation mechanism is heavily
417
 * based on asynchronous methods as well.
418
 *
419
 * - \c createOffer takes a single parameter, that can contain any of the
420
 * following properties and callbacks:
421
 *   - \c media: you can use this property to tell the library which media (audio/video/data)
422
 * you're interested in, and whether you're going to send and/or receive any of them; by default
423
 * audio and video are enabled in both directions, while the Data Channels are disabled;
424
 * this option is an object that can take any of the following properties:
425
 *     - \c audioSend: \c true/false (do or do not send audio);
426
 *     - \c audioRecv: \c true/false (do or do not receive audio);
427
 *     - \c audio: \c true/false (do or do not send \b and receive audio, takes precedence on the above);
428
 *     - \c audio: object with \c deviceId property (specify ID of audio device to capture, takes precedence on the above;
429
 * devices list can be accessed with \c Janus.listDevices(callback) );
430
 *     - \c videoSend: \c true/false (do or do not send video);
431
 *     - \c videoRecv: \c true/false (do or do not receive video);
432
 *     - \c video: \c true/false (do or do not send \b and receive video, takes precedence on the above);
433
 *     - \c video: \c "lowres"/"lowres-16:9"/"stdres"/"stdres-16:9"/"hires"/"hires-16:9"
434
 * (send a 320x240/320x180/640x480/640x360/1280x720 video, takes precedence on the above; default is \c "stdres" )
435
 * this property will affect the resulting getUserMedia that the library will issue; please
436
 * notice that Firefox doesn't support the \c "16:9" variants, which will fallback
437
 * to the ones; besides, \c "hires" and \c "hires-16:9" are currently synonymous, as
438
 * there's no 4:3 high resolution constraint as of now;
439
 *     - \c video: \c "screen" (use screensharing for video, disables audio, takes precedence on both audio and video);
440
 *     - \c video: object with \c deviceId , \c width and/or \c height properties (specify ID of video device to capture
441
 * and optionally resolution to use, takes precedence on the above; devices list can be accessed with \c Janus.listDevices(callback) );
442
 *     - \c data: \c true/false (do or do not use Data Channels, default is false)
443
 *     - \c failIfNoAudio: \c true/false (whether a getUserMedia should fail if audio send is asked, but no audio device is available, default is false)
444
 *     - \c failIfNoVideo: \c true/false (whether a getUserMedia should fail if video send is asked, but no video device is available, default is false)
445
 *   - \c trickle: \c true/false, to tell the library whether you want
446
 * Trickle ICE to be used (true, the default) or not (false);
447
 *   - \c stream: optional, only to be passed in case you obtained a MediaStream object yourself with a \c getUserMedia
448
 * request, and that you want the library to use instead of having it get one by itself (makes
449
 * the \c media property useless, as it won't be read for accessing any device);
450
 *   - a set of callbacks to be notified about the result, namely:
451
 *     - \c success: the session description was created (attached as a parameter) and is ready to be sent to the plugin; 
452
 *     - \c error: the session description was NOT successfully created;
453
 * - \c createAnswer takes the same options as createOffer, but requires
454
 * an additional one as part of the single parameter argument:
455
 *   - \c jsep: the session description sent by the plugin (e.g., as received
456
 * in an \c onmessage callback) as its OFFER.
457
 *
458
 * Whether you use \c createOffer or \c createAnswer depending on the scenario,
459
 * you should end up with a valid \c jsep object returned in the \c success
460
 * callback. You can attach this \c jsep object to a message in a \c send request
461
 * to pass it to the plugin, and have the gateway negotiate a PeerConnection
462
 * with your application.
463
 *
464
 * Here's an example of how to use \c createOffer, taken from the Echo Test demo page:
465
 *
466
 \verbatim
467
// Attach to echo test plugin
468
janus.attach(
469
	{
470
		plugin: "janus.plugin.echotest",
471
		success: function(pluginHandle) {
472
			// Negotiate WebRTC
473
			echotest = pluginHandle;
474
			var body = { "audio": true, "video": true };
475
			echotest.send({"message": body});
476
			echotest.createOffer(
477
				{
478
					// No media property provided: by default,
479
						// it's sendrecv for audio and video
480
					success: function(jsep) {
481
						// Got our SDP! Send our OFFER to the plugin
482
						echotest.send({"message": body, "jsep": jsep});
483
					},
484
					error: function(error) {
485
						// An error occurred...
486
					}
487
				});
488
		},
489
		[..]
490
		onmessage: function(msg, jsep) {
491
			// Handle msg, if needed, and check jsep
492
			if(jsep !== undefined && jsep !== null) {
493
				// We have the ANSWER from the plugin
494
				echotest.handleRemoteJsep({jsep: jsep});
495
			}
496
		},
497
		[..]
498
		onlocalstream: function(stream) {
499
			// Invoked after createOffer
500
			// This is our video
501
		},
502
		onremotestream: function(stream) {
503
			// Invoked after handleRemoteJsep has got us a PeerConnection
504
			// This is the remote video
505
		},
506
		[..]
507
  \endverbatim
508
 *
509
 * This, instead, is an example of how to use \c createAnswer, taken from the Streaming demo page:
510
 *
511
 \verbatim
512
// Attach to echo test plugin
513
janus.attach(
514
	{
515
		plugin: "janus.plugin.streaming",
516
		success: function(pluginHandle) {
517
			// Handle created
518
			streaming = pluginHandle;
519
			[..]
520
		},
521
		[..]
522
		onmessage: function(msg, jsep) {
523
			// Handle msg, if needed, and check jsep
524
			if(jsep !== undefined && jsep !== null) {
525
				// We have an OFFER from the plugin
526
				streaming.createAnswer(
527
					{
528
						// We attach the remote OFFER
529
						jsep: jsep,
530
						// We want recvonly audio/video
531
						media: { audioSend: false, videoSend: false },
532
						success: function(ourjsep) {
533
							// Got our SDP! Send our ANSWER to the plugin
534
							var body = { "request": "start" };
535
							streaming.send({"message": body, "jsep": ourjsep});
536
						},
537
						error: function(error) {
538
							// An error occurred...
539
						}
540
					});
541
			}
542
		},
543
		[..]
544
		onlocalstream: function(stream) {
545
			// This will NOT be invoked, we chose recvonly
546
		},
547
		onremotestream: function(stream) {
548
			// Invoked after send has got us a PeerConnection
549
			// This is the remote video
550
		},
551
		[..]
552
  \endverbatim
553
 *
554
 * Of course, these are just a couple of examples where the scenarios
555
 * assumed that one plugin would only receive (Echo Test) or generate
556
 * (Streaming) offers. A more complex example (e.g., a Video Call plugin)
557
 * would involve both, allowing you to either send offers to a plugin,
558
 * or receive some from them. Handling this is just a matter of checking
559
 * the \c type of the \c jsep object and reacting accordingly.
560
 *  
561
 * <hr>
562
 *
563
 * This is it! For more information about the API, have a look at the
564
 * demo pages that are available in the \b html folder in this package.
565
 *
566
 */
567

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

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

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

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

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

    
2162
[Service]
2163
Type=simple
2164
ExecStart=/opt/janus/bin/janus -o
2165
Restart=on-abnormal
2166
LimitNOFILE=65536
2167

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

    
2193
start on filesystem or runlevel [2345]
2194
stop on runlevel [!2345]
2195
limit nofile 50000 50000
2196
limit core unlimited unlimited
2197

    
2198
respawn
2199
respawn limit 10 5
2200

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

    
2220
### BEGIN INIT INFO
2221
# Provides:          Janus
2222
# Required-Start:    $remote_fs $syslog
2223
# Required-Stop:     $remote_fs $syslog
2224
# Default-Start:     2 3 4 5
2225
# Default-Stop:      0 1 6
2226
# Short-Description: Janus WebRTC gateway
2227
# Description:       Janus WebRTC gateway
2228
### END INIT INFO
2229

    
2230
DAEMON=/usr/bin/janus
2231
DAEMON_NAME=janus
2232

    
2233
# Add any command line options for your daemon here
2234
DAEMON_OPTS="-D -o"
2235

    
2236
# This next line determines what user the script runs as.
2237
# Root generally not recommended but necessary if you are using the Raspberry Pi GPIO from Python.
2238
DAEMON_USER=root
2239

    
2240
# The process ID of the script when it runs is stored here:
2241
PIDFILE=/var/run/$DAEMON_NAME.pid
2242

    
2243
. /lib/lsb/init-functions
2244

    
2245
do_start () {
2246
    log_daemon_msg "Starting system $DAEMON_NAME daemon"
2247
    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
2248
    log_end_msg $?
2249
}
2250
do_stop () {
2251
    log_daemon_msg "Stopping system $DAEMON_NAME daemon"
2252
    start-stop-daemon --stop --pidfile $PIDFILE --retry 10
2253
    log_end_msg $?
2254
}
2255

    
2256
case "$1" in
2257

    
2258
    start|stop)
2259
        do_${1}
2260
        ;;
2261

    
2262
    restart|reload|force-reload)
2263
        do_stop
2264
        do_start
2265
        ;;
2266

    
2267
    status)
2268
        status_of_proc "$DAEMON_NAME" "$DAEMON" && exit 0 || exit $?
2269
        ;;
2270

    
2271
    *)
2272
        echo "Usage: /etc/init.d/$DAEMON_NAME {start|stop|restart|status}"
2273
        exit 1
2274
        ;;
2275

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

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

    
2567

    
2568
/*! \page README README
2569
 *  \verbinclude README.md
2570
 */
2571

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

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

    
3032
/*! \defgroup core Core
3033
 * \brief Core implementation of the gateway
3034
 * \details The Janus WebRTC Gateway is founded on a core that glues the
3035
 * involved parts together. The main code is janus.c that implements
3036
 * the logic behind the gateway itself: it implements the web server that
3037
 * interacts with browsers, and handles sessions with them. This includes
3038
 * taking care of media signalling and negotiation, and bridging peers
3039
 * with available plugins.
3040
 */
3041

    
3042
/*! \defgroup protocols Protocols
3043
 * \brief Implementations of the WebRTC protocols
3044
 * \details The WebRTC specification (WEBRTC/RTCWEB) currently mandates
3045
 * the usage of a few protocols and techniques. The code in this group
3046
 * takes care of them all (SDP, ICE, DTLS-SRTP, RTP/RTCP). 
3047
 * \ingroup core
3048
 */
3049

    
3050
/*! \defgroup plugins Plugins
3051
 * \brief Gateway plugins available out of the box
3052
 * \details In order to showcase how different plugins can implement
3053
 * completely different applications on top of the Janus core, a few
3054
 * plugin implementations are provided out of the box. The API for
3055
 * writing a new plugin is specified in the \ref pluginapi section.
3056
 */
3057

    
3058
/*! \defgroup pluginapi Plugin API
3059
 * \brief Plugin API (aka, how to write your own plugin)
3060
 * \details The plugin.h header specifies the API a plugin needs to
3061
 * implement and make available in order to be used by the gateway and
3062
 * exposed to browsers. 
3063
 * \ingroup plugins
3064
 */
3065

    
3066
/*! \defgroup transports Transports
3067
 * \brief Transport plugins available out of the box
3068
 * \details In order to showcase how different transport plugins can implement
3069
 * support for the Janus API over different transport protocols, a few
3070
 * plugin implementations are provided out of the box. The API for
3071
 * writing a new plugin is specified in the \ref transportapi section.
3072
 */
3073

    
3074
/*! \defgroup transportapi Transport API
3075
 * \brief Transport API (aka, how to write your own transport plugin)
3076
 * \details The transport.h header specifies the API a plugin needs to
3077
 * implement and make available in order to expose a new transport protocol
3078
 * that can be used by the gateway for talking the Janus API.
3079
 * \ingroup transports
3080
 */
3081

    
3082
/*! \defgroup eventhandlers Event Handlers
3083
 * \brief Event handler plugins available out of the box
3084
 * \details In order to showcase how different plugins can handle events
3085
 * originated by the Janus core or any of its plugins, a sample plugin
3086
 * implementation is provided out of the box. The API for writing a new
3087
 * event handler plugin is specified in the \ref eventhandlerapi section.
3088
 */
3089

    
3090
/*! \defgroup eventhandlerapi Event Handler API
3091
 * \brief Event Handler API (aka, how to write your own event handler plugin)
3092
 * \details The eventhandler.h header specifies the API a plugin needs to
3093
 * implement and make available in order to receive events from Janus.
3094
 * \ingroup eventhandlers
3095
 */
3096

    
3097
/*! \defgroup tools Tools and utilities
3098
 * \brief Tools and utilities
3099
 * \details Set of simple tools and utilities that may be of help when
3100
 * used in conjunction with Janus. 
3101
 */
3102

    
3103
/*! \defgroup postprocessing Recordings post-processing utility
3104
 * \brief Recordings post-processing utility
3105
 * \details This simple utility (janus-pp-rec.c) allows you to
3106
 * post-process recordings generated by the janus_recorder helper (e.g.,
3107
 * in the Video MCU plugin). 
3108
 * \ingroup tools
3109
 */