Statistics
| Branch: | Revision:

janus-gateway / ice.h @ 0351dafc

History | View | Annotate | Download (30.7 KB)

1
/*! \file    ice.h
2
 * \author   Lorenzo Miniero <lorenzo@meetecho.com>
3
 * \copyright GNU General Public License v3
4
 * \brief    ICE/STUN/TURN processing (headers)
5
 * \details  Implementation (based on libnice) of the ICE process. The
6
 * code handles the whole ICE process, from the gathering of candidates
7
 * to the final setup of a virtual channel RTP and RTCP can be transported
8
 * on. Incoming RTP and RTCP packets from peers are relayed to the associated
9
 * plugins by means of the incoming_rtp and incoming_rtcp callbacks. Packets
10
 * to be sent to peers are relayed by peers invoking the relay_rtp and
11
 * relay_rtcp gateway callbacks instead. 
12
 * 
13
 * \ingroup protocols
14
 * \ref protocols
15
 */
16
 
17
#ifndef _JANUS_ICE_H
18
#define _JANUS_ICE_H
19

    
20
#include <glib.h>
21
#include <agent.h>
22

    
23
#include "sdp.h"
24
#include "dtls.h"
25
#include "sctp.h"
26
#include "rtcp.h"
27
#include "utils.h"
28
#include "plugins/plugin.h"
29

    
30

    
31
/*! \brief ICE stuff initialization
32
 * @param[in] ice_lite Whether the ICE Lite mode should be enabled or not
33
 * @param[in] ice_tcp Whether ICE-TCP support should be enabled or not (only libnice >= 0.1.8, currently broken)
34
 * @param[in] ipv6 Whether IPv6 candidates must be negotiated or not
35
 * @param[in] rtp_min_port Minimum port to use for RTP/RTCP, if a range is to be used
36
 * @param[in] rtp_max_port Maximum port to use for RTP/RTCP, if a range is to be used */
37
void janus_ice_init(gboolean ice_lite, gboolean ice_tcp, gboolean ipv6, uint16_t rtp_min_port, uint16_t rtp_max_port);
38
/*! \brief ICE stuff de-initialization */
39
void janus_ice_deinit(void);
40
/*! \brief Method to force Janus to use a STUN server when gathering candidates
41
 * @param[in] stun_server STUN server address to use
42
 * @param[in] stun_port STUN port to use
43
 * @returns 0 in case of success, a negative integer on errors */
44
int janus_ice_set_stun_server(gchar *stun_server, uint16_t stun_port);
45
/*! \brief Method to force Janus to use a TURN server when gathering candidates
46
 * @param[in] turn_server TURN server address to use
47
 * @param[in] turn_port TURN port to use
48
 * @param[in] turn_type Relay type (udp, tcp or tls)
49
 * @param[in] turn_user TURN username, if needed
50
 * @param[in] turn_pwd TURN password, if needed
51
 * @returns 0 in case of success, a negative integer on errors */
52
int janus_ice_set_turn_server(gchar *turn_server, uint16_t turn_port, gchar *turn_type, gchar *turn_user, gchar *turn_pwd);
53
/*! \brief Method to force Janus to contact a TURN REST API server to get a TURN service to use when gathering candidates.
54
 * The TURN REST API takes precedence over any static credential passed via janus_ice_set_turn_server
55
 * @note Requires libcurl to be available, and a working TURN REST API backend (see turnrest.h)
56
 * @param[in] api_server TURN REST API backend (NULL to disable the API)
57
 * @param[in] api_key API key to use, if required
58
 * @param[in] api_method HTTP method to use (POST by default)
59
 * @returns 0 in case of success, a negative integer on errors */
60
int janus_ice_set_turn_rest_api(gchar *api_server, gchar *api_key, gchar *api_method);
61
/*! \brief Method to get the STUN server IP address
62
 * @returns The currently used STUN server IP address, if available, or NULL if not */
63
char *janus_ice_get_stun_server(void);
64
/*! \brief Method to get the STUN server port
65
 * @returns The currently used STUN server port, if available, or 0 if not */
66
uint16_t janus_ice_get_stun_port(void);
67
/*! \brief Method to get the TURN server IP address
68
 * @returns The currently used TURN server IP address, if available, or NULL if not */
69
char *janus_ice_get_turn_server(void);
70
/*! \brief Method to get the TURN server port
71
 * @returns The currently used TURN server port, if available, or 0 if not */
72
uint16_t janus_ice_get_turn_port(void);
73
/*! \brief Method to get the specified TURN REST API backend, if any
74
 * @returns The currently specified  TURN REST API backend, if available, or NULL if not */
