mainpage.dox

/*!
 * \mainpage Janus - General purpose WebRTC Gateway
 *
 * \par Developer Documentation for the Janus WebRTC Gateway
 * This is the main developer documentation for the Janus WebRTC
 * Gateway, generated with the help of
 * <a href="http://www.doxygen.org">Doxygen</a>. Make sure you
 * check the \ref DEPS before attempting a compilation. If you are
 * interested in how to compile, install and use the gateway,
 * checkout the \ref README information. A \ref FAQ page is also available.
 *
 * \par A general purpose gateway
 * The Janus WebRTC Gateway has been conceived as a <tt>general purpose</tt>
 * gateway. As such, it doesn't provide any functionality per se
 * other than implementing the means to set up a WebRTC media communication
 * with a browser, exchanging JSON messages with it, and relaying RTP/RTCP
 * and messages between browsers and the server-side application logic they're attached to. Any specific
 * feature/application needs to be implemented in server side plugins,
 * that browsers can then contact via the gateway to take advantage of
 * the functionality they provide. Example of such plugins can be
 * implementations of applications like echo tests, conference bridges,
 * media recorders, SIP gateways and the like.
 * 
 * The reason for this is simple: we wanted something that would have a
 * <tt>small footprint</tt> (hence a C implementation) and that we could only
 * equip with what was <tt>really needed</tt> (hence pluggable modules). That is,
 * something that would allow us to deploy either a full-fledged WebRTC
 * gateway on the cloud, or a small nettop/box to handle a specific use case.
 *
 * \par Architecture and APIs
 * The core of the gateway is specified in the \ref core section. The protocols
 * implemented in the gateway are listed in the \ref protocols group
 * instead. A list of plugins made available out of the box by Meetecho
 * are available in the \ref plugins group: these plugins can be changed
 * or extended to match your requirements, or just used as a simple
 * reference should you be interested in writing a new plugin from
 * scratch (and you're definitely welcome to!). A \ref pluginapi to
 * create new plugins, or understand how they're conceived, is documented
 * as well. A documentation on the available HTTP/WebSocket/RabbitMQ 
 * tranports and the HTTP/WebSocket JavaScript API to use the
 * gateway and the plugins it makes available in your web application
 * can be found in the \ref JS and \ref rest pages. If you're interested
 * in monitoring Janus resources, you can refer to the \ref admin page.
 *
 * Finally, some information on how to deploy Janus and your web
 * applications that want to make use of it are provided in the \ref deploy
 * page. If you're interested in starting Janus as a service/daemon rather
 * than launching it normally, check the information provided in the
 * \ref service page.
 *
 * This is only the first version of the gateway, and as such it is a bit
 * rough at the edges: there is definitely room for improvement, there are
 * bugs, limitations, and things that need to be done. For a quick glance
 * on the most relevant pending stuff check our \ref todo (and, if you're
 * willing to help on any of those, get in touch with us!). Make also
 * sure you read the \ref debug page for info on how you can help us
 * fixing issues you might encounter along the road.
 *
 * \section copyright Copyright and author
 *
 * Janus WebRTC Gateway © 2014 <a href="http://www.meetecho.com/">Meetecho</a> (http://www.meetecho.com/)
 *
 * \author Lorenzo Miniero <lorenzo@meetecho.com> ( \ref CREDITS )
 *
 * \section license License
 * This program is free software, distributed under the terms of
 * the GNU General Public License Version 3. For more details and licensing
 * options, including a commercial license, see the \ref COPYING page.
 *
*/

/*! \page DEPS Dependencies
 *
 * The application and the plugins depend on the following open source
 * software and libraries, so make sure you install the related development
 * versions before attempting a compilation:
 *
 * - \b GLib: http://library.gnome.org/devel/glib/
 * - \b pkg-config: http://www.freedesktop.org/wiki/Software/pkg-config/
 * - \b gengetopt: http://www.gnu.org/software/gengetopt/ (command line)
 * - \b libmicrohttpd: http://www.gnu.org/software/libmicrohttpd/ (Web server)
 * - \b libini-config: https://fedorahosted.org/sssd/ (INI configurations)
 * - \b Jansson: http://www.digip.org/jansson/ (JSON)
 * - \b libnice: http://nice.freedesktop.org/wiki/ (ICE/STUN/TURN)
 * - \b OpenSSL: http://www.openssl.org/ (DTLS, at least v1.0.1e)
 * - \b libsrtp: http://srtp.sourceforge.net/srtp.html (SRTP, at least v1.5 suggested)
 * - \b Sofia-SIP: http://sofia-sip.sourceforge.net/ (SDP parsing, SIP handling in the SIP plugin)
 * - \b usrsctp: http://code.google.com/p/sctp-refimpl/ (\c optional, Data Channels)
 * - \b libwebsockets: https://libwebsockets.org/ (\c optional, WebSockets)
 * - \b rabbitmq-c: https://github.com/alanxz/rabbitmq-c (\c optional, v1.0.4, RabbitMQ)
 * - \b libopus: http://opus-codec.org/ (\c optional, only needed for the bridge plugin)
 * - \b libogg: http://xiph.org/ogg/ (\c optional, only needed for the voicemail plugin)
 *
 */

