Statistics
| Branch: | Revision:

janus-gateway / plugins / plugin.h @ 8241c758

History | View | Annotate | Download (24.1 KB)

1 be35facb meetecho
/*! \file   plugin.h
2
 * \author Lorenzo Miniero <lorenzo@meetecho.com>
3 9d11ac50 meetecho
 * \copyright GNU General Public License v3
4 be35facb meetecho
 * \brief  Plugin-Gateway communication
5
 * \details  This header contains the definition of the callbacks both
6 3c317d48 Lorenzo Miniero
 * the gateway and all the plugins need to implement to interact with
7 be35facb meetecho
 * 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 a3d13e20 meetecho
 * - \c relay_data(): to send/relay the peer a SCTP DataChannel message.
24 be35facb meetecho
 * 
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 3a26e009 meetecho
        JANUS_LOG(LOG_VERB, , "%s created!\n", MY_PLUGIN_NAME);
39 be35facb meetecho
        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 667b2005 meetecho
 * - \c get_api_compatibility(): this method MUST return JANUS_PLUGIN_API_VERSION;
56 be35facb meetecho
 * - \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 a3d13e20 meetecho
 * - \c incoming_data(): a callback to notify you a peer has sent you a message on a SCTP DataChannel;
67 1281ca86 meetecho
 * - \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 be35facb meetecho
 * - \c hangup_media(): a callback to notify you the peer PeerConnection has been closed (e.g., after a DTLS alert);
69 667b2005 meetecho
 * - \c query_session(): this method is called by the gateway to get plugin-specific info on a session between you and a peer;
70 be35facb meetecho
 * - \c destroy_session(): this method is called by the gateway to destroy a session between you and a peer.
71
 * 
72 1281ca86 meetecho
 * 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 be35facb meetecho
 * 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 cfd5c0d6 meetecho
 * a plugin can rely on a mapping called janus_plugin_session that
99 be35facb meetecho
 * 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 1d31e31f Lorenzo Miniero
#include <glib.h>
158 6c173b76 Lorenzo Miniero
#include <jansson.h>
159
160 be35facb meetecho
161 667b2005 meetecho
/*! \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 1281ca86 meetecho
 */
170 ff455cce Lorenzo Miniero
#define JANUS_PLUGIN_API_VERSION        8
171 1281ca86 meetecho
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 667b2005 meetecho
 * */
