Statistics
| Branch: | Revision:

janus-gateway / events / eventhandler.h @ 84c1291c

History | View | Annotate | Download (10.7 KB)

1
/*! \file   event.h
2
 * \author Lorenzo Miniero <lorenzo@meetecho.com>
3
 * \copyright GNU General Public License v3
4
 * \brief  Modular Janus event handlers (headers)
5
 * \details  This header contains the definition of the callbacks all
6
 * the event handlers need to implement to interact with the Janus core.
7
 * In fact, an event handler is basically a module that receives
8
 * notifications from the Janus core and plugins about things happening,
9
 * together with more or less detailed information that may be relevant.
10
 * This may include WebRTC related events (e.g., a PeerConnection going
11
 * up or down, media stopping or resuming, etc.), events related to media,
12
 * or custom events plugins may originate on their own (e.g., a participant
13
 * publishing their media in a conference, or a SIP call starting). What
14
 * to do with these events is then up to the handler: it may choose to store
15
 * them somewhere (e.g., a database), analyse and process them, or simply
16
 * send them to an external tool for statistics purposes or troubleshooting.
17
 * Whatever the aim, the structures to make the interaction between core
18
 * and event handlers possible are defined here.
19
 * 
20
 * An event handler plugin that wants to register at the gateway needs to
21
 * implement the \c janus_eventhandler interface. This includes callbacks
22
 * the Janus core can use to pass and request information, and a mask of
23
 * the events the plugin is interested in subscribing to. Besides, as an
24
 * event handler plugin is a shared object, and as such external to the
25
 * gateway itself, in order to be dynamically loaded at startup it needs
26
 * to implement the \c create_e() hook as well, that should return a
27
 * pointer to the plugin instance. This is an example of such a step:
28
 * 
29
\verbatim
30
static janus_eventhandler myhandler = {
31
        [..]
32
};
33

34
janus_eventhandler *create(void) {
35
        JANUS_LOG(LOG_VERB, , "%s created!\n", MY_HANDLER_NAME);
36
        return &myhandler;
37
}
38
\endverbatim
39
 * 
40
 * This will make sure that your event handler plugin is loaded at startup
41
 * by the gateway, if it is deployed in the proper folder.
42
 * 
43
 * As anticipated and described in the above example, an event handler plugin
44
 * must basically be an instance of the \c janus_eventhandler type. As such,
45
 * it must implement the following methods and callbacks for the gateway:
46
 * 
47
 * - \c init(): this is called by the gateway as soon as your event handler
48
 * plugin is started; this is where you should setup your event handler plugin
49
 * (e.g., static stuff and reading the configuration file);
50
 * - \c destroy(): on the other hand, this is called by the gateway when it
51
 * is shutting down, and your event handler plugin should too;
52
 * - \c get_api_compatibility(): this method MUST return JANUS_EVENTHANDLER_API_VERSION;
53
 * - \c get_version(): this method should return a numeric version identifier (e.g., 3);
54
 * - \c get_version_string(): this method should return a verbose version identifier (e.g., "v1.0.1");
55
 * - \c 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");
56
 * - \c get_name(): this method should return a short display name for your event handler plugin (e.g., "My Amazing Event Handler");
57
 * - \c get_package(): this method should return a unique package identifier for your event handler plugin (e.g., "janus.eventhandler.myeventhandler");
58
 * - \c incoming_event(): this callack informs the event handler that an event is available for consumption.
59
 * 
60
 * All the above methods and callbacks are mandatory: the Janus core will
61
 * reject an event handler plugin that doesn't implement any of the
62
 * mandatory callbacks.
63
 * 
64
 * Additionally, a \c janus_eventhandler instance must also include a
65
 * mask of the events it is interested in, a \c events_mask janus_flag
66
 * object that must refer to the available types defined in this header.
67
 * The core, in fact, will refer to that mask to check whether your event
68
 * handler is interested in a specific event or not.   
69
 * 
70
 * Unlike other kind of modules (transports, plugins), the \c init() method
71
 * here only passes the path to the configurations files folder, as event
72
 * handlers never need to contact the gateway themselves. This path can be used to read and
73
 * parse a configuration file for the event handler plugin: the event handler
74
 * plugins we made available out of the box use the package name as a
75
 * name for the file (e.g., \c janus.eventhandler.fake.cfg for the sample
76
 * event handler plugin), but you're free to use a different one, as long
77
 * as it doesn't collide with existing ones. Besides, the existing eventhandler
78
 * plugins use the same INI format for configuration files the gateway
79
 * uses (relying on the \c janus_config helpers for the purpose) but
80
 * again, if you prefer a different format (XML, JSON, etc.) that's up to you. 
81
 * 
82
 * \ingroup eventhandlerapi
83
 * \ref eventhandlerapi
84
 */
