Statistics
| Branch: | Revision:

janus-gateway / plugins / plugin.h @ 47df0af9

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 <jansson.h>
158

    
159

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

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

    
209

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

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

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

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

    
260
        /*! \brief Method to create a new session/handle for a peer
261
         * @param[in] handle The plugin/gateway session that will be used for this peer
262
         * @param[out] error An integer that may contain information about any error */
263
        void (* const create_session)(janus_plugin_session *handle, int *error);
264
        /*! \brief Method to handle an incoming message/request from a peer
265
         * @param[in] handle The plugin/gateway session used for this peer
266
         * @param[in] transaction The transaction identifier for this message/request
267
         * @param[in] message The json_t object containing the message/request JSON
268
         * @param[in] jsep The json_t object containing the JSEP type/SDP, if available
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, json_t *message, json_t *jsep);
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_t object with the requested info */
324
        json_t *(* 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
         * @note The Janus core increases the references to both the message and jsep
332
         * json_t objects. This means that you'll have to decrease your own
333
         * reference yourself with a \c json_decref after calling push_event.
334
         * @param[in] handle The plugin/gateway session used for this peer
335
         * @param[in] plugin The plugin instance that is sending the message/event
336
         * @param[in] transaction The transaction identifier this message refers to
337
         * @param[in] message The json_t object containing the JSON message
338
         * @param[in] jsep The json_t object containing the JSEP type and the SDP attached to the message/event, if any (offer/answer) */
339
        int (* const push_event)(janus_plugin_session *handle, janus_plugin *plugin, const char *transaction, json_t *message, json_t *jsep);
340

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

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

    
370
};
371

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

    
375

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

    
405
/*! \brief Janus plugin result */
406
struct janus_plugin_result {
407
        /*! \brief Result type */
408
        janus_plugin_result_type type;
409
        /*! \brief Text associated with this plugin result.
410
         * @note This is ONLY used for JANUS_PLUGIN_OK_WAIT (to provide hints on
411
         * why a request is being handled asynchronously) and JANUS_PLUGIN_ERROR
412
         * (to provide a reason for the error). It is ignored for JANUS_PLUGIN_OK.
413
         * Besides, it is NOT freed when destroying the janus_plugin_result instance,
414
         * so if you allocated a string for that, you'll have to free it yourself. */
415
        const char *text;
416
        /*! \brief Result content
417
         * @note This is ONLY used for JANUS_PLUGIN_OK, and is ignored otherwise.
418
         * It MUST be a valid JSON payload (even when returning application
419
         * level errors). Its reference is decremented automatically when destroying
420
         * the janus_plugin_result instance, so if your plugin wants to re-use the
421
         * same object for multiple responses, you jave to \c json_incref the object before
422
         * passing it to the core, and \c json_decref it when you're done with it. */
423
        json_t *content;
424
};
425

    
426
/*! \brief Helper to quickly create a janus_plugin_result instance
427
 * @param[in] type The type of result
428
 * @param[in] text String to add to the result (for JANUS_PLUGIN_OK_WAIT or JANUS_PLUGIN_ERROR), if any
429
 * @param[in] content The json_t object with the content of the result, if any
430
 * @returns A valid janus_plugin_result instance, if successful, or NULL otherwise */
431
janus_plugin_result *janus_plugin_result_new(janus_plugin_result_type type, const char *text, json_t *content);
432

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

    
439

    
440
#endif