75
char *janus_ice_get_turn_rest_api(void);
76
/*! \brief Helper method to force Janus to overwrite all host candidates with the public IP */
77
void janus_ice_enable_nat_1_1(void);
78
/*! \brief Method to add an interface/IP to the enforce list for ICE (that is, only gather candidates from these and ignore the others)
79
 * \note This method is especially useful to speed up the ICE gathering process on the gateway: in fact,
80
 * if you know in advance which interface must be used (e.g., the main interface connected to the internet),
81
 * adding it to the enforce list will prevent libnice from gathering candidates from other interfaces.
82
 * If you're interested in excluding interfaces explicitly, instead, check janus_ice_ignore_interface.
83
 * @param[in] ip Interface/IP to enforce (e.g., 192.168. or eth0) */
84
void janus_ice_enforce_interface(const char *ip);
85
/*! \brief Method to check whether an interface is currently in the enforce list for ICE (that is, won't have candidates)
86
 * @param[in] ip Interface/IP to check (e.g., 192.168.244.1 or eth1)
87
 * @returns true if the interface/IP is in the enforce list, false otherwise */
88
gboolean janus_ice_is_enforced(const char *ip);
89
/*! \brief Method to add an interface/IP to the ignore list for ICE (that is, don't gather candidates)
90
 * \note This method is especially useful to speed up the ICE gathering process on the gateway: in fact,
91
 * if you know in advance an interface is not going to be used (e.g., one of those created by VMware),
92
 * adding it to the ignore list will prevent libnice from gathering a candidate for it.
93
 * Unlike the enforce list, the ignore list also accepts IP addresses, partial or complete.
94
 * If you're interested in only using specific interfaces, instead, check janus_ice_enforce_interface.
95
 * @param[in] ip Interface/IP to ignore (e.g., 192.168. or eth1) */
96
void janus_ice_ignore_interface(const char *ip);
97
/*! \brief Method to check whether an interface/IP is currently in the ignore list for ICE (that is, won't have candidates)
98
 * @param[in] ip Interface/IP to check (e.g., 192.168.244.1 or eth1)
99
 * @returns true if the interface/IP is in the ignore list, false otherwise */
100
gboolean janus_ice_is_ignored(const char *ip);
101
/*! \brief Method to check whether ICE Lite mode is enabled or not (still WIP)
102
 * @returns true if ICE-TCP support is enabled/supported, false otherwise */
103
gboolean janus_ice_is_ice_lite_enabled(void);
104
/*! \brief Method to check whether ICE-TCP support is enabled/supported or not (still WIP)
105
 * @returns true if ICE-TCP support is enabled/supported, false otherwise */
106
gboolean janus_ice_is_ice_tcp_enabled(void);
107
/*! \brief Method to check whether IPv6 candidates are enabled/supported or not (still WIP)
108
 * @returns true if IPv6 candidates are enabled/supported, false otherwise */
109
gboolean janus_ice_is_ipv6_enabled(void);
110
/*! \brief Method to check whether BUNDLE support is forced or not
111
 * @returns true if BUNDLE is mandatory, false otherwise */
112
gboolean janus_ice_is_bundle_forced(void);
113
/*! \brief Method to set the BUNDLE support mode (true means mandatory, false means optional)
114
 * @param forced whether BUNDLE support must be forced or not (default is false) */
115
void janus_ice_force_bundle(gboolean forced);
116
/*! \brief Method to check whether rtcp-mux support is forced or not
117
 * @returns true if rtcp-mux is mandatory, false otherwise */
118
gboolean janus_ice_is_rtcpmux_forced(void);
119
/*! \brief Method to set the rtcp-mux support mode (true means mandatory, false means optional)
120
 * @param forced whether rtcp-mux support must be forced or not (default is false) */
121
void janus_ice_force_rtcpmux(gboolean forced);
122
/*! \brief Method to get the port that has been assigned for the RTCP component blackhole in case of rtcp-mux
123
 * @returns The blackhole port */
124
gint janus_ice_get_rtcpmux_blackhole_port(void);
125
/*! \brief Method to modify the max NACK value (i.e., the number of packets per handle to store for retransmissions)
126
 * @param[in] mnq The new max NACK value */
127
void janus_set_max_nack_queue(uint mnq);
128
/*! \brief Method to get the current max NACK value (i.e., the number of packets per handle to store for retransmissions)
129
 * @returns The current max NACK value */
130
uint janus_get_max_nack_queue(void);
131
/*! \brief Method to check whether libnice debugging has been enabled (http://nice.freedesktop.org/libnice/libnice-Debug-messages.html)
132
 * @returns True if libnice debugging is enabled, FALSE otherwise */
