Statistics
| Branch: | Revision:

janus-gateway / plugins / plugin.h @ 1d31e31f

History | View | Annotate | Download (23.4 KB)

1
/*! \file   plugin.h
2
 * \author Lorenzo Miniero <lorenzo@meetecho.com>
3
 * \copyright GNU General Public License v3
4
 * \brief  Plugin-Gateway communication
5
 * \details  This header contains the definition of the callbacks both
6
 * the gateway and all the plugins need to implement to interact with
7
 * each other. The structures to make the communication possible are
8
 * defined here as well.
9
 * 
10
 * In particular, the gateway implements the \c janus_callbacks interface.
11
 * This means that, as a plugin, you can use the methods it exposes to
12
 * contact the gateway, e.g., in order to have it relay a message, event
13
 * or RTP/RTCP packet to the peer you're handling. In particular, the
14
 * methods the gateway exposes to plugins are:
15
 * 
16
 * - \c push_event(): to send a JSON message/event to the peer (with or without
17
 * an attached JSEP formatted SDP to negotiate a WebRTC PeerConnection);
18
 * the syntax of the message/event is completely up to you, the only
19
 * important thing is that it MUST be a JSON object, as it will be included
20
 * as such within the Janus session/handle protocol;
21
 * - \c relay_rtp(): to send/relay the peer an RTP packet;
22
 * - \c relay_rtcp(): to send/relay the peer an RTCP message.
23
 * - \c relay_data(): to send/relay the peer a SCTP DataChannel message.
24
 * 
25
 * On the other hand, a plugin that wants to register at the gateway
26
 * needs to implement the \c janus_plugin interface. Besides, as a
27
 * plugin is a shared object, and as such external to the gateway itself,
28
 * in order to be dynamically loaded at startup it needs to implement
29
 * the \c create_p() hook as well, that should return a pointer to the
30
 * plugin instance. This is an example of such a step:
31
 * 
32
\verbatim
33
static janus_plugin myplugin = {
34
        [..]
35
};
36

37
janus_plugin *create(void) {
38
        JANUS_LOG(LOG_VERB, , "%s created!\n", MY_PLUGIN_NAME);
39
        return &myplugin;
40
}
41
\endverbatim
42
 * 
43
 * This will make sure that your plugin is loaded at startup by the gateway,
44
 * if it is deployed in the proper folder.
45
 * 
46
 * As anticipated and described in the above example, a plugin must basically
47
 * be an instance of the \c janus_plugin type. As such, it must implement
48
 * the following methods and callbacks for the gateway:
49
 * 
50
 * - \c init(): this is called by the gateway as soon as your plugin is started;
51
 * this is where you should setup your plugin (e.g., static stuff and reading
52
 * the configuration file);
53
 * - \c destroy(): on the other hand, this is called by the gateway when it
54
 * is shutting down, and your plugin should too;
55
 * - \c get_api_compatibility(): this method MUST return JANUS_PLUGIN_API_VERSION;
56
 * - \c get_version(): this method should return a numeric version identifier (e.g., 3);
57
 * - \c get_version_string(): this method should return a verbose version identifier (e.g., "v1.0.1");
58
 * - \c get_description(): this method should return a verbose description of your plugin (e.g., "This is my awesome plugin that does this and that");
59
 * - \c get_name(): this method should return a short display name for your plugin (e.g., "My Awesome Plugin");
60
 * - \c get_package(): this method should return a unique package identifier for your plugin (e.g., "janus.plugin.myplugin");
61
 * - \c create_session(): this method is called by the gateway to create a session between you and a peer;
62
 * - \c handle_message(): a callback to notify you the peer sent you a message/request;
63
 * - \c setup_media(): a callback to notify you the peer PeerConnection is now ready to be used;
64
 * - \c incoming_rtp(): a callback to notify you a peer has sent you a RTP packet;
65
 * - \c incoming_rtcp(): a callback to notify you a peer has sent you a RTCP message;
66
 * - \c incoming_data(): a callback to notify you a peer has sent you a message on a SCTP DataChannel;
67
 * - \c slow_link(): a callback to notify you a peer has sent a lot of NACKs recently, and the media path may be slow;
68
 * - \c hangup_media(): a callback to notify you the peer PeerConnection has been closed (e.g., after a DTLS alert);
69
 * - \c query_session(): this method is called by the gateway to get plugin-specific info on a session between you and a peer;
70
 * - \c destroy_session(): this method is called by the gateway to destroy a session between you and a peer.
71
 * 
72
 * All the above methods and callbacks, except for \c incoming_rtp ,
73
 * \c incoming_rtcp , \c incoming_data and \c slow_link , are mandatory:
74
 * the Janus core will reject a plugin that doesn't implement any of the
75
 * mandatory callbacks. The previously mentioned ones, instead, are
76
 * optional, so you're free to implement only those you care about. If
77
 * your plugin will not handle any data channel, for instance, it makes
78
 * sense to not implement the \c incoming_data callback at all. At the
79
 * same time, if your plugin is ONLY going to use data channels and
80
 * can't care less about RTP or RTCP, \c incoming_rtp and \c incoming_rtcp
81
 * can be left out. Finally, \c slow_link is just there as a helper, some
82
 * additional information you may be interested about, but you're not
83
 * forced to receive it if you don't care.
84
 * 
85
 * The gateway \c janus_callbacks interface is provided to a plugin, together
86
 * with the path to the configurations files folder, in the \c init() method.
87
 * This path can be used to read and parse a configuration file for the
88
 * plugin: the plugins we made available out of the box use the package
89
 * name as a name for the file (e.g., \c janus.plugin.echotest.cfg for
90
 * the Echo Test plugin), but you're free to use a different one, as long
91
 * as it doesn't collide with existing ones. Besides, the existing plugins
92
 * use the same INI format for configuration files the gateway uses (relying
93
 * on the \c janus_config helpers for the purpose) but again, if you prefer
94
 * a different format (XML, JSON, etc.) that's up to you. 
95
 *
96
 * Both the the gateway and a plugin can have several different sessions
97
 * with the same and/or different peers: to match a specific session,
98
 * a plugin can rely on a mapping called janus_plugin_session that
99
 * is what all the communication between the plugins and the gateway
100
 * (that is, both methods invoked by the gateway and callbacks invoked by
101
 * the plugins) will make use of. See the janus_videoroom.c plugin for
102
 * an example of multiple handles associated to the same peer. 
103
 * 
104
 * All messages/requests/events sent to and received from a plugin are
105
 * asynchronous, meaning there's no way to immediately reply to a message
106
 * sent by a browser, for instance. Messages/requests coming from browsers
107
 * in a \c handle_message() callback, though, have a transaction
108
 * identifier, which you can use in a \c push_event() reply to allow the
109
 * browser to match it to the original request, if needed.
110
 * 
111
 * As anticipated, both \c handle_message() and \c push_event() can attach
112
 * a JSEP/SDP payload. This means that a browser, for instance, can attach
113
 * a JSEP/SDP offer to negotiate a WebRTC PeerConnection with a plugin: the plugin
114
 * would then need to provide, immediately or not, a JSEP/SDP answer to
115
 * do so. At the same time, a plugin may want to originate the call instead:
116
 * in that case, the plugin would attach a JSEP/SDP offer in a \c push_event()
117
 * call, to which the browser would then need to reply with a JSEP/SDP answer,
118
 * as described in \ref JS.
119
 * \note It's important to notice that, while the gateway core would indeed
120
 *  take care of the WebRTC PeerConnection setup itself in terms of
121
 * ICE/DTLS/RT(C)P on your behalf, plugins are what will actually manipulate
122
 * the media flowing around, and as such it's them who are responsible for
123
 * what concerns the codec negotiation in a JSEP/SDP offer/answer. This
124
 * normally is not something you need to worry about, especially if you're
125
 * just moving SDP around (e.g., janus_echotest.c or janus_videocall.c). 
126
 * If your plugin is going to generate media frames (e.g., as janus_audiobridge.c),
127
 * you only support some codecs (e.g., Opus in janus_audiobridge.c) or you
128
 * want to use the same SDP offer for several different sessions (e.g., a webinar), 
129
 * you need to make sure that your offer/answer does not contain anything
130
 * you don't support. Besides, you also need to make sure that you use
131
 * SDP-provided information (e.g., payload types) coherently. 
132
 * 
133
 * \todo Right now plugins can only interact with peers, through the gateway.
134
 * Besides, a single PeerConnection can at the moment be used by only one
135
 * plugin, as that plugin is actually the "owner" of the PeerConnection itself.
136
 * In next versions of Janus we'll work on stuff like plugins "chaining": that
137
 * is, plugins that can act as "filters" for other plugins (e.g., transcoders)
138
 * or as additional sources/sinks for the same PeerConnection of the same peer
139
 * (e.g., to add recording functionality to a video conference using a
140
 * different plugin).
141
 * 
142
 * \ingroup pluginapi
143
 * \ref pluginapi
144
 */
