Statistics
| Branch: | Revision:

janus-gateway / mainpage.dox @ f82a8605

History | View | Annotate | Download (113 KB)

1 be35facb meetecho
/*!
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 3d7320cb meetecho
 * checkout the \ref README information. A \ref FAQ page is also available.
11 be35facb meetecho
 *
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 54582a6a Lorenzo Miniero
 *
24 be35facb meetecho
 * 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 ead45815 meetecho
 * as well. A documentation on the available HTTP/WebSocket/RabbitMQ 
40
 * tranports and the HTTP/WebSocket JavaScript API to use the
41 be35facb meetecho
 * gateway and the plugins it makes available in your web application
42 ecb79ec6 meetecho
 * can be found in the \ref JS and \ref rest pages. If you're interested
43
 * in monitoring Janus resources, you can refer to the \ref admin page.
44 1f2c037b Lorenzo Miniero
 *
45
 * Finally, some information on how to deploy Janus and your web
46
 * applications that want to make use of it are provided in the \ref deploy
47
 * page. If you're interested in starting Janus as a service/daemon rather
48
 * than launching it normally, check the information provided in the
49 1e2606bf Lorenzo Miniero
 * \ref service page. Some additional \ref resources are also listed in
50
 * case you're interested in talking to Janus from different languages
51
 * and platforms.
52 be35facb meetecho
 *
53
 * This is only the first version of the gateway, and as such it is a bit
54
 * rough at the edges: there is definitely room for improvement, there are
55
 * bugs, limitations, and things that need to be done. For a quick glance
56
 * on the most relevant pending stuff check our \ref todo (and, if you're
57 9355a077 Lorenzo Miniero
 * willing to help on any of those, get in touch with us!). Make also
58
 * sure you read the \ref debug page for info on how you can help us
59
 * fixing issues you might encounter along the road.
60 be35facb meetecho
 *
61
 * \section copyright Copyright and author
62
 *
63
 * Janus WebRTC Gateway © 2014 <a href="http://www.meetecho.com/">Meetecho</a> (http://www.meetecho.com/)
64
 *
65
 * \author Lorenzo Miniero <lorenzo@meetecho.com> ( \ref CREDITS )
66
 *
67
 * \section license License
68
 * This program is free software, distributed under the terms of
69 be196340 meetecho
 * the GNU General Public License Version 3. For more details and licensing
70
 * options, including a commercial license, see the \ref COPYING page.
71 be35facb meetecho
 *
72
*/
73
74
/*! \page DEPS Dependencies
75
 *
76
 * The application and the plugins depend on the following open source
77
 * software and libraries, so make sure you install the related development
78
 * versions before attempting a compilation:
79
 *
80
 * - \b GLib: http://library.gnome.org/devel/glib/
81
 * - \b pkg-config: http://www.freedesktop.org/wiki/Software/pkg-config/
82
 * - \b gengetopt: http://www.gnu.org/software/gengetopt/ (command line)
83
 * - \b libini-config: https://fedorahosted.org/sssd/ (INI configurations)
84
 * - \b Jansson: http://www.digip.org/jansson/ (JSON)
85
 * - \b libnice: http://nice.freedesktop.org/wiki/ (ICE/STUN/TURN)
86
 * - \b OpenSSL: http://www.openssl.org/ (DTLS, at least v1.0.1e)
87 0b841733 Lorenzo Miniero
 * - \b libsrtp: https://github.com/cisco/libsrtp (SRTP, at least v1.5 suggested)
88 be35facb meetecho
 * - \b Sofia-SIP: http://sofia-sip.sourceforge.net/ (SDP parsing, SIP handling in the SIP plugin)
89 ead45815 meetecho
 * - \b usrsctp: http://code.google.com/p/sctp-refimpl/ (\c optional, Data Channels)
90 09ac2273 meetecho
 * - \b libmicrohttpd: http://www.gnu.org/software/libmicrohttpd/ (\c optional, Web server)
91 f500ae8e meetecho
 * - \b libwebsockets: https://libwebsockets.org/ (\c optional, WebSockets)
92 ff257ca1 meetecho
 * - \b rabbitmq-c: https://github.com/alanxz/rabbitmq-c (\c optional, v1.0.4, RabbitMQ)
93 ead45815 meetecho
 * - \b libopus: http://opus-codec.org/ (\c optional, only needed for the bridge plugin)
94
 * - \b libogg: http://xiph.org/ogg/ (\c optional, only needed for the voicemail plugin)
95 be35facb meetecho
 *
96
 */
97
98
/*! \page JS JavaScript API
99 09ac2273 meetecho
 * The gateway exposes, assuming the HTTP transport has been compiled, a
100
 * pseudo-RESTful interface, and optionally also WebSocket/RabbitMQ interfaces
101
 * as well, all of which based on JSON messages. These
102
 * interfaces are described in more detail in the \ref plainhttp \ref WS
103
 * and \ref rabbit documentation respectively, and all allow clients to
104 af40a682 meetecho
 * take advantage of the features provided by Janus and the functionality
105 09ac2273 meetecho
 * made available by its plugins. Considering most clients will be web browsers,
106
 * a common choice will be to rely on either the REST or the WebSockets
107
 * interface for the purpose. To make things easier for web
108 af40a682 meetecho
 * developers, a JavaScript library (\c janus.js) is available that can
109
 * make use of both interfaces using exactly the same API. This library
110 be35facb meetecho
 * eases the task of creating sessions with the gateway, attaching WebRTC
111
 * users to plugins, send and receive requests and events to the plugins
112
 * themselves and so on. For real examples of how this library can be
113
 * used, check the demos in the \b html folder of this package.
114 54582a6a Lorenzo Miniero
 *
115 47637450 meetecho
 * \note The current \c janus.js library makes use of jQuery (http://jquery.com/)
116
 * as a support. We're considering preparing versions that make use of
117
 * different libraries as well (e.g., Prototype, Dojo, Script.aculo.us, etc.)
118
 * in case your web application us based on something that cannot make use
119
 * of jQuery. Of course, if you happen to prepare one yourself in the
120
 * meanwhile don't hesitate and let us know! :-)
121
 *
122 be35facb meetecho
 * In general, when using the gateway features, you would normally do the following:
123
 *
124
 * -# include the Janus JavaScript library in your web page;
125
 * -# initialize the Janus JavaScript library;
126
 * -# connect to the gateway and create a session;
127
 * -# create one or more handles to attach to a plugin (e.g., echo test and/or streaming);
128
 * -# interact with the plugin (sending/receiving messages, negotiating a PeerConnection);
129
 * -# eventually, close all the handles and shutdown the related PeerConnections;  
130
 * -# destroy the session.  
131 54582a6a Lorenzo Miniero
 *
132 be35facb meetecho
 * The above steps will be presented in order, describing how you can use
133
 * the low level API to accomplish them. Consider that in the future we might
134
 * provide higher level wrappers to this API to address specific needs, e.g.,
135
 * a higher level API for each plugin: this would make it even easier to use
136
 * the gateway features, as a high level API for the streaming plugin, for
137
 * instance, may just ask you to provide the server address and the ID of
138
 * the \c &lt;video&gt; element to display the stream in, and would take care of all the
139
 * above mentioned steps on your behalf. Needless to say, you're very welcome
140
 * to provide wrapper APIs yourself, if you feel a sudden urge to do so! :-)
141
 *
142
 * <hr>
143
 *
144
 * As a first step, you should include the \c janus.js library in your project:
145
 *
146
\verbatim
147
<script type="text/javascript" src="janus.js" ></script>
148
\endverbatim
149
 *
150
 * The core of the JavaScript API is the \c Janus object. This object needs
151
 * to be initialized the first time it is used in a page. This can be done
152
 * using the static \c init method of the object, which accepts the
153
 * following options:
154
 *
155 c2c01614 Lorenzo Miniero
 * - \c debug: whether debug should be enabled on the JavaScript console, and what levels
156
 *   - \c true or \c "all": all debuggers enabled (Janus.trace, Janus.debug, Janus.log, Janus.warn, Janus.error)
157
 *   - array (e.g., <code>["trace", "warn"]</code>): only enable selected debuggers (allowed tokens: trace, debug, log, warn, error)
158
 *   - \c false: disable all debuggers
159 be35facb meetecho
 * - \c callback: a user provided function that is invoked when the initialization is complete. 
160 54582a6a Lorenzo Miniero
 *
161 be35facb meetecho
 * Here's an example:
162
 *
163 54582a6a Lorenzo Miniero
 *
164 be35facb meetecho
 \verbatim
165
Janus.init({
166
   debug: true,
167
   callback: function() {
168
	   // Done!
169
   });
170
 \endverbatim
171
 *
172
 * Once the library has been initialized, you can start creating sessions.
173
 * Normally, each browser tab will need a single session with the gateway: in
174
 * fact, each gateway session can contain several different plugin handles
175
 * at the same time, meaning you can start several different WebRTC sessions
176
 * with the same or different plugins for the same user using the same
177
 * gateway session. That said, you're free to set up different gateway
178
 * sessions in the same page, should you prefer so.
179
 *
180
 * Creating a session is quite easy. You just need to use the \c new constructor
181
 * to create a new \c Janus object that will handle your interaction with the
182
 * gateway. Considering the dynamic and asynchronous nature of Janus sessions
183
 * (events may occur at any time), there are several properties and callbacks you
184
 * can configure when creating a session:
185
 *
186 d961635a meetecho
 * - \c server: the address of the gateway as a specific address (e.g.,
187
 * http://yourserver:8088/janus to use the plain HTTP API or ws://yourserver:8188/
188
 * for WebSockets) or as an array of addresses to try sequentially to allow
189
 * automatic for fallback/failover during setup;
190 be35facb meetecho
 * - \c iceServers: a list of STUN/TURN servers to use (a default STUN server
191
 * will be used if you skip this property);
192
 * - a set of callbacks to be notified about events, namely:
193
 * 		- \c success: the session was successfully created and is ready to be used;
194
 * 		- \c error: the session was NOT successfully created;
195
 * 		- \c destroyed: the session was destroyed and can't be used any more.
196
 *
197
 * These properties and callbacks are passed to the method as properties
198
 * of a single parameter object: that is, the \c Janus constructor takes a
199
 * single parameter, which although acts as a container for all the available
200
 * options. The \c success callback is where you tipically start your application
201
 * logic, e.g., attaching the peer to a plugin and start a media session.
202
 *
203
 * Here's an example:
204 54582a6a Lorenzo Miniero
 *
205 be35facb meetecho
 \verbatim
206
var janus = new Janus(
207
	{
208
		server: 'http://yourserver:8088/janus',
209
		success: function() {
210
			// Done! attach to plugin XYZ
211
		},
212
		error: function(cause) {
213
			// Error, can't go on...
214
		},
215
		destroyed: function() {
216
			// I should get rid of this
217
		}
218
	});
219
 \endverbatim
220
 *
221 d961635a meetecho
 * As anticipated, the server may be a specific address, e.g.:
222
 *
223
 \verbatim
224
var janus = new Janus(
225
	{
226
		server: 'http://yourserver:8088/janus',
227
				// or
228
		server: 'ws://yourserver:8188/',
229
		[..]
230
 \endverbatim
231
 *
232
 * or an array of addresses. Such an array can be especially useful if
233
 * you want the library to first check if the WebSockets server is
234
 * reachable and, if not, fallback to plain HTTP, or just to provide
235
 * a link multiple instances to try for failover. This is an example of
236
 * how to pass a 'try websockets and fallback to HTTP' array:
237
 *
238
 \verbatim
239
var janus = new Janus(
240
	{
241
		server: ['ws://yourserver:8188/','http://yourserver:8088/janus'],
242
		[..]
243
 \endverbatim
244
 *
245 be35facb meetecho
 * Once created, this object represents your session with the gateway.
246
 * you can interact with a \c Janus object in several different ways.
247
 * In particular, the following properties and methods are defined:
248
 *
249
 * - \c getServer(): returns the address of the gateway;
250
 * - \c isConnected(): returns \c true if the Janus instance is connected
251
 * to the gateway, \c false otherwise;
252
 * - \c getSessionId(): returns the unique gateway session identifier;
253
 * - \c attach(parameters): attaches the session to a plugin, creating an handle;
254
 * more handles to the same or different plugins can be created at the same time;
255
 * - \c destroy(parameters): destroys the session with the gateway, and closes
256
 * all the handles (and related PeerConnections) the session may have with any plugin as well.
257
 *
258
 * The most important property is obviously the \c attach() method, as
259
 * it's what will allow you to exploit the features of a plugin to manipulate
260
 * the media sent and/or received by a PeerConnection in your web page.
261
 * This method will create a plugin handle you can use for the purpose,
262
 * for which you can configure properties and callbacks when calling the
263
 * \c attach() method itself. As for the \c Janus constructor, the \c attach()
264
 * method takes a single parameter that can contain any of the following
265
 * properties and callbacks:
266
 *
267
 * - \c plugin: the unique package name of the plugin (e.g., \c janus.plugin.echotest );
268
 * will be used if you skip this property)
269
 * - a set of callbacks to be notified about events, namely:
270
 * 		- \c success: the handle was successfully created and is ready to be used;
271
 * 		- \c error: the handle was NOT successfully created;
272
 * 		- \c consentDialog: this callback is triggered just before \c getUserMedia is called
273
 * (parameter=<b>true</b>) and after it is completed (parameter=<b>false</b>); this means it can
274
 * be used to modify the UI accordingly, e.g., to prompt the user about the need to accept the device access consent requests;
275
 * 		- \c onmessage: a message/event has been received from the plugin;
276
 * 		- \c onlocalstream: a local \c MediaStream is available and ready to be displayed;
277
 * 		- \c onremotestream: a remote \c MediaStream is available and ready to be displayed;
278 af40a682 meetecho
 * 		- \c ondataopen: a Data Channel is available and ready to be used;
279
 * 		- \c ondata: data has been received through the Data Channel;
280
 * 		- \c oncleanup: the WebRTC PeerConnection with the plugin was closed;
281
 * 		- \c detached: the plugin handle has been detached by the plugin itself,
282
 * and so should not be used anymore.
283 be35facb meetecho
 *
284
 * Here's an example:
285 54582a6a Lorenzo Miniero
 *
286 be35facb meetecho
 \verbatim
287
// Attach to echo test plugin, using the previously created janus instance
288
janus.attach(
289
	{
290
		plugin: "janus.plugin.echotest",
291
		success: function(pluginHandle) {
292
			// Plugin attached! 'pluginHandle' is our handle
293
		},
294
		error: function(cause) {
295
			// Couldn't attach to the plugin
296
		},
297
		consentDialog: function(on) {
298
			// e.g., Darken the screen if on=true (getUserMedia incoming), restore it otherwise
299
		},
300
		onmessage: function(msg, jsep) {
301
			// We got a message/event (msg) from the plugin
302
			// If jsep is not null, this involves a WebRTC negotiation
303
		},
304
		onlocalstream: function(stream) {
305
			// We have a local stream (getUserMedia worked!) to display
306
		},
307
		onremotestream: function(stream) {
308
			// We have a remote stream (working PeerConnection!) to display
309
		},
310
		oncleanup: function() {
311
			// PeerConnection with the plugin closed, clean the UI
312
			// The plugin handle is still valid so we can create a new one
313 af40a682 meetecho
		},
314
		detached: function() {
315
			// Connection with the plugin closed, get rid of its features
316
			// The plugin handle is not valid anymore
317 be35facb meetecho
		}
318
	});
319
 \endverbatim
320
 *
321
 * So the \c attach() method allows you to attach to a plugin, and specify 
322
 * the callbacks to invoke when anything relevant happens in this interaction.
323
 * To actively interact with the plugin, you can use the \c Handle object
324
 * that is returned by the \c success callback (pluginHandle in the example).
325
 *
326
 * This \c Handle object has several methods you can use to interact with
327
 * the plugin or check the state of the session handle:
328
 *
329
 * - \c getId(): returns the unique handle identifier;
330
 * - \c getPlugin(): returns the unique package name of the attached plugin;
331
 * - \c send(parameters): sends a message (with or without a jsep to
332
 * negotiate a PeerConnection) to the plugin;
333
 * - \c createOffer(callbacks): asks the library to create a WebRTC compliant OFFER;
334
 * - \c createAnswer(callbacks): asks the library to create a WebRTC compliant ANSWER;
335
 * - \c handleRemoteJsep(callbacks): asks the library to handle an incoming WebRTC compliant session description;
336
 * - \c dtmf(parameters): sends a DTMF tone on the PeerConnection;
337 a3d13e20 meetecho
 * - \c data(parameters): sends data through the Data Channel, if available;
338 be35facb meetecho
 * - \c getBitrate(): gets a verbose description of the currently received stream bitrate (only available on Chrome, for now);
339
 * - \c hangup(): tells the library to close the PeerConnection;
340
 * - \c detach(parameters): detaches from the plugin and destroys the handle, tearing
341
 * down the related PeerConnection if it exists.
342
 *
343
 * While the \c Handle API may look complex, it's actually quite straightforward
344
 * once you get the concept. The only step that may require a little more
345
 * effort to understand is the PeerConnection negotiation, but again, if
346
 * you're familiar with the WebRTC API, the \c Handle actually makes it
347
 * a lot easier.
348
 *
349
 * The idea behind it's usage is the following:
350
 *
351
 * -# you use \c attach() to create a \c Handle object;
352
 * -# in the \c success callback, your application logic can kick in: you may
353
 * want to send a message to the plugin ( \c send(msg) ), negotiate
354
 * a PeerConnection with the plugin right away ( \c createOffer followed
355
 * by a \c send(msg, jsep) ) or wait for something to happen to do anything;
356
 * -# the \c onmessage callback tells you when you've got messages from the plugin;
357
 * if the \c jsep parameter is not null, just pass it to the library, which will take
358
 * care of it for you; if it's an \b OFFER use \c createAnswer (followed by a
359
 * \c send(msg, jsep) to close the loop with the plugin), otherwise use
360
 * \c handleRemoteJsep ;
361
 * -# whether you took the initiative to set up a PeerConnection or the plugin did,
362
 * the \c onlocalstream and/or the \c onremotestream callbacks will provide
363
 * you with a stream you can display in your page;
364
 * -# each plugin may allow you to manipulate what should flow through the
365
 * PeerConnection channel: the \c send method and \c onmessage callback
366
 * will allow you to handle this interaction (e.g., to tell the plugin
367 a3d13e20 meetecho
 * to mute your stream, or to be notified about someone joining a virtual room),
368
 * while the \c ondata callback is triggered whenever data is received
369 05bba746 meetecho
 * on the Data Channel, if available (and the \c ondataopen callback
370
 * will tell you when a Data Channel is actually available). 
371 be35facb meetecho
 *
372
 * The following paragraphs will delve a bit deeper in the negotiation
373
 * mechanism provided by the \c Handle API, in particular describing
374
 * the properties and callbacks that may be involved. To follow the approach
375
 * outlined by the W3C WebRTC API, this negotiation mechanism is heavily
376
 * based on asynchronous methods as well.
377
 *
378
 * - \c createOffer takes a single parameter, that can contain any of the
379
 * following properties and callbacks:
380 a3d13e20 meetecho
 *   - \c media: you can use this property to tell the library which media (audio/video/data)
381
 * you're interested in, and whether you're going to send and/or receive any of them; by default
382
 * audio and video are enabled in both directions, while the Data Channels are disabled;
383 be35facb meetecho
 * this option is an object that can take any of the following properties:
384 13984df7 meetecho
 *     - \c audioSend: \c true/false (do or do not send audio);
385
 *     - \c audioRecv: \c true/false (do or do not receive audio);
386
 *     - \c audio: \c true/false (do or do not send \b and receive audio, takes precedence on the above);
387
 *     - \c videoSend: \c true/false (do or do not send video);
388
 *     - \c videoRecv: \c true/false (do or do not receive video);
389
 *     - \c video: \c true/false (do or do not send \b and receive video, takes precedence on the above);
390 1a0b5bea meetecho
 *     - \c video: \c "lowres"/"lowres-16:9"/"stdres"/"stdres-16:9"/"hires"/"hires-16:9"
391
 * (send a 320x240/320x180/640x480/640x360/1280x720 video, takes precedence on the above;
392
 default is \c "stdres" )
393
 * this property will affect the resulting getUserMedia that the library will issue; please
394
 * notice that Firefox doesn't support the \c "16:9" variants, which will fallback
395
 * to the ones; besides, \c "hires" and \c "hires-16:9" are currently synonymous, as
396
 * there's no 4:3 high resolution constraint as of now;
397 13984df7 meetecho
 *     - \c video: \c "screen" (use screensharing for video, disables audio, takes precedence on both audio and video);
398 a3d13e20 meetecho
 *     - \c data: \c true/false (do or do not use Data Channels, default is false)
399 13984df7 meetecho
 *   - \c trickle: \c true/false, to tell the library whether you want
400
 * Trickle ICE to be used (true, the default) or not (false);
401 7d56d846 Lorenzo Miniero
 *   - \c stream: optional, only to be passed in case you obtained a MediaStream object yourself with a \c getUserMedia
402
 * request, and that you want the library to use instead of having it get one by itself (makes
403
 * the \c media property useless, as it won't be read for accessing any device);
404 be35facb meetecho
 *   - a set of callbacks to be notified about the result, namely:
405
 *     - \c success: the session description was created (attached as a parameter) and is ready to be sent to the plugin; 
406
 *     - \c error: the session description was NOT successfully created;
407
 * - \c createAnswer takes the same options as createOffer, but requires
408
 * an additional one as part of the single parameter argument:
409
 *   - \c jsep: the session description sent by the plugin (e.g., as received
410
 * in an \c onmessage callback) as its OFFER.
411
 *
412
 * Whether you use \c createOffer or \c createAnswer depending on the scenario,
413
 * you should end up with a valid \c jsep object returned in the \c success
414
 * callback. You can attach this \c jsep object to a message in a \c send request
415
 * to pass it to the plugin, and have the gateway negotiate a PeerConnection
416
 * with your application.
417
 *
418
 * Here's an example of how to use \c createOffer, taken from the Echo Test demo page:
419
 *
420
 \verbatim
421
// Attach to echo test plugin
422
janus.attach(
423
	{
424
		plugin: "janus.plugin.echotest",
425
		success: function(pluginHandle) {
426
			// Negotiate WebRTC
427
			echotest = pluginHandle;
428
			var body = { "audio": true, "video": true };
429
			echotest.send({"message": body});
430
			echotest.createOffer(
431
				{
432
					// No media property provided: by default,
433
						// it's sendrecv for audio and video
434
					success: function(jsep) {
435
						// Got our SDP! Send our OFFER to the plugin
436
						echotest.send({"message": body, "jsep": jsep});
437
					},
438
					error: function(error) {
439
						// An error occurred...
440
					}
441
				});
442
		},
443
		[..]
444
		onmessage: function(msg, jsep) {
445
			// Handle msg, if needed, and check jsep
446
			if(jsep !== undefined && jsep !== null) {
447
				// We have the ANSWER from the plugin
448
				echotest.handleRemoteJsep({jsep: jsep});
449
			}
450
		},
451
		[..]
452
		onlocalstream: function(stream) {
453
			// Invoked after createOffer
454
			// This is our video
455
		},
456
		onremotestream: function(stream) {
457
			// Invoked after handleRemoteJsep has got us a PeerConnection
458
			// This is the remote video
459
		},
460
		[..]
461
  \endverbatim
462
 *
463
 * This, instead, is an example of how to use \c createAnswer, taken from the Streaming demo page:
464
 *
465
 \verbatim
466
// Attach to echo test plugin
467
janus.attach(
468
	{
469
		plugin: "janus.plugin.streaming",
470
		success: function(pluginHandle) {
471
			// Handle created
472
			streaming = pluginHandle;
473
			[..]
474
		},
475
		[..]
476
		onmessage: function(msg, jsep) {
477
			// Handle msg, if needed, and check jsep
478
			if(jsep !== undefined && jsep !== null) {
479
				// We have an OFFER from the plugin
480
				streaming.createAnswer(
481
					{
482
						// We attach the remote OFFER
483
						jsep: jsep,
484
						// We want recvonly audio/video
485
						media: { audioSend: false, videoSend: false },
486
						success: function(ourjsep) {
487
							// Got our SDP! Send our ANSWER to the plugin
488
							var body = { "request": "start" };
489
							streaming.send({"message": body, "jsep": ourjsep});
490
						},
491
						error: function(error) {
492
							// An error occurred...
493
						}
494
					});
495
			}
496
		},
497
		[..]
498
		onlocalstream: function(stream) {
499
			// This will NOT be invoked, we chose recvonly
500
		},
501
		onremotestream: function(stream) {
502
			// Invoked after send has got us a PeerConnection
503
			// This is the remote video
504
		},
505
		[..]
506
  \endverbatim
507
 *
508
 * Of course, these are just a couple of examples where the scenarios
509
 * assumed that one plugin would only receive (Echo Test) or generate
510
 * (Streaming) offers. A more complex example (e.g., a Video Call plugin)
511
 * would involve both, allowing you to either send offers to a plugin,
512
 * or receive some from them. Handling this is just a matter of checking
513
 * the \c type of the \c jsep object and reacting accordingly.
514
 *  
515
 * <hr>
516 54582a6a Lorenzo Miniero
 *
517 be35facb meetecho
 * This is it! For more information about the API, have a look at the
518
 * demo pages that are available in the \b html folder in this package.
519 54582a6a Lorenzo Miniero
 *
520 be35facb meetecho
 */
