1/*
2mediastreamer2 library - modular sound and video processing and streaming
3Copyright (C) 2012 Belledonne Communications
4
5This program is free software; you can redistribute it and/or
6modify it under the terms of the GNU General Public License
7as published by the Free Software Foundation; either version 2
8of the License, or (at your option) any later version.
9
10This program is distributed in the hope that it will be useful,
11but WITHOUT ANY WARRANTY; without even the implied warranty of
12MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
13GNU General Public License for more details.
14
15You should have received a copy of the GNU General Public License
16along with this program; if not, write to the Free Software
17Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA.
18*/
19
20#ifndef ice_h
21#define ice_h
22
23#include "mscommon.h"
24#include "ortp/stun_udp.h"
25#include "ortp/stun.h"
26#include "ortp/ortp.h"
27
28
29/**
30 * @file ice.h
31 * @brief mediastreamer2 ice.h include file
32 *
33 * This file provides the API to handle the ICE protocol defined in the RFC 5245.
34 */
35
36
37/**
38 * ICE agent role.
39 *
40 * See the terminology in paragraph 3 of the RFC 5245 for more details.
41 */
42typedef enum {
43 IR_Controlling,
44 IR_Controlled
45} IceRole;
46
47/**
48 * ICE candidate type.
49 *
50 * See the terminology in paragraph 3 of the RFC 5245 for more details.
51 */
52typedef enum {
53 ICT_HostCandidate,
54 ICT_ServerReflexiveCandidate,
55 ICT_PeerReflexiveCandidate,
56 ICT_RelayedCandidate
57} IceCandidateType;
58
59/**
60 * ICE candidate pair state.
61 *
62 * See paragraph 5.7.4 ("Computing states") of RFC 5245 for more details.
63 */
64typedef enum {
65 ICP_Waiting,
66 ICP_InProgress,
67 ICP_Succeeded,
68 ICP_Failed,
69 ICP_Frozen
70} IceCandidatePairState;
71
72/**
73 * ICE check list state.
74 *
75 * See paragraph 5.7.4 ("Computing states") of RFC 5245 for more details.
76 */
77typedef enum {
78 ICL_Running,
79 ICL_Completed,
80 ICL_Failed
81} IceCheckListState;
82
83/**
84 * ICE session state.
85 */
86typedef enum {
87 IS_Stopped,
88 IS_Running,
89 IS_Completed,
90 IS_Failed
91} IceSessionState;
92
93/**
94 * Structure representing an ICE session.
95 */
96typedef struct _IceSession {
97 MSList *streams; /**< List of IceChecklist structures. Each element of the list represents a media stream */
98 char *local_ufrag; /**< Local username fragment for the session (assigned during the session creation) */
99 char *local_pwd; /**< Local password for the session (assigned during the session creation) */
100 char *remote_ufrag; /**< Remote username fragment for the session (provided via SDP by the peer) */
101 char *remote_pwd; /**< Remote password for the session (provided via SDP by the peer) */
102 IceRole role; /**< Role played by the agent for this session */
103 IceSessionState state; /**< State of the session */
104 uint64_t tie_breaker; /**< Random number used to resolve role conflicts (see paragraph 5.2 of the RFC 5245) */
105 uint32_t ta; /**< Duration of timer for sending connectivity checks in ms */
106 uint8_t max_connectivity_checks; /**< Configuration parameter to limit the number of connectivity checks performed by the agent (default is 100) */
107 uint8_t keepalive_timeout; /**< Configuration parameter to define the timeout between each keepalive packets (default is 15s) */
108 MSTimeSpec event_time; /**< Time when an event must be sent */
109 int event_value; /** Value of the event to send */
110 bool_t send_event; /**< Boolean value telling whether an event must be sent or not */
111 struct sockaddr_storage ss; /**< STUN server address to use for the candidates gathering process */
112 socklen_t ss_len; /**< Length of the STUN server address to use for the candidates gathering process */
113 MSTimeSpec gathering_start_ts;
114 MSTimeSpec gathering_end_ts;
115} IceSession;
116
117typedef struct _IceStunServerCheckTransaction {
118 UInt96 transactionID;
119 MSTimeSpec request_time;
120 MSTimeSpec response_time;
121} IceStunServerCheckTransaction;
122
123typedef struct _IceStunServerCheck {
124 ortp_socket_t sock;
125 int srcport;
126 MSList *transactions; /**< List of IceStunServerCheckTransaction structures. */
127 MSTimeSpec next_transmission_time;
128 bool_t responded;
129} IceStunServerCheck;
130
131/**
132 * Structure representing an ICE transport address.
133 */
134typedef struct _IceTransportAddress {
135 char ip[64];
136 int port;
137 // TODO: Handling of IP version (4 or 6) and transport type: TCP, UDP...
138} IceTransportAddress;
139
140/**
141 * Structure representing an ICE candidate.
142 */
143typedef struct _IceCandidate {
144 char foundation[32]; /**< Foundation of the candidate (see paragraph 3 of the RFC 5245 for more details */
145 IceTransportAddress taddr; /**< Transport address of the candidate */
146 IceCandidateType type; /**< Type of the candidate */
147 uint32_t priority; /**< Priority of the candidate */
148 uint16_t componentID; /**< component ID between 1 and 256: usually 1 for RTP component and 2 for RTCP component */
149 struct _IceCandidate *base; /**< Pointer to the candidate that is the base of the current one */
150 bool_t is_default; /**< Boolean value telling whether this candidate is a default candidate or not */
151} IceCandidate;
152
153/**
154 * Structure representing an ICE candidate pair.
155 */
156typedef struct _IceCandidatePair {
157 IceCandidate *local; /**< Pointer to the local candidate of the pair */
158 IceCandidate *remote; /**< Pointer to the remote candidate of the pair */
159 IceCandidatePairState state; /**< State of the candidate pair */
160 uint64_t priority; /**< Priority of the candidate pair */
161 MSTimeSpec transmission_time; /**< Time when the connectivity check for the candidate pair has been sent */
162 uint32_t rto; /**< Duration of the retransmit timer for the connectivity check sent for the candidate pair in ms */
163 uint8_t retransmissions; /**< Number of retransmissions for the connectivity check sent for the candidate pair */
164 IceRole role; /**< Role of the agent when the connectivity check has been sent for the candidate pair */
165 bool_t is_default; /**< Boolean value telling whether this candidate pair is a default candidate pair or not */
166 bool_t use_candidate; /**< Boolean value telling if the USE-CANDIDATE attribute must be set for the connectivity checks send for the candidate pair */
167 bool_t is_nominated; /**< Boolean value telling whether this candidate pair is nominated or not */
168 bool_t wait_transaction_timeout; /**< Boolean value telling to create a new binding request on retransmission timeout */
169} IceCandidatePair;
170
171/**
172 * Structure representing the foundation of an ICE candidate pair.
173 *
174 * It is the concatenation of the foundation of a local candidate and the foundation of a remote candidate.
175 */
176typedef struct _IcePairFoundation {
177 char local[32]; /**< Foundation of the local candidate */
178 char remote[32]; /**< Foundation of the remote candidate */
179} IcePairFoundation;
180
181typedef struct _IceValidCandidatePair {
182 IceCandidatePair *valid; /**< Pointer to a valid candidate pair (it may be in the check list or not */
183 IceCandidatePair *generated_from; /**< Pointer to the candidate pair that generated the connectivity check producing the valid candidate pair */
184 bool_t selected; /**< Boolean value telling whether this valid candidate pair has been selected or not */
185} IceValidCandidatePair;
186
187typedef struct _IceTransaction {
188 UInt96 transactionID; /**< Transaction ID of the connectivity check sent for the candidate pair */
189 IceCandidatePair *pair; /**< A pointer to the candidate pair associated with the transaction. */
190} IceTransaction;
191
192/**
193 * Structure representing an ICE check list.
194 *
195 * Each media stream must be assigned a check list.
196 * Check lists are added to an ICE session using the ice_session_add_check_list() function.
197 */
198typedef struct _IceCheckList {
199 IceSession *session; /**< Pointer to the ICE session */
200 RtpSession *rtp_session; /**< Pointer to the RTP session associated with this ICE check list */
201 char *remote_ufrag; /**< Remote username fragment for this check list (provided via SDP by the peer) */
202 char *remote_pwd; /**< Remote password for this check list (provided via SDP by the peer) */
203 MSList *stun_server_checks; /**< List of IceStunServerCheck structures */
204 MSList *local_candidates; /**< List of IceCandidate structures */
205 MSList *remote_candidates; /**< List of IceCandidate structures */
206 MSList *pairs; /**< List of IceCandidatePair structures */
207 MSList *losing_pairs; /**< List of IceCandidatePair structures */
208 MSList *triggered_checks_queue; /**< List of IceCandidatePair structures */
209 MSList *check_list; /**< List of IceCandidatePair structures */
210 MSList *valid_list; /**< List of IceValidCandidatePair structures */
211 MSList *foundations; /**< List of IcePairFoundation structures */
212 MSList *local_componentIDs; /**< List of uint16_t */
213 MSList *remote_componentIDs; /**< List of uint16_t */
214 MSList *transaction_list; /**< List of IceTransaction structures */
215 IceCheckListState state; /**< Global state of the ICE check list */
216 MSTimeSpec ta_time; /**< Time when the Ta timer has been processed for the last time */
217 MSTimeSpec keepalive_time; /**< Time when the last keepalive packet has been sent for this stream */
218 uint32_t foundation_generator; /**< Autoincremented integer to generate unique foundation values */
219 bool_t mismatch; /**< Boolean value telling whether there was a mismatch during the answer/offer process */
220 bool_t gathering_candidates; /**< Boolean value telling whether a candidate gathering process is running or not */
221 bool_t gathering_finished; /**< Boolean value telling whether the candidate gathering process has finished or not */
222 bool_t nomination_delay_running; /**< Boolean value telling whether the nomination process has been delayed or not */
223 MSTimeSpec gathering_start_time; /**< Time when the gathering process was started */
224 MSTimeSpec nomination_delay_start_time; /**< Time when the nomination process has been delayed */
225} IceCheckList;
226
227
228
229#ifdef __cplusplus
230extern "C"{
231#endif
232
233/**
234 * Allocate a new ICE session.
235 *
236 * @return Pointer to the allocated session
237 *
238 * This must be performed for each media session that is to use ICE.
239 */
240MS2_PUBLIC IceSession * ice_session_new(void);
241
242/**
243 * Destroy a previously allocated ICE session.
244 *
245 * @param session The session to destroy.
246 *
247 * To be used when a media session using ICE is tore down.
248 */
249MS2_PUBLIC void ice_session_destroy(IceSession *session);
250
251/**
252 * Allocate a new ICE check list.
253 *
254 * @return Pointer to the allocated check list
255 *
256 * 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.
257 */
258MS2_PUBLIC IceCheckList * ice_check_list_new(void);
259
260/**
261 * Destroy a previously allocated ICE check list.
262 *
263 * @param cl The check list to destroy
264 */
265MS2_PUBLIC void ice_check_list_destroy(IceCheckList *cl);
266
267/**
268 * Tell whether ICE local candidates have been gathered for an ICE check list or not.
269 *
270 * @param session A pointer to a check list
271 * @return TRUE if local candidates have been gathered for the check list, FALSE otherwise.
272 */
273MS2_PUBLIC bool_t ice_check_list_candidates_gathered(const IceCheckList *cl);
274
275/**
276 * Get the nth check list of an ICE session.
277 *
278 * @param session A pointer to a session
279 * @param n The number of the check list to access
280 * @return A pointer to the nth check list of the session if it exists, NULL otherwise
281 */
282MS2_PUBLIC IceCheckList *ice_session_check_list(const IceSession *session, unsigned int n);
283
284/**
285 * Get the local username fragment of an ICE session.
286 *
287 * @param session A pointer to a session
288 * @return A pointer to the local username fragment of the session
289 */
290MS2_PUBLIC const char * ice_session_local_ufrag(const IceSession *session);
291
292/**
293 * Get the local password of an ICE session.
294 *
295 * @param session A pointer to a session
296 * @return A pointer to the local password of the session
297 */
298MS2_PUBLIC const char * ice_session_local_pwd(const IceSession *session);
299
300/**
301 * Get the remote username fragment of an ICE session.
302 *
303 * @param session A pointer to a session
304 * @return A pointer to the remote username fragment of the session
305 */
306MS2_PUBLIC const char * ice_session_remote_ufrag(const IceSession *session);
307
308/**
309 * Get the remote password of an ICE session.
310 *
311 * @param session A pointer to a session
312 * @return A pointer to the remote password of the session
313 */
314MS2_PUBLIC const char * ice_session_remote_pwd(const IceSession *session);
315
316/**
317 * Get the state of an ICE session.
318 *
319 * @param session A pointer to a session
320 * @return The state of the session
321 */
322MS2_PUBLIC IceSessionState ice_session_state(const IceSession *session);
323
324/**
325 * Gte the role of the agent for an ICE session.
326 *
327 * @param session A pointer to a session
328 * @return The role of the agent for the session
329 */
330MS2_PUBLIC IceRole ice_session_role(const IceSession *session);
331
332/**
333 * Set the role of the agent for an ICE session.
334 *
335 * @param session The session for which to set the role
336 * @param role The role to set the session to
337 */
338MS2_PUBLIC void ice_session_set_role(IceSession *session, IceRole role);
339
340/**
341 * Set the local credentials of an ICE session.
342 *
343 * This function SHOULD not be used. However, it is used by mediastream for testing purpose to
344 * apply the same credentials for local and remote agents because the SDP exchange is bypassed.
345 */
346MS2_PUBLIC void ice_session_set_local_credentials(IceSession *session, const char *ufrag, const char *pwd);
347
348/**
349 * Tell if remote credentials of an ICE session have changed or not.
350 *
351 * @param session A pointer to a session
352 * @param ufrag The new remote username fragment
353 * @param pwd The new remote password
354 * @return TRUE if the remote credentials of the session have changed, FALSE otherwise.
355 */
356MS2_PUBLIC bool_t ice_session_remote_credentials_changed(IceSession *session, const char *ufrag, const char *pwd);
357
358/**
359 * Set the remote credentials of an ICE session.
360 *
361 * @param session A pointer to a session
362 * @param ufrag The remote username fragment
363 * @param pwd The remote password
364 *
365 * This function is to be called once the remote credentials have been received via SDP.
366 */
367MS2_PUBLIC void ice_session_set_remote_credentials(IceSession *session, const char *ufrag, const char *pwd);
368
369/**
370 * Define the maximum number of connectivity checks that will be performed by the agent.
371 *
372 * @param session A pointer to a session
373 * @param max_connectivity_checks The maximum number of connectivity checks to perform
374 *
375 * This function is to be called just after the creation of the session, before any connectivity check is performed.
376 * The default number of connectivity checks is 100.
377 */
378MS2_PUBLIC void ice_session_set_max_connectivity_checks(IceSession *session, uint8_t max_connectivity_checks);
379
380/**
381 * Define the timeout between each keepalive packet in seconds.
382 *
383 * @param session A pointer to a session
384 * @param timeout The duration of the keepalive timeout in seconds
385 *
386 * The default keepalive timeout is set to 15 seconds.
387 */
388MS2_PUBLIC void ice_session_set_keepalive_timeout(IceSession *session, uint8_t timeout);
389
390/**
391 * Get the number of check lists in an ICE session.
392 *
393 * @param session A pointer to a session
394 * @return The number of check lists in the ICE session
395 */
396MS2_PUBLIC int ice_session_nb_check_lists(IceSession *session);
397
398/**
399 * Tell whether an ICE session has at least one completed check list.
400 *
401 * @param session A pointer to a session
402 * @return TRUE if the session has at least one completed check list, FALSE otherwise
403 */
404MS2_PUBLIC bool_t ice_session_has_completed_check_list(const IceSession *session);
405
406/**
407 * Add an ICE check list to an ICE session.
408 *
409 * @param session The session that is assigned the check list
410 * @param cl The check list to assign to the session
411 */
412MS2_PUBLIC void ice_session_add_check_list(IceSession *session, IceCheckList *cl);
413
414/**
415 * Remove an ICE check list from an ICE session.
416 *
417 * @param session The session from which to remove the check list
418 * @param cl The check list to remove from the session
419 */
420MS2_PUBLIC void ice_session_remove_check_list(IceSession *session, IceCheckList *cl);
421
422/**
423 * Tell whether ICE local candidates have been gathered for an ICE session or not.
424 *
425 * @param session A pointer to a session
426 * @return TRUE if local candidates have been gathered for the session, FALSE otherwise.
427 */
428MS2_PUBLIC bool_t ice_session_candidates_gathered(const IceSession *session);
429
430/**
431 * Gather ICE local candidates for an ICE session.
432 *
433 * @param session A pointer to a session
434 * @param ss The STUN server address
435 * @param ss_len The length of the STUN server address
436 */
437MS2_PUBLIC void ice_session_gather_candidates(IceSession *session, const struct sockaddr * ss, socklen_t ss_len);
438
439/**
440 * Tell the duration of the gathering process for an ICE session in ms.
441 *
442 * @param session A pointer to a session
443 * @return -1 if gathering has not been run, the duration of the gathering process in ms otherwise.
444 */
445MS2_PUBLIC int ice_session_gathering_duration(IceSession *session);
446
447/**
448 * Tell the average round trip time during the gathering process for an ICE session in ms.
449 *
450 * @param session A pointer to a session
451 * @return -1 if gathering has not been run, the average round trip time in ms otherwise.
452 */
453MS2_PUBLIC int ice_session_average_gathering_round_trip_time(IceSession *session);
454
455/**
456 * Select ICE candidates that will be used and notified in the SDP.
457 *
458 * @param session A pointer to a session
459 *
460 * This function is to be used by the Controlling agent when ICE processing has finished.
461 */
462MS2_PUBLIC void ice_session_select_candidates(IceSession *session);
463
464/**
465 * Restart an ICE session.
466 *
467 * @param session A pointer to a session
468 */
469MS2_PUBLIC void ice_session_restart(IceSession *session);
470
471/**
472 * Get the state of an ICE check list.
473 *
474 * @param cl A pointer to a check list
475 * @return The check list state
476 */
477MS2_PUBLIC IceCheckListState ice_check_list_state(const IceCheckList *cl);
478
479/**
480 * Set the state of an ICE check list.
481 *
482 * @param cl A pointer to a check list
483 * @param state The new state of the check list
484 */
485MS2_PUBLIC void ice_check_list_set_state(IceCheckList *cl, IceCheckListState state);
486
487/**
488 * Assign an RTP session to an ICE check list.
489 *
490 * @param cl A pointer to a check list
491 * @param rtp_session A pointer to the RTP session to assign to the check list
492 */
493MS2_PUBLIC void ice_check_list_set_rtp_session(IceCheckList *cl, RtpSession *rtp_session);
494
495/**
496 * Get the local username fragment of an ICE check list.
497 *
498 * @param cl A pointer to a check list
499 * @return A pointer to the local username fragment of the check list
500 */
501MS2_PUBLIC const char * ice_check_list_local_ufrag(const IceCheckList *cl);
502
503/**
504 * Get the local password of an ICE check list.
505 *
506 * @param cl A pointer to a check list
507 * @return A pointer to the local password of the check list
508 */
509MS2_PUBLIC const char * ice_check_list_local_pwd(const IceCheckList *cl);
510
511/**
512 * Get the remote username fragment of an ICE check list.
513 *
514 * @param cl A pointer to a check list
515 * @return A pointer to the remote username fragment of the check list
516 */
517MS2_PUBLIC const char * ice_check_list_remote_ufrag(const IceCheckList *cl);
518
519/**
520 * Get the remote password of an ICE check list.
521 *
522 * @param cl A pointer to a check list
523 * @return A pointer to the remote password of the check list
524 */
525MS2_PUBLIC const char * ice_check_list_remote_pwd(const IceCheckList *cl);
526
527/**
528 * Get the mismatch property of an ICE check list.
529 *
530 * @param cl A pointer to a check list
531 * @return TRUE if there was a mismatch for the check list, FALSE otherwise
532 */
533MS2_PUBLIC bool_t ice_check_list_is_mismatch(const IceCheckList *cl);
534
535/**
536 * Tell if remote credentials of an ICE check list have changed or not.
537 *
538 * @param cl A pointer to a check list
539 * @param ufrag The new remote username fragment
540 * @param pwd The new remote password
541 * @return TRUE if the remote credentials of the check list have changed, FALSE otherwise.
542 */
543MS2_PUBLIC bool_t ice_check_list_remote_credentials_changed(IceCheckList *cl, const char *ufrag, const char *pwd);
544
545/**
546 * Set the remote credentials of an ICE check list.
547 *
548 * @param cl A pointer to a check list
549 * @param ufrag The remote username fragment
550 * @param pwd The remote password
551 *
552 * This function is to be called once the remote credentials have been received via SDP.
553 */
554MS2_PUBLIC void ice_check_list_set_remote_credentials(IceCheckList *cl, const char *ufrag, const char *pwd);
555
556/**
557 * Get the default local candidate for an ICE check list.
558 *
559 * @param cl A pointer to a check list
560 * @param rtp_addr A pointer to store the RTP address
561 * @param rtp_port A pointer to store the RTP port
562 * @param rtcp_addr A pointer to store the RTCP address
563 * @param rtcp_port A pointer to store the RTCP port
564 * @return TRUE if the information have been successfully retrieved, FALSE otherwise
565 */
566MS2_PUBLIC 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);
567
568/**
569 * Get the selected valid local candidate for an ICE check list.
570 *
571 * @param cl A pointer to a check list
572 * @param rtp_addr A pointer to store the RTP address
573 * @param rtp_port A pointer to store the RTP port
574 * @param rtcp_addr A pointer to store the RTCP address
575 * @param rtcp_port A pointer to store the RTCP port
576 * @return TRUE if the information have been successfully retrieved, FALSE otherwise
577 */
578MS2_PUBLIC 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);
579
580/**
581 * Get the selected valid remote candidate for an ICE check list.
582 *
583 * @param cl A pointer to a check list
584 * @param rtp_addr A pointer to store the RTP address
585 * @param rtp_port A pointer to store the RTP port
586 * @param rtcp_addr A pointer to store the RTCP address
587 * @param rtcp_port A pointer to store the RTCP port
588 * @return TRUE if the information have been successfully retrieved, FALSE otherwise
589 */
590MS2_PUBLIC 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);
591
592/**
593 * Get the type of the selected valid candidate for an ICE check list.
594 *
595 * @param cl A pointer to a check list
596 * @return The type of the selected valid candidate
597 */
598MS2_PUBLIC IceCandidateType ice_check_list_selected_valid_candidate_type(const IceCheckList *cl);
599
600/**
601 * Check if an ICE check list can be set in the Completed state after handling losing pairs.
602 *
603 * @param cl A pointer to a check list
604 */
605MS2_PUBLIC void ice_check_list_check_completed(IceCheckList *cl);
606
607/**
608 * Get the candidate type as a string.
609 *
610 * @param candidate A pointer to a candidate
611 * @return A pointer to the candidate type as a string
612 */
613MS2_PUBLIC const char * ice_candidate_type(const IceCandidate *candidate);
614
615/**
616 * Add a local candidate to an ICE check list.
617 *
618 * @param cl A pointer to a check list
619 * @param type The type of the local candidate to add as a string (must be one of: "host", "srflx", "prflx" or "relay")
620 * @param ip The IP address of the local candidate as a string (eg. 192.168.0.10)
621 * @param port The port of the local candidate
622 * @param componentID The component ID of the local candidate (usually 1 for RTP and 2 for RTCP)
623 * @param base A pointer to the base candidate of the candidate to add.
624 *
625 * This function is to be called when gathering local candidates.
626 */
627MS2_PUBLIC IceCandidate * ice_add_local_candidate(IceCheckList *cl, const char *type, const char *ip, int port, uint16_t componentID, IceCandidate *base);
628
629/**
630 * Add a remote candidate to an ICE check list.
631 *
632 * @param cl A pointer to a check list
633 * @param type The type of the remote candidate to add as a string (must be one of: "host", "srflx", "prflx" or "relay")
634 * @param ip The IP address of the remote candidate as a string (eg. 192.168.0.10)
635 * @param port The port of the remote candidate
636 * @param componentID The component ID of the remote candidate (usually 1 for RTP and 2 for RTCP)
637 * @param priority The priority of the remote candidate
638 * @param foundation The foundation of the remote candidate
639 * @param is_default Boolean value telling whether the remote candidate is a default candidate or not
640 *
641 * This function is to be called once the remote candidate list has been received via SDP.
642 */
643MS2_PUBLIC 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);
644
645/**
646 * Add a losing pair to an ICE check list.
647 *
648 * @param cl A pointer to a check list
649 * @param componentID The component ID of the candidates of the pair to add
650 * @param local_addr The address of the local candidate of the pair to add
651 * @param local_port The port of the local candidate of the pair to add
652 * @param remote_addr The address of the remote candidate of the pair to add
653 * @param remote_port The port of the remote candidate of the pair to add
654 *
655 * This function is to be called when a RE-INVITE with an SDP containing a remote-candidates attribute is received.
656 */
657MS2_PUBLIC void ice_add_losing_pair(IceCheckList *cl, uint16_t componentID, const char *local_addr, int local_port, const char *remote_addr, int remote_port);
658
659/**
660 * Get the number of losing candidate pairs for an ICE session.
661 *
662 * @param session A pointer to a session
663 * @return The number of losing candidate pairs for the session.
664 */
665MS2_PUBLIC int ice_session_nb_losing_pairs(const IceSession *session);
666
667/**
668 * Unselect the previously selected valid pairs.
669 *
670 * @param cl A pointer to a check list
671 *
672 * This function is to be used to use the pairs given by the remote controlling agent instead of the pairs we found ourselves.
673 */
674MS2_PUBLIC void ice_check_list_unselect_valid_pairs(IceCheckList *cl);
675
676/**
677 * Set the base for the local server reflexive candidates of an ICE session.
678 *
679 * This function SHOULD not be used. However, it is used by mediastream for testing purpose to
680 * work around the fact that it does not use candidates gathering.
681 * It is to be called automatically when the gathering process finishes.
682 */
683MS2_PUBLIC void ice_session_set_base_for_srflx_candidates(IceSession *session);
684
685/**
686 * Compute the foundations of the local candidates of an ICE session.
687 *
688 * @param session A pointer to a session
689 *
690 * This function is to be called at the end of the local candidates gathering process, before sending
691 * the SDP to the remote agent.
692 */
693MS2_PUBLIC void ice_session_compute_candidates_foundations(IceSession *session);
694
695/**
696 * Eliminate the redundant candidates of an ICE session.
697 *
698 * @param session A pointer to a session
699 *
700 * This function is to be called at the end of the local candidates gathering process, before sending
701 * the SDP to the remote agent.
702 */
703MS2_PUBLIC void ice_session_eliminate_redundant_candidates(IceSession *session);
704
705/**
706 * Choose the default candidates of an ICE session.
707 *
708 * @param session A pointer to a session
709 *
710 * This function is to be called at the end of the local candidates gathering process, before sending
711 * the SDP to the remote agent.
712 */
713MS2_PUBLIC void ice_session_choose_default_candidates(IceSession *session);
714
715/**
716 * Choose the default remote candidates of an ICE session.
717 *
718 * This function SHOULD not be used. Instead, the default remote candidates MUST be defined as default
719 * when creating them with ice_add_remote_candidate().
720 * However, this function is used by mediastream for testing purpose.
721 */
722MS2_PUBLIC void ice_session_choose_default_remote_candidates(IceSession *session);
723
724/**
725 * Pair the local and the remote candidates for an ICE session and start sending connectivity checks.
726 *
727 * @param session A pointer to a session
728 */
729MS2_PUBLIC void ice_session_start_connectivity_checks(IceSession *session);
730
731/**
732 * Check whether all the ICE check lists of the session includes a default candidate for each component ID in its remote candidates list.
733 *
734 * @param session A pointer to a session
735 */
736MS2_PUBLIC void ice_session_check_mismatch(IceSession *session);
737
738/**
739 * Core ICE check list processing.
740 *
741 * This function is called from the audiostream or the videostream and is NOT to be called by the user.
742 */
743void ice_check_list_process(IceCheckList* cl, RtpSession* rtp_session);
744
745/**
746 * Handle a STUN packet that has been received.
747 *
748 * This function is called from the audiostream or the videostream and is NOT to be called by the user.
749 */
750void ice_handle_stun_packet(IceCheckList* cl, RtpSession* rtp_session, const OrtpEventData* evt_data);
751
752/**
753 * Get the remote address, RTP port and RTCP port to use to send the stream once the ICE process has finished successfully.
754 *
755 * @param cl A pointer to a check list
756 * @param rtp_addr A pointer to the buffer to use to store the remote RTP address
757 * @param rtp_port A pointer to the location to store the RTP port to
758 * @param rtcp_aadr A pointer to the buffer to use to store the remote RTCP address
759 * @param rtcp_port A pointer to the location to store the RTCP port to
760 * @param addr_len The size of the buffer to use to store the remote addresses
761 *
762 * This function will usually be called from within the success callback defined while creating the ICE check list with ice_check_list_new().
763 */
764MS2_PUBLIC 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);
765
766/**
767 * Print the route used to send the stream if the ICE process has finished successfully.
768 *
769 * @param cl A pointer to a check list
770 * @param message A message to print before the route
771 */
772MS2_PUBLIC void ice_check_list_print_route(const IceCheckList *cl, const char *message);
773
774/**
775 * Dump an ICE session in the traces (debug function).
776 */
777MS2_PUBLIC void ice_dump_session(const IceSession *session);
778
779/**
780 * Dump the candidates of an ICE check list in the traces (debug function).
781 */
782MS2_PUBLIC void ice_dump_candidates(const IceCheckList *cl);
783
784/**
785 * Dump the candidate pairs of an ICE check list in the traces (debug function).
786 */
787MS2_PUBLIC void ice_dump_candidate_pairs(const IceCheckList *cl);
788
789/**
790 * Dump the valid list of an ICE check list in the traces (debug function).
791 */
792MS2_PUBLIC void ice_dump_valid_list(const IceCheckList *cl);
793
794/**
795 * Dump the list of candidate pair foundations of an ICE check list in the traces (debug function).
796 */
797MS2_PUBLIC void ice_dump_candidate_pairs_foundations(const IceCheckList *cl);
798
799/**
800 * Dump the list of component IDs of an ICE check list in the traces (debug function).
801 */
802MS2_PUBLIC void ice_dump_componentIDs(const IceCheckList *cl);
803
804/**
805 * Dump an ICE check list in the traces (debug function).
806 */
807MS2_PUBLIC void ice_dump_check_list(const IceCheckList *cl);
808
809/**
810 * Dump the triggered checks queue of an ICE check list in the traces (debug function).
811 */
812MS2_PUBLIC void ice_dump_triggered_checks_queue(const IceCheckList *cl);
813
814#ifdef __cplusplus
815}
816#endif
817
818#endif
819