188 1281ca86 meetecho
#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 667b2005 meetecho
210
211 be35facb meetecho
/*! \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 cfd5c0d6 meetecho
typedef struct janus_plugin_session janus_plugin_session;
217 292d035f meetecho
/*! \brief Result of individual requests passed to plugins */
218
typedef struct janus_plugin_result janus_plugin_result;
219 be35facb meetecho
220
/*! \brief Plugin-Gateway session mapping */
221 cfd5c0d6 meetecho
struct janus_plugin_session {
222 be35facb meetecho
        /*! \brief Opaque pointer to the gateway session */
223
        void *gateway_handle;
224
        /*! \brief Opaque pointer to the plugin session */
225
        void *plugin_handle;
226 cfd5c0d6 meetecho
        /*! \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 be35facb meetecho
};
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 667b2005 meetecho
        /*! \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 be35facb meetecho
        /*! \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 a3d13e20 meetecho
        /*! \brief Informative method to request the author of the plugin */
257
        const char *(* const get_author)(void);
258 be35facb meetecho
        /*! \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 cfd5c0d6 meetecho
        void (* const create_session)(janus_plugin_session *handle, int *error);
265 be35facb meetecho
        /*! \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 dd11fa0a Lorenzo Miniero
         * @param[in] message The json_t object containing the message/request JSON
269
         * @param[in] jsep The json_t object containing the JSEP type/SDP, if available
270 292d035f meetecho
         * @returns A janus_plugin_result instance that may contain a response (for immediate/synchronous replies), an ack
271
         * (for asynchronously managed requests) or an error */
272 dd11fa0a Lorenzo Miniero
        struct janus_plugin_result * (* const handle_message)(janus_plugin_session *handle, char *transaction, json_t *message, json_t *jsep);
273 be35facb meetecho
        /*! \brief Callback to be notified when the associated PeerConnection is up and ready to be used
274
         * @param[in] handle The plugin/gateway session used for this peer */
275 cfd5c0d6 meetecho
        void (* const setup_media)(janus_plugin_session *handle);
276 be35facb meetecho
        /*! \brief Method to handle an incoming RTP packet from a peer
277
         * @param[in] handle The plugin/gateway session used for this peer
278
         * @param[in] video Whether this is an audio or a video frame
279
         * @param[in] buf The packet data (buffer)
280
         * @param[in] len The buffer lenght */
281 cfd5c0d6 meetecho
        void (* const incoming_rtp)(janus_plugin_session *handle, int video, char *buf, int len);
282 be35facb meetecho
        /*! \brief Method to handle an incoming RTCP packet from a peer
283
         * @param[in] handle The plugin/gateway session used for this peer
284
         * @param[in] video Whether this is related to an audio or a video stream
285
         * @param[in] buf The message data (buffer)
286
         * @param[in] len The buffer lenght */
287 cfd5c0d6 meetecho
        void (* const incoming_rtcp)(janus_plugin_session *handle, int video, char *buf, int len);
288 a3d13e20 meetecho
        /*! \brief Method to handle incoming SCTP/DataChannel data from a peer (text only, for the moment)
289
         * \note We currently only support text data, binary data will follow... please also notice that
290
         * DataChannels send unterminated strings, so you'll have to terminate them with a \0 yourself to
291
         * use them. 
292
         * @param[in] handle The plugin/gateway session used for this peer
293
         * @param[in] buf The message data (buffer)
294
         * @param[in] len The buffer lenght */
295
        void (* const incoming_data)(janus_plugin_session *handle, char *buf, int len);
296 24c01741 meetecho
        /*! \brief Method to be notified by the core when too many NACKs have
297
         * been received or sent by Janus, and so a slow or potentially
298
         * unreliable network is to be expected for this peer
299 1281ca86 meetecho
         * \note Beware that this callback may be called more than once in a row,
300
         * (even though never more than once per second), until things go better for that
301
         * PeerConnection. You may or may not want to handle this callback and
302
         * act on it, considering you can get bandwidth information from REMB
303
         * feedback sent by the peer if the browser supports it. Besides, your
304
         * plugin may not have access to encoder related settings to slow down
305
         * or decreae the bitrate if required after the callback is called.
306
         * Nevertheless, it can be useful for debugging, or for informing your
307
         * users about potential issues that may be happening media-wise.
308
         * @param[in] handle The plugin/gateway session used for this peer
309 24c01741 meetecho
         * @param[in] uplink Whether this is related to the uplink (Janus to peer)
310
         * or downlink (peer to Janus)
311 1281ca86 meetecho
         * @param[in] video Whether this is related to an audio or a video stream */
312 24c01741 meetecho
        void (* const slow_link)(janus_plugin_session *handle, int uplink, int video);
313 be35facb meetecho
        /*! \brief Callback to be notified about DTLS alerts from a peer (i.e., the PeerConnection is not valid any more)
314
         * @param[in] handle The plugin/gateway session used for this peer */
315 cfd5c0d6 meetecho
        void (* const hangup_media)(janus_plugin_session *handle);
316 be35facb meetecho
        /*! \brief Method to destroy a session/handle for a peer
317
         * @param[in] handle The plugin/gateway session used for this peer
318
         * @param[out] error An integer that may contain information about any error */
319 cfd5c0d6 meetecho
        void (* const destroy_session)(janus_plugin_session *handle, int *error);
320 667b2005 meetecho
        /*! \brief Method to get plugin-specific info of a session/handle
321
         *  \note This was added in version 0.0.7 of the gateway. Janus assumes
322
         * the string is always allocated, so don't return constants here
323
         * @param[in] handle The plugin/gateway session used for this peer
324 dd11fa0a Lorenzo Miniero
         * @returns A json_t object with the requested info */
325
        json_t *(* const query_session)(janus_plugin_session *handle);
326 be35facb meetecho
327
};
328
329
/*! \brief Callbacks to contact the gateway */
330
struct janus_callbacks {
331
        /*! \brief Callback to push events/messages to a peer
332 dd11fa0a Lorenzo Miniero
         * @note The Janus core increases the references to both the message and jsep
333
         * json_t objects. This means that you'll have to decrease your own
334
         * reference yourself with a \c json_decref after calling push_event.
335 be35facb meetecho
         * @param[in] handle The plugin/gateway session used for this peer
336
         * @param[in] plugin The plugin instance that is sending the message/event
337
         * @param[in] transaction The transaction identifier this message refers to
338 dd11fa0a Lorenzo Miniero
         * @param[in] message The json_t object containing the JSON message
339
         * @param[in] jsep The json_t object containing the JSEP type and the SDP attached to the message/event, if any (offer/answer) */
340
        int (* const push_event)(janus_plugin_session *handle, janus_plugin *plugin, const char *transaction, json_t *message, json_t *jsep);
341 be35facb meetecho
342
        /*! \brief Callback to relay RTP packets to a peer
343
         * @param[in] handle The plugin/gateway session used for this peer
344
         * @param[in] video Whether this is an audio or a video frame
345
         * @param[in] buf The packet data (buffer)
346
         * @param[in] len The buffer lenght */
347 cfd5c0d6 meetecho
        void (* const relay_rtp)(janus_plugin_session *handle, int video, char *buf, int len);
348 be35facb meetecho
        /*! \brief Callback to relay RTCP messages to a peer
349
         * @param[in] handle The plugin/gateway session that will be used for this peer
350
         * @param[in] video Whether this is related to an audio or a video stream
351
         * @param[in] buf The message data (buffer)
352
         * @param[in] len The buffer lenght */
353 cfd5c0d6 meetecho
        void (* const relay_rtcp)(janus_plugin_session *handle, int video, char *buf, int len);
354 a3d13e20 meetecho
        /*! \brief Callback to relay SCTP/DataChannel messages to a peer
355
         * @param[in] handle The plugin/gateway session that will be used for this peer
356
         * @param[in] buf The message data (buffer)
357
         * @param[in] len The buffer lenght */
358
        void (* const relay_data)(janus_plugin_session *handle, char *buf, int len);
359 be35facb meetecho
360 af40a682 meetecho
        /*! \brief Callback to ask the core to close a WebRTC PeerConnection
361
         * \note A call to this method will result in the core invoking the hangup_media
362
         * callback on this plugin when done
363
         * @param[in] handle The plugin/gateway session that the PeerConnection is related to */
364
        void (* const close_pc)(janus_plugin_session *handle);
365
        /*! \brief Callback to ask the core to get rid of a plugin/gateway session
366
         * \note A call to this method will result in the core invoking the destroy_session
367
         * callback on this plugin when done
368
         * @param[in] handle The plugin/gateway session to get rid of */
369
        void (* const end_session)(janus_plugin_session *handle);
370
371 1d31e31f Lorenzo Miniero
        /*! \brief Callback to check whether the event handlers mechanism is enabled
372
         * @returns TRUE if it is, FALSE if it isn't (which means notify_event should NOT be called) */
373
        gboolean (* const events_is_enabled)(void);
374 6c173b76 Lorenzo Miniero
        /*! \brief Callback to notify an event to the registered and subscribed event handlers
375
         * \note Don't unref the event object, the core will do that for you
376 c734a91a Lorenzo Miniero
         * @param[in] plugin The plugin originating the event
377
         * @param[in] handle The plugin/gateway session originating the event, if any
378 6c173b76 Lorenzo Miniero
         * @param[in] event The event to notify as a Jansson json_t object */
379 c734a91a Lorenzo Miniero
        void (* const notify_event)(janus_plugin *plugin, janus_plugin_session *handle, json_t *event);
380 6c173b76 Lorenzo Miniero
381 be35facb meetecho
};
382
383
/*! \brief The hook that plugins need to implement to be created from the gateway */
384
typedef janus_plugin* create_p(void);
385
386
387 292d035f meetecho
/** @name Janus plugin results
388
 * @brief When a client sends a message to a plugin (e.g., a request or a
389
 * command) this is notified to the plugin through a handle_message()
390
 * callback. The plugin can then either handle the request immediately
391
 * and provide a response (synchronous approach) or decide to queue it
392
 * and process it later (asynchronous approach). In both cases the plugin
393
 * must return a janus_plugin_result instance to the core, that will allow
394
 * the client to: 1. know whether a response is immediately available or
395
 * it will be later on through notifications, and 2. what the actual content
396
 * of the result might be. Of course, notifications related to the
397
 * transaction may occur later on even for synchronous requests, if the
398
 * plugin was implemented with use cases that envisage this approach.
399
 * @note An error may be returned as well, but this would cause a core-level
400
 * error to be returned to the client. If you want to provide indications
401
 * about a failed operation for application-level reason, the correct
402
 * approach is to return a success with a plugin-specific payload describing
403
 * the error.
404
 */