521
522 ead45815 meetecho
/*! \page rest RESTful, WebSockets and RabbitMQ API
523 af40a682 meetecho
 *
524 ead45815 meetecho
 * Since version \c 0.0.6, there are three different ways to interact with a
525
 * Janus instance: a \ref plainhttp (the default), a \ref WS and a \ref rabbit
526
 * (both optional, need an external library to be available). All of
527 af40a682 meetecho
 * the interfaces use the same messages (in terms of requests, responses
528
 * and notifications), so almost all the concepts described in the
529 ead45815 meetecho
 * \ref plainhttp section apply to the WebSocket/RabbitMQ interfaces as well.
530 09ac2273 meetecho
 * Besides, since version \c 0.1.0 the transport mechanism for the Janus API
531
 * has been made modular, which means other protocols for transporting
532
 * Janus API messages might become available in the future: considering the
533
 * Janus protocol is supposed to be mostly agnostic to the protocol it is
534
 * transported on, the concepts explained in the following sections should
535
 * apply to those as well.
536
 *
537 ead45815 meetecho
 * As it will be explained later in the \ref WS and \ref rabbit sections
538
 * below, the only differences come when addressing specific sessions/handles
539 09ac2273 meetecho
 * and in part in how you handle notifications using something different than
540
 * the REST interface: in fact, since with WebSockets and RabbitMQ (and, as
541
 * anticipated, with other protocols that may be added in the future too)
542
 * there's no REST-based path involved, you'll need a couple of additional
543
 * identifiers to bridge the gap.
544 263ce349 Lorenzo Miniero
 * Some details are also provided in case you're interested in \ref auth.
545 54582a6a Lorenzo Miniero
 *
546 af40a682 meetecho
 * \section plainhttp Plain HTTP REST Interface
547 47637450 meetecho
 * As anticipated in the \ref JS documentation, the gateway deploys a
548
 * RESTful interface that clients can exploit. The \c janus.js library
549
 * makes use of it in a transparent way, but if you're interested in
550
 * more details about it (e.g., because you want to talk to the gateway
551
 * your own way), this page described the interface and the protocol
552 263ce349 Lorenzo Miniero
 * the API exposes and uses.
553 47637450 meetecho
 *
554
 * There are basically three types/levels of endpoints you can meet:
555
 *
556
 * -# \ref root (\c /janus by default, but configurable), which
557
 * you only \b POST to in order to create a gateway session;
558
 * -# \ref sessions (e.g., \c /janus/12345678, using the
559
 * identifier retrieved with a previous create), which you either send
560
 * a \b GET to (long poll for events and messages from plugins) or a \b POST
561
 * (to create plugin handles or manipulate the session);
562
 * -# \ref handles (e.g., \c /janus/12345678/98765432, appending
563
 * the handle identifier to the session one) which you only send \b POST
564
 * messages to (messages/negotiations for a plugin, handle manipulation),
565
 * as all events related to this handle would be received in the session
566
 * endpoint \b GET (the \c janus.js library would redirect the incoming
567
 * messages to the right handle internally).
568
 *
569
 * Messages and requests you can send to and receive from any of the
570
 * above mentioned endpoints are described in the following chapters.
571
 * In general, all messages share at least two fields:
572 54582a6a Lorenzo Miniero
 *
573 47637450 meetecho
 * - \c janus: the request/event (e.g., "create", "attach", "message", etc.);
574
 * - \c transaction: a random string that the client can use to match incoming
575
 * messages from the gateway (since, as explained in the \ref plugins
576
 * documentation, all messages are asynchronous).
577
 *
578
 * Different messages will of course add different information to this
579
 * base syntax. Error message, instead, usually have these fields:
580
 *
581
 * - \c janus: this would be "error";
582
 * - \c transaction: this would be the transaction identifier of the request
583
 * that failed;
584
 * - \c error: a JSON object containing two fields:
585
 *   - \c code: a numeric error code, as defined in apierror.h;
586
 *   - \c reason: a verbose string describing the cause of the failure.
587
 *
588
 * An example of an error is presented here:
589
 *
590
\verbatim
591
{
592
	"janus" : "error",
593
	"transaction" : "a1b2c3d4"
594
	"error" : {
595
		"code" : 458
596
		"reason" : "Could not find session 12345678"
597
	}
598
}
599
\endverbatim
600
 *
601 af40a682 meetecho
 *
602
 * \section info Getting info about the Janus instance
603
 * The API exposes an \c info endpoint you can query to get information
604
 * about the Janus instance you're talking to. Specifically, it returns
605
 * information about the version of the Janus server, whether some of the
606 09ac2273 meetecho
 * optional features (e.g., Data Channels or IPv6) are supported or not, 
607
 * and which transports and plugins are available.
608 af40a682 meetecho
 *
609
 * To get this information, just send an HTTP \b GET message to the \c info
610
 * endpoint (e.g., http://yourserver:8088/janus/info), which will return
611
 * something like this:
612
 *
613
\verbatim
614
{
615 09ac2273 meetecho
	"janus": "server_info",
616
	"transaction": "i1bzIL341Kl2",
617 af40a682 meetecho
	"name": "Janus WebRTC Gateway",
618 09ac2273 meetecho
	"version": 10,
619
	"version_string": "0.1.0",
620
	"author": "Meetecho s.r.l.",
621
	"data_channels": "true",	// Data channels are supported
622
	"ipv6": "false",			// IPv6 is not configured
623
	"ice-tcp": "false",			// ICE-TCP support is disabled
624
	"transports": {
625
		"janus.transport.http": {
626
			"name": "JANUS REST (HTTP/HTTPS) transport plugin",
627
			"author": "Meetecho s.r.l.",
628
			"description": "This transport plugin adds REST (HTTP/HTTPS) support to the Janus API via libmicrohttpd.",
629
			"version_string": "0.0.1",
630
			"version": 1
631
		},
632
		[..]	// Other transport plugins
633
	},
634 af40a682 meetecho
	"plugins": {
635
		"janus.plugin.sip": {		// The SIP plugin is available
636
			"version_string": "0.0.2",
637
			"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.",
638
			"author": "Meetecho s.r.l.",
639
			"name": "JANUS SIP plugin",
640
			"version": 2
641
		},
642
		"janus.plugin.videoroom": {	// The Video MCU plugin is available
643
			"version_string": "0.0.3",
644
			"description": "This is a plugin implementing a videoconferencing MCU for Janus, something like Licode.",
645
			"author": "Meetecho s.r.l.",
646
			"name": "JANUS VideoRoom plugin",
647
			"version": 3
648
		},
649
		[..]	// Other plugins
650
	}
651
\endverbatim
652
 *
653
 * You can use this information to selectively enable or disable features
654
 * in your application according to what's available in the Janus instance
655
 * you're trying to contact.
656
 *
657
 *
658 47637450 meetecho
 * \section root The gateway root
659
 * The gateway root is \c /janus by default but, as anticipated, it is
660
 * configurable, either via command line or in the \c janus.cfg configuration.
661
 *
662
 * You can only contact the gateway root when you want to create a new
663
 * session with the gateway. To do so, you need to \b POST the a \c janus "create"
664
 * JSON message to the gateway:
665
 *
666
\verbatim
667
{
668
	"janus" : "create",
669
	"transaction" : "<random alphanumeric string>"
670
}
671
\endverbatim
672
 *
673
 * If the request is successful, you'll receive the unique session identifier
674
 * in a response formatted like this:
675
 *
676
\verbatim
677
{
678
	"janus" : "success",
679 ecb79ec6 meetecho
	"transaction" : "<same as the request>",
680 47637450 meetecho
	"data" : {
681
		"id" : <unique integer session ID>
682
	}
683
}
684
\endverbatim
685
 *
686
 * In case of an error, you'll receive an error message as the one introduced
687
 * before. This request, if issued with a POST to the gateway root, can only
688
 * fail if you miss any of the required fields in the request.
689
 *
690 af40a682 meetecho
 *
691 47637450 meetecho
 * \section sessions The session endpoint
692
 * Once you've created a session, a new endpoint you can use is created
693
 * in the gateway. Specifically, the new endpoint is constructed by
694
 * concatenating the gateway root and the session identifier you've been
695
 * returned (\c e.g., \c /janus/12345678).
696
 *
697
 * This endpoint can be used in two different ways: 
698
 *
699
 * -# using a parameter-less \b GET request to the endpoint, you'll
700
 * issue a long-poll request to be notified about events and incoming
701
 * messages from this session;
702
 * -# using a \b POST request to send JSON messages, you'll interact
703
 * with the session itself.
704
 *
705
 * <hr>
706
 *
707
 * \par Long-poll requests
708
 * The long-poll will only trigger events related to messages you're
709
 * being sent from plugins, and as such will be clearer to understand
710
 * once you read the \ref handles section. That said, the events are formatted
711
 * this way:
712
 *
713
 * - \c janus: this would be "event";
714
 * - \c sender: this would be the unique numeric plugin handle identifier;
715
 * - \c transaction: this is optional: it is either related to a request
716
 * you sent to a plugin before, or it may be missing in case this is an
717
 * event the plugin sent on its own account;
718
 * - \c plugindata: a JSON object containing the info coming from the plugin itself:
719
 *   - \c plugin: the plugin's unique package name (e.g., \c janus.plugin.echotest);
720
 *   - \c data: an opaque JSON object that is plugin specific.
721
 * - \c jsep: an optional JSON object containing the JSEP SDP (offer or
722
 * answer) the plugin may send to negotiate a WebRTC PeerConnection with
723
 * the client (check the \ref handles section for more details).
724
 *
725
 * An example of such an event (in this case, sent by the janus_echotest.c
726
 * plugin in response to a request) is presented here:
727
 *
728
\verbatim
729
{
730
	"janus" : "event",
731
	"sender" : 1815153248,
732
	"transaction" : "sBJNyUhH6Vc6",
733
	"plugindata" : {
734
		"plugin": "janus.plugin.echotest",
735
		"data" : {
736
			"echotest" : "event",
737
			"result" : "ok"
738
		}
739
	},
740
}
741
\endverbatim
742
 *
743
 * The long-poll request has a 30 seconds timeout. If it has no event to
744
 * report, a simple \em keep-alive message will be triggered:
745
 *
746
\verbatim
747
{
748
	"janus" : "keepalive",
749
}
750
\endverbatim
751
 *
752
 * As with all long-poll based approaches, it's up to your application
753
 * to send a new polling request as soon as an event or a keep-alive
754
 * has been received.
755
 *
756 aff9f5c0 meetecho
 * Notice that, by default, the long poll returns a single event: that is,
757
 * as soon as a message becomes available in the session queue, that event
758
 * is returned and the long poll closes. If you want to receive more events
759 616ca9d5 meetecho
 * within the context of the same long poll, you can pass the \c maxev
760 aff9f5c0 meetecho
 * query string parameter to the GET, e.g.:
761
 *
762
\verbatim
763 616ca9d5 meetecho
GET http://host:port/janus/<sessionid>?maxev=5
764 aff9f5c0 meetecho
\endverbatim
765
 *
766
\verbatim
767
[
768
	{
769
		// Event #1
770
		"janus" : "event",
771
		[..]
772
	},
773
	{
774
		// Event #2
775
		"janus" : "event",
776
		[..]
777
	},
778
	[..]
779
]
780
\endverbatim
781
 *
782
 * This request will instruct the gateway to return at maximum 5 events
783
 * within the context of the same long poll, formatted as a JSON array
784
 * of events. Please beware that this does \b NOT mean that you'll
785
 * always get 5 events this way: it only means that, if a message becomes
786
 * available in the queue and more events are present as well, Janus will
787
 * return more than one without needing you to send multiple long polls
788
 * immediately thereafter to get them. For this reason, don't be surprised
789 616ca9d5 meetecho
 * if even with a \c maxev parameter set, you'll still get a single
790 aff9f5c0 meetecho
 * event being notified as the sole object in the returned array.
791 47637450 meetecho
 *
792
 * <hr>
793
 *
794
 * \par Interacting with the session
795
 * To interact with the session, e.g., to create a new handle to attach
796
 * to a plugin or destroy the current session, you need to send a \b POST
797
 * JSON message to the session endpoint.
798
 *
799
 * To attach to a plugin in order to exploit its features, you need to
800
 * \b POST a \c janus "attach" JSON message to the gateway; you'll need
801
 * of course to provide information on the plugin you want to attach to,
802
 * which can be done using the \c plugin field: 
803
 *
804
\verbatim
805
{
806
	"janus" : "attach",
807
	"plugin" : "<the plugin's unique package name>",
808
	"transaction" : "<random string>"
809
}
810
\endverbatim
811
 *
812
 * If the request is successful, you'll receive the unique plugin handle
813
 * identifier in a response formatted the same way as the session create
814
 * one, that is like this:
815
 *
816
\verbatim
817
{
818
	"janus" : "success",
819 ecb79ec6 meetecho
	"transaction" : "<same as the request>",
820 47637450 meetecho
	"data" : {
821
		"id" : <unique integer plugin handle ID>
822
	}
823
}
824
\endverbatim
825
 *
826
 * In case of an error, you'll receive an error message as the one introduced
827
 * before. This request, if issued with a POST to a valid session endpoint, can only
828
 * fail if you miss any of the required fields in the request or if the
829
 * plugin you requested is not available in the gateway.
830
 *
831
 * To destroy the current session, instead, just send a "destroy" \c janus
832
 * request:
833
 *
834
\verbatim
835
{
836
	"janus" : "destroy",
837
	"transaction" : "<random string>"
838
}
839
\endverbatim
840
 *
841
 * This will also destroy the endpoint created for this session.
842
 * If your session is currently managing one or more plugin handles, 
843
 * make sure you destroy them first (as explained in the next section).
844
 * The gateway tries to do this automatically when receiving a session
845
 * destroy request, but a cleaner approach on the client side would help 
846
 * nonetheless avoid potential issues.
847
 *
848
 * \section handles The plugin handle endpoint
849
 * Once you've created a plugin handle, a new endpoint you can use is created
850
 * in the gateway. Specifically, the new endpoint is constructed by
851
 * concatenating the gateway root, the session identifier and the new
852
 * plugin handle identifier you've been returned (\c e.g.,
853
 * \c /janus/12345678/98765432).
854
 *
855
 * You can use this plugin handle for everything that is related to the
856
 * communication with a plugin, that is, send the plugin a message,
857
 * negotiate a WebRTC connection to attach to the plugin, and so on.
858
 *
859
 * To send a plugin a message/request, you need to \b POST the handle
860
 * endpoint a \c janus "message" JSON payload. The \c body field will
861
 * have to contain a plugin-specific JSON payload. In case the message
862
 * also needs to convey WebRTC-related negotiation information, a \c jsep
863
 * field containing the JSON-ified version of the JSEP object can be 
864
 * attached as well.
865
 *
866 af40a682 meetecho
 * \note If you attach a \c jsep object, whether it's an offer or an answer,
867
 * you're stating your will to negotiate a PeerConnection. This means that
868
 * an empty or invalid \c jsep object will trigger a validation and will
869
 * cause the whole request to fail, so make sure you exclude the field
870
 * completely from your request if all you're interested into is sending
871
 * a message to a plugin.
872
 *
873 47637450 meetecho
 * Here's an example of a message you may send the janus_echotest.c plugin
874
 * to mute your audio:
875
 *
876
\verbatim
877
{
878
	"janus" : "message",
879
	"transaction" : "sBJNyUhH6Vc6",
880
	"body" : {
881
		"audio" : false
882
	}
883
}
884
\endverbatim
885
 *
886
 * The same message containing negotiation information as well, instead,
887
 * (an OFFER, in this example), is presented here:
888
 *
889
\verbatim
890
{
891
	"janus" : "message",
892
	"transaction" : "sBJNyUhH6Vc6",
893
	"body" : {
894
		"audio" : false
895
	},
896
	"jsep" : {
897
		"type" : "offer",
898
		"sdp" : "v=0\r\no=[..more sdp stuff..]"
899
	}
900
}
901
\endverbatim
902
 *
903 742f8871 meetecho
 * If you're going to \c trickle candidates rather than including them
904
 * all in an SDP OFFER or ANSWER, there is an ad-hoc message you can use
905
 * to do so which is called, unsurprisingly, \c trickle and which you
906
 * can use to send one or more trickle candidates to Janus. Since such
907
 * a message is related to a specific PeerConnection, it will need to be
908
 * addressed to the right Handle just as the \c message introduced
909
 * previously. A \c trickle message can contain three different kind of
910
 * information:
911
 *
912
 *  - a single trickle candidate;
913
 *  - an array of trickle candidates;
914
 *  - a null candidate or a \c completed JSON object to notify the end of the
915
 * candidates.
916
 *
917
 * This is an example of a single candidate being trickled:
918
 *
919
\verbatim
920
{
921
	"janus" : "trickle",
922
	"transaction" : "hehe83hd8dw12e",
923
	"candidate" : {
924
		"sdpMid" : "video",
925
		"sdpMLineIndex" : 1,
926
		"candidate" : "..."
927
	}
928
}
929
\endverbatim
930
 *
931
 * This, instead, is an example of how to group more trickle candidates
932
 * in a single request (particularly useful if you're wrapping Janus in
933
 * your server and want to reduce the number of transactions):
934
 *
935
\verbatim
936
{
937
	"janus" : "trickle",
938
	"transaction" : "hehe83hd8dw12e",
939 2f704a4e meetecho
	"candidates" : [ 
940 742f8871 meetecho
		{
941
			"sdpMid" : "video",
942
			"sdpMLineIndex" : 1,
943
			"candidate" : "..."
944
		},
945
		{
946
			"sdpMid" : "video",
947
			"sdpMLineIndex" : 1,
948
			"candidate" : "..."
949
		},
950
		[..]
951
	]
952
}
953
\endverbatim
954
 *
955
 * Finally, this is how you can tell Janus that you sent all the trickle
956
 * candidates that were gathered:
957
 *
958
\verbatim
959
{
960
	"janus" : "trickle",
961
	"transaction" : "hehe83hd8dw12e",
962
	"candidate" : {
963
		"completed" : true
964
	}
965
}
966
\endverbatim
967
 *
968 292d035f meetecho
 * Plugins may handle this requests synchronously or asynchronously. In
969
 * the former, plugins would return a response to the request itself
970
 * immediately; in the latter, instead, the plugin would only notify a
971
 * successful reception of the request, which it would process later.
972 47637450 meetecho
 * Considering the asynchronous nature of the Janus API, a successful
973 292d035f meetecho
 * management of such messages within the gateway would in such case result in
974 47637450 meetecho
 * a \c janus "ack" messages being sent back to the client. A logical response
975
 * to those messages, if needed, would be provided as an event in the
976
 * long-poll interface described previously, and clients would be able
977
 * to match it to the original request by means of the transaction
978
 * identifiers. It is worth noting, though, that should a WebRTC negotiation
979
 * be involved you don't have to expect an ANSWER to your OFFER to be
980
 * sent back in the same transaction. A plugin may decide, in its
981
 * application logic, to not provide you with an ANSWER right away, but
982
 * only after some internal state changes occur. It's up to your application
983
 * to handle the negotiation state accordingly.
984
 *
985
 * An example of an "ack" being sent back to the client, using the previous
986
 * sample request as a reference, is presented here:
987
 *
988
\verbatim
989
{
990
	"janus" : "ack",
991
	"transaction" : "sBJNyUhH6Vc6"
992
}
993
\endverbatim
994
 *
995 292d035f meetecho
 * If you receive this ack instead of a "success" response, you can be
996
 * sure the plugin has received the message, and is going to process it soon.
997 47637450 meetecho
 *
998
 * In case of an error, instead, you'll receive an error message as the one
999
 * introduced before. This request, if issued with a POST to a valid plugin
1000
 * handle endpoint, can only fail if you miss any of the required fields
1001
 * in the request, if the plugin you tried to contact is not available in
1002
 * the gateway anymore, if an error occurred in the plugin when trying to
1003
 * receive the message or if the \c jsep SDP you may have provided is
1004
 * invalid.
1005
 *
1006
 * To destroy the plugin handle, instead, just send a "detach" \c janus
1007
 * request:
1008
 *
1009
\verbatim
1010
{
1011
	"janus" : "detach",
1012
	"transaction" : "<random string>"
1013
}
1014
\endverbatim
1015
 *
1016
 * This will also destroy the endpoint created for this plugin handle.
1017
 * If your plugin handle is also managing an ongoing WebRTC connection
1018
 * with the plugin, make sure it is torn down as part of this process.
1019
 * The plugin implementation and the gateway core should do this
1020
 * automatically, but implementing the right behaviour in clients would
1021
 * help avoid potential issues nonetheless.
1022
 *
1023 afb3a236 meetecho
 * \section events WebRTC-related events
1024
 *
1025
 * As anticipated in the previous sections, Janus can send events and
1026
 * notifications at any time through the long poll channel (or, as it
1027
 * will be explained later, through the related push mechanisms made
1028
 * available by the \ref WS and \ref rabbit ). While this channel is
1029
 * mostly used to convey asynchronous notifications originated by
1030
 * plugins as part of the messaging they may have with the application
1031
 * using it, the same channel is actually used by Janus to trigger
1032
 * events related to different aspects pertaining a specific handle.
1033
 *
1034
 * In particular, for each handle involving a PeerConnection Janus
1035
 * provides notifications about its current state. To do so, the
1036
 * following events may be received as well:
1037
 *
1038
 *  - \c webrtcup: ICE and DTLS succeeded, and so Janus correctly
1039
 * established a PeerConnection with the user/application;
1040
 *  - \c media: whether Janus is receiving (\c receiving: \c true/false)
1041
 * audio/video (\c type: \c "audio/video") on this PeerConnection;
1042
 *  - \c hangup: the PeerConnection was closed, either by Janus or by
1043
 * the user/application, and as such cannot be used anymore.
1044
 *
1045
 * As such, to monitor the status of a PeerConnection as seen from
1046
 * Janus you can make use of these events to track what's going on. A
1047
 * correct flow for an active PeerConnection would be one that, after a
1048
 * WebRTC negotiation and setup, results in a \c webrtcup event followed
1049
 * by two \c media events (in case both audio and video have been
1050
 * negotiated) specifying that the first audio/video packets have been
1051
 * received. A \c hangup event would inform the user/application that
1052
 * no media is being exchanged with Janus anymore.
1053
 *
1054
 * Here are a few examples of how these events may look like.
1055
 *
1056
 * A PeerConnection becoming ready:
1057
 *
1058
\verbatim
1059
{
1060
	"janus" : "webrtcup",
1061
	session_id: <the session identifier>,
1062
	sender: <the handle identifier>
1063
}
1064
\endverbatim
1065
 *
1066
 * First audio bytes being received by Janus:
1067
 *
1068
\verbatim
1069
{
1070
	"janus" : "media",
1071
	session_id: <the session identifier>,
1072
	sender: <the handle identifier>,
1073
	"type" : "audio",
1074
	"receiving" : true
1075
}
1076
\endverbatim
1077
 *
1078
 * Audio not getting to Janus anymore for some reason:
1079
 *
1080
\verbatim
1081
{
1082
	"janus" : "media",
1083
	"session_id" : <the session identifier>,
1084
	"sender" : <the handle identifier>
1085
	"type" : "audio",
1086
	"receiving" : false
1087
}
1088
\endverbatim
1089
 *
1090
 * Audio getting to Janus again (same message as first audio):
1091
 *
1092
\verbatim
1093
{
1094
	"janus" : "media",
1095
	"session_id" : <the session identifier>,
1096
	"sender" : <the handle identifier>
1097
	"type" : "audio",
1098
	"receiving" : true
1099
}
1100
\endverbatim
1101
 *
1102
 * PeerConnection closed for a DTLS alert (normal shutdown):
1103
 *
1104
\verbatim
1105
{
1106
	"janus" : "hangup",
1107
	"session_id" : <the session identifier>,
1108
	"sender" : <the handle identifier>,
1109
	"reason" : "DTLS alert"
1110
}
1111
\endverbatim
1112
 *
1113
 * It is important to point out that the \c media event notifications
1114
 * only apply if your PeerConnection is going to actually send media to
1115
 * Janus. A \c recvonly PeerConnection, for instance (e.g., as the
1116
 * Streaming plugin would create) would never trigger any \c media
1117
 * event, as Janus would never be receiving media, but only send it.
1118
 *
1119 af40a682 meetecho
 * \section WS WebSockets Interface
1120
 * In recent version of Janus we added support for WebSockets to control
1121
 * the gateway, along the already existing (and still the default) REST
1122
 * API. In fact, while WebSockets still present some more issues in terms
1123
 * of reachability when compared to plain HTTP, they definitely provide
1124
 * a more efficient means for implementing a bidirectional communication.
1125
 * This is especially useful if you're wrapping the Janus API on your
1126
 * servers, as it allows you to avoid all the noise and overhead introduced
1127
 * by several concurrent HTTP transactions and long polls by relying on
1128
 * what may be seen as a single "control channel".
1129 f500ae8e meetecho
 *
1130
 * To interact with Janus using WebSockets you MUST specify a specific
1131
 * subprotocol, named \c janus-protocol, e.g.,
1132
 *
1133
\verbatim
1134
var websocket = new WebSocket('ws://1.2.3.4:8188', 'janus-protocol');
1135
\endverbatim
1136 54582a6a Lorenzo Miniero
 *
1137 f500ae8e meetecho
 * The \c janus.js library does this automatically.
1138
 *
1139 af40a682 meetecho
 * As anticipated at the beginning of this section, the actual messages
1140
 * being exchanged are exactly the same. This means that all the concepts
1141
 * introduced before still apply: you still create a session, attach to
1142
 * a plugin and interact with it exactly the same way. What is different
1143
 * is, of course, the REST path approach that becomes unavailable when
1144
 * using a WebSocket as a control channel. To address the idenfitiers
1145
 * that become missing using WebSockets, you'll need to add additional
1146
 * fields to the requests when necessary.
1147 54582a6a Lorenzo Miniero
 *
1148 af40a682 meetecho
 * So, when you want to create a session using the REST API, you send a
1149
 * POST to the gateway base path: 
1150 54582a6a Lorenzo Miniero
 *
1151 af40a682 meetecho
\verbatim
1152
{
1153
	"janus" : "create",
1154
	"transaction" : "<random alphanumeric string>"
1155
}
1156
\endverbatim
1157 54582a6a Lorenzo Miniero
 *
1158 af40a682 meetecho
 * The same applies if you're interested in getting generic info from the
1159
 * Janus instance. Since there's no \b GET you can use, a specific \c janus
1160
 * request type called \c info is available:
1161 54582a6a Lorenzo Miniero
 *
1162 af40a682 meetecho
\verbatim
1163
{
1164
	"janus" : "info",
1165
	"transaction" : "<random alphanumeric string>"
1166
}
1167
\endverbatim
1168 54582a6a Lorenzo Miniero
 *
1169 af40a682 meetecho
 * Since you'd contact the base path for both requests, you don't need to add any identifier
1170
 * for this scenario. But if instead you want to attach to a plugin within
1171
 * the context of a specific session, using the REST API you'd send a
1172
 * post to the \c /janus/<session-id> endpoint:
1173 54582a6a Lorenzo Miniero
 *
1174 af40a682 meetecho
\verbatim
1175
{
1176
	"janus" : "attach",
1177
	"plugin" : "<the plugin's unique package name>",
1178
	"transaction" : "<random string>"
1179
}
1180
\endverbatim
1181 54582a6a Lorenzo Miniero
 *
1182 af40a682 meetecho
 * To make this work with WebSockets as well, you need to add a further
1183
 * field called \c session_id in the request:
1184 54582a6a Lorenzo Miniero
 *
1185 af40a682 meetecho
\verbatim
1186
{
1187
	"janus" : "attach",
1188 fae8d5ff meetecho
	"session_id" : <the session identifier>,		// NEW!
1189 af40a682 meetecho
	"plugin" : "<the plugin's unique package name>",
1190
	"transaction" : "<random string>"
1191
}
1192
\endverbatim
1193 54582a6a Lorenzo Miniero
 *
1194 af40a682 meetecho
 * which will allow the WebSocket server to understand which session this
1195
 * request pertains to. At the same time, when you need to address a
1196
 * specific handle (e.g., to send a message to a plugin, or negotiate a
1197
 * WebRTC PeerConnection) you'll need to add a \c handle_id field to the
1198
 * request as well, or the request will be rejected:
1199
 *
1200
\verbatim
1201
{
1202
	"janus" : "message",
1203 fae8d5ff meetecho
	"session_id" : <the session identifier>,		// NEW!
1204
	"handle_id" : <the handle identifier>,		// NEW!
1205 af40a682 meetecho
	"transaction" : "sBJNyUhH6Vc6",
1206
	"body" : {
1207
		"audio" : false
1208
	}
1209
}
1210
\endverbatim
1211
 *
1212
 * Considering the bidirectional nature of WebSockets and the fact that
1213
 * the channel will be shared for different requests, you'll need to pay
1214
 * extra attention to the \c transaction identifier, which will allow you
1215
 * to map incoming responses and events to the request you sent that
1216
 * originated them.
1217 54582a6a Lorenzo Miniero
 *
1218 7d97da92 meetecho
 * An \b important aspect to point out is related to keep-alive messages
1219
 * for WebSockets Janus channels. A Janus session is kept alive as long
1220
 * as there's no inactivity for 60 seconds: if no messages have been
1221
 * received in that time frame, the session is torn down by the gateway.
1222
 * A normal activity on a session is usually enough to prevent that;
1223
 * for a more prolonged inactivity with respect to messaging, on plain
1224
 * HTTP the session is usually kept alive through the regular long poll
1225
 * requests, which act as activity as long as the session is concerned.
1226
 * This aid is obviously not possible when using WebSockets, where a single channel is
1227
 * used both for sending requests and receiving events and responses. For
1228
 * this reason, an ad-hoc message for keeping alive a Janus session should
1229
 * to be triggered on a regular basis:
1230 54582a6a Lorenzo Miniero
 *
1231 7d97da92 meetecho
\verbatim
1232
{
1233
	"janus" : "keepalive",
1234 fae8d5ff meetecho
	"session_id" : <the session identifier>,
1235 7d97da92 meetecho
	"transaction" : "sBJNyUhH6Vc6"
1236
}
1237
\endverbatim
1238 54582a6a Lorenzo Miniero
 *
1239 7d97da92 meetecho
 * This will make sure that the gateway detects activity on the session
1240
 * even when no actual messages are being exchanged with handles.
1241 54582a6a Lorenzo Miniero
 *
1242 af40a682 meetecho
 * As a last point, another slight difference with WebSockets comes from
1243
 * how push notifications are implemented. In the \ref plainhttp this is
1244
 * done via long polls: that is, you explicitly subscribe to notifications,
1245
 * and have to do that again as soon as an event has been received. With
1246
 * WebSockets, this is not needed: as soon as you create a session on a
1247
 * WebSocket, that channel becomes automatically subscribed for events
1248
 * related to that sessions, and you'll receive them on the same WebSocket.
1249
 * For the same reason, as soon as the WebSocket is closed, all the sessions
1250
 * created within its context are considered closed as well, and so their
1251
 * resources (including all the handles and PeerConnections) will be
1252
 * released as well.
1253 54582a6a Lorenzo Miniero
 *
1254 af40a682 meetecho
 * \note The same \c janus.js JavaScript library can be used both with the
1255
 * REST and the WebSockets API: all you need to do is provide the right
1256
 * Janus server address during the initialization and the library will
1257
 * use one or the other according to the protocol prefix.
1258 54582a6a Lorenzo Miniero
 *
1259 ead45815 meetecho
 * \section rabbit RabbitMQ interface
1260
 * The semantics of how the requests have to be built, when compared to
1261
 * the usage of plain HTTP, is exactly the same as for WebSockets, so 
1262
 * refer to the \ref WS documentation for details about that.
1263 54582a6a Lorenzo Miniero
 *
1264 ead45815 meetecho
 * Of course, there are other aspects that differ when making use of 
1265
 * RabbitMQ messaging to talk to Janus, rather than using HTTP messages
1266
 * or WebSockets. Specifically, RabbitMQ just basically forwards messages
1267
 * on queues, and as such implementing a pseudo-bidirectional channel
1268
 * as the Janus API requires needs some precaution.
1269 54582a6a Lorenzo Miniero
 *
1270 ead45815 meetecho
 * In particular, when configuring Janus to use RabbitMQ you'll have to
1271
 * specify \b two \b queues:
1272
 *
1273
 * - a queue for \b incoming messages (application -> Janus);
1274
 * - a queue for \b outgoing messages (Janus -> application).
1275
 *
1276
 * The proper usage of these queues will allow you to implement the kind
1277
 * of bidirectional channel Janus needs.
1278
 *
1279
 * Another aspect to point out is that Janus requires all requests to
1280
 * have a random \c correlation_id identifier. In fact, as pointed out
1281
 * in the previous sections, the Janus API is conceived as a request/response
1282
 * protocol that can involve asynchronous notifications as well. In order
1283
 * to make sure that an application can match a received response to one
1284
 * of the requests made earlier, Janus copies the \c correlation_id
1285
 * identifier from the original request in the response to it: this is
1286
 * compliant with the
1287
 * <a href="https://www.rabbitmq.com/tutorials/tutorial-six-python.html">RPC pattern</a>
1288
 * as specified in the RabbitMQ documentation. Notifications originated by
1289
 * Janus, instead, will not include a \c correlation_id identifier, and as
1290
 * such applications shouldn't expect any: applications will still be able
1291
 * to match a notification to a request, if the involved plugin was
1292
 * implemented to do so, by looking at the Janus-level \c transaction
1293
 * identifier.
1294 54582a6a Lorenzo Miniero
 *
1295 47637450 meetecho
 */
