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_STRANS_H__ 21 #define __PJNATH_ICE_STRANS_H__ 22 23 24 /** 25 * @file ice_strans.h 26 * @brief ICE Stream Transport 27 */ 28 #include <pjnath/ice_session.h> 29 #include <pjnath/stun_sock.h> 30 #include <pjnath/turn_sock.h> 31 #include <pjlib-util/resolver.h> 32 #include <pj/ioqueue.h> 33 #include <pj/timer.h> 34 35 36 PJ_BEGIN_DECL 37 38 39 /** 40 * @addtogroup PJNATH_ICE_STREAM_TRANSPORT 41 * @{ 42 * 43 * This module describes ICE stream transport, as represented by #pj_ice_strans 44 * structure, and is part of PJNATH - the Open Source NAT traversal helper 45 * library. 46 * 47 * ICE stream transport, as represented by #pj_ice_strans structure, is an ICE 48 * capable class for transporting media streams within a media session. 49 * It consists of one or more transport sockets (typically two for RTP 50 * based communication - one for RTP and one for RTCP), and an 51 * \ref PJNATH_ICE_SESSION for performing connectivity checks among the. 52 * various candidates of the transport addresses. 53 * 54 * 55 * \section ice_strans_using_sec Using the ICE stream transport 56 * 57 * The steps below describe how to use ICE session: 58 * 59 * - initialize a #pj_ice_strans_cfg structure. This contains various 60 * settings for the ICE stream transport, and among other things contains 61 * the STUN and TURN settings.\n\n 62 * - create the instance with #pj_ice_strans_create(). Among other things, 63 * the function needs the following arguments: 64 * - the #pj_ice_strans_cfg structure for the main configurations 65 * - number of components to be supported 66 * - instance of #pj_ice_strans_cb structure to report callbacks to 67 * application.\n\n 68 * - while the #pj_ice_strans_create() call completes immediately, the 69 * initialization will be running in the background to gather the 70 * candidates (for example STUN and TURN candidates, if they are enabled 71 * in the #pj_ice_strans_cfg setting). Application will be notified when 72 * the initialization completes in the \a on_ice_complete callback of 73 * the #pj_ice_strans_cb structure (the \a op argument of this callback 74 * will be PJ_ICE_STRANS_OP_INIT).\n\n 75 * - when media stream is to be started (for example, a call is to be 76 * started), create an ICE session by calling #pj_ice_strans_init_ice().\n\n 77 * - the application now typically will need to communicate local ICE 78 * information to remote host. It can achieve this by using the following 79 * functions to query local ICE information: 80 * - #pj_ice_strans_get_ufrag_pwd() 81 * - #pj_ice_strans_enum_cands() 82 * - #pj_ice_strans_get_def_cand()\n 83 * The application may need to encode the above information as SDP.\n\n 84 * - when the application receives remote ICE information (for example, from 85 * the SDP received from remote), it can now start ICE negotiation, by 86 * calling #pj_ice_strans_start_ice(). This function requires some 87 * information about remote ICE agent such as remote ICE username fragment 88 * and password as well as array of remote candidates.\n\n 89 * - note that the PJNATH library does not work with SDP; application would 90 * need to encode and parse the SDP itself.\n\n 91 * - once ICE negotiation has been started, application will be notified 92 * about the completion in the \a on_ice_complete() callback of the 93 * #pj_ice_strans_cb.\n\n 94 * - at any time, application may send or receive data. However the ICE 95 * stream transport may not be able to send it depending on its current 96 * state. Before ICE negotiation is started, the data will be sent using 97 * default candidate of the component. After negotiation is completed, 98 * data will be sent using the candidate from the successful/nominated 99 * pair. The ICE stream transport may not be able to send data while 100 * negotiation is in progress.\n\n 101 * - application sends data by using #pj_ice_strans_sendto2(). Incoming 102 * data will be reported in \a on_rx_data() callback of the 103 * #pj_ice_strans_cb.\n\n 104 * - once the media session has finished (e.g. user hangs up the call), 105 * destroy the ICE session with #pj_ice_strans_stop_ice().\n\n 106 * - at this point, application may destroy the ICE stream transport itself, 107 * or let it run so that it can be reused to create other ICE session. 108 * The benefit of letting the ICE stream transport alive (without any 109 * session active) is to avoid delay with the initialization, howerver 110 * keeping the transport alive means the transport needs to keep the 111 * STUN binding open by using keep-alive and also TURN allocation alive, 112 * and this will consume power which is an important issue for mobile 113 * applications.\n\n 114 */ 115 116 /* Deprecated API pj_ice_strans_sendto() due to its limitations. See 117 * below for more info and refer to 118 * https://trac.pjsip.org/repos/ticket/2229 for more details. 119 */ 120 #ifndef DEPRECATED_FOR_TICKET_2229 121 # define DEPRECATED_FOR_TICKET_2229 0 122 #endif 123 124 /** Forward declaration for ICE stream transport. */ 125 typedef struct pj_ice_strans pj_ice_strans; 126 127 /** Transport operation types to be reported on \a on_status() callback */ 128 typedef enum pj_ice_strans_op 129 { 130 /** Initialization (candidate gathering) */ 131 PJ_ICE_STRANS_OP_INIT, 132 133 /** Negotiation */ 134 PJ_ICE_STRANS_OP_NEGOTIATION, 135 136 /** This operation is used to report failure in keep-alive operation. 137 * Currently it is only used to report TURN Refresh failure. 138 */ 139 PJ_ICE_STRANS_OP_KEEP_ALIVE, 140 141 /** IP address change notification from STUN keep-alive operation. 142 */ 143 PJ_ICE_STRANS_OP_ADDR_CHANGE 144 145 } pj_ice_strans_op; 146 147 /** 148 * This structure contains callbacks that will be called by the 149 * ICE stream transport. 150 */ 151 typedef struct pj_ice_strans_cb 152 { 153 /** 154 * This callback will be called when the ICE transport receives 155 * incoming packet from the sockets which is not related to ICE 156 * (for example, normal RTP/RTCP packet destined for application). 157 * 158 * @param ice_st The ICE stream transport. 159 * @param comp_id The component ID. 160 * @param pkt The packet. 161 * @param size Size of the packet. 162 * @param src_addr Source address of the packet. 163 * @param src_addr_len Length of the source address. 164 */ 165 void (*on_rx_data)(pj_ice_strans *ice_st, 166 unsigned comp_id, 167 void *pkt, pj_size_t size, 168 const pj_sockaddr_t *src_addr, 169 unsigned src_addr_len); 170 171 /** 172 * This callback is optional and will be called to notify the status of 173 * async send operations. 174 * 175 * @param ice_st The ICE stream transport. 176 * @param sent If value is positive non-zero it indicates the 177 * number of data sent. When the value is negative, 178 * it contains the error code which can be retrieved 179 * by negating the value (i.e. status=-sent). 180 */ 181 void (*on_data_sent)(pj_ice_strans *sock, 182 pj_ssize_t sent); 183 184 /** 185 * An optional callback that will be called by the ICE transport when a 186 * valid pair has been found during ICE negotiation. 187 * 188 * @param ice_st The ICE stream transport. 189 */ 190 void (*on_valid_pair)(pj_ice_strans *ice_st); 191 192 /** 193 * Callback to report status of various ICE operations. 194 * 195 * @param ice_st The ICE stream transport. 196 * @param op The operation which status is being reported. 197 * @param status Operation status. 198 */ 199 void (*on_ice_complete)(pj_ice_strans *ice_st, 200 pj_ice_strans_op op, 201 pj_status_t status); 202 203 /** 204 * Callback to report a new ICE local candidate, e.g: after successful 205 * STUN Binding, after a successful TURN allocation. Only new candidates 206 * whose type is server reflexive or relayed will be notified via this 207 * callback. This callback also indicates end-of-candidate via parameter 208 * 'last'. 209 * 210 * Trickle ICE can use this callback to convey the new candidate 211 * to remote agent and monitor end-of-candidate indication. 212 * 213 * @param ice_st The ICE stream transport. 214 * @param cand The new local candidate, can be NULL when the last 215 * local candidate initialization failed/timeout. 216 * @param end_of_cand PJ_TRUE if this is the last of local candidate. 217 */ 218 void (*on_new_candidate)(pj_ice_strans *ice_st, 219 const pj_ice_sess_cand *cand, 220 pj_bool_t end_of_cand); 221 222 } pj_ice_strans_cb; 223 224 225 /** 226 * STUN and local transport settings for ICE stream transport. 227 */ 228 typedef struct pj_ice_strans_stun_cfg 229 { 230 /** 231 * Address family, IPv4 or IPv6. 232 * 233 * Default value is pj_AF_INET() (IPv4) 234 */ 235 int af; 236 237 /** 238 * Optional configuration for STUN transport. The default 239 * value will be initialized with #pj_stun_sock_cfg_default(). 240 */ 241 pj_stun_sock_cfg cfg; 242 243 /** 244 * Maximum number of host candidates to be added. If the 245 * value is zero, no host candidates will be added. 246 * 247 * Default: 64 248 */ 249 unsigned max_host_cands; 250 251 /** 252 * Include loopback addresses in the host candidates. 253 * 254 * Default: PJ_FALSE 255 */ 256 pj_bool_t loop_addr; 257 258 /** 259 * Specify the STUN server domain or hostname or IP address. 260 * If DNS SRV resolution is required, application must fill 261 * in this setting with the domain name of the STUN server 262 * and set the resolver instance in the \a resolver field. 263 * Otherwise if the \a resolver setting is not set, this 264 * field will be resolved with hostname resolution and in 265 * this case the \a port field must be set. 266 * 267 * The \a port field should also be set even when DNS SRV 268 * resolution is used, in case the DNS SRV resolution fails. 269 * 270 * When this field is empty, STUN mapped address resolution 271 * will not be performed. In this case only ICE host candidates 272 * will be added to the ICE transport, unless if \a no_host_cands 273 * field is set. In this case, both host and srflx candidates 274 * are disabled. 275 * 276 * If there are more than one STUN candidates per ICE stream 277 * transport component, the standard recommends to use the same 278 * STUN server for all STUN candidates. 279 * 280 * The default value is empty. 281 */ 282 pj_str_t server; 283 284 /** 285 * The port number of the STUN server, when \a server 286 * field specifies a hostname rather than domain name. This 287 * field should also be set even when the \a server 288 * specifies a domain name, to allow DNS SRV resolution 289 * to fallback to DNS A/AAAA resolution when the DNS SRV 290 * resolution fails. 291 * 292 * The default value is PJ_STUN_PORT. 293 */ 294 pj_uint16_t port; 295 296 /** 297 * Ignore STUN resolution error and proceed with just local 298 * addresses. 299 * 300 * The default is PJ_FALSE 301 */ 302 pj_bool_t ignore_stun_error; 303 304 } pj_ice_strans_stun_cfg; 305 306 307 /** 308 * TURN transport settings for ICE stream transport. 309 */ 310 typedef struct pj_ice_strans_turn_cfg 311 { 312 /** 313 * Address family, IPv4 or IPv6. 314 * 315 * Default value is pj_AF_INET() (IPv4) 316 */ 317 int af; 318 319 /** 320 * Optional TURN socket settings. The default values will be 321 * initialized by #pj_turn_sock_cfg_default(). This contains 322 * settings such as QoS. 323 */ 324 pj_turn_sock_cfg cfg; 325 326 /** 327 * Specify the TURN server domain or hostname or IP address. 328 * If DNS SRV resolution is required, application must fill 329 * in this setting with the domain name of the TURN server 330 * and set the resolver instance in the \a resolver field. 331 * Otherwise if the \a resolver setting is not set, this 332 * field will be resolved with hostname resolution and in 333 * this case the \a port field must be set. 334 * 335 * The \a port field should also be set even when DNS SRV 336 * resolution is used, in case the DNS SRV resolution fails. 337 * 338 * When this field is empty, relay candidate will not be 339 * created. 340 * 341 * The default value is empty. 342 */ 343 pj_str_t server; 344 345 /** 346 * The port number of the TURN server, when \a server 347 * field specifies a hostname rather than domain name. This 348 * field should also be set even when the \a server 349 * specifies a domain name, to allow DNS SRV resolution 350 * to fallback to DNS A/AAAA resolution when the DNS SRV 351 * resolution fails. 352 * 353 * Default is zero. 354 */ 355 pj_uint16_t port; 356 357 /** 358 * Type of connection to the TURN server. 359 * 360 * Default is PJ_TURN_TP_UDP. 361 */ 362 pj_turn_tp_type conn_type; 363 364 /** 365 * Credential to be used for the TURN session. This setting 366 * is mandatory. 367 * 368 * Default is to have no credential. 369 */ 370 pj_stun_auth_cred auth_cred; 371 372 /** 373 * Optional TURN Allocate parameter. The default value will be 374 * initialized by #pj_turn_alloc_param_default(). 375 */ 376 pj_turn_alloc_param alloc_param; 377 378 } pj_ice_strans_turn_cfg; 379 380 381 /** 382 * This structure describes ICE stream transport configuration. Application 383 * should initialize the structure by calling #pj_ice_strans_cfg_default() 384 * before changing the settings. 385 */ 386 typedef struct pj_ice_strans_cfg 387 { 388 /** 389 * The address family which will be used as the default address 390 * in the SDP offer. Setting this to pj_AF_UNSPEC() means that 391 * the address family will not be considered during the process 392 * of default candidate selection. 393 * 394 * The default value is pj_AF_INET() (IPv4). 395 */ 396 int af; 397 398 /** 399 * STUN configuration which contains the timer heap and 400 * ioqueue instance to be used, and STUN retransmission 401 * settings. This setting is mandatory. 402 * 403 * The default value is all zero. Application must initialize 404 * this setting with #pj_stun_config_init(). 405 */ 406 pj_stun_config stun_cfg; 407 408 /** 409 * DNS resolver to be used to resolve servers. If DNS SRV 410 * resolution is required, the resolver must be set. 411 * 412 * The default value is NULL. 413 */ 414 pj_dns_resolver *resolver; 415 416 /** 417 * This contains various STUN session options. Once the ICE stream 418 * transport is created, application may also change the options 419 * with #pj_ice_strans_set_options(). 420 */ 421 pj_ice_sess_options opt; 422 423 /** 424 * Warning: this field is deprecated, please use \a stun_tp field instead. 425 * To maintain backward compatibility, if \a stun_tp_cnt is zero, the 426 * value of this field will be copied to \a stun_tp. 427 * 428 * STUN and local transport settings. This specifies the settings 429 * for local UDP socket address and STUN resolved address. 430 */ 431 pj_ice_strans_stun_cfg stun; 432 433 /** 434 * Number of STUN transports. 435 * 436 * Default: 0 437 */ 438 unsigned stun_tp_cnt; 439 440 /** 441 * STUN and local transport settings. This specifies the settings 442 * for local UDP socket address and STUN resolved address. 443 */ 444 pj_ice_strans_stun_cfg stun_tp[PJ_ICE_MAX_STUN]; 445 446 /** 447 * Warning: this field is deprecated, please use \a turn_tp field instead. 448 * To maintain backward compatibility, if \a turn_tp_cnt is zero, the 449 * value of this field will be copied to \a turn_tp. 450 * 451 * TURN transport settings. 452 */ 453 pj_ice_strans_turn_cfg turn; 454 455 /** 456 * Number of TURN transports. 457 * 458 * Default: 0 459 */ 460 unsigned turn_tp_cnt; 461 462 /** 463 * TURN transport settings. 464 */ 465 pj_ice_strans_turn_cfg turn_tp[PJ_ICE_MAX_TURN]; 466 467 /** 468 * Number of send buffers used for pj_ice_strans_sendto2(). If the send 469 * buffers are full, pj_ice_strans_sendto()/sendto2() will return 470 * PJ_EBUSY. 471 * 472 * Set this to 0 to disable buffering (then application will have to 473 * maintain the buffer passed to pj_ice_strans_sendto()/sendto2() 474 * until it has been sent). 475 * 476 * Default: 4 477 */ 478 unsigned num_send_buf; 479 480 /** 481 * Buffer size used for pj_ice_strans_sendto2(). 482 * 483 * Default: 0 (size determined by the size of the first packet sent). 484 */ 485 unsigned send_buf_size; 486 487 /** 488 * Component specific settings, which will override the settings in 489 * the STUN and TURN settings above. For example, setting the QoS 490 * parameters here allows the application to have different QoS 491 * traffic type for RTP and RTCP component. 492 */ 493 struct { 494 /** 495 * QoS traffic type to be set on this transport. When application 496 * wants to apply QoS tagging to the transport, it's preferable to 497 * set this field rather than \a qos_param fields since this is 498 * more portable. 499 * 500 * Default value is PJ_QOS_TYPE_BEST_EFFORT. 501 */ 502 pj_qos_type qos_type; 503 504 /** 505 * Set the low level QoS parameters to the transport. This is a 506 * lower level operation than setting the \a qos_type field and 507 * may not be supported on all platforms. 508 * 509 * By default all settings in this structure are disabled. 510 */ 511 pj_qos_params qos_params; 512 513 /** 514 * Specify target value for socket receive buffer size. It will be 515 * applied using setsockopt(). When it fails to set the specified 516 * size, it will try with lower value until the highest possible is 517 * successfully set. 518 * 519 * When this is set to zero, this component will apply socket receive 520 * buffer size settings specified in STUN and TURN socket config 521 * above, i.e: \a stun::cfg::so_rcvbuf_size and 522 * \a turn::cfg::so_rcvbuf_size. Otherwise, this setting will be 523 * applied to STUN and TURN sockets for this component, overriding 524 * the setting specified in STUN/TURN socket config. 525 * 526 * Default: 0 527 */ 528 unsigned so_rcvbuf_size; 529 530 /** 531 * Specify target value for socket send buffer size. It will be 532 * applied using setsockopt(). When it fails to set the specified 533 * size, it will try with lower value until the highest possible is 534 * successfully set. 535 * 536 * When this is set to zero, this component will apply socket send 537 * buffer size settings specified in STUN and TURN socket config 538 * above, i.e: \a stun::cfg::so_sndbuf_size and 539 * \a turn::cfg::so_sndbuf_size. Otherwise, this setting will be 540 * applied to STUN and TURN sockets for this component, overriding 541 * the setting specified in STUN/TURN socket config. 542 * 543 * Default: 0 544 */ 545 unsigned so_sndbuf_size; 546 547 } comp[PJ_ICE_MAX_COMP]; 548 549 } pj_ice_strans_cfg; 550 551 552 /** 553 * ICE stream transport's state. 554 */ 555 typedef enum pj_ice_strans_state 556 { 557 /** 558 * ICE stream transport is not created. 559 */ 560 PJ_ICE_STRANS_STATE_NULL, 561 562 /** 563 * ICE candidate gathering process is in progress. 564 */ 565 PJ_ICE_STRANS_STATE_INIT, 566 567 /** 568 * ICE stream transport initialization/candidate gathering process is 569 * complete, ICE session may be created on this stream transport. 570 */ 571 PJ_ICE_STRANS_STATE_READY, 572 573 /** 574 * New session has been created and the session is ready. 575 */ 576 PJ_ICE_STRANS_STATE_SESS_READY, 577 578 /** 579 * ICE negotiation is in progress. 580 */ 581 PJ_ICE_STRANS_STATE_NEGO, 582 583 /** 584 * ICE negotiation has completed successfully and media is ready 585 * to be used. 586 */ 587 PJ_ICE_STRANS_STATE_RUNNING, 588 589 /** 590 * ICE negotiation has completed with failure. 591 */ 592 PJ_ICE_STRANS_STATE_FAILED 593 594 } pj_ice_strans_state; 595 596 597 /** 598 * Initialize ICE transport configuration with default values. 599 * 600 * @param cfg The configuration to be initialized. 601 */ 602 PJ_DECL(void) pj_ice_strans_cfg_default(pj_ice_strans_cfg *cfg); 603 604 605 /** 606 * Initialize ICE STUN transport configuration with default values. 607 * 608 * @param cfg The configuration to be initialized. 609 */ 610 PJ_DECL(void) pj_ice_strans_stun_cfg_default(pj_ice_strans_stun_cfg *cfg); 611 612 613 /** 614 * Initialize ICE TURN transport configuration with default values. 615 * 616 * @param cfg The configuration to be initialized. 617 */ 618 PJ_DECL(void) pj_ice_strans_turn_cfg_default(pj_ice_strans_turn_cfg *cfg); 619 620 621 /** 622 * Copy configuration. 623 * 624 * @param pool Pool. 625 * @param dst Destination. 626 * @param src Source. 627 */ 628 PJ_DECL(void) pj_ice_strans_cfg_copy(pj_pool_t *pool, 629 pj_ice_strans_cfg *dst, 630 const pj_ice_strans_cfg *src); 631 632 633 /** 634 * Create and initialize the ICE stream transport with the specified 635 * parameters. 636 * 637 * @param name Optional name for logging identification. 638 * @param cfg Configuration. 639 * @param comp_cnt Number of components. 640 * @param user_data Arbitrary user data to be associated with this 641 * ICE stream transport. 642 * @param cb Callback. 643 * @param p_ice_st Pointer to receive the ICE stream transport 644 * instance. 645 * 646 * @return PJ_SUCCESS if ICE stream transport is created 647 * successfully. 648 */ 649 PJ_DECL(pj_status_t) pj_ice_strans_create(const char *name, 650 const pj_ice_strans_cfg *cfg, 651 unsigned comp_cnt, 652 void *user_data, 653 const pj_ice_strans_cb *cb, 654 pj_ice_strans **p_ice_st); 655 656 /** 657 * Get ICE session state. 658 * 659 * @param ice_st The ICE stream transport. 660 * 661 * @return ICE session state. 662 */ 663 PJ_DECL(pj_ice_strans_state) pj_ice_strans_get_state(pj_ice_strans *ice_st); 664 665 666 /** 667 * Get string representation of ICE state. 668 * 669 * @param state ICE stream transport state. 670 * 671 * @return String. 672 */ 673 PJ_DECL(const char*) pj_ice_strans_state_name(pj_ice_strans_state state); 674 675 676 /** 677 * Destroy the ICE stream transport. This will destroy the ICE session 678 * inside the ICE stream transport, close all sockets and release all 679 * other resources. 680 * 681 * @param ice_st The ICE stream transport. 682 * 683 * @return PJ_SUCCESS, or the appropriate error code. 684 */ 685 PJ_DECL(pj_status_t) pj_ice_strans_destroy(pj_ice_strans *ice_st); 686 687 688 /** 689 * Get the user data associated with the ICE stream transport. 690 * 691 * @param ice_st The ICE stream transport. 692 * 693 * @return The user data. 694 */ 695 PJ_DECL(void*) pj_ice_strans_get_user_data(pj_ice_strans *ice_st); 696 697 698 /** 699 * Get the value of various options of the ICE stream transport. 700 * 701 * @param ice_st The ICE stream transport. 702 * @param opt The options to be initialized with the values 703 * from the ICE stream transport. 704 * 705 * @return PJ_SUCCESS on success, or the appropriate error. 706 */ 707 PJ_DECL(pj_status_t) pj_ice_strans_get_options(pj_ice_strans *ice_st, 708 pj_ice_sess_options *opt); 709 710 /** 711 * Specify various options for this ICE stream transport. Application 712 * should call #pj_ice_strans_get_options() to initialize the options 713 * with their default values. 714 * 715 * @param ice_st The ICE stream transport. 716 * @param opt Options to be applied to this ICE stream transport. 717 * 718 * @return PJ_SUCCESS on success, or the appropriate error. 719 */ 720 PJ_DECL(pj_status_t) pj_ice_strans_set_options(pj_ice_strans *ice_st, 721 const pj_ice_sess_options *opt); 722 723 /** 724 * Update number of components of the ICE stream transport. This can only 725 * reduce the number of components from the initial value specified in 726 * pj_ice_strans_create() and before ICE session is initialized. 727 * 728 * @param ice_st The ICE stream transport. 729 * @param comp_cnt Number of components. 730 * 731 * @return PJ_SUCCESS on success, or the appropriate error. 732 */ 733 PJ_DECL(pj_status_t) pj_ice_strans_update_comp_cnt(pj_ice_strans *ice_st, 734 unsigned comp_cnt); 735 736 /** 737 * Get the group lock for this ICE stream transport. 738 * 739 * @param ice_st The ICE stream transport. 740 * 741 * @return The group lock. 742 */ 743 PJ_DECL(pj_grp_lock_t *) pj_ice_strans_get_grp_lock(pj_ice_strans *ice_st); 744 745 /** 746 * Initialize the ICE session in the ICE stream transport. 747 * When application is about to send an offer containing ICE capability, 748 * or when it receives an offer containing ICE capability, it must 749 * call this function to initialize the internal ICE session. This would 750 * register all transport address aliases for each component to the ICE 751 * session as candidates. Then application can enumerate all local 752 * candidates by calling #pj_ice_strans_enum_cands(), and encode these 753 * candidates in the SDP to be sent to remote agent. 754 * 755 * @param ice_st The ICE stream transport. 756 * @param role ICE role. 757 * @param local_ufrag Optional local username fragment. 758 * @param local_passwd Optional local password. 759 * 760 * @return PJ_SUCCESS, or the appropriate error code. 761 */ 762 PJ_DECL(pj_status_t) pj_ice_strans_init_ice(pj_ice_strans *ice_st, 763 pj_ice_sess_role role, 764 const pj_str_t *local_ufrag, 765 const pj_str_t *local_passwd); 766 767 /** 768 * Check if the ICE stream transport has the ICE session created. The 769 * ICE session is created with #pj_ice_strans_init_ice(). 770 * 771 * @param ice_st The ICE stream transport. 772 * 773 * @return PJ_TRUE if #pj_ice_strans_init_ice() has been 774 * called. 775 */ 776 PJ_DECL(pj_bool_t) pj_ice_strans_has_sess(pj_ice_strans *ice_st); 777 778 779 /** 780 * Check if ICE negotiation is still running. 781 * 782 * @param ice_st The ICE stream transport. 783 * 784 * @return PJ_TRUE if ICE session has been created and ICE 785 * negotiation negotiation is in progress. 786 */ 787 PJ_DECL(pj_bool_t) pj_ice_strans_sess_is_running(pj_ice_strans *ice_st); 788 789 790 /** 791 * Check if ICE negotiation has completed. 792 * 793 * @param ice_st The ICE stream transport. 794 * 795 * @return PJ_TRUE if ICE session has been created and the 796 * negotiation is complete. 797 */ 798 PJ_DECL(pj_bool_t) pj_ice_strans_sess_is_complete(pj_ice_strans *ice_st); 799 800 801 /** 802 * Get the current/running component count. If ICE negotiation has not 803 * been started, the number of components will be equal to the number 804 * when the ICE stream transport was created. Once negotiation been 805 * started, the number of components will be the lowest number of 806 * component between local and remote agents. 807 * 808 * @param ice_st The ICE stream transport. 809 * 810 * @return The running number of components. 811 */ 812 PJ_DECL(unsigned) pj_ice_strans_get_running_comp_cnt(pj_ice_strans *ice_st); 813 814 815 /** 816 * Get the ICE username fragment and password of the ICE session. The 817 * local username fragment and password can only be retrieved once ICE 818 * session has been created with #pj_ice_strans_init_ice(). The remote 819 * username fragment and password can only be retrieved once ICE session 820 * has been started with #pj_ice_strans_start_ice(). 821 * 822 * Note that the string returned by this function is only valid throughout 823 * the duration of the ICE session, and the application must not modify 824 * these strings. Once the ICE session has been stopped with 825 * #pj_ice_strans_stop_ice(), the pointer in the string will no longer be 826 * valid. 827 * 828 * @param ice_st The ICE stream transport. 829 * @param loc_ufrag Optional pointer to receive ICE username fragment 830 * of local endpoint from the ICE session. 831 * @param loc_pwd Optional pointer to receive ICE password of local 832 * endpoint from the ICE session. 833 * @param rem_ufrag Optional pointer to receive ICE username fragment 834 * of remote endpoint from the ICE session. 835 * @param rem_pwd Optional pointer to receive ICE password of remote 836 * endpoint from the ICE session. 837 * 838 * @return PJ_SUCCESS if the strings have been retrieved 839 * successfully. 840 */ 841 PJ_DECL(pj_status_t) pj_ice_strans_get_ufrag_pwd(pj_ice_strans *ice_st, 842 pj_str_t *loc_ufrag, 843 pj_str_t *loc_pwd, 844 pj_str_t *rem_ufrag, 845 pj_str_t *rem_pwd); 846 847 848 /** 849 * Get the number of local candidates for the specified component ID. 850 * 851 * @param ice_st The ICE stream transport. 852 * @param comp_id Component ID. 853 * 854 * @return The number of candidates. 855 */ 856 PJ_DECL(unsigned) pj_ice_strans_get_cands_count(pj_ice_strans *ice_st, 857 unsigned comp_id); 858 859 /** 860 * Enumerate the local candidates for the specified component. 861 * 862 * @param ice_st The ICE stream transport. 863 * @param comp_id Component ID. 864 * @param count On input, it specifies the maximum number of 865 * elements. On output, it will be filled with 866 * the number of candidates copied to the 867 * array. 868 * @param cand Array of candidates. 869 * 870 * @return PJ_SUCCESS, or the appropriate error code. 871 */ 872 PJ_DECL(pj_status_t) pj_ice_strans_enum_cands(pj_ice_strans *ice_st, 873 unsigned comp_id, 874 unsigned *count, 875 pj_ice_sess_cand cand[]); 876 877 /** 878 * Get the default candidate for the specified component. When this 879 * function is called before ICE negotiation completes, the default 880 * candidate is selected according to local preference criteria. When 881 * this function is called after ICE negotiation completes, the 882 * default candidate is the candidate that forms the valid pair. 883 * 884 * @param ice_st The ICE stream transport. 885 * @param comp_id Component ID. 886 * @param cand Pointer to receive the default candidate 887 * information. 888 */ 889 PJ_DECL(pj_status_t) pj_ice_strans_get_def_cand(pj_ice_strans *ice_st, 890 unsigned comp_id, 891 pj_ice_sess_cand *cand); 892 893 /** 894 * Get the current ICE role. ICE session must have been initialized 895 * before this function can be called. 896 * 897 * @param ice_st The ICE stream transport. 898 * 899 * @return Current ICE role. 900 */ 901 PJ_DECL(pj_ice_sess_role) pj_ice_strans_get_role(pj_ice_strans *ice_st); 902 903 904 /** 905 * Change session role. This happens for example when ICE session was 906 * created with controlled role when receiving an offer, but it turns out 907 * that the offer contains "a=ice-lite" attribute when the SDP gets 908 * inspected. ICE session must have been initialized before this function 909 * can be called. 910 * 911 * @param ice_st The ICE stream transport. 912 * @param new_role The new role to be set. 913 * 914 * @return PJ_SUCCESS on success, or the appropriate error. 915 */ 916 PJ_DECL(pj_status_t) pj_ice_strans_change_role(pj_ice_strans *ice_st, 917 pj_ice_sess_role new_role); 918 919 920 /** 921 * Start ICE connectivity checks. This function can only be called 922 * after the ICE session has been created in the ICE stream transport 923 * with #pj_ice_strans_init_ice(). 924 * 925 * This function must be called once application has received remote 926 * candidate list (typically from the remote SDP). This function pairs 927 * local candidates with remote candidates, and starts ICE connectivity 928 * checks. The ICE session/transport will then notify the application 929 * via the callback when ICE connectivity checks completes, either 930 * successfully or with failure. 931 * 932 * @param ice_st The ICE stream transport. 933 * @param rem_ufrag Remote ufrag, as seen in the SDP received from 934 * the remote agent. 935 * @param rem_passwd Remote password, as seen in the SDP received from 936 * the remote agent. 937 * @param rcand_cnt Number of remote candidates in the array. 938 * @param rcand Remote candidates array. 939 * 940 * @return PJ_SUCCESS, or the appropriate error code. 941 */ 942 PJ_DECL(pj_status_t) pj_ice_strans_start_ice(pj_ice_strans *ice_st, 943 const pj_str_t *rem_ufrag, 944 const pj_str_t *rem_passwd, 945 unsigned rcand_cnt, 946 const pj_ice_sess_cand rcand[]); 947 948 949 /** 950 * Update check list after receiving new remote ICE candidates or after 951 * new local ICE candidates are found and conveyed to remote. This function 952 * can also be called after receiving end of candidate indication from 953 * either remote or local agent. 954 * 955 * This function is only applicable when trickle ICE is not disabled and 956 * after ICE session has been created using pj_ice_strans_init_ice(). 957 * 958 * @param ice_st The ICE stream transport. 959 * @param rem_ufrag Remote ufrag, as seen in the SDP received from 960 * the remote agent. 961 * @param rem_passwd Remote password, as seen in the SDP received from 962 * the remote agent. 963 * @param rcand_cnt Number of new remote candidates in the array. 964 * @param rcand New remote candidates array. 965 * @param rcand_end Set to PJ_TRUE if remote has signalled 966 * end-of-candidate. 967 * 968 * @return PJ_SUCCESS, or the appropriate error code. 969 */ 970 PJ_DECL(pj_status_t) pj_ice_strans_update_check_list( 971 pj_ice_strans *ice_st, 972 const pj_str_t *rem_ufrag, 973 const pj_str_t *rem_passwd, 974 unsigned rcand_cnt, 975 const pj_ice_sess_cand rcand[], 976 pj_bool_t rcand_end); 977 978 /** 979 * Retrieve the candidate pair that has been nominated and successfully 980 * checked for the specified component. If ICE negotiation is still in 981 * progress or it has failed, this function will return NULL. 982 * 983 * @param ice_st The ICE stream transport. 984 * @param comp_id Component ID. 985 * 986 * @return The valid pair as ICE checklist structure if the 987 * pair exist. 988 */ 989 PJ_DECL(const pj_ice_sess_check*) 990 pj_ice_strans_get_valid_pair(const pj_ice_strans *ice_st, 991 unsigned comp_id); 992 993 /** 994 * Stop and destroy the ICE session inside this media transport. Application 995 * needs to call this function once the media session is over (the call has 996 * been disconnected). 997 * 998 * Application MAY reuse this ICE stream transport for subsequent calls. 999 * In this case, it must call #pj_ice_strans_stop_ice() when the call is 1000 * disconnected, and reinitialize the ICE stream transport for subsequent 1001 * call with #pj_ice_strans_init_ice()/#pj_ice_strans_start_ice(). In this 1002 * case, the ICE stream transport will maintain the internal sockets and 1003 * continue to send STUN keep-alive packets and TURN Refresh request to 1004 * keep the NAT binding/TURN allocation open and to detect change in STUN 1005 * mapped address. 1006 * 1007 * If application does not want to reuse the ICE stream transport for 1008 * subsequent calls, it must call #pj_ice_strans_destroy() to destroy the 1009 * ICE stream transport altogether. 1010 * 1011 * @param ice_st The ICE stream transport. 1012 * 1013 * @return PJ_SUCCESS, or the appropriate error code. 1014 */ 1015 PJ_DECL(pj_status_t) pj_ice_strans_stop_ice(pj_ice_strans *ice_st); 1016 1017 1018 #if !DEPRECATED_FOR_TICKET_2229 1019 /** 1020 * Send outgoing packet using this transport. 1021 * Application can send data (normally RTP or RTCP packets) at any time 1022 * by calling this function. This function takes a destination 1023 * address as one of the arguments, and this destination address should 1024 * be taken from the default transport address of the component (that is 1025 * the address in SDP c= and m= lines, or in a=rtcp attribute). 1026 * If ICE negotiation is in progress, this function will send the data 1027 * to the destination address. Otherwise if ICE negotiation has completed 1028 * successfully, this function will send the data to the nominated remote 1029 * address, as negotiated by ICE. 1030 * 1031 * Limitations: 1032 * 1. This function cannot inform the app whether the data has been sent, 1033 * or currently still pending. 1034 * 2. In case that the data is still pending, the application has no way 1035 * of knowing the status of the send operation (whether it's a success 1036 * or failure). 1037 * Due to these limitations, the API is deprecated and will be removed 1038 * in the future. 1039 * 1040 * Note that application shouldn't mix using pj_ice_strans_sendto() and 1041 * pj_ice_strans_sendto2() to avoid inconsistent calling of 1042 * on_data_sent() callback. 1043 * 1044 * @param ice_st The ICE stream transport. 1045 * @param comp_id Component ID. 1046 * @param data The data or packet to be sent. 1047 * @param data_len Size of data or packet, in bytes. 1048 * @param dst_addr The destination address. 1049 * @param dst_addr_len Length of destination address. 1050 * 1051 * @return PJ_SUCCESS if data has been sent, or will be sent 1052 * later. No callback will be called. 1053 */ 1054 PJ_DECL(pj_status_t) pj_ice_strans_sendto(pj_ice_strans *ice_st, 1055 unsigned comp_id, 1056 const void *data, 1057 pj_size_t data_len, 1058 const pj_sockaddr_t *dst_addr, 1059 int dst_addr_len); 1060 #endif 1061 1062 1063 /** 1064 * Send outgoing packet using this transport. 1065 * Application can send data (normally RTP or RTCP packets) at any time 1066 * by calling this function. This function takes a destination 1067 * address as one of the arguments, and this destination address should 1068 * be taken from the default transport address of the component (that is 1069 * the address in SDP c= and m= lines, or in a=rtcp attribute). 1070 * If ICE negotiation is in progress, this function will try to send the data 1071 * via any valid candidate pair (which has passed ICE connectivity test). 1072 * If ICE negotiation has completed successfully, this function will send 1073 * the data to the nominated remote address, as negotiated by ICE. 1074 * If the ICE negotiation fails or valid candidate pair is not yet available, 1075 * this function will send the data using default candidate to the specified 1076 * destination address. 1077 * 1078 * Note that application shouldn't mix using pj_ice_strans_sendto() and 1079 * pj_ice_strans_sendto2() to avoid inconsistent calling of 1080 * on_data_sent() callback. 1081 * 1082 * @param ice_st The ICE stream transport. 1083 * @param comp_id Component ID. 1084 * @param data The data or packet to be sent. 1085 * @param data_len Size of data or packet, in bytes. 1086 * @param dst_addr The destination address. 1087 * @param dst_addr_len Length of destination address. 1088 * 1089 * @return PJ_SUCCESS if data has been sent, or 1090 * PJ_EPENDING if data cannot be sent immediately. In 1091 * this case the \a on_data_sent() callback will be 1092 * called when data is actually sent. Any other return 1093 * value indicates error condition. 1094 */ 1095 PJ_DECL(pj_status_t) pj_ice_strans_sendto2(pj_ice_strans *ice_st, 1096 unsigned comp_id, 1097 const void *data, 1098 pj_size_t data_len, 1099 const pj_sockaddr_t *dst_addr, 1100 int dst_addr_len); 1101 1102 1103 /** 1104 * @} 1105 */ 1106 1107 1108 PJ_END_DECL 1109 1110 1111 1112 #endif /* __PJNATH_ICE_STRANS_H__ */ 1113 1114