mediastreamer2 5.2.0
Data Structures | Macros | Typedefs | Enumerations | Functions
ice.h File Reference

mediastreamer2 ice.h include file More...

#include <mediastreamer2/mscommon.h>
#include <mediastreamer2/stun.h>
#include <ortp/ortp.h>
Include dependency graph for ice.h:

Data Structures

struct  _IceSession
 
struct  _IceStunServerRequestTransaction
 
struct  _IceStunServerRequest
 
struct  _IceStunRequestRoundTripTime
 
struct  _IceTransportAddress
 
struct  _IceCandidate
 
struct  _IceCandidatePair
 
struct  _IcePairFoundation
 
struct  _IceValidCandidatePair
 
struct  _IceTransaction
 
struct  _IceCheckList
 

Macros

#define ICE_SESSION_MAX_CHECK_LISTS   8
 
#define ICE_RTP_COMPONENT_ID   1
 
#define ICE_RTCP_COMPONENT_ID   2
 

Typedefs

typedef struct _IceSession IceSession
 
typedef struct _IceStunServerRequestTransaction IceStunServerRequestTransaction
 
typedef struct _IceStunServerRequest IceStunServerRequest
 
typedef struct _IceStunRequestRoundTripTime IceStunRequestRoundTripTime
 
typedef struct _IceTransportAddress IceTransportAddress
 
typedef struct _IceCandidate IceCandidate
 
typedef struct _IceCandidatePair IceCandidatePair
 
typedef struct _IcePairFoundation IcePairFoundation
 
typedef struct _IceValidCandidatePair IceValidCandidatePair
 
typedef struct _IceTransaction IceTransaction
 
typedef struct _IceCheckList IceCheckList
 

Enumerations

enum  IceRole {
  IR_Controlling ,
  IR_Controlled
}
 
enum  IceCandidateType {
  ICT_CandidateInvalid = -1 ,
  ICT_HostCandidate ,
  ICT_ServerReflexiveCandidate ,
  ICT_PeerReflexiveCandidate ,
  ICT_RelayedCandidate ,
  ICT_CandidateTypeMax
}
 
enum  IceCandidatePairState {
  ICP_Waiting ,
  ICP_InProgress ,
  ICP_Succeeded ,
  ICP_Failed ,
  ICP_Frozen
}
 
enum  IceCheckListState {
  ICL_Running ,
  ICL_Completed ,
  ICL_Failed
}
 
enum  IceSessionState {
  IS_Stopped ,
  IS_Running ,
  IS_Completed ,
  IS_Failed
}
 

Functions

IceSessionice_session_new (void)
 
void ice_session_set_default_candidates_types (IceSession *session, const IceCandidateType types[ICT_CandidateTypeMax])
 
void ice_session_set_default_candidates_ip_version (IceSession *session, bool_t ipv6_preferred)
 
void ice_session_destroy (IceSession *session)
 
IceCheckListice_check_list_new (void)
 
void ice_check_list_destroy (IceCheckList *cl)
 
bool_t ice_check_list_candidates_gathered (const IceCheckList *cl)
 
IceCheckListice_session_check_list (const IceSession *session, int n)
 
const char * ice_session_local_ufrag (const IceSession *session)
 
const char * ice_session_local_pwd (const IceSession *session)
 
const char * ice_session_remote_ufrag (const IceSession *session)
 
const char * ice_session_remote_pwd (const IceSession *session)
 
IceSessionState ice_session_state (const IceSession *session)
 
IceRole ice_session_role (const IceSession *session)
 
void ice_session_set_role (IceSession *session, IceRole role)
 
void ice_session_set_local_credentials (IceSession *session, const char *ufrag, const char *pwd)
 
bool_t ice_session_remote_credentials_changed (IceSession *session, const char *ufrag, const char *pwd)
 
void ice_session_set_remote_credentials (IceSession *session, const char *ufrag, const char *pwd)
 
const char * ice_check_list_get_remote_ufrag (const IceCheckList *cl)
 
const char * ice_check_list_get_remote_pwd (const IceCheckList *cl)
 
void ice_session_set_max_connectivity_checks (IceSession *session, uint8_t max_connectivity_checks)
 
void ice_session_set_keepalive_timeout (IceSession *session, uint8_t timeout)
 
int ice_session_nb_check_lists (IceSession *session)
 
bool_t ice_session_has_completed_check_list (const IceSession *session)
 
void ice_session_add_check_list (IceSession *session, IceCheckList *cl, unsigned int idx)
 
void ice_session_remove_check_list (IceSession *session, IceCheckList *cl)
 