145

    
146
#ifndef _JANUS_PLUGIN_H
147
#define _JANUS_PLUGIN_H
148

    
149
#include <stdlib.h>
150
#include <stdint.h>
151
#include <stdio.h>
152
#include <string.h>
153
#include <ctype.h>
154
#include <unistd.h>
155
#include <inttypes.h>
156

    
157
#include <glib.h>
158
#include <jansson.h>
159

    
160

    
161
/*! \brief Version of the API, to match the one plugins were compiled against
162
 * 
163
 * \note This was added in version 0.0.7 of the gateway, to address changes
164
 * to the API that might break existing plugin or the core itself. All
165
 * plugins MUST implement the get_api_compatibility() method to make
166
 * this work. Do NOT try to launch a pre 0.0.7 plugin on a >= 0.0.7
167
 * gateway or it will crash.
168
 * 
169
 */
170
#define JANUS_PLUGIN_API_VERSION        5
171

    
172
/*! \brief Initialization of all plugin properties to NULL
173
 * 
174
 * \note This was added in version 0.0.8 of the gateway, to address changes
175
 * to the API that might break existing plugin or the core itself. All
176
 * plugins MUST add this as the FIRST line when initializing their
177
 * plugin structure, e.g.:
178
 * 
179
\verbatim
180
static janus_plugin janus_echotest_plugin =
181
        {
182
                JANUS_PLUGIN_INIT,
183
                
184
                .init = janus_echotest_init,
185
                [..]
186
\endverbatim
187
 * */