1296 cfd5c0d6 meetecho
1297 263ce349 Lorenzo Miniero
/*! \page auth Authenticating the Janus API
1298
 * By default no authentication is involved when using the Janus API.
1299
 * This means that the API is completely open, and that everybody can
1300
 * talk to Janus and its plugins and set up media connections. There are
1301
 * times, though, where limiting access to Janus may be desirable, e.g.,
1302
 * when you want to prevent unauthorized users to join a service you
1303
 * created, or when you wrap the Janus API in your server and you want
1304
 * your application to be the only one to be able to interact with
1305
 * Janus from a messaging perspective.
1306 54582a6a Lorenzo Miniero
 *
1307 263ce349 Lorenzo Miniero
 * There are a couple of ways to authenticate requests in Janus:
1308 54582a6a Lorenzo Miniero
 *
1309 263ce349 Lorenzo Miniero
 * - using a \ref token (useful for web users);
1310
 * - using a \ref secret (useful when wrapping the Janus API).
1311 54582a6a Lorenzo Miniero
 *
1312 263ce349 Lorenzo Miniero
 * \section token Token based authentication mechanism
1313
 * The token based authentication mechanism expects all users to provide,
1314
 * in each request, a \c token string attribute: if this token is
1315
 * known to Janus, the request will be accepted, otherwise it will be
1316
 * rejected as an \c unauthorized response. Configuring the token based
1317
 * authentication mechanism is easy enough: you can do that either via
1318
 * the command line (\c -A or \c --token-auth ) or in the \c janus.cfg
1319
 * configuration (\c token_auth value in the \c general section).
1320 54582a6a Lorenzo Miniero
 *
1321 263ce349 Lorenzo Miniero
 * These tokens are completely opaque to Janus, meaning they can be
1322
 * pretty much anything that you want. Janus does not do any form of
1323
 * authorization/authentication itself: it's up to you to provide it
1324
 * with valid tokens users can use, e.g., as part of your server-side
1325
 * application handling users. You can add and remove tokens
1326
 * dynamically using the \ref admin, which means you will need to enable
1327
 * it if you want to use tokens, or otherwise all requests will fail
1328
 * (Janus will never have a valid token, so all requests will be rejected).
1329 54582a6a Lorenzo Miniero
 *
1330 263ce349 Lorenzo Miniero
 * You add tokens using the \c add_token admin request, while you
1331 54582a6a Lorenzo Miniero
 * remove them using \c remove_token. You can also limit the scope of tokens
1332
 * to specific plugins, by passing a list of plugins to \c add_token or
1333
 * modifying the token properties via \c allow_token and \c disallow_token.
1334
 * By default (\c add_token without any plugin specified) Janus assumes
1335
 * a new token is allowed to access all plugins. A list of all the
1336
 * existing tokens can be retrieved with a \c list_tokens request.
1337
 *
1338
 * Here are a couple of examples of how you can use the requests:
1339
 *
1340
\verbatim
1341
{
1342
	"janus" : "add_token",
1343
	"token": "a1b2c3d4",
1344
	"transaction" : "sBJNyUhH6Vc6",
1345
	"admin_secret": "adminpassword"
1346
}
1347
\endverbatim
1348
 *
1349
 * This adds a new token (a1b2c3d4) that is allowed to access all the
1350
 * plugins in Janus (no limitation provided in \c add_token ). To create
1351
 * a new token and limit the scope to a few selected plugins, you can
1352
 * use this other syntax instead (notice the extra \c plugins array):
1353
 *
1354 263ce349 Lorenzo Miniero
\verbatim
1355
{
1356
	"janus" : "add_token",
1357
	"token": "a1b2c3d4",
1358 54582a6a Lorenzo Miniero
	"plugins": [
1359
		"janus.plugin.streaming",
1360
		"janus.plugin.videoroom"
1361
	],
1362
	"transaction" : "sBJNyUhH6Vc6",
1363
	"admin_secret": "adminpassword"
1364
}
1365
\endverbatim
1366
 *
1367
 * In this other example, we're creating a new token, and also telling
1368
 * Janus that the only plugins a user with this token can access are
1369
 * the Streaming and Videoroom plugins. An attempt to attach to a
1370
 * different plugin (e.g., EchoTest) will result in an error.
1371
 *
1372
 * You can change the permissions a token has with respect to plugin
1373
 * access at any time. In the following example, we add a new plugin
1374
 * to the permissions for an existing token:
1375
 *
1376
\verbatim
1377
{
1378
	"janus" : "allow_token",
1379
	"token": "a1b2c3d4",
1380
	"plugins": [
1381
		"janus.plugin.echotest"
1382
	],
1383 263ce349 Lorenzo Miniero
	"transaction" : "sBJNyUhH6Vc6",
1384
	"admin_secret": "adminpassword"
1385
}
1386
\endverbatim
1387 54582a6a Lorenzo Miniero
 *
1388
 * This way, the provided token is now also allowed to access the EchoTest
1389
 * plugin. To remove a permission, the syntax is this one instead:
1390
 *
1391
\verbatim
1392
{
1393
	"janus" : "disallow_token",
1394
	"token": "a1b2c3d4",
1395
	"plugins": [
1396
		"janus.plugin.videoroom"
1397
	],
1398
	"transaction" : "sBJNyUhH6Vc6",
1399
	"admin_secret": "adminpassword"
1400
}
1401
\endverbatim
1402
 *
1403
 * To retrieve a list of all the valid tokens Janus is aware of, together
1404
 * with the plugins each of them is allowed to access, a \c list_tokens
1405
 * request can be used:
1406
 *
1407
\verbatim
1408
{
1409
	"janus" : "list_tokens",
1410
	"transaction" : "sBJNyUhH6Vc6",
1411
	"admin_secret": "adminpassword"
1412
}
1413
\endverbatim
1414
 *
1415
 * Finally, you can get rid of a token using a \c remove_token request:
1416
 *
1417 263ce349 Lorenzo Miniero
\verbatim
1418
{
1419
	"janus" : "remove_token",
1420
	"token": "a1b2c3d4",
1421
	"transaction" : "sBJNyUhH6Vc6",
1422
	"admin_secret": "adminpassword"
1423
}
1424
\endverbatim
1425 54582a6a Lorenzo Miniero
 *
1426 263ce349 Lorenzo Miniero
 * As anticipated, with the token based mechanism enabled, all users
1427
 * will need to provide a valid token as part of their requests. This is
1428
 * done by adding a \c token attribute to the request root, e.g.:
1429 54582a6a Lorenzo Miniero
 *
1430 263ce349 Lorenzo Miniero
\verbatim
1431
{
1432
	"janus" : "create",
1433
	"transaction" : "sBJNyUhH6Vc6",
1434
	"token": "usertoken"
1435
}
1436
\endverbatim
1437 54582a6a Lorenzo Miniero
 *
1438 263ce349 Lorenzo Miniero
 * The same applies for the long poll GET messages as well, which will
1439
 * need to contain the \c token as a query string parameter.
1440 54582a6a Lorenzo Miniero
 *
1441 263ce349 Lorenzo Miniero
 * A valid token will mean the request will be accepted and processed
1442
 * normally. A missing or invalid token, instead, will result in an
1443
 * error being returned:
1444 54582a6a Lorenzo Miniero
 *
1445 263ce349 Lorenzo Miniero
\verbatim
1446
{
1447
	"janus" : "error",
1448
	"transaction" : "sBJNyUhH6Vc6",
1449
	"error" : {
1450
		"code" : 403,
1451
		"reason" : "Unauthorized request (wrong or missing secret/token)"
1452
	}
1453 54582a6a Lorenzo Miniero
}
1454
\endverbatim
1455
 *
1456
 * An attempt to use a valid token to attach to a plugin it is not
1457
 * allowed to access, instead, will result in a different error:
1458
 *
1459
\verbatim
1460
{
1461
	"janus" : "error",
1462
	"transaction" : "sBJNyUhH6Vc6",
1463
	"error" : {
1464
		"code" : 405,
1465
		"reason" : "Provided token can't access plugin 'janus.plugin.echotest'"
1466
	}
1467
}
1468 263ce349 Lorenzo Miniero
\endverbatim
1469 54582a6a Lorenzo Miniero
 *
1470 263ce349 Lorenzo Miniero
 * \section secret Shared static secret
1471
 * Several deployers showed an interested in wrapping the Janus API on
1472
 * their server side: this allows them to keep the interaction with their
1473
 * users the way it was before, while still benefiting from the features
1474
 * Janus provides. This is an easy enough step, as it just needs developers
1475
 * to relay the involved SDP, and implementing the Janus API messages to
1476
 * handle the logic.
1477
 *
1478
 * That said, since in this case Janus would be contacted, through the API,
1479
 * just by a limited number of applications (e.g., application servers
1480
 * made in node.js, Ruby, Java Servlets or whatever) and not random
1481
 * browsers, it is reasonable to involve a mechanism to control who is
1482
 * allowed to contact and control it. The previous section described
1483
 * how you can exploit a token based mechanism for authenticating
1484
 * requests, but since in this case you only need a single application,
1485
 * or a limited set of them,
1486
 * to be able to talk to Janus, it's worthwhile to resort to something
1487
 * simpler and more static. To allow for that, Janus also exposes a
1488
 * shared API secret mechanism: that is, you configure Janus with a string
1489
 * applications need to present when sending requests, and if they don't,
1490
 * Janus rejects them with an \c unauthorized message.
1491 54582a6a Lorenzo Miniero
 *
1492 263ce349 Lorenzo Miniero
 * Configuring the API secret mechanism is easy enough: you can do that
1493
 * either via the command line (\c -a or \c --apisecret ) or in the
1494
 * \c janus.cfg configuration (\c api_secret value in the \c general section).
1495
 * When enabled, all requests addressed to that Janus instance \b MUST
1496
 * also contain an \c apisecret field in the Janus message headers. For
1497
 * instance, this message presented above would fail:
1498 54582a6a Lorenzo Miniero
 *
1499 263ce349 Lorenzo Miniero
\verbatim
1500
{
1501
	"janus" : "create",
1502
	"transaction" : "<random alphanumeric string>"
1503
}
1504
\endverbatim
1505 54582a6a Lorenzo Miniero
 *
1506 263ce349 Lorenzo Miniero
\verbatim
1507
{
1508
	"janus" : "error",
1509
	"transaction" : "<same as request>"
1510
	"error" : {
1511
		"code" : 403,
1512
		"reason" : "Unauthorized request (wrong or missing secret/token)"
1513
	}
1514
}
1515
\endverbatim
1516 54582a6a Lorenzo Miniero
 *
1517 263ce349 Lorenzo Miniero
 * For a successful transaction, the message would have to look like this:
1518 54582a6a Lorenzo Miniero
 *
1519 263ce349 Lorenzo Miniero
\verbatim
1520
{
1521
	"janus" : "create",
1522
	"apisecret" : "<API secret configured in Janus>",
1523
	"transaction" : "<random alphanumeric string>"
1524
}
1525
\endverbatim
1526 54582a6a Lorenzo Miniero
 *
1527 263ce349 Lorenzo Miniero
 * The same applies for the long poll GET messages as well, which will
1528
 * need to contain the \c apisecret as a query string parameter.
1529 54582a6a Lorenzo Miniero
 *
1530 263ce349 Lorenzo Miniero
 */
