1 | /* |
2 | mediastreamer2 library - modular sound and video processing and streaming |
3 | Copyright (C) 2012 Belledonne Communications |
4 | |
5 | This program is free software; you can redistribute it and/or |
6 | modify it under the terms of the GNU General Public License |
7 | as published by the Free Software Foundation; either version 2 |
8 | of the License, or (at your option) any later version. |
9 | |
10 | This program is distributed in the hope that it will be useful, |
11 | but WITHOUT ANY WARRANTY; without even the implied warranty of |
12 | MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the |
13 | GNU General Public License for more details. |
14 | |
15 | You should have received a copy of the GNU General Public License |
16 | along with this program; if not, write to the Free Software |
17 | Foundation, 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 | */ |
42 | typedef 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 | */ |
52 | typedef 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 | */ |
64 | typedef 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 | */ |
77 | typedef enum { |
78 | ICL_Running, |
79 | ICL_Completed, |
80 | ICL_Failed |
81 | } IceCheckListState; |
82 | |
83 | /** |
84 | * ICE session state. |
85 | */ |
86 | typedef enum { |
87 | IS_Stopped, |
88 | IS_Running, |
89 | IS_Completed, |
90 | IS_Failed |
91 | } IceSessionState; |
92 | |
93 | /** |
94 | * Structure representing an ICE session. |
95 | */ |
96 | typedef 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 | |
117 | typedef struct _IceStunServerCheckTransaction { |
118 | UInt96 transactionID; |
119 | MSTimeSpec request_time; |
120 | MSTimeSpec response_time; |
121 | } IceStunServerCheckTransaction; |
122 | |
123 | typedef 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 | */ |
134 | typedef 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 | */ |
143 | typedef 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 | */ |
156 | typedef 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 | */ |
176 | typedef struct _IcePairFoundation { |
177 | char local[32]; /**< Foundation of the local candidate */ |
178 | char remote[32]; /**< Foundation of the remote candidate */ |
179 | } IcePairFoundation; |
180 | |
181 | typedef 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 | |
187 | typedef 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 | */ |
198 | typedef 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 |
230 | extern "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 | */ |
240 | MS2_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 | */ |
249 | MS2_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 | */ |
258 | MS2_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 | */ |
265 | MS2_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 | */ |
273 | MS2_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 | */ |
282 | MS2_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 | */ |
290 | MS2_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 | */ |
298 | MS2_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 | */ |
306 | MS2_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 | */ |
314 | MS2_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 | */ |
322 | MS2_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 | */ |
330 | MS2_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 | */ |
338 | MS2_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 | */ |
346 | MS2_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 | */ |
356 | MS2_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 | */ |
367 | MS2_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 | */ |
378 | MS2_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 | */ |
388 | MS2_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 | */ |
396 | MS2_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 | */ |
404 | MS2_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 | */ |
412 | MS2_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 | */ |
420 | MS2_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 | */ |
428 | MS2_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 | */ |
437 | MS2_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 | */ |
445 | MS2_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 | */ |
453 | MS2_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 | */ |
462 | MS2_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 | */ |
469 | MS2_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 | */ |
477 | MS2_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 | */ |
485 | MS2_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 | */ |
493 | MS2_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 | */ |
501 | MS2_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 | */ |
509 | MS2_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 | */ |
517 | MS2_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 | */ |
525 | MS2_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 | */ |
533 | MS2_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 | */ |
543 | MS2_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 | */ |
554 | MS2_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 | */ |
566 | MS2_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 | */ |
578 | MS2_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 | */ |
590 | MS2_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 | */ |
598 | MS2_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 | */ |
605 | MS2_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 | */ |
613 | MS2_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 | */ |
627 | MS2_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 | */ |
643 | MS2_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 | */ |
657 | MS2_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 | */ |
665 | MS2_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 | */ |
674 | MS2_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 | */ |
683 | MS2_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 | */ |
693 | MS2_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 | */ |
703 | MS2_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 | */ |
713 | MS2_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 | */ |
722 | MS2_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 | */ |
729 | MS2_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 | */ |
736 | MS2_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 | */ |
743 | void 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 | */ |
750 | void 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 | */ |
764 | MS2_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 | */ |
772 | MS2_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 | */ |
777 | MS2_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 | */ |
782 | MS2_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 | */ |
787 | MS2_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 | */ |
792 | MS2_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 | */ |
797 | MS2_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 | */ |
802 | MS2_PUBLIC void ice_dump_componentIDs(const IceCheckList *cl); |
803 | |
804 | /** |
805 | * Dump an ICE check list in the traces (debug function). |
806 | */ |
807 | MS2_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 | */ |
812 | MS2_PUBLIC void ice_dump_triggered_checks_queue(const IceCheckList *cl); |
813 | |
814 | #ifdef __cplusplus |
815 | } |
816 | #endif |
817 | |
818 | #endif |
819 | |