188
#define JANUS_PLUGIN_INIT(...) {                \
189
                .init = NULL,                                        \
190
                .destroy = NULL,                                \
191
                .get_api_compatibility = NULL,        \
192
                .get_version = NULL,                        \
193
                .get_version_string = NULL,                \
194
                .get_description = NULL,                \
195
                .get_name = NULL,                                \
196
                .get_author = NULL,                                \
197
                .get_package = NULL,                        \
198
                .create_session = NULL,                        \
199
                .handle_message = NULL,                        \
200
                .setup_media = NULL,                        \
201
                .incoming_rtp = NULL,                        \
202
                .incoming_rtcp = NULL,                        \
203
                .incoming_data = NULL,                        \
204
                .slow_link = NULL,                                \
205
                .hangup_media = NULL,                        \
206
                .destroy_session = NULL,                \
207
                .query_session = NULL,                         \
208
                ## __VA_ARGS__ }
209

    
210

    
211
/*! \brief Callbacks to contact the gateway */
212
typedef struct janus_callbacks janus_callbacks;
213
/*! \brief The plugin session and callbacks interface */
214
typedef struct janus_plugin janus_plugin;
215
/*! \brief Plugin-Gateway session mapping */
216
typedef struct janus_plugin_session janus_plugin_session;
217
/*! \brief Result of individual requests passed to plugins */
218
typedef struct janus_plugin_result janus_plugin_result;
219

    
220
/*! \brief Plugin-Gateway session mapping */
221
struct janus_plugin_session {
222
        /*! \brief Opaque pointer to the gateway session */
223
        void *gateway_handle;
224
        /*! \brief Opaque pointer to the plugin session */
225
        void *plugin_handle;
226
        /*! \brief Whether this mapping has been stopped definitely or not: if so,
227
         * the plugin shouldn't make use of it anymore */
228
        int stopped:1;
229
};
230

    
231
/*! \brief The plugin session and callbacks interface */
232
struct janus_plugin {
233
        /*! \brief Plugin initialization/constructor
234
         * @param[in] callback The callback instance the plugin can use to contact the gateway
235
         * @param[in] config_path Path of the folder where the configuration for this plugin can be found
236
         * @returns 0 in case of success, a negative integer in case of error */
237
        int (* const init)(janus_callbacks *callback, const char *config_path);
238
        /*! \brief Plugin deinitialization/destructor */
239
        void (* const destroy)(void);
240

    
241
        /*! \brief Informative method to request the API version this plugin was compiled against
242
         *  \note This was added in version 0.0.7 of the gateway, to address changes
243
         * to the API that might break existing plugin or the core itself. All
244
         * plugins MUST implement this method and return JANUS_PLUGIN_API_VERSION
245
         * to make this work, or they will be rejected by the core. Do NOT try
246
         * to launch a <= 0.0.7 plugin on a >= 0.0.7 gateway or it will crash. */
247
        int (* const get_api_compatibility)(void);
248
        /*! \brief Informative method to request the numeric version of the plugin */
249
        int (* const get_version)(void);
250
        /*! \brief Informative method to request the string version of the plugin */
251
        const char *(* const get_version_string)(void);
252
        /*! \brief Informative method to request a description of the plugin */
253
        const char *(* const get_description)(void);
254
        /*! \brief Informative method to request the name of the plugin */
255
        const char *(* const get_name)(void);
256
        /*! \brief Informative method to request the author of the plugin */
257
        const char *(* const get_author)(void);
258
        /*! \brief Informative method to request the package name of the plugin (what will be used in web applications to refer to it) */
259
        const char *(* const get_package)(void);
260

    
261
        /*! \brief Method to create a new session/handle for a peer
262
         * @param[in] handle The plugin/gateway session that will be used for this peer
263
         * @param[out] error An integer that may contain information about any error */
264
        void (* const create_session)(janus_plugin_session *handle, int *error);
265
        /*! \brief Method to handle an incoming message/request from a peer
266
         * @param[in] handle The plugin/gateway session used for this peer
267
         * @param[in] transaction The transaction identifier for this message/request
268
         * @param[in] message The stringified version of the message/request JSON
269
         * @returns A janus_plugin_result instance that may contain a response (for immediate/synchronous replies), an ack
270
         * (for asynchronously managed requests) or an error */
271
        struct janus_plugin_result * (* const handle_message)(janus_plugin_session *handle, char *transaction, char *message, char *sdp_type, char *sdp);
272
        /*! \brief Callback to be notified when the associated PeerConnection is up and ready to be used
273
         * @param[in] handle The plugin/gateway session used for this peer */
274
        void (* const setup_media)(janus_plugin_session *handle);
275
        /*! \brief Method to handle an incoming RTP packet from a peer
276
         * @param[in] handle The plugin/gateway session used for this peer
277
         * @param[in] video Whether this is an audio or a video frame
278
         * @param[in] buf The packet data (buffer)
279
         * @param[in] len The buffer lenght */
280
        void (* const incoming_rtp)(janus_plugin_session *handle, int video, char *buf, int len);
281
        /*! \brief Method to handle an incoming RTCP packet from a peer
282
         * @param[in] handle The plugin/gateway session used for this peer
283
         * @param[in] video Whether this is related to an audio or a video stream
284
         * @param[in] buf The message data (buffer)
285
         * @param[in] len The buffer lenght */
286
        void (* const incoming_rtcp)(janus_plugin_session *handle, int video, char *buf, int len);
287
        /*! \brief Method to handle incoming SCTP/DataChannel data from a peer (text only, for the moment)
288
         * \note We currently only support text data, binary data will follow... please also notice that
289
         * DataChannels send unterminated strings, so you'll have to terminate them with a \0 yourself to
290
         * use them. 
291
         * @param[in] handle The plugin/gateway session used for this peer
292
         * @param[in] buf The message data (buffer)
293
         * @param[in] len The buffer lenght */
294
        void (* const incoming_data)(janus_plugin_session *handle, char *buf, int len);
295
        /*! \brief Method to be notified by the core when too many NACKs have
296
         * been received or sent by Janus, and so a slow or potentially
297
         * unreliable network is to be expected for this peer
298
         * \note Beware that this callback may be called more than once in a row,
299
         * (even though never more than once per second), until things go better for that
300
         * PeerConnection. You may or may not want to handle this callback and
301
         * act on it, considering you can get bandwidth information from REMB
302
         * feedback sent by the peer if the browser supports it. Besides, your
303
         * plugin may not have access to encoder related settings to slow down
304
         * or decreae the bitrate if required after the callback is called.
305
         * Nevertheless, it can be useful for debugging, or for informing your
306
         * users about potential issues that may be happening media-wise.
307
         * @param[in] handle The plugin/gateway session used for this peer
308
         * @param[in] uplink Whether this is related to the uplink (Janus to peer)
309
         * or downlink (peer to Janus)
310
         * @param[in] video Whether this is related to an audio or a video stream */
311
        void (* const slow_link)(janus_plugin_session *handle, int uplink, int video);
312
        /*! \brief Callback to be notified about DTLS alerts from a peer (i.e., the PeerConnection is not valid any more)
313
         * @param[in] handle The plugin/gateway session used for this peer */
314
        void (* const hangup_media)(janus_plugin_session *handle);
315
        /*! \brief Method to destroy a session/handle for a peer
316
         * @param[in] handle The plugin/gateway session used for this peer
317
         * @param[out] error An integer that may contain information about any error */
318
        void (* const destroy_session)(janus_plugin_session *handle, int *error);
319
        /*! \brief Method to get plugin-specific info of a session/handle
320
         *  \note This was added in version 0.0.7 of the gateway. Janus assumes
321
         * the string is always allocated, so don't return constants here
322
         * @param[in] handle The plugin/gateway session used for this peer
323
         * @returns A JSON-formatted string with the requested info */
324
        char *(* const query_session)(janus_plugin_session *handle);
325

    
326
};
327

    
328
/*! \brief Callbacks to contact the gateway */
329
struct janus_callbacks {
330
        /*! \brief Callback to push events/messages to a peer
331
         * @param[in] handle The plugin/gateway session used for this peer
332
         * @param[in] plugin The plugin instance that is sending the message/event
333
         * @param[in] transaction The transaction identifier this message refers to
334
         * @param[in] message The stringified version of the JSON message
335
         * @param[in] sdp_type The type of the SDP attached to the message/event, if any (offer/answer)
336
         * @param[in] sdp The SDP attached to the message/event, if any (in case the plugin is requesting or responding to a media setup) */
337
        int (* const push_event)(janus_plugin_session *handle, janus_plugin *plugin, const char *transaction, const char *message, const char *sdp_type, const char *sdp);
338

    
339
        /*! \brief Callback to relay RTP packets to a peer
340
         * @param[in] handle The plugin/gateway session used for this peer
341
         * @param[in] video Whether this is an audio or a video frame
342
         * @param[in] buf The packet data (buffer)
343
         * @param[in] len The buffer lenght */
344
        void (* const relay_rtp)(janus_plugin_session *handle, int video, char *buf, int len);
345
        /*! \brief Callback to relay RTCP messages to a peer
346
         * @param[in] handle The plugin/gateway session that will be used for this peer
347
         * @param[in] video Whether this is related to an audio or a video stream
348
         * @param[in] buf The message data (buffer)
349
         * @param[in] len The buffer lenght */
350
        void (* const relay_rtcp)(janus_plugin_session *handle, int video, char *buf, int len);
351
        /*! \brief Callback to relay SCTP/DataChannel messages to a peer
352
         * @param[in] handle The plugin/gateway session that will be used for this peer
353
         * @param[in] buf The message data (buffer)
354
         * @param[in] len The buffer lenght */
355
        void (* const relay_data)(janus_plugin_session *handle, char *buf, int len);
356

    
357
        /*! \brief Callback to ask the core to close a WebRTC PeerConnection
358
         * \note A call to this method will result in the core invoking the hangup_media
359
         * callback on this plugin when done
360
         * @param[in] handle The plugin/gateway session that the PeerConnection is related to */
361
        void (* const close_pc)(janus_plugin_session *handle);
362
        /*! \brief Callback to ask the core to get rid of a plugin/gateway session
363
         * \note A call to this method will result in the core invoking the destroy_session
364
         * callback on this plugin when done
365
         * @param[in] handle The plugin/gateway session to get rid of */
366
        void (* const end_session)(janus_plugin_session *handle);
367

    
368
        /*! \brief Callback to check whether the event handlers mechanism is enabled
369
         * @returns TRUE if it is, FALSE if it isn't (which means notify_event should NOT be called) */
370
        gboolean (* const events_is_enabled)(void);
371
        /*! \brief Callback to notify an event to the registered and subscribed event handlers
372
         * \note Don't unref the event object, the core will do that for you
373
         * @param[in] handle The plugin/gateway session originating the event
374
         * @param[in] event The event to notify as a Jansson json_t object */
375
        void (* const notify_event)(janus_plugin_session *handle, json_t *event);
376

    
377
};
378

    
379
/*! \brief The hook that plugins need to implement to be created from the gateway */
380
typedef janus_plugin* create_p(void);
381

    
382

    
383
/** @name Janus plugin results
384
 * @brief When a client sends a message to a plugin (e.g., a request or a
385
 * command) this is notified to the plugin through a handle_message()
386
 * callback. The plugin can then either handle the request immediately
387
 * and provide a response (synchronous approach) or decide to queue it
388
 * and process it later (asynchronous approach). In both cases the plugin
389
 * must return a janus_plugin_result instance to the core, that will allow
390
 * the client to: 1. know whether a response is immediately available or
391
 * it will be later on through notifications, and 2. what the actual content
392
 * of the result might be. Of course, notifications related to the
393
 * transaction may occur later on even for synchronous requests, if the
394
 * plugin was implemented with use cases that envisage this approach.
395
 * @note An error may be returned as well, but this would cause a core-level
396
 * error to be returned to the client. If you want to provide indications
397
 * about a failed operation for application-level reason, the correct
398
 * approach is to return a success with a plugin-specific payload describing
399
 * the error.
400
 */