133
gboolean janus_ice_is_ice_debugging_enabled(void);
134
/*! \brief Method to enable libnice debugging (http://nice.freedesktop.org/libnice/libnice-Debug-messages.html) */
135
void janus_ice_debugging_enable(void);
136
/*! \brief Method to disable libnice debugging (the default) */
137
void janus_ice_debugging_disable(void);
138

    
139

    
140
/*! \brief Helper method to get a string representation of a libnice ICE state
141
 * @param[in] state The libnice ICE state
142
 * @returns A string representation of the libnice ICE state */
143
const gchar *janus_get_ice_state_name(gint state);
144

    
145

    
146
/*! \brief Janus ICE handle/session */
147
typedef struct janus_ice_handle janus_ice_handle;
148
/*! \brief Janus ICE stream */
149
typedef struct janus_ice_stream janus_ice_stream;
150
/*! \brief Janus ICE component */
151
typedef struct janus_ice_component janus_ice_component;
152
/*! \brief Helper to handle pending trickle candidates (e.g., when we're still waiting for an offer) */
153
typedef struct janus_ice_trickle janus_ice_trickle;
154

    
155

    
156
#define JANUS_ICE_HANDLE_WEBRTC_PROCESSING_OFFER        (1 << 0)
157
#define JANUS_ICE_HANDLE_WEBRTC_START                                (1 << 1)
158
#define JANUS_ICE_HANDLE_WEBRTC_READY                                (1 << 2)
159
#define JANUS_ICE_HANDLE_WEBRTC_STOP                                (1 << 3)
160
#define JANUS_ICE_HANDLE_WEBRTC_ALERT                                (1 << 4)
161
#define JANUS_ICE_HANDLE_WEBRTC_BUNDLE                                (1 << 5)
162
#define JANUS_ICE_HANDLE_WEBRTC_RTCPMUX                                (1 << 6)
163
#define JANUS_ICE_HANDLE_WEBRTC_TRICKLE                                (1 << 7)
164
#define JANUS_ICE_HANDLE_WEBRTC_ALL_TRICKLES                (1 << 8)
165
#define JANUS_ICE_HANDLE_WEBRTC_TRICKLE_SYNCED                (1 << 9)
166
#define JANUS_ICE_HANDLE_WEBRTC_DATA_CHANNELS                (1 << 10)
167
#define JANUS_ICE_HANDLE_WEBRTC_PLAN_B                                (1 << 11)
168
#define JANUS_ICE_HANDLE_WEBRTC_CLEANING                        (1 << 12)
169
#define JANUS_ICE_HANDLE_WEBRTC_HAS_AUDIO                        (1 << 13)
170
#define JANUS_ICE_HANDLE_WEBRTC_HAS_VIDEO                        (1 << 14)
171
#define JANUS_ICE_HANDLE_WEBRTC_GOT_OFFER                        (1 << 15)
172
#define JANUS_ICE_HANDLE_WEBRTC_GOT_ANSWER                        (1 << 16)
173

    
174

    
175
/*! \brief Janus media statistics
176
 * \note To improve with more stuff */
177
typedef struct janus_ice_stats {
178
        /*! \brief Audio packets sent or received */
179
        guint32 audio_packets;
180
        /*! \brief Audio bytes sent or received */
181
        guint64 audio_bytes;
182
        /*! \brief Audio bytes sent or received in the last second */
183
        GList *audio_bytes_lastsec;
184
        /*! \brief Whether or not we notified about audio lastsec issues already */
185
        gboolean audio_notified_lastsec;
186
        /*! \brief Number of audio NACKs sent or received */
187
        guint32 audio_nacks;
188
        /*! \brief Video packets sent or received */
189
        guint32 video_packets;
190
        /*! \brief Video bytes sent or received */
191
        guint64 video_bytes;
192
        /*! \brief Video bytes sent or received in the last second */
193
        GList *video_bytes_lastsec;
194
        /*! \brief Whether or not we notified about video lastsec issues already */
195
        gboolean video_notified_lastsec;
196
        /*! \brief Number of video NACKs sent or received */
197
        guint32 video_nacks;
198
        /*! \brief Data packets sent or received */
199
        guint32 data_packets;
200
        /*! \brief Data bytes sent or received */
201
        guint64 data_bytes;
202
        /*! \brief Last time the slow_link callback (of the plugin) was called */
203
        gint64 last_slowlink_time;
204
        /*! \brief Start time of recent NACKs (for slow_link) */
205
        gint64 sl_nack_period_ts;
206
        /*! \brief Count of recent NACKs (for slow_link) */
207
        guint sl_nack_recent_cnt;
208
} janus_ice_stats;
209

    
210
/*! \brief Janus media statistics: received packet info
211
 * \note To improve with more stuff */
