Loading...
Searching...
No Matches
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"
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
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 | |
| #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
| |
| #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. | |
Modular Janus event handlers (headers)
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.
| #define JANUS_EVENT_SUBTYPE_CORE_SHUTDOWN 2 |
Core event subtypes: shutdown.
| #define JANUS_EVENT_SUBTYPE_CORE_STARTUP 1 |
Core event subtypes: startup.
| #define JANUS_EVENT_SUBTYPE_MEDIA_SLOWLINK 2 |
Media event subtypes: slow link.
| #define JANUS_EVENT_SUBTYPE_MEDIA_STATE 1 |
Media event subtypes: media state.
| #define JANUS_EVENT_SUBTYPE_MEDIA_STATS 3 |
Media event subtypes: stats.
| #define JANUS_EVENT_SUBTYPE_NONE 0 |
No subtype.
| #define JANUS_EVENT_SUBTYPE_WEBRTC_DTLS 5 |
WebRTC event subtypes: DTLS state.
| #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_PAIR 4 |
WebRTC event subtypes: selected pair.
| #define JANUS_EVENT_SUBTYPE_WEBRTC_RCAND 3 |
WebRTC event subtypes: remote candidate.
| #define JANUS_EVENT_SUBTYPE_WEBRTC_STATE 6 |
WebRTC event subtypes: PeerConnection state.
| #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 3 |
Version of the API, to match the one event handler plugins were compiled against.
| #define JANUS_EVENTHANDLER_INIT | ( | ... | ) |
| typedef janus_eventhandler * create_e(void) |
The hook that event handler plugins need to implement to be created from the Janus core.
| typedef struct janus_eventhandler janus_eventhandler |
The event handler plugin session and callbacks interface.