void ice_session_remove_check_list_from_idx (IceSession *session, unsigned int idx)
 
bool_t ice_session_candidates_gathered (const IceSession *session)
 
bool_t ice_session_gather_candidates (IceSession *session, const struct sockaddr *ss, socklen_t ss_len)
 
int ice_session_gathering_duration (IceSession *session)
 
void ice_session_enable_forced_relay (IceSession *session, bool_t enable)
 
void ice_session_enable_short_turn_refresh (IceSession *session, bool_t enable)
 
void ice_session_enable_turn (IceSession *session, bool_t enable)
 
void ice_session_set_turn_transport (IceSession *session, const char *transport)
 
void ice_session_set_turn_root_certificate (IceSession *session, const char *root_certificate)
 
void ice_session_set_turn_cn (IceSession *session, const char *cn)
 
void ice_session_set_stun_auth_requested_cb (IceSession *session, MSStunAuthRequestedCb cb, void *userdata)
 
int ice_session_average_gathering_round_trip_time (IceSession *session)
 
void ice_session_select_candidates (IceSession *session)
 
void ice_session_restart (IceSession *session, IceRole role)
 
void ice_session_reset (IceSession *session, IceRole role)
 
IceCheckListState ice_check_list_state (const IceCheckList *cl)
 
void ice_check_list_set_state (IceCheckList *cl, IceCheckListState state)
 
const char * ice_check_list_state_to_string (const IceCheckListState state)
 
void ice_check_list_set_rtp_session (IceCheckList *cl, RtpSession *rtp_session)
 
const char * ice_check_list_local_ufrag (const IceCheckList *cl)
 
const char * ice_check_list_local_pwd (const IceCheckList *cl)
 
const char * ice_check_list_remote_ufrag (const IceCheckList *cl)
 
const char * ice_check_list_remote_pwd (const IceCheckList *cl)
 
bool_t ice_check_list_is_mismatch (const IceCheckList *cl)
 
bool_t ice_check_list_remote_credentials_changed (IceCheckList *cl, const char *ufrag, const char *pwd)
 
void ice_check_list_set_remote_credentials (IceCheckList *cl, const char *ufrag, const char *pwd)
 
bool_t ice_check_list_default_local_candidate (const IceCheckList *cl, IceCandidate **rtp_candidate, IceCandidate **rtcp_candidate)
 
bool_t ice_check_list_selected_valid_local_candidate (const IceCheckList *cl, IceCandidate **rtp_candidate, IceCandidate **rtcp_candidate)
 
bool_t ice_check_list_selected_valid_local_base_candidate (const IceCheckList *cl, IceCandidate **rtp_candidate, IceCandidate **rtcp_candidate)
 
bool_t ice_check_list_selected_valid_remote_candidate (const IceCheckList *cl, IceCandidate **rtp_candidate, IceCandidate **rtcp_candidate)
 
IceCandidateType ice_check_list_selected_valid_candidate_type (const IceCheckList *cl)
 
void ice_check_list_check_completed (IceCheckList *cl)
 
const char * ice_candidate_type (const IceCandidate *candidate)
 
IceCandidateice_add_local_candidate (IceCheckList *cl, const char *type, int family, const char *ip, int port, uint16_t componentID, IceCandidate *base)
 
IceCandidateice_add_remote_candidate (IceCheckList *cl, const char *type, int family, const char *ip, int port, uint16_t componentID, uint32_t priority, const char *const foundation, bool_t is_default)
 
void ice_add_losing_pair (IceCheckList *cl, uint16_t componentID, int local_family, const char *local_addr, int local_port, int remote_family, const char *remote_addr, int remote_port)
 
int ice_session_nb_losing_pairs (const IceSession *session)
 
void ice_session_set_base_for_srflx_candidates (IceSession *session)
 
void ice_check_list_remove_rtcp_candidates (IceCheckList *cl)
 
void ice_session_compute_candidates_foundations (IceSession *session)
 
void ice_session_eliminate_redundant_candidates (IceSession *session)
 
void ice_session_choose_default_candidates (IceSession *session)
 
void ice_session_choose_default_remote_candidates (IceSession *session)
 
void ice_session_start_connectivity_checks (IceSession *session)
 
void ice_session_check_mismatch (IceSession *session)
 
void ice_session_enable_message_integrity_check (IceSession *session, bool_t enable)
 
void ice_check_list_process (IceCheckList *cl, RtpSession *rtp_session)
 
void ice_handle_stun_packet (IceCheckList *cl, RtpSession *rtp_session, const OrtpEventData *evt_data)
 