/*! \page JS JavaScript API
 * The gateway exposes both a pseudo-RESTful interface, and optionally a
 * WebSocket interface as well, both of which based on JSON messages. These
 * interfaces are described in more detail in the \ref plainhttp and
 * \ref WS documentation respectively, and both allow web applications to
 * take advantage of the features provided by Janus and the functionality
 * made available by its plugins. To make things easier for web
 * developers, a JavaScript library (\c janus.js) is available that can
 * make use of both interfaces using exactly the same API. This library
 * eases the task of creating sessions with the gateway, attaching WebRTC
 * users to plugins, send and receive requests and events to the plugins
 * themselves and so on. For real examples of how this library can be
 * used, check the demos in the \b html folder of this package.
 * 
 * \note The current \c janus.js library makes use of jQuery (http://jquery.com/)
 * as a support. We're considering preparing versions that make use of
 * different libraries as well (e.g., Prototype, Dojo, Script.aculo.us, etc.)
 * in case your web application us based on something that cannot make use
 * of jQuery. Of course, if you happen to prepare one yourself in the
 * meanwhile don't hesitate and let us know! :-)
 *
 * In general, when using the gateway features, you would normally do the following:
 *
 * -# include the Janus JavaScript library in your web page;
 * -# initialize the Janus JavaScript library;
 * -# connect to the gateway and create a session;
 * -# create one or more handles to attach to a plugin (e.g., echo test and/or streaming);
 * -# interact with the plugin (sending/receiving messages, negotiating a PeerConnection);
 * -# eventually, close all the handles and shutdown the related PeerConnections;  
 * -# destroy the session.  
 * 
 * The above steps will be presented in order, describing how you can use
 * the low level API to accomplish them. Consider that in the future we might
 * provide higher level wrappers to this API to address specific needs, e.g.,
 * a higher level API for each plugin: this would make it even easier to use
 * the gateway features, as a high level API for the streaming plugin, for
 * instance, may just ask you to provide the server address and the ID of
 * the \c &lt;video&gt; element to display the stream in, and would take care of all the
 * above mentioned steps on your behalf. Needless to say, you're very welcome
 * to provide wrapper APIs yourself, if you feel a sudden urge to do so! :-)
 *
 * <hr>
 *
 * As a first step, you should include the \c janus.js library in your project:
 *
\verbatim
<script type="text/javascript" src="janus.js" ></script>
\endverbatim
 *
 * The core of the JavaScript API is the \c Janus object. This object needs
 * to be initialized the first time it is used in a page. This can be done
 * using the static \c init method of the object, which accepts the
 * following options:
 *
 * - \c debug: whether debug should be enabled on the JavaScript console (true/false, default=false)
 * - \c callback: a user provided function that is invoked when the initialization is complete. 
 * 
 * Here's an example:
 *
 * 
 \verbatim
Janus.init({
   debug: true,
   callback: function() {
	   // Done!
   });
 \endverbatim
 *
 * Once the library has been initialized, you can start creating sessions.
 * Normally, each browser tab will need a single session with the gateway: in
 * fact, each gateway session can contain several different plugin handles
 * at the same time, meaning you can start several different WebRTC sessions
 * with the same or different plugins for the same user using the same
 * gateway session. That said, you're free to set up different gateway
 * sessions in the same page, should you prefer so.
 *
 * Creating a session is quite easy. You just need to use the \c new constructor
 * to create a new \c Janus object that will handle your interaction with the
 * gateway. Considering the dynamic and asynchronous nature of Janus sessions
 * (events may occur at any time), there are several properties and callbacks you
 * can configure when creating a session:
 *
 * - \c server: the address of the gateway as a specific address (e.g.,
 * http://yourserver:8088/janus to use the plain HTTP API or ws://yourserver:8188/
 * for WebSockets) or as an array of addresses to try sequentially to allow
 * automatic for fallback/failover during setup;
 * - \c iceServers: a list of STUN/TURN servers to use (a default STUN server
 * will be used if you skip this property);
 * - a set of callbacks to be notified about events, namely:
 * 		- \c success: the session was successfully created and is ready to be used;
 * 		- \c error: the session was NOT successfully created;
 * 		- \c destroyed: the session was destroyed and can't be used any more.
 *
 * These properties and callbacks are passed to the method as properties
 * of a single parameter object: that is, the \c Janus constructor takes a
 * single parameter, which although acts as a container for all the available
 * options. The \c success callback is where you tipically start your application
 * logic, e.g., attaching the peer to a plugin and start a media session.
 *
 * Here's an example:
 * 
 \verbatim
var janus = new Janus(
	{
		server: 'http://yourserver:8088/janus',
		success: function() {
			// Done! attach to plugin XYZ
		},
		error: function(cause) {
			// Error, can't go on...
		},
		destroyed: function() {
			// I should get rid of this
		}
	});
 \endverbatim
 *
 * As anticipated, the server may be a specific address, e.g.:
 *
 \verbatim
var janus = new Janus(
	{
		server: 'http://yourserver:8088/janus',
				// or
		server: 'ws://yourserver:8188/',
		[..]
 \endverbatim
 *
 * or an array of addresses. Such an array can be especially useful if
 * you want the library to first check if the WebSockets server is
 * reachable and, if not, fallback to plain HTTP, or just to provide
 * a link multiple instances to try for failover. This is an example of
 * how to pass a 'try websockets and fallback to HTTP' array:
 *
 \verbatim
var janus = new Janus(
	{
		server: ['ws://yourserver:8188/','http://yourserver:8088/janus'],
		[..]
 \endverbatim
 *
 * Once created, this object represents your session with the gateway.
 * you can interact with a \c Janus object in several different ways.
 * In particular, the following properties and methods are defined:
 *
 * - \c getServer(): returns the address of the gateway;
 * - \c isConnected(): returns \c true if the Janus instance is connected
 * to the gateway, \c false otherwise;
 * - \c getSessionId(): returns the unique gateway session identifier;
 * - \c attach(parameters): attaches the session to a plugin, creating an handle;
 * more handles to the same or different plugins can be created at the same time;
 * - \c destroy(parameters): destroys the session with the gateway, and closes
 * all the handles (and related PeerConnections) the session may have with any plugin as well.
 *
 * The most important property is obviously the \c attach() method, as
 * it's what will allow you to exploit the features of a plugin to manipulate
 * the media sent and/or received by a PeerConnection in your web page.
 * This method will create a plugin handle you can use for the purpose,
 * for which you can configure properties and callbacks when calling the
 * \c attach() method itself. As for the \c Janus constructor, the \c attach()
 * method takes a single parameter that can contain any of the following
 * properties and callbacks:
 *
 * - \c plugin: the unique package name of the plugin (e.g., \c janus.plugin.echotest );
 * will be used if you skip this property)
 * - a set of callbacks to be notified about events, namely:
 * 		- \c success: the handle was successfully created and is ready to be used;
 * 		- \c error: the handle was NOT successfully created;
 * 		- \c consentDialog: this callback is triggered just before \c getUserMedia is called
 * (parameter=<b>true</b>) and after it is completed (parameter=<b>false</b>); this means it can
 * be used to modify the UI accordingly, e.g., to prompt the user about the need to accept the device access consent requests;
 * 		- \c onmessage: a message/event has been received from the plugin;
 * 		- \c onlocalstream: a local \c MediaStream is available and ready to be displayed;
 * 		- \c onremotestream: a remote \c MediaStream is available and ready to be displayed;
 * 		- \c ondataopen: a Data Channel is available and ready to be used;
 * 		- \c ondata: data has been received through the Data Channel;
 * 		- \c oncleanup: the WebRTC PeerConnection with the plugin was closed;
 * 		- \c detached: the plugin handle has been detached by the plugin itself,
 * and so should not be used anymore.
 *
 * Here's an example:
 * 
 \verbatim
// Attach to echo test plugin, using the previously created janus instance
janus.attach(
	{
		plugin: "janus.plugin.echotest",
		success: function(pluginHandle) {
			// Plugin attached! 'pluginHandle' is our handle
		},
		error: function(cause) {
			// Couldn't attach to the plugin
		},
		consentDialog: function(on) {
			// e.g., Darken the screen if on=true (getUserMedia incoming), restore it otherwise
		},
		onmessage: function(msg, jsep) {
			// We got a message/event (msg) from the plugin
			// If jsep is not null, this involves a WebRTC negotiation
		},
		onlocalstream: function(stream) {
			// We have a local stream (getUserMedia worked!) to display
		},
		onremotestream: function(stream) {
			// We have a remote stream (working PeerConnection!) to display
		},
		oncleanup: function() {
			// PeerConnection with the plugin closed, clean the UI
			// The plugin handle is still valid so we can create a new one
		},
		detached: function() {
			// Connection with the plugin closed, get rid of its features
			// The plugin handle is not valid anymore
		}
	});
 \endverbatim
 *
 * So the \c attach() method allows you to attach to a plugin, and specify 
 * the callbacks to invoke when anything relevant happens in this interaction.
 * To actively interact with the plugin, you can use the \c Handle object
 * that is returned by the \c success callback (pluginHandle in the example).
 *
 * This \c Handle object has several methods you can use to interact with
 * the plugin or check the state of the session handle:
 *
 * - \c getId(): returns the unique handle identifier;
 * - \c getPlugin(): returns the unique package name of the attached plugin;
 * - \c send(parameters): sends a message (with or without a jsep to
 * negotiate a PeerConnection) to the plugin;
 * - \c createOffer(callbacks): asks the library to create a WebRTC compliant OFFER;
 * - \c createAnswer(callbacks): asks the library to create a WebRTC compliant ANSWER;
 * - \c handleRemoteJsep(callbacks): asks the library to handle an incoming WebRTC compliant session description;
 * - \c dtmf(parameters): sends a DTMF tone on the PeerConnection;
 * - \c data(parameters): sends data through the Data Channel, if available;
 * - \c getBitrate(): gets a verbose description of the currently received stream bitrate (only available on Chrome, for now);
 * - \c hangup(): tells the library to close the PeerConnection;
 * - \c detach(parameters): detaches from the plugin and destroys the handle, tearing
 * down the related PeerConnection if it exists.
 *
 * While the \c Handle API may look complex, it's actually quite straightforward
 * once you get the concept. The only step that may require a little more
 * effort to understand is the PeerConnection negotiation, but again, if
 * you're familiar with the WebRTC API, the \c Handle actually makes it
 * a lot easier.
 *
 * The idea behind it's usage is the following:
 *
 * -# you use \c attach() to create a \c Handle object;
 * -# in the \c success callback, your application logic can kick in: you may
 * want to send a message to the plugin ( \c send(msg) ), negotiate
 * a PeerConnection with the plugin right away ( \c createOffer followed
 * by a \c send(msg, jsep) ) or wait for something to happen to do anything;
 * -# the \c onmessage callback tells you when you've got messages from the plugin;
 * if the \c jsep parameter is not null, just pass it to the library, which will take
 * care of it for you; if it's an \b OFFER use \c createAnswer (followed by a
 * \c send(msg, jsep) to close the loop with the plugin), otherwise use
 * \c handleRemoteJsep ;
 * -# whether you took the initiative to set up a PeerConnection or the plugin did,
 * the \c onlocalstream and/or the \c onremotestream callbacks will provide
 * you with a stream you can display in your page;
 * -# each plugin may allow you to manipulate what should flow through the
 * PeerConnection channel: the \c send method and \c onmessage callback
 * will allow you to handle this interaction (e.g., to tell the plugin
 * to mute your stream, or to be notified about someone joining a virtual room),
 * while the \c ondata callback is triggered whenever data is received
 * on the Data Channel, if available (and the \c ondataopen callback
 * will tell you when a Data Channel is actually available). 
 *
 * The following paragraphs will delve a bit deeper in the negotiation
 * mechanism provided by the \c Handle API, in particular describing
 * the properties and callbacks that may be involved. To follow the approach
 * outlined by the W3C WebRTC API, this negotiation mechanism is heavily
 * based on asynchronous methods as well.
 *
 * - \c createOffer takes a single parameter, that can contain any of the
 * following properties and callbacks:
 *   - \c media: you can use this property to tell the library which media (audio/video/data)
 * you're interested in, and whether you're going to send and/or receive any of them; by default
 * audio and video are enabled in both directions, while the Data Channels are disabled;
 * this option is an object that can take any of the following properties:
 *     - \c audioSend: \c true/false (do or do not send audio);
 *     - \c audioRecv: \c true/false (do or do not receive audio);
 *     - \c audio: \c true/false (do or do not send \b and receive audio, takes precedence on the above);
 *     - \c videoSend: \c true/false (do or do not send video);
 *     - \c videoRecv: \c true/false (do or do not receive video);
 *     - \c video: \c true/false (do or do not send \b and receive video, takes precedence on the above);
 *     - \c video: \c "lowres"/"lowres-16:9"/"stdres"/"stdres-16:9"/"hires"/"hires-16:9"
 * (send a 320x240/320x180/640x480/640x360/1280x720 video, takes precedence on the above;
 default is \c "stdres" )
 * this property will affect the resulting getUserMedia that the library will issue; please
 * notice that Firefox doesn't support the \c "16:9" variants, which will fallback
 * to the ones; besides, \c "hires" and \c "hires-16:9" are currently synonymous, as
 * there's no 4:3 high resolution constraint as of now;
 *     - \c video: \c "screen" (use screensharing for video, disables audio, takes precedence on both audio and video);
 *     - \c data: \c true/false (do or do not use Data Channels, default is false)
 *   - \c trickle: \c true/false, to tell the library whether you want
 * Trickle ICE to be used (true, the default) or not (false);
 *   - a set of callbacks to be notified about the result, namely:
 *     - \c success: the session description was created (attached as a parameter) and is ready to be sent to the plugin; 
 *     - \c error: the session description was NOT successfully created;
 * - \c createAnswer takes the same options as createOffer, but requires
 * an additional one as part of the single parameter argument:
 *   - \c jsep: the session description sent by the plugin (e.g., as received
 * in an \c onmessage callback) as its OFFER.
 *
 * Whether you use \c createOffer or \c createAnswer depending on the scenario,
 * you should end up with a valid \c jsep object returned in the \c success
 * callback. You can attach this \c jsep object to a message in a \c send request
 * to pass it to the plugin, and have the gateway negotiate a PeerConnection
 * with your application.
 *
 * Here's an example of how to use \c createOffer, taken from the Echo Test demo page:
 *
 \verbatim
// Attach to echo test plugin
janus.attach(
	{
		plugin: "janus.plugin.echotest",
		success: function(pluginHandle) {
			// Negotiate WebRTC
			echotest = pluginHandle;
			var body = { "audio": true, "video": true };
			echotest.send({"message": body});
			echotest.createOffer(
				{
					// No media property provided: by default,
						// it's sendrecv for audio and video
					success: function(jsep) {
						// Got our SDP! Send our OFFER to the plugin
						echotest.send({"message": body, "jsep": jsep});
					},
					error: function(error) {
						// An error occurred...
					}
				});
		},
		[..]
		onmessage: function(msg, jsep) {
			// Handle msg, if needed, and check jsep
			if(jsep !== undefined && jsep !== null) {
				// We have the ANSWER from the plugin
				echotest.handleRemoteJsep({jsep: jsep});
			}
		},
		[..]
		onlocalstream: function(stream) {
			// Invoked after createOffer
			// This is our video
		},
		onremotestream: function(stream) {
			// Invoked after handleRemoteJsep has got us a PeerConnection
			// This is the remote video
		},
		[..]
  \endverbatim
 *
 * This, instead, is an example of how to use \c createAnswer, taken from the Streaming demo page:
 *
 \verbatim
// Attach to echo test plugin
janus.attach(
	{
		plugin: "janus.plugin.streaming",
		success: function(pluginHandle) {
			// Handle created
			streaming = pluginHandle;
			[..]
		},
		[..]
		onmessage: function(msg, jsep) {
			// Handle msg, if needed, and check jsep
			if(jsep !== undefined && jsep !== null) {
				// We have an OFFER from the plugin
				streaming.createAnswer(
					{
						// We attach the remote OFFER
						jsep: jsep,
						// We want recvonly audio/video
						media: { audioSend: false, videoSend: false },
						success: function(ourjsep) {
							// Got our SDP! Send our ANSWER to the plugin
							var body = { "request": "start" };
							streaming.send({"message": body, "jsep": ourjsep});
						},
						error: function(error) {
							// An error occurred...
						}
					});
			}
		},
		[..]
		onlocalstream: function(stream) {
			// This will NOT be invoked, we chose recvonly
		},
		onremotestream: function(stream) {
			// Invoked after send has got us a PeerConnection
			// This is the remote video
		},
		[..]
  \endverbatim
 *
 * Of course, these are just a couple of examples where the scenarios
 * assumed that one plugin would only receive (Echo Test) or generate
 * (Streaming) offers. A more complex example (e.g., a Video Call plugin)
 * would involve both, allowing you to either send offers to a plugin,
 * or receive some from them. Handling this is just a matter of checking
 * the \c type of the \c jsep object and reacting accordingly.
 *  
 * <hr>
 * 
 * This is it! For more information about the API, have a look at the
 * demo pages that are available in the \b html folder in this package.
 * 
 */