212
typedef struct janus_ice_stats_item {
213
        /*! \brief Bytes sent or received */
214
        guint64 bytes;
215
        /*! \brief Time at which this happened */
216
        gint64 when;
217
} janus_ice_stats_item;
218

    
219
/*! \brief Quick helper method to reset stats
220
 * @param stats The janus_ice_stats instance to reset */
221
void janus_ice_stats_reset(janus_ice_stats *stats);
222

    
223
/*! \brief Quick helper method to notify a WebRTC hangup through the Janus API
224
 * @param handle The janus_ice_handle instance this event refers to
225
 * @param reason A description of why this happened */
226
void janus_ice_notify_hangup(janus_ice_handle *handle, const char *reason);
227

    
228

    
229
/*! \brief Quick helper method to check if a plugin session associated with a Janus handle is still valid
230
 * @param plugin_session The janus_plugin_session instance to validate
231
 * @returns true if the plugin session is valid, false otherwise */
232
gboolean janus_plugin_session_is_alive(janus_plugin_session *plugin_session);
233

    
234

    
235
/*! \brief A helper struct for determining when to send NACKs */
236
typedef struct janus_seq_info {
237
        gint64 ts;
238
        guint16 seq;
239
        guint16 state;
240
        struct janus_seq_info *next;
241
        struct janus_seq_info *prev;
242
} seq_info_t;
243
enum {
244
        SEQ_MISSING,
245
        SEQ_NACKED,
246
        SEQ_GIVEUP,
247
        SEQ_RECVED
248
};
249

    
250

    
251
/*! \brief Janus ICE handle */
252
struct janus_ice_handle {
253
        /*! \brief Opaque pointer to the gateway/peer session */
254
        void *session;
255
        /*! \brief Handle identifier, guaranteed to be non-zero */
256
        guint64 handle_id;
257
        /*! \brief Monotonic time of when the handle has been created */
258
        gint64 created;
259
        /*! \brief Opaque application (plugin) pointer */
260
        void *app;
261
        /*! \brief Opaque gateway/plugin session pointer */
262
        janus_plugin_session *app_handle;
263
        /*! \brief Mask of WebRTC-related flags for this handle */
264
        janus_flags webrtc_flags;
265
        /*! \brief Number of gathered candidates */
266
        gint cdone;
267
        /*! \brief GLib context for libnice */
268
        GMainContext *icectx;
269
        /*! \brief GLib loop for libnice */
270
        GMainLoop *iceloop;
271
        /*! \brief GLib thread for libnice */
272
        GThread *icethread;
273
        /*! \brief libnice ICE agent */
274
        NiceAgent *agent;
275
        /*! \brief Monotonic time of when the ICE agent has been created */
276
        gint64 agent_created;
277
        /*! \brief ICE role (controlling or controlled) */
278
        gboolean controlling;
279
        /*! \brief libnice ICE audio ID */
280
        guint audio_id;
281
        /*! \brief libnice ICE video ID */
282
        guint video_id;
283
        /*! \brief libnice ICE DataChannels ID */
284
        guint data_id;
285
        /*! \brief Audio mid (media ID) */
286
        gchar *audio_mid;
287
        /*! \brief Video mid (media ID) */
288
        gchar *video_mid;
289
        /*! \brief Data channel mid (media ID) */
290
        gchar *data_mid;
291
        /*! \brief Number of streams */
292
        gint streams_num;
293
        /*! \brief GLib hash table of streams (IDs are the keys) */
294
        GHashTable *streams;
295
        /*! \brief Audio stream */
296
        janus_ice_stream *audio_stream;
297
        /*! \brief Video stream */
298
        janus_ice_stream *video_stream;
299
        /*! \brief SCTP/DataChannel stream */
300
        janus_ice_stream *data_stream;
301
        /*! \brief RTP profile set by caller (so that we can match it) */
302
        gchar *rtp_profile;
303
        /*! \brief SDP generated locally (just for debugging purposes) */
304
        gchar *local_sdp;
305
        /*! \brief SDP received by the peer (just for debugging purposes) */
306
        gchar *remote_sdp;
307
        /*! \brief List of pending trickle candidates (those we received before getting the JSEP offer) */
308
        GList *pending_trickles;
309
        /*! \brief Queue of outgoing packets to send */
310
        GAsyncQueue *queued_packets;
311
        /*! \brief GLib thread for sending outgoing packets */
312
        GThread *send_thread;
313
        /*! \brief Atomic flag to make sure we only create the thread once */
314
        volatile gint send_thread_created;
315
        /*! \brief Mutex to lock/unlock the ICE session */
316
        janus_mutex mutex;
317
};
318

    
319
/*! \brief Janus ICE stream */
320
struct janus_ice_stream {
321
        /*! \brief Janus ICE handle this stream belongs to */
322
        janus_ice_handle *handle;
323
        /*! \brief libnice ICE stream ID */
324
        guint stream_id;
325
        /*! \brief Whether this stream is ready to be used */
326
        gint cdone:1;
327
        /*! \brief Whether the medium associated with this stream has been disabled (e.g., m=audio 0) */
328
        guint disabled;
329
        /*! \brief Audio SSRC of the gateway for this stream (may be bundled) */
330
        guint32 audio_ssrc;
331
        /*! \brief Video SSRC of the gateway for this stream (may be bundled) */
332
        guint32 video_ssrc;
333
        /*! \brief Audio SSRC of the peer for this stream (may be bundled) */
334
        guint32 audio_ssrc_peer;
335
        /*! \brief Video SSRC of the peer for this stream (may be bundled) */
336
        guint32 video_ssrc_peer;
337
        /*! \brief Video retransmissions SSRC of the peer for this stream (may be bundled) */
338
        guint32 video_ssrc_peer_rtx;
339
        /*! \brief List of payload types we can expect for audio */
340
        GList *audio_payload_types;
341
        /*! \brief List of payload types we can expect for video */
342
        GList *video_payload_types;
343
        /*! \brief RTP payload type of this stream */
344
        gint payload_type;
345
        /*! \brief RTCP context for the audio stream (may be bundled) */
346
        rtcp_context *audio_rtcp_ctx;
347
        /*! \brief RTCP context for the video stream (may be bundled) */
348
        rtcp_context *video_rtcp_ctx;
349
        /*! \brief Last sent audio RTP timestamp */
350
        guint32 audio_last_ts;
351
        /*! \brief Last sent video RTP timestamp */
352
        guint32 video_last_ts;
353
        /*! \brief DTLS role of the gateway for this stream */
354
        janus_dtls_role dtls_role;
355
        /*! \brief Hashing algorhitm used by the peer for the DTLS certificate (e.g., "SHA-256") */
356
        gchar *remote_hashing;
357
        /*! \brief Hashed fingerprint of the peer's certificate, as parsed in SDP */
358
        gchar *remote_fingerprint;
359
        /*! \brief The ICE username for this stream */
360
        gchar *ruser;
361
        /*! \brief The ICE password for this stream */
362
        gchar *rpass;
363
        /*! \brief GLib hash table of components (IDs are the keys) */
364
        GHashTable *components;
365
        /*! \brief RTP (or SCTP, if this is the data stream) component */
366
        janus_ice_component *rtp_component;
367
        /*! \brief RTCP component */
368
        janus_ice_component *rtcp_component;
369
        /*! \brief Helper flag to avoid flooding the console with the same error all over again */
370
        gint noerrorlog:1;
371
        /*! \brief Mutex to lock/unlock this stream */
372
        janus_mutex mutex;
373
};
374

    
375
#define LAST_SEQS_MAX_LEN 160
376
/*! \brief Janus ICE component */
377
struct janus_ice_component {
378
        /*! \brief Janus ICE stream this component belongs to */
379
        janus_ice_stream *stream;
380
        /*! \brief libnice ICE stream ID */
381
        guint stream_id;
382
        /*! \brief libnice ICE component ID */
383
        guint component_id;
384
        /*! \brief libnice ICE component state */
385
        guint state;
386
        /*! \brief Monotonic time of when this component has successfully connected */
387
        gint64 component_connected;
388
        /*! \brief GLib list of libnice remote candidates for this component */
389
        GSList *candidates;
390
        /*! \brief GLib list of local candidates for this component (summary) */
391
        GSList *local_candidates;
392
        /*! \brief GLib list of remote candidates for this component (summary) */
393
        GSList *remote_candidates;
394
        /*! \brief String representation of the selected pair as notified by libnice (foundations) */
395
        gchar *selected_pair;
396
        /*! \brief Whether the setup of remote candidates for this component has started or not */
397
        gboolean process_started;
398
        /*! \brief Re-transmission timer for DTLS */
399
        GSource *source;
400
        /*! \brief DTLS-SRTP stack */
401
        janus_dtls_srtp *dtls;
402
        /*! \brief List of previously sent janus_rtp_packet RTP packets, in case we receive NACKs */
403
        GList *retransmit_buffer;
404
        /*! \brief Last time a log message about sending retransmits was printed */
405
        gint64 retransmit_log_ts;
406
        /*! \brief Number of retransmitted packets since last log message */
407
        guint retransmit_recent_cnt;
408
        /*! \brief Last time a log message about sending NACKs was printed */
409
        gint64 nack_sent_log_ts;
410
        /*! \brief Number of NACKs sent since last log message */
411
        guint nack_sent_recent_cnt;
412
        /*! \brief List of recently received audio sequence numbers (as a support to NACK generation) */
413
        seq_info_t *last_seqs_audio;
414
        /*! \brief List of recently received video sequence numbers (as a support to NACK generation) */
415
        seq_info_t *last_seqs_video;
416
        /*! \brief Stats for incoming data (audio/video/data) */
417
        janus_ice_stats in_stats;
418
        /*! \brief Stats for outgoing data (audio/video/data) */
419
        janus_ice_stats out_stats;
420
        /*! \brief Helper flag to avoid flooding the console with the same error all over again */
421
        gint noerrorlog:1;
422
        /*! \brief Mutex to lock/unlock this component */
423
        janus_mutex mutex;
424
};
425

    
426
/*! \brief Helper to handle pending trickle candidates (e.g., when we're still waiting for an offer) */
427
struct janus_ice_trickle {
428
        /*! \brief Janus ICE handle this trickle candidate belongs to */
429
        janus_ice_handle *handle;
430
        /*! \brief Monotonic time of when this trickle candidate has been received */
431
        gint64 received;
432
        /*! \brief Janus API transaction ID of the original trickle request */
433
        char *transaction;
434
        /*! \brief JSON object of the trickle candidate(s) */
435
        json_t *candidate;
436
};
437

    
438
/** @name Janus ICE trickle candidates methods
439
 */