void ice_get_remote_addr_and_ports_from_valid_pairs (const IceCheckList *cl, char *rtp_addr, int *rtp_port, char *rtcp_addr, int *rtcp_port, int addr_len)
 
void ice_check_list_print_route (const IceCheckList *cl, const char *message)
 
void ice_dump_session (const IceSession *session)
 
void ice_dump_candidates (const IceCheckList *cl)
 
void ice_dump_candidate_pairs (const IceCheckList *cl)
 
void ice_dump_valid_list (const IceCheckList *cl)
 
void ice_dump_candidate_pairs_foundations (const IceCheckList *cl)
 
void ice_dump_componentIDs (const IceCheckList *cl)
 
void ice_dump_check_list (const IceCheckList *cl)
 
void ice_dump_triggered_checks_queue (const IceCheckList *cl)
 

Detailed Description

mediastreamer2 ice.h include file

This file provides the API to handle the ICE protocol defined in the RFC 5245.

Macro Definition Documentation

◆ ICE_SESSION_MAX_CHECK_LISTS

#define ICE_SESSION_MAX_CHECK_LISTS   8

The maximum number of check lists in an ICE session.

Typedef Documentation

◆ IceCandidate

typedef struct _IceCandidate IceCandidate

Structure representing an ICE candidate.

◆ IceCandidatePair

Structure representing an ICE candidate pair.

◆ IceCheckList

typedef struct _IceCheckList IceCheckList

Structure representing an ICE check list.

Each media stream must be assigned a check list. Check lists are added to an ICE session using the ice_session_add_check_list() function.

◆ IcePairFoundation

Structure representing the foundation of an ICE candidate pair.

It is the concatenation of the foundation of a local candidate and the foundation of a remote candidate.

◆ IceSession

typedef struct _IceSession IceSession

Structure representing an ICE session.

◆ IceTransportAddress

Structure representing an ICE transport address.

Enumeration Type Documentation

◆ IceCandidatePairState

ICE candidate pair state.

See paragraph 5.7.4 ("Computing states") of RFC 5245 for more details.

◆ IceCandidateType

ICE candidate type.

See the terminology in paragraph 3 of the RFC 5245 for more details.

◆ IceCheckListState

ICE check list state.

See paragraph 5.7.4 ("Computing states") of RFC 5245 for more details.

◆ IceRole

enum IceRole

ICE agent role.

See the terminology in paragraph 3 of the RFC 5245 for more details.

◆ IceSessionState

ICE session state.

Function Documentation

◆ ice_add_local_candidate()

IceCandidate * ice_add_local_candidate ( IceCheckList cl,
const char *  type,
int  family,
const char *  ip,
int  port,
uint16_t  componentID,
IceCandidate base 
)

Add a local candidate to an ICE check list.

Parameters
clA pointer to a check list
typeThe type of the local candidate to add as a string (must be one of: "host", "srflx", "prflx" or "relay")
familyThe address family of the local candidate (AF_INET or AF_INET6)
ipThe IP address of the local candidate as a string (eg. 192.168.0.10)
portThe port of the local candidate
componentIDThe component ID of the local candidate (usually 1 for RTP and 2 for RTCP)
baseA pointer to the base candidate of the candidate to add.

This function is to be called when gathering local candidates.

◆ ice_add_losing_pair()

void ice_add_losing_pair ( IceCheckList cl,
uint16_t  componentID,
int  local_family,
const char *  local_addr,
int  local_port,
int  remote_family,
const char *  remote_addr,
int  remote_port 
)

Add a losing pair to an ICE check list.

Parameters
clA pointer to a check list
componentIDThe component ID of the candidates of the pair to add
familyThe address family of the candidates (AF_INET or AF_INET6)
local_addrThe address of the local candidate of the pair to add
local_portThe port of the local candidate of the pair to add
remote_addrThe address of the remote candidate of the pair to add
remote_portThe port of the remote candidate of the pair to add

This function is to be called when a RE-INVITE with an SDP containing a remote-candidates attribute is received.

◆ ice_add_remote_candidate()

IceCandidate * ice_add_remote_candidate ( IceCheckList cl,
const char *  type,
int  family,
const char *  ip,
int  port,
uint16_t  componentID,
uint32_t  priority,
const char *const  foundation,
bool_t  is_default 
)

Add a remote candidate to an ICE check list.

Parameters
clA pointer to a check list
typeThe type of the remote candidate to add as a string (must be one of: "host", "srflx", "prflx" or "relay")
familyThe address family of the remote candidate (AF_INET or AF_INET6)
ipThe IP address of the remote candidate as a string (eg. 192.168.0.10)
portThe port of the remote candidate
componentIDThe component ID of the remote candidate (usually 1 for RTP and 2 for RTCP)
priorityThe priority of the remote candidate
foundationThe foundation of the remote candidate
is_defaultBoolean value telling whether the remote candidate is a default candidate or not

