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., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA. 18 */ 19 20 #ifndef ice_h 21 #define ice_h 22 23 #include <mediastreamer2/mscommon.h> 24 #include <mediastreamer2/stun.h> 25 #include <ortp/ortp.h> 26 27 28 /** 29 * @file ice.h 30 * @brief mediastreamer2 ice.h include file 31 * 32 * This file provides the API to handle the ICE protocol defined in the RFC 5245. 33 */ 34 35 36 /** 37 * The maximum number of check lists in an ICE session. 38 */ 39 #define ICE_SESSION_MAX_CHECK_LISTS 8 40 41 42 /** 43 * ICE agent role. 44 * 45 * See the terminology in paragraph 3 of the RFC 5245 for more details. 46 */ 47 typedef enum { 48 IR_Controlling, 49 IR_Controlled 50 } IceRole; 51 52 /** 53 * ICE candidate type. 54 * 55 * See the terminology in paragraph 3 of the RFC 5245 for more details. 56 */ 57 typedef enum { 58 ICT_CandidateInvalid = -1, 59 ICT_HostCandidate, 60 ICT_ServerReflexiveCandidate, 61 ICT_PeerReflexiveCandidate, 62 ICT_RelayedCandidate, 63 ICT_CandidateTypeMax 64 } IceCandidateType; 65 66 /** 67 * ICE candidate pair state. 68 * 69 * See paragraph 5.7.4 ("Computing states") of RFC 5245 for more details. 70 */ 71 typedef enum { 72 ICP_Waiting, 73 ICP_InProgress, 74 ICP_Succeeded, 75 ICP_Failed, 76 ICP_Frozen 77 } IceCandidatePairState; 78 79 /** 80 * ICE check list state. 81 * 82 * See paragraph 5.7.4 ("Computing states") of RFC 5245 for more details. 83 */ 84 typedef enum { 85 ICL_Running, 86 ICL_Completed, 87 ICL_Failed 88 } IceCheckListState; 89 90 /** 91 * ICE session state. 92 */ 93 typedef enum { 94 IS_Stopped, 95 IS_Running, 96 IS_Completed, 97 IS_Failed 98 } IceSessionState; 99 100 struct _IceCheckList; 101 102 /** 103 * Structure representing an ICE session. 104 */ 105 typedef struct _IceSession { 106 struct _IceCheckList * streams[ICE_SESSION_MAX_CHECK_LISTS]; /**< Table of IceChecklist structure pointers. Each element represents a media stream */ 107 MSStunAuthRequestedCb stun_auth_requested_cb; /**< Callback called when authentication is requested */ 108 void *stun_auth_requested_userdata; /**< Userdata to pass to the STUN authentication requested callback */ 109 char *local_ufrag; /**< Local username fragment for the session (assigned during the session creation) */ 110 char *local_pwd; /**< Local password for the session (assigned during the session creation) */ 111 char *remote_ufrag; /**< Remote username fragment for the session (provided via SDP by the peer) */ 112 char *remote_pwd; /**< Remote password for the session (provided via SDP by the peer) */ 113 IceRole role; /**< Role played by the agent for this session */ 114 IceSessionState state; /**< State of the session */ 115 uint64_t tie_breaker; /**< Random number used to resolve role conflicts (see paragraph 5.2 of the RFC 5245) */ 116 int32_t ta; /**< Duration of timer for sending connectivity checks in ms */ 117 int event_value; /** Value of the event to send */ 118 MSTimeSpec event_time; /**< Time when an event must be sent */ 119 struct sockaddr_storage ss; /**< STUN server address to use for the candidates gathering process */ 120 socklen_t ss_len; /**< Length of the STUN server address to use for the candidates gathering process */ 121 MSTimeSpec gathering_start_ts; 122 MSTimeSpec gathering_end_ts; 123 IceCandidateType default_types[ICT_CandidateTypeMax]; 124 bool_t check_message_integrity; /*set to false for backward compatibility only*/ 125 bool_t send_event; /**< Boolean value telling whether an event must be sent or not */ 126 uint8_t max_connectivity_checks; /**< Configuration parameter to limit the number of connectivity checks performed by the agent (default is 100) */ 127 uint8_t keepalive_timeout; /**< Configuration parameter to define the timeout between each keepalive packets (default is 15s) */ 128 bool_t forced_relay; /**< Force use of relay by modifying the local and reflexive candidates */ 129 bool_t turn_enabled; /**< TURN protocol enabled */ 130 bool_t short_turn_refresh; /**< Short TURN refresh for tests */ 131 } IceSession; 132 133 typedef struct _IceStunServerRequestTransaction { 134 UInt96 transactionID; 135 MSTimeSpec request_time; 136 MSTimeSpec response_time; 137 } IceStunServerRequestTransaction; 138 139 typedef struct _IceStunServerRequest { 140 struct _IceCheckList *cl; 141 RtpTransport *rtptp; 142 MSTurnContext *turn_context; 143 struct addrinfo *source_ai; 144 MSList *transactions; /**< List of IceStunServerRequestTransaction structures. */ 145 MSTimeSpec next_transmission_time; 146 MSStunAddress peer_address; 147 uint16_t channel_number; 148 uint16_t stun_method; 149 uint8_t requested_address_family; 150 bool_t gathering; 151 bool_t responded; 152 bool_t to_remove; 153 } IceStunServerRequest; 154 155 typedef struct _IceStunRequestRoundTripTime { 156 int nb_responses; 157 int sum; 158 } IceStunRequestRoundTripTime; 159 160 /** 161 * Structure representing an ICE transport address. 162 */ 163 typedef struct _IceTransportAddress { 164 char ip[64]; 165 int port; 166 int family; 167 // TODO: Handling of transport type: TCP, UDP... 168 } IceTransportAddress; 169 170 /** 171 * Structure representing an ICE candidate. 172 */ 173 typedef struct _IceCandidate { 174 char foundation[32]; /**< Foundation of the candidate (see paragraph 3 of the RFC 5245 for more details */ 175 IceTransportAddress taddr; /**< Transport address of the candidate */ 176 IceCandidateType type; /**< Type of the candidate */ 177 uint32_t priority; /**< Priority of the candidate */ 178 uint16_t componentID; /**< component ID between 1 and 256: usually 1 for RTP component and 2 for RTCP component */ 179 struct _IceCandidate *base; /**< Pointer to the candidate that is the base of the current one */ 180 bool_t is_default; /**< Boolean value telling whether this candidate is a default candidate or not */ 181 } IceCandidate; 182 183 /** 184 * Structure representing an ICE candidate pair. 185 */ 186 typedef struct _IceCandidatePair { 187 IceCandidate *local; /**< Pointer to the local candidate of the pair */ 188 IceCandidate *remote; /**< Pointer to the remote candidate of the pair */ 189 IceCandidatePairState state; /**< State of the candidate pair */ 190 uint64_t priority; /**< Priority of the candidate pair */ 191 MSTimeSpec transmission_time; /**< Time when the connectivity check for the candidate pair has been sent */ 192 int32_t rto; /**< Duration of the retransmit timer for the connectivity check sent for the candidate pair in ms */ 193 uint8_t retransmissions; /**< Number of retransmissions for the connectivity check sent for the candidate pair */ 194 IceRole role; /**< Role of the agent when the connectivity check has been sent for the candidate pair */ 195 bool_t is_default; /**< Boolean value telling whether this candidate pair is a default candidate pair or not */ 196 bool_t use_candidate; /**< Boolean value telling if the USE-CANDIDATE attribute must be set for the connectivity checks send for the candidate pair */ 197 bool_t is_nominated; /**< Boolean value telling whether this candidate pair is nominated or not */ 198 bool_t wait_transaction_timeout; /**< Boolean value telling to create a new binding request on retransmission timeout */ 199 bool_t retry_with_dummy_message_integrity; /** use to tell to retry with dummy message integrity. Useful to keep backward compatibility with older version*/ 200 bool_t use_dummy_hmac; /*don't compute real hmac. used for backward compatibility*/ 201 } IceCandidatePair; 202 203 /** 204 * Structure representing the foundation of an ICE candidate pair. 205 * 206 * It is the concatenation of the foundation of a local candidate and the foundation of a remote candidate. 207 */ 208 typedef struct _IcePairFoundation { 209 char local[32]; /**< Foundation of the local candidate */ 210 char remote[32]; /**< Foundation of the remote candidate */ 211 } IcePairFoundation; 212 213 typedef struct _IceValidCandidatePair { 214 IceCandidatePair *valid; /**< Pointer to a valid candidate pair (it may be in the check list or not */ 215 IceCandidatePair *generated_from; /**< Pointer to the candidate pair that generated the connectivity check producing the valid candidate pair */ 216 bool_t selected; /**< Boolean value telling whether this valid candidate pair has been selected or not */ 217 } IceValidCandidatePair; 218 219 typedef struct _IceTransaction { 220 UInt96 transactionID; /**< Transaction ID of the connectivity check sent for the candidate pair */ 221 IceCandidatePair *pair; /**< A pointer to the candidate pair associated with the transaction. */ 222 } IceTransaction; 223 224 /** 225 * Structure representing an ICE check list. 226 * 227 * Each media stream must be assigned a check list. 228 * Check lists are added to an ICE session using the ice_session_add_check_list() function. 229 */ 230 typedef struct _IceCheckList { 231 IceSession *session; /**< Pointer to the ICE session */ 232 MSTurnContext *rtp_turn_context; /**< TURN context for RTP socket */ 233 MSTurnContext *rtcp_turn_context; /**< TURN context for RTCP socket */ 234 RtpSession *rtp_session; /**< Pointer to the RTP session associated with this ICE check list */ 235 char *remote_ufrag; /**< Remote username fragment for this check list (provided via SDP by the peer) */ 236 char *remote_pwd; /**< Remote password for this check list (provided via SDP by the peer) */ 237 MSList *stun_server_requests; /**< List of IceStunServerRequest structures */ 238 MSList *local_candidates; /**< List of IceCandidate structures */ 239 MSList *remote_candidates; /**< List of IceCandidate structures */ 240 MSList *pairs; /**< List of IceCandidatePair structures */ 241 MSList *losing_pairs; /**< List of IceCandidatePair structures */ 242 MSList *triggered_checks_queue; /**< List of IceCandidatePair structures */ 243 MSList *check_list; /**< List of IceCandidatePair structures */ 244 MSList *valid_list; /**< List of IceValidCandidatePair structures */ 245 MSList *foundations; /**< List of IcePairFoundation structures */ 246 MSList *local_componentIDs; /**< List of uint16_t */ 247 MSList *remote_componentIDs; /**< List of uint16_t */ 248 MSList *transaction_list; /**< List of IceTransaction structures */ 249 IceCheckListState state; /**< Global state of the ICE check list */ 250 MSTimeSpec ta_time; /**< Time when the Ta timer has been processed for the last time */ 251 MSTimeSpec keepalive_time; /**< Time when the last keepalive packet has been sent for this stream */ 252 uint32_t foundation_generator; /**< Autoincremented integer to generate unique foundation values */ 253 bool_t mismatch; /**< Boolean value telling whether there was a mismatch during the answer/offer process */ 254 bool_t gathering_candidates; /**< Boolean value telling whether a candidate gathering process is running or not */ 255 bool_t gathering_finished; /**< Boolean value telling whether the candidate gathering process has finished or not */ 256 bool_t nomination_delay_running; /**< Boolean value telling whether the nomination process has been delayed or not */ 257 MSTimeSpec gathering_start_time; /**< Time when the gathering process was started */ 258 MSTimeSpec nomination_delay_start_time; /**< Time when the nomination process has been delayed */ 259 IceStunRequestRoundTripTime rtt; 260 } IceCheckList; 261 262 263 264 #ifdef __cplusplus 265 extern "C"{ 266 #endif 267 268 /** 269 * Allocate a new ICE session. 270 * 271 * @return Pointer to the allocated session 272 * 273 * This must be performed for each media session that is to use ICE. 274 */ 275 MS2_PUBLIC IceSession * ice_session_new(void); 276 277 278 /** 279 * Set the prefered type for default candidates, as defined in rfc5245#section-4.1.4. 280 * The type table can be terminated by the ICT_CandidateInvalid element, may it contain less elements 281 * than the number of types available. 282 **/ 283 MS2_PUBLIC void ice_session_set_default_candidates_types(IceSession *session, 284 const IceCandidateType types[ICT_CandidateTypeMax]); 285 /** 286 * Destroy a previously allocated ICE session. 287 * 288 * @param session The session to destroy. 289 * 290 * To be used when a media session using ICE is tore down. 291 */ 292 MS2_PUBLIC void ice_session_destroy(IceSession *session); 293 294 /** 295 * Allocate a new ICE check list. 296 * 297 * @return Pointer to the allocated check list 298 * 299 * 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. 300 */ 301 MS2_PUBLIC IceCheckList * ice_check_list_new(void); 302 303 /** 304 * Destroy a previously allocated ICE check list. 305 * 306 * @param cl The check list to destroy 307 */ 308 MS2_PUBLIC void ice_check_list_destroy(IceCheckList *cl); 309 310 /** 311 * Tell whether ICE local candidates have been gathered for an ICE check list or not. 312 * 313 * @param cl A pointer to a check list 314 * @return TRUE if local candidates have been gathered for the check list, FALSE otherwise. 315 */ 316 MS2_PUBLIC bool_t ice_check_list_candidates_gathered(const IceCheckList *cl); 317 318 /** 319 * Get the nth check list of an ICE session. 320 * 321 * @param session A pointer to a session 322 * @param n The number of the check list to access 323 * @return A pointer to the nth check list of the session if it exists, NULL otherwise 324 */ 325 MS2_PUBLIC IceCheckList *ice_session_check_list(const IceSession *session, int n); 326 327 /** 328 * Get the local username fragment of an ICE session. 329 * 330 * @param session A pointer to a session 331 * @return A pointer to the local username fragment of the session 332 */ 333 MS2_PUBLIC const char * ice_session_local_ufrag(const IceSession *session); 334 335 /** 336 * Get the local password of an ICE session. 337 * 338 * @param session A pointer to a session 339 * @return A pointer to the local password of the session 340 */ 341 MS2_PUBLIC const char * ice_session_local_pwd(const IceSession *session); 342 343 /** 344 * Get the remote username fragment of an ICE session. 345 * 346 * @param session A pointer to a session 347 * @return A pointer to the remote username fragment of the session 348 */ 349 MS2_PUBLIC const char * ice_session_remote_ufrag(const IceSession *session); 350 351 /** 352 * Get the remote password of an ICE session. 353 * 354 * @param session A pointer to a session 355 * @return A pointer to the remote password of the session 356 */ 357 MS2_PUBLIC const char * ice_session_remote_pwd(const IceSession *session); 358 359 /** 360 * Get the state of an ICE session. 361 * 362 * @param session A pointer to a session 363 * @return The state of the session 364 */ 365 MS2_PUBLIC IceSessionState ice_session_state(const IceSession *session); 366 367 /** 368 * Get the role of the agent for an ICE session. 369 * 370 * @param session A pointer to a session 371 * @return The role of the agent for the session 372 */ 373 MS2_PUBLIC IceRole ice_session_role(const IceSession *session); 374 375 /** 376 * Set the role of the agent for an ICE session. 377 * 378 * @param session The session for which to set the role 379 * @param role The role to set the session to 380 */ 381 MS2_PUBLIC void ice_session_set_role(IceSession *session, IceRole role); 382 383 /** 384 * Set the local credentials of an ICE session. 385 * 386 * This function SHOULD not be used. However, it is used by mediastream for testing purpose to 387 * apply the same credentials for local and remote agents because the SDP exchange is bypassed. 388 */ 389 MS2_PUBLIC void ice_session_set_local_credentials(IceSession *session, const char *ufrag, const char *pwd); 390 391 /** 392 * Tell if remote credentials of an ICE session have changed or not. 393 * 394 * @param session A pointer to a session 395 * @param ufrag The new remote username fragment 396 * @param pwd The new remote password 397 * @return TRUE if the remote credentials of the session have changed, FALSE otherwise. 398 */ 399 MS2_PUBLIC bool_t ice_session_remote_credentials_changed(IceSession *session, const char *ufrag, const char *pwd); 400 401 /** 402 * Set the remote credentials of an ICE session. 403 * 404 * @param session A pointer to a session 405 * @param ufrag The remote username fragment 406 * @param pwd The remote password 407 * 408 * This function is to be called once the remote credentials have been received via SDP. 409 */ 410 MS2_PUBLIC void ice_session_set_remote_credentials(IceSession *session, const char *ufrag, const char *pwd); 411 412 /** 413 * get the remote ufrag of an ICE check list. 414 * 415 * @param cl A pointer to a check list 416 * 417 * This function is to be called once the remote credentials have been received via SDP. 418 */ 419 MS2_PUBLIC const char* ice_check_list_get_remote_ufrag(const IceCheckList *cl); 420 421 /** 422 * get the remote pwd of an ICE check list. 423 * 424 * @param cl A pointer to a check list 425 * 426 * This function is to be called once the remote credentials have been received via SDP. 427 */ 428 MS2_PUBLIC const char* ice_check_list_get_remote_pwd(const IceCheckList *cl); 429 430 /** 431 * Define the maximum number of connectivity checks that will be performed by the agent. 432 * 433 * @param session A pointer to a session 434 * @param max_connectivity_checks The maximum number of connectivity checks to perform 435 * 436 * This function is to be called just after the creation of the session, before any connectivity check is performed. 437 * The default number of connectivity checks is 100. 438 */ 439 MS2_PUBLIC void ice_session_set_max_connectivity_checks(IceSession *session, uint8_t max_connectivity_checks); 440 441 /** 442 * Define the timeout between each keepalive packet in seconds. 443 * 444 * @param session A pointer to a session 445 * @param timeout The duration of the keepalive timeout in seconds 446 * 447 * The default keepalive timeout is set to 15 seconds. 448 */ 449 MS2_PUBLIC void ice_session_set_keepalive_timeout(IceSession *session, uint8_t timeout); 450 451 /** 452 * Get the number of check lists in an ICE session. 453 * 454 * @param session A pointer to a session 455 * @return The number of check lists in the ICE session 456 */ 457 MS2_PUBLIC int ice_session_nb_check_lists(IceSession *session); 458 459 /** 460 * Tell whether an ICE session has at least one completed check list. 461 * 462 * @param session A pointer to a session 463 * @return TRUE if the session has at least one completed check list, FALSE otherwise 464 */ 465 MS2_PUBLIC bool_t ice_session_has_completed_check_list(const IceSession *session); 466 467 /** 468 * Add an ICE check list to an ICE session. 469 * 470 * @param session The session that is assigned the check list 471 * @param cl The check list to assign to the session 472 * @param idx The index of the check list to add 473 */ 474 MS2_PUBLIC void ice_session_add_check_list(IceSession *session, IceCheckList *cl, unsigned int idx); 475 476 /** 477 * Remove an ICE check list from an ICE session. 478 * 479 * @param session The session from which to remove the check list 480 * @param cl The check list to remove from the session 481 */ 482 MS2_PUBLIC void ice_session_remove_check_list(IceSession *session, IceCheckList *cl); 483 484 /** 485 * Remove an ICE check list from an ICE session given its index. 486 * 487 * @param session The session from which to remove the check list 488 * @param idx The index of the check list in the ICE session 489 */ 490 MS2_PUBLIC void ice_session_remove_check_list_from_idx(IceSession *session, unsigned int idx); 491 492 /** 493 * Tell whether ICE local candidates have been gathered for an ICE session or not. 494 * 495 * @param session A pointer to a session 496 * @return TRUE if local candidates have been gathered for the session, FALSE otherwise. 497 */ 498 MS2_PUBLIC bool_t ice_session_candidates_gathered(const IceSession *session); 499 500 /** 501 * Gather ICE local candidates for an ICE session. 502 * 503 * @param session A pointer to a session 504 * @param ss The STUN server address 505 * @param ss_len The length of the STUN server address 506 * @return TRUE if the gathering is in progress, FALSE if no gathering is happening. 507 */ 508 MS2_PUBLIC bool_t ice_session_gather_candidates(IceSession *session, const struct sockaddr * ss, socklen_t ss_len); 509 510 /** 511 * Tell the duration of the gathering process for an ICE session in ms. 512 * 513 * @param session A pointer to a session 514 * @return -1 if gathering has not been run, the duration of the gathering process in ms otherwise. 515 */ 516 MS2_PUBLIC int ice_session_gathering_duration(IceSession *session); 517 518 /** 519 * Enable forced relay for tests. 520 * The local and reflexive candidates are changed so that these paths do not work to force the use of the relay. 521 * @param session A pointer to a session. 522 * @param enable A boolean value telling whether to force relay or not. 523 */ 524 MS2_PUBLIC void ice_session_enable_forced_relay(IceSession *session, bool_t enable); 525 526 /** 527 * Enable short TURN refresh for tests. 528 * This changes the delay to send allocation refresh, create permission, and channel bind requests. 529 * @param session A pointer to a session 530 * @param enable A boolean value telling whether to use short turn refresh. 531 */ 532 MS2_PUBLIC void ice_session_enable_short_turn_refresh(IceSession *session, bool_t enable); 533 534 /** 535 * Enable TURN protol. 536 * @param session A pointer to a session 537 * @param enable A boolean value telling whether to enable TURN protocol or not. 538 */ 539 MS2_PUBLIC void ice_session_enable_turn(IceSession *session, bool_t enable); 540 541 MS2_PUBLIC void ice_session_set_stun_auth_requested_cb(IceSession *session, MSStunAuthRequestedCb cb, void *userdata); 542 543 /** 544 * Tell the average round trip time during the gathering process for an ICE session in ms. 545 * 546 * @param session A pointer to a session 547 * @return -1 if gathering has not been run, the average round trip time in ms otherwise. 548 */ 549 MS2_PUBLIC int ice_session_average_gathering_round_trip_time(IceSession *session); 550 551 /** 552 * Select ICE candidates that will be used and notified in the SDP. 553 * 554 * @param session A pointer to a session 555 * 556 * This function is to be used by the Controlling agent when ICE processing has finished. 557 */ 558 MS2_PUBLIC void ice_session_select_candidates(IceSession *session); 559 560 /** 561 * Restart an ICE session. 562 * 563 * @param session A pointer to a session 564 * @param role The role of the agent after the session restart 565 */ 566 MS2_PUBLIC void ice_session_restart(IceSession *session, IceRole role); 567 568 /** 569 * Reset an ICE session. 570 * It has the same effect as a session restart but also clears the local candidates. 571 * 572 * @param session A pointer to a session 573 * @param role The role of the agent after the session restart 574 */ 575 MS2_PUBLIC void ice_session_reset(IceSession *session, IceRole role); 576 577 /** 578 * Get the state of an ICE check list. 579 * 580 * @param cl A pointer to a check list 581 * @return The check list state 582 */ 583 MS2_PUBLIC IceCheckListState ice_check_list_state(const IceCheckList *cl); 584 585 /** 586 * Set the state of an ICE check list. 587 * 588 * @param cl A pointer to a check list 589 * @param state The new state of the check list 590 */ 591 MS2_PUBLIC void ice_check_list_set_state(IceCheckList *cl, IceCheckListState state); 592 /** 593 * Humanly readable IceCheckListState 594 * 595 * @param state The state of the check list 596 * @return a humanly readable IceCheckListState. 597 */ 598 MS2_PUBLIC const char* ice_check_list_state_to_string(const IceCheckListState state); 599 /** 600 * Assign an RTP session to an ICE check list. 601 * 602 * @param cl A pointer to a check list 603 * @param rtp_session A pointer to the RTP session to assign to the check list 604 */ 605 MS2_PUBLIC void ice_check_list_set_rtp_session(IceCheckList *cl, RtpSession *rtp_session); 606 607 /** 608 * Get the local username fragment of an ICE check list. 609 * 610 * @param cl A pointer to a check list 611 * @return A pointer to the local username fragment of the check list 612 */ 613 MS2_PUBLIC const char * ice_check_list_local_ufrag(const IceCheckList *cl); 614 615 /** 616 * Get the local password of an ICE check list. 617 * 618 * @param cl A pointer to a check list 619 * @return A pointer to the local password of the check list 620 */ 621 MS2_PUBLIC const char * ice_check_list_local_pwd(const IceCheckList *cl); 622 623 /** 624 * Get the remote username fragment of an ICE check list. 625 * 626 * @param cl A pointer to a check list 627 * @return A pointer to the remote username fragment of the check list 628 */ 629 MS2_PUBLIC const char * ice_check_list_remote_ufrag(const IceCheckList *cl); 630 631 /** 632 * Get the remote password of an ICE check list. 633 * 634 * @param cl A pointer to a check list 635 * @return A pointer to the remote password of the check list 636 */ 637 MS2_PUBLIC const char * ice_check_list_remote_pwd(const IceCheckList *cl); 638 639 /** 640 * Get the mismatch property of an ICE check list. 641 * 642 * @param cl A pointer to a check list 643 * @return TRUE if there was a mismatch for the check list, FALSE otherwise 644 */ 645 MS2_PUBLIC bool_t ice_check_list_is_mismatch(const IceCheckList *cl); 646 647 /** 648 * Tell if remote credentials of an ICE check list have changed or not. 649 * 650 * @param cl A pointer to a check list 651 * @param ufrag The new remote username fragment 652 * @param pwd The new remote password 653 * @return TRUE if the remote credentials of the check list have changed, FALSE otherwise. 654 */ 655 MS2_PUBLIC bool_t ice_check_list_remote_credentials_changed(IceCheckList *cl, const char *ufrag, const char *pwd); 656 657 /** 658 * Set the remote credentials of an ICE check list. 659 * 660 * @param cl A pointer to a check list 661 * @param ufrag The remote username fragment 662 * @param pwd The remote password 663 * 664 * This function is to be called once the remote credentials have been received via SDP. 665 */ 666 MS2_PUBLIC void ice_check_list_set_remote_credentials(IceCheckList *cl, const char *ufrag, const char *pwd); 667 668 /** 669 * Get the default local candidate for an ICE check list. 670 * 671 * @param cl A pointer to a check list 672 * @param rtp_candidate A pointer to store the RTP default local candidate 673 * @param rtcp_candidate A pointer to store the RTCP default local candidate 674 * @return TRUE if the information have been successfully retrieved, FALSE otherwise 675 */ 676 MS2_PUBLIC bool_t ice_check_list_default_local_candidate(const IceCheckList *cl, IceCandidate **rtp_candidate, IceCandidate **rtcp_candidate); 677 678 /** 679 * Get the selected valid local candidate for an ICE check list. 680 * 681 * @param cl A pointer to a check list 682 * @param rtp_candidate A pointer to store the RTP valid local candidate 683 * @param rtcp_candidate A pointer to store the RTCP valid local candidate 684 * @return TRUE if the information have been successfully retrieved, FALSE otherwise 685 */ 686 MS2_PUBLIC bool_t ice_check_list_selected_valid_local_candidate(const IceCheckList *cl, IceCandidate **rtp_candidate, IceCandidate **rtcp_candidate); 687 688 /** 689 * Get the selected valid remote candidate for an ICE check list. 690 * 691 * @param cl A pointer to a check list 692 * @param rtp_candidate A pointer to store the RTP valid remote candidate 693 * @param rtcp_candidate A pointer to store the RTCP valid remote candidate 694 * @return TRUE if the information have been successfully retrieved, FALSE otherwise 695 */ 696 MS2_PUBLIC bool_t ice_check_list_selected_valid_remote_candidate(const IceCheckList *cl, IceCandidate **rtp_candidate, IceCandidate **rtcp_candidate); 697 698 /** 699 * Get the type of the selected valid candidate for an ICE check list. 700 * 701 * @param cl A pointer to a check list 702 * @return The type of the selected valid candidate 703 */ 704 MS2_PUBLIC IceCandidateType ice_check_list_selected_valid_candidate_type(const IceCheckList *cl); 705 706 /** 707 * Check if an ICE check list can be set in the Completed state after handling losing pairs. 708 * 709 * @param cl A pointer to a check list 710 */ 711 MS2_PUBLIC void ice_check_list_check_completed(IceCheckList *cl); 712 713 /** 714 * Get the candidate type as a string. 715 * 716 * @param candidate A pointer to a candidate 717 * @return A pointer to the candidate type as a string 718 */ 719 MS2_PUBLIC const char * ice_candidate_type(const IceCandidate *candidate); 720 721 /** 722 * Add a local candidate to an ICE check list. 723 * 724 * @param cl A pointer to a check list 725 * @param type The type of the local candidate to add as a string (must be one of: "host", "srflx", "prflx" or "relay") 726 * @param family The address family of the local candidate (AF_INET or AF_INET6) 727 * @param ip The IP address of the local candidate as a string (eg. 192.168.0.10) 728 * @param port The port of the local candidate 729 * @param componentID The component ID of the local candidate (usually 1 for RTP and 2 for RTCP) 730 * @param base A pointer to the base candidate of the candidate to add. 731 * 732 * This function is to be called when gathering local candidates. 733 */ 734 MS2_PUBLIC IceCandidate * ice_add_local_candidate(IceCheckList *cl, const char *type, int family, const char *ip, int port, uint16_t componentID, IceCandidate *base); 735 736 /** 737 * Add a remote candidate to an ICE check list. 738 * 739 * @param cl A pointer to a check list 740 * @param type The type of the remote candidate to add as a string (must be one of: "host", "srflx", "prflx" or "relay") 741 * @param family The address family of the remote candidate (AF_INET or AF_INET6) 742 * @param ip The IP address of the remote candidate as a string (eg. 192.168.0.10) 743 * @param port The port of the remote candidate 744 * @param componentID The component ID of the remote candidate (usually 1 for RTP and 2 for RTCP) 745 * @param priority The priority of the remote candidate 746 * @param foundation The foundation of the remote candidate 747 * @param is_default Boolean value telling whether the remote candidate is a default candidate or not 748 * 749 * This function is to be called once the remote candidate list has been received via SDP. 750 */ 751 MS2_PUBLIC 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); 752 753 /** 754 * Add a losing pair to an ICE check list. 755 * 756 * @param cl A pointer to a check list 757 * @param componentID The component ID of the candidates of the pair to add 758 * @param family The address family of the candidates (AF_INET or AF_INET6) 759 * @param local_addr The address of the local candidate of the pair to add 760 * @param local_port The port of the local candidate of the pair to add 761 * @param remote_addr The address of the remote candidate of the pair to add 762 * @param remote_port The port of the remote candidate of the pair to add 763 * 764 * This function is to be called when a RE-INVITE with an SDP containing a remote-candidates attribute is received. 765 */ 766 MS2_PUBLIC 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); 767 768 /** 769 * Get the number of losing candidate pairs for an ICE session. 770 * 771 * @param session A pointer to a session 772 * @return The number of losing candidate pairs for the session. 773 */ 774 MS2_PUBLIC int ice_session_nb_losing_pairs(const IceSession *session); 775 776 /** 777 * Unselect the previously selected valid pairs. 778 * 779 * @param cl A pointer to a check list 780 * 781 * This function is to be used to use the pairs given by the remote controlling agent instead of the pairs we found ourselves. 782 */ 783 MS2_PUBLIC void ice_check_list_unselect_valid_pairs(IceCheckList *cl); 784 785 /** 786 * Set the base for the local server reflexive candidates of an ICE session. 787 * 788 * This function SHOULD not be used. However, it is used by mediastream for testing purpose to 789 * work around the fact that it does not use candidates gathering. 790 * It is to be called automatically when the gathering process finishes. 791 */ 792 MS2_PUBLIC void ice_session_set_base_for_srflx_candidates(IceSession *session); 793 794 /** 795 * Remove local and remote RTCP candidates from an ICE check list. 796 * 797 * @param cl A pointer to a check list 798 * 799 * This function MUST be called before calling ice_session_start_connectivity_checks(). It is useful when using rtcp-mux. 800 */ 801 MS2_PUBLIC void ice_check_list_remove_rtcp_candidates(IceCheckList *cl); 802 803 /** 804 * Compute the foundations of the local candidates of an ICE session. 805 * 806 * @param session A pointer to a session 807 * 808 * This function is to be called at the end of the local candidates gathering process, before sending 809 * the SDP to the remote agent. 810 */ 811 MS2_PUBLIC void ice_session_compute_candidates_foundations(IceSession *session); 812 813 /** 814 * Eliminate the redundant candidates of an ICE session. 815 * 816 * @param session A pointer to a session 817 * 818 * This function is to be called at the end of the local candidates gathering process, before sending 819 * the SDP to the remote agent. 820 */ 821 MS2_PUBLIC void ice_session_eliminate_redundant_candidates(IceSession *session); 822 823 /** 824 * Choose the default candidates of an ICE session. 825 * 826 * @param session A pointer to a session 827 * 828 * This function is to be called at the end of the local candidates gathering process, before sending 829 * the SDP to the remote agent. 830 */ 831 MS2_PUBLIC void ice_session_choose_default_candidates(IceSession *session); 832 833 /** 834 * Choose the default remote candidates of an ICE session. 835 * 836 * This function SHOULD not be used. Instead, the default remote candidates MUST be defined as default 837 * when creating them with ice_add_remote_candidate(). 838 * However, this function is used by mediastream for testing purpose. 839 */ 840 MS2_PUBLIC void ice_session_choose_default_remote_candidates(IceSession *session); 841 842 /** 843 * Pair the local and the remote candidates for an ICE session and start sending connectivity checks. 844 * 845 * @param session A pointer to a session 846 */ 847 MS2_PUBLIC void ice_session_start_connectivity_checks(IceSession *session); 848 849 /** 850 * Check whether all the ICE check lists of the session includes a default candidate for each component ID in its remote candidates list. 851 * 852 * @param session A pointer to a session 853 */ 854 MS2_PUBLIC void ice_session_check_mismatch(IceSession *session); 855 856 857 /** 858 * Disable/enable strong message integrity check. Used for backward compatibility only 859 * default value is enabled 860 * @param session A pointer to a session 861 * @param enable value 862 * 863 */ 864 MS2_PUBLIC void ice_session_enable_message_integrity_check(IceSession *session,bool_t enable); 865 866 /** 867 * Core ICE check list processing. 868 * 869 * This function is called from the audiostream or the videostream and is NOT to be called by the user. 870 */ 871 void ice_check_list_process(IceCheckList* cl, RtpSession* rtp_session); 872 873 /** 874 * Handle a STUN packet that has been received. 875 * 876 * This function is called from the audiostream or the videostream and is NOT to be called by the user. 877 */ 878 void ice_handle_stun_packet(IceCheckList* cl, RtpSession* rtp_session, const OrtpEventData* evt_data); 879 880 /** 881 * Get the remote address, RTP port and RTCP port to use to send the stream once the ICE process has finished successfully. 882 * 883 * @param cl A pointer to a check list 884 * @param rtp_addr A pointer to the buffer to use to store the remote RTP address 885 * @param rtp_port A pointer to the location to store the RTP port to 886 * @param rtcp_addr A pointer to the buffer to use to store the remote RTCP address 887 * @param rtcp_port A pointer to the location to store the RTCP port to 888 * @param addr_len The size of the buffer to use to store the remote addresses 889 * 890 * This function will usually be called from within the success callback defined while creating the ICE check list with ice_check_list_new(). 891 */ 892 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); 893 894 /** 895 * Print the route used to send the stream if the ICE process has finished successfully. 896 * 897 * @param cl A pointer to a check list 898 * @param message A message to print before the route 899 */ 900 MS2_PUBLIC void ice_check_list_print_route(const IceCheckList *cl, const char *message); 901 902 /** 903 * Dump an ICE session in the traces (debug function). 904 */ 905 MS2_PUBLIC void ice_dump_session(const IceSession *session); 906 907 /** 908 * Dump the candidates of an ICE check list in the traces (debug function). 909 */ 910 MS2_PUBLIC void ice_dump_candidates(const IceCheckList *cl); 911 912 /** 913 * Dump the candidate pairs of an ICE check list in the traces (debug function). 914 */ 915 MS2_PUBLIC void ice_dump_candidate_pairs(const IceCheckList *cl); 916 917 /** 918 * Dump the valid list of an ICE check list in the traces (debug function). 919 */ 920 MS2_PUBLIC void ice_dump_valid_list(const IceCheckList *cl); 921 922 /** 923 * Dump the list of candidate pair foundations of an ICE check list in the traces (debug function). 924 */ 925 MS2_PUBLIC void ice_dump_candidate_pairs_foundations(const IceCheckList *cl); 926 927 /** 928 * Dump the list of component IDs of an ICE check list in the traces (debug function). 929 */ 930 MS2_PUBLIC void ice_dump_componentIDs(const IceCheckList *cl); 931 932 /** 933 * Dump an ICE check list in the traces (debug function). 934 */ 935 MS2_PUBLIC void ice_dump_check_list(const IceCheckList *cl); 936 937 /** 938 * Dump the triggered checks queue of an ICE check list in the traces (debug function). 939 */ 940 MS2_PUBLIC void ice_dump_triggered_checks_queue(const IceCheckList *cl); 941 942 943 #ifdef __cplusplus 944 } 945 #endif 946 947 #endif 948