Loading...
Searching...
No Matches
eventhandler.h File Reference
Event Handlers » Event Handler API

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 3
| Version of the API, to match the one event handler plugins were compiled against.
#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_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.
#define | JANUS_EVENT_TYPE_SESSION (1 << 0)
| Session related events (e.g., session created/destroyed, etc.).
#define | JANUS_EVENT_TYPE_HANDLE (1 << 1)
| Handle related events (e.g., handle attached/detached, etc.).
#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_JSEP (1 << 3)
| JSEP related events (e.g., got/sent offer/answer).
#define | JANUS_EVENT_TYPE_WEBRTC (1 << 4)
| WebRTC related events (e.g., PeerConnection up/down, ICE updates, DTLS updates, etc.).
#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_PLUGIN (1 << 6)
| Events originated by plugins (at the moment, all of them, no way to pick).
#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_CORE (1 << 8)
| Events originated by the core for its own events (e.g., Janus starting/shutting down).
#define | JANUS_EVENT_TYPE_ALL (0xffffffff)
| Mask with all events enabled (shortcut when you want to subscribe to everything).
Subtype of event types Janus could notify

Some events, like JANUS_EVENT_TYPE_WEBRTC, don't have a uniform syntax: an event related to a new local candidate looks very different from an event related to, e.g., a selected pair or a DTLS state, all of which belong to the same category of `webrtc` type events. In order to simplify the management of events in strongly typed languages, events can contain a `subtype` property as well: this property is optional, because not all event types need this finer grain of detail. At the time of writing, subtypes are only available for JANUS_EVENT_TYPE_CORE ("core"), JANUS_EVENT_TYPE_WEBRTC ("webrtc") and JANUS_EVENT_TYPE_MEDIA ("media") types.

Note
  Unlike the type, subtypes are not a mask: as a consequence, you cannot filter subtypes using the Event Handler plugin API, only types. Besides, there can be overlaps between subtypes related to

#define | JANUS_EVENT_SUBTYPE_NONE 0
| No subtype.
#define | JANUS_EVENT_SUBTYPE_CORE_STARTUP 1
| Core event subtypes: startup.
#define | JANUS_EVENT_SUBTYPE_CORE_SHUTDOWN 2
| Core event subtypes: shutdown.
#define | JANUS_EVENT_SUBTYPE_WEBRTC_ICE 1
| WebRTC event subtypes: ICE state.
#define | JANUS_EVENT_SUBTYPE_WEBRTC_LCAND 2
| WebRTC event subtypes: local candidate.
#define | JANUS_EVENT_SUBTYPE_WEBRTC_RCAND 3
| WebRTC event subtypes: remote candidate.
#define | JANUS_EVENT_SUBTYPE_WEBRTC_PAIR 4
| WebRTC event subtypes: selected pair.
#define | JANUS_EVENT_SUBTYPE_WEBRTC_DTLS 5
| WebRTC event subtypes: DTLS state.
#define | JANUS_EVENT_SUBTYPE_WEBRTC_STATE 6
| WebRTC event subtypes: PeerConnection state.
#define | JANUS_EVENT_SUBTYPE_MEDIA_STATE 1
| Media event subtypes: media state.
#define | JANUS_EVENT_SUBTYPE_MEDIA_SLOWLINK 2
| Media event subtypes: slow link.
#define | JANUS_EVENT_SUBTYPE_MEDIA_STATS 3
| Media event subtypes: stats.

## Typedefs

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

## 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

Copyright
  GNU General Public License v3

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:

- `init()`: this is called by the Janus core as soon as your event handler plugin is started; this is where you should setup your event handler plugin (e.g., static stuff and reading the configuration file);
- `destroy()`: on the other hand, this is called by the core when it is shutting down, and your event handler plugin should too;
- `get_api_compatibility()`: this method MUST return JANUS_EVENTHANDLER_API_VERSION;
- `get_version()`: this method should return a numeric version identifier (e.g., 3);
- `get_version_string()`: this method should return a verbose version identifier (e.g., "v1.0.1");
- `get_description()`: this method should return a verbose description of your event handler plugin (e.g., "This is an event handler that saves some events on a database");
- `get_name()`: this method should return a short display name for your event handler plugin (e.g., "My Amazing Event Handler");
- `get_package()`: this method should return a unique package identifier for your event handler plugin (e.g., "janus.eventhandler.myeventhandler");
- `incoming_event()`: this callback informs the event handler that an event is available for consumption.

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.jcfg` 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 libconfig 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

## JANUS_EVENT_SUBTYPE_CORE_SHUTDOWN

#define JANUS_EVENT_SUBTYPE_CORE_SHUTDOWN 2

Core event subtypes: shutdown.

## JANUS_EVENT_SUBTYPE_CORE_STARTUP

#define JANUS_EVENT_SUBTYPE_CORE_STARTUP 1

Core event subtypes: startup.

## JANUS_EVENT_SUBTYPE_MEDIA_SLOWLINK

#define JANUS_EVENT_SUBTYPE_MEDIA_SLOWLINK 2

Media event subtypes: slow link.

## JANUS_EVENT_SUBTYPE_MEDIA_STATE

#define JANUS_EVENT_SUBTYPE_MEDIA_STATE 1

Media event subtypes: media state.

## JANUS_EVENT_SUBTYPE_MEDIA_STATS

#define JANUS_EVENT_SUBTYPE_MEDIA_STATS 3

Media event subtypes: stats.

## JANUS_EVENT_SUBTYPE_NONE

#define JANUS_EVENT_SUBTYPE_NONE 0

No subtype.

## JANUS_EVENT_SUBTYPE_WEBRTC_DTLS

#define JANUS_EVENT_SUBTYPE_WEBRTC_DTLS 5

WebRTC event subtypes: DTLS state.

## JANUS_EVENT_SUBTYPE_WEBRTC_ICE

#define JANUS_EVENT_SUBTYPE_WEBRTC_ICE 1

WebRTC event subtypes: ICE state.

## JANUS_EVENT_SUBTYPE_WEBRTC_LCAND

#define JANUS_EVENT_SUBTYPE_WEBRTC_LCAND 2

WebRTC event subtypes: local candidate.

## JANUS_EVENT_SUBTYPE_WEBRTC_PAIR

#define JANUS_EVENT_SUBTYPE_WEBRTC_PAIR 4

WebRTC event subtypes: selected pair.

## JANUS_EVENT_SUBTYPE_WEBRTC_RCAND

#define JANUS_EVENT_SUBTYPE_WEBRTC_RCAND 3

WebRTC event subtypes: remote candidate.

## JANUS_EVENT_SUBTYPE_WEBRTC_STATE

#define JANUS_EVENT_SUBTYPE_WEBRTC_STATE 6

WebRTC event subtypes: PeerConnection state.

## JANUS_EVENT_TYPE_ALL

#define JANUS_EVENT_TYPE_ALL (0xffffffff)

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

## JANUS_EVENT_TYPE_CORE

#define JANUS_EVENT_TYPE_CORE (1 << 8)

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

## JANUS_EVENT_TYPE_EXTERNAL

#define JANUS_EVENT_TYPE_EXTERNAL (1 << 2)

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

## JANUS_EVENT_TYPE_HANDLE

#define JANUS_EVENT_TYPE_HANDLE (1 << 1)

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

## JANUS_EVENT_TYPE_JSEP

#define JANUS_EVENT_TYPE_JSEP (1 << 3)

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

## JANUS_EVENT_TYPE_MEDIA

#define JANUS_EVENT_TYPE_MEDIA (1 << 5)

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

## JANUS_EVENT_TYPE_NONE

#define JANUS_EVENT_TYPE_NONE (0)

No event.

## JANUS_EVENT_TYPE_PLUGIN

#define JANUS_EVENT_TYPE_PLUGIN (1 << 6)

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

## JANUS_EVENT_TYPE_SESSION

#define JANUS_EVENT_TYPE_SESSION (1 << 0)

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

## JANUS_EVENT_TYPE_TRANSPORT

#define JANUS_EVENT_TYPE_TRANSPORT (1 << 7)

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

## JANUS_EVENT_TYPE_WEBRTC

#define JANUS_EVENT_TYPE_WEBRTC (1 << 4)

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

## JANUS_EVENTHANDLER_API_VERSION

#define JANUS_EVENTHANDLER_API_VERSION 3

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

## JANUS_EVENTHANDLER_INIT

#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__ }
JANUS_EVENT_TYPE_NONE
#define JANUS_EVENT_TYPE_NONE
No event.
Definition eventhandler.h:129

## Typedef Documentation

## create_e

typedef janus_eventhandler * create_e(void)

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

## janus_eventhandler

typedef struct janus_eventhandler janus_eventhandler

The event handler plugin session and callbacks interface.