This function is to be called once the remote candidate list has been received via SDP.

◆ ice_candidate_type()

const char * ice_candidate_type ( const IceCandidate candidate)

Get the candidate type as a string.

Parameters
candidateA pointer to a candidate
Returns
A pointer to the candidate type as a string

◆ ice_check_list_candidates_gathered()

bool_t ice_check_list_candidates_gathered ( const IceCheckList cl)

Tell whether ICE local candidates have been gathered for an ICE check list or not.

Parameters
clA pointer to a check list
Returns
TRUE if local candidates have been gathered for the check list, FALSE otherwise.

◆ ice_check_list_check_completed()

void ice_check_list_check_completed ( IceCheckList cl)

Check if an ICE check list can be set in the Completed state after handling losing pairs.

Parameters
clA pointer to a check list

◆ ice_check_list_default_local_candidate()

bool_t ice_check_list_default_local_candidate ( const IceCheckList cl,
IceCandidate **  rtp_candidate,
IceCandidate **  rtcp_candidate 
)

Get the default local candidate for an ICE check list.

Parameters
clA pointer to a check list
rtp_candidateA pointer to store the RTP default local candidate
rtcp_candidateA pointer to store the RTCP default local candidate
Returns
TRUE if the information have been successfully retrieved, FALSE otherwise

◆ ice_check_list_destroy()

void ice_check_list_destroy ( IceCheckList cl)

Destroy a previously allocated ICE check list.

Parameters
clThe check list to destroy

◆ ice_check_list_get_remote_pwd()

const char * ice_check_list_get_remote_pwd ( const IceCheckList cl)

get the remote pwd of an ICE check list.

Parameters
clA pointer to a check list

This function is to be called once the remote credentials have been received via SDP.

◆ ice_check_list_get_remote_ufrag()

const char * ice_check_list_get_remote_ufrag ( const IceCheckList cl)

get the remote ufrag of an ICE check list.

Parameters
clA pointer to a check list

This function is to be called once the remote credentials have been received via SDP.

◆ ice_check_list_is_mismatch()

bool_t ice_check_list_is_mismatch ( const IceCheckList cl)

Get the mismatch property of an ICE check list.

Parameters
clA pointer to a check list
Returns
TRUE if there was a mismatch for the check list, FALSE otherwise

◆ ice_check_list_local_pwd()

const char * ice_check_list_local_pwd ( const IceCheckList cl)

Get the local password of an ICE check list.

Parameters
clA pointer to a check list
Returns
A pointer to the local password of the check list

◆ ice_check_list_local_ufrag()

const char * ice_check_list_local_ufrag ( const IceCheckList cl)

Get the local username fragment of an ICE check list.

Parameters
clA pointer to a check list
Returns
A pointer to the local username fragment of the check list

◆ ice_check_list_new()

IceCheckList * ice_check_list_new ( void  )

Allocate a new ICE check list.

Returns
Pointer to the allocated check list

A check list must be allocated for each media stream of a media session and be added to an ICE session using the ice_session_add_check_list() function.

◆ ice_check_list_print_route()

void ice_check_list_print_route ( const IceCheckList cl,
const char *  message 
)

Print the route used to send the stream if the ICE process has finished successfully.

Parameters
clA pointer to a check list
messageA message to print before the route

◆ ice_check_list_process()

void ice_check_list_process ( IceCheckList cl,
RtpSession *  rtp_session 
)

Core ICE check list processing.

This function is called from the audiostream or the videostream and is NOT to be called by the user.

◆ ice_check_list_remote_credentials_changed()

bool_t ice_check_list_remote_credentials_changed ( IceCheckList cl,
const char *  ufrag,
const char *  pwd 
)

Tell if remote credentials of an ICE check list have changed or not.

Parameters
clA pointer to a check list
ufragThe new remote username fragment
pwdThe new remote password
Returns
TRUE if the remote credentials of the check list have changed, FALSE otherwise.

◆ ice_check_list_remote_pwd()

const char * ice_check_list_remote_pwd ( const IceCheckList cl)

Get the remote password of an ICE check list.

Parameters
clA pointer to a check list
Returns
A pointer to the remote password of the check list

◆ ice_check_list_remote_ufrag()

const char * ice_check_list_remote_ufrag ( const IceCheckList cl)

Get the remote username fragment of an ICE check list.

Parameters
clA pointer to a check list
Returns
A pointer to the remote username fragment of the check list

