Fork me on GitHub
Data Structures | Macros | Typedefs
eventhandler.h File Reference

Modular Janus event handlers (headers) More...

#include <stdlib.h>
#include <stdint.h>
#include <stdio.h>
#include <string.h>
#include <ctype.h>
#include <unistd.h>
#include <inttypes.h>
#include <glib.h>
#include <jansson.h>
#include "../utils.h"
Include dependency graph for eventhandler.h:
This graph shows which files directly or indirectly include this file:

Go to the source code of this file.

Data Structures

struct  janus_eventhandler
 The event handler plugin session and callbacks interface. More...
 

Macros

#define JANUS_EVENTHANDLER_API_VERSION   2
 Version of the API, to match the one event handler plugins were compiled against. More...
 
#define JANUS_EVENTHANDLER_INIT(...)
 
Type of events Janus could notify, and the handler subscribe to

Initialization of all event handler plugin properties to NULL

Note
All event handler plugins MUST add this as the FIRST line when initializing their event handler plugin structure, e.g.:
static janus_eventhandler janus_fake_eventhandler handler plugin =
        {
                JANUS_EVENTHANDLER_INIT,
                
                .init = janus_fake_init,
                [..]

This mask makes it easy to subscribe to, and unsubscribe from, specific events, as all you need to do is to use janus_flags_set and janus_flags_clear on the events_mask property of the handler instance, and the core will know whether you care about something or not.

#define JANUS_EVENT_TYPE_NONE   (0)
 No event. More...
 
#define JANUS_EVENT_TYPE_SESSION   (1 << 0)
 Session related events (e.g., session created/destroyed, etc.) More...
 
#define JANUS_EVENT_TYPE_HANDLE   (1 << 1)
 Handle related events (e.g., handle attached/detached, etc.) More...
 
#define JANUS_EVENT_TYPE_EXTERNAL   (1 << 2)
 External events originated via Admin API (e.g., custom events coming from external scripts) More...
 
#define JANUS_EVENT_TYPE_JSEP   (1 << 3)
 JSEP related events (e.g., got/sent offer/answer) More...
 
#define JANUS_EVENT_TYPE_WEBRTC   (1 << 4)
 WebRTC related events (e.g., PeerConnection up/down, ICE updates, DTLS updates, etc.) More...
 
#define JANUS_EVENT_TYPE_MEDIA   (1 << 5)
 Media related events (e.g., media started/stopped flowing, stats on packets/bytes, etc.) More...
 
#define JANUS_EVENT_TYPE_PLUGIN   (1 << 6)
 Events originated by plugins (at the moment, all of them, no way to pick) More...
 
#define JANUS_EVENT_TYPE_TRANSPORT   (1 << 7)
 Events originated by transports (at the moment, all of them, no way to pick) More...
 
#define JANUS_EVENT_TYPE_CORE   (1 << 8)
 Events originated by the core for its own events (e.g., Janus starting/shutting down) More...
 
#define JANUS_EVENT_TYPE_ALL   (0xffffffff)
 Mask with all events enabled (shortcut when you want to subscribe to everything) More...
 

Typedefs

typedef struct janus_eventhandler janus_eventhandler
 The event handler plugin session and callbacks interface. More...
 
typedef janus_eventhandlercreate_e(void)
 The hook that event handler plugins need to implement to be created from the Janus core. More...
 

Detailed Description

Modular Janus event handlers (headers)

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

This header contains the definition of the callbacks all the event handlers need to implement to interact with the Janus core. In fact, an event handler is basically a module that receives notifications from the Janus core and plugins about things happening, together with more or less detailed information that may be relevant. This may include WebRTC related events (e.g., a PeerConnection going up or down, media stopping or resuming, etc.), events related to media, or custom events plugins may originate on their own (e.g., a participant publishing their media in a conference, or a SIP call starting). What to do with these events is then up to the handler: it may choose to store them somewhere (e.g., a database), analyse and process them, or simply send them to an external tool for statistics purposes or troubleshooting. Whatever the aim, the structures to make the interaction between core and event handlers possible are defined here.

An event handler plugin that wants to register at the Janus core needs to implement the janus_eventhandler interface. This includes callbacks the Janus core can use to pass and request information, and a mask of the events the plugin is interested in subscribing to. Besides, as an event handler plugin is a shared object, and as such external to the core itself, in order to be dynamically loaded at startup it needs to implement the create_e() hook as well, that should return a pointer to the plugin instance. This is an example of such a step:

static janus_eventhandler myhandler = {
        [..]
};

janus_eventhandler *create(void) {
        JANUS_LOG(LOG_VERB, , "%s created!\n", MY_HANDLER_NAME);
        return &myhandler;
}

This will make sure that your event handler plugin is loaded at startup by the Janus core, if it is deployed in the proper folder.

As anticipated and described in the above example, an event handler plugin must basically be an instance of the janus_eventhandler type. As such, it must implement the following methods and callbacks for the core:

All the above methods and callbacks are mandatory: the Janus core will reject an event handler plugin that doesn't implement any of the mandatory callbacks.

Additionally, a janus_eventhandler instance must also include a mask of the events it is interested in, a events_mask janus_flag object that must refer to the available types defined in this header. The core, in fact, will refer to that mask to check whether your event handler is interested in a specific event or not.

Unlike other kind of modules (transports, plugins), the init() method here only passes the path to the configurations files folder, as event handlers never need to contact the Janus core themselves. This path can be used to read and parse a configuration file for the event handler plugin: the event handler plugins we made available out of the box use the package name as a name for the file (e.g., janus.eventhandler.fake.cfg for the sample event handler plugin), but you're free to use a different one, as long as it doesn't collide with existing ones. Besides, the existing eventhandler plugins use the same INI format for configuration files the core uses (relying on the janus_config helpers for the purpose) but again, if you prefer a different format (XML, JSON, etc.) that's up to you.

Event Handler API

Macro Definition Documentation

#define JANUS_EVENT_TYPE_ALL   (0xffffffff)

Mask with all events enabled (shortcut when you want to subscribe to everything)

#define JANUS_EVENT_TYPE_CORE   (1 << 8)

Events originated by the core for its own events (e.g., Janus starting/shutting down)

#define JANUS_EVENT_TYPE_EXTERNAL   (1 << 2)

External events originated via Admin API (e.g., custom events coming from external scripts)

#define JANUS_EVENT_TYPE_HANDLE   (1 << 1)

Handle related events (e.g., handle attached/detached, etc.)

#define JANUS_EVENT_TYPE_JSEP   (1 << 3)

JSEP related events (e.g., got/sent offer/answer)

#define JANUS_EVENT_TYPE_MEDIA   (1 << 5)

Media related events (e.g., media started/stopped flowing, stats on packets/bytes, etc.)

#define JANUS_EVENT_TYPE_NONE   (0)

No event.

#define JANUS_EVENT_TYPE_PLUGIN   (1 << 6)

Events originated by plugins (at the moment, all of them, no way to pick)

#define JANUS_EVENT_TYPE_SESSION   (1 << 0)

Session related events (e.g., session created/destroyed, etc.)

#define JANUS_EVENT_TYPE_TRANSPORT   (1 << 7)

Events originated by transports (at the moment, all of them, no way to pick)

#define JANUS_EVENT_TYPE_WEBRTC   (1 << 4)

WebRTC related events (e.g., PeerConnection up/down, ICE updates, DTLS updates, etc.)

#define JANUS_EVENTHANDLER_API_VERSION   2

Version of the API, to match the one event handler plugins were compiled against.

#define JANUS_EVENTHANDLER_INIT (   ...)
Value:
{ \
.init = NULL, \
.destroy = NULL, \
.get_api_compatibility = NULL, \
.get_version = NULL, \
.get_version_string = NULL, \
.get_description = NULL, \
.get_name = NULL, \
.get_author = NULL, \
.get_package = NULL, \
.incoming_event = NULL, \
.events_mask = JANUS_EVENT_TYPE_NONE, \
## __VA_ARGS__ }
#define JANUS_EVENT_TYPE_NONE
No event.
Definition: eventhandler.h:129

Typedef Documentation

typedef janus_eventhandler* create_e(void)

The hook that event handler plugins need to implement to be created from the Janus core.

The event handler plugin session and callbacks interface.