440
///@{
441
/*! \brief Helper method to allocate a janus_ice_trickle instance
442
 * @param[in] handle The Janus ICE handle this trickle candidate belongs to
443
 * @param[in] transaction The Janus API ID of the original trickle request
444
 * @param[in] candidate The trickle candidate, as a Jansson object
445
 * @returns a pointer to the new instance, if successful, NULL otherwise */
446
janus_ice_trickle *janus_ice_trickle_new(janus_ice_handle *handle, const char *transaction, json_t *candidate);
447
/*! \brief Helper method to parse trickle candidates
448
 * @param[in] handle The Janus ICE handle this candidate belongs to
449
 * @param[in] candidate The trickle candidate to parse, as a Jansson object
450
 * @param[in,out] error Error string describing the failure, if any
451
 * @returns 0 in case of success, any code from apierror.h in case of failure */
452
gint janus_ice_trickle_parse(janus_ice_handle *handle, json_t *candidate, const char **error);
453
/*! \brief Helper method to destroy a janus_ice_trickle instance
454
 * @param[in] trickle The janus_ice_trickle instance to destroy */
455
void janus_ice_trickle_destroy(janus_ice_trickle *trickle);
456
///@}
457

    
458

    
459
/** @name Janus ICE handle methods
460
 */
461
///@{
462
/*! \brief Method to create a new Janus ICE handle
463
 * @param[in] gateway_session The gateway/peer session this ICE handle will belong to
464
 * @returns The created Janus ICE handle if successful, NULL otherwise */
