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