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

mediastreamer2 ice.h include file More...

#include "mscommon.h"
#include "ortp/stun_udp.h"
#include "ortp/stun.h"
#include "ortp/ortp.h"
Include dependency graph for ice.h:

Data Structures

struct  _IceSession
 
struct  _IceTransportAddress
 
struct  _IceCandidate
 
struct  _IceCandidatePair
 
struct  _IcePairFoundation
 
struct  _IceCheckList
 

Typedefs

typedef struct _IceSession IceSession
 
typedef struct _IceTransportAddress IceTransportAddress
 
typedef struct _IceCandidate IceCandidate
 
typedef struct _IceCandidatePair IceCandidatePair
 
typedef struct _IcePairFoundation IcePairFoundation
 
typedef struct _IceCheckList IceCheckList
 

Enumerations

enum  IceRole
 
enum  IceCandidateType
 
enum  IceCandidatePairState
 
enum  IceCheckListState
 
enum  IceSessionState
 

Functions

IceSessionice_session_new (void)
 
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, unsigned 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)
 
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)
 
void ice_session_remove_check_list (IceSession *session, IceCheckList *cl)
 
bool_t ice_session_candidates_gathered (const IceSession *session)
 
void ice_session_gather_candidates (IceSession *session, struct sockaddr_storage ss, socklen_t ss_len)
 
int ice_session_gathering_duration (IceSession *session)
 
int ice_session_average_gathering_round_trip_time (IceSession *session)
 
void ice_session_select_candidates (IceSession *session)
 
void ice_session_restart (IceSession *session)
 
IceCheckListState ice_check_list_state (const IceCheckList *cl)
 
void ice_check_list_set_state (IceCheckList *cl, 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, const char **rtp_addr, int *rtp_port, const char **rtcp_addr, int *rtcp_port)
 
bool_t ice_check_list_selected_valid_local_candidate (const IceCheckList *cl, const char **rtp_addr, int *rtp_port, const char **rtcp_addr, int *rtcp_port)
 
bool_t ice_check_list_selected_valid_remote_candidate (const IceCheckList *cl, const char **rtp_addr, int *rtp_port, const char **rtcp_addr, int *rtcp_port)
 
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, const char *ip, int port, uint16_t componentID, IceCandidate *base)
 
IceCandidateice_add_remote_candidate (IceCheckList *cl, const char *type, 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, const char *local_addr, int local_port, const char *remote_addr, int remote_port)
 
int ice_session_nb_losing_pairs (const IceSession *session)
 
void ice_check_list_unselect_valid_pairs (IceCheckList *cl)
 
void ice_session_set_base_for_srflx_candidates (IceSession *session)
 
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_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.

Typedef Documentation

typedef struct _IceSession IceSession

Structure representing an ICE session.

Structure representing an ICE transport address.

typedef struct _IceCandidate IceCandidate

Structure representing an ICE candidate.

Structure representing an ICE candidate pair.

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.

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.

Enumeration Type Documentation

enum IceRole

ICE agent role.

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

ICE candidate type.

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

ICE candidate pair state.

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

ICE check list state.

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

ICE session state.

Function Documentation

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.

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.

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.

void ice_check_list_destroy ( IceCheckList cl)

Destroy a previously allocated ICE check list.

Parameters
clThe check list to destroy
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
sessionA pointer to a check list
Returns
TRUE if local candidates have been gathered for the check list, FALSE otherwise.
IceCheckList* ice_session_check_list ( const IceSession session,
unsigned 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
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
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
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
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
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
IceRole ice_session_role ( const IceSession session)

Gte the role of the agent for an ICE session.

Parameters
sessionA pointer to a session
Returns
The role of the agent for the session
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
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.

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.
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.

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.

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.

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
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
void ice_session_add_check_list ( IceSession session,
IceCheckList cl 
)

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
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
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.
void ice_session_gather_candidates ( IceSession session,
struct sockaddr_storage  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
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.
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.
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.

void ice_session_restart ( IceSession session)

Restart an ICE session.

Parameters
sessionA pointer to a session
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
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
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
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
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
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
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
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
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.
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.

bool_t ice_check_list_default_local_candidate ( const IceCheckList cl,
const char **  rtp_addr,
int *  rtp_port,
const char **  rtcp_addr,
int *  rtcp_port 
)

Get the default local candidate for an ICE check list.

Parameters
clA pointer to a check list
rtp_addrA pointer to store the RTP address
rtp_portA pointer to store the RTP port
rtcp_addrA pointer to store the RTCP address
rtcp_portA pointer to store the RTCP port
Returns
TRUE if the information have been successfully retrieved, FALSE otherwise
bool_t ice_check_list_selected_valid_local_candidate ( const IceCheckList cl,
const char **  rtp_addr,
int *  rtp_port,
const char **  rtcp_addr,
int *  rtcp_port 
)

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

Parameters
clA pointer to a check list
rtp_addrA pointer to store the RTP address
rtp_portA pointer to store the RTP port
rtcp_addrA pointer to store the RTCP address
rtcp_portA pointer to store the RTCP port
Returns
TRUE if the information have been successfully retrieved, FALSE otherwise
bool_t ice_check_list_selected_valid_remote_candidate ( const IceCheckList cl,
const char **  rtp_addr,
int *  rtp_port,
const char **  rtcp_addr,
int *  rtcp_port 
)

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

Parameters
clA pointer to a check list
rtp_addrA pointer to store the RTP address
rtp_portA pointer to store the RTP port
rtcp_addrA pointer to store the RTCP address
rtcp_portA pointer to store the RTCP port
Returns
TRUE if the information have been successfully retrieved, FALSE otherwise
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
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
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
IceCandidate* ice_add_local_candidate ( IceCheckList cl,
const char *  type,
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")
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.

IceCandidate* ice_add_remote_candidate ( IceCheckList cl,
const char *  type,
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")
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.

void ice_add_losing_pair ( IceCheckList cl,
uint16_t  componentID,
const char *  local_addr,
int  local_port,
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
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.

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.
void ice_check_list_unselect_valid_pairs ( IceCheckList cl)

Unselect the previously selected valid pairs.

Parameters
clA pointer to a check list

This function is to be used to use the pairs given by the remote controlling agent instead of the pairs we found ourselves.

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 SHOULD not be used. However, it is used by mediastream for testing purpose to work around the fact that it does not use candidates gathering. It is to be called automatically when the gathering process finishes.

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.

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.

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.

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.

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
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
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.

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.

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_aadrA 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().

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
void ice_dump_session ( const IceSession session)

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

void ice_dump_candidates ( const IceCheckList cl)

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

void ice_dump_candidate_pairs ( const IceCheckList cl)

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

void ice_dump_valid_list ( const IceCheckList cl)

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

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).

void ice_dump_componentIDs ( const IceCheckList cl)

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

void ice_dump_check_list ( const IceCheckList cl)

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

void ice_dump_triggered_checks_queue ( const IceCheckList cl)

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