1 /* $Id$ */ 2 /* 3 * Copyright (C) 2008-2011 Teluu Inc. (http://www.teluu.com) 4 * Copyright (C) 2003-2008 Benny Prijono <benny@prijono.org> 5 * 6 * This program is free software; you can redistribute it and/or modify 7 * it under the terms of the GNU General Public License as published by 8 * the Free Software Foundation; either version 2 of the License, or 9 * (at your option) any later version. 10 * 11 * This program is distributed in the hope that it will be useful, 12 * but WITHOUT ANY WARRANTY; without even the implied warranty of 13 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the 14 * GNU General Public License for more details. 15 * 16 * You should have received a copy of the GNU General Public License 17 * along with this program; if not, write to the Free Software 18 * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA 19 */ 20 #ifndef __PJNATH_ICE_SESSION_H__ 21 #define __PJNATH_ICE_SESSION_H__ 22 23 /** 24 * @file ice_session.h 25 * @brief ICE session management 26 */ 27 #include <pjnath/types.h> 28 #include <pjnath/stun_session.h> 29 #include <pjnath/errno.h> 30 #include <pj/sock.h> 31 #include <pj/timer.h> 32 33 PJ_BEGIN_DECL 34 35 36 /** 37 * @addtogroup PJNATH_ICE_SESSION 38 * @{ 39 * 40 * This module describes #pj_ice_sess, a transport independent ICE session, 41 * part of PJNATH - the Open Source NAT helper library. 42 * 43 * \section pj_ice_sess_sec ICE Session 44 * 45 * An ICE session, represented by #pj_ice_sess structure, is the lowest 46 * abstraction of ICE in PJNATH, and it is used to perform and manage 47 * connectivity checks of transport address candidates <b>within a 48 * single media stream</b> (note: this differs from what is described 49 * in ICE draft, where an ICE session manages the whole media sessions 50 * rather than just a single stream). 51 * 52 * The ICE session described here is independent from any transports, 53 * meaning that the actual network I/O for this session would have to 54 * be performed by the application, or higher layer abstraction. 55 * Using this framework, application would give any incoming packets to 56 * the ICE session, and it would provide the ICE session with a callback 57 * to send outgoing message. 58 * 59 * For higher abstraction of ICE where transport is included, please 60 * see \ref PJNATH_ICE_STREAM_TRANSPORT. 61 * 62 * \subsection pj_ice_sess_using_sec Using The ICE Session 63 * 64 * The steps below describe how to use ICE session. Alternatively application 65 * can use the higher level ICE API, \ref PJNATH_ICE_STREAM_TRANSPORT, 66 * which has provided the integration of ICE with socket transport. 67 * 68 * The steps to use ICE session is similar for both offerer and 69 * answerer: 70 * - create ICE session with #pj_ice_sess_create(). Among other things, 71 * application needs to specify: 72 * - STUN configuration (pj_stun_config), containing STUN settings 73 * such as timeout values and the instances of timer heap and 74 * ioqueue. 75 * - Session name, useful for identifying this session in the log. 76 * - Initial ICE role (#pj_ice_sess_role). The role can be changed 77 * at later time with #pj_ice_sess_change_role(), and ICE session 78 * can also change its role automatically when it detects role 79 * conflict. 80 * - Number of components in the media session. 81 * - Callback to receive ICE events (#pj_ice_sess_cb) 82 * - Optional local ICE username and password. If these arguments 83 * are NULL, they will be generated randomly. 84 * - Add local candidates for each component, with #pj_ice_sess_add_cand(). 85 * A candidate is represented with #pj_ice_sess_cand structure. 86 * Each component must be provided with at least one candidate, and 87 * all components must have the same number of candidates. Failing 88 * to comply with this will cause failure during pairing process. 89 * - Create offer to describe local ICE candidates. ICE session does not 90 * provide a function to create such offer, but application should be 91 * able to create one since it knows about all components and candidates. 92 * If application uses \ref PJNATH_ICE_STREAM_TRANSPORT, it can 93 * enumerate local candidates by calling #pj_ice_strans_enum_cands(). 94 * Application may use #pj_ice_sess_find_default_cand() to let ICE 95 * session chooses the default transport address to be used in SDP 96 * c= and m= lines. 97 * - Send the offer to remote endpoint using signaling such as SIP. 98 * - Once application has received the answer, it should parse this 99 * answer, build array of remote candidates, and create check lists by 100 * calling #pj_ice_sess_create_check_list(). This process is known as 101 * pairing the candidates, and will result in the creation of check lists. 102 * - Once checklist has been created, application then can call 103 * #pj_ice_sess_start_check() to instruct ICE session to start 104 * performing connectivity checks. The ICE session performs the 105 * connectivity checks by processing each check in the checklists. 106 * - Application will be notified about the result of ICE connectivity 107 * checks via the callback that was given in #pj_ice_sess_create() 108 * above. 109 * 110 * To send data, application calls #pj_ice_sess_send_data(). If ICE 111 * negotiation has not completed, ICE session would simply drop the data, 112 * and return error to caller. If ICE negotiation has completed 113 * successfully, ICE session will in turn call the \a on_tx_pkt 114 * callback of #pj_ice_sess_cb instance that was previously registered 115 * in #pj_ice_sess_create() above. 116 * 117 * When application receives any packets on the underlying sockets, it 118 * must call #pj_ice_sess_on_rx_pkt(). The ICE session will inspect the 119 * packet to decide whether to process it locally (if the packet is a 120 * STUN message and is part of ICE session) or otherwise pass it back to 121 * application via \a on_rx_data callback. 122 */ 123 124 /** 125 * Forward declaration for checklist. 126 */ 127 typedef struct pj_ice_sess_checklist pj_ice_sess_checklist; 128 129 /** 130 * This enumeration describes the type of an ICE candidate. 131 */ 132 typedef enum pj_ice_cand_type 133 { 134 /** 135 * ICE host candidate. A host candidate represents the actual local 136 * transport address in the host. 137 */ 138 PJ_ICE_CAND_TYPE_HOST, 139 140 /** 141 * ICE server reflexive candidate, which represents the public mapped 142 * address of the local address, and is obtained by sending STUN 143 * Binding request from the host candidate to a STUN server. 144 */ 145 PJ_ICE_CAND_TYPE_SRFLX, 146 147 /** 148 * ICE peer reflexive candidate, which is the address as seen by peer 149 * agent during connectivity check. 150 */ 151 PJ_ICE_CAND_TYPE_PRFLX, 152 153 /** 154 * ICE relayed candidate, which represents the address allocated in 155 * TURN server. 156 */ 157 PJ_ICE_CAND_TYPE_RELAYED, 158 159 /** 160 * Number of defined ICE candidate types. 161 */ 162 PJ_ICE_CAND_TYPE_MAX 163 164 } pj_ice_cand_type; 165 166 167 /** Forward declaration for pj_ice_sess */ 168 typedef struct pj_ice_sess pj_ice_sess; 169 170 /** Forward declaration for pj_ice_sess_check */ 171 typedef struct pj_ice_sess_check pj_ice_sess_check; 172 173 /** Forward declaration for pj_ice_sess_cand */ 174 typedef struct pj_ice_sess_cand pj_ice_sess_cand; 175 176 /** 177 * This structure describes ICE component. 178 * A media stream may require multiple components, each of which has 179 * to work for the media stream as a whole to work. For media streams 180 * based on RTP, there are two components per media stream - one for RTP, 181 * and one for RTCP. 182 */ 183 typedef struct pj_ice_sess_comp 184 { 185 /** 186 * Pointer to ICE check with highest priority which connectivity check 187 * has been successful. The value will be NULL if a no successful check 188 * has not been found for this component. 189 */ 190 pj_ice_sess_check *valid_check; 191 192 /** 193 * Pointer to ICE check with highest priority which connectivity check 194 * has been successful and it has been nominated. The value may be NULL 195 * if there is no such check yet. 196 */ 197 pj_ice_sess_check *nominated_check; 198 199 /** 200 * The STUN session to be used to send and receive STUN messages for this 201 * component. 202 */ 203 pj_stun_session *stun_sess; 204 205 } pj_ice_sess_comp; 206 207 208 /** 209 * Data structure to be attached to internal message processing. 210 */ 211 typedef struct pj_ice_msg_data 212 { 213 /** Transport ID for this message */ 214 unsigned transport_id; 215 216 /** Flag to indicate whether data.req contains data */ 217 pj_bool_t has_req_data; 218 219 /** The data */ 220 union data { 221 /** Request data */ 222 struct request_data { 223 pj_ice_sess *ice; /**< ICE session */ 224 pj_ice_sess_checklist *clist; /**< Checklist */ 225 unsigned ckid; /**< Check ID */ 226 pj_ice_sess_cand *lcand; /**< Local cand */ 227 pj_ice_sess_cand *rcand; /**< Remote cand */ 228 } req; 229 } data; 230 231 } pj_ice_msg_data; 232 233 234 /** 235 * This structure describes an ICE candidate. 236 * ICE candidate is a transport address that is to be tested by ICE 237 * procedures in order to determine its suitability for usage for 238 * receipt of media. Candidates also have properties - their type 239 * (server reflexive, relayed or host), priority, foundation, and 240 * base. 241 */ 242 struct pj_ice_sess_cand 243 { 244 /** 245 * The candidate ID. 246 */ 247 unsigned id; 248 249 /** 250 * The candidate type, as described in #pj_ice_cand_type enumeration. 251 */ 252 pj_ice_cand_type type; 253 254 /** 255 * Status of this candidate. The value will be PJ_SUCCESS if candidate 256 * address has been resolved successfully, PJ_EPENDING when the address 257 * resolution process is in progress, or other value when the address 258 * resolution has completed with failure. 259 */ 260 pj_status_t status; 261 262 /** 263 * The component ID of this candidate. Note that component IDs starts 264 * with one for RTP and two for RTCP. In other words, it's not zero 265 * based. 266 */ 267 pj_uint8_t comp_id; 268 269 /** 270 * Transport ID to be used to send packets for this candidate. 271 */ 272 pj_uint8_t transport_id; 273 274 /** 275 * Local preference value, which typically is 65535. 276 */ 277 pj_uint16_t local_pref; 278 279 /** 280 * The foundation string, which is an identifier which value will be 281 * equivalent for two candidates that are of the same type, share the 282 * same base, and come from the same STUN server. The foundation is 283 * used to optimize ICE performance in the Frozen algorithm. 284 */ 285 pj_str_t foundation; 286 287 /** 288 * The candidate's priority, a 32-bit unsigned value which value will be 289 * calculated by the ICE session when a candidate is registered to the 290 * ICE session. 291 */ 292 pj_uint32_t prio; 293 294 /** 295 * IP address of this candidate. For host candidates, this represents 296 * the local address of the socket. For reflexive candidates, the value 297 * will be the public address allocated in NAT router for the host 298 * candidate and as reported in MAPPED-ADDRESS or XOR-MAPPED-ADDRESS 299 * attribute of STUN Binding request. For relayed candidate, the value 300 * will be the address allocated in the TURN server by STUN Allocate 301 * request. 302 */ 303 pj_sockaddr addr; 304 305 /** 306 * Base address of this candidate. "Base" refers to the address an agent 307 * sends from for a particular candidate. For host candidates, the base 308 * is the same as the host candidate itself. For reflexive candidates, 309 * the base is the local IP address of the socket. For relayed candidates, 310 * the base address is the transport address allocated in the TURN server 311 * for this candidate. 312 */ 313 pj_sockaddr base_addr; 314 315 /** 316 * Related address, which is used for informational only and is not used 317 * in any way by the ICE session. 318 */ 319 pj_sockaddr rel_addr; 320 321 }; 322 323 324 /** 325 * This enumeration describes the state of ICE check. 326 */ 327 typedef enum pj_ice_sess_check_state 328 { 329 /** 330 * A check for this pair hasn't been performed, and it can't 331 * yet be performed until some other check succeeds, allowing this 332 * pair to unfreeze and move into the Waiting state. 333 */ 334 PJ_ICE_SESS_CHECK_STATE_FROZEN, 335 336 /** 337 * A check has not been performed for this pair, and can be 338 * performed as soon as it is the highest priority Waiting pair on 339 * the check list. 340 */ 341 PJ_ICE_SESS_CHECK_STATE_WAITING, 342 343 /** 344 * A check has not been performed for this pair, and can be 345 * performed as soon as it is the highest priority Waiting pair on 346 * the check list. 347 */ 348 PJ_ICE_SESS_CHECK_STATE_IN_PROGRESS, 349 350 /** 351 * A check has not been performed for this pair, and can be 352 * performed as soon as it is the highest priority Waiting pair on 353 * the check list. 354 */ 355 PJ_ICE_SESS_CHECK_STATE_SUCCEEDED, 356 357 /** 358 * A check for this pair was already done and failed, either 359 * never producing any response or producing an unrecoverable failure 360 * response. 361 */ 362 PJ_ICE_SESS_CHECK_STATE_FAILED 363 364 } pj_ice_sess_check_state; 365 366 367 /** 368 * This structure describes an ICE connectivity check. An ICE check 369 * contains a candidate pair, and will involve sending STUN Binding 370 * Request transaction for the purposes of verifying connectivity. 371 * A check is sent from the local candidate to the remote candidate 372 * of a candidate pair. 373 */ 374 struct pj_ice_sess_check 375 { 376 /** 377 * Pointer to local candidate entry of this check. 378 */ 379 pj_ice_sess_cand *lcand; 380 381 /** 382 * Pointer to remote candidate entry of this check. 383 */ 384 pj_ice_sess_cand *rcand; 385 386 /** 387 * Foundation index, referring to foundation array defined in checklist. 388 */ 389 int foundation_idx; 390 391 /** 392 * Check priority. 393 */ 394 pj_timestamp prio; 395 396 /** 397 * Connectivity check state. 398 */ 399 pj_ice_sess_check_state state; 400 401 /** 402 * STUN transmit data containing STUN Binding request that was sent 403 * as part of this check. The value will only be set when this check 404 * has a pending transaction, and is used to cancel the transaction 405 * when other check has succeeded. 406 */ 407 pj_stun_tx_data *tdata; 408 409 /** 410 * Flag to indicate whether this check is nominated. A nominated check 411 * contains USE-CANDIDATE attribute in its STUN Binding request. 412 */ 413 pj_bool_t nominated; 414 415 /** 416 * When the check failed, this will contain the failure status of the 417 * STUN transaction. 418 */ 419 pj_status_t err_code; 420 }; 421 422 423 /** 424 * This enumeration describes ICE checklist state. 425 */ 426 typedef enum pj_ice_sess_checklist_state 427 { 428 /** 429 * The checklist is not yet running. 430 */ 431 PJ_ICE_SESS_CHECKLIST_ST_IDLE, 432 433 /** 434 * In this state, ICE checks are still in progress for this 435 * media stream. 436 */ 437 PJ_ICE_SESS_CHECKLIST_ST_RUNNING, 438 439 /** 440 * In this state, ICE checks have completed for this media stream, 441 * either successfully or with failure. 442 */ 443 PJ_ICE_SESS_CHECKLIST_ST_COMPLETED 444 445 } pj_ice_sess_checklist_state; 446 447 448 /** 449 * This structure represents ICE check list, that is an ordered set of 450 * candidate pairs that an agent will use to generate checks. 451 */ 452 struct pj_ice_sess_checklist 453 { 454 /** 455 * The checklist state. 456 */ 457 pj_ice_sess_checklist_state state; 458 459 /** 460 * Number of candidate pairs (checks). 461 */ 462 unsigned count; 463 464 /** 465 * Array of candidate pairs (checks). 466 */ 467 pj_ice_sess_check checks[PJ_ICE_MAX_CHECKS]; 468 469 /** 470 * Number of foundations. 471 */ 472 unsigned foundation_cnt; 473 474 /** 475 * Array of foundations, check foundation index refers to this array. 476 */ 477 pj_str_t foundation[PJ_ICE_MAX_CHECKS * 2]; 478 479 /** 480 * A timer used to perform periodic check for this checklist. 481 */ 482 pj_timer_entry timer; 483 484 }; 485 486 487 /** 488 * This structure contains callbacks that will be called by the ICE 489 * session. 490 */ 491 typedef struct pj_ice_sess_cb 492 { 493 /** 494 * An optional callback that will be called by the ICE session when 495 * a valid pair has been found during ICE negotiation. 496 * 497 * @param ice The ICE session. 498 */ 499 void (*on_valid_pair)(pj_ice_sess *ice); 500 501 /** 502 * An optional callback that will be called by the ICE session when 503 * ICE negotiation has completed, successfully or with failure. 504 * 505 * @param ice The ICE session. 506 * @param status Will contain PJ_SUCCESS if ICE negotiation is 507 * successful, or some error code. 508 */ 509 void (*on_ice_complete)(pj_ice_sess *ice, pj_status_t status); 510 511 /** 512 * A mandatory callback which will be called by the ICE session when 513 * it needs to send outgoing STUN packet. 514 * 515 * @param ice The ICE session. 516 * @param comp_id ICE component ID. 517 * @param transport_id Transport ID. 518 * @param pkt The STUN packet. 519 * @param size The size of the packet. 520 * @param dst_addr Packet destination address. 521 * @param dst_addr_len Length of destination address. 522 */ 523 pj_status_t (*on_tx_pkt)(pj_ice_sess *ice, unsigned comp_id, 524 unsigned transport_id, 525 const void *pkt, pj_size_t size, 526 const pj_sockaddr_t *dst_addr, 527 unsigned dst_addr_len); 528 529 /** 530 * A mandatory callback which will be called by the ICE session when 531 * it receives packet which is not part of ICE negotiation. 532 * 533 * @param ice The ICE session. 534 * @param comp_id ICE component ID. 535 * @param transport_id Transport ID. 536 * @param pkt The whole packet. 537 * @param size Size of the packet. 538 * @param src_addr Source address where this packet was received 539 * from. 540 * @param src_addr_len The length of source address. 541 */ 542 void (*on_rx_data)(pj_ice_sess *ice, unsigned comp_id, 543 unsigned transport_id, 544 void *pkt, pj_size_t size, 545 const pj_sockaddr_t *src_addr, 546 unsigned src_addr_len); 547 } pj_ice_sess_cb; 548 549 550 /** 551 * This enumeration describes the role of the ICE agent. 552 */ 553 typedef enum pj_ice_sess_role 554 { 555 /** 556 * The role is unknown. 557 */ 558 PJ_ICE_SESS_ROLE_UNKNOWN, 559 560 /** 561 * The ICE agent is in controlled role. 562 */ 563 PJ_ICE_SESS_ROLE_CONTROLLED, 564 565 /** 566 * The ICE agent is in controlling role. 567 */ 568 PJ_ICE_SESS_ROLE_CONTROLLING 569 570 } pj_ice_sess_role; 571 572 573 /** 574 * This structure represents an incoming check (an incoming Binding 575 * request message), and is mainly used to keep early checks in the 576 * list in the ICE session. An early check is a request received 577 * from remote when we haven't received SDP answer yet, therefore we 578 * can't perform triggered check. For such cases, keep the incoming 579 * request in a list, and we'll do triggered checks (simultaneously) 580 * as soon as we receive answer. 581 */ 582 typedef struct pj_ice_rx_check 583 { 584 PJ_DECL_LIST_MEMBER(struct pj_ice_rx_check); /**< Standard list */ 585 586 unsigned comp_id; /**< Component ID. */ 587 unsigned transport_id; /**< Transport ID. */ 588 589 pj_sockaddr src_addr; /**< Source address of request */ 590 unsigned src_addr_len; /**< Length of src address. */ 591 592 pj_bool_t use_candidate; /**< USE-CANDIDATE is present? */ 593 pj_uint32_t priority; /**< PRIORITY value in the req. */ 594 pj_stun_uint64_attr *role_attr; /**< ICE-CONTROLLING/CONTROLLED */ 595 596 } pj_ice_rx_check; 597 598 599 /** 600 * This enumeration describes the modes of trickle ICE. 601 */ 602 typedef enum pj_ice_sess_trickle 603 { 604 /** 605 * Trickle ICE is disabled. 606 */ 607 PJ_ICE_SESS_TRICKLE_DISABLED, 608 609 /** 610 * Half trickle ICE. This mode has better interoperability when remote 611 * capability of ICE trickle is unknown at ICE initialization. 612 * 613 * As ICE initiator, it will convey all local ICE candidates to remote 614 * (just like regular ICE) and be ready to receive either response, 615 * trickle or regular ICE. As ICE answerer, it will do trickle ICE if 616 * it receives an offer with trickle ICE indication, otherwise it will do 617 * regular ICE. 618 */ 619 PJ_ICE_SESS_TRICKLE_HALF, 620 621 /** 622 * Full trickle ICE. Only use this mode if it is known that that remote 623 * supports trickle ICE. The discovery whether remote supports trickle 624 * ICE should be done prior to ICE initialization and done by application 625 * (ICE does not provide the discovery mechanism). 626 */ 627 PJ_ICE_SESS_TRICKLE_FULL 628 629 } pj_ice_sess_trickle; 630 631 632 /** 633 * This structure describes various ICE session options. Application 634 * configure the ICE session with these options by calling 635 * #pj_ice_sess_set_options(). 636 */ 637 typedef struct pj_ice_sess_options 638 { 639 /** 640 * Specify whether to use aggressive nomination. This setting can only 641 * be enabled when trickle ICE is disabled. 642 */ 643 pj_bool_t aggressive; 644 645 /** 646 * For controlling agent if it uses regular nomination, specify the delay 647 * to perform nominated check (connectivity check with USE-CANDIDATE 648 * attribute) after all components have a valid pair. 649 * 650 * Default value is PJ_ICE_NOMINATED_CHECK_DELAY. 651 */ 652 unsigned nominated_check_delay; 653 654 /** 655 * For a controlled agent, specify how long it wants to wait (in 656 * milliseconds) for the controlling agent to complete sending 657 * connectivity check with nominated flag set to true for all components 658 * after the controlled agent has found that all connectivity checks in 659 * its checklist have been completed and there is at least one successful 660 * (but not nominated) check for every component. 661 * 662 * Default value for this option is 663 * ICE_CONTROLLED_AGENT_WAIT_NOMINATION_TIMEOUT. Specify -1 to disable 664 * this timer. 665 */ 666 int controlled_agent_want_nom_timeout; 667 668 /** 669 * Trickle ICE mode. Note that, when enabled, aggressive nomination will 670 * be automatically disabled. 671 * 672 * Default value is PJ_ICE_SESS_TRICKLE_DISABLED. 673 */ 674 pj_ice_sess_trickle trickle; 675 676 } pj_ice_sess_options; 677 678 679 /** 680 * This structure describes the ICE session. For this version of PJNATH, 681 * an ICE session corresponds to a single media stream (unlike the ICE 682 * session described in the ICE standard where an ICE session covers the 683 * whole media and may consist of multiple media streams). The decision 684 * to support only a single media session was chosen for simplicity, 685 * while still allowing application to utilize multiple media streams by 686 * creating multiple ICE sessions, one for each media stream. 687 */ 688 struct pj_ice_sess 689 { 690 char obj_name[PJ_MAX_OBJ_NAME]; /**< Object name. */ 691 692 pj_pool_t *pool; /**< Pool instance. */ 693 void *user_data; /**< App. data. */ 694 pj_grp_lock_t *grp_lock; /**< Group lock */ 695 pj_ice_sess_role role; /**< ICE role. */ 696 pj_ice_sess_options opt; /**< Options */ 697 pj_timestamp tie_breaker; /**< Tie breaker value */ 698 pj_uint8_t *prefs; /**< Type preference. */ 699 pj_bool_t is_nominating; /**< Nominating stage */ 700 pj_bool_t is_complete; /**< Complete? */ 701 pj_bool_t is_destroying; /**< Destroy is called */ 702 pj_bool_t valid_pair_found; /**< First pair found */ 703 pj_bool_t is_trickling; /**< End-of-candidates ind 704 sent/received? */ 705 pj_status_t ice_status; /**< Error status. */ 706 pj_timer_entry timer; /**< ICE timer. */ 707 pj_timer_entry timer_end_of_cand; /**< End-of-cand timer. */ 708 pj_ice_sess_cb cb; /**< Callback. */ 709 710 pj_stun_config stun_cfg; /**< STUN settings. */ 711 712 /* STUN credentials */ 713 pj_str_t tx_ufrag; /**< Remote ufrag. */ 714 pj_str_t tx_uname; /**< Uname for TX. */ 715 pj_str_t tx_pass; /**< Remote password. */ 716 pj_str_t rx_ufrag; /**< Local ufrag. */ 717 pj_str_t rx_uname; /**< Uname for RX */ 718 pj_str_t rx_pass; /**< Local password. */ 719 720 /* Components */ 721 unsigned comp_cnt; /**< # of components. */ 722 pj_ice_sess_comp comp[PJ_ICE_MAX_COMP]; /**< Component array */ 723 unsigned comp_ka; /**< Next comp for KA */ 724 725 /* Local candidates */ 726 unsigned lcand_cnt; /**< # of local cand. */ 727 pj_ice_sess_cand lcand[PJ_ICE_MAX_CAND]; /**< Array of cand. */ 728 unsigned lcand_paired; /**< # of local cand 729 paired (trickling) */ 730 731 /* Remote candidates */ 732 unsigned rcand_cnt; /**< # of remote cand. */ 733 pj_ice_sess_cand rcand[PJ_ICE_MAX_CAND]; /**< Array of cand. */ 734 unsigned rcand_paired; /**< # of remote cand 735 paired (trickling) */ 736 737 /** Array of transport datas */ 738 pj_ice_msg_data tp_data[PJ_ICE_MAX_STUN + PJ_ICE_MAX_TURN]; 739 740 /* List of eearly checks */ 741 pj_ice_rx_check early_check; /**< Early checks. */ 742 743 /* Checklist */ 744 pj_ice_sess_checklist clist; /**< Active checklist */ 745 746 /* Valid list */ 747 pj_ice_sess_checklist valid_list; /**< Valid list. */ 748 749 /** Temporary buffer for misc stuffs to avoid using stack too much */ 750 union { 751 char txt[128]; 752 char errmsg[PJ_ERR_MSG_SIZE]; 753 } tmp; 754 }; 755 756 757 /** 758 * This is a utility function to retrieve the string name for the 759 * particular candidate type. 760 * 761 * @param type Candidate type. 762 * 763 * @return The string representation of the candidate type. 764 */ 765 PJ_DECL(const char*) pj_ice_get_cand_type_name(pj_ice_cand_type type); 766 767 768 /** 769 * This is a utility function to retrieve the string name for the 770 * particular role type. 771 * 772 * @param role Role type. 773 * 774 * @return The string representation of the role. 775 */ 776 PJ_DECL(const char*) pj_ice_sess_role_name(pj_ice_sess_role role); 777 778 779 /** 780 * This is a utility function to calculate the foundation identification 781 * for a candidate. 782 * 783 * @param pool Pool to allocate the foundation string. 784 * @param foundation Pointer to receive the foundation string. 785 * @param type Candidate type. 786 * @param base_addr Base address of the candidate. 787 */ 788 PJ_DECL(void) pj_ice_calc_foundation(pj_pool_t *pool, 789 pj_str_t *foundation, 790 pj_ice_cand_type type, 791 const pj_sockaddr *base_addr); 792 793 /** 794 * Initialize ICE session options with library default values. 795 * 796 * @param opt ICE session options. 797 */ 798 PJ_DECL(void) pj_ice_sess_options_default(pj_ice_sess_options *opt); 799 800 /** 801 * Create ICE session with the specified role and number of components. 802 * Application would typically need to create an ICE session before 803 * sending an offer or upon receiving one. After the session is created, 804 * application can register candidates to the ICE session by calling 805 * #pj_ice_sess_add_cand() function. 806 * 807 * @param stun_cfg The STUN configuration settings, containing among 808 * other things the timer heap instance to be used 809 * by the ICE session. 810 * @param name Optional name to identify this ICE instance in 811 * the log file. 812 * @param role ICE role. 813 * @param comp_cnt Number of components. 814 * @param cb ICE callback. 815 * @param local_ufrag Optional string to be used as local username to 816 * authenticate incoming STUN binding request. If 817 * the value is NULL, a random string will be 818 * generated. 819 * @param local_passwd Optional string to be used as local password. 820 * @param grp_lock Optional group lock to be used by this session. 821 * If NULL, the session will create one itself. 822 * @param p_ice Pointer to receive the ICE session instance. 823 * 824 * @return PJ_SUCCESS if ICE session is created successfully. 825 */ 826 PJ_DECL(pj_status_t) pj_ice_sess_create(pj_stun_config *stun_cfg, 827 const char *name, 828 pj_ice_sess_role role, 829 unsigned comp_cnt, 830 const pj_ice_sess_cb *cb, 831 const pj_str_t *local_ufrag, 832 const pj_str_t *local_passwd, 833 pj_grp_lock_t *grp_lock, 834 pj_ice_sess **p_ice); 835 836 /** 837 * Get the value of various options of the ICE session. 838 * 839 * @param ice The ICE session. 840 * @param opt The options to be initialized with the values 841 * from the ICE session. 842 * 843 * @return PJ_SUCCESS on success, or the appropriate error. 844 */ 845 PJ_DECL(pj_status_t) pj_ice_sess_get_options(pj_ice_sess *ice, 846 pj_ice_sess_options *opt); 847 848 /** 849 * Specify various options for this ICE session. Application MUST only 850 * call this function after the ICE session has been created but before 851 * any connectivity check is started. 852 * 853 * Application should call #pj_ice_sess_get_options() to initialize the 854 * options with their default values. 855 * 856 * @param ice The ICE session. 857 * @param opt Options to be applied to the ICE session. 858 * 859 * @return PJ_SUCCESS on success, or the appropriate error. 860 */ 861 PJ_DECL(pj_status_t) pj_ice_sess_set_options(pj_ice_sess *ice, 862 const pj_ice_sess_options *opt); 863 864 /** 865 * Destroy ICE session. This will cancel any connectivity checks currently 866 * running, if any, and any other events scheduled by this session, as well 867 * as all memory resources. 868 * 869 * @param ice ICE session instance. 870 * 871 * @return PJ_SUCCESS on success. 872 */ 873 PJ_DECL(pj_status_t) pj_ice_sess_destroy(pj_ice_sess *ice); 874 875 876 /** 877 * Change session role. This happens for example when ICE session was 878 * created with controlled role when receiving an offer, but it turns out 879 * that the offer contains "a=ice-lite" attribute when the SDP gets 880 * inspected. 881 * 882 * @param ice The ICE session. 883 * @param new_role The new role to be set. 884 * 885 * @return PJ_SUCCESS on success, or the appropriate error. 886 */ 887 PJ_DECL(pj_status_t) pj_ice_sess_change_role(pj_ice_sess *ice, 888 pj_ice_sess_role new_role); 889 890 891 /** 892 * Assign a custom preference values for ICE candidate types. By assigning 893 * custom preference value, application can control the order of candidates 894 * to be checked first. The default preference settings is to use 126 for 895 * host candidates, 100 for server reflexive candidates, 110 for peer 896 * reflexive candidates, an 0 for relayed candidates. 897 * 898 * Note that this function must be called before any candidates are added 899 * to the ICE session. 900 * 901 * @param ice The ICE session. 902 * @param prefs Array of candidate preference value. The values are 903 * put in the array indexed by the candidate type as 904 * specified in pj_ice_cand_type. 905 * 906 * @return PJ_SUCCESS on success, or the appropriate error code. 907 */ 908 PJ_DECL(pj_status_t) pj_ice_sess_set_prefs(pj_ice_sess *ice, 909 const pj_uint8_t prefs[4]); 910 911 912 913 /** 914 * Add a candidate to this ICE session. Application must add candidates for 915 * each components ID before it can start pairing the candidates and 916 * performing connectivity checks. 917 * 918 * @param ice ICE session instance. 919 * @param comp_id Component ID of this candidate. 920 * @param transport_id Transport ID to be used to send packets for this 921 * candidate. 922 * @param type Candidate type. 923 * @param local_pref Local preference for this candidate, which 924 * normally should be set to 65535. 925 * @param foundation Foundation identification. 926 * @param addr The candidate address. 927 * @param base_addr The candidate's base address. 928 * @param rel_addr Optional related address. 929 * @param addr_len Length of addresses. 930 * @param p_cand_id Optional pointer to receive the candidate ID. 931 * 932 * @return PJ_SUCCESS if candidate is successfully added. 933 */ 934 PJ_DECL(pj_status_t) pj_ice_sess_add_cand(pj_ice_sess *ice, 935 unsigned comp_id, 936 unsigned transport_id, 937 pj_ice_cand_type type, 938 pj_uint16_t local_pref, 939 const pj_str_t *foundation, 940 const pj_sockaddr_t *addr, 941 const pj_sockaddr_t *base_addr, 942 const pj_sockaddr_t *rel_addr, 943 int addr_len, 944 unsigned *p_cand_id); 945 946 /** 947 * Find default candidate for the specified component ID, using this 948 * rule: 949 * - if the component has a successful candidate pair, then the 950 * local candidate of this pair will be returned. 951 * - otherwise a relay, reflexive, or host candidate will be selected 952 * on that specified order. 953 * 954 * @param ice The ICE session instance. 955 * @param comp_id The component ID. 956 * @param p_cand_id Pointer to receive the candidate ID. 957 * 958 * @return PJ_SUCCESS if a candidate has been selected. 959 */ 960 PJ_DECL(pj_status_t) pj_ice_sess_find_default_cand(pj_ice_sess *ice, 961 unsigned comp_id, 962 int *p_cand_id); 963 964 /** 965 * Pair the local and remote candidates to create check list. Application 966 * typically would call this function after receiving SDP containing ICE 967 * candidates from the remote host (either upon receiving the initial 968 * offer, for UAS, or upon receiving the answer, for UAC). 969 * 970 * Note that ICE connectivity check will not start until application calls 971 * #pj_ice_sess_start_check(). 972 * 973 * @param ice ICE session instance. 974 * @param rem_ufrag Remote ufrag, as seen in the SDP received from 975 * the remote agent. 976 * @param rem_passwd Remote password, as seen in the SDP received from 977 * the remote agent. 978 * @param rem_cand_cnt Number of remote candidates. 979 * @param rem_cand Remote candidate array. Remote candidates are 980 * gathered from the SDP received from the remote 981 * agent. 982 * 983 * @return PJ_SUCCESS or the appropriate error code. 984 */ 985 PJ_DECL(pj_status_t) 986 pj_ice_sess_create_check_list(pj_ice_sess *ice, 987 const pj_str_t *rem_ufrag, 988 const pj_str_t *rem_passwd, 989 unsigned rem_cand_cnt, 990 const pj_ice_sess_cand rem_cand[]); 991 992 993 /** 994 * Update check list after receiving new remote ICE candidates or after 995 * new local ICE candidates are found and conveyed to remote. This function 996 * can also be called to indicate that trickling has completed, i.e: 997 * local candidates gathering completed and remote has sent end-of-candidate 998 * indication. 999 * 1000 * This function is only applicable when trickle ICE is not disabled. 1001 * 1002 * @param ice ICE session instance. 1003 * @param rem_ufrag Remote ufrag, as seen in the SDP received from 1004 * the remote agent. 1005 * @param rem_passwd Remote password, as seen in the SDP received from 1006 * the remote agent. 1007 * @param rem_cand_cnt Number of remote candidates. 1008 * @param rem_cand Remote candidate array. Remote candidates are 1009 * gathered from the SDP received from the remote 1010 * agent. 1011 * @param trickle_done Flag to indicate end of trickling, set to PJ_TRUE 1012 * after all local candidates have been gathered AND 1013 * after receiving end-of-candidate indication from 1014 * remote. 1015 * 1016 * @return PJ_SUCCESS or the appropriate error code. 1017 */ 1018 PJ_DECL(pj_status_t) 1019 pj_ice_sess_update_check_list(pj_ice_sess *ice, 1020 const pj_str_t *rem_ufrag, 1021 const pj_str_t *rem_passwd, 1022 unsigned rem_cand_cnt, 1023 const pj_ice_sess_cand rem_cand[], 1024 pj_bool_t trickle_done); 1025 1026 1027 /** 1028 * Start ICE periodic check. This function will return immediately, and 1029 * application will be notified about the connectivity check status in 1030 * #pj_ice_sess_cb callback. 1031 * 1032 * @param ice The ICE session instance. 1033 * 1034 * @return PJ_SUCCESS or the appropriate error code. 1035 */ 1036 PJ_DECL(pj_status_t) pj_ice_sess_start_check(pj_ice_sess *ice); 1037 1038 1039 /** 1040 * Send data using this ICE session. If ICE checks have not produced a 1041 * valid check for the specified component ID, this function will return 1042 * with failure. Otherwise ICE session will send the packet to remote 1043 * destination using the nominated local candidate for the specified 1044 * component. 1045 * 1046 * This function will in turn call \a on_tx_pkt function in 1047 * #pj_ice_sess_cb callback to actually send the packet to the wire. 1048 * 1049 * @param ice The ICE session. 1050 * @param comp_id Component ID. 1051 * @param data The data or packet to be sent. 1052 * @param data_len Size of data or packet, in bytes. 1053 * 1054 * @return If the callback \a on_tx_pkt() is called, this 1055 * will contain the return value of the callback. 1056 * Otherwise, it will indicate failure with 1057 * the appropriate error code. 1058 */ 1059 PJ_DECL(pj_status_t) pj_ice_sess_send_data(pj_ice_sess *ice, 1060 unsigned comp_id, 1061 const void *data, 1062 pj_size_t data_len); 1063 1064 /** 1065 * Report the arrival of packet to the ICE session. Since ICE session 1066 * itself doesn't have any transports, it relies on application or 1067 * higher layer component to give incoming packets to the ICE session. 1068 * If the packet is not a STUN packet, this packet will be given back 1069 * to application via \a on_rx_data() callback in #pj_ice_sess_cb. 1070 * 1071 * @param ice The ICE session. 1072 * @param comp_id Component ID. 1073 * @param transport_id Number to identify where this packet was received 1074 * from. This parameter will be returned back to 1075 * application in \a on_tx_pkt() callback. 1076 * @param pkt Incoming packet. 1077 * @param pkt_size Size of incoming packet. 1078 * @param src_addr Source address of the packet. 1079 * @param src_addr_len Length of the address. 1080 * 1081 * @return PJ_SUCCESS or the appropriate error code. 1082 */ 1083 PJ_DECL(pj_status_t) pj_ice_sess_on_rx_pkt(pj_ice_sess *ice, 1084 unsigned comp_id, 1085 unsigned transport_id, 1086 void *pkt, 1087 pj_size_t pkt_size, 1088 const pj_sockaddr_t *src_addr, 1089 int src_addr_len); 1090 1091 1092 1093 /** 1094 * @} 1095 */ 1096 1097 1098 PJ_END_DECL 1099 1100 1101 #endif /* __PJNATH_ICE_SESSION_H__ */ 1102 1103