1531
1532 ecb79ec6 meetecho
/*! \page admin Admin/Monitor API
1533
 * Recent versions of Janus introduced a new feature: an Admin/Monitor
1534
 * API that can be used to ask Janus for more specific information
1535
 * related to sessions and handles. This is especially useful when you
1536
 * want to debug issues at the media level.
1537
 *
1538 263ce349 Lorenzo Miniero
 * \note Right now, this new API mostly allows you to retrieve information,
1539
 * but only act on part of it: for more interaction (e.g., to force a
1540 ead45815 meetecho
 * session removal), you can rely on the existing \ref rest for the purpose.
1541 ecb79ec6 meetecho
 *
1542 4610cf26 Lorenzo Miniero
 * The API, for security reasons, is typically noy enabled by default in any of the
1543 09ac2273 meetecho
 * transport plugins: that's definitely the case for the stock transport
1544
 * plugins, for instance, while additional, third party plugins may choose
1545
 * to expose the functionality without requiring any tweaking. As to the
1546 4610cf26 Lorenzo Miniero
 * existing transport, you can enable the admin API by editing the \c [ \c admin \c ]
1547 09ac2273 meetecho
 * section in the related transport configuration file (e.g., \c janus.transport.http.cfg
1548
 * for the REST interface, to use the admin API over HTTP). The configuration
1549
 * is pretty much the same as the one for the Janus API. In addition, you
1550 ecb79ec6 meetecho
 * can configure restrictions in the form of a password/secret that clients
1551 09ac2273 meetecho
 * need to provide or other transport-specific ones.
1552 ecb79ec6 meetecho
 *
1553
 * For what concerns the syntax, it's very similar to the \ref rest and
1554 ead45815 meetecho
 * so this page will briefly discuss the differences. At the moment, a few
1555 ecb79ec6 meetecho
 * different methods are exposed:
1556
 *
1557
 * - \c list_sessions: list all the sessions currently active in Janus
1558
 * (returns an array of session identifiers);
1559
 * - \c list_handles: list all the ICE handles currently active in a Janus
1560
 * session (returns an array of handle identifiers);
1561 ead45815 meetecho
 * - \c handle_info: list all the available info on a specific ICE handle;
1562
 * - \c set_log_level: change the log level in Janus on the fly;
1563
 * - \c set_locking_debug: selectively enable/disable a live debugging of
1564
 * the locks in Janus on the fly (useful if you're experiencing deadlocks
1565 263ce349 Lorenzo Miniero
 * and want to investigate them);
1566
 * - \c add_token: add a valid token (only available if you enabled the \ref token);
1567 54582a6a Lorenzo Miniero
 * - \c allow_token: give a token access to a plugin (only available if you enabled the \ref token);
1568
 * - \c disallow_token: remove a token access from a plugin (only available if you enabled the \ref token);
1569
 * - \c list_tokens: list the existing tokens (only available if you enabled the \ref token);
1570 263ce349 Lorenzo Miniero
 * - \c remove_token: remove a token (only available if you enabled the \ref token).
1571 ecb79ec6 meetecho
 *
1572
 * Following the same spirit of the \ref rest these methods need to be
1573
 * invoked on the right path and/or providing the right \c session_id and
1574
 * \c handle_id identifiers. Specifically, \c list_sessions must be invoked
1575
 * without any session/handle information, as it's a global request. Here's
1576
 * an example of how such a request and its related response might look like:
1577
 *
1578
\verbatim
1579
POST /admin
1580
{
1581
	"janus" : "list_sessions",
1582
	"transaction" : "<random alphanumeric string>",
1583
	"admin_secret" : "<password specified in janus.cfg, if any>"
1584
}
1585
\endverbatim
1586
 *
1587
 *
1588
\verbatim
1589
{
1590
	"janus" : "success",
1591
	"transaction" : "<same as the request>",
1592
	"sessions" : [
1593
		<session ID #1>,
1594
		<session ID #2>,
1595
		[..]
1596
		<session ID #n>
1597
	]
1598
}
1599
\endverbatim
1600
 *
1601
 * On the other hand, since \c list_handles is related to a specific session,
1602
 * a session must be referenced correctly. Using the REST API, this can
1603
 * be done by appending the session identifier (e.g., one of the IDs
1604
 * returned by the previous call) to the API root:
1605
 *
1606
\verbatim
1607
POST /admin/12345678
1608
{
1609
	"janus" : "list_handles",
1610
	"transaction" : "<random alphanumeric string>",
1611
	"admin_secret" : "<password specified in janus.cfg, if any>"
1612
}
1613
\endverbatim
1614
 *
1615
 *
1616
\verbatim
1617
{
1618
	"janus" : "success",
1619
	"transaction" : "<same as the request>",
1620
	"session_id" : 12345678,
1621
	"handles" : [
1622
		<handle ID #1>,
1623
		<handle ID #2>,
1624
		[..]
1625
		<handle ID #n>
1626
	]
1627
}
1628
\endverbatim
1629
 *
1630
 * Once a list of handles is available, detailed info on any of them can
1631
 * be obtained by means of a \c handle_info call. Since this is a
1632
 * handle-specific request, the correct handle identifier must be
1633
 * referenced, e.g., by appending the ID to the session it belongs to:
1634
 *
1635
\verbatim
1636
POST /admin/12345678/98765432
1637
{
1638
	"janus" : "handle_info",
1639
	"transaction" : "<random alphanumeric string>",
1640
	"admin_secret" : "<password specified in janus.cfg, if any>"
1641
}
1642
\endverbatim
1643
 *
1644
 *
1645
\verbatim
1646
{
1647
	"janus" : "success",
1648
	"transaction" : "<same as the request>",
1649
	"session_id" : 12345678,
1650
	"handle_id" : 98765432,
1651
	"info" : {
1652 09ac2273 meetecho
		"session_id" : 12345678,
1653
		"session_last_activity": 7927759122,
1654
		"session_transport": "janus.transport.websockets",
1655
		"handle_id" : 98765432,
1656 ecb79ec6 meetecho
		"plugin": "janus.plugin.echotest",
1657 09ac2273 meetecho
		"plugin_specific": {
1658
			// plugin specific (e.g., EchoTest internals)
1659
		},
1660 ecb79ec6 meetecho
		"flags": {
1661
			// flags
1662
		},
1663
		"sdps": {
1664
			"local": "v=0[..]",
1665
			"remote": "v=0[..]"
1666
		},
1667
		"streams": [
1668
			// streams, components, etc.
1669
		]
1670
	}
1671
}
1672
\endverbatim
1673
 *
1674
 * The actual content of the last response is omitted for brevity, but
1675
 * you're welcome to experiment with it in order to check whether more
1676 09ac2273 meetecho
 * information (of a different nature, maybe) may be useful to have. In
1677
 * particular, you may want to play with the plugin-specific details, as
1678
 * different plugins will return different information according to what
1679
 * they provide: for instance, the videoroom plugin might clarify whether
1680
 * a handle is being used for publishing media or for receiving it, and
1681
 * what are the involved IDs, the current status of the delivery, and so on.
1682
 * At the same time, the \c streams object will contain invaluable details
1683
 * related to the WebRTC PeerConnection associated with the handle, as
1684
 * in input/output statistics statistics (bytes, bytes per seconds, NACKs,
1685
 * etc.) or the SDP/ICE/DTLS states.
1686 ecb79ec6 meetecho
 *
1687 ead45815 meetecho
 * Finally, the syntax for the \c set_log_level and \c set_locking_debug
1688
 * commands is quite straightforward:
1689
 *
1690
\verbatim
1691
POST /admin
1692
{
1693
	"janus" : "set_log_level",
1694
	"level" : <integer between 0 and 7, see debug.h>,
1695
	"transaction" : "<random alphanumeric string>",
1696
	"admin_secret" : "<password specified in janus.cfg, if any>"
1697
}
1698
\endverbatim
1699
 *
1700
\verbatim
1701
POST /admin
1702
{
1703
	"janus" : "set_locking_debug",
1704
	"debug" : <0 to disable, 1 to enable>,
1705
	"transaction" : "<random alphanumeric string>",
1706
	"admin_secret" : "<password specified in janus.cfg, if any>"
1707
}
1708
\endverbatim
1709
 *
1710
 * Both commands will return the updated level/debug setting if successful,
1711
 * and an error otherwise.
1712
 *
1713 09ac2273 meetecho
 * To conclude, all of the above mentioned examples have assumed an usage
1714
 * of HTTP to interact with the Admin API. The same considerations already
1715
 * made for the Janus API as to the usage of different transports (WebSockets,
1716
 * RabbitMQ or others) apply here as well, particularly with respect to
1717
 * the explicit \c session_id and \c handle_id in the JSON payload.  
1718
 *
1719 ecb79ec6 meetecho
 */