/*! \page rest RESTful, WebSockets and RabbitMQ API
 *
 * Since version \c 0.0.6, there are three different ways to interact with a
 * Janus instance: a \ref plainhttp (the default), a \ref WS and a \ref rabbit
 * (both optional, need an external library to be available). All of
 * the interfaces use the same messages (in terms of requests, responses
 * and notifications), so almost all the concepts described in the
 * \ref plainhttp section apply to the WebSocket/RabbitMQ interfaces as well.
 * As it will be explained later in the \ref WS and \ref rabbit sections
 * below, the only differences come when addressing specific sessions/handles
 * and in part in how you handle notifications using WebSockets: in fact,
 * since with WebSockets and RabbitMQ there's no REST-based path involved,
 * you'll need a couple of additional identifiers to bridge the gap.
 * 
 * \section plainhttp Plain HTTP REST Interface
 * As anticipated in the \ref JS documentation, the gateway deploys a
 * RESTful interface that clients can exploit. The \c janus.js library
 * makes use of it in a transparent way, but if you're interested in
 * more details about it (e.g., because you want to talk to the gateway
 * your own way), this page described the interface and the protocol
 * the API exposes and uses. Some details are also provided in case you're
 * interested in \ref secret when wrapping requests in your application.
 *
 * There are basically three types/levels of endpoints you can meet:
 *
 * -# \ref root (\c /janus by default, but configurable), which
 * you only \b POST to in order to create a gateway session;
 * -# \ref sessions (e.g., \c /janus/12345678, using the
 * identifier retrieved with a previous create), which you either send
 * a \b GET to (long poll for events and messages from plugins) or a \b POST
 * (to create plugin handles or manipulate the session);
 * -# \ref handles (e.g., \c /janus/12345678/98765432, appending
 * the handle identifier to the session one) which you only send \b POST
 * messages to (messages/negotiations for a plugin, handle manipulation),
 * as all events related to this handle would be received in the session
 * endpoint \b GET (the \c janus.js library would redirect the incoming
 * messages to the right handle internally).
 *
 * Messages and requests you can send to and receive from any of the
 * above mentioned endpoints are described in the following chapters.
 * In general, all messages share at least two fields:
 * 
 * - \c janus: the request/event (e.g., "create", "attach", "message", etc.);
 * - \c transaction: a random string that the client can use to match incoming
 * messages from the gateway (since, as explained in the \ref plugins
 * documentation, all messages are asynchronous).
 *
 * Different messages will of course add different information to this
 * base syntax. Error message, instead, usually have these fields:
 *
 * - \c janus: this would be "error";
 * - \c transaction: this would be the transaction identifier of the request
 * that failed;
 * - \c error: a JSON object containing two fields:
 *   - \c code: a numeric error code, as defined in apierror.h;
 *   - \c reason: a verbose string describing the cause of the failure.
 *
 * An example of an error is presented here:
 *
\verbatim
{
	"janus" : "error",
	"transaction" : "a1b2c3d4"
	"error" : {
		"code" : 458
		"reason" : "Could not find session 12345678"
	}
}
\endverbatim
 *
 *
 * \section info Getting info about the Janus instance
 * The API exposes an \c info endpoint you can query to get information
 * about the Janus instance you're talking to. Specifically, it returns
 * information about the version of the Janus server, whether some of the
 * optional features (Data Channels and WebSockets) are supported or not, 
 * and which plugins are available.
 *
 * To get this information, just send an HTTP \b GET message to the \c info
 * endpoint (e.g., http://yourserver:8088/janus/info), which will return
 * something like this:
 *
\verbatim
{
	"version_string": "0.0.6",
	"author": "Meetecho s.r.l.",
	"name": "Janus WebRTC Gateway",
	"version": 4,
	"websockets": 1,		// WebSockets are supported
	"data_channels": 1,		// Data Channels are supported
	"rabbitmq": 1,			// RabbitMQ is supported
	"plugins": {
		"janus.plugin.sip": {		// The SIP plugin is available
			"version_string": "0.0.2",
			"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.",
			"author": "Meetecho s.r.l.",
			"name": "JANUS SIP plugin",
			"version": 2
		},
		"janus.plugin.videoroom": {	// The Video MCU plugin is available
			"version_string": "0.0.3",
			"description": "This is a plugin implementing a videoconferencing MCU for Janus, something like Licode.",
			"author": "Meetecho s.r.l.",
			"name": "JANUS VideoRoom plugin",
			"version": 3
		},
		[..]	// Other plugins
	}
\endverbatim
 *
 * You can use this information to selectively enable or disable features
 * in your application according to what's available in the Janus instance
 * you're trying to contact.
 *
 *
 * \section root The gateway root
 * The gateway root is \c /janus by default but, as anticipated, it is
 * configurable, either via command line or in the \c janus.cfg configuration.
 *
 * You can only contact the gateway root when you want to create a new
 * session with the gateway. To do so, you need to \b POST the a \c janus "create"
 * JSON message to the gateway:
 *
\verbatim
{
	"janus" : "create",
	"transaction" : "<random alphanumeric string>"
}
\endverbatim
 *
 * If the request is successful, you'll receive the unique session identifier
 * in a response formatted like this:
 *
\verbatim
{
	"janus" : "success",
	"transaction" : "<same as the request>",
	"data" : {
		"id" : <unique integer session ID>
	}
}
\endverbatim
 *
 * In case of an error, you'll receive an error message as the one introduced
 * before. This request, if issued with a POST to the gateway root, can only
 * fail if you miss any of the required fields in the request.
 *
 *
 * \section sessions The session endpoint
 * Once you've created a session, a new endpoint you can use is created
 * in the gateway. Specifically, the new endpoint is constructed by
 * concatenating the gateway root and the session identifier you've been
 * returned (\c e.g., \c /janus/12345678).
 *
 * This endpoint can be used in two different ways: 
 *
 * -# using a parameter-less \b GET request to the endpoint, you'll
 * issue a long-poll request to be notified about events and incoming
 * messages from this session;
 * -# using a \b POST request to send JSON messages, you'll interact
 * with the session itself.
 *
 * <hr>
 *
 * \par Long-poll requests
 * The long-poll will only trigger events related to messages you're
 * being sent from plugins, and as such will be clearer to understand
 * once you read the \ref handles section. That said, the events are formatted
 * this way:
 *
 * - \c janus: this would be "event";
 * - \c sender: this would be the unique numeric plugin handle identifier;
 * - \c transaction: this is optional: it is either related to a request
 * you sent to a plugin before, or it may be missing in case this is an
 * event the plugin sent on its own account;
 * - \c plugindata: a JSON object containing the info coming from the plugin itself:
 *   - \c plugin: the plugin's unique package name (e.g., \c janus.plugin.echotest);
 *   - \c data: an opaque JSON object that is plugin specific.
 * - \c jsep: an optional JSON object containing the JSEP SDP (offer or
 * answer) the plugin may send to negotiate a WebRTC PeerConnection with
 * the client (check the \ref handles section for more details).
 *
 * An example of such an event (in this case, sent by the janus_echotest.c
 * plugin in response to a request) is presented here:
 *
\verbatim
{
	"janus" : "event",
	"sender" : 1815153248,
	"transaction" : "sBJNyUhH6Vc6",
	"plugindata" : {
		"plugin": "janus.plugin.echotest",
		"data" : {
			"echotest" : "event",
			"result" : "ok"
		}
	},
}
\endverbatim
 *
 * The long-poll request has a 30 seconds timeout. If it has no event to
 * report, a simple \em keep-alive message will be triggered:
 *
\verbatim
{
	"janus" : "keepalive",
}
\endverbatim
 *
 * As with all long-poll based approaches, it's up to your application
 * to send a new polling request as soon as an event or a keep-alive
 * has been received.
 *
 * Notice that, by default, the long poll returns a single event: that is,
 * as soon as a message becomes available in the session queue, that event
 * is returned and the long poll closes. If you want to receive more events
 * within the context of the same long poll, you can pass the \c maxev
 * query string parameter to the GET, e.g.:
 *
\verbatim
GET http://host:port/janus/<sessionid>?maxev=5
\endverbatim
 *
\verbatim
[
	{
		// Event #1
		"janus" : "event",
		[..]
	},
	{
		// Event #2
		"janus" : "event",
		[..]
	},
	[..]
]
\endverbatim
 *
 * This request will instruct the gateway to return at maximum 5 events
 * within the context of the same long poll, formatted as a JSON array
 * of events. Please beware that this does \b NOT mean that you'll
 * always get 5 events this way: it only means that, if a message becomes
 * available in the queue and more events are present as well, Janus will
 * return more than one without needing you to send multiple long polls
 * immediately thereafter to get them. For this reason, don't be surprised
 * if even with a \c maxev parameter set, you'll still get a single
 * event being notified as the sole object in the returned array.
 *
 * <hr>
 *
 * \par Interacting with the session
 * To interact with the session, e.g., to create a new handle to attach
 * to a plugin or destroy the current session, you need to send a \b POST
 * JSON message to the session endpoint.
 *
 * To attach to a plugin in order to exploit its features, you need to
 * \b POST a \c janus "attach" JSON message to the gateway; you'll need
 * of course to provide information on the plugin you want to attach to,
 * which can be done using the \c plugin field: 
 *
\verbatim
{
	"janus" : "attach",
	"plugin" : "<the plugin's unique package name>",
	"transaction" : "<random string>"
}
\endverbatim
 *
 * If the request is successful, you'll receive the unique plugin handle
 * identifier in a response formatted the same way as the session create
 * one, that is like this:
 *
\verbatim
{
	"janus" : "success",
	"transaction" : "<same as the request>",
	"data" : {
		"id" : <unique integer plugin handle ID>
	}
}
\endverbatim
 *
 * In case of an error, you'll receive an error message as the one introduced
 * before. This request, if issued with a POST to a valid session endpoint, can only
 * fail if you miss any of the required fields in the request or if the
 * plugin you requested is not available in the gateway.
 *
 * To destroy the current session, instead, just send a "destroy" \c janus
 * request:
 *
\verbatim
{
	"janus" : "destroy",
	"transaction" : "<random string>"
}
\endverbatim
 *
 * This will also destroy the endpoint created for this session.
 * If your session is currently managing one or more plugin handles, 
 * make sure you destroy them first (as explained in the next section).
 * The gateway tries to do this automatically when receiving a session
 * destroy request, but a cleaner approach on the client side would help 
 * nonetheless avoid potential issues.
 *
 * \section handles The plugin handle endpoint
 * Once you've created a plugin handle, a new endpoint you can use is created
 * in the gateway. Specifically, the new endpoint is constructed by
 * concatenating the gateway root, the session identifier and the new
 * plugin handle identifier you've been returned (\c e.g.,
 * \c /janus/12345678/98765432).
 *
 * You can use this plugin handle for everything that is related to the
 * communication with a plugin, that is, send the plugin a message,
 * negotiate a WebRTC connection to attach to the plugin, and so on.
 *
 * To send a plugin a message/request, you need to \b POST the handle
 * endpoint a \c janus "message" JSON payload. The \c body field will
 * have to contain a plugin-specific JSON payload. In case the message
 * also needs to convey WebRTC-related negotiation information, a \c jsep
 * field containing the JSON-ified version of the JSEP object can be 
 * attached as well.
 *
 * \note If you attach a \c jsep object, whether it's an offer or an answer,
 * you're stating your will to negotiate a PeerConnection. This means that
 * an empty or invalid \c jsep object will trigger a validation and will
 * cause the whole request to fail, so make sure you exclude the field
 * completely from your request if all you're interested into is sending
 * a message to a plugin.
 *
 * Here's an example of a message you may send the janus_echotest.c plugin
 * to mute your audio:
 *
\verbatim
{
	"janus" : "message",
	"transaction" : "sBJNyUhH6Vc6",
	"body" : {
		"audio" : false
	}
}
\endverbatim
 *
 * The same message containing negotiation information as well, instead,
 * (an OFFER, in this example), is presented here:
 *
\verbatim
{
	"janus" : "message",
	"transaction" : "sBJNyUhH6Vc6",
	"body" : {
		"audio" : false
	},
	"jsep" : {
		"type" : "offer",
		"sdp" : "v=0\r\no=[..more sdp stuff..]"
	}
}
\endverbatim
 *
 * If you're going to \c trickle candidates rather than including them
 * all in an SDP OFFER or ANSWER, there is an ad-hoc message you can use
 * to do so which is called, unsurprisingly, \c trickle and which you
 * can use to send one or more trickle candidates to Janus. Since such
 * a message is related to a specific PeerConnection, it will need to be
 * addressed to the right Handle just as the \c message introduced
 * previously. A \c trickle message can contain three different kind of
 * information:
 *
 *  - a single trickle candidate;
 *  - an array of trickle candidates;
 *  - a null candidate or a \c completed JSON object to notify the end of the
 * candidates.
 *
 * This is an example of a single candidate being trickled:
 *
\verbatim
{
	"janus" : "trickle",
	"transaction" : "hehe83hd8dw12e",
	"candidate" : {
		"sdpMid" : "video",
		"sdpMLineIndex" : 1,
		"candidate" : "..."
	}
}
\endverbatim
 *
 * This, instead, is an example of how to group more trickle candidates
 * in a single request (particularly useful if you're wrapping Janus in
 * your server and want to reduce the number of transactions):
 *
\verbatim
{
	"janus" : "trickle",
	"transaction" : "hehe83hd8dw12e",
	"candidates" : [ 
		{
			"sdpMid" : "video",
			"sdpMLineIndex" : 1,
			"candidate" : "..."
		},
		{
			"sdpMid" : "video",
			"sdpMLineIndex" : 1,
			"candidate" : "..."
		},
		[..]
	]
}
\endverbatim
 *
 * Finally, this is how you can tell Janus that you sent all the trickle
 * candidates that were gathered:
 *
\verbatim
{
	"janus" : "trickle",
	"transaction" : "hehe83hd8dw12e",
	"candidate" : {
		"completed" : true
	}
}
\endverbatim
 *
 * Plugins may handle this requests synchronously or asynchronously. In
 * the former, plugins would return a response to the request itself
 * immediately; in the latter, instead, the plugin would only notify a
 * successful reception of the request, which it would process later.
 * Considering the asynchronous nature of the Janus API, a successful
 * management of such messages within the gateway would in such case result in
 * a \c janus "ack" messages being sent back to the client. A logical response
 * to those messages, if needed, would be provided as an event in the
 * long-poll interface described previously, and clients would be able
 * to match it to the original request by means of the transaction
 * identifiers. It is worth noting, though, that should a WebRTC negotiation
 * be involved you don't have to expect an ANSWER to your OFFER to be
 * sent back in the same transaction. A plugin may decide, in its
 * application logic, to not provide you with an ANSWER right away, but
 * only after some internal state changes occur. It's up to your application
 * to handle the negotiation state accordingly.
 *
 * An example of an "ack" being sent back to the client, using the previous
 * sample request as a reference, is presented here:
 *
\verbatim
{
	"janus" : "ack",
	"transaction" : "sBJNyUhH6Vc6"
}
\endverbatim
 *
 * If you receive this ack instead of a "success" response, you can be
 * sure the plugin has received the message, and is going to process it soon.
 *
 * In case of an error, instead, you'll receive an error message as the one
 * introduced before. This request, if issued with a POST to a valid plugin
 * handle endpoint, can only fail if you miss any of the required fields
 * in the request, if the plugin you tried to contact is not available in
 * the gateway anymore, if an error occurred in the plugin when trying to
 * receive the message or if the \c jsep SDP you may have provided is
 * invalid.
 *
 * To destroy the plugin handle, instead, just send a "detach" \c janus
 * request:
 *
\verbatim
{
	"janus" : "detach",
	"transaction" : "<random string>"
}
\endverbatim
 *
 * This will also destroy the endpoint created for this plugin handle.
 * If your plugin handle is also managing an ongoing WebRTC connection
 * with the plugin, make sure it is torn down as part of this process.
 * The plugin implementation and the gateway core should do this
 * automatically, but implementing the right behaviour in clients would
 * help avoid potential issues nonetheless.
 *
 * \section events WebRTC-related events
 *
 * As anticipated in the previous sections, Janus can send events and
 * notifications at any time through the long poll channel (or, as it
 * will be explained later, through the related push mechanisms made
 * available by the \ref WS and \ref rabbit ). While this channel is
 * mostly used to convey asynchronous notifications originated by
 * plugins as part of the messaging they may have with the application
 * using it, the same channel is actually used by Janus to trigger
 * events related to different aspects pertaining a specific handle.
 *
 * In particular, for each handle involving a PeerConnection Janus
 * provides notifications about its current state. To do so, the
 * following events may be received as well:
 *
 *  - \c webrtcup: ICE and DTLS succeeded, and so Janus correctly
 * established a PeerConnection with the user/application;
 *  - \c media: whether Janus is receiving (\c receiving: \c true/false)
 * audio/video (\c type: \c "audio/video") on this PeerConnection;
 *  - \c hangup: the PeerConnection was closed, either by Janus or by
 * the user/application, and as such cannot be used anymore.
 *
 * As such, to monitor the status of a PeerConnection as seen from
 * Janus you can make use of these events to track what's going on. A
 * correct flow for an active PeerConnection would be one that, after a
 * WebRTC negotiation and setup, results in a \c webrtcup event followed
 * by two \c media events (in case both audio and video have been
 * negotiated) specifying that the first audio/video packets have been
 * received. A \c hangup event would inform the user/application that
 * no media is being exchanged with Janus anymore.
 *
 * Here are a few examples of how these events may look like.
 *
 * A PeerConnection becoming ready:
 *
\verbatim
{
	"janus" : "webrtcup",
	session_id: <the session identifier>,
	sender: <the handle identifier>
}
\endverbatim
 *
 * First audio bytes being received by Janus:
 *
\verbatim
{
	"janus" : "media",
	session_id: <the session identifier>,
	sender: <the handle identifier>,
	"type" : "audio",
	"receiving" : true
}
\endverbatim
 *
 * Audio not getting to Janus anymore for some reason:
 *
\verbatim
{
	"janus" : "media",
	"session_id" : <the session identifier>,
	"sender" : <the handle identifier>
	"type" : "audio",
	"receiving" : false
}
\endverbatim
 *
 * Audio getting to Janus again (same message as first audio):
 *
\verbatim
{
	"janus" : "media",
	"session_id" : <the session identifier>,
	"sender" : <the handle identifier>
	"type" : "audio",
	"receiving" : true
}
\endverbatim
 *
 * PeerConnection closed for a DTLS alert (normal shutdown):
 *
\verbatim
{
	"janus" : "hangup",
	"session_id" : <the session identifier>,
	"sender" : <the handle identifier>,
	"reason" : "DTLS alert"
}
\endverbatim
 *
 * It is important to point out that the \c media event notifications
 * only apply if your PeerConnection is going to actually send media to
 * Janus. A \c recvonly PeerConnection, for instance (e.g., as the
 * Streaming plugin would create) would never trigger any \c media
 * event, as Janus would never be receiving media, but only send it.
 *
 * \section secret Securing the API
 * Several deployers showed an interested in wrapping the Janus API on
 * their server side: this allows them to keep the interaction with their
 * users the way it was before, while still benefiting from the features
 * Janus provides. This is an easy enough step, as it just needs developers
 * to relay the involved SDP, and implementing the Janus API messages to
 * handle the logic.
 *
 * That said, since in this case Janus would be contacted, through the API,
 * just by a limited number of applications (e.g., application servers
 * made in node.js, Ruby, Java Servlets or whatever) and not random
 * browsers, it is reasonable to involve a mechanism to control who is
 * allowed to contact and control it. To allow for that, Janus exposes a
 * shared API secret mechanism: that is, you configure Janus with a string
 * applications need to present when sending requests, and if they don't,
 * Janus rejects them with an \c unauthorized message.
 * 
 * Configuring the API secret mechanism is easy enough: you can do that
 * either via the command line (\c -a or \c --apisecret ) or in the
 * \c janus.cfg configuration (\c api_secret value in the \c general section).
 * When enabled, all requests addressed to that Janus instance \b MUST
 * also contain an \c apisecret field in the Janus message headers. For
 * instance, this message presented above would fail:
 * 
\verbatim
{
	"janus" : "create",
	"transaction" : "<random alphanumeric string>"
}
\endverbatim
 * 
\verbatim
{
	"janus": "error",
	"error": {
		"reason": "Unauthorized request (wrong or missing apisecret)",
		"code": 403
	}
}
\endverbatim
 * 
 * For a successful transaction, the message would have to look like this:
 * 
\verbatim
{
	"janus" : "create",
	"apisecret" : "<API secret configured in Janus>",
	"transaction" : "<random alphanumeric string>"
}
\endverbatim
 * 
 * The same applies for the long poll GET messages as well, which will
 * need to contain the \c apisecret as a query string parameter.
 * 
 * \section WS WebSockets Interface
 * In recent version of Janus we added support for WebSockets to control
 * the gateway, along the already existing (and still the default) REST
 * API. In fact, while WebSockets still present some more issues in terms
 * of reachability when compared to plain HTTP, they definitely provide
 * a more efficient means for implementing a bidirectional communication.
 * This is especially useful if you're wrapping the Janus API on your
 * servers, as it allows you to avoid all the noise and overhead introduced
 * by several concurrent HTTP transactions and long polls by relying on
 * what may be seen as a single "control channel".
 *
 * To interact with Janus using WebSockets you MUST specify a specific
 * subprotocol, named \c janus-protocol, e.g.,
 *
\verbatim
var websocket = new WebSocket('ws://1.2.3.4:8188', 'janus-protocol');
\endverbatim
 * 
 * The \c janus.js library does this automatically.
 *
 * As anticipated at the beginning of this section, the actual messages
 * being exchanged are exactly the same. This means that all the concepts
 * introduced before still apply: you still create a session, attach to
 * a plugin and interact with it exactly the same way. What is different
 * is, of course, the REST path approach that becomes unavailable when
 * using a WebSocket as a control channel. To address the idenfitiers
 * that become missing using WebSockets, you'll need to add additional
 * fields to the requests when necessary.
 * 
 * So, when you want to create a session using the REST API, you send a
 * POST to the gateway base path: 
 * 
\verbatim
{
	"janus" : "create",
	"transaction" : "<random alphanumeric string>"
}
\endverbatim
 * 
 * The same applies if you're interested in getting generic info from the
 * Janus instance. Since there's no \b GET you can use, a specific \c janus
 * request type called \c info is available:
 * 
\verbatim
{
	"janus" : "info",
	"transaction" : "<random alphanumeric string>"
}
\endverbatim
 * 
 * Since you'd contact the base path for both requests, you don't need to add any identifier
 * for this scenario. But if instead you want to attach to a plugin within
 * the context of a specific session, using the REST API you'd send a
 * post to the \c /janus/<session-id> endpoint:
 * 
\verbatim
{
	"janus" : "attach",
	"plugin" : "<the plugin's unique package name>",
	"transaction" : "<random string>"
}
\endverbatim
 * 
 * To make this work with WebSockets as well, you need to add a further
 * field called \c session_id in the request:
 * 
\verbatim
{
	"janus" : "attach",
	"session_id" : <the session identifier>,		// NEW!
	"plugin" : "<the plugin's unique package name>",
	"transaction" : "<random string>"
}
\endverbatim
 * 
 * which will allow the WebSocket server to understand which session this
 * request pertains to. At the same time, when you need to address a
 * specific handle (e.g., to send a message to a plugin, or negotiate a
 * WebRTC PeerConnection) you'll need to add a \c handle_id field to the
 * request as well, or the request will be rejected:
 *
\verbatim
{
	"janus" : "message",
	"session_id" : <the session identifier>,		// NEW!
	"handle_id" : <the handle identifier>,		// NEW!
	"transaction" : "sBJNyUhH6Vc6",
	"body" : {
		"audio" : false
	}
}
\endverbatim
 *
 * Considering the bidirectional nature of WebSockets and the fact that
 * the channel will be shared for different requests, you'll need to pay
 * extra attention to the \c transaction identifier, which will allow you
 * to map incoming responses and events to the request you sent that
 * originated them.
 * 
 * An \b important aspect to point out is related to keep-alive messages
 * for WebSockets Janus channels. A Janus session is kept alive as long
 * as there's no inactivity for 60 seconds: if no messages have been
 * received in that time frame, the session is torn down by the gateway.
 * A normal activity on a session is usually enough to prevent that;
 * for a more prolonged inactivity with respect to messaging, on plain
 * HTTP the session is usually kept alive through the regular long poll
 * requests, which act as activity as long as the session is concerned.
 * This aid is obviously not possible when using WebSockets, where a single channel is
 * used both for sending requests and receiving events and responses. For
 * this reason, an ad-hoc message for keeping alive a Janus session should
 * to be triggered on a regular basis:
 * 
\verbatim
{
	"janus" : "keepalive",
	"session_id" : <the session identifier>,
	"transaction" : "sBJNyUhH6Vc6"
}
\endverbatim
 * 
 * This will make sure that the gateway detects activity on the session
 * even when no actual messages are being exchanged with handles.
 * 
 * As a last point, another slight difference with WebSockets comes from
 * how push notifications are implemented. In the \ref plainhttp this is
 * done via long polls: that is, you explicitly subscribe to notifications,
 * and have to do that again as soon as an event has been received. With
 * WebSockets, this is not needed: as soon as you create a session on a
 * WebSocket, that channel becomes automatically subscribed for events
 * related to that sessions, and you'll receive them on the same WebSocket.
 * For the same reason, as soon as the WebSocket is closed, all the sessions
 * created within its context are considered closed as well, and so their
 * resources (including all the handles and PeerConnections) will be
 * released as well.
 * 
 * \note The same \c janus.js JavaScript library can be used both with the
 * REST and the WebSockets API: all you need to do is provide the right
 * Janus server address during the initialization and the library will
 * use one or the other according to the protocol prefix.
 * 
 * \section rabbit RabbitMQ interface
 * The semantics of how the requests have to be built, when compared to
 * the usage of plain HTTP, is exactly the same as for WebSockets, so 
 * refer to the \ref WS documentation for details about that.
 * 
 * Of course, there are other aspects that differ when making use of 
 * RabbitMQ messaging to talk to Janus, rather than using HTTP messages
 * or WebSockets. Specifically, RabbitMQ just basically forwards messages
 * on queues, and as such implementing a pseudo-bidirectional channel
 * as the Janus API requires needs some precaution.
 * 
 * In particular, when configuring Janus to use RabbitMQ you'll have to
 * specify \b two \b queues:
 *
 * - a queue for \b incoming messages (application -> Janus);
 * - a queue for \b outgoing messages (Janus -> application).
 *
 * The proper usage of these queues will allow you to implement the kind
 * of bidirectional channel Janus needs.
 *
 * Another aspect to point out is that Janus requires all requests to
 * have a random \c correlation_id identifier. In fact, as pointed out
 * in the previous sections, the Janus API is conceived as a request/response
 * protocol that can involve asynchronous notifications as well. In order
 * to make sure that an application can match a received response to one
 * of the requests made earlier, Janus copies the \c correlation_id
 * identifier from the original request in the response to it: this is
 * compliant with the
 * <a href="https://www.rabbitmq.com/tutorials/tutorial-six-python.html">RPC pattern</a>
 * as specified in the RabbitMQ documentation. Notifications originated by
 * Janus, instead, will not include a \c correlation_id identifier, and as
 * such applications shouldn't expect any: applications will still be able
 * to match a notification to a request, if the involved plugin was
 * implemented to do so, by looking at the Janus-level \c transaction
 * identifier.
 * 
 */