◆ ice_check_list_remove_rtcp_candidates()

void ice_check_list_remove_rtcp_candidates ( IceCheckList cl)

Remove local and remote RTCP candidates from an ICE check list.

Parameters
clA pointer to a check list

This function MUST be called before calling ice_session_start_connectivity_checks(). It is useful when using rtcp-mux.

◆ ice_check_list_selected_valid_candidate_type()

IceCandidateType ice_check_list_selected_valid_candidate_type ( const IceCheckList cl)

Get the type of the selected valid candidate for an ICE check list.

Parameters
clA pointer to a check list
Returns
The type of the selected valid candidate

◆ ice_check_list_selected_valid_local_base_candidate()

bool_t ice_check_list_selected_valid_local_base_candidate ( const IceCheckList cl,
IceCandidate **  rtp_candidate,
IceCandidate **  rtcp_candidate 
)

Get the selected valid base candidate for an ICE check list.

Parameters
clA pointer to a check list
rtp_candidateA pointer to store the RTP valid local base candidate
rtcp_candidateA pointer to store the RTCP valid local base candidate
Returns
TRUE if the information have been successfully retrieved, FALSE otherwise

◆ ice_check_list_selected_valid_local_candidate()

bool_t ice_check_list_selected_valid_local_candidate ( const IceCheckList cl,
IceCandidate **  rtp_candidate,
IceCandidate **  rtcp_candidate 
)

Get the selected valid local candidate for an ICE check list.

Parameters
clA pointer to a check list
rtp_candidateA pointer to store the RTP valid local candidate
rtcp_candidateA pointer to store the RTCP valid local candidate
Returns
TRUE if the information have been successfully retrieved, FALSE otherwise

◆ ice_check_list_selected_valid_remote_candidate()

bool_t ice_check_list_selected_valid_remote_candidate ( const IceCheckList cl,
IceCandidate **  rtp_candidate,
IceCandidate **  rtcp_candidate 
)

Get the selected valid remote candidate for an ICE check list.

Parameters
clA pointer to a check list
rtp_candidateA pointer to store the RTP valid remote candidate
rtcp_candidateA pointer to store the RTCP valid remote candidate
Returns
TRUE if the information have been successfully retrieved, FALSE otherwise

◆ ice_check_list_set_remote_credentials()

void ice_check_list_set_remote_credentials ( IceCheckList cl,
const char *  ufrag,
const char *  pwd 
)

Set the remote credentials of an ICE check list.

Parameters
clA pointer to a check list
ufragThe remote username fragment
pwdThe remote password

This function is to be called once the remote credentials have been received via SDP.

◆ ice_check_list_set_rtp_session()

void ice_check_list_set_rtp_session ( IceCheckList cl,
RtpSession *  rtp_session 
)

Assign an RTP session to an ICE check list.

Parameters
clA pointer to a check list
rtp_sessionA pointer to the RTP session to assign to the check list

◆ ice_check_list_set_state()

void ice_check_list_set_state ( IceCheckList cl,
IceCheckListState  state 
)

Set the state of an ICE check list.

Parameters
clA pointer to a check list
stateThe new state of the check list

◆ ice_check_list_state()

IceCheckListState ice_check_list_state ( const IceCheckList cl)

Get the state of an ICE check list.

Parameters
clA pointer to a check list
Returns
The check list state

◆ ice_check_list_state_to_string()

const char * ice_check_list_state_to_string ( const IceCheckListState  state)

Humanly readable IceCheckListState

Parameters
stateThe state of the check list
Returns
a humanly readable IceCheckListState.

◆ ice_dump_candidate_pairs()

void ice_dump_candidate_pairs ( const IceCheckList cl)

Dump the candidate pairs of an ICE check list in the traces (debug function).

◆ ice_dump_candidate_pairs_foundations()

void ice_dump_candidate_pairs_foundations ( const IceCheckList cl)

Dump the list of candidate pair foundations of an ICE check list in the traces (debug function).

◆ ice_dump_candidates()

void ice_dump_candidates ( const IceCheckList cl)

Dump the candidates of an ICE check list in the traces (debug function).

◆ ice_dump_check_list()

void ice_dump_check_list ( const IceCheckList cl)

Dump an ICE check list in the traces (debug function).

◆ ice_dump_componentIDs()

void ice_dump_componentIDs ( const IceCheckList cl)

Dump the list of component IDs of an ICE check list in the traces (debug function).

◆ ice_dump_session()

void ice_dump_session ( const IceSession session)

Dump an ICE session in the traces (debug function).

◆ ice_dump_triggered_checks_queue()