1720
1721 cfd5c0d6 meetecho
/*! \page deploy Deploying Janus
1722
 *
1723
 * When you're going to deploy Janus (e.g., to try the demos we made
1724
 * available out-of-the-box), there's one thing that is important to point
1725
 * out: while Janus does indeed provide an HTTP RESTful interface (documented
1726
 * in \ref rest), it does \b NOT also act as a webserver for static files.
1727
 * This means you'll need a different webserver to host static files, including
1728
 * HTML/PHP/JSP/etc. pages, JavaScript files, images and whatever is part
1729
 * of your web application.
1730
 *
1731
 * That said, deploying Janus is, in principle, quite simple: just start Janus on a
1732
 * machine, put the HTML and JavaScript that will make use of it on a webserver
1733
 * somewhere, make sure the JavaScript code is configured with the right
1734
 * address for the gateway and you're done!
1735
 *
1736
 * Let's assume, for the sake of simplicity, that your webserver is serving
1737
 * files on port \c 80. By default, Janus binds on the \c 8088 port for HTTP.
1738
 * So, if Janus and the webserver hosting the are co-located, all you need to get your 
1739
 * application working is configure the web application to point to the right
1740
 * address for the gateway. In the demos provided with these packages, this
1741
 * is done by means of the \c server variable:
1742
 *
1743 1f2c037b Lorenzo Miniero
 \verbatim
1744 cfd5c0d6 meetecho
var server = "http://" + window.location.hostname + ":8088/janus";
1745
 \endverbatim
1746
 *
1747
 * which basically tells the JavaScript application that the Janus API can be
1748
 * contacted at the same host as the website but at a different port (8088) and path (/janus). 
1749
 * In case you configured the gateway differently, e.g., 7000 as the port 
1750
 * for HTTP and /my/custom/path as the API endpoint, the \c server variable
1751
 * could be built this way:
1752
 *
1753 1f2c037b Lorenzo Miniero
 \verbatim
1754 cfd5c0d6 meetecho
var server = "http://" + window.location.hostname + ":7000/my/custom/path";
1755
 \endverbatim
1756
 *
1757
 * In case the webserver and Janus are <b>NOT</b> colocated, instead, just
1758
 * replace the \c window.location.hostname part with the right address of
1759
 * the gateway, e.g.:
1760
 *
1761 1f2c037b Lorenzo Miniero
 \verbatim
1762 cfd5c0d6 meetecho
var server = "http://www.example.com:8088/janus";
1763
 \endverbatim
1764
 *
1765
 * It's important to point out, though, that this more "static" approach
1766
 * only works if the webserver is serving files via HTTP. As soon as you
1767
 * start involving \b HTTPS, things start to get more complicated: in fact,
1768
 * for security reasons you cannot contact an HTTP backend if the page is
1769
 * made available via HTTPS. This means that if you're interested in serving
1770
 * your web application via HTTPS, you'll need to enable the HTTPS embedded
1771
 * webserver in Janus as well, and configure the JavaScript code to refer to
1772
 * that itself, e.g.:
1773
 *
1774 1f2c037b Lorenzo Miniero
 \verbatim
1775 cfd5c0d6 meetecho
var server = "https://" + window.location.hostname + ":8089/janus";
1776
 \endverbatim
1777
 *
1778
 * assuming \c 8089 is the port you configured Janus to use for HTTPS.
1779
 * To make this more "dynamic", e.g., allow both HTTP and HTTPS instead of
1780
 * just sticking to one, you might make use of something like this:
1781
 *
1782 1f2c037b Lorenzo Miniero
 \verbatim
1783 cfd5c0d6 meetecho
var server = null;
1784
if(window.location.protocol === 'http:')
1785
	server = "http://" + window.location.hostname + ":8088/janus";
1786
else
1787
	server = "https://" + window.location.hostname + ":8089/janus";
1788
 \endverbatim
1789
 *
1790
 * that is evaulate the right address to use at runtime.
1791
 *
1792
 * Anyway, there's a much easier way to address these scenarios, which
1793
 * is explained in the next section.
1794
 *
1795
 * \section apache Deploying Janus behind a web frontend
1796
 *
1797
 * To avoid most of the issues explained above, an easy approach can be
1798
 * deploying Janus behind a frontend, that would act as a reverse proxy for it.
1799
 * This would allow you to make the Janus API available as a relative path 
1800
 * of your web application, rather than a service reachable at a different
1801
 * port and/or domain.
1802
 *
1803
 * Configuring the web application, as a consequence, would be even easier,
1804
 * as all you'd need to do would be to provide a relative path for the API,
1805
 * e.g.:
1806
 *
1807 1f2c037b Lorenzo Miniero
 \verbatim
1808 cfd5c0d6 meetecho
var server = "/janus";
1809
 \endverbatim
1810
 *
1811
 * which would automatically work whether the page is served via HTTP or
1812
 * HTTPS. In fact, all the HTTPS requests would be terminated at the webserver,
1813
 * which would then always send simple HTTP messages to the gateway itself.
1814
 *
1815
 * An easy way to do so in Apache HTTPD is by means of the following directives:
1816
 *
1817 1f2c037b Lorenzo Miniero
 \verbatim
1818 cfd5c0d6 meetecho
ProxyRequests Off
1819
ProxyVia Off
1820
ProxyPass /janus http://127.0.0.1:8088/janus
1821
ProxyPassReverse /janus http://127.0.0.1:8088/janus
1822
 \endverbatim
1823
 *
1824
 * Different versions of HTTPD or different webservers may require a
1825
 * different syntax, but the principle is usually always the same: you instruct
1826
 * the webserver to act as a proxy for a local endpoint, in this case a
1827
 * Janus instance colocated at the webserver and configured with the
1828
 * default settings.
1829
 *
1830
 * \section webserver A quick and easy web server
1831 468315f1 meetecho
 * While opening WebRTC-powered web applications by just opening the
1832
 * application HTML files from file system works with some browsers, it
1833
 * doesn't in others. Specifically, this works in Firefox but not in Chrome
1834
 * (see <a href="https://github.com/meetecho/janus-gateway/issues/291">issue #291</a>).
1835
 * Anyway, considering that you will eventually want other people besides
1836
 * you to use your Janus services, this means that to test and use Janus
1837
 * you'll want/need to host your applications on a webserver.
1838 54582a6a Lorenzo Miniero
 *
1839 cfd5c0d6 meetecho
 * If you're not interested in configuring a full-fledged webserver, but
1840
 * are only interested in a quick and easy way to test the demos, you can
1841
 * make use of the embedded webservers some frameworks like PHP and Python
1842
 * provide. To start a webserver for the demos, for instance, just open a
1843
 * terminal in the \c html folder of the project, and type:
1844
 *
1845
 *\verbatim
1846
php -S 0.0.0.0:8000
1847
 \endverbatim
1848
 *
1849
 * or:
1850
 *
1851
 *\verbatim
1852
python -m SimpleHTTPServer 8000
1853
 \endverbatim
1854
 *
1855
 * This will setup a webserver on port \c 8000 for you to use, meaning you'll
1856
 * just need to have your browser open a local connection to that port to 
1857
 * try the demos:
1858
 *
1859
 *\verbatim
1860
http://yourlocaliphere:8000
1861
 \endverbatim
1862
 *
1863
 * You can do the same on a different port to also access the HTML version of the Doxygen generated
1864
 * documentation, starting the embedded webservers from the \c docs/html
1865
 * folder instead:
1866
 *
1867
 *\verbatim
1868
php -S 0.0.0.0:9000
1869
 \endverbatim
1870
 *
1871
 * or:
1872
 *
1873
 *\verbatim
1874
python -m SimpleHTTPServer 9000
1875
 \endverbatim
1876
 *
1877 d961635a meetecho
 * \section deplyws Using Janus with WebSockets 
1878 af40a682 meetecho
 *
1879
 * Configuring the usae of WebSockets rather than the REST API in the JavaScript
1880
 * library is quite trivial, as it's a matter of passing a \c ws:// address
1881
 * instead of an \c http:// one to the constructor. That said, most of the same
1882
 * considerations provided for the REST API apply here as well, e.g.,
1883
 * to just use \c window.location.hostname if the webserver and Janus are
1884
 * colocated:
1885
 *
1886 1f2c037b Lorenzo Miniero
 \verbatim
1887 af40a682 meetecho
var server = "ws://" + window.location.hostname + ":8188/";
1888
 \endverbatim
1889
 *
1890
 * to specify the port if you change it:
1891
 *
1892 1f2c037b Lorenzo Miniero
 \verbatim
1893 af40a682 meetecho
var server = "ws://" + window.location.hostname + ":7000/";
1894
 \endverbatim
1895
 *
1896
 * and/or the right address of the gateway in case the webserver and Janus
1897
 * are <b>NOT</b> colocated:
1898
 *
1899 1f2c037b Lorenzo Miniero
 \verbatim
1900 af40a682 meetecho
var server = "ws://www.example.com:8188/";
1901
 \endverbatim
1902
 *
1903
 * Notice how the path (\c /janus by default for HTTP) is not provided
1904
 * for WebSockets, as it is ignored by the gateway.
1905
 *
1906
 * The considerations for deploying Janus behind a proxy/webserver, though,
1907
 * differ if you use WebSockets. Instead, most webservers (e.g., Apache HTTPD)
1908
 * don't provide an easy way to proxy WebSocket requests, and usually
1909
 * require custom modifications for the purpose. If this is something
1910
 * you're interested in, we recommend you follow the best practices related
1911
 * to that made available by the web server developers.
1912
 *
1913 d961635a meetecho
 * \section both Using fallback addresses 
1914
 * As anticipated in the \ref JS section, you can also pass an array of servers
1915
 * to the Janus library initialization. This allows you, for instance, to
1916
 * pass a link to both the WebSockets and REST interfaces, and have the
1917
 * library try them both to see which one is reachable, e.g.:
1918
 *
1919
 \verbatim
1920
var ws_server = "ws://" + window.location.hostname + ":8188/";
1921
var http_server = "http://" + window.location.hostname + ":8088/janus";
1922
var servers = [ws_server, http_server];
1923
 \endverbatim
1924
 *
1925
 * which is especially useful if you're not sure whether or not WebSockets
1926
 * will work in some specific networks. Please notice that, for the individual
1927
 * servers listed in the array, the same considerations given above (e.g.,
1928
 * in terms of relative vs. absolute linking) still apply.
1929
 *
1930
 * Such an approach can also be used when you've deployed several different
1931
 * instances of Janus, and you want the library to try some and fallback
1932
 * to others if any of them is not reachable for any reason.
1933
 *
1934 cfd5c0d6 meetecho
 */
