ICE/STUN/TURN processing. More...

#include <ifaddrs.h>
#include <poll.h>
#include <net/if.h>
#include <sys/socket.h>
#include <sys/time.h>
#include <netdb.h>
#include <fcntl.h>
#include <stun/usages/bind.h>
#include <nice/debug.h>
#include "janus.h"
#include "debug.h"
#include "ice.h"
#include "turnrest.h"
#include "sdp.h"
#include "rtpsrtp.h"
#include "rtcp.h"
#include "apierror.h"
#include "ip-utils.h"
#include "events.h"

Include dependency graph for ice.c:

Data Structures
struct	janus_ice_static_event_loop

struct	janus_ice_queued_packet

struct	janus_ice_nacked_packet

struct	janus_ice_outgoing_traffic

Macros
#define	JANUS_ICE_PACKET_AUDIO 0

#define	JANUS_ICE_PACKET_VIDEO 1

#define	JANUS_ICE_PACKET_TEXT 2

#define	JANUS_ICE_PACKET_BINARY 3

#define	JANUS_ICE_PACKET_SCTP 4

#define	DEFAULT_NO_MEDIA_TIMER 1

#define	DEFAULT_SLOWLINK_THRESHOLD 0

#define	DEFAULT_TWCC_PERIOD 200

#define	DEFAULT_MIN_NACK_QUEUE 200

#define	DEFAULT_MAX_NACK_QUEUE 1000

#define	MAX_NACK_IGNORE 200000

#define	SEQ_MISSING_WAIT 12000 /* 12ms */

#define	SEQ_NACKED_WAIT 155000 /* 155ms */

Typedefs
typedef struct janus_ice_static_event_loop	janus_ice_static_event_loop

typedef struct janus_ice_queued_packet	janus_ice_queued_packet

typedef struct janus_ice_nacked_packet	janus_ice_nacked_packet

typedef struct janus_ice_outgoing_traffic	janus_ice_outgoing_traffic

Functions
char *	janus_ice_get_stun_server (void)
	Method to get the STUN server IP address.

uint16_t	janus_ice_get_stun_port (void)
	Method to get the STUN server port.

char *	janus_ice_get_turn_server (void)
	Method to get the TURN server IP address.

uint16_t	janus_ice_get_turn_port (void)
	Method to get the TURN server port.

char *	janus_ice_get_turn_rest_api (void)
	Method to get the specified TURN REST API backend, if any.

void	janus_ice_allow_force_relay (void)
	Method to enable applications to force Janus to use TURN.

gboolean	janus_ice_is_force_relay_allowed (void)
	Method to check whether applications are allowed to force Janus to use TURN.

gboolean	janus_ice_is_ice_lite_enabled (void)
	Method to check whether ICE Lite mode is enabled or not (still WIP)

gboolean	janus_ice_is_ice_tcp_enabled (void)
	Method to check whether ICE-TCP support is enabled/supported or not (still WIP)

gboolean	janus_ice_is_full_trickle_enabled (void)
	Method to check whether full-trickle support is enabled or not.

gboolean	janus_ice_is_mdns_enabled (void)
	Method to check whether mDNS resolution is enabled or not.

gboolean	janus_ice_is_ipv6_enabled (void)
	Method to check whether IPv6 candidates are enabled/supported or not.

gboolean	janus_ice_is_ipv6_linklocal_enabled (void)
	Method to check whether IPv6 link-local candidates will be gathered or not.

void	janus_ice_set_consent_freshness_enabled (gboolean enabled)
	Method to enable/disable consent freshness in PeerConnections.

gboolean	janus_ice_is_consent_freshness_enabled (void)
	Method to check whether consent fresnhess will be enabled in ICE.

void	janus_ice_set_keepalive_conncheck_enabled (gboolean enabled)
	Method to enable/disable connectivity checks as keepalives for PeerConnections.

gboolean	janus_ice_is_keepalive_conncheck_enabled (void)
	Method to check whether connectivity checks will be used as keepalives.

void	janus_ice_set_hangup_on_failed_enabled (gboolean enabled)
	Method to enable/disable immediate hangups of PeerConnectionss on ICE failures.

gboolean	janus_ice_is_hangup_on_failed_enabled (void)
	Method to check whether ICE failures will result in immediate hangups.

void	janus_enable_opaqueid_in_api (void)
	Method to enable opaque ID in Janus API responses/events.

gboolean	janus_is_opaqueid_in_api_enabled (void)
	Method to check whether opaque ID have to be added to Janus API responses/events.

int	janus_ice_get_static_event_loops (void)
	Method to return the number of static event loops, if enabled.

gboolean	janus_ice_is_loop_indication_allowed (void)
	Method to check whether loop indication via API is allowed.

void	janus_ice_set_static_event_loops (int loops, gboolean allow_api)
	Method to configure the static event loops mechanism at startup.

json_t *	janus_ice_static_event_loops_info (void)
	Helper method to return a summary of the static loops activity.

void	janus_ice_stop_static_event_loops (void)
	Method to stop all the static event loops, if enabled.