void ice_dump_triggered_checks_queue ( const IceCheckList cl)

Dump the triggered checks queue of an ICE check list in the traces (debug function).

◆ ice_dump_valid_list()

void ice_dump_valid_list ( const IceCheckList cl)

Dump the valid list of an ICE check list in the traces (debug function).

◆ ice_get_remote_addr_and_ports_from_valid_pairs()

void ice_get_remote_addr_and_ports_from_valid_pairs ( const IceCheckList cl,
char *  rtp_addr,
int *  rtp_port,
char *  rtcp_addr,
int *  rtcp_port,
int  addr_len 
)

Get the remote address, RTP port and RTCP port to use to send the stream once the ICE process has finished successfully.

Parameters
clA pointer to a check list
rtp_addrA pointer to the buffer to use to store the remote RTP address
rtp_portA pointer to the location to store the RTP port to
rtcp_addrA pointer to the buffer to use to store the remote RTCP address
rtcp_portA pointer to the location to store the RTCP port to
addr_lenThe size of the buffer to use to store the remote addresses

This function will usually be called from within the success callback defined while creating the ICE check list with ice_check_list_new().

◆ ice_handle_stun_packet()

void ice_handle_stun_packet ( IceCheckList cl,
RtpSession *  rtp_session,
const OrtpEventData *  evt_data 
)

Handle a STUN packet that has been received.

This function is called from the audiostream or the videostream and is NOT to be called by the user.

◆ ice_session_add_check_list()

void ice_session_add_check_list ( IceSession session,
IceCheckList cl,
unsigned int  idx 
)

Add an ICE check list to an ICE session.

Parameters
sessionThe session that is assigned the check list
clThe check list to assign to the session
idxThe index of the check list to add

◆ ice_session_average_gathering_round_trip_time()

int ice_session_average_gathering_round_trip_time ( IceSession session)

Tell the average round trip time during the gathering process for an ICE session in ms.

Parameters
sessionA pointer to a session
Returns
-1 if gathering has not been run, the average round trip time in ms otherwise.

◆ ice_session_candidates_gathered()

bool_t ice_session_candidates_gathered ( const IceSession session)

Tell whether ICE local candidates have been gathered for an ICE session or not.

Parameters
sessionA pointer to a session
Returns
TRUE if local candidates have been gathered for the session, FALSE otherwise.

◆ ice_session_check_list()

IceCheckList * ice_session_check_list ( const IceSession session,
int  n 
)

Get the nth check list of an ICE session.

Parameters
sessionA pointer to a session
nThe number of the check list to access
Returns
A pointer to the nth check list of the session if it exists, NULL otherwise

◆ ice_session_check_mismatch()

void ice_session_check_mismatch ( IceSession session)

Check whether all the ICE check lists of the session includes a default candidate for each component ID in its remote candidates list.

Parameters
sessionA pointer to a session

◆ ice_session_choose_default_candidates()

void ice_session_choose_default_candidates ( IceSession session)

Choose the default candidates of an ICE session.

Parameters
sessionA pointer to a session

This function is to be called at the end of the local candidates gathering process, before sending the SDP to the remote agent.

◆ ice_session_choose_default_remote_candidates()

void ice_session_choose_default_remote_candidates ( IceSession session)

Choose the default remote candidates of an ICE session.

This function SHOULD not be used. Instead, the default remote candidates MUST be defined as default when creating them with ice_add_remote_candidate(). However, this function is used by mediastream for testing purpose.

◆ ice_session_compute_candidates_foundations()

void ice_session_compute_candidates_foundations ( IceSession session)

Compute the foundations of the local candidates of an ICE session.

Parameters
sessionA pointer to a session

This function is to be called at the end of the local candidates gathering process, before sending the SDP to the remote agent.

◆ ice_session_destroy()

void ice_session_destroy ( IceSession session)

Destroy a previously allocated ICE session.

Parameters
sessionThe session to destroy.

To be used when a media session using ICE is tore down.

◆ ice_session_eliminate_redundant_candidates()

void ice_session_eliminate_redundant_candidates ( IceSession session)

Eliminate the redundant candidates of an ICE session.

Parameters
sessionA pointer to a session

This function is to be called at the end of the local candidates gathering process, before sending the SDP to the remote agent.

◆ ice_session_enable_forced_relay()

void ice_session_enable_forced_relay ( IceSession session,
bool_t  enable 
)

Enable forced relay for tests. The local and reflexive candidates are changed so that these paths do not work to force the use of the relay.

Parameters
sessionA pointer to a session.
enableA boolean value telling whether to force relay or not.