1935 1f2c037b Lorenzo Miniero
1936 86b169e3 Lorenzo Miniero
/*! \page service Janus as a daemon/service
1937 1f2c037b Lorenzo Miniero
 *
1938 7091a464 Lorenzo Miniero
 * By default, Janus starts in foreground, and as such works as a server
1939
 * application that you start normally and displays output on the console.
1940 1f2c037b Lorenzo Miniero
 * That said, there are several reasons why you may not want to keep
1941
 * Janus in the foreground, while still being interested in checking
1942
 * the console to see what's happening.
1943
 *
1944
 * There are different ways to "daemonize" it and have it run as a service,
1945
 * though. This page tries to summarize a few ways to do so, starting
1946
 * from "dumb" approaches like sending to background and/or using screen/tmux,
1947
 * to more sophisticated approaches involving \c systemd, \c upstart
1948
 * and others.
1949
 *
1950 7091a464 Lorenzo Miniero
 * \section daemon Running Janus as a daemon
1951
 * Since version \c 0.1.0, you can run Janus as a daemon application. To
1952
 * do so, just pass either \c -b or <code>\--daemon</code> as a command line
1953
 * argument, and Janus will be daemonized. Just beware, though, that
1954 f82a8605 Lorenzo Miniero
 * since this results in stdout/stdin/stderr being closed, you MUST
1955
 * specify a log file for Janus to use, either via command line (\c -L
1956
 * or <code>\--log-file) or in \c janus.cfg.
1957 7091a464 Lorenzo Miniero
 *
1958 1f2c037b Lorenzo Miniero
 * \section bg Running in background
1959 7091a464 Lorenzo Miniero
 * Another simple way to run Janus in the background is to just append the
1960 1f2c037b Lorenzo Miniero
 * \c & character to the command line. Anyway, this will still "flood" the console
1961
 * with output from Janus. While there are ways to handle it (e.g., as
1962
 * explained <a href="http://www.thegeekstuff.com/2010/05/unix-background-job/">here</a>),
1963
 * a nice and easy way to handle this is redirecting the output to a 
1964
 * separate file, e.g., a dedicated log:
1965
 *
1966
 \verbatim
1967
/opt/janus/bin/janus -d 5 -6 >/path/to/mylogfile 2>&1 &
1968
 \endverbatim
1969
 *
1970
 * This is especially useful in case you want to keep a log of what
1971
 * happened when Janus was running, and can also be used as a simple and
1972
 * effective way to watch the console "live" using \c tail:
1973
 \verbatim
1974
tail -f /path/to/mylogfile
1975
 \endverbatim
1976
 *
1977
 * \section screen Terminal multiplexers
1978
 * Another easy way to run Janus in the background is using terminal
1979
 * multiplexers like \c screen or \c tmux. If you're not familiar with
1980
 * such applications, you can find a quick overview
1981
 * <a href="https://en.wikipedia.org/wiki/Terminal_multiplexer">here</a>.
1982
 *
1983
 * The following is a simple example with \c screen:
1984
 *
1985
 \verbatim
1986
screen -S janus -d -m
1987
screen -r janus -X stuff $'/opt/janus/bin/janus -d 5 -6\n'
1988
 \endverbatim
1989
 *
1990
 * This will create a session called "janus" and launch Janus in it with
1991
 * a few command line options (in this case, just the option to enable
1992
 * IPv6 support and set the debug to verbose). Janus will then be running
1993
 * in the background: accessing the console is just a matter of attaching
1994
 * to the "janus" screen: 
1995
 *
1996
 \verbatim
1997
screen -r janus
1998
[CTRL+A+D to detach again]
1999
 \endverbatim
2000
 *
2001
 * Terminal multiplexers usually allow for logging the output to file
2002
 * as well, if you want to keep an history of what happened during the
2003
 * Janus lifetime.
2004
 *
2005
 * \section systemd systemd
2006 b5bc8c12 Saúl Ibarra Corretgé
 * This section shows how you can add Janus as a service to
2007 1f2c037b Lorenzo Miniero
 * <a href="https://en.wikipedia.org/wiki/Systemd">systemd</a>.
2008
 *
2009
 \verbatim
2010
[Unit]
2011
Description=Janus WebRTC gateway
2012
After=network.target
2013
2014
[Service]
2015
Type=simple
2016 b5bc8c12 Saúl Ibarra Corretgé
ExecStart=/opt/janus/bin/janus -o
2017 1f2c037b Lorenzo Miniero
Restart=on-abnormal
2018 3d5b4b5f Ancor Gonzalez Sosa
LimitNOFILE=65536
2019 1f2c037b Lorenzo Miniero
2020
[Install]
2021
WantedBy=multi-user.target
2022
 \endverbatim
2023
 *
2024 b5bc8c12 Saúl Ibarra Corretgé
 * \note Remember to adjust the path in ExecStart to match the Janus binary path.
2025
 *
2026 00991fc1 Lorenzo Miniero
 * \warning Please beware that, per the default \c RateLimitInterval and
2027
 * and \c RateLimitBurst values in the default sytemd configuration, logger
2028
 * messages are dropped if they arrive faster than ~33 per second. You
2029
 * may want to configure them accordingly, or otherwise Janus log messages
2030 151f41e6 Lorenzo Miniero
 * may be missing. To fix this, setting <code>RateLimitInterval=1s</code>
2031
 * and <code>RateLimitBurst=2000</code> in
2032 00991fc1 Lorenzo Miniero
 * <code>/etc/systemd/journald.conf</code> is usually enough.
2033
 *
2034 1f2c037b Lorenzo Miniero
 * \note systemd example provided by
2035
 * <a href="https://github.com/meetecho/janus-gateway/pull/306">\@saghul</a> 
2036
 *
2037
 * \section upstart upstart
2038 86b169e3 Lorenzo Miniero
 * This section shows how you can add Janus as a daemon to
2039
 * <a href="http://upstart.ubuntu.com/">upstart</a>, which is
2040
 * typically available on Ubuntu systems.
2041
 *
2042
 \verbatim
2043
description "janus"
2044
2045
start on filesystem or runlevel [2345]
2046
stop on runlevel [!2345]
2047
limit nofile 50000 50000
2048
limit core unlimited unlimited
2049
2050
respawn
2051
respawn limit 10 5
2052
2053
exec /opt/janus/bin/janus
2054
 \endverbatim
2055
 *
2056
 * \note upstart example provided by
2057
 * <a href="https://github.com/meetecho/janus-gateway/pull/306">\@ploxiln</a> 
2058 1f2c037b Lorenzo Miniero
 *
2059 9314d8e4 Saúl Ibarra Corretgé
 * \section sysvinit sysvinit
2060
 * This section shows how you can add Janus as a daemon to
2061
 * SysVinit based systems.
2062
 *
2063
 \verbatim
2064
#!/bin/sh
2065
2066
### BEGIN INIT INFO
2067
# Provides:          Janus
2068
# Required-Start:    $remote_fs $syslog
2069
# Required-Stop:     $remote_fs $syslog
2070
# Default-Start:     2 3 4 5
2071
# Default-Stop:      0 1 6
2072
# Short-Description: Janus WebRTC gateway
2073
# Description:       Janus WebRTC gateway
2074
### END INIT INFO
2075
2076
DAEMON=/usr/bin/janus
2077
DAEMON_NAME=janus
2078
2079
# Add any command line options for your daemon here
2080
DAEMON_OPTS="-D -o"
2081
2082
# This next line determines what user the script runs as.
2083
# Root generally not recommended but necessary if you are using the Raspberry Pi GPIO from Python.
2084
DAEMON_USER=root
2085
2086
# The process ID of the script when it runs is stored here:
2087
PIDFILE=/var/run/$DAEMON_NAME.pid
2088
2089
. /lib/lsb/init-functions
2090
2091
do_start () {
2092
    log_daemon_msg "Starting system $DAEMON_NAME daemon"
2093
    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
2094
    log_end_msg $?
2095
}
2096
do_stop () {
2097
    log_daemon_msg "Stopping system $DAEMON_NAME daemon"
2098
    start-stop-daemon --stop --pidfile $PIDFILE --retry 10
2099
    log_end_msg $?
2100
}
2101
2102
case "$1" in
2103
2104
    start|stop)
2105
        do_${1}
2106
        ;;
2107
2108
    restart|reload|force-reload)
2109
        do_stop
2110
        do_start
2111
        ;;
2112
2113
    status)
2114
        status_of_proc "$DAEMON_NAME" "$DAEMON" && exit 0 || exit $?
2115
        ;;
2116
2117
    *)
2118
        echo "Usage: /etc/init.d/$DAEMON_NAME {start|stop|restart|status}"
2119
        exit 1
2120
        ;;
2121
2122
esac
2123
exit 0
2124
 \endverbatim
2125
 *
2126
 * \note sysvinit example provided by
2127
 * <a href="https://github.com/saghul">\@saghul</a> 
2128
 *
2129 1f2c037b Lorenzo Miniero
 * \section Others
2130
 * TODO.
2131
 *
2132
 */
2133 47637450 meetecho
 