/*! \page admin Admin/Monitor API
 * Recent versions of Janus introduced a new feature: an Admin/Monitor
 * API that can be used to ask Janus for more specific information
 * related to sessions and handles. This is especially useful when you
 * want to debug issues at the media level.
 *
 * \note Right now, this new API only allows you to retrieve information,
 * but not act on part of it: for more interaction (e.g., to force a
 * session removal), you can rely on the existing \ref rest for the purpose.
 *
 * The API, for security reasons, is not enabled by default. You can enable
 * it by editing the \c [admin] section in the \c janus.cfg configuration
 * file accordingly. The configuration is pretty much the same as the one
 * for the \ref plainhttp so you can refer to that one. In addition, you
 * can configure restrictions in the form of a password/secret that clients
 * need to provide and access lists based on full/partial addresses.
 *
 * For what concerns the syntax, it's very similar to the \ref rest and
 * so this page will briefly discuss the differences. At the moment, a few
 * different methods are exposed:
 *
 * - \c list_sessions: list all the sessions currently active in Janus
 * (returns an array of session identifiers);
 * - \c list_handles: list all the ICE handles currently active in a Janus
 * session (returns an array of handle identifiers);
 * - \c handle_info: list all the available info on a specific ICE handle;
 * - \c set_log_level: change the log level in Janus on the fly;
 * - \c set_locking_debug: selectively enable/disable a live debugging of
 * the locks in Janus on the fly (useful if you're experiencing deadlocks
 * and want to investigate them).
 *
 * Following the same spirit of the \ref rest these methods need to be
 * invoked on the right path and/or providing the right \c session_id and
 * \c handle_id identifiers. Specifically, \c list_sessions must be invoked
 * without any session/handle information, as it's a global request. Here's
 * an example of how such a request and its related response might look like:
 *
\verbatim
POST /admin
{
	"janus" : "list_sessions",
	"transaction" : "<random alphanumeric string>",
	"admin_secret" : "<password specified in janus.cfg, if any>"
}
\endverbatim
 *
 *
\verbatim
{
	"janus" : "success",
	"transaction" : "<same as the request>",
	"sessions" : [
		<session ID #1>,
		<session ID #2>,
		[..]
		<session ID #n>
	]
}
\endverbatim
 *
 * On the other hand, since \c list_handles is related to a specific session,
 * a session must be referenced correctly. Using the REST API, this can
 * be done by appending the session identifier (e.g., one of the IDs
 * returned by the previous call) to the API root:
 *
\verbatim
POST /admin/12345678
{
	"janus" : "list_handles",
	"transaction" : "<random alphanumeric string>",
	"admin_secret" : "<password specified in janus.cfg, if any>"
}
\endverbatim
 *
 *
\verbatim
{
	"janus" : "success",
	"transaction" : "<same as the request>",
	"session_id" : 12345678,
	"handles" : [
		<handle ID #1>,
		<handle ID #2>,
		[..]
		<handle ID #n>
	]
}
\endverbatim
 *
 * Once a list of handles is available, detailed info on any of them can
 * be obtained by means of a \c handle_info call. Since this is a
 * handle-specific request, the correct handle identifier must be
 * referenced, e.g., by appending the ID to the session it belongs to:
 *
\verbatim
POST /admin/12345678/98765432
{
	"janus" : "handle_info",
	"transaction" : "<random alphanumeric string>",
	"admin_secret" : "<password specified in janus.cfg, if any>"
}
\endverbatim
 *
 *
\verbatim
{
	"janus" : "success",
	"transaction" : "<same as the request>",
	"session_id" : 12345678,
	"handle_id" : 98765432,
	"info" : {
		"plugin": "janus.plugin.echotest",
		"flags": {
			// flags
		},
		"sdps": {
			"local": "v=0[..]",
			"remote": "v=0[..]"
		},
		"streams": [
			// streams, components, etc.
		]
	}
}
\endverbatim
 *
 * The actual content of the last response is omitted for brevity, but
 * you're welcome to experiment with it in order to check whether more
 * information (of a different nature, maybe) may be useful to have.
 *
 * \note At the moment, no plugin-related information is available through
 * this API. The only plugin-related information you can find is which
 * plugin a specific handle is attached to.
 *
 * Finally, the syntax for the \c set_log_level and \c set_locking_debug
 * commands is quite straightforward:
 *
\verbatim
POST /admin
{
	"janus" : "set_log_level",
	"level" : <integer between 0 and 7, see debug.h>,
	"transaction" : "<random alphanumeric string>",
	"admin_secret" : "<password specified in janus.cfg, if any>"
}
\endverbatim
 *
\verbatim
POST /admin
{
	"janus" : "set_locking_debug",
	"debug" : <0 to disable, 1 to enable>,
	"transaction" : "<random alphanumeric string>",
	"admin_secret" : "<password specified in janus.cfg, if any>"
}
\endverbatim
 *
 * Both commands will return the updated level/debug setting if successful,
 * and an error otherwise.
 *
 */