405
///@{
406
/*! \brief Result types */
407
typedef enum janus_plugin_result_type {
408
        /*! \brief A severe error happened (not an application level error) */
409
        JANUS_PLUGIN_ERROR = -1,
410
        /*! \brief The request was correctly handled and a response is provided (synchronous) */
411
        JANUS_PLUGIN_OK,
412
        /*! \brief The request was correctly handled and notifications will follow with more info (asynchronous) */
413
        JANUS_PLUGIN_OK_WAIT,
414
} janus_plugin_result_type;
415
416
/*! \brief Janus plugin result */
417
struct janus_plugin_result {
418
        /*! \brief Result type */
419
        janus_plugin_result_type type;
420 dd11fa0a Lorenzo Miniero
        /*! \brief Text associated with this plugin result.
421
         * @note This is ONLY used for JANUS_PLUGIN_OK_WAIT (to provide hints on
422
         * why a request is being handled asynchronously) and JANUS_PLUGIN_ERROR
423
         * (to provide a reason for the error). It is ignored for JANUS_PLUGIN_OK.
424
         * Besides, it is NOT freed when destroying the janus_plugin_result instance,
425
         * so if you allocated a string for that, you'll have to free it yourself. */
426
        const char *text;
427 292d035f meetecho
        /*! \brief Result content
428 dd11fa0a Lorenzo Miniero
         * @note This is ONLY used for JANUS_PLUGIN_OK, and is ignored otherwise.
429
         * It MUST be a valid JSON payload (even when returning application
430
         * level errors). Its reference is decremented automatically when destroying
431
         * the janus_plugin_result instance, so if your plugin wants to re-use the
432
         * same object for multiple responses, you jave to \c json_incref the object before
433
         * passing it to the core, and \c json_decref it when you're done with it. */
434
        json_t *content;
435 292d035f meetecho
};
436
437
/*! \brief Helper to quickly create a janus_plugin_result instance
438
 * @param[in] type The type of result
439 dd11fa0a Lorenzo Miniero
 * @param[in] text String to add to the result (for JANUS_PLUGIN_OK_WAIT or JANUS_PLUGIN_ERROR), if any
440
 * @param[in] content The json_t object with the content of the result, if any
441 292d035f meetecho
 * @returns A valid janus_plugin_result instance, if successful, or NULL otherwise */
442 dd11fa0a Lorenzo Miniero
janus_plugin_result *janus_plugin_result_new(janus_plugin_result_type type, const char *text, json_t *content);
443 292d035f meetecho
444
/*! \brief Helper to quickly destroy a janus_plugin_result instance
445
 * @param[in] result The janus_plugin_result instance to destroy
446
 * @returns A valid janus_plugin_result instance, if successful, or NULL otherwise */
447
void janus_plugin_result_destroy(janus_plugin_result *result);
448
///@}
449
450
451 be35facb meetecho
#endif