401
///@{
402
/*! \brief Result types */
403
typedef enum janus_plugin_result_type {
404
        /*! \brief A severe error happened (not an application level error) */
405
        JANUS_PLUGIN_ERROR = -1,
406
        /*! \brief The request was correctly handled and a response is provided (synchronous) */
407
        JANUS_PLUGIN_OK,
408
        /*! \brief The request was correctly handled and notifications will follow with more info (asynchronous) */
409
        JANUS_PLUGIN_OK_WAIT,
410
} janus_plugin_result_type;
411

    
412
/*! \brief Janus plugin result */
413
struct janus_plugin_result {
414
        /*! \brief Result type */
415
        janus_plugin_result_type type;
416
        /*! \brief Result content
417
         * @note This MUST be a valid JSON payload in case of JANUS_PLUGIN_OK (even when
418
         * returning application level errors), and MUST be a generic string
419
         * in case of JANUS_PLUGIN_ERROR. If returning a JANUS_PLUGIN_OK_WAIT,
420
         * the content is optional, but if provided (e.g., if the plugin wants
421
         * to provide verbose info about the reasons for choosing an async approach)
422
         * the content MUST be a generic string, as it will end up in a string
423
         * element in the JSON ack response. */
424
        char *content;
425
};
426

    
427
/*! \brief Helper to quickly create a janus_plugin_result instance
428
 * @param[in] type The type of result
429
 * @param[in] content The content of the result
430
 * @note The content is always strdup-ed, if available, so remember to free the original
431
 * string yourself, if you allocated it
432
 * @returns A valid janus_plugin_result instance, if successful, or NULL otherwise */
433
janus_plugin_result *janus_plugin_result_new(janus_plugin_result_type type, const char *content);
434

    
435
/*! \brief Helper to quickly destroy a janus_plugin_result instance
436
 * @param[in] result The janus_plugin_result instance to destroy
437
 * @returns A valid janus_plugin_result instance, if successful, or NULL otherwise */
438
void janus_plugin_result_destroy(janus_plugin_result *result);
439
///@}
440

    
441

    
442
#endif