465
janus_ice_handle *janus_ice_handle_create(void *gateway_session);
466
/*! \brief Method to find an existing Janus ICE handle from its ID
467
 * @param[in] gateway_session The gateway/peer session this ICE handle belongs to
468
 * @param[in] handle_id The Janus ICE handle ID
469
 * @returns The created Janus ICE handle if successful, NULL otherwise */
470
janus_ice_handle *janus_ice_handle_find(void *gateway_session, guint64 handle_id);
471
/*! \brief Method to attach a Janus ICE handle to a plugin
472
 * \details This method is very important, as it allows plugins to send/receive media (RTP/RTCP) to/from a WebRTC peer.
473
 * @param[in] gateway_session The gateway/peer session this ICE handle belongs to
474
 * @param[in] handle_id The Janus ICE handle ID
475
 * @param[in] plugin The plugin the ICE handle needs to be attached to
476
 * @returns 0 in case of success, a negative integer otherwise */
477
gint janus_ice_handle_attach_plugin(void *gateway_session, guint64 handle_id, janus_plugin *plugin);
478
/*! \brief Method to destroy a Janus ICE handle
479
 * @param[in] gateway_session The gateway/peer session this ICE handle belongs to
480
 * @param[in] handle_id The Janus ICE handle ID to destroy
481
 * @returns 0 in case of success, a negative integer otherwise */
