Fork me on GitHub
 All Data Structures Files Functions Variables Typedefs Enumerations Enumerator Macros Groups Pages
Data Structures | Macros | Typedefs | Functions
janus.h File Reference

Janus core (headers) More...

#include <inttypes.h>
#include <stdlib.h>
#include <stdint.h>
#include <stdio.h>
#include <string.h>
#include <ctype.h>
#include <unistd.h>
#include <jansson.h>
#include <microhttpd.h>
#include "mutex.h"
#include "dtls.h"
#include "ice.h"
#include "sctp.h"
#include "plugins/plugin.h"
Include dependency graph for janus.h:
This graph shows which files directly or indirectly include this file:

Go to the source code of this file.

Data Structures

struct  janus_http_msg
 Incoming HTTP message. More...
struct  janus_http_event
 HTTP event to push. More...
struct  janus_session
 Gateway-Client session. More...
struct  janus_request_source
 Helper to address request sources (e.g., a specific HTTP connection, websocket or RabbitMQ queue) More...

Macros

#define BUFSIZE   4096

Typedefs

typedef struct janus_http_msg janus_http_msg
 Incoming HTTP message.
typedef struct janus_http_event janus_http_event
 HTTP event to push.
typedef struct janus_session janus_session
 Gateway-Client session.

Functions

void janus_http_event_free (janus_http_event *event)
gchar * janus_get_server_pem (void)
 Helper method to return the path to the provided server certificate.
gchar * janus_get_server_key (void)
 Helper method to return the path to the provided server certificate key.
gchar * janus_get_local_ip (void)
 Helper method to return the local IP address (autodetected by default)
gchar * janus_get_public_ip (void)
 Helper method to return the IP address to use in the SDP (autodetected by default)
void janus_set_public_ip (const char *ip)
 Helper method to overwrite the IP address to use in the SDP.
gint janus_is_stopping (void)
 Helper method to check whether the gateway is being shut down.
Janus Gateway-Client session methods
janus_sessionjanus_session_create (guint64 session_id)
 Method to create a new Janus Gateway-Client session.
janus_sessionjanus_session_find (guint64 session_id)
 Method to find an existing Janus Gateway-Client session from its ID.
void janus_session_notify_event (guint64 session_id, janus_http_event *event)
 Method to add an event to notify to the queue of notifications for this session.
janus_sessionjanus_session_find_destroyed (guint64 session_id)
 Method to find an existing Janus Gateway-Client session scheduled to be destroyed from its ID.
gint janus_session_destroy (guint64 session_id)
 Method to destroy a Janus Gateway-Client session.
void janus_session_free (janus_session *session)
 Method to actually free the resources allocated by a Janus Gateway-Client session.
Janus web server

Browsers make use of HTTP to make requests to the gateway. Since the gateway may be deployed on a different domain than the web server hosting the web applications using it, the gateway automatically handles OPTIONS request to comply with the CORS specification. POST requests can be used to ask for the management of a session with the gateway, to attach to a plugin, to send messages to the plugin itself and so on. GET requests instead are used for getting events associated to a gateway session (and as such to all its plugin handles and the events plugins push in the session itself), using a long poll approach. A JavaScript library (janus.js) implements all of this on the client side automatically.

int janus_ws_client_connect (void *cls, const struct sockaddr *addr, socklen_t addrlen)
 Callback (libmicrohttpd) invoked when a new connection is attempted on the REST API.
int janus_admin_ws_client_connect (void *cls, const struct sockaddr *addr, socklen_t addrlen)
 Callback (libmicrohttpd) invoked when a new connection is attempted on the admin/monitor webserver.
int janus_ws_handler (void *cls, struct MHD_Connection *connection, const char *url, const char *method, const char *version, const char *upload_data, size_t *upload_data_size, void **ptr)
 Callback (libmicrohttpd) invoked when an HTTP message (GET, POST, OPTIONS, etc.) is available.
int janus_admin_ws_handler (void *cls, struct MHD_Connection *connection, const char *url, const char *method, const char *version, const char *upload_data, size_t *upload_data_size, void **ptr)
 Callback (libmicrohttpd) invoked when an admin/monitor HTTP message (GET, POST, OPTIONS, etc.) is available.
int janus_ws_headers (void *cls, enum MHD_ValueKind kind, const char *key, const char *value)
 Callback (libmicrohttpd) invoked when headers of an incoming HTTP message have been parsed.
void janus_ws_request_completed (void *cls, struct MHD_Connection *connection, void **con_cls, enum MHD_RequestTerminationCode toe)
 Callback (libmicrohttpd) invoked when a request has been processed and can be freed.
int janus_ws_notifier (janus_request_source *source, int max_events)
 Worker to handle requests that are actually long polls.
Janus plugin management

As anticipated, the gateway doesn't provide any specific feature: it takes care of WebRTC-related stuff, and of sending and receiving JSON-based messages. To implement applications based on these foundations, plugins can be used. These plugins are shared objects that need to implement the interfaces defined in plugin.h and as such are dynamically loaded by the gateway at startup, and unloaded when the gateway closes.