2134 9355a077 Lorenzo Miniero
/*! \page debug Debugging Janus
2135
 *
2136
 * In the magical world of fairies and unicorns, the sun always shines
2137
 * and everything always works smoothly and without issues. Unfortunately,
2138
 * this is not the world we live in, and so you might still encounter
2139
 * issues using Janus, e.g., unexpected crashes and the like. We always
2140
 * try and tackle bugs as soon as we spot them, but some issues may be
2141
 * always lingering in the background.
2142
 *
2143
 * Should you encounter a bug or a crash, open a new
2144
 * <a href="https://github.com/meetecho/janus-gateway/issues/new">issue</a>
2145
 * on GitHub. Make sure you carefully read the
2146
 * <a href="https://github.com/meetecho/janus-gateway/blob/master/CONTRIBUTING.md">guidelines</a>
2147
 * for contributing, or otherwise we may decide to close the issue and
2148
 * not even look at it.
2149
 *
2150
 * What's important for us to look into issues and bugs definitely is
2151
 * having enough information to do so. As such, whenever possible try to
2152
 * provide as many details and data as possible. Quite useful to us are
2153
 * GDB stacktraces and/or AddressSanitizer output. The following sections
2154
 * give a quick overview on how you can collect this information after
2155
 * a crash, but for a more detailed description of the tools you should
2156
 * refer to the related documentation pages and tutorials.
2157
 *
2158
 * \section gdb GDB
2159
 * GDB is the <a href="http://www.gnu.org/software/gdb/">GNU Project Debugger</a>
2160
 * and is an effective tool for looking at what has happened (or is
2161
 * happening) inside an application. As such, it's quite useful to spot
2162
 * bugs and the like, as it can provide information about the values of
2163
 * variables when they were used and the application crashed.
2164 54582a6a Lorenzo Miniero
 *
2165 9355a077 Lorenzo Miniero
 * When Janus crashes, you should get a core dump file somewhere. This is
2166
 * a recorded state of the application memory at the time of crashing, and
2167
 * so a backtrace of what lead to an issue can help. You can open such
2168
 * a core dump file via gdb this way:
2169 54582a6a Lorenzo Miniero
 *
2170 9355a077 Lorenzo Miniero
 \verbatim
2171
gdb /path/to/bin/janus /path/to/coredump
2172
gdb bt
2173
 \endverbatim
2174 54582a6a Lorenzo Miniero
 *
2175 9355a077 Lorenzo Miniero
 * The \c bt command retrieves the backtrace, and is what you should provide
2176
 * as part of your new issue.
2177 54582a6a Lorenzo Miniero
 *
2178 9355a077 Lorenzo Miniero
 * \note Please \c DON'T paste this backtrace in the issue text. Use a
2179
 * service like <a href="https://gist.github.com/">Gist</a> or
2180
 * <a href="http://pastebin.com/">Pastebin</a> and pass the generated
2181
 * link instead.
2182 54582a6a Lorenzo Miniero
 *
2183 9355a077 Lorenzo Miniero
 * \section sanitizer Address Sanitizer
2184
 * An even better tool for spotting issues is
2185
 * <a href="https://code.google.com/p/address-sanitizer/">Address Sanitizer</a>,
2186
 * a fast memory error detector. Since it can spot memory errors, it's
2187
 * very useful to find out about hidden race conditions and the like.
2188 54582a6a Lorenzo Miniero
 *
2189 9355a077 Lorenzo Miniero
 * Unlike GDB which can be used as is, though, to use Address Sanitizer
2190
 * you'll first need to recompile Janus with some new settings, as it
2191
 * requires a specific dependency on a library, libasan, which you'll need
2192
 * to install through your repository manager if needed. Besides, you'll
2193
 * need at least gcc 4.8 for this to work: older versions of gcc won't
2194
 * work.
2195 54582a6a Lorenzo Miniero
 *
2196 9355a077 Lorenzo Miniero
 * Once you've installed libasan, reconfigure Janus like this:
2197 54582a6a Lorenzo Miniero
 *
2198 9355a077 Lorenzo Miniero
 \verbatim
2199
CFLAGS="-fsanitize=address -fno-omit-frame-pointer" LDFLAGS="-lasan" ./configure --prefix=/opt/janus
2200
 \endverbatim
2201 54582a6a Lorenzo Miniero
 *
2202 9355a077 Lorenzo Miniero
 * Of course you're free to add whatever additional configuration parameter
2203
 * you were using before: the important parts are the environment variables
2204
 * before that. Once done configuring, do a \c make \c clean (to make sure
2205
 * everything is recompiled from scratch) and then a \c make and \c make \c install
2206
 * as usual.
2207 54582a6a Lorenzo Miniero
 *
2208 9355a077 Lorenzo Miniero
 * At this point, your Janus version should be Address Sanitizer compliant.
2209
 * To make sure, try using \c ldd to check whether libasan is indeed a
2210
 * dependency or not:
2211 54582a6a Lorenzo Miniero
 *
2212 9355a077 Lorenzo Miniero
 \verbatim
2213
ldd janus | grep asan
2214
 \endverbatim
2215 54582a6a Lorenzo Miniero
 *
2216 9355a077 Lorenzo Miniero
 * If it is, you're done: whenever Janus crashes for any reason, you'll
2217
 * get additional output from Address Sanitizer automatically with details
2218
 * on what went wrong, and that's what you should provide as part of the
2219
 * issue content. Just as a side note, please beware that using Address
2220
 * Sanitizer Janus will run just a bit slower, even though not to the
2221
 * point of being unusable (as when using, e.g., valgrind).
2222 54582a6a Lorenzo Miniero
 *
2223 9355a077 Lorenzo Miniero
 * \note Please \c DON'T paste Address Sanitizer output in the issue text.
2224
 * Use a service like <a href="https://gist.github.com/">Gist</a> or
2225
 * <a href="http://pastebin.com/">Pastebin</a> and pass the generated
2226
 * link instead.
2227 54582a6a Lorenzo Miniero
 *
2228 9355a077 Lorenzo Miniero
 */
2229
2230 1e2606bf Lorenzo Miniero
/*! \page resources Resources
2231
 * This page contains pointers to some third-party resources, in particular
2232
 * client stacks, libraries and bindings in other languages, that is
2233
 * tools that you find helpful to interact with Janus outside of the
2234
 * context of the \c janus.js JavaScript library we provide. It is not
2235
 * a complete list, but just a summary of the material that has been
2236
 * shared so far on the <a href="https://groups.google.com/forum/#!forum/meetecho-janus">meetecho-janus</a>
2237
 * Google group. 
2238 54582a6a Lorenzo Miniero
 *
2239 1e2606bf Lorenzo Miniero
 * If you've developed anything related to Janus (client stacks, plugins,
2240
 * transports, etc.) and you're willing to share them with the community,
2241
 * or you know any such effort that is not listed here, just let us know
2242
 * and we'll add it on this page.
2243 54582a6a Lorenzo Miniero
 *
2244 1e2606bf Lorenzo Miniero
 * \section stacks Client-side stacks
2245 54582a6a Lorenzo Miniero
 *
2246 1e2606bf Lorenzo Miniero
 * \subsection nodejs node-js
2247
 * <a href="https://github.com/rtc-io/rtc-janus">rtc-janus</a>, a node and
2248
 * browserify compatible integration layer for the Janus WebRTC gateway.
2249
 * Experimental and incomplete as per the author words, but a good starting point.
2250 54582a6a Lorenzo Miniero
 *
2251 1e2606bf Lorenzo Miniero
 * \subsection dotnet C#/.NET
2252
 * <a href="https://github.com/Computician/JanusSharp">JanusSharp</a>,
2253
 * a C#/.Net client side API wrapper for the Janus API.
2254 54582a6a Lorenzo Miniero
 *
2255 1e2606bf Lorenzo Miniero
 * \section mobile Mobile resources
2256 54582a6a Lorenzo Miniero
 *
2257 1e2606bf Lorenzo Miniero
 * \subsection android Android
2258
 * <a href="https://github.com/Computician/janus-gateway-android">janus-gateway-android</a>,
2259
 * an API wrapper that utilizes the native WebRTC build and is made to ease communication with Janus.
2260 54582a6a Lorenzo Miniero
 *
2261 1e2606bf Lorenzo Miniero
 * \subsection ios iOS
2262
 * <a href="https://github.com/davibe/cordova-webrtc-janus-gateway">cordova-webrtc-janus-gateway</a>,
2263
 * a cordova application that interfaces with Janus and is based on the PhoneRTC cordova plugin.
2264 54582a6a Lorenzo Miniero
 *
2265 1e2606bf Lorenzo Miniero
 * \section thirdplugins Third-party plugins
2266 54582a6a Lorenzo Miniero
 *
2267 1e2606bf Lorenzo Miniero
 * TBD.
2268 54582a6a Lorenzo Miniero
 *
2269 1e2606bf Lorenzo Miniero
 * \section thirdtrasports Third-party transports
2270 54582a6a Lorenzo Miniero
 *
2271 1e2606bf Lorenzo Miniero
 * TBD. (for more info, see the \c modular-transports branch).
2272 54582a6a Lorenzo Miniero
 *
2273 1e2606bf Lorenzo Miniero
 */
2274
2275
2276 be35facb meetecho
/*! \page README README
2277 ddc1f702 meetecho
 *  \verbinclude README.md
2278 be35facb meetecho
 */
2279
2280
/*! \page CREDITS Credits
2281
 *
2282
 * Janus WebRTC Gateway © 2014 <a href="http://www.meetecho.com/">Meetecho</a> (http://www.meetecho.com/)
2283
 *
2284
 * \b Author:
2285
 *         Lorenzo Miniero <lorenzo@meetecho.com>
2286
 *
2287
 * Several open source components have been used to implement this software:
2288
 *
2289
 * - \b GLib: http://library.gnome.org/devel/glib/
2290
 * - \b pkg-config: http://www.freedesktop.org/wiki/Software/pkg-config/
2291
 * - \b gengetopt: http://www.gnu.org/software/gengetopt/ (command line)
2292
 * - \b libini-config: https://fedorahosted.org/sssd/ (INI configurations)
2293
 * - \b Jansson: http://www.digip.org/jansson/ (JSON)
2294
 * - \b libnice: http://nice.freedesktop.org/wiki/ (ICE/STUN/TURN)
2295
 * - \b OpenSSL: http://www.openssl.org/ (DTLS, at least v1.0.1e)
2296 0b841733 Lorenzo Miniero
 * - \b libsrtp: https://github.com/cisco/libsrtp (SRTP, at least v1.5 suggested)
2297 be35facb meetecho
 * - \b Sofia-SIP: http://sofia-sip.sourceforge.net/ (SDP parsing, SIP handling in the SIP plugin)
2298 a3d13e20 meetecho
 * - \b usrsctp: http://code.google.com/p/sctp-refimpl/ (Data Channels)
2299 09ac2273 meetecho
 * - \b libmicrohttpd: http://www.gnu.org/software/libmicrohttpd/ (Web server)
2300
 * - \b libwebsockets: https://libwebsockets.org/ (WebSockets)
2301
 * - \b rabbitmq-c: https://github.com/alanxz/rabbitmq-c (RabbitMQ)
2302 be35facb meetecho
 * - \b libopus: http://opus-codec.org/ (only needed for the bridge plugin)
2303
 * - \b libogg: http://xiph.org/ogg/ (only needed for the voicemail plugin)
2304
 *
2305
 */
2306
  
2307
/*! \page COPYING License
2308 2607c69d meetecho
 * This program is free software, distributed under the terms of the GNU
2309
 * General Public License Version 3.
2310
 *
2311 be196340 meetecho
 * If you're interested in a commercial license (e.g., because GPLv3 is
2312
 * not suited for what you need, you're interested in technical support
2313
 * or want to sponsor the development of new features), feel free to
2314
 * <a href="http://www.meetecho.com">contact us</a>.
2315 2607c69d meetecho
 *
2316 be35facb meetecho
 *  \verbinclude COPYING
2317
 */