◆ ice_session_enable_message_integrity_check()

void ice_session_enable_message_integrity_check ( IceSession session,
bool_t  enable 
)

Disable/enable strong message integrity check. Used for backward compatibility only default value is enabled

Parameters
sessionA pointer to a session
enablevalue

◆ ice_session_enable_short_turn_refresh()

void ice_session_enable_short_turn_refresh ( IceSession session,
bool_t  enable 
)

Enable short TURN refresh for tests. This changes the delay to send allocation refresh, create permission, and channel bind requests.

Parameters
sessionA pointer to a session
enableA boolean value telling whether to use short turn refresh.

◆ ice_session_enable_turn()

void ice_session_enable_turn ( IceSession session,
bool_t  enable 
)

Enable TURN protocol.

Parameters
sessionA pointer to a session
enableA boolean value telling whether to enable TURN protocol or not.

◆ ice_session_gather_candidates()

bool_t ice_session_gather_candidates ( IceSession session,
const struct sockaddr *  ss,
socklen_t  ss_len 
)

Gather ICE local candidates for an ICE session.

Parameters
sessionA pointer to a session
ssThe STUN server address
ss_lenThe length of the STUN server address
Returns
TRUE if the gathering is in progress, FALSE if no gathering is happening.

◆ ice_session_gathering_duration()

int ice_session_gathering_duration ( IceSession session)

Tell the duration of the gathering process for an ICE session in ms.

Parameters
sessionA pointer to a session
Returns
-1 if gathering has not been run, the duration of the gathering process in ms otherwise.

◆ ice_session_has_completed_check_list()

bool_t ice_session_has_completed_check_list ( const IceSession session)

Tell whether an ICE session has at least one completed check list.

Parameters
sessionA pointer to a session
Returns
TRUE if the session has at least one completed check list, FALSE otherwise

◆ ice_session_local_pwd()

const char * ice_session_local_pwd ( const IceSession session)

Get the local password of an ICE session.

Parameters
sessionA pointer to a session
Returns
A pointer to the local password of the session

◆ ice_session_local_ufrag()

const char * ice_session_local_ufrag ( const IceSession session)

Get the local username fragment of an ICE session.

Parameters
sessionA pointer to a session
Returns
A pointer to the local username fragment of the session

◆ ice_session_nb_check_lists()

int ice_session_nb_check_lists ( IceSession session)

Get the number of check lists in an ICE session.

Parameters
sessionA pointer to a session
Returns
The number of check lists in the ICE session

◆ ice_session_nb_losing_pairs()

int ice_session_nb_losing_pairs ( const IceSession session)

Get the number of losing candidate pairs for an ICE session.

Parameters
sessionA pointer to a session
Returns
The number of losing candidate pairs for the session.

◆ ice_session_new()

IceSession * ice_session_new ( void  )

Allocate a new ICE session.

Returns
Pointer to the allocated session

This must be performed for each media session that is to use ICE.

◆ ice_session_remote_credentials_changed()

bool_t ice_session_remote_credentials_changed ( IceSession session,
const char *  ufrag,
const char *  pwd 
)

Tell if remote credentials of an ICE session have changed or not.

Parameters
sessionA pointer to a session
ufragThe new remote username fragment
pwdThe new remote password
Returns
TRUE if the remote credentials of the session have changed, FALSE otherwise.

◆ ice_session_remote_pwd()

const char * ice_session_remote_pwd ( const IceSession session)

Get the remote password of an ICE session.

Parameters
sessionA pointer to a session
Returns
A pointer to the remote password of the session

◆ ice_session_remote_ufrag()

const char * ice_session_remote_ufrag ( const IceSession session)

Get the remote username fragment of an ICE session.

Parameters
sessionA pointer to a session
Returns
A pointer to the remote username fragment of the session

◆ ice_session_remove_check_list()

void ice_session_remove_check_list ( IceSession session,
IceCheckList cl 
)

Remove an ICE check list from an ICE session.

Parameters
sessionThe session from which to remove the check list
clThe check list to remove from the session

◆ ice_session_remove_check_list_from_idx()

void ice_session_remove_check_list_from_idx ( IceSession session,
unsigned int  idx 
)

Remove an ICE check list from an ICE session given its index.

Parameters
sessionThe session from which to remove the check list
idxThe index of the check list in the ICE session

◆ ice_session_reset()

void ice_session_reset ( IceSession session,
IceRole  role 
)

Reset an ICE session. It has the same effect as a session restart but also clears the local candidates.

Parameters
sessionA pointer to a session
roleThe role of the agent after the session restart

◆ ice_session_restart()

