mediastreamer2 5.2.0
|
mediastreamer2 ice.h include file More...
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 } |
mediastreamer2 ice.h include file
This file provides the API to handle the ICE protocol defined in the RFC 5245.
#define ICE_SESSION_MAX_CHECK_LISTS 8 |
The maximum number of check lists in an ICE session.
typedef struct _IceCandidate IceCandidate |
Structure representing an ICE candidate.
typedef struct _IceCandidatePair IceCandidatePair |
Structure representing an ICE candidate pair.
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.
typedef struct _IcePairFoundation 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.
typedef struct _IceSession IceSession |
Structure representing an ICE session.
typedef struct _IceTransportAddress IceTransportAddress |
Structure representing an ICE transport address.
ICE candidate pair state.
See paragraph 5.7.4 ("Computing states") of RFC 5245 for more details.
enum IceCandidateType |
ICE candidate type.
See the terminology in paragraph 3 of the RFC 5245 for more details.
enum IceCheckListState |
ICE check list state.
See paragraph 5.7.4 ("Computing states") of RFC 5245 for more details.
enum IceRole |
ICE agent role.
See the terminology in paragraph 3 of the RFC 5245 for more details.
enum IceSessionState |
ICE session state.
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.
cl | A pointer to a check list |
type | The type of the local candidate to add as a string (must be one of: "host", "srflx", "prflx" or "relay") |
family | The address family of the local candidate (AF_INET or AF_INET6) |
ip | The IP address of the local candidate as a string (eg. 192.168.0.10) |
port | The port of the local candidate |
componentID | The component ID of the local candidate (usually 1 for RTP and 2 for RTCP) |
base | A pointer to the base candidate of the candidate to add. |
This function is to be called when gathering local candidates.
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.
cl | A pointer to a check list |
componentID | The component ID of the candidates of the pair to add |
family | The address family of the candidates (AF_INET or AF_INET6) |
local_addr | The address of the local candidate of the pair to add |
local_port | The port of the local candidate of the pair to add |
remote_addr | The address of the remote candidate of the pair to add |
remote_port | The 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.
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.
cl | A pointer to a check list |
type | The type of the remote candidate to add as a string (must be one of: "host", "srflx", "prflx" or "relay") |
family | The address family of the remote candidate (AF_INET or AF_INET6) |
ip | The IP address of the remote candidate as a string (eg. 192.168.0.10) |
port | The port of the remote candidate |
componentID | The component ID of the remote candidate (usually 1 for RTP and 2 for RTCP) |
priority | The priority of the remote candidate |
foundation | The foundation of the remote candidate |
is_default | Boolean 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.
const char * ice_candidate_type | ( | const IceCandidate * | candidate | ) |
Get the candidate type as a string.
candidate | A pointer to a candidate |
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.
cl | A pointer to a check list |
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.
cl | A pointer to a check list |
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.
cl | A pointer to a check list |
rtp_candidate | A pointer to store the RTP default local candidate |
rtcp_candidate | A pointer to store the RTCP default local candidate |
void ice_check_list_destroy | ( | IceCheckList * | cl | ) |
Destroy a previously allocated ICE check list.
cl | The check list to destroy |
const char * ice_check_list_get_remote_pwd | ( | const IceCheckList * | cl | ) |
get the remote pwd of an ICE check list.
cl | A pointer to a check list |
This function is to be called once the remote credentials have been received via SDP.
const char * ice_check_list_get_remote_ufrag | ( | const IceCheckList * | cl | ) |
get the remote ufrag of an ICE check list.
cl | A pointer to a check list |
This function is to be called once the remote credentials have been received via SDP.
bool_t ice_check_list_is_mismatch | ( | const IceCheckList * | cl | ) |
Get the mismatch property of an ICE check list.
cl | A pointer to a check list |
const char * ice_check_list_local_pwd | ( | const IceCheckList * | cl | ) |
Get the local password of an ICE check list.
cl | A pointer to a check list |
const char * ice_check_list_local_ufrag | ( | const IceCheckList * | cl | ) |
Get the local username fragment of an ICE check list.
cl | A pointer to a check list |
IceCheckList * ice_check_list_new | ( | void | ) |
Allocate a new ICE 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_print_route | ( | const IceCheckList * | cl, |
const char * | message | ||
) |
Print the route used to send the stream if the ICE process has finished successfully.
cl | A pointer to a check list |
message | A message to print before the route |
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.
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.
cl | A pointer to a check list |
ufrag | The new remote username fragment |
pwd | The new remote password |
const char * ice_check_list_remote_pwd | ( | const IceCheckList * | cl | ) |
Get the remote password of an ICE check list.
cl | A pointer to a check list |
const char * ice_check_list_remote_ufrag | ( | const IceCheckList * | cl | ) |
Get the remote username fragment of an ICE check list.
cl | A pointer to a check list |
void ice_check_list_remove_rtcp_candidates | ( | IceCheckList * | cl | ) |
Remove local and remote RTCP candidates from an ICE check list.
cl | A pointer to a check list |
This function MUST be called before calling ice_session_start_connectivity_checks(). It is useful when using rtcp-mux.
IceCandidateType ice_check_list_selected_valid_candidate_type | ( | const IceCheckList * | cl | ) |
Get the type of the selected valid candidate for an ICE check list.
cl | A pointer to a check list |
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.
cl | A pointer to a check list |
rtp_candidate | A pointer to store the RTP valid local base candidate |
rtcp_candidate | A pointer to store the RTCP valid local base 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.
cl | A pointer to a check list |
rtp_candidate | A pointer to store the RTP valid local candidate |
rtcp_candidate | A pointer to store the RTCP valid local 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.
cl | A pointer to a check list |
rtp_candidate | A pointer to store the RTP valid remote candidate |
rtcp_candidate | A pointer to store the RTCP valid remote candidate |
void ice_check_list_set_remote_credentials | ( | IceCheckList * | cl, |
const char * | ufrag, | ||
const char * | pwd | ||
) |
Set the remote credentials of an ICE check list.
cl | A pointer to a check list |
ufrag | The remote username fragment |
pwd | The remote password |
This function is to be called once the remote credentials have been received via SDP.
void ice_check_list_set_rtp_session | ( | IceCheckList * | cl, |
RtpSession * | rtp_session | ||
) |
Assign an RTP session to an ICE check list.
cl | A pointer to a check list |
rtp_session | A pointer to the RTP session to assign to the check list |
void ice_check_list_set_state | ( | IceCheckList * | cl, |
IceCheckListState | state | ||
) |
Set the state of an ICE check list.
cl | A pointer to a check list |
state | The new state of the check list |
IceCheckListState ice_check_list_state | ( | const IceCheckList * | cl | ) |
Get the state of an ICE check list.
cl | A pointer to a check list |
const char * ice_check_list_state_to_string | ( | const IceCheckListState | state | ) |
Humanly readable IceCheckListState
state | The state of the check list |
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_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_candidates | ( | const IceCheckList * | cl | ) |
Dump the candidates 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_componentIDs | ( | const IceCheckList * | cl | ) |
Dump the list of component IDs of an ICE check list in the traces (debug function).
void ice_dump_session | ( | const IceSession * | session | ) |
Dump an ICE session 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).
void ice_dump_valid_list | ( | const IceCheckList * | cl | ) |
Dump the valid list of an ICE check list in the traces (debug function).
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.
cl | A pointer to a check list |
rtp_addr | A pointer to the buffer to use to store the remote RTP address |
rtp_port | A pointer to the location to store the RTP port to |
rtcp_addr | A pointer to the buffer to use to store the remote RTCP address |
rtcp_port | A pointer to the location to store the RTCP port to |
addr_len | The 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_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_session_add_check_list | ( | IceSession * | session, |
IceCheckList * | cl, | ||
unsigned int | idx | ||
) |
Add an ICE check list to an ICE session.
session | The session that is assigned the check list |
cl | The check list to assign to the session |
idx | The index of the check list to add |
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.
session | A pointer to a session |
bool_t ice_session_candidates_gathered | ( | const IceSession * | session | ) |
Tell whether ICE local candidates have been gathered for an ICE session or not.
session | A pointer to a session |
IceCheckList * ice_session_check_list | ( | const IceSession * | session, |
int | n | ||
) |
Get the nth check list of an ICE session.
session | A pointer to a session |
n | The number of the check list to access |
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.
session | A pointer to a session |
void ice_session_choose_default_candidates | ( | IceSession * | session | ) |
Choose the default candidates of an ICE session.
session | A 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_compute_candidates_foundations | ( | IceSession * | session | ) |
Compute the foundations of the local candidates of an ICE session.
session | A 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_destroy | ( | IceSession * | session | ) |
Destroy a previously allocated ICE session.
session | The session to destroy. |
To be used when a media session using ICE is tore down.
void ice_session_eliminate_redundant_candidates | ( | IceSession * | session | ) |
Eliminate the redundant candidates of an ICE session.
session | A 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_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.
session | A pointer to a session. |
enable | A boolean value telling whether to force relay or not. |
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
session | A pointer to a session |
enable | value |
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.
session | A pointer to a session |
enable | A boolean value telling whether to use short turn refresh. |
void ice_session_enable_turn | ( | IceSession * | session, |
bool_t | enable | ||
) |
Enable TURN protocol.
session | A pointer to a session |
enable | A boolean value telling whether to enable TURN protocol or not. |
bool_t ice_session_gather_candidates | ( | IceSession * | session, |
const struct sockaddr * | ss, | ||
socklen_t | ss_len | ||
) |
Gather ICE local candidates for an ICE session.
session | A pointer to a session |
ss | The STUN server address |
ss_len | The 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.
session | A pointer to a session |
bool_t ice_session_has_completed_check_list | ( | const IceSession * | session | ) |
Tell whether an ICE session has at least one completed check list.
session | A pointer to a session |
const char * ice_session_local_pwd | ( | const IceSession * | session | ) |
Get the local password of an ICE session.
session | A pointer to a session |
const char * ice_session_local_ufrag | ( | const IceSession * | session | ) |
Get the local username fragment of an ICE session.
session | A pointer to a session |
int ice_session_nb_check_lists | ( | IceSession * | session | ) |
Get the number of check lists in an ICE session.
session | A pointer to a session |
int ice_session_nb_losing_pairs | ( | const IceSession * | session | ) |
Get the number of losing candidate pairs for an ICE session.
session | A pointer to a session |
IceSession * ice_session_new | ( | void | ) |
Allocate a new ICE session.
This must be performed for each media session that is to use ICE.
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.
session | A pointer to a session |
ufrag | The new remote username fragment |
pwd | The new remote password |
const char * ice_session_remote_pwd | ( | const IceSession * | session | ) |
Get the remote password of an ICE session.
session | A pointer to a session |
const char * ice_session_remote_ufrag | ( | const IceSession * | session | ) |
Get the remote username fragment of an ICE session.
session | A pointer to a session |
void ice_session_remove_check_list | ( | IceSession * | session, |
IceCheckList * | cl | ||
) |
Remove an ICE check list from an ICE session.
session | The session from which to remove the check list |
cl | The check list to remove from the session |
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.
session | The session from which to remove the check list |
idx | The index of the check list in the ICE session |
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.
session | A pointer to a session |
role | The role of the agent after the session restart |
void ice_session_restart | ( | IceSession * | session, |
IceRole | role | ||
) |
Restart an ICE session.
session | A pointer to a session |
role | The role of the agent after the session restart |
IceRole ice_session_role | ( | const IceSession * | session | ) |
Get the role of the agent for an ICE session.
session | A pointer to a session |
void ice_session_select_candidates | ( | IceSession * | session | ) |
Select ICE candidates that will be used and notified in the SDP.
session | A pointer to a session |
This function is to be used by the Controlling agent when ICE processing has finished.
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:
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.
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.
void ice_session_set_keepalive_timeout | ( | IceSession * | session, |
uint8_t | timeout | ||
) |
Define the timeout between each keepalive packet in seconds.
session | A pointer to a session |
timeout | The duration of the keepalive timeout in seconds |
The default keepalive timeout is set to 15 seconds.
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.
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.
session | A pointer to a session |
max_connectivity_checks | The 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_remote_credentials | ( | IceSession * | session, |
const char * | ufrag, | ||
const char * | pwd | ||
) |
Set the remote credentials of an ICE session.
session | A pointer to a session |
ufrag | The remote username fragment |
pwd | The remote password |
This function is to be called once the remote credentials have been received via SDP.
void ice_session_set_role | ( | IceSession * | session, |
IceRole | role | ||
) |
Set the role of the agent for an ICE session.
session | The session for which to set the role |
role | The role to set the session to |
void ice_session_set_turn_cn | ( | IceSession * | session, |
const char * | cn | ||
) |
Set TURN CN when using TLS.
session | A pointer to a session |
cn | The CN. |
void ice_session_set_turn_root_certificate | ( | IceSession * | session, |
const char * | root_certificate | ||
) |
Set TURN root certificate path when using TLS.
session | A pointer to a session |
root_certificate | The path of the root certificate. |
void ice_session_set_turn_transport | ( | IceSession * | session, |
const char * | transport | ||
) |
Set TURN transport.
session | A pointer to a session |
transport | The transport that TURN should use (should be UDP, TCP or TLS). |
void ice_session_start_connectivity_checks | ( | IceSession * | session | ) |
Pair the local and the remote candidates for an ICE session and start sending connectivity checks.
session | A pointer to a session |
IceSessionState ice_session_state | ( | const IceSession * | session | ) |
Get the state of an ICE session.
session | A pointer to a session |