482
gint janus_ice_handle_destroy(void *gateway_session, guint64 handle_id);
483
/*! \brief Method to actually free the resources allocated by a Janus ICE handle
484
 * @param[in] handle The Janus ICE handle instance to free */
485
void janus_ice_free(janus_ice_handle *handle);
486
/*! \brief Method to only hangup (e.g., DTLS alert) the WebRTC PeerConnection allocated by a Janus ICE handle
487
 * @param[in] handle The Janus ICE handle instance managing the WebRTC PeerConnection to hangup */
488
void janus_ice_webrtc_hangup(janus_ice_handle *handle);
489
/*! \brief Method to only free the WebRTC related resources allocated by a Janus ICE handle
490
 * @param[in] handle The Janus ICE handle instance managing the WebRTC resources to free */
491
void janus_ice_webrtc_free(janus_ice_handle *handle);
492
/*! \brief Method to only free resources related to a specific ICE stream allocated by a Janus ICE handle
493
 * @param[in] container The map containing the list of all streams for the handle
494
 * @param[in] stream The Janus ICE stream instance to free */
495
void janus_ice_stream_free(GHashTable *container, janus_ice_stream *stream);
496
/*! \brief Method to only free resources related to a specific ICE component allocated by a Janus ICE handle
497
 * @param[in] container The map containing the list of all components for the stream
498
 * @param[in] component The Janus ICE component instance to free */
499
void janus_ice_component_free(GHashTable *container, janus_ice_component *component);
500
///@}
501

    
502

    
503
/** @name Janus ICE handle callbacks
504
 */
505
///@{
506
/*! \brief libnice callback to notify when candidates have been gathered for an ICE agent
507
 * @param[in] agent The libnice agent for which the callback applies
508
 * @param[in] stream_id The stream ID for which the callback applies
509
 * @param[in] ice Opaque pointer to the Janus ICE handle associated with the libnice ICE agent */
510
void janus_ice_cb_candidate_gathering_done (NiceAgent *agent, guint stream_id, gpointer ice);
511
/*! \brief libnice callback to notify when the state of a component changes for an ICE agent
512
 * @param[in] agent The libnice agent for which the callback applies
513
 * @param[in] stream_id The stream ID for which the callback applies
514
 * @param[in] component_id The component ID for which the callback applies
515
 * @param[in] state New ICE state of the component
516
 * @param[in] ice Opaque pointer to the Janus ICE handle associated with the libnice ICE agent */
517
void janus_ice_cb_component_state_changed (NiceAgent *agent, guint stream_id, guint component_id, guint state, gpointer ice);
518
/*! \brief libnice callback to notify when a pair of candidates has been selected for an ICE agent
519
 * @param[in] agent The libnice agent for which the callback applies
520
 * @param[in] stream_id The stream ID for which the callback applies
521
 * @param[in] component_id The component ID for which the callback applies
522
 * @param[in] local Local candidate (or foundation)
523
 * @param[in] remote Remote candidate (or foundation)
524
 * @param[in] ice Opaque pointer to the Janus ICE handle associated with the libnice ICE agent */
525
#ifndef HAVE_LIBNICE_TCP
526
void janus_ice_cb_new_selected_pair (NiceAgent *agent, guint stream_id, guint component_id, gchar *local, gchar *remote, gpointer ice);
527
#else
528
void janus_ice_cb_new_selected_pair (NiceAgent *agent, guint stream_id, guint component_id, NiceCandidate *local, NiceCandidate *remote, gpointer ice);
529
#endif
530
/*! \brief libnice callback to notify when a new remote candidate has been discovered for an ICE agent
531
 * @param[in] agent The libnice agent for which the callback applies
532
 * @param[in] stream_id The stream ID for which the callback applies
533
 * @param[in] component_id The component ID for which the callback applies
534
 * @param[in] foundation Candidate (or foundation)
535
 * @param[in] ice Opaque pointer to the Janus ICE handle associated with the libnice ICE agent */
536
#ifndef HAVE_LIBNICE_TCP
537
void janus_ice_cb_new_remote_candidate (NiceAgent *agent, guint stream_id, guint component_id, gchar *candidate, gpointer ice);
538
#else
539
void janus_ice_cb_new_remote_candidate (NiceAgent *agent, NiceCandidate *candidate, gpointer ice);
540
#endif
541
/*! \brief libnice callback to notify when data has been received by an ICE agent
542
 * @param[in] agent The libnice agent for which the callback applies
543
 * @param[in] stream_id The stream ID for which the callback applies
544
 * @param[in] component_id The component ID for which the callback applies
545
 * @param[in] len Length of the data buffer
546
 * @param[in] buf Data buffer
547
 * @param[in] ice Opaque pointer to the Janus ICE handle associated with the libnice ICE agent */
