mediastreamer2
2.9.1
|
mediastreamer2 ice.h include file More...
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 |
mediastreamer2 ice.h include file
This file provides the API to handle the ICE protocol defined in the RFC 5245.
typedef struct _IceSession IceSession |
Structure representing an ICE session.
typedef struct _IceTransportAddress IceTransportAddress |
Structure representing an ICE transport address.
typedef struct _IceCandidate IceCandidate |
Structure representing an ICE candidate.
typedef struct _IceCandidatePair IceCandidatePair |
Structure representing an ICE candidate pair.
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 _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.
enum IceRole |
ICE agent role.
See the terminology in paragraph 3 of the RFC 5245 for more details.
enum IceCandidateType |
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.
enum IceCheckListState |
ICE check list state.
See paragraph 5.7.4 ("Computing states") of RFC 5245 for more details.
enum IceSessionState |
ICE session state.
IceSession* ice_session_new | ( | void | ) |
Allocate a new ICE 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.
session | The 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.
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.
cl | The 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.
session | A pointer to a check list |
IceCheckList* ice_session_check_list | ( | const IceSession * | session, |
unsigned 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 |
const char* ice_session_local_ufrag | ( | const IceSession * | session | ) |
Get the local username fragment of an ICE session.
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_remote_ufrag | ( | const IceSession * | session | ) |
Get the remote username fragment of an ICE session.
session | A pointer to a session |
const char* ice_session_remote_pwd | ( | const IceSession * | session | ) |
Get the remote password of an ICE session.
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 |
IceRole ice_session_role | ( | const IceSession * | session | ) |
Gte the role of the agent for an ICE session.
session | A pointer to a session |
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_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.
session | A pointer to a session |
ufrag | The new remote username fragment |
pwd | The new remote password |
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_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_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.
int ice_session_nb_check_lists | ( | IceSession * | session | ) |
Get the number of check lists in an ICE session.
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 |
void ice_session_add_check_list | ( | IceSession * | session, |
IceCheckList * | cl | ||
) |
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 |
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 |
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 |
void ice_session_gather_candidates | ( | IceSession * | session, |
struct sockaddr_storage | 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 |
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 |
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_restart | ( | IceSession * | session | ) |
Restart an ICE session.
session | A pointer to a session |
IceCheckListState ice_check_list_state | ( | const IceCheckList * | cl | ) |
Get the state of an ICE check list.
cl | A pointer to a 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 |
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 |
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 |
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_remote_ufrag | ( | const IceCheckList * | cl | ) |
Get the remote username fragment of an ICE check list.
cl | A pointer to a check list |
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 |
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 |
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 |
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.
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.
cl | A pointer to a check list |
rtp_addr | A pointer to store the RTP address |
rtp_port | A pointer to store the RTP port |
rtcp_addr | A pointer to store the RTCP address |
rtcp_port | A pointer to store the 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 | ||
) |
Get the selected valid local candidate for an ICE check list.
cl | A pointer to a check list |
rtp_addr | A pointer to store the RTP address |
rtp_port | A pointer to store the RTP port |
rtcp_addr | A pointer to store the RTCP address |
rtcp_port | A pointer to store the 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 | ||
) |
Get the selected valid remote candidate for an ICE check list.
cl | A pointer to a check list |
rtp_addr | A pointer to store the RTP address |
rtp_port | A pointer to store the RTP port |
rtcp_addr | A pointer to store the RTCP address |
rtcp_port | A pointer to store the RTCP port |
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 |
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 |
const char* ice_candidate_type | ( | const IceCandidate * | candidate | ) |
Get the candidate type as a string.
candidate | A pointer to a candidate |
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.
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") |
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.
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.
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") |
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.
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.
cl | A pointer to a check list |
componentID | The component ID of the candidates of the pair to add |
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.
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 |
void ice_check_list_unselect_valid_pairs | ( | IceCheckList * | cl | ) |
Unselect the previously selected valid pairs.
cl | A 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.
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_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_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_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 |
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_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.
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_aadr | 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_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_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).