2318
2319 3d7320cb meetecho
/*! \page FAQ Frequently Asked Questions
2320
 * This page contains a list of FAQ as gathered on the
2321
 * <a href="https://groups.google.com/forum/?pli=1#!forum/meetecho-janus">meetecho-janus</a>
2322
 * Google group and the 
2323
 * <a href="https://github.com/meetecho/janus-gateway/issues">Issues</a>
2324
 * page on GitHub. It obviously also includes things we're being asked all the
2325
 * time in general! If your question is not listed here or not available
2326
 * anywhere in this documentation, feel free to refer to the group for
2327
 * generic help, or to the Issues page for bugs in the implementation.\n\n
2328
 *
2329
 * -# <b>What is Janus?</b>\n
2330
 *    .
2331
 *    Janus is an open source WebRTC gateway written by <a href="http://www.meetecho.com">Meetecho</a>,
2332
 *    conceived as modular and, as much as possible,
2333
 *    general purpose. It acts as a WebRTC endpoint browsers can interact
2334
 *    with, and different modules can determine what should be done with
2335
 *    the media. This means that you can do SIP, videoconferencing, streaming
2336
 *    and tons of other stuff using the same box! And if what you need is
2337
 *    not there, you can always write your own module and expand Janus.\n\n
2338
 *    .
2339
 * -# <b>What is Meetecho?</b>\n
2340
 *    .
2341
 *    Meetecho is a startup founded by a few researchers, post-docs and
2342
 *    Ph.Ds coming from the Universty of Napoli Federico II. We've been
2343
 *    working on real-time multimedia applications over the Internet for
2344
 *    years, and at one point we decided to try and make products out
2345
 *    of our research efforts. Our web conferencing platform and Janus
2346
 *    is part of those efforts.\n\n
2347
 *    .
2348
 * -# <b>Now that we're at it, how is Meetecho pronounced??</b>\n
2349
 *    .
2350
 *    We're being asked that a lot! We've heard so many variants and different
2351
 *    pronounciations of the name that we could make a book out of it!
2352
 *    When we chose the name, we wanted it to sound like
2353
 *    <a href="https://www.youtube.com/watch?v=TkgDOMSv9PE">this</a>,
2354
 *    which means \a awesome! in Italian. The extra H was a mistake on our
2355
 *    side, as obviously \a echo is pronouced differently than \a eco! Long
2356
 *    story short, it doesn't really matter how you pronounce it: just
2357
 *    do it and help us be famous! :-)\n\n
2358
 *    .
2359
 * -# <b>Why is Janus called like that?</b>\n
2360
 *    .
2361
 *    Quoting <a href="http://en.wikipedia.org/wiki/Janus">Wikipedia</a>:
2362
 *    "<i>In ancient Roman religion and myth, Janus (Latin: Ianus, pronounced
2363
 *    [ˈiaː.nus]) is the god of beginnings and transitions, and thereby of
2364
 *    gates, doors, passages, endings and time. He is usually depicted as
2365
 *    having two faces, since he looks to the future and to the past.</i>"
2366
 *    Considering the general purpose nature of our gateway, where one face always looks
2367
 *    at the future (WebRTC) and the other at the past (whatever the modules
2368
 *    allows you to do, be it legacy stuff or not), Janus looked like the
2369
 *    perfect name for it! And besides, we're Italian, Ancient Rome was
2370
 *    awesome and mythology rules... ;-)  
2371
 *    \n\n
2372
 *    .
2373 ead45815 meetecho
 * -# <b>Is the license AGPL or GPL? Do you provide alternative license mechanisms as well?</b>\n
2374 3d7320cb meetecho
 *    .
2375 d3c229a7 meetecho
 *    First, a word of update: we recently switched from AGPLv3 to GPLv3,
2376
 *    so if AGPL was your concern, we hope this simple choice managed to
2377
 *    change your mind on whether considering trying Janus or not!
2378
 *
2379
 *    That said, we initially chose AGPL for a simple reason: we wanted our work to be open source,
2380 3d7320cb meetecho
 *    and we wanted interested people to play with it and contribute back
2381
 *    whatever improvement they could provide to the core. This is not always
2382
 *    the case with open source software, which is sometimes just seen as
2383
 *    free stuff you can exploit without helping back, and AGPL looked like
2384
 *    the easiest way to do that. We've been made aware that this license
2385
 *    mechanism is
2386
 *    <a href="https://groups.google.com/forum/?pli=1#!searchin/discuss-webrtc/janus/discuss-webrtc/LJHXkIsAaEU/fHgJ2z0sxfoJ">not very appreciated</a>
2387
 *    around, especially because of some
2388
 *    interpretations about it that could affect the way proprietary stuff
2389 d3c229a7 meetecho
 *    is deployed. We obviously cared about these concerns, and that's what
2390
 *    eventually lead to pick GPLv3 as a license, which should make it
2391
 *    easier for Janus to be integrated in heterogeneous scenarios.\n\n
2392 3d7320cb meetecho
 *    Apart from that, we're obviously also willing to discuss different
2393
 *    licensing agreements with interested parties, including commercial
2394
 *    ones. Sponsored development can also be considered, so if you're
2395
 *    interested in more details just contact us.\n\n
2396
 *    .
2397
 * -# <b>On what OS can I install Janus?</b>\n
2398
 *    .
2399
 *    At the moment only Linux is supported. While a more cross-platform
2400
 *    approach has been considered, there are no plans to work in that
2401
 *    direction in the near future, as we're mostly interested in adding
2402
 *    new features and improving/enhancing what's already there.\n\n
2403
 *    .
2404
 * -# <b>I've launched Janus, how do I try the demos?</b>\n
2405
 *    .
2406
 *    The demos are available in the \c html folder in the project. That
2407
 *    said, the integrated web server in Janus does not serve static files
2408
 *    as well, so you'll have to make them available using a different
2409
 *    webserver. Details about how to deploy Janus are provided in
2410
 *    \ref deploy.\n\n
2411
 *    .
2412 a3d13e20 meetecho
 * -# <b>Are Data Channels supported?</b>\n
2413 3d7320cb meetecho
 *    .
2414 ead45815 meetecho
 *    Yes they are! Starting from version \c 0.0.3 of Janus, we added a first
2415 a3d13e20 meetecho
 *    experimental support to Data Channels, that can as such be used in
2416
 *    plugins that choose to support them. Right now, they are only
2417
 *    handled in the Echo Test plugin, but this will be added to other
2418
 *    plugins as well, if not just to showcase what can be done with them.\n\n
2419
 *    Please notice that right now we only support text data: we're
2420
 *    currently working on binary streams as well, so we hope support
2421
 *    for those will be available soon.\n\n
2422 3d7320cb meetecho
 *    .
2423 eb492087 meetecho
 * -# <b>I don't care about Data Channels, do I have to compile usrsctp anyway?</b>\n
2424
 *    .
2425
 *    Support for Data Channels is optional. If you don't care about them,
2426 ead45815 meetecho
 *    but only about audio and/or video, pass the \c --disable-data-channels
2427
 *    option to the configure script. If you already attempted an install
2428 eb492087 meetecho
 *    previously, issue a \c make \c clean before compiling again, or
2429
 *    you might encounter issues with pre-existing symbols.\n\n
2430
 *    .
2431
 * -# <b>I can't install usrsctp, I'm getting errors about dereferencing pointers?</b>\n
2432
 *    .
2433
 *    Apparently recent compilers are stricter with respect to some code
2434
 *    syntaxes, and this seems to be affecting the way \c usrsctp is written
2435
 *    as of now. Some users managed to fix this issue by passing an export
2436
 *    before the \c bootstrap and \c configure steps in the \c usrsctp
2437
 *    compilation:\n\n
2438
 *\verbatim
2439
   export CFLAGS="-fno-strict-aliasing" ./boostrap
2440
   export CFLAGS="-fno-strict-aliasing" ./configure --prefix=/usr
2441
   make && make install
2442
 \endverbatim
2443
 *    Another solution seems to be removing all the \c -O2 occurrences
2444
 *    in the generated \c configure script.\n\n
2445
 *    .
2446 3d7320cb meetecho
 * -# <b>Can I use Janus as a gateway to my Freeswitch/Kamailio/Asterisk/other SIP infrastructure?</b>\n
2447
 *    .
2448
 *    Of course! One of the modules we provide out of the box is a SIP
2449
 *    gateway plugin based on the <a href="http://sofia-sip.sourceforge.net/">Sofia-SIP</a>
2450
 *    library stack. These plugin allows a web user to register at a SIP
2451
 *    proxy/server either as an authenticated user or as a guest, and
2452
 *    start or receive calls from other SIP users, including other web users
2453
 *    exploiting the same plugin. Janus will take care of all the WebRTC-related
2454
 *    stuff (ICE, DTLS, SRTP), which means that on the SIP side it will
2455
 *    be plain RTP only, much easier and lighter to handle for legacy
2456
 *    implementations. This has so far only been tested with
2457
 *    Kamailio and Asterisk but, since a well known and reliable stack
2458
 *    like Sofia is being used for the purpose, it should work fine with
2459
 *    other implementations as well.\n\n
2460
 *    Please notice that there's definitely room for improvement in this
2461
 *    module (e.g., video support is a bit flaky right now), so let us
2462
 *    know if you encounter any problems with it!\n\n
2463
 *    .
2464
 * -# <b>Can I use existng SIP stacks (e.g., JsSIP) with Janus?</b>\n
2465
 *    .
2466
 *    Janus uses a custom JSON-based protocol for all the communication
2467
 *    between web users and plugins in the gateway, so no, that's not
2468
 *    possible right now. The SIP plugin in Janus only exposes some very
2469
 *    high level information to web users (e.g., registration failed/succeeded,
2470
 *    incoming call, decline, hangup, etc.), without delving in any SIP-related
2471
 *    detail, which is instead completely demanded to the server-side plugin
2472
 *    itself. This ensures that web users can take advantage of SIP functionality
2473
 *    in an easy way, without having to worry about the details and complexity
2474
 *    of SIP within JavaScript.\n\n
2475
 *    .
2476
 * -# <b>Does Janus support transcoding?</b>\n
2477
 *    .
2478
 *    Janus is a simple intermediary between WebRTC users and server-side
2479
 *    plugins providing application logic, so no, it doesn't provide any
2480
 *    transcoding functionality per-se. If transcoding is needed, this is
2481
 *    supposed to be implemented within plugins themselves. That said,
2482
 *    none of the plugins we provide out-of the box does transcoding,
2483
 *    since we wanted the implementation to be lightweight and besides
2484
 *    there are several existing tools and third-party implementations that
2485
 *    could be leveraged for the purpose.\n\n
2486
 *    .
2487
 * -# <b>Does Janus support recording?</b>\n
2488
 *    .
2489
 *    See above: no recording functionality is provided by Janus itself,
2490
 *    as that's something that should be done by plugins as part of their
2491
 *    application logic. That said, unlike transcoding some of the plugins
2492
 *    do implement some sort of recording feature. Specifically, the
2493
 *    Audio Bridge plugin allows for a recording of the mixed audio room
2494
 *    to an uncompressed WAV file; the Voice Mail plugin, instead, allows
2495
 *    for the recording of audio frames provided by a web user to an .opus
2496
 *    file, for the purpose of archiving. The same functionality could
2497
 *    be easily migrated to other plugins, and work is being done to
2498
 *    do the same for video as well (something that we have ready, but
2499
 *    currently introduces too many dependencies that we'd rather avoid).\n\n
2500
 *    .
2501
 * -# <b>Can I use WebSockets instead of plain HTTP to interact with Janus?</b>\n
2502
 *    .
2503 af40a682 meetecho
 *    Since version \c 0.0.4, you can! At first we chose a REST-based plain HTTP communication
2504 3d7320cb meetecho
 *    for a simple reason: we noticed that there were some scenarios (e.g.,
2505
 *    client firewalls) where websockets wouldn't work, even though WebRTC
2506
 *    did. To improve the chances of success in the communication, we
2507
 *    then chose this simpler approach with respect to signalling. Besides,
2508
 *    plain HTTP is much easier to proxy and/or place behind frontends
2509
 *    like Apache HTTPD or nginx than WebSockets, another aspect that
2510
 *    played a decisive role in our decision, as we were also very interested
2511
 *    in making the integration of Janus in heterogeneous environments
2512 af40a682 meetecho
 *    as easy as possible. That said, WebSockets also provide substantial
2513
 *    benefits when compared to plain HTTP, and definitely make life easier to
2514
 *    server side integrators as well, e.g., in terms of overhead and use of
2515
 *    resources. For this reason, we added an optional (meaning you can
2516
 *    skip it if you want) support for WebSockets that uses the same API
2517 ead45815 meetecho
 *    already available in HTTP, as documented in the \ref WS. \n
2518
 *    \note Please beware that support for WebSockets
2519 af40a682 meetecho
 *    is still \b highly \b experimental, so handle that with care!\n\n
2520 3d7320cb meetecho
 *    .
2521 ead45815 meetecho
 * -# <b>Can I use RabbitMQ instead of HTTP/WebSockets to interact with Janus?</b>\n
2522
 *    .
2523
 *    Since version \c 0.0.6, you can! This is a feature that several
2524
 *    developers asked for, especially those that are interested in wrapping
2525
 *    the Janus API on the server side, and implement the communication
2526
 *    on the client side their own way. Specificaly, Janus now supports
2527
 *    RabbitMQ based messaging as an alternative "transport" for API
2528
 *    requests, responses and notifications, meaning it can be used with
2529
 *    or without HTTP and WebSockets, depending on your requirements.
2530
 *    To implement a pseudo-bidirectional channel using RabbitMQ, Janus
2531
 *    makes use of two different queues: one to receive messages, and another
2532
 *    one to send responses and notifications. Since this support is in its
2533
 *    early stages, right now you can only have a single "application"
2534
 *    talking to a specific Janus instance using RabbitMQ messaging,
2535
 *    meaning that Janus won't implement multiple queues to handle
2536
 *    multiple concurrent "application servers" taking advantage of its
2537
 *    features. Support for this is planned, though (e.g., through some kind
2538
 *    of negotiation to create queues on the fly). If you're going to use
2539
 *    the same RabbitMQ server for handling multiple Janus instances from
2540
 *    the same application or different ones, make sure you configure
2541
 *    different queues for each of them (e.g., from-janus-1/to-janus-1 and
2542
 *    from-janus-2/to-janus-2), or otherwise in case of "conflicts" more
2543
 *    instances will end making use of the same queues and messages will get lost.\n
2544
 *    Just as with WebSockets, the Janus API usage when involving RabbitMQ
2545
 *    is exactly the same as the one for HTTP and WebSockets, as documented
2546
 *    in \ref rabbit. \n \note Please beware that support for RabbitMQ is
2547
 *    still \b highly \b experimental, so handle that with care!\n\n
2548
 *    .
2549 09ac2273 meetecho
 * -# <b>What about <my favourite control protocol> instead?</b>\n
2550
 *    .
2551
 *    Since version \c 0.1.0, the transports for the Janus API have been made
2552
 *    modular. This means that, assuming a transport plugin implementing
2553
 *    support for your favourite protocol has been made available, you
2554
 *    can just add it to the Janus transport modules folder and it should
2555
 *    work. If no plugin has been implemented, you may even want to do so
2556
 *    yourself, or ask for ours or others help.\r\n
2557
 *    .
2558 3d7320cb meetecho
 * -# <b>Can I use Janus with node.js or other frameworks?</b>\n
2559
 *    .
2560 355bacc6 meetecho
 *    Not out of the box, but since interaction with Janus can be completely
2561
 *    HTTP/WebSockets based, this can be abstracted in several different way. With
2562 a3d13e20 meetecho
 *    respect to node.js, <a href="#">NICTA</a> recently released a module
2563 3d7320cb meetecho
 *    called <a href="https://www.npmjs.org/package/rtc-janus">rtc-janus</a>
2564
 *    that allows you to interact with a Janus instance from a node.js
2565
 *    application, so give that a try!\n\n
2566
 *    .
2567
 * -# <b>Is there any benchmark on Janus performances?</b>\n
2568
 *    .
2569
 *    Benchmarking Janus is not an easy task, especially if we consider
2570
 *    its general purpose nature. In fact, Janus by itself does not much
2571
 *    more than negotiating WebRTC PeerConnections and relaying frames
2572
 *    around, while most of the application login is in the modules. As
2573
 *    you can imagine, different modules may have very different requirements
2574
 *    and impact on the performances. For instance, the Echo Test is probably
2575
 *    much lighter than the Video MCU, even if they're handling the same
2576
 *    number of users. This means that such a benchmarking does not have
2577
 *    much sense unless you contextualise the scenarios.\n\n
2578
 *    For this reason, we and some Janus adopters have recently tried to
2579
 *    do some benchmarking taking a specific plugin as a reference, that
2580
 *    is the Video MCU: in fact, the Video MCU is one of the most popular
2581
 *    modules in Janus, and by itself it does represent a good test bed
2582
 *    considering its many-to-many communication pattern. You can find
2583
 *    some details and considerations in a recent
2584
 *    <a href="https://groups.google.com/forum/?pli=1#!topic/meetecho-janus/ydGcbMt7IX0">post</a>
2585 355bacc6 meetecho
 *    on our Google group.\n\n
2586
 *    You can find more results in a publication we made at the
2587
 *    <a href="http://janus.conf.meetecho.com/citeus.html">All-Web real-time Systems (AWeS 2015)</a> workshop.\n\n
2588 3d7320cb meetecho
 *    .
2589
 * -# <b>I want to write my own plugin, where do I start?</b>\n
2590
 *    .
2591
 *    Great! There's an API you can refer to, documented in \ref pluginapi.
2592
 *    Since you'll want your web users to interact with it, make also sure
2593
 *    you study the \ref JS as well, especially the parts that talk about
2594
 *    how to send/receive messages and negotiate WebRTC PeerConnections.
2595
 *    The existing plugins are also an excellent way to start to get
2596
 *    comfortable with the API: a good starting point may be the Echo Test
2597
 *    plugin, which is a very simple and barebone implementation that
2598 a3d13e20 meetecho
 *    simply bounces back whatever it is sent, and also involves some
2599 3d7320cb meetecho
 *    rough application logic to determine its behaviour (e.g., messages
2600
 *    coming from web users that selectively enable or disable video).
2601
 *    If you need any help with this, feel free to contact us: we're
2602
 *    excited to see who will make available the first third-party Janus
2603
 *    plugin!\n\n
2604
 *    .
2605
 * -# <b>I'm using the Video MCU and, when several users are handled, I get
2606
 *    a "Too many open files" errors and Janus crashes</b>\n
2607
 *    .
2608
 *    As all applications on Linux environments, Janus is bound to the
2609
 *    constraints imposed by the OS and/or the user. One of these constraints
2610
 *    is related to how many file descriptors the application, or all the
2611
 *    applications, can open. On several distributions this number is, by
2612
 *    default, quite low, which can cause the issue you experienced. This
2613
 *    value, together with others, can be modified, per-user or for all users,
2614
 *    using the \c ulimit application. For a simple and quick way to handle
2615
 *    this refer to the guide provided by the MongoDB developers:
2616
 *    http://docs.mongodb.org/manual/reference/ulimit/ \n\n
2617
 *    .
2618
 * -# <b>When I enable the HTTPS web server in Janus, the CPU goes crazy</b>\n
2619
 *    .
2620
 *    As discussed in a recent <a href="https://groups.google.com/forum/?pli=1#!topic/meetecho-janus/lD8A0VqXsNs">post</a>
2621
 *    on our Google group, this is caused by an occasional problem within
2622
 *    libmicrohttpd, the library we use to implement an embedded web server
2623
 *    in Janus. This is not deterministic, as the high CPU usage does happen
2624
 *    on some distributions (e.g., Ubuntu 12.04), while it doesn't on
2625
 *    others (e.g., Ubuntu 14.04). Anyway, this only can happen if you enable
2626
 *    HTTPS support within Janus itself: you can still have a safe HTTPS
2627
 *    usage with Janus if you deploy it behind a frontend (e.g., Apache HTTPD)
2628
 *    that takes care of this on its behalf. Refer to the \ref deploy section
2629
 *    for more details about this.\n\n
2630
 *    .
2631 355bacc6 meetecho
 * -# <b>I enabled TURN in the Janus configuration, but my clients behind a firewall can't connect</b>\n
2632
 *    .
2633
 *    As explained in the \c janus.cfg documentation, the TURN settings you
2634
 *    configure there refer to Janus \b itself, \b not the clients that make use
2635
 *    of its services. This means that, whether you configure a static TURN
2636
 *    server and the related credentials, or the REST API client stack to
2637
 *    retrieve them dynamically, you're asking Janus to gather relay candidates
2638
 *    for ITSELF. This is only useful if you know that your Janus instance
2639
 *    will not be deployed on a public address (as it usually will) but will
2640
 *    instead potentially sit behind a restrictive component like a firewall,
2641
 *    or if you simply want to limit the number of open ports and so force
2642
 *    all media traffic to go through the TURN server port alone.\n\n
2643
 *    If you want your clients to gather relay candidates, instead, this
2644
 *    needs to be done on the client side (e.g., in JavaScript, if your
2645
 *    clients are web applications). If you're using our \ref JS check
2646
 *    the \c echotest.js code, which has a commented portion that explains
2647
 *    how to provide one or more TURN servers to make use of. If you're
2648
 *    handling the WebRTC-related stuff on your own and are contacting
2649
 *    Janus some other way, please refer to the related way of specifying
2650
 *    STUN and TURN servers instead.\n\n
2651
 *    .
2652 3d7320cb meetecho
 * -# <b>Can you implement a feature I want?</b>\n
2653
 *    .
2654
 *    We're constantly working on new features and on improving what's
2655
 *    already there, and we do love feedback from users. That said, we're
2656
 *    a small team and we do have to pay our bills, so we always have to
2657
 *    reserve our resources wisely. If there's a feature you'd like to
2658
 *    see implemented, tell us on our Google group, and discuss it with
2659
 *    other users: it may be on our schedule, or someone else may be
2660
 *    already working on it to contribute it back to the project. You
2661
 *    may even want to try and build it yourself and help us make Janus
2662
 *    even better! If you really need something that isn't there, you
2663 355bacc6 meetecho
 *    may also want to consider a sponsored development or contact us
2664
 *    for consulting.\n\n
2665 3d7320cb meetecho
 *    .
2666
 */
2667
2668 be35facb meetecho
/*! \defgroup core Core
2669
 * \brief Core implementation of the gateway
2670
 * \details The Janus WebRTC Gateway is founded on a core that glues the
2671
 * involved parts together. The main code is janus.c that implements
2672
 * the logic behind the gateway itself: it implements the web server that
2673
 * interacts with browsers, and handles sessions with them. This includes
2674
 * taking care of media signalling and negotiation, and bridging peers
2675
 * with available plugins.
2676
 */
2677
2678
/*! \defgroup protocols Protocols
2679
 * \brief Implementations of the WebRTC protocols
2680
 * \details The WebRTC specification (WEBRTC/RTCWEB) currently mandates
2681
 * the usage of a few protocols and techniques. The code in this group
2682
 * takes care of them all (SDP, ICE, DTLS-SRTP, RTP/RTCP). 
2683
 * \ingroup core
2684
 */
2685
2686
/*! \defgroup plugins Plugins
2687
 * \brief Gateway plugins available out of the box
2688
 * \details In order to showcase how different plugins can implement
2689
 * completely different applications on top of the Janus core, a few
2690
 * plugin implementations are provided out of the box. The API for
2691
 * writing a new plugin is specified in the \ref pluginapi section.
2692
 */
2693
2694
/*! \defgroup pluginapi Plugin API
2695
 * \brief Plugin API (aka, how to write your own plugin)
2696
 * \details The plugin.h header specifies the API a plugin needs to
2697
 * implement and make available in order to be used by the gateway and
2698
 * exposed to browsers. 
2699
 * \ingroup plugins
2700
 */
2701 9d11ac50 meetecho
2702
/*! \defgroup tools Tools and utilities
2703
 * \brief Tools and utilities
2704
 * \details Set of simple tools and utilities that may be of help when
2705
 * used in conjunction with Janus. 
2706
 */
2707
2708
/*! \defgroup postprocessing Recordings post-processing utility
2709
 * \brief Recordings post-processing utility
2710
 * \details This simple utility (janus-pp-rec.c) allows you to
2711
 * post-process recordings generated by the janus_recorder helper (e.g.,
2712
 * in the Video MCU plugin). 
2713
 * \ingroup tools
2714
 */