548
void janus_ice_cb_nice_recv (NiceAgent *agent, guint stream_id, guint component_id, guint len, gchar *buf, gpointer ice);
549

    
550
/*! \brief Gateway RTP callback, called when a plugin has an RTP packet to send to a peer
551
 * @param[in] handle The Janus ICE handle associated with the peer
552
 * @param[in] video Whether this is an audio or a video frame
553
 * @param[in] buf The packet data (buffer)
554
 * @param[in] len The buffer lenght */
555
void janus_ice_relay_rtp(janus_ice_handle *handle, int video, char *buf, int len);
556
/*! \brief Gateway RTCP callback, called when a plugin has an RTCP message to send to a peer
557
 * @param[in] handle The Janus ICE handle associated with the peer
558
 * @param[in] video Whether this is related to an audio or a video stream
559
 * @param[in] buf The message data (buffer)
560
 * @param[in] len The buffer lenght */
561
void janus_ice_relay_rtcp(janus_ice_handle *handle, int video, char *buf, int len);
562
/*! \brief Gateway SCTP/DataChannel callback, called when a plugin has data to send to a peer
563
 * @param[in] handle The Janus ICE handle associated with the peer
564
 * @param[in] buf The message data (buffer)
565
 * @param[in] len The buffer lenght */
566
void janus_ice_relay_data(janus_ice_handle *handle, char *buf, int len);
567
/*! \brief Plugin SCTP/DataChannel callback, called by the SCTP stack when when there's data for a plugin
568
 * @param[in] handle The Janus ICE handle associated with the peer
569
 * @param[in] buffer The message data (buffer)
570
 * @param[in] length The buffer lenght */
571
void janus_ice_incoming_data(janus_ice_handle *handle, char *buffer, int length);
572
///@}
573

    
574

    
575
/** @name Janus ICE handle helpers
576
 */
577
///@{
578
/*! \brief Janus ICE handle thread */
579
void *janus_ice_thread(void *data);
580
/*! \brief Janus ICE thread for sending outgoing packets */
581
void *janus_ice_send_thread(void *data);
582
/*! \brief Method to locally set up the ICE candidates (initialization and gathering)
583
 * @param[in] handle The Janus ICE handle this method refers to
584
 * @param[in] offer Whether this is for an OFFER or an ANSWER
585
 * @param[in] audio Whether audio is enabled
586
 * @param[in] video Whether video is enabled
587
 * @param[in] data Whether SCTP data channels are enabled
588
 * @param[in] bundle Whether BUNDLE is supported or not
589
 * @param[in] rtcpmux Whether rtcp-mux is supported or not
590
 * @param[in] trickle Whether ICE trickling is supported or not
591
 * @returns 0 in case of success, a negative integer otherwise */
592
int janus_ice_setup_local(janus_ice_handle *handle, int offer, int audio, int video, int data, int bundle, int rtcpmux, int trickle);
593
/*! \brief Method to add local candidates to a janus_sdp SDP object representation
594
 * @param[in] handle The Janus ICE handle this method refers to
595
 * @param[in] mline The Janus SDP m-line object to add candidates to
596
 * @param[in] stream_id The stream ID of the candidate to add to the SDP
597
 * @param[in] component_id The component ID of the candidate to add to the SDP */
598
void janus_ice_candidates_to_sdp(janus_ice_handle *handle, janus_sdp_mline *mline, guint stream_id, guint component_id);
599
/*! \brief Method to handle remote candidates and start the connectivity checks
600
 * @param[in] handle The Janus ICE handle this method refers to
601
 * @param[in] stream_id The stream ID of the candidate to add to the SDP
602
 * @param[in] component_id The component ID of the candidate to add to the SDP */
603
void janus_ice_setup_remote_candidates(janus_ice_handle *handle, guint stream_id, guint component_id);
604
/*! \brief Callback to be notified when the DTLS handshake for a specific component has been completed
605
 * \details This method also decides when to notify attached plugins about the availability of a reliable PeerConnection
606
 * @param[in] handle The Janus ICE handle this callback refers to
607
 * @param[in] component The Janus ICE component that is now ready to be used */
608
void janus_ice_dtls_handshake_done(janus_ice_handle *handle, janus_ice_component *component);
609
///@}
610

    
611
#endif