gboolean	janus_ice_is_ice_debugging_enabled (void)
	Method to check whether libnice debugging has been enabled (http://nice.freedesktop.org/libnice/libnice-Debug-messages.html)

void	janus_ice_debugging_enable (void)
	Method to enable libnice debugging (http://nice.freedesktop.org/libnice/libnice-Debug-messages.html)

void	janus_ice_debugging_disable (void)
	Method to disable libnice debugging (the default)

void	janus_ice_enable_nat_1_1 (gboolean kph)
	Helper method to force Janus to overwrite all host candidates with the public IP.

void	janus_ice_enforce_interface (const char *ip)
	Method to add an interface/IP to the enforce list for ICE (that is, only gather candidates from these and ignore the others)

gboolean	janus_ice_is_enforced (const char *ip)
	Method to check whether an interface is currently in the enforce list for ICE (that is, won't have candidates)

void	janus_ice_ignore_interface (const char *ip)
	Method to add an interface/IP to the ignore list for ICE (that is, don't gather candidates)

gboolean	janus_ice_is_ignored (const char *ip)
	Method to check whether an interface/IP is currently in the ignore list for ICE (that is, won't have candidates)

void	janus_ice_set_event_stats_period (int period)
	Method to modify the event handler statistics period (i.e., the number of seconds that should pass before Janus notifies event handlers about media statistics for a PeerConnection)

int	janus_ice_get_event_stats_period (void)
	Method to get the current event handler statistics period (see above)

void	janus_ice_event_set_combine_media_stats (gboolean combine_media_stats_to_one_event)
	Method to define whether the media stats shall be dispatched in one event (true) or in dedicated single events (false - default)

gboolean	janus_ice_event_get_combine_media_stats (void)
	Method to retrieve whether media statistic events shall be dispatched combined or in single events.

int	janus_ice_get_peerconnection_num (void)
	Method to get the number of active PeerConnection (for stats)

void	janus_set_no_media_timer (uint timer)
	Method to modify the no-media event timer (i.e., the number of seconds where no media arrives before Janus notifies this)

uint	janus_get_no_media_timer (void)
	Method to get the current no-media event timer (see above)

void	janus_set_slowlink_threshold (uint packets)
	Method to modify the slowlink-threshold property (i.e., the number of lost packets per seconds that should trigger a slow-link event)

uint	janus_get_slowlink_threshold (void)
	Method to get the current slowlink-threshold value (see above)

void	janus_set_twcc_period (uint period)
	Method to modify the TWCC feedback period (i.e., how often TWCC feedback is sent back to media senders)

uint	janus_get_twcc_period (void)
	Method to get the current TWCC period (see above)

void	janus_set_dscp (int dscp)
	Method to modify the DSCP value to set, which is disabled by default.

int	janus_get_dscp (void)
	Method to get the current DSCP value (see above)

void	janus_set_nack_optimizations_enabled (gboolean optimize)
	Method to enable/disable the NACK optimizations on outgoing keyframes: when enabled, the NACK buffer for a PeerConnection is cleaned any time Janus sends a keyframe, as any missing packet won't be needed since the keyframe will allow the media recipient to still restore a complete image anyway. Since this optimization seems to cause some issues in some edge cases, it's disabled by default.

gboolean	janus_is_nack_optimizations_enabled (void)
	Method to check whether NACK optimizations on outgoing keyframes are enabled or not.

void	janus_set_min_nack_queue (uint16_t mnq)
	Method to modify the min NACK value (i.e., the minimum time window of packets per handle to store for retransmissions)

uint16_t	janus_get_min_nack_queue (void)
	Method to get the current min NACK value (i.e., the minimum time window of packets per handle to store for retransmissions)

void	janus_seq_list_free (janus_seq_info **head)

void	janus_ice_relay_rtcp_internal (janus_ice_handle handle, janus_plugin_rtcp packet, gboolean filter_rtcp)

gboolean	janus_plugin_session_is_alive (janus_plugin_session *plugin_session)
	Quick helper method to check if a plugin session associated with a Janus handle is still valid.

void	janus_ice_notify_hangup (janus_ice_handle handle, const char reason)
	Quick helper method to notify a WebRTC hangup through the Janus API.

janus_ice_trickle *	janus_ice_trickle_new (const char transaction, json_t candidate)
	Helper method to allocate a janus_ice_trickle instance.

gint	janus_ice_trickle_parse (janus_ice_handle handle, json_t candidate, const char **error)
	Helper method to parse trickle candidates.

void	janus_ice_trickle_destroy (janus_ice_trickle *trickle)
	Helper method to destroy a janus_ice_trickle instance.

void	janus_ice_init (gboolean ice_lite, gboolean ice_tcp, gboolean full_trickle, gboolean ignore_mdns, gboolean ipv6, gboolean ipv6_linklocal, uint16_t rtp_min_port, uint16_t rtp_max_port)
	ICE stuff initialization.

void	janus_ice_deinit (void)
	ICE stuff de-initialization.

int	janus_ice_test_stun_server (janus_network_address addr, uint16_t port, uint16_t local_port, janus_network_address public_addr, uint16_t *public_port)
	Method to check whether a STUN server is reachable.

int	janus_ice_set_stun_server (gchar *stun_server, uint16_t stun_port)
	Method to force Janus to use a STUN server when gathering candidates.

int	janus_ice_set_turn_server (gchar turn_server, uint16_t turn_port, gchar turn_type, gchar turn_user, gchar turn_pwd)
	Method to force Janus to use a TURN server when gathering candidates.

int	janus_ice_set_turn_rest_api (gchar api_server, gchar api_key, gchar *api_method, uint api_timeout)
	Method to force Janus to contact a TURN REST API server to get a TURN service to use when gathering candidates. The TURN REST API takes precedence over any static credential passed via janus_ice_set_turn_server.

const gchar *	janus_get_ice_state_name (gint state)
	Helper method to get a string representation of a libnice ICE state.

janus_ice_handle *	janus_ice_handle_create (void core_session, const char opaque_id, const char *token)
	Method to create a new Janus ICE handle.

gint	janus_ice_handle_attach_plugin (void core_session, janus_ice_handle handle, janus_plugin *plugin, int loop_index)
	Method to attach a Janus ICE handle to a plugin.

gint	janus_ice_handle_destroy (void core_session, janus_ice_handle handle)
	Method to destroy a Janus ICE handle.

void	janus_ice_webrtc_hangup (janus_ice_handle handle, const char reason)
	Method to only hangup (e.g., DTLS alert) the WebRTC PeerConnection allocated by a Janus ICE handle.

void	janus_ice_stream_destroy (janus_ice_stream *stream)
	Method to only free resources related to a specific ICE stream allocated by a Janus ICE handle.

void	janus_ice_component_destroy (janus_ice_component *component)
	Method to only free resources related to a specific ICE component allocated by a Janus ICE handle.

void	janus_ice_incoming_data (janus_ice_handle handle, char label, char protocol, gboolean textdata, char buffer, int length)
	Plugin SCTP/DataChannel callback, called by the SCTP stack when when there's data for a plugin.

void	janus_ice_candidates_to_sdp (janus_ice_handle handle, janus_sdp_mline mline, guint stream_id, guint component_id)
	Method to add local candidates to a janus_sdp SDP object representation.

void	janus_ice_add_remote_candidate (janus_ice_handle handle, NiceCandidate c)
	Method to queue a remote candidate for processing.

void	janus_ice_setup_remote_candidates (janus_ice_handle *handle, guint stream_id, guint component_id)
	Method to handle remote candidates and start the connectivity checks.

int	janus_ice_setup_local (janus_ice_handle *handle, int offer, int audio, int video, int data, int trickle, janus_dtls_role dtls_role)
	Method to locally set up the ICE candidates (initialization and gathering)

void	janus_ice_restart (janus_ice_handle *handle)
	Method to restart ICE and the connectivity checks.

void	janus_ice_resend_trickles (janus_ice_handle *handle)
	Method to resend all the existing candidates via trickle (e.g., after an ICE restart)

void	janus_ice_relay_rtp (janus_ice_handle handle, janus_plugin_rtp packet)
	Core RTP callback, called when a plugin has an RTP packet to send to a peer.

void	janus_ice_relay_rtcp (janus_ice_handle handle, janus_plugin_rtcp packet)
	Core RTCP callback, called when a plugin has an RTCP message to send to a peer.

void	janus_ice_send_pli (janus_ice_handle *handle)
	Helper core callback, called when a plugin wants to send a RTCP PLI to a peer.

void	janus_ice_send_remb (janus_ice_handle *handle, uint32_t bitrate)
	Helper core callback, called when a plugin wants to send a RTCP REMB to a peer.

void	janus_ice_relay_sctp (janus_ice_handle handle, char buffer, int length)
	Core SCTP/DataChannel callback, called by the SCTP stack when when there's data to send.

void	janus_ice_notify_data_ready (janus_ice_handle *handle)
	Plugin SCTP/DataChannel callback, called by the SCTP stack when data can be written.

void	janus_ice_notify_media_stopped (janus_ice_handle *handle)
	Core SDP callback, called by the SDP stack when a stream has been paused by a negotiation.

void	janus_ice_dtls_handshake_done (janus_ice_handle handle, janus_ice_component component)
	Callback to be notified when the DTLS handshake for a specific component has been completed.

Variables
GList *	janus_ice_enforce_list = NULL

GList *	janus_ice_ignore_list = NULL

janus_mutex	ice_list_mutex

Detailed Description

ICE/STUN/TURN processing.

Author: Lorenzo Miniero loren.nosp@m.zo@m.nosp@m.eetec.nosp@m.ho.c.nosp@m.om

Copyright: GNU General Public License v3

Implementation (based on libnice) of the ICE process. The code handles the whole ICE process, from the gathering of candidates to the final setup of a virtual channel RTP and RTCP can be transported on. Incoming RTP and RTCP packets from peers are relayed to the associated plugins by means of the incoming_rtp and incoming_rtcp callbacks. Packets to be sent to peers are relayed by peers invoking the relay_rtp and relay_rtcp core callbacks instead.

Protocols

Macro Definition Documentation

◆ DEFAULT_MAX_NACK_QUEUE

#define DEFAULT_MAX_NACK_QUEUE 1000

◆ DEFAULT_MIN_NACK_QUEUE

#define DEFAULT_MIN_NACK_QUEUE 200

◆ DEFAULT_NO_MEDIA_TIMER

#define DEFAULT_NO_MEDIA_TIMER 1

◆ DEFAULT_SLOWLINK_THRESHOLD

#define DEFAULT_SLOWLINK_THRESHOLD 0

◆ DEFAULT_TWCC_PERIOD

#define DEFAULT_TWCC_PERIOD 200

◆ JANUS_ICE_PACKET_AUDIO

#define JANUS_ICE_PACKET_AUDIO 0

◆ JANUS_ICE_PACKET_BINARY

#define JANUS_ICE_PACKET_BINARY 3

◆ JANUS_ICE_PACKET_SCTP

#define JANUS_ICE_PACKET_SCTP 4

◆ JANUS_ICE_PACKET_TEXT

#define JANUS_ICE_PACKET_TEXT 2

◆ JANUS_ICE_PACKET_VIDEO

#define JANUS_ICE_PACKET_VIDEO 1

◆ MAX_NACK_IGNORE

#define MAX_NACK_IGNORE 200000

◆ SEQ_MISSING_WAIT

#define SEQ_MISSING_WAIT 12000 /* 12ms */

◆ SEQ_NACKED_WAIT

#define SEQ_NACKED_WAIT 155000 /* 155ms */

Typedef Documentation

◆ janus_ice_nacked_packet

typedef struct janus_ice_nacked_packet janus_ice_nacked_packet

◆ janus_ice_outgoing_traffic

typedef struct janus_ice_outgoing_traffic janus_ice_outgoing_traffic

◆ janus_ice_queued_packet

typedef struct janus_ice_queued_packet janus_ice_queued_packet

◆ janus_ice_static_event_loop

typedef struct janus_ice_static_event_loop janus_ice_static_event_loop

Function Documentation

◆ janus_enable_opaqueid_in_api()

void janus_enable_opaqueid_in_api ( void )

Method to enable opaque ID in Janus API responses/events.

◆ janus_get_dscp()

int janus_get_dscp ( void )

Method to get the current DSCP value (see above)

Returns: The current DSCP value (0 if disabled)

◆ janus_get_ice_state_name()

const gchar * janus_get_ice_state_name ( gint state )

Helper method to get a string representation of a libnice ICE state.

Parameters

[in] state The libnice ICE state

Returns: A string representation of the libnice ICE state

◆ janus_get_min_nack_queue()

uint16_t janus_get_min_nack_queue ( void )

Method to get the current min NACK value (i.e., the minimum time window of packets per handle to store for retransmissions)

Returns: The current min NACK value

◆ janus_get_no_media_timer()

uint janus_get_no_media_timer ( void )

Method to get the current no-media event timer (see above)

Returns: The current no-media event timer

◆ janus_get_slowlink_threshold()

uint janus_get_slowlink_threshold ( void )

Method to get the current slowlink-threshold value (see above)

Returns: The current slowlink-threshold value

◆ janus_get_twcc_period()

uint janus_get_twcc_period ( void )

Method to get the current TWCC period (see above)

Returns: The current TWCC period

◆ janus_ice_add_remote_candidate()

void janus_ice_add_remote_candidate	(	janus_ice_handle *	handle,
		NiceCandidate *	c )

Method to queue a remote candidate for processing.

Parameters

[in]	handle	The Janus ICE handle this method refers to
[in]	c	The remote NiceCandidate to process

◆ janus_ice_allow_force_relay()

void janus_ice_allow_force_relay ( void )

Method to enable applications to force Janus to use TURN.

◆ janus_ice_candidates_to_sdp()

void janus_ice_candidates_to_sdp	(	janus_ice_handle *	handle,
		janus_sdp_mline *	mline,
		guint	stream_id,
		guint	component_id )

Method to add local candidates to a janus_sdp SDP object representation.

Parameters

[in]	handle	The Janus ICE handle this method refers to
[in]	mline	The Janus SDP m-line object to add candidates to
[in]	stream_id	The stream ID of the candidate to add to the SDP
[in]	component_id	The component ID of the candidate to add to the SDP

◆ janus_ice_component_destroy()

void janus_ice_component_destroy ( janus_ice_component * component )

Method to only free resources related to a specific ICE component allocated by a Janus ICE handle.

Parameters

[in] component The Janus ICE component instance to free

◆ janus_ice_debugging_disable()

void janus_ice_debugging_disable ( void )

Method to disable libnice debugging (the default)

◆ janus_ice_debugging_enable()

void janus_ice_debugging_enable ( void )

Method to enable libnice debugging (http://nice.freedesktop.org/libnice/libnice-Debug-messages.html)

◆ janus_ice_deinit()

void janus_ice_deinit ( void )

ICE stuff de-initialization.

◆ janus_ice_dtls_handshake_done()

void janus_ice_dtls_handshake_done	(	janus_ice_handle *	handle,
		janus_ice_component *	component )

Callback to be notified when the DTLS handshake for a specific component has been completed.

This method also decides when to notify attached plugins about the availability of a reliable PeerConnection

Parameters

[in]	handle	The Janus ICE handle this callback refers to
[in]	component	The Janus ICE component that is now ready to be used

◆ janus_ice_enable_nat_1_1()

void janus_ice_enable_nat_1_1 ( gboolean keep_private_host )

Helper method to force Janus to overwrite all host candidates with the public IP.

Parameters

[in] keep_private_host Whether we should keep the original private host as a separate candidate, or replace it

◆ janus_ice_enforce_interface()

void janus_ice_enforce_interface ( const char * ip )

Method to add an interface/IP to the enforce list for ICE (that is, only gather candidates from these and ignore the others)

Note: This method is especially useful to speed up the ICE gathering process on the server: in fact, if you know in advance which interface must be used (e.g., the main interface connected to the internet), adding it to the enforce list will prevent libnice from gathering candidates from other interfaces. If you're interested in excluding interfaces explicitly, instead, check janus_ice_ignore_interface.

Parameters

[in] ip Interface/IP to enforce (e.g., 192.168. or eth0)

◆ janus_ice_event_get_combine_media_stats()

gboolean janus_ice_event_get_combine_media_stats ( void )

Method to retrieve whether media statistic events shall be dispatched combined or in single events.

Returns: true to combine events

◆ janus_ice_event_set_combine_media_stats()

void janus_ice_event_set_combine_media_stats ( gboolean combine_media_stats_to_one_event )

Method to define whether the media stats shall be dispatched in one event (true) or in dedicated single events (false - default)

Parameters

[in] combine_media_stats_to_one_event true to combine media statistics in on event or false to send dedicated events

◆ janus_ice_get_event_stats_period()

int janus_ice_get_event_stats_period ( void )

Method to get the current event handler statistics period (see above)

Returns: The current event handler stats period

◆ janus_ice_get_peerconnection_num()

int janus_ice_get_peerconnection_num ( void )

Method to get the number of active PeerConnection (for stats)

Returns: The current number of active PeerConnections

◆ janus_ice_get_static_event_loops()

int janus_ice_get_static_event_loops ( void )

Method to return the number of static event loops, if enabled.

Returns: The number of static event loops, if configured, or 0 if the feature is disabled

◆ janus_ice_get_stun_port()

uint16_t janus_ice_get_stun_port ( void )

Method to get the STUN server port.

Returns: The currently used STUN server port, if available, or 0 if not

◆ janus_ice_get_stun_server()

char * janus_ice_get_stun_server ( void )

Method to get the STUN server IP address.

Returns: The currently used STUN server IP address, if available, or NULL if not

◆ janus_ice_get_turn_port()

uint16_t janus_ice_get_turn_port ( void )

Method to get the TURN server port.

Returns: The currently used TURN server port, if available, or 0 if not

◆ janus_ice_get_turn_rest_api()

char * janus_ice_get_turn_rest_api ( void )

Method to get the specified TURN REST API backend, if any.

Returns: The currently specified TURN REST API backend, if available, or NULL if not

◆ janus_ice_get_turn_server()

char * janus_ice_get_turn_server ( void )

Method to get the TURN server IP address.

Returns: The currently used TURN server IP address, if available, or NULL if not

◆ janus_ice_handle_attach_plugin()

gint janus_ice_handle_attach_plugin	(	void *	core_session,
		janus_ice_handle *	handle,
		janus_plugin *	plugin,
		int	loop_index )

Method to attach a Janus ICE handle to a plugin.

This method is very important, as it allows plugins to send/receive media (RTP/RTCP) to/from a WebRTC peer.

Parameters

[in]	core_session	The core/peer session this ICE handle belongs to
[in]	handle	The Janus ICE handle
[in]	plugin	The plugin the ICE handle needs to be attached to
[in]	loop_index	In case static event loops are used, an indication on which loop to use for this handle (-1 will let the core pick one; in case API selection is disabled in the settings, this value is ignored)

Returns: 0 in case of success, a negative integer otherwise

◆ janus_ice_handle_create()

janus_ice_handle * janus_ice_handle_create	(	void *	core_session,
		const char *	opaque_id,
		const char *	token )

Method to create a new Janus ICE handle.

Parameters

[in]	core_session	The core/peer session this ICE handle will belong to
[in]	opaque_id	The opaque identifier provided by the creator, if any (optional)
[in]	token	The auth token provided by the creator, if any (optional)

Returns: The created Janus ICE handle if successful, NULL otherwise

◆ janus_ice_handle_destroy()

gint janus_ice_handle_destroy	(	void *	core_session,
		janus_ice_handle *	handle )

Method to destroy a Janus ICE handle.

Parameters

[in]	core_session	The core/peer session this ICE handle belongs to
[in]	handle	The Janus ICE handle to destroy

Returns: 0 in case of success, a negative integer otherwise

◆ janus_ice_ignore_interface()

void janus_ice_ignore_interface ( const char * ip )

Method to add an interface/IP to the ignore list for ICE (that is, don't gather candidates)

Note: This method is especially useful to speed up the ICE gathering process on the server: in fact, if you know in advance an interface is not going to be used (e.g., one of those created by VMware), adding it to the ignore list will prevent libnice from gathering a candidate for it. Unlike the enforce list, the ignore list also accepts IP addresses, partial or complete. If you're interested in only using specific interfaces, instead, check janus_ice_enforce_interface.

Parameters

[in] ip Interface/IP to ignore (e.g., 192.168. or eth1)

◆ janus_ice_incoming_data()

void janus_ice_incoming_data	(	janus_ice_handle *	handle,
		char *	label,
		char *	protocol,
		gboolean	textdata,
		char *	buffer,
		int	length )

Plugin SCTP/DataChannel callback, called by the SCTP stack when when there's data for a plugin.

Parameters

[in]	handle	The Janus ICE handle associated with the peer
[in]	label	The label of the data channel the message is from
[in]	protocol	The protocol of the data channel to use
[in]	textdata	Whether the buffer is text (domstring) or binary data
[in]	buffer	The message data (buffer)
[in]	length	The buffer length

◆ janus_ice_init()

void janus_ice_init	(	gboolean	ice_lite,
		gboolean	ice_tcp,
		gboolean	full_trickle,
		gboolean	ignore_mdns,
		gboolean	ipv6,
		gboolean	ipv6_linklocal,
		uint16_t	rtp_min_port,
		uint16_t	rtp_max_port )

ICE stuff initialization.

Parameters

[in]	ice_lite	Whether the ICE Lite mode should be enabled or not
[in]	ice_tcp	Whether ICE-TCP support should be enabled or not (only libnice >= 0.1.8, currently broken)
[in]	full_trickle	Whether full-trickle must be used (instead of half-trickle)
[in]	ignore_mdns	Whether mDNS candidates should be ignored, instead of resolved
[in]	ipv6	Whether IPv6 candidates must be negotiated or not
[in]	ipv6_linklocal	Whether IPv6 link-local candidates should be gathered
[in]	rtp_min_port	Minimum port to use for RTP/RTCP, if a range is to be used
[in]	rtp_max_port	Maximum port to use for RTP/RTCP, if a range is to be used

Note: The RTP/RTCP port range configuration may be just a placeholder: for instance, libnice supports this since 0.1.0, but the 0.1.3 on Fedora fails when linking with an undefined reference to nice_agent_set_port_range so this is checked by the install.sh script in advance.

◆ janus_ice_is_consent_freshness_enabled()

gboolean janus_ice_is_consent_freshness_enabled ( void )

Method to check whether consent fresnhess will be enabled in ICE.

Returns: true if enabled, false (default) otherwise

◆ janus_ice_is_enforced()

gboolean janus_ice_is_enforced ( const char * ip )

Method to check whether an interface is currently in the enforce list for ICE (that is, won't have candidates)

Parameters

[in] ip Interface/IP to check (e.g., 192.168.244.1 or eth1)

Returns: true if the interface/IP is in the enforce list, false otherwise

◆ janus_ice_is_force_relay_allowed()

gboolean janus_ice_is_force_relay_allowed ( void )

Method to check whether applications are allowed to force Janus to use TURN.

Returns: TRUE if they're allowed, FALSE otherwise

◆ janus_ice_is_full_trickle_enabled()

gboolean janus_ice_is_full_trickle_enabled ( void )

Method to check whether full-trickle support is enabled or not.

Returns: true if full-trickle support is enabled, false otherwise

◆ janus_ice_is_hangup_on_failed_enabled()

gboolean janus_ice_is_hangup_on_failed_enabled ( void )

Method to check whether ICE failures will result in immediate hangups.

Returns: true if enabled, false (default) otherwise

◆ janus_ice_is_ice_debugging_enabled()

gboolean janus_ice_is_ice_debugging_enabled ( void )

Method to check whether libnice debugging has been enabled (http://nice.freedesktop.org/libnice/libnice-Debug-messages.html)

Returns: True if libnice debugging is enabled, FALSE otherwise

◆ janus_ice_is_ice_lite_enabled()

gboolean janus_ice_is_ice_lite_enabled ( void )

Method to check whether ICE Lite mode is enabled or not (still WIP)

Returns: true if ICE-TCP support is enabled/supported, false otherwise

◆ janus_ice_is_ice_tcp_enabled()

gboolean janus_ice_is_ice_tcp_enabled ( void )

Method to check whether ICE-TCP support is enabled/supported or not (still WIP)

Returns: true if ICE-TCP support is enabled/supported, false otherwise

◆ janus_ice_is_ignored()

gboolean janus_ice_is_ignored ( const char * ip )

Method to check whether an interface/IP is currently in the ignore list for ICE (that is, won't have candidates)

Parameters

[in] ip Interface/IP to check (e.g., 192.168.244.1 or eth1)

Returns: true if the interface/IP is in the ignore list, false otherwise

◆ janus_ice_is_ipv6_enabled()

gboolean janus_ice_is_ipv6_enabled ( void )

Method to check whether IPv6 candidates are enabled/supported or not.

Returns: true if IPv6 candidates are enabled/supported, false otherwise

◆ janus_ice_is_ipv6_linklocal_enabled()

gboolean janus_ice_is_ipv6_linklocal_enabled ( void )

Method to check whether IPv6 link-local candidates will be gathered or not.

Note: This obviously only makes sense if IPv6 support is enabled in general

Returns: true if IPv6 link-local candidates will be gathered, false otherwise

◆ janus_ice_is_keepalive_conncheck_enabled()

gboolean janus_ice_is_keepalive_conncheck_enabled ( void )

Method to check whether connectivity checks will be used as keepalives.

Returns: true if enabled, false (default) otherwise

◆ janus_ice_is_loop_indication_allowed()

gboolean janus_ice_is_loop_indication_allowed ( void )

Method to check whether loop indication via API is allowed.

Returns: true if allowed, false otherwise

◆ janus_ice_is_mdns_enabled()

gboolean janus_ice_is_mdns_enabled ( void )

Method to check whether mDNS resolution is enabled or not.

Returns: true if mDNS resolution is enabled, false otherwise

◆ janus_ice_notify_data_ready()

void janus_ice_notify_data_ready ( janus_ice_handle * handle )

Plugin SCTP/DataChannel callback, called by the SCTP stack when data can be written.

Parameters

[in] handle The Janus ICE handle associated with the peer

◆ janus_ice_notify_hangup()

void janus_ice_notify_hangup	(	janus_ice_handle *	handle,
		const char *	reason )

Quick helper method to notify a WebRTC hangup through the Janus API.

Parameters

handle	The janus_ice_handle instance this event refers to
reason	A description of why this happened

◆ janus_ice_notify_media_stopped()

void janus_ice_notify_media_stopped ( janus_ice_handle * handle )

Core SDP callback, called by the SDP stack when a stream has been paused by a negotiation.

Parameters

[in] handle The Janus ICE handle associated with the peer

◆ janus_ice_relay_rtcp()

void janus_ice_relay_rtcp	(	janus_ice_handle *	handle,
		janus_plugin_rtcp *	packet )

Core RTCP callback, called when a plugin has an RTCP message to send to a peer.

Parameters

[in]	handle	The Janus ICE handle associated with the peer
[in]	packet	The RTCP message to send

◆ janus_ice_relay_rtcp_internal()

void janus_ice_relay_rtcp_internal	(	janus_ice_handle *	handle,
		janus_plugin_rtcp *	packet,
		gboolean	filter_rtcp )

◆ janus_ice_relay_rtp()

void janus_ice_relay_rtp	(	janus_ice_handle *	handle,
		janus_plugin_rtp *	packet )

Core RTP callback, called when a plugin has an RTP packet to send to a peer.

Parameters

[in]	handle	The Janus ICE handle associated with the peer
[in]	packet	The RTP packet to send

◆ janus_ice_relay_sctp()

void janus_ice_relay_sctp	(	janus_ice_handle *	handle,
		char *	buffer,
		int	length )

Core SCTP/DataChannel callback, called by the SCTP stack when when there's data to send.

Parameters

[in]	handle	The Janus ICE handle associated with the peer
[in]	buffer	The message data (buffer)
[in]	length	The buffer length

◆ janus_ice_resend_trickles()

void janus_ice_resend_trickles ( janus_ice_handle * handle )

Method to resend all the existing candidates via trickle (e.g., after an ICE restart)

Parameters

[in] handle The Janus ICE handle this method refers to

◆ janus_ice_restart()

void janus_ice_restart ( janus_ice_handle * handle )

Method to restart ICE and the connectivity checks.

Parameters

[in] handle The Janus ICE handle this method refers to

◆ janus_ice_send_pli()

void janus_ice_send_pli ( janus_ice_handle * handle )

Helper core callback, called when a plugin wants to send a RTCP PLI to a peer.

Parameters

[in] handle The Janus ICE handle associated with the peer

◆ janus_ice_send_remb()

void janus_ice_send_remb	(	janus_ice_handle *	handle,
		uint32_t	bitrate )

Helper core callback, called when a plugin wants to send a RTCP REMB to a peer.

Parameters

[in]	handle	The Janus ICE handle associated with the peer
[in]	bitrate	The bitrate value to put in the REMB message

◆ janus_ice_set_consent_freshness_enabled()

void janus_ice_set_consent_freshness_enabled ( gboolean enabled )

Method to enable/disable consent freshness in PeerConnections.

Note: This is only available on libnice >= 0.1.19, and automatically enables keepalive connectivity checks too. Documentation for the setting: https://libnice.freedesktop.org/libnice/NiceAgent.html#NiceAgent–consent-freshness

Parameters

[in] enabled Whether the functionality should be enabled or disabled

◆ janus_ice_set_event_stats_period()

void janus_ice_set_event_stats_period ( int period )

Method to modify the event handler statistics period (i.e., the number of seconds that should pass before Janus notifies event handlers about media statistics for a PeerConnection)

Parameters

[in] period The new period value, in seconds

◆ janus_ice_set_hangup_on_failed_enabled()

void janus_ice_set_hangup_on_failed_enabled ( gboolean enabled )

Method to enable/disable immediate hangups of PeerConnectionss on ICE failures.

Parameters

[in] enabled Whether the functionality should be enabled or disabled

◆ janus_ice_set_keepalive_conncheck_enabled()

void janus_ice_set_keepalive_conncheck_enabled ( gboolean enabled )

Method to enable/disable connectivity checks as keepalives for PeerConnections.

Note: The main rationale behind this setting is provided in the libnice documentation: https://libnice.freedesktop.org/libnice/NiceAgent.html#NiceAgent–keepalive-conncheck

Parameters

[in] enabled Whether the functionality should be enabled or disabled

◆ janus_ice_set_static_event_loops()

void janus_ice_set_static_event_loops	(	int	loops,
		gboolean	allow_api )

Method to configure the static event loops mechanism at startup.

Note: Check the event_loops property in the janus.jcfg configuration for an explanation of this feature, and the possible impact on Janus and users

Parameters

[in]	loops	The number of static event loops to start (0 to disable the feature)
[in]	allow_api	Whether allocation on a specific loop driven via API should be allowed or not (false by default)

◆ janus_ice_set_stun_server()

int janus_ice_set_stun_server	(	gchar *	stun_server,
		uint16_t	stun_port )

Method to force Janus to use a STUN server when gathering candidates.

Parameters

[in]	stun_server	STUN server address to use
[in]	stun_port	STUN port to use

Returns: 0 in case of success, a negative integer on errors

◆ janus_ice_set_turn_rest_api()

int janus_ice_set_turn_rest_api	(	gchar *	api_server,
		gchar *	api_key,
		gchar *	api_method,
		uint	api_timeout )

Method to force Janus to contact a TURN REST API server to get a TURN service to use when gathering candidates. The TURN REST API takes precedence over any static credential passed via janus_ice_set_turn_server.

Note: Requires libcurl to be available, and a working TURN REST API backend (see turnrest.h)

Parameters

[in]	api_server	TURN REST API backend (NULL to disable the API)
[in]	api_key	API key to use, if required
[in]	api_method	HTTP method to use (POST by default)
[in]	api_timeout	total timeout for HTTP method in seconds

Returns: 0 in case of success, a negative integer on errors

◆ janus_ice_set_turn_server()

int janus_ice_set_turn_server	(	gchar *	turn_server,
		uint16_t	turn_port,
		gchar *	turn_type,
		gchar *	turn_user,
		gchar *	turn_pwd )

Method to force Janus to use a TURN server when gathering candidates.

Parameters

[in]	turn_server	TURN server address to use
[in]	turn_port	TURN port to use
[in]	turn_type	Relay type (udp, tcp or tls)
[in]	turn_user	TURN username, if needed
[in]	turn_pwd	TURN password, if needed

Returns: 0 in case of success, a negative integer on errors

◆ janus_ice_setup_local()

int janus_ice_setup_local	(	janus_ice_handle *	handle,
		int	offer,
		int	audio,
		int	video,
		int	data,
		int	trickle,
		janus_dtls_role	dtls_role )

Method to locally set up the ICE candidates (initialization and gathering)

Parameters

[in]	handle	The Janus ICE handle this method refers to
[in]	offer	Whether this is for an OFFER or an ANSWER
[in]	audio	Whether audio is enabled
[in]	video	Whether video is enabled
[in]	data	Whether SCTP data channels are enabled
[in]	trickle	Whether ICE trickling is supported or not
[in]	dtls_role	The DTLS role that should be taken for this PeerConnection

Returns: 0 in case of success, a negative integer otherwise

◆ janus_ice_setup_remote_candidates()

void janus_ice_setup_remote_candidates	(	janus_ice_handle *	handle,
		guint	stream_id,
		guint	component_id )

Method to handle remote candidates and start the connectivity checks.

Parameters

[in]	handle	The Janus ICE handle this method refers to
[in]	stream_id	The stream ID of the candidate to add to the SDP
[in]	component_id	The component ID of the candidate to add to the SDP

◆ janus_ice_static_event_loops_info()

json_t * janus_ice_static_event_loops_info ( void )

Helper method to return a summary of the static loops activity.

Note: This is only used by the Admin API

Returns: a json_t array with the required info

◆ janus_ice_stop_static_event_loops()

void janus_ice_stop_static_event_loops ( void )

Method to stop all the static event loops, if enabled.

Note: This will wait for the related threads to exit, and so may delay the shutdown process

◆ janus_ice_stream_destroy()

void janus_ice_stream_destroy ( janus_ice_stream * stream )

Method to only free resources related to a specific ICE stream allocated by a Janus ICE handle.

Parameters

[in] stream The Janus ICE stream instance to free

◆ janus_ice_test_stun_server()

int janus_ice_test_stun_server	(	janus_network_address *	addr,
		uint16_t	port,
		uint16_t	local_port,
		janus_network_address *	public_addr,
		uint16_t *	public_port )

Method to check whether a STUN server is reachable.

Parameters

[in]	addr	Address of the STUN server as a janus_network_address instance
[in]	port	Port of the STUN server
[in]	local_port	Local port to bind to (0 means random choice)
[out]	public_addr	Public address returned by the STUN server as a janus_network_address instance
[out]	public_port	Public port returned by the STUN server

Returns: 0 in case of success, a negative integer on errors

◆ janus_ice_trickle_destroy()

void janus_ice_trickle_destroy ( janus_ice_trickle * trickle )

Helper method to destroy a janus_ice_trickle instance.

Parameters

[in] trickle The janus_ice_trickle instance to destroy

◆ janus_ice_trickle_new()

janus_ice_trickle * janus_ice_trickle_new	(	const char *	transaction,
		json_t *	candidate )

Helper method to allocate a janus_ice_trickle instance.

Parameters

[in]	transaction	The Janus API ID of the original trickle request
[in]	candidate	The trickle candidate, as a Jansson object

Returns: a pointer to the new instance, if successful, NULL otherwise

◆ janus_ice_trickle_parse()

gint janus_ice_trickle_parse	(	janus_ice_handle *	handle,
		json_t *	candidate,
		const char **	error )

Helper method to parse trickle candidates.

Parameters

[in]	handle	The Janus ICE handle this candidate belongs to
[in]	candidate	The trickle candidate to parse, as a Jansson object
[in,out]	error	Error string describing the failure, if any

Returns: 0 in case of success, any code from apierror.h in case of failure

◆ janus_ice_webrtc_hangup()

void janus_ice_webrtc_hangup	(	janus_ice_handle *	handle,
		const char *	reason )

Method to only hangup (e.g., DTLS alert) the WebRTC PeerConnection allocated by a Janus ICE handle.

Parameters

[in]	handle	The Janus ICE handle instance managing the WebRTC PeerConnection to hangup
[in]	reason	A description of why this happened

◆ janus_is_nack_optimizations_enabled()

gboolean janus_is_nack_optimizations_enabled ( void )

Method to check whether NACK optimizations on outgoing keyframes are enabled or not.

Returns: optimize if optimizations are enabled, false otherwise

◆ janus_is_opaqueid_in_api_enabled()

gboolean janus_is_opaqueid_in_api_enabled ( void )

Method to check whether opaque ID have to be added to Janus API responses/events.

Returns: TRUE if they need to be present, FALSE otherwise

◆ janus_plugin_session_is_alive()

gboolean janus_plugin_session_is_alive ( janus_plugin_session * plugin_session )

Quick helper method to check if a plugin session associated with a Janus handle is still valid.

Parameters

plugin_session The janus_plugin_session instance to validate

Returns: true if the plugin session is valid, false otherwise

◆ janus_seq_list_free()

void janus_seq_list_free ( janus_seq_info ** head )

◆ janus_set_dscp()

void janus_set_dscp ( int dscp )

Method to modify the DSCP value to set, which is disabled by default.

Parameters

[in] dscp The new DSCP value (0 to disable)

◆ janus_set_min_nack_queue()

void janus_set_min_nack_queue ( uint16_t mnq )

Method to modify the min NACK value (i.e., the minimum time window of packets per handle to store for retransmissions)

Parameters

[in] mnq The new min NACK value

◆ janus_set_nack_optimizations_enabled()

void janus_set_nack_optimizations_enabled ( gboolean optimize )

Method to enable/disable the NACK optimizations on outgoing keyframes: when enabled, the NACK buffer for a PeerConnection is cleaned any time Janus sends a keyframe, as any missing packet won't be needed since the keyframe will allow the media recipient to still restore a complete image anyway. Since this optimization seems to cause some issues in some edge cases, it's disabled by default.

Parameters

[in] optimize Whether the optimization should be enabled or disabled

◆ janus_set_no_media_timer()

void janus_set_no_media_timer ( uint timer )

Method to modify the no-media event timer (i.e., the number of seconds where no media arrives before Janus notifies this)

Parameters

[in] timer The new timer value, in seconds

◆ janus_set_slowlink_threshold()

void janus_set_slowlink_threshold ( uint packets )

Method to modify the slowlink-threshold property (i.e., the number of lost packets per seconds that should trigger a slow-link event)

Parameters

[in] packets The new value, in lost packets per seconds

◆ janus_set_twcc_period()

void janus_set_twcc_period ( uint period )

Method to modify the TWCC feedback period (i.e., how often TWCC feedback is sent back to media senders)

Parameters

[in] period The new period value, in milliseconds

Variable Documentation

◆ ice_list_mutex

janus_mutex ice_list_mutex

◆ janus_ice_enforce_list

GList* janus_ice_enforce_list = NULL

◆ janus_ice_ignore_list

GList * janus_ice_ignore_list = NULL

Data Structures

Macros

Typedefs

Functions

Variables

Detailed Description

Macro Definition Documentation

◆ DEFAULT_MAX_NACK_QUEUE

◆ DEFAULT_MIN_NACK_QUEUE

◆ DEFAULT_NO_MEDIA_TIMER

◆ DEFAULT_SLOWLINK_THRESHOLD

◆ DEFAULT_TWCC_PERIOD

◆ JANUS_ICE_PACKET_AUDIO

◆ JANUS_ICE_PACKET_BINARY

◆ JANUS_ICE_PACKET_SCTP

◆ JANUS_ICE_PACKET_TEXT

◆ JANUS_ICE_PACKET_VIDEO

◆ MAX_NACK_IGNORE

◆ SEQ_MISSING_WAIT

◆ SEQ_NACKED_WAIT

Typedef Documentation

◆ janus_ice_nacked_packet

◆ janus_ice_outgoing_traffic

◆ janus_ice_queued_packet

◆ janus_ice_static_event_loop

Function Documentation

◆ janus_enable_opaqueid_in_api()

◆ janus_get_dscp()

◆ janus_get_ice_state_name()

◆ janus_get_min_nack_queue()

◆ janus_get_no_media_timer()

◆ janus_get_slowlink_threshold()

◆ janus_get_twcc_period()

◆ janus_ice_add_remote_candidate()

◆ janus_ice_allow_force_relay()

◆ janus_ice_candidates_to_sdp()

◆ janus_ice_component_destroy()

◆ janus_ice_debugging_disable()

◆ janus_ice_debugging_enable()

◆ janus_ice_deinit()

◆ janus_ice_dtls_handshake_done()

◆ janus_ice_enable_nat_1_1()

◆ janus_ice_enforce_interface()

◆ janus_ice_event_get_combine_media_stats()

◆ janus_ice_event_set_combine_media_stats()

◆ janus_ice_get_event_stats_period()

◆ janus_ice_get_peerconnection_num()

◆ janus_ice_get_static_event_loops()

◆ janus_ice_get_stun_port()

◆ janus_ice_get_stun_server()

◆ janus_ice_get_turn_port()

◆ janus_ice_get_turn_rest_api()

◆ janus_ice_get_turn_server()

◆ janus_ice_handle_attach_plugin()

◆ janus_ice_handle_create()

◆ janus_ice_handle_destroy()

◆ janus_ice_ignore_interface()

◆ janus_ice_incoming_data()

◆ janus_ice_init()

◆ janus_ice_is_consent_freshness_enabled()

◆ janus_ice_is_enforced()

◆ janus_ice_is_force_relay_allowed()

◆ janus_ice_is_full_trickle_enabled()

◆ janus_ice_is_hangup_on_failed_enabled()

◆ janus_ice_is_ice_debugging_enabled()

◆ janus_ice_is_ice_lite_enabled()

◆ janus_ice_is_ice_tcp_enabled()

◆ janus_ice_is_ignored()

◆ janus_ice_is_ipv6_enabled()

◆ janus_ice_is_ipv6_linklocal_enabled()

◆ janus_ice_is_keepalive_conncheck_enabled()

◆ janus_ice_is_loop_indication_allowed()

◆ janus_ice_is_mdns_enabled()

◆ janus_ice_notify_data_ready()

◆ janus_ice_notify_hangup()

◆ janus_ice_notify_media_stopped()

◆ janus_ice_relay_rtcp()

◆ janus_ice_relay_rtcp_internal()

◆ janus_ice_relay_rtp()

◆ janus_ice_relay_sctp()