void janus_plugin_close (void *key, void *value, void *user_data)
 Callback (g_hash_table_foreach) invoked when it's time to destroy a plugin instance.
void janus_pluginso_close (void *key, void *value, void *user_data)
 Callback (g_hash_table_foreach) invoked when it's time to close a plugin.
janus_pluginjanus_plugin_find (const gchar *package)
 Method to return a registered plugin instance out of its package name.

Janus request processing

Since messages may come from different sources (plain HTTP or WebSockets, and potentially even more in the future), we have a shared way to process messages: a method to process a request, and helper methods to return a success or an error message.

#define JANUS_SOURCE_PLAIN_HTTP   1
 Plain HTTP REST source.
#define JANUS_SOURCE_WEBSOCKETS   2
 WebSocket source.
#define JANUS_SOURCE_RABBITMQ   3
 RabbitMQ source.
typedef struct janus_request_source janus_request_source
 Helper to address request sources (e.g., a specific HTTP connection, websocket or RabbitMQ queue)
janus_request_sourcejanus_request_source_new (int type, void *source, void *msg)
 Helper to allocate a janus_request_source instance.
void janus_request_source_destroy (janus_request_source *req_source)
 Helper to destroy a janus_request_source instance.
int janus_process_incoming_request (janus_request_source *source, json_t *request)
 Helper to process an incoming request, no matter where it comes from.
int janus_process_incoming_admin_request (janus_request_source *source, json_t *request)
 Helper to process an incoming admin/monitor request, no matter where it comes from.
int janus_process_success (janus_request_source *source, char *payload)
 Method to return a successful Janus response message (JSON) to the browser.