85

    
86
#ifndef _JANUS_EVENTHANDLER_H
87
#define _JANUS_EVENTHANDLER_H
88

    
89
#include <stdlib.h>
90
#include <stdint.h>
91
#include <stdio.h>
92
#include <string.h>
93
#include <ctype.h>
94
#include <unistd.h>
95
#include <inttypes.h>
96

    
97
#include <glib.h>
98
#include <jansson.h>
99

    
100
#include "../utils.h"
101

    
102

    
103
/*! \brief Version of the API, to match the one event handler plugins were compiled against */
104
#define JANUS_EVENTHANDLER_API_VERSION        1
105

    
106
/*! \brief Initialization of all event handler plugin properties to NULL
107
 * 
108
 * \note All event handler plugins MUST add this as the FIRST line when initializing
109
 * their event handler plugin structure, e.g.:
110
 * 
111
\verbatim
112
static janus_eventhandler janus_fake_eventhandler handler plugin =
113
        {
114
                JANUS_EVENTHANDLER_INIT,
115
                
116
                .init = janus_fake_init,
117
                [..]
118
\endverbatim
119
 */
120

    
121
/** @name Type of events Janus could notify, and the handler subscribe to
122
 * @details This mask makes it easy to subscribe to, and unsubscribe from,
123
 * specific events, as all you need to do is to use janus_flags_set and
124
 * janus_flags_clear on the \c events_mask property of the handler instance,
125
 * and the core will know whether you care about something or not.
126
 */
127
///@{
128
/*! \brief No event */
129
#define JANUS_EVENT_TYPE_NONE                        (0)
130
/*! \brief Session related events (e.g., session created/destroyed, etc.) */
131
#define JANUS_EVENT_TYPE_SESSION                (1 << 0)
132
/*! \brief Handle related events (e.g., handle attached/detached, etc.) */
133
#define JANUS_EVENT_TYPE_HANDLE                        (1 << 1)
134
/*! \brief JSEP related events (e.g., got/sent offer/answer) */
135
#define JANUS_EVENT_TYPE_JSEP                        (1 << 3)
136
/*! \brief WebRTC related events (e.g., PeerConnection up/down, ICE updates, DTLS updates, etc.) */
137
#define JANUS_EVENT_TYPE_WEBRTC                        (1 << 4)
138
/*! \brief Media related events (e.g., media started/stopped flowing, stats on packets/bytes, etc.) */
139
#define JANUS_EVENT_TYPE_MEDIA                        (1 << 5)
140
/*! \brief Events originated by plugins (at the moment, all of them, no way to pick) */
141
#define JANUS_EVENT_TYPE_PLUGIN                        (1 << 6)
142
/*! \brief Events originated by transports (at the moment, all of them, no way to pick) */
143
#define JANUS_EVENT_TYPE_TRANSPORT                (1 << 7)
144
/*! \brief Events originated by the core for its own events (e.g., Janus starting/shutting down) */
145
#define JANUS_EVENT_TYPE_CORE                        (1 << 8)
146
        /* TODO Others? */