void ice_session_restart ( IceSession session,
IceRole  role 
)

Restart an ICE session.

Parameters
sessionA pointer to a session
roleThe role of the agent after the session restart

◆ ice_session_role()

IceRole ice_session_role ( const IceSession session)

Get the role of the agent for an ICE session.

Parameters
sessionA pointer to a session
Returns
The role of the agent for the session

◆ ice_session_select_candidates()

void ice_session_select_candidates ( IceSession session)

Select ICE candidates that will be used and notified in the SDP.

Parameters
sessionA pointer to a session

This function is to be used by the Controlling agent when ICE processing has finished.

◆ ice_session_set_base_for_srflx_candidates()

void ice_session_set_base_for_srflx_candidates ( IceSession session)

Set the base for the local server reflexive candidates of an ICE session.

This function is usually not necessary, because the base candidate is automatically set during gathering. However, it is required when server-reflexive candidates are added manually into the session, which happens at least in these two cases:

  • in 'mediastream' tool for testing purpose to work around the fact that it does not use candidates gathering.
  • when server-reflexive candidates are defined by configuration, for example when ICE is used in a server software deployed behind a NAT. It is to be called before starting the connectivity checks.

◆ ice_session_set_default_candidates_ip_version()

void ice_session_set_default_candidates_ip_version ( IceSession session,
bool_t  ipv6_preferred 
)

Set the AF_INET/AF_INET6 preference for electing the default candidates, when both are available.

◆ ice_session_set_default_candidates_types()

void ice_session_set_default_candidates_types ( IceSession session,
const IceCandidateType  types[ICT_CandidateTypeMax] 
)

Set the prefered type for default candidates, as defined in rfc5245::section-4.1.4. The type table can be terminated by the ICT_CandidateInvalid element, may it contain less elements than the number of types available.

◆ ice_session_set_keepalive_timeout()

void ice_session_set_keepalive_timeout ( IceSession session,
uint8_t  timeout 
)

Define the timeout between each keepalive packet in seconds.

Parameters
sessionA pointer to a session
timeoutThe duration of the keepalive timeout in seconds

The default keepalive timeout is set to 15 seconds.

◆ ice_session_set_local_credentials()

void ice_session_set_local_credentials ( IceSession session,
const char *  ufrag,
const char *  pwd 
)

Set the local credentials of an ICE session.

This function SHOULD not be used. However, it is used by mediastream for testing purpose to apply the same credentials for local and remote agents because the SDP exchange is bypassed.

◆ ice_session_set_max_connectivity_checks()

void ice_session_set_max_connectivity_checks ( IceSession session,
uint8_t  max_connectivity_checks 
)

Define the maximum number of connectivity checks that will be performed by the agent.

Parameters
sessionA pointer to a session
max_connectivity_checksThe maximum number of connectivity checks to perform

This function is to be called just after the creation of the session, before any connectivity check is performed. The default number of connectivity checks is 100.

◆ ice_session_set_remote_credentials()

void ice_session_set_remote_credentials ( IceSession session,
const char *  ufrag,
const char *  pwd 
)

Set the remote credentials of an ICE session.

Parameters
sessionA pointer to a session
ufragThe remote username fragment
pwdThe remote password

This function is to be called once the remote credentials have been received via SDP.

◆ ice_session_set_role()

void ice_session_set_role ( IceSession session,
IceRole  role 
)

Set the role of the agent for an ICE session.

Parameters
sessionThe session for which to set the role
roleThe role to set the session to

◆ ice_session_set_turn_cn()

void ice_session_set_turn_cn ( IceSession session,
const char *  cn 
)

Set TURN CN when using TLS.

Parameters
sessionA pointer to a session
cnThe CN.

◆ ice_session_set_turn_root_certificate()

void ice_session_set_turn_root_certificate ( IceSession session,
const char *  root_certificate 
)

Set TURN root certificate path when using TLS.

Parameters
sessionA pointer to a session
root_certificateThe path of the root certificate.

◆ ice_session_set_turn_transport()

void ice_session_set_turn_transport ( IceSession session,
const char *  transport 
)

Set TURN transport.

Parameters
sessionA pointer to a session
transportThe transport that TURN should use (should be UDP, TCP or TLS).

◆ ice_session_start_connectivity_checks()

void ice_session_start_connectivity_checks ( IceSession session)

Pair the local and the remote candidates for an ICE session and start sending connectivity checks.

Parameters
sessionA pointer to a session

◆ ice_session_state()

IceSessionState ice_session_state ( const IceSession session)

Get the state of an ICE session.

Parameters
sessionA pointer to a session
Returns
The state of the session