int janus_process_error (janus_request_source *source, uint64_t session_id, const char *transaction, gint error, const char *format,...) G_GNUC_PRINTF(5
 Method to return an error Janus response message (JSON) to the browser.

Detailed Description

Janus core (headers)

Author
Lorenzo Miniero loren.nosp@m.zo@m.nosp@m.eetec.nosp@m.ho.c.nosp@m.om

Implementation of the gateway core. This code takes care of the gateway initialization (command line/configuration) and setup, and implements the web server (based on libmicrohttpd) and Janus protocol (a JSON protocol implemented with Jansson) to interact with the web applications. The core also takes care of bridging peers and plugins accordingly.

Core

Macro Definition Documentation

#define BUFSIZE   4096
#define JANUS_SOURCE_PLAIN_HTTP   1

Plain HTTP REST source.

#define JANUS_SOURCE_RABBITMQ   3

RabbitMQ source.

#define JANUS_SOURCE_WEBSOCKETS   2

WebSocket source.

Typedef Documentation

HTTP event to push.

Incoming HTTP message.

Helper to address request sources (e.g., a specific HTTP connection, websocket or RabbitMQ queue)

typedef struct janus_session janus_session

Gateway-Client session.

Function Documentation

int janus_admin_ws_client_connect ( void *  cls,
const struct sockaddr *  addr,
socklen_t  addrlen 
)

Callback (libmicrohttpd) invoked when a new connection is attempted on the admin/monitor webserver.

int janus_admin_ws_handler ( void *  cls,
struct MHD_Connection *  connection,
const char *  url,
const char *  method,
const char *  version,
const char *  upload_data,
size_t *  upload_data_size,
void **  ptr 
)

Callback (libmicrohttpd) invoked when an admin/monitor HTTP message (GET, POST, OPTIONS, etc.) is available.

gchar* janus_get_local_ip ( void  )

Helper method to return the local IP address (autodetected by default)

gchar* janus_get_public_ip ( void  )

Helper method to return the IP address to use in the SDP (autodetected by default)

gchar* janus_get_server_key ( void  )

Helper method to return the path to the provided server certificate key.

gchar* janus_get_server_pem ( void  )

Helper method to return the path to the provided server certificate.

void janus_http_event_free ( janus_http_event event)
gint janus_is_stopping ( void  )

Helper method to check whether the gateway is being shut down.

void janus_plugin_close ( void *  key,
void *  value,
void *  user_data 
)

Callback (g_hash_table_foreach) invoked when it's time to destroy a plugin instance.

Parameters
[in]keyKey of the plugins hash table (package name)
[in]valueThe janus_plugin plugin instance to destroy
[in]user_dataUser provided data (unused)
janus_plugin* janus_plugin_find ( const gchar *  package)

Method to return a registered plugin instance out of its package name.

Parameters
[in]packageThe unique package name of the plugin
Returns
The plugin instance
void janus_pluginso_close ( void *  key,
void *  value,
void *  user_data 
)

Callback (g_hash_table_foreach) invoked when it's time to close a plugin.

Parameters
[in]keyKey of the plugins hash table (package name)
[in]valueThe janus_plugin plugin instance to close
[in]user_dataUser provided data (unused)
int janus_process_error ( janus_request_source source,
uint64_t  session_id,
const char *  transaction,
gint  error,
const char *  format,
  ... 
)

Method to return an error Janus response message (JSON) to the browser.

Parameters
[in]sourceThe source that originated the request
[in]session_idJanus session identifier this error refers to
[in]transactionThe Janus transaction identifier
[in]errorThe error code as defined in apierror.h
[in]formatThe printf format of the reason string, followed by a variable number of arguments, if needed; if format is NULL, a pre-configured string associated with the error code is used
Returns
MHD_YES on success, MHD_NO otherwise
int janus_process_incoming_admin_request ( janus_request_source source,
json_t *  request 
)

Helper to process an incoming admin/monitor request, no matter where it comes from.

Parameters
[in]sourceThe source that originated the request
[in]requestThe JSON request
Returns
MHD_YES on success, MHD_NO otherwise
int janus_process_incoming_request ( janus_request_source source,
json_t *  request 
)

Helper to process an incoming request, no matter where it comes from.

Parameters
[in]sourceThe source that originated the request
[in]requestThe JSON request
Returns
MHD_YES on success, MHD_NO otherwise
int janus_process_success ( janus_request_source source,
char *  payload 
)

Method to return a successful Janus response message (JSON) to the browser.

Parameters
[in]sourceThe source that originated the request
[in]payloadThe stringified version of the Janus response (JSON)
Returns
MHD_YES on success, MHD_NO otherwise
void janus_request_source_destroy ( janus_request_source req_source)

Helper to destroy a janus_request_source instance.

Parameters
[in]req_sourceThe janus_request_source instance to destroy
Note
The opaque pointers in the instance are not destroyed, that's up to you
janus_request_source* janus_request_source_new ( int  type,
void *  source,
void *  msg 
)

Helper to allocate a janus_request_source instance.

Parameters
[in]typeThe source type
[in]sourceOpaque pointer to the source
[in]msgOpaque pointer to the original request, if available
Returns
A pointer to a janus_request_source instance if successful, NULL otherwise
janus_session* janus_session_create ( guint64  session_id)

Method to create a new Janus Gateway-Client session.

Parameters
[in]session_idThe desired Janus Gateway-Client session ID, or 0 if it needs to be generated randomly
Returns
The created Janus Gateway-Client session if successful, NULL otherwise
gint janus_session_destroy ( guint64  session_id)

Method to destroy a Janus Gateway-Client session.

Parameters
[in]session_idThe Janus Gateway-Client session ID to destroy
Returns
0 in case of success, a negative integer otherwise
janus_session* janus_session_find ( guint64  session_id)

Method to find an existing Janus Gateway-Client session from its ID.

Parameters
[in]session_idThe Janus Gateway-Client session ID
Returns
The created Janus Gateway-Client session if successful, NULL otherwise
janus_session* janus_session_find_destroyed ( guint64  session_id)

Method to find an existing Janus Gateway-Client session scheduled to be destroyed from its ID.

Parameters
[in]session_idThe Janus Gateway-Client session ID
Returns
The created Janus Gateway-Client session if successful, NULL otherwise
void janus_session_free ( janus_session session)

Method to actually free the resources allocated by a Janus Gateway-Client session.

Parameters
[in]sessionThe Janus Gateway-Client session instance to free
void janus_session_notify_event ( guint64  session_id,
janus_http_event event 
)

Method to add an event to notify to the queue of notifications for this session.

Parameters
[in]session_idThe Janus Gateway-Client session ID
[in]eventThe janus_http_event instance to add to the queue
void janus_set_public_ip ( const char *  ip)

Helper method to overwrite the IP address to use in the SDP.

int janus_ws_client_connect ( void *  cls,
const struct sockaddr *  addr,
socklen_t  addrlen 
)

Callback (libmicrohttpd) invoked when a new connection is attempted on the REST API.

int janus_ws_handler ( void *  cls,
struct MHD_Connection *  connection,
const char *  url,
const char *  method,
const char *  version,
const char *  upload_data,
size_t *  upload_data_size,
void **  ptr 
)

Callback (libmicrohttpd) invoked when an HTTP message (GET, POST, OPTIONS, etc.) is available.

int janus_ws_headers ( void *  cls,
enum MHD_ValueKind  kind,
const char *  key,
const char *  value 
)

Callback (libmicrohttpd) invoked when headers of an incoming HTTP message have been parsed.

int janus_ws_notifier ( janus_request_source source,
int  max_events 
)

Worker to handle requests that are actually long polls.

As this method handles a long poll, it doesn't return until an event (e.g., pushed by a plugin) is available, or a timeout (30 seconds) has been fired. In case of a timeout, a keep-alive Janus response (JSON) is sent to tell the browser that the session is still valid.

Parameters
[in]sourceThe janus_request_source instance that is handling the request
[in]max_eventsThe maximum number of events that can be returned in a single response (by default just one; if more, an array is returned)
Returns
MHD_YES on success, MHD_NO otherwise
Todo:
Improve the Janus protocol keep-alive mechanism in JavaScript
void janus_ws_request_completed ( void *  cls,
struct MHD_Connection *  connection,
void **  con_cls,
enum MHD_RequestTerminationCode  toe 
)

Callback (libmicrohttpd) invoked when a request has been processed and can be freed.