147
/*! \brief Mask with all events enabled (shortcut when you want to subscribe to everything) */
148
#define JANUS_EVENT_TYPE_ALL                (0xffffffff)
149
///@}
150

    
151
#define JANUS_EVENTHANDLER_INIT(...) {                        \
152
                .init = NULL,                                                        \
153
                .destroy = NULL,                                                \
154
                .get_api_compatibility = NULL,                        \
155
                .get_version = NULL,                                        \
156
                .get_version_string = NULL,                                \
157
                .get_description = NULL,                                \
158
                .get_name = NULL,                                                \
159
                .get_author = NULL,                                                \
160
                .get_package = NULL,                                        \
161
                .incoming_event = NULL,                                        \
162
                .events_mask = JANUS_EVENT_TYPE_NONE,        \
163
                ## __VA_ARGS__ }
164

    
165

    
166
/*! \brief Callbacks to contact the gateway */
167
typedef struct janus_eventhandler_callbacks janus_eventhandler_callbacks;
168
/*! \brief The event handler plugin session and callbacks interface */
169
typedef struct janus_eventhandler janus_eventhandler;
170

    
171

    
172
/*! \brief The event handler plugin session and callbacks interface */
173
struct janus_eventhandler {
174
        /*! \brief Event handler plugin initialization/constructor
175
         * @param[in] config_path Path of the folder where the configuration for this event handler plugin can be found
176
         * @returns 0 in case of success, a negative integer in case of error */
177
        int (* const init)(const char *config_path);
178
        /*! \brief Event handler plugin deinitialization/destructor */
179
        void (* const destroy)(void);
180

    
181
        /*! \brief Informative method to request the API version this event handler plugin was compiled against
182
         *  \note All event handler plugins MUST implement this method and return JANUS_EVENTHANDLER_API_VERSION
183
         * to make this work, or they will be rejected by the core. */
184
        int (* const get_api_compatibility)(void);
185
        /*! \brief Informative method to request the numeric version of the event handler plugin */
186
        int (* const get_version)(void);
187
        /*! \brief Informative method to request the string version of the event handler plugin */
188
        const char *(* const get_version_string)(void);
189
        /*! \brief Informative method to request a description of the event handler plugin */
190
        const char *(* const get_description)(void);
191
        /*! \brief Informative method to request the name of the event handler plugin */
192
        const char *(* const get_name)(void);
193
        /*! \brief Informative method to request the author of the event handler plugin */
194
        const char *(* const get_author)(void);
195
        /*! \brief Informative method to request the package name of the event handler plugin (what will be used in web applications to refer to it) */
196
        const char *(* const get_package)(void);
197

    
198
        /*! \brief Method to notify the event handler plugin that a new event is available
199
         * \details All events are notified as a Jansson json_t object, and the syntax of
200
         * the associated JSON document is as follows:
201
         * \verbatim
202
        {
203
                "type" : <numeric event type identifier>,
204
                "timestamp" : <monotonic time of when the event was generated>,
205
                "session_id" : <unique session identifier>,
206
                "handle_id" : <unique handle identifier, if provided/available>,
207
                "event" : {
208
                        <event body, custom depending on event type>
209
                }
210
        }
211
         * \endverbatim
212
         * \note Do NOT handle the event directly in this method. Janus sends events from its
213
         * working threads, and so you'd most likely end up slowing it down. Just take note of it
214
         * and handle it somewhere else. It's your responsibility to \c json_decref the event
215
         * object once you're done with it: a failure to do so will result in memory leaks.
216
         * @param[in] event Jansson object containing the event details */
217
        void (* const incoming_event)(json_t *event);
218

    
219
        /*! \brief Mask of events this handler is interested in, as a janus_flags object */
220
        janus_flags events_mask;
221
};
222

    
223
/*! \brief The hook that event handler plugins need to implement to be created from the gateway */
224
typedef janus_eventhandler* create_e(void);
225

    
226
#endif