/*! \page deploy Deploying Janus
 *
 * When you're going to deploy Janus (e.g., to try the demos we made
 * available out-of-the-box), there's one thing that is important to point
 * out: while Janus does indeed provide an HTTP RESTful interface (documented
 * in \ref rest), it does \b NOT also act as a webserver for static files.
 * This means you'll need a different webserver to host static files, including
 * HTML/PHP/JSP/etc. pages, JavaScript files, images and whatever is part
 * of your web application.
 *
 * That said, deploying Janus is, in principle, quite simple: just start Janus on a
 * machine, put the HTML and JavaScript that will make use of it on a webserver
 * somewhere, make sure the JavaScript code is configured with the right
 * address for the gateway and you're done!
 *
 * Let's assume, for the sake of simplicity, that your webserver is serving
 * files on port \c 80. By default, Janus binds on the \c 8088 port for HTTP.
 * So, if Janus and the webserver hosting the are co-located, all you need to get your 
 * application working is configure the web application to point to the right
 * address for the gateway. In the demos provided with these packages, this
 * is done by means of the \c server variable:
 *
 \verbatim
var server = "http://" + window.location.hostname + ":8088/janus";
 \endverbatim
 *
 * which basically tells the JavaScript application that the Janus API can be
 * contacted at the same host as the website but at a different port (8088) and path (/janus). 
 * In case you configured the gateway differently, e.g., 7000 as the port 
 * for HTTP and /my/custom/path as the API endpoint, the \c server variable
 * could be built this way:
 *
 \verbatim
var server = "http://" + window.location.hostname + ":7000/my/custom/path";
 \endverbatim
 *
 * In case the webserver and Janus are <b>NOT</b> colocated, instead, just
 * replace the \c window.location.hostname part with the right address of
 * the gateway, e.g.:
 *
 \verbatim
var server = "http://www.example.com:8088/janus";
 \endverbatim
 *
 * It's important to point out, though, that this more "static" approach
 * only works if the webserver is serving files via HTTP. As soon as you
 * start involving \b HTTPS, things start to get more complicated: in fact,
 * for security reasons you cannot contact an HTTP backend if the page is
 * made available via HTTPS. This means that if you're interested in serving
 * your web application via HTTPS, you'll need to enable the HTTPS embedded
 * webserver in Janus as well, and configure the JavaScript code to refer to
 * that itself, e.g.:
 *
 \verbatim
var server = "https://" + window.location.hostname + ":8089/janus";
 \endverbatim
 *
 * assuming \c 8089 is the port you configured Janus to use for HTTPS.
 * To make this more "dynamic", e.g., allow both HTTP and HTTPS instead of
 * just sticking to one, you might make use of something like this:
 *
 \verbatim
var server = null;
if(window.location.protocol === 'http:')
	server = "http://" + window.location.hostname + ":8088/janus";
else
	server = "https://" + window.location.hostname + ":8089/janus";
 \endverbatim
 *
 * that is evaulate the right address to use at runtime.
 *
 * Anyway, there's a much easier way to address these scenarios, which
 * is explained in the next section.
 *
 * \section apache Deploying Janus behind a web frontend
 *
 * To avoid most of the issues explained above, an easy approach can be
 * deploying Janus behind a frontend, that would act as a reverse proxy for it.
 * This would allow you to make the Janus API available as a relative path 
 * of your web application, rather than a service reachable at a different
 * port and/or domain.
 *
 * Configuring the web application, as a consequence, would be even easier,
 * as all you'd need to do would be to provide a relative path for the API,
 * e.g.:
 *
 \verbatim
var server = "/janus";
 \endverbatim
 *
 * which would automatically work whether the page is served via HTTP or
 * HTTPS. In fact, all the HTTPS requests would be terminated at the webserver,
 * which would then always send simple HTTP messages to the gateway itself.
 *
 * An easy way to do so in Apache HTTPD is by means of the following directives:
 *
 \verbatim
ProxyRequests Off
ProxyVia Off
ProxyPass /janus http://127.0.0.1:8088/janus
ProxyPassReverse /janus http://127.0.0.1:8088/janus
 \endverbatim
 *
 * Different versions of HTTPD or different webservers may require a
 * different syntax, but the principle is usually always the same: you instruct
 * the webserver to act as a proxy for a local endpoint, in this case a
 * Janus instance colocated at the webserver and configured with the
 * default settings.
 *
 * \section webserver A quick and easy web server
 * While opening WebRTC-powered web applications by just opening the
 * application HTML files from file system works with some browsers, it
 * doesn't in others. Specifically, this works in Firefox but not in Chrome
 * (see <a href="https://github.com/meetecho/janus-gateway/issues/291">issue #291</a>).
 * Anyway, considering that you will eventually want other people besides
 * you to use your Janus services, this means that to test and use Janus
 * you'll want/need to host your applications on a webserver.
 * 
 * If you're not interested in configuring a full-fledged webserver, but
 * are only interested in a quick and easy way to test the demos, you can
 * make use of the embedded webservers some frameworks like PHP and Python
 * provide. To start a webserver for the demos, for instance, just open a
 * terminal in the \c html folder of the project, and type:
 *
 *\verbatim
php -S 0.0.0.0:8000
 \endverbatim
 *
 * or:
 *
 *\verbatim
python -m SimpleHTTPServer 8000
 \endverbatim
 *
 * This will setup a webserver on port \c 8000 for you to use, meaning you'll
 * just need to have your browser open a local connection to that port to 
 * try the demos:
 *
 *\verbatim
http://yourlocaliphere:8000
 \endverbatim
 *
 * You can do the same on a different port to also access the HTML version of the Doxygen generated
 * documentation, starting the embedded webservers from the \c docs/html
 * folder instead:
 *
 *\verbatim
php -S 0.0.0.0:9000
 \endverbatim
 *
 * or:
 *
 *\verbatim
python -m SimpleHTTPServer 9000
 \endverbatim
 *
 * \section deplyws Using Janus with WebSockets 
 *
 * Configuring the usae of WebSockets rather than the REST API in the JavaScript
 * library is quite trivial, as it's a matter of passing a \c ws:// address
 * instead of an \c http:// one to the constructor. That said, most of the same
 * considerations provided for the REST API apply here as well, e.g.,
 * to just use \c window.location.hostname if the webserver and Janus are
 * colocated:
 *
 \verbatim
var server = "ws://" + window.location.hostname + ":8188/";
 \endverbatim
 *
 * to specify the port if you change it:
 *
 \verbatim
var server = "ws://" + window.location.hostname + ":7000/";
 \endverbatim
 *
 * and/or the right address of the gateway in case the webserver and Janus
 * are <b>NOT</b> colocated:
 *
 \verbatim
var server = "ws://www.example.com:8188/";
 \endverbatim
 *
 * Notice how the path (\c /janus by default for HTTP) is not provided
 * for WebSockets, as it is ignored by the gateway.
 *
 * The considerations for deploying Janus behind a proxy/webserver, though,
 * differ if you use WebSockets. Instead, most webservers (e.g., Apache HTTPD)
 * don't provide an easy way to proxy WebSocket requests, and usually
 * require custom modifications for the purpose. If this is something
 * you're interested in, we recommend you follow the best practices related
 * to that made available by the web server developers.
 *
 * \section both Using fallback addresses 
 * As anticipated in the \ref JS section, you can also pass an array of servers
 * to the Janus library initialization. This allows you, for instance, to
 * pass a link to both the WebSockets and REST interfaces, and have the
 * library try them both to see which one is reachable, e.g.:
 *
 \verbatim
var ws_server = "ws://" + window.location.hostname + ":8188/";
var http_server = "http://" + window.location.hostname + ":8088/janus";
var servers = [ws_server, http_server];
 \endverbatim
 *
 * which is especially useful if you're not sure whether or not WebSockets
 * will work in some specific networks. Please notice that, for the individual
 * servers listed in the array, the same considerations given above (e.g.,
 * in terms of relative vs. absolute linking) still apply.
 *
 * Such an approach can also be used when you've deployed several different
 * instances of Janus, and you want the library to try some and fallback
 * to others if any of them is not reachable for any reason.
 *
 */

/*! \page service Janus as a daemon/service
 *
 * By default, Janus cannot be started as a daemon. In fact, it is
 * currently conceived as a server application that you start normally.
 * That said, there are several reasons why you may not want to keep
 * Janus in the foreground, while still being interested in checking
 * the console to see what's happening.
 *
 * There are different ways to "daemonize" it and have it run as a service,
 * though. This page tries to summarize a few ways to do so, starting
 * from "dumb" approaches like sending to background and/or using screen/tmux,
 * to more sophisticated approaches involving \c systemd, \c upstart
 * and others.
 *
 * \section bg Running in background
 * The simplest way to run Janus in the background is to just append the
 * \c & character to the command line. Anyway, this will still "flood" the console
 * with output from Janus. While there are ways to handle it (e.g., as
 * explained <a href="http://www.thegeekstuff.com/2010/05/unix-background-job/">here</a>),
 * a nice and easy way to handle this is redirecting the output to a 
 * separate file, e.g., a dedicated log:
 *
 \verbatim
/opt/janus/bin/janus -d 5 -6 >/path/to/mylogfile 2>&1 &
 \endverbatim
 *
 * This is especially useful in case you want to keep a log of what
 * happened when Janus was running, and can also be used as a simple and
 * effective way to watch the console "live" using \c tail:
 \verbatim
tail -f /path/to/mylogfile
 \endverbatim
 *
 * \section screen Terminal multiplexers
 * Another easy way to run Janus in the background is using terminal
 * multiplexers like \c screen or \c tmux. If you're not familiar with
 * such applications, you can find a quick overview
 * <a href="https://en.wikipedia.org/wiki/Terminal_multiplexer">here</a>.
 *
 * The following is a simple example with \c screen:
 *
 \verbatim
screen -S janus -d -m
screen -r janus -X stuff $'/opt/janus/bin/janus -d 5 -6\n'
 \endverbatim
 *
 * This will create a session called "janus" and launch Janus in it with
 * a few command line options (in this case, just the option to enable
 * IPv6 support and set the debug to verbose). Janus will then be running
 * in the background: accessing the console is just a matter of attaching
 * to the "janus" screen: 
 *
 \verbatim
screen -r janus
[CTRL+A+D to detach again]
 \endverbatim
 *
 * Terminal multiplexers usually allow for logging the output to file
 * as well, if you want to keep an history of what happened during the
 * Janus lifetime.
 *
 * \section systemd systemd
 * This section shows how you can add Janus as a service to
 * <a href="https://en.wikipedia.org/wiki/Systemd">systemd</a>.
 *
 \verbatim
[Unit]
Description=Janus WebRTC gateway
After=network.target

[Service]
Type=simple
ExecStart=/opt/janus/bin/janus -o
Restart=on-abnormal
LimitNOFILE=65536

[Install]
WantedBy=multi-user.target
 \endverbatim
 *
 * \note Remember to adjust the path in ExecStart to match the Janus binary path.
 *
 * \note systemd example provided by
 * <a href="https://github.com/meetecho/janus-gateway/pull/306">\@saghul</a> 
 *
 * \section upstart upstart
 * This section shows how you can add Janus as a daemon to
 * <a href="http://upstart.ubuntu.com/">upstart</a>, which is
 * typically available on Ubuntu systems.
 *
 \verbatim
description "janus"

start on filesystem or runlevel [2345]
stop on runlevel [!2345]
limit nofile 50000 50000
limit core unlimited unlimited

respawn
respawn limit 10 5

exec /opt/janus/bin/janus
 \endverbatim
 *
 * \note upstart example provided by
 * <a href="https://github.com/meetecho/janus-gateway/pull/306">\@ploxiln</a> 
 *
 * \section sysvinit sysvinit
 * This section shows how you can add Janus as a daemon to
 * SysVinit based systems.
 *
 \verbatim
#!/bin/sh

### BEGIN INIT INFO
# Provides:          Janus
# Required-Start:    $remote_fs $syslog
# Required-Stop:     $remote_fs $syslog
# Default-Start:     2 3 4 5
# Default-Stop:      0 1 6
# Short-Description: Janus WebRTC gateway
# Description:       Janus WebRTC gateway
### END INIT INFO

DAEMON=/usr/bin/janus
DAEMON_NAME=janus

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

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

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

. /lib/lsb/init-functions

do_start () {
    log_daemon_msg "Starting system $DAEMON_NAME daemon"
    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
    log_end_msg $?
}
do_stop () {
    log_daemon_msg "Stopping system $DAEMON_NAME daemon"
    start-stop-daemon --stop --pidfile $PIDFILE --retry 10
    log_end_msg $?
}

case "$1" in

    start|stop)
        do_${1}
        ;;

    restart|reload|force-reload)
        do_stop
        do_start
        ;;

    status)
        status_of_proc "$DAEMON_NAME" "$DAEMON" && exit 0 || exit $?
        ;;

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

esac
exit 0
 \endverbatim
 *
 * \note sysvinit example provided by
 * <a href="https://github.com/saghul">\@saghul</a> 
 *
 * \section Others
 * TODO.
 *
 */
 
/*! \page debug Debugging Janus
 *
 * In the magical world of fairies and unicorns, the sun always shines
 * and everything always works smoothly and without issues. Unfortunately,
 * this is not the world we live in, and so you might still encounter
 * issues using Janus, e.g., unexpected crashes and the like. We always
 * try and tackle bugs as soon as we spot them, but some issues may be
 * always lingering in the background.
 *
 * Should you encounter a bug or a crash, open a new
 * <a href="https://github.com/meetecho/janus-gateway/issues/new">issue</a>
 * on GitHub. Make sure you carefully read the
 * <a href="https://github.com/meetecho/janus-gateway/blob/master/CONTRIBUTING.md">guidelines</a>
 * for contributing, or otherwise we may decide to close the issue and
 * not even look at it.
 *
 * What's important for us to look into issues and bugs definitely is
 * having enough information to do so. As such, whenever possible try to
 * provide as many details and data as possible. Quite useful to us are
 * GDB stacktraces and/or AddressSanitizer output. The following sections
 * give a quick overview on how you can collect this information after
 * a crash, but for a more detailed description of the tools you should
 * refer to the related documentation pages and tutorials.
 *
 * \section gdb GDB
 * GDB is the <a href="http://www.gnu.org/software/gdb/">GNU Project Debugger</a>
 * and is an effective tool for looking at what has happened (or is
 * happening) inside an application. As such, it's quite useful to spot
 * bugs and the like, as it can provide information about the values of
 * variables when they were used and the application crashed.
 * 
 * When Janus crashes, you should get a core dump file somewhere. This is
 * a recorded state of the application memory at the time of crashing, and
 * so a backtrace of what lead to an issue can help. You can open such
 * a core dump file via gdb this way:
 * 
 \verbatim
gdb /path/to/bin/janus /path/to/coredump
gdb bt
 \endverbatim
 * 
 * The \c bt command retrieves the backtrace, and is what you should provide
 * as part of your new issue.
 * 
 * \note Please \c DON'T paste this backtrace in the issue text. Use a
 * service like <a href="https://gist.github.com/">Gist</a> or
 * <a href="http://pastebin.com/">Pastebin</a> and pass the generated
 * link instead.
 * 
 * \section sanitizer Address Sanitizer
 * An even better tool for spotting issues is
 * <a href="https://code.google.com/p/address-sanitizer/">Address Sanitizer</a>,
 * a fast memory error detector. Since it can spot memory errors, it's
 * very useful to find out about hidden race conditions and the like.
 * 
 * Unlike GDB which can be used as is, though, to use Address Sanitizer
 * you'll first need to recompile Janus with some new settings, as it
 * requires a specific dependency on a library, libasan, which you'll need
 * to install through your repository manager if needed. Besides, you'll
 * need at least gcc 4.8 for this to work: older versions of gcc won't
 * work.
 * 
 * Once you've installed libasan, reconfigure Janus like this:
 * 
 \verbatim
CFLAGS="-fsanitize=address -fno-omit-frame-pointer" LDFLAGS="-lasan" ./configure --prefix=/opt/janus
 \endverbatim
 * 
 * Of course you're free to add whatever additional configuration parameter
 * you were using before: the important parts are the environment variables
 * before that. Once done configuring, do a \c make \c clean (to make sure
 * everything is recompiled from scratch) and then a \c make and \c make \c install
 * as usual.
 * 
 * At this point, your Janus version should be Address Sanitizer compliant.
 * To make sure, try using \c ldd to check whether libasan is indeed a
 * dependency or not:
 * 
 \verbatim
ldd janus | grep asan
 \endverbatim
 * 
 * If it is, you're done: whenever Janus crashes for any reason, you'll
 * get additional output from Address Sanitizer automatically with details
 * on what went wrong, and that's what you should provide as part of the
 * issue content. Just as a side note, please beware that using Address
 * Sanitizer Janus will run just a bit slower, even though not to the
 * point of being unusable (as when using, e.g., valgrind).
 * 
 * \note Please \c DON'T paste Address Sanitizer output in the issue text.
 * Use a service like <a href="https://gist.github.com/">Gist</a> or
 * <a href="http://pastebin.com/">Pastebin</a> and pass the generated
 * link instead.
 * 
 */

/*! \page README README
 *  \verbinclude README.md
 */

/*! \page CREDITS Credits
 *
 * Janus WebRTC Gateway © 2014 <a href="http://www.meetecho.com/">Meetecho</a> (http://www.meetecho.com/)
 *
 * \b Author:
 *         Lorenzo Miniero <lorenzo@meetecho.com>
 *
 * Several open source components have been used to implement this software:
 *
 * - \b GLib: http://library.gnome.org/devel/glib/
 * - \b pkg-config: http://www.freedesktop.org/wiki/Software/pkg-config/
 * - \b gengetopt: http://www.gnu.org/software/gengetopt/ (command line)
 * - \b libmicrohttpd: http://www.gnu.org/software/libmicrohttpd/ (Web server)
 * - \b libini-config: https://fedorahosted.org/sssd/ (INI configurations)
 * - \b Jansson: http://www.digip.org/jansson/ (JSON)
 * - \b libnice: http://nice.freedesktop.org/wiki/ (ICE/STUN/TURN)
 * - \b OpenSSL: http://www.openssl.org/ (DTLS, at least v1.0.1e)
 * - \b libsrtp: http://srtp.sourceforge.net/srtp.html (SRTP, at least v1.5 suggested)
 * - \b Sofia-SIP: http://sofia-sip.sourceforge.net/ (SDP parsing, SIP handling in the SIP plugin)
 * - \b usrsctp: http://code.google.com/p/sctp-refimpl/ (Data Channels)
 * - \b libopus: http://opus-codec.org/ (only needed for the bridge plugin)
 * - \b libogg: http://xiph.org/ogg/ (only needed for the voicemail plugin)
 *
 */
  
/*! \page COPYING License
 * This program is free software, distributed under the terms of the GNU
 * General Public License Version 3.
 *
 * If you're interested in a commercial license (e.g., because GPLv3 is
 * not suited for what you need, you're interested in technical support
 * or want to sponsor the development of new features), feel free to
 * <a href="http://www.meetecho.com">contact us</a>.
 *
 *  \verbinclude COPYING
 */

/*! \page FAQ Frequently Asked Questions
 * This page contains a list of FAQ as gathered on the
 * <a href="https://groups.google.com/forum/?pli=1#!forum/meetecho-janus">meetecho-janus</a>
 * Google group and the 
 * <a href="https://github.com/meetecho/janus-gateway/issues">Issues</a>
 * page on GitHub. It obviously also includes things we're being asked all the
 * time in general! If your question is not listed here or not available
 * anywhere in this documentation, feel free to refer to the group for
 * generic help, or to the Issues page for bugs in the implementation.\n\n
 *
 * -# <b>What is Janus?</b>\n
 *    .
 *    Janus is an open source WebRTC gateway written by <a href="http://www.meetecho.com">Meetecho</a>,
 *    conceived as modular and, as much as possible,
 *    general purpose. It acts as a WebRTC endpoint browsers can interact
 *    with, and different modules can determine what should be done with
 *    the media. This means that you can do SIP, videoconferencing, streaming
 *    and tons of other stuff using the same box! And if what you need is
 *    not there, you can always write your own module and expand Janus.\n\n
 *    .
 * -# <b>What is Meetecho?</b>\n
 *    .
 *    Meetecho is a startup founded by a few researchers, post-docs and
 *    Ph.Ds coming from the Universty of Napoli Federico II. We've been
 *    working on real-time multimedia applications over the Internet for
 *    years, and at one point we decided to try and make products out
 *    of our research efforts. Our web conferencing platform and Janus
 *    is part of those efforts.\n\n
 *    .
 * -# <b>Now that we're at it, how is Meetecho pronounced??</b>\n
 *    .
 *    We're being asked that a lot! We've heard so many variants and different
 *    pronounciations of the name that we could make a book out of it!
 *    When we chose the name, we wanted it to sound like
 *    <a href="https://www.youtube.com/watch?v=TkgDOMSv9PE">this</a>,
 *    which means \a awesome! in Italian. The extra H was a mistake on our
 *    side, as obviously \a echo is pronouced differently than \a eco! Long
 *    story short, it doesn't really matter how you pronounce it: just
 *    do it and help us be famous! :-)\n\n
 *    .
 * -# <b>Why is Janus called like that?</b>\n
 *    .
 *    Quoting <a href="http://en.wikipedia.org/wiki/Janus">Wikipedia</a>:
 *    "<i>In ancient Roman religion and myth, Janus (Latin: Ianus, pronounced
 *    [ˈiaː.nus]) is the god of beginnings and transitions, and thereby of
 *    gates, doors, passages, endings and time. He is usually depicted as
 *    having two faces, since he looks to the future and to the past.</i>"
 *    Considering the general purpose nature of our gateway, where one face always looks
 *    at the future (WebRTC) and the other at the past (whatever the modules
 *    allows you to do, be it legacy stuff or not), Janus looked like the
 *    perfect name for it! And besides, we're Italian, Ancient Rome was
 *    awesome and mythology rules... ;-)  
 *    \n\n
 *    .
 * -# <b>Is the license AGPL or GPL? Do you provide alternative license mechanisms as well?</b>\n
 *    .
 *    First, a word of update: we recently switched from AGPLv3 to GPLv3,
 *    so if AGPL was your concern, we hope this simple choice managed to
 *    change your mind on whether considering trying Janus or not!
 *
 *    That said, we initially chose AGPL for a simple reason: we wanted our work to be open source,
 *    and we wanted interested people to play with it and contribute back
 *    whatever improvement they could provide to the core. This is not always
 *    the case with open source software, which is sometimes just seen as
 *    free stuff you can exploit without helping back, and AGPL looked like
 *    the easiest way to do that. We've been made aware that this license
 *    mechanism is
 *    <a href="https://groups.google.com/forum/?pli=1#!searchin/discuss-webrtc/janus/discuss-webrtc/LJHXkIsAaEU/fHgJ2z0sxfoJ">not very appreciated</a>
 *    around, especially because of some
 *    interpretations about it that could affect the way proprietary stuff
 *    is deployed. We obviously cared about these concerns, and that's what
 *    eventually lead to pick GPLv3 as a license, which should make it
 *    easier for Janus to be integrated in heterogeneous scenarios.\n\n
 *    Apart from that, we're obviously also willing to discuss different
 *    licensing agreements with interested parties, including commercial
 *    ones. Sponsored development can also be considered, so if you're
 *    interested in more details just contact us.\n\n
 *    .
 * -# <b>On what OS can I install Janus?</b>\n
 *    .
 *    At the moment only Linux is supported. While a more cross-platform
 *    approach has been considered, there are no plans to work in that
 *    direction in the near future, as we're mostly interested in adding
 *    new features and improving/enhancing what's already there.\n\n
 *    .
 * -# <b>I've launched Janus, how do I try the demos?</b>\n
 *    .
 *    The demos are available in the \c html folder in the project. That
 *    said, the integrated web server in Janus does not serve static files
 *    as well, so you'll have to make them available using a different
 *    webserver. Details about how to deploy Janus are provided in
 *    \ref deploy.\n\n
 *    .
 * -# <b>Are Data Channels supported?</b>\n
 *    .
 *    Yes they are! Starting from version \c 0.0.3 of Janus, we added a first
 *    experimental support to Data Channels, that can as such be used in
 *    plugins that choose to support them. Right now, they are only
 *    handled in the Echo Test plugin, but this will be added to other
 *    plugins as well, if not just to showcase what can be done with them.\n\n
 *    Please notice that right now we only support text data: we're
 *    currently working on binary streams as well, so we hope support
 *    for those will be available soon.\n\n
 *    .
 * -# <b>I don't care about Data Channels, do I have to compile usrsctp anyway?</b>\n
 *    .
 *    Support for Data Channels is optional. If you don't care about them,
 *    but only about audio and/or video, pass the \c --disable-data-channels
 *    option to the configure script. If you already attempted an install
 *    previously, issue a \c make \c clean before compiling again, or
 *    you might encounter issues with pre-existing symbols.\n\n
 *    .
 * -# <b>I can't install usrsctp, I'm getting errors about dereferencing pointers?</b>\n
 *    .
 *    Apparently recent compilers are stricter with respect to some code
 *    syntaxes, and this seems to be affecting the way \c usrsctp is written
 *    as of now. Some users managed to fix this issue by passing an export
 *    before the \c bootstrap and \c configure steps in the \c usrsctp
 *    compilation:\n\n
 *\verbatim
   export CFLAGS="-fno-strict-aliasing" ./boostrap
   export CFLAGS="-fno-strict-aliasing" ./configure --prefix=/usr
   make && make install
 \endverbatim
 *    Another solution seems to be removing all the \c -O2 occurrences
 *    in the generated \c configure script.\n\n
 *    .
 * -# <b>Can I use Janus as a gateway to my Freeswitch/Kamailio/Asterisk/other SIP infrastructure?</b>\n
 *    .
 *    Of course! One of the modules we provide out of the box is a SIP
 *    gateway plugin based on the <a href="http://sofia-sip.sourceforge.net/">Sofia-SIP</a>
 *    library stack. These plugin allows a web user to register at a SIP
 *    proxy/server either as an authenticated user or as a guest, and
 *    start or receive calls from other SIP users, including other web users
 *    exploiting the same plugin. Janus will take care of all the WebRTC-related
 *    stuff (ICE, DTLS, SRTP), which means that on the SIP side it will
 *    be plain RTP only, much easier and lighter to handle for legacy
 *    implementations. This has so far only been tested with
 *    Kamailio and Asterisk but, since a well known and reliable stack
 *    like Sofia is being used for the purpose, it should work fine with
 *    other implementations as well.\n\n
 *    Please notice that there's definitely room for improvement in this
 *    module (e.g., video support is a bit flaky right now), so let us
 *    know if you encounter any problems with it!\n\n
 *    .
 * -# <b>Can I use existng SIP stacks (e.g., JsSIP) with Janus?</b>\n
 *    .
 *    Janus uses a custom JSON-based protocol for all the communication
 *    between web users and plugins in the gateway, so no, that's not
 *    possible right now. The SIP plugin in Janus only exposes some very
 *    high level information to web users (e.g., registration failed/succeeded,
 *    incoming call, decline, hangup, etc.), without delving in any SIP-related
 *    detail, which is instead completely demanded to the server-side plugin
 *    itself. This ensures that web users can take advantage of SIP functionality
 *    in an easy way, without having to worry about the details and complexity
 *    of SIP within JavaScript.\n\n
 *    .
 * -# <b>Does Janus support transcoding?</b>\n
 *    .
 *    Janus is a simple intermediary between WebRTC users and server-side
 *    plugins providing application logic, so no, it doesn't provide any
 *    transcoding functionality per-se. If transcoding is needed, this is
 *    supposed to be implemented within plugins themselves. That said,
 *    none of the plugins we provide out-of the box does transcoding,
 *    since we wanted the implementation to be lightweight and besides
 *    there are several existing tools and third-party implementations that
 *    could be leveraged for the purpose.\n\n
 *    .
 * -# <b>Does Janus support recording?</b>\n
 *    .
 *    See above: no recording functionality is provided by Janus itself,
 *    as that's something that should be done by plugins as part of their
 *    application logic. That said, unlike transcoding some of the plugins
 *    do implement some sort of recording feature. Specifically, the
 *    Audio Bridge plugin allows for a recording of the mixed audio room
 *    to an uncompressed WAV file; the Voice Mail plugin, instead, allows
 *    for the recording of audio frames provided by a web user to an .opus
 *    file, for the purpose of archiving. The same functionality could
 *    be easily migrated to other plugins, and work is being done to
 *    do the same for video as well (something that we have ready, but
 *    currently introduces too many dependencies that we'd rather avoid).\n\n
 *    .
 * -# <b>Can I use WebSockets instead of plain HTTP to interact with Janus?</b>\n
 *    .
 *    Since version \c 0.0.4, you can! At first we chose a REST-based plain HTTP communication
 *    for a simple reason: we noticed that there were some scenarios (e.g.,
 *    client firewalls) where websockets wouldn't work, even though WebRTC
 *    did. To improve the chances of success in the communication, we
 *    then chose this simpler approach with respect to signalling. Besides,
 *    plain HTTP is much easier to proxy and/or place behind frontends
 *    like Apache HTTPD or nginx than WebSockets, another aspect that
 *    played a decisive role in our decision, as we were also very interested
 *    in making the integration of Janus in heterogeneous environments
 *    as easy as possible. That said, WebSockets also provide substantial
 *    benefits when compared to plain HTTP, and definitely make life easier to
 *    server side integrators as well, e.g., in terms of overhead and use of
 *    resources. For this reason, we added an optional (meaning you can
 *    skip it if you want) support for WebSockets that uses the same API
 *    already available in HTTP, as documented in the \ref WS. \n
 *    \note Please beware that support for WebSockets
 *    is still \b highly \b experimental, so handle that with care!\n\n
 *    .
 * -# <b>Can I use RabbitMQ instead of HTTP/WebSockets to interact with Janus?</b>\n
 *    .
 *    Since version \c 0.0.6, you can! This is a feature that several
 *    developers asked for, especially those that are interested in wrapping
 *    the Janus API on the server side, and implement the communication
 *    on the client side their own way. Specificaly, Janus now supports
 *    RabbitMQ based messaging as an alternative "transport" for API
 *    requests, responses and notifications, meaning it can be used with
 *    or without HTTP and WebSockets, depending on your requirements.
 *    To implement a pseudo-bidirectional channel using RabbitMQ, Janus
 *    makes use of two different queues: one to receive messages, and another
 *    one to send responses and notifications. Since this support is in its
 *    early stages, right now you can only have a single "application"
 *    talking to a specific Janus instance using RabbitMQ messaging,
 *    meaning that Janus won't implement multiple queues to handle
 *    multiple concurrent "application servers" taking advantage of its
 *    features. Support for this is planned, though (e.g., through some kind
 *    of negotiation to create queues on the fly). If you're going to use
 *    the same RabbitMQ server for handling multiple Janus instances from
 *    the same application or different ones, make sure you configure
 *    different queues for each of them (e.g., from-janus-1/to-janus-1 and
 *    from-janus-2/to-janus-2), or otherwise in case of "conflicts" more
 *    instances will end making use of the same queues and messages will get lost.\n
 *    Just as with WebSockets, the Janus API usage when involving RabbitMQ
 *    is exactly the same as the one for HTTP and WebSockets, as documented
 *    in \ref rabbit. \n \note Please beware that support for RabbitMQ is
 *    still \b highly \b experimental, so handle that with care!\n\n
 *    .
 * -# <b>Can I use Janus with node.js or other frameworks?</b>\n
 *    .
 *    Not out of the box, but since interaction with Janus can be completely
 *    HTTP/WebSockets based, this can be abstracted in several different way. With
 *    respect to node.js, <a href="#">NICTA</a> recently released a module
 *    called <a href="https://www.npmjs.org/package/rtc-janus">rtc-janus</a>
 *    that allows you to interact with a Janus instance from a node.js
 *    application, so give that a try!\n\n
 *    .
 * -# <b>Is there any benchmark on Janus performances?</b>\n
 *    .
 *    Benchmarking Janus is not an easy task, especially if we consider
 *    its general purpose nature. In fact, Janus by itself does not much
 *    more than negotiating WebRTC PeerConnections and relaying frames
 *    around, while most of the application login is in the modules. As
 *    you can imagine, different modules may have very different requirements
 *    and impact on the performances. For instance, the Echo Test is probably
 *    much lighter than the Video MCU, even if they're handling the same
 *    number of users. This means that such a benchmarking does not have
 *    much sense unless you contextualise the scenarios.\n\n
 *    For this reason, we and some Janus adopters have recently tried to
 *    do some benchmarking taking a specific plugin as a reference, that
 *    is the Video MCU: in fact, the Video MCU is one of the most popular
 *    modules in Janus, and by itself it does represent a good test bed
 *    considering its many-to-many communication pattern. You can find
 *    some details and considerations in a recent
 *    <a href="https://groups.google.com/forum/?pli=1#!topic/meetecho-janus/ydGcbMt7IX0">post</a>
 *    on our Google group.\n\n
 *    You can find more results in a publication we made at the
 *    <a href="http://janus.conf.meetecho.com/citeus.html">All-Web real-time Systems (AWeS 2015)</a> workshop.\n\n
 *    .
 * -# <b>I want to write my own plugin, where do I start?</b>\n
 *    .
 *    Great! There's an API you can refer to, documented in \ref pluginapi.
 *    Since you'll want your web users to interact with it, make also sure
 *    you study the \ref JS as well, especially the parts that talk about
 *    how to send/receive messages and negotiate WebRTC PeerConnections.
 *    The existing plugins are also an excellent way to start to get
 *    comfortable with the API: a good starting point may be the Echo Test
 *    plugin, which is a very simple and barebone implementation that
 *    simply bounces back whatever it is sent, and also involves some
 *    rough application logic to determine its behaviour (e.g., messages
 *    coming from web users that selectively enable or disable video).
 *    If you need any help with this, feel free to contact us: we're
 *    excited to see who will make available the first third-party Janus
 *    plugin!\n\n
 *    .
 * -# <b>I'm using the Video MCU and, when several users are handled, I get
 *    a "Too many open files" errors and Janus crashes</b>\n
 *    .
 *    As all applications on Linux environments, Janus is bound to the
 *    constraints imposed by the OS and/or the user. One of these constraints
 *    is related to how many file descriptors the application, or all the
 *    applications, can open. On several distributions this number is, by
 *    default, quite low, which can cause the issue you experienced. This
 *    value, together with others, can be modified, per-user or for all users,
 *    using the \c ulimit application. For a simple and quick way to handle
 *    this refer to the guide provided by the MongoDB developers:
 *    http://docs.mongodb.org/manual/reference/ulimit/ \n\n
 *    .
 * -# <b>When I enable the HTTPS web server in Janus, the CPU goes crazy</b>\n
 *    .
 *    As discussed in a recent <a href="https://groups.google.com/forum/?pli=1#!topic/meetecho-janus/lD8A0VqXsNs">post</a>
 *    on our Google group, this is caused by an occasional problem within
 *    libmicrohttpd, the library we use to implement an embedded web server
 *    in Janus. This is not deterministic, as the high CPU usage does happen
 *    on some distributions (e.g., Ubuntu 12.04), while it doesn't on
 *    others (e.g., Ubuntu 14.04). Anyway, this only can happen if you enable
 *    HTTPS support within Janus itself: you can still have a safe HTTPS
 *    usage with Janus if you deploy it behind a frontend (e.g., Apache HTTPD)
 *    that takes care of this on its behalf. Refer to the \ref deploy section
 *    for more details about this.\n\n
 *    .
 * -# <b>I enabled TURN in the Janus configuration, but my clients behind a firewall can't connect</b>\n
 *    .
 *    As explained in the \c janus.cfg documentation, the TURN settings you
 *    configure there refer to Janus \b itself, \b not the clients that make use
 *    of its services. This means that, whether you configure a static TURN
 *    server and the related credentials, or the REST API client stack to
 *    retrieve them dynamically, you're asking Janus to gather relay candidates
 *    for ITSELF. This is only useful if you know that your Janus instance
 *    will not be deployed on a public address (as it usually will) but will
 *    instead potentially sit behind a restrictive component like a firewall,
 *    or if you simply want to limit the number of open ports and so force
 *    all media traffic to go through the TURN server port alone.\n\n
 *    If you want your clients to gather relay candidates, instead, this
 *    needs to be done on the client side (e.g., in JavaScript, if your
 *    clients are web applications). If you're using our \ref JS check
 *    the \c echotest.js code, which has a commented portion that explains
 *    how to provide one or more TURN servers to make use of. If you're
 *    handling the WebRTC-related stuff on your own and are contacting
 *    Janus some other way, please refer to the related way of specifying
 *    STUN and TURN servers instead.\n\n
 *    .
 * -# <b>Can you implement a feature I want?</b>\n
 *    .
 *    We're constantly working on new features and on improving what's
 *    already there, and we do love feedback from users. That said, we're
 *    a small team and we do have to pay our bills, so we always have to
 *    reserve our resources wisely. If there's a feature you'd like to
 *    see implemented, tell us on our Google group, and discuss it with
 *    other users: it may be on our schedule, or someone else may be
 *    already working on it to contribute it back to the project. You
 *    may even want to try and build it yourself and help us make Janus
 *    even better! If you really need something that isn't there, you
 *    may also want to consider a sponsored development or contact us
 *    for consulting.\n\n
 *    .
 */

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

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

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

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

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

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