/usr/include/pjnath/ice_strans.h is in libpjproject-dev 2.1.0.0.ast20130823-1.
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 | /* $Id: ice_strans.h 4133 2012-05-21 14:00:17Z bennylp $ */
/*
* Copyright (C) 2008-2011 Teluu Inc. (http://www.teluu.com)
* Copyright (C) 2003-2008 Benny Prijono <benny@prijono.org>
*
* 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 __PJNATH_ICE_STRANS_H__
#define __PJNATH_ICE_STRANS_H__
/**
* @file ice_strans.h
* @brief ICE Stream Transport
*/
#include <pjnath/ice_session.h>
#include <pjnath/stun_sock.h>
#include <pjnath/turn_sock.h>
#include <pjlib-util/resolver.h>
#include <pj/ioqueue.h>
#include <pj/timer.h>
PJ_BEGIN_DECL
/**
* @addtogroup PJNATH_ICE_STREAM_TRANSPORT
* @{
*
* This module describes ICE stream transport, as represented by #pj_ice_strans
* structure, and is part of PJNATH - the Open Source NAT traversal helper
* library.
*
* ICE stream transport, as represented by #pj_ice_strans structure, is an ICE
* capable class for transporting media streams within a media session.
* It consists of one or more transport sockets (typically two for RTP
* based communication - one for RTP and one for RTCP), and an
* \ref PJNATH_ICE_SESSION for performing connectivity checks among the.
* various candidates of the transport addresses.
*
*
* \section ice_strans_using_sec Using the ICE stream transport
*
* The steps below describe how to use ICE session:
*
* - initialize a #pj_ice_strans_cfg structure. This contains various
* settings for the ICE stream transport, and among other things contains
* the STUN and TURN settings.\n\n
* - create the instance with #pj_ice_strans_create(). Among other things,
* the function needs the following arguments:
* - the #pj_ice_strans_cfg structure for the main configurations
* - number of components to be supported
* - instance of #pj_ice_strans_cb structure to report callbacks to
* application.\n\n
* - while the #pj_ice_strans_create() call completes immediately, the
* initialization will be running in the background to gather the
* candidates (for example STUN and TURN candidates, if they are enabled
* in the #pj_ice_strans_cfg setting). Application will be notified when
* the initialization completes in the \a on_ice_complete callback of
* the #pj_ice_strans_cb structure (the \a op argument of this callback
* will be PJ_ICE_STRANS_OP_INIT).\n\n
* - when media stream is to be started (for example, a call is to be
* started), create an ICE session by calling #pj_ice_strans_init_ice().\n\n
* - the application now typically will need to communicate local ICE
* information to remote host. It can achieve this by using the following
* functions to query local ICE information:
* - #pj_ice_strans_get_ufrag_pwd()
* - #pj_ice_strans_enum_cands()
* - #pj_ice_strans_get_def_cand()\n
* The application may need to encode the above information as SDP.\n\n
* - when the application receives remote ICE information (for example, from
* the SDP received from remote), it can now start ICE negotiation, by
* calling #pj_ice_strans_start_ice(). This function requires some
* information about remote ICE agent such as remote ICE username fragment
* and password as well as array of remote candidates.\n\n
* - note that the PJNATH library does not work with SDP; application would
* need to encode and parse the SDP itself.\n\n
* - once ICE negotiation has been started, application will be notified
* about the completion in the \a on_ice_complete() callback of the
* #pj_ice_strans_cb.\n\n
* - at any time, application may send or receive data. However the ICE
* stream transport may not be able to send it depending on its current
* state. Before ICE negotiation is started, the data will be sent using
* default candidate of the component. After negotiation is completed,
* data will be sent using the candidate from the successful/nominated
* pair. The ICE stream transport may not be able to send data while
* negotiation is in progress.\n\n
* - application sends data by using #pj_ice_strans_sendto(). Incoming
* data will be reported in \a on_rx_data() callback of the
* #pj_ice_strans_cb.\n\n
* - once the media session has finished (e.g. user hangs up the call),
* destroy the ICE session with #pj_ice_strans_stop_ice().\n\n
* - at this point, application may destroy the ICE stream transport itself,
* or let it run so that it can be reused to create other ICE session.
* The benefit of letting the ICE stream transport alive (without any
* session active) is to avoid delay with the initialization, howerver
* keeping the transport alive means the transport needs to keep the
* STUN binding open by using keep-alive and also TURN allocation alive,
* and this will consume power which is an important issue for mobile
* applications.\n\n
*/
/** Forward declaration for ICE stream transport. */
typedef struct pj_ice_strans pj_ice_strans;
/** Transport operation types to be reported on \a on_status() callback */
typedef enum pj_ice_strans_op
{
/** Initialization (candidate gathering) */
PJ_ICE_STRANS_OP_INIT,
/** Negotiation */
PJ_ICE_STRANS_OP_NEGOTIATION,
/** This operatino is used to report failure in keep-alive operation.
* Currently it is only used to report TURN Refresh failure.
*/
PJ_ICE_STRANS_OP_KEEP_ALIVE
} pj_ice_strans_op;
/**
* This structure contains callbacks that will be called by the
* ICE stream transport.
*/
typedef struct pj_ice_strans_cb
{
/**
* This callback will be called when the ICE transport receives
* incoming packet from the sockets which is not related to ICE
* (for example, normal RTP/RTCP packet destined for application).
*
* @param ice_st The ICE stream transport.
* @param comp_id The component ID.
* @param pkt The packet.
* @param size Size of the packet.
* @param src_addr Source address of the packet.
* @param src_addr_len Length of the source address.
*/
void (*on_rx_data)(pj_ice_strans *ice_st,
unsigned comp_id,
void *pkt, pj_size_t size,
const pj_sockaddr_t *src_addr,
unsigned src_addr_len);
/**
* Callback to report status of various ICE operations.
*
* @param ice_st The ICE stream transport.
* @param op The operation which status is being reported.
* @param status Operation status.
*/
void (*on_ice_complete)(pj_ice_strans *ice_st,
pj_ice_strans_op op,
pj_status_t status);
} pj_ice_strans_cb;
/**
* This structure describes ICE stream transport configuration. Application
* should initialize the structure by calling #pj_ice_strans_cfg_default()
* before changing the settings.
*/
typedef struct pj_ice_strans_cfg
{
/**
* Address family, IPv4 or IPv6. Currently only pj_AF_INET() (IPv4)
* is supported, and this is the default value.
*/
int af;
/**
* STUN configuration which contains the timer heap and
* ioqueue instance to be used, and STUN retransmission
* settings. This setting is mandatory.
*
* The default value is all zero. Application must initialize
* this setting with #pj_stun_config_init().
*/
pj_stun_config stun_cfg;
/**
* DNS resolver to be used to resolve servers. If DNS SRV
* resolution is required, the resolver must be set.
*
* The default value is NULL.
*/
pj_dns_resolver *resolver;
/**
* This contains various STUN session options. Once the ICE stream
* transport is created, application may also change the options
* with #pj_ice_strans_set_options().
*/
pj_ice_sess_options opt;
/**
* STUN and local transport settings. This specifies the
* settings for local UDP socket, which will be resolved
* to get the STUN mapped address.
*/
struct {
/**
* Optional configuration for STUN transport. The default
* value will be initialized with #pj_stun_sock_cfg_default().
*/
pj_stun_sock_cfg cfg;
/**
* Maximum number of host candidates to be added. If the
* value is zero, no host candidates will be added.
*
* Default: 64
*/
unsigned max_host_cands;
/**
* Include loopback addresses in the host candidates.
*
* Default: PJ_FALSE
*/
pj_bool_t loop_addr;
/**
* Specify the STUN server domain or hostname or IP address.
* If DNS SRV resolution is required, application must fill
* in this setting with the domain name of the STUN server
* and set the resolver instance in the \a resolver field.
* Otherwise if the \a resolver setting is not set, this
* field will be resolved with hostname resolution and in
* this case the \a port field must be set.
*
* The \a port field should also be set even when DNS SRV
* resolution is used, in case the DNS SRV resolution fails.
*
* When this field is empty, STUN mapped address resolution
* will not be performed. In this case only ICE host candidates
* will be added to the ICE transport, unless if \a no_host_cands
* field is set. In this case, both host and srflx candidates
* are disabled.
*
* The default value is empty.
*/
pj_str_t server;
/**
* The port number of the STUN server, when \a server
* field specifies a hostname rather than domain name. This
* field should also be set even when the \a server
* specifies a domain name, to allow DNS SRV resolution
* to fallback to DNS A/AAAA resolution when the DNS SRV
* resolution fails.
*
* The default value is PJ_STUN_PORT.
*/
pj_uint16_t port;
/**
* Ignore STUN resolution error and proceed with just local
* addresses.
*
* The default is PJ_FALSE
*/
pj_bool_t ignore_stun_error;
} stun;
/**
* TURN specific settings.
*/
struct {
/**
* Optional TURN socket settings. The default values will be
* initialized by #pj_turn_sock_cfg_default(). This contains
* settings such as QoS.
*/
pj_turn_sock_cfg cfg;
/**
* Specify the TURN server domain or hostname or IP address.
* If DNS SRV resolution is required, application must fill
* in this setting with the domain name of the TURN server
* and set the resolver instance in the \a resolver field.
* Otherwise if the \a resolver setting is not set, this
* field will be resolved with hostname resolution and in
* this case the \a port field must be set.
*
* The \a port field should also be set even when DNS SRV
* resolution is used, in case the DNS SRV resolution fails.
*
* When this field is empty, relay candidate will not be
* created.
*
* The default value is empty.
*/
pj_str_t server;
/**
* The port number of the TURN server, when \a server
* field specifies a hostname rather than domain name. This
* field should also be set even when the \a server
* specifies a domain name, to allow DNS SRV resolution
* to fallback to DNS A/AAAA resolution when the DNS SRV
* resolution fails.
*
* Default is zero.
*/
pj_uint16_t port;
/**
* Type of connection to the TURN server.
*
* Default is PJ_TURN_TP_UDP.
*/
pj_turn_tp_type conn_type;
/**
* Credential to be used for the TURN session. This setting
* is mandatory.
*
* Default is to have no credential.
*/
pj_stun_auth_cred auth_cred;
/**
* Optional TURN Allocate parameter. The default value will be
* initialized by #pj_turn_alloc_param_default().
*/
pj_turn_alloc_param alloc_param;
} turn;
/**
* Component specific settings, which will override the settings in
* the STUN and TURN settings above. For example, setting the QoS
* parameters here allows the application to have different QoS
* traffic type for RTP and RTCP component.
*/
struct {
/**
* QoS traffic type to be set on this transport. When application
* wants to apply QoS tagging to the transport, it's preferable to
* set this field rather than \a qos_param fields since this is
* more portable.
*
* Default value is PJ_QOS_TYPE_BEST_EFFORT.
*/
pj_qos_type qos_type;
/**
* Set the low level QoS parameters to the transport. This is a
* lower level operation than setting the \a qos_type field and
* may not be supported on all platforms.
*
* By default all settings in this structure are disabled.
*/
pj_qos_params qos_params;
} comp[PJ_ICE_MAX_COMP];
} pj_ice_strans_cfg;
/**
* ICE stream transport's state.
*/
typedef enum pj_ice_strans_state
{
/**
* ICE stream transport is not created.
*/
PJ_ICE_STRANS_STATE_NULL,
/**
* ICE candidate gathering process is in progress.
*/
PJ_ICE_STRANS_STATE_INIT,
/**
* ICE stream transport initialization/candidate gathering process is
* complete, ICE session may be created on this stream transport.
*/
PJ_ICE_STRANS_STATE_READY,
/**
* New session has been created and the session is ready.
*/
PJ_ICE_STRANS_STATE_SESS_READY,
/**
* ICE negotiation is in progress.
*/
PJ_ICE_STRANS_STATE_NEGO,
/**
* ICE negotiation has completed successfully and media is ready
* to be used.
*/
PJ_ICE_STRANS_STATE_RUNNING,
/**
* ICE negotiation has completed with failure.
*/
PJ_ICE_STRANS_STATE_FAILED
} pj_ice_strans_state;
/**
* Initialize ICE transport configuration with default values.
*
* @param cfg The configuration to be initialized.
*/
PJ_DECL(void) pj_ice_strans_cfg_default(pj_ice_strans_cfg *cfg);
/**
* Copy configuration.
*
* @param pool Pool.
* @param dst Destination.
* @param src Source.
*/
PJ_DECL(void) pj_ice_strans_cfg_copy(pj_pool_t *pool,
pj_ice_strans_cfg *dst,
const pj_ice_strans_cfg *src);
/**
* Create and initialize the ICE stream transport with the specified
* parameters.
*
* @param name Optional name for logging identification.
* @param cfg Configuration.
* @param comp_cnt Number of components.
* @param user_data Arbitrary user data to be associated with this
* ICE stream transport.
* @param cb Callback.
* @param p_ice_st Pointer to receive the ICE stream transport
* instance.
*
* @return PJ_SUCCESS if ICE stream transport is created
* successfully.
*/
PJ_DECL(pj_status_t) pj_ice_strans_create(const char *name,
const pj_ice_strans_cfg *cfg,
unsigned comp_cnt,
void *user_data,
const pj_ice_strans_cb *cb,
pj_ice_strans **p_ice_st);
/**
* Get ICE session state.
*
* @param ice_st The ICE stream transport.
*
* @return ICE session state.
*/
PJ_DECL(pj_ice_strans_state) pj_ice_strans_get_state(pj_ice_strans *ice_st);
/**
* Get string representation of ICE state.
*
* @param state ICE stream transport state.
*
* @return String.
*/
PJ_DECL(const char*) pj_ice_strans_state_name(pj_ice_strans_state state);
/**
* Destroy the ICE stream transport. This will destroy the ICE session
* inside the ICE stream transport, close all sockets and release all
* other resources.
*
* @param ice_st The ICE stream transport.
*
* @return PJ_SUCCESS, or the appropriate error code.
*/
PJ_DECL(pj_status_t) pj_ice_strans_destroy(pj_ice_strans *ice_st);
/**
* Get the user data associated with the ICE stream transport.
*
* @param ice_st The ICE stream transport.
*
* @return The user data.
*/
PJ_DECL(void*) pj_ice_strans_get_user_data(pj_ice_strans *ice_st);
/**
* Get the value of various options of the ICE stream transport.
*
* @param ice_st The ICE stream transport.
* @param opt The options to be initialized with the values
* from the ICE stream transport.
*
* @return PJ_SUCCESS on success, or the appropriate error.
*/
PJ_DECL(pj_status_t) pj_ice_strans_get_options(pj_ice_strans *ice_st,
pj_ice_sess_options *opt);
/**
* Specify various options for this ICE stream transport. Application
* should call #pj_ice_strans_get_options() to initialize the options
* with their default values.
*
* @param ice_st The ICE stream transport.
* @param opt Options to be applied to this ICE stream transport.
*
* @return PJ_SUCCESS on success, or the appropriate error.
*/
PJ_DECL(pj_status_t) pj_ice_strans_set_options(pj_ice_strans *ice_st,
const pj_ice_sess_options *opt);
/**
* Initialize the ICE session in the ICE stream transport.
* When application is about to send an offer containing ICE capability,
* or when it receives an offer containing ICE capability, it must
* call this function to initialize the internal ICE session. This would
* register all transport address aliases for each component to the ICE
* session as candidates. Then application can enumerate all local
* candidates by calling #pj_ice_strans_enum_cands(), and encode these
* candidates in the SDP to be sent to remote agent.
*
* @param ice_st The ICE stream transport.
* @param role ICE role.
* @param local_ufrag Optional local username fragment.
* @param local_passwd Optional local password.
*
* @return PJ_SUCCESS, or the appropriate error code.
*/
PJ_DECL(pj_status_t) pj_ice_strans_init_ice(pj_ice_strans *ice_st,
pj_ice_sess_role role,
const pj_str_t *local_ufrag,
const pj_str_t *local_passwd);
/**
* Check if the ICE stream transport has the ICE session created. The
* ICE session is created with #pj_ice_strans_init_ice().
*
* @param ice_st The ICE stream transport.
*
* @return PJ_TRUE if #pj_ice_strans_init_ice() has been
* called.
*/
PJ_DECL(pj_bool_t) pj_ice_strans_has_sess(pj_ice_strans *ice_st);
/**
* Check if ICE negotiation is still running.
*
* @param ice_st The ICE stream transport.
*
* @return PJ_TRUE if ICE session has been created and ICE
* negotiation negotiation is in progress.
*/
PJ_DECL(pj_bool_t) pj_ice_strans_sess_is_running(pj_ice_strans *ice_st);
/**
* Check if ICE negotiation has completed.
*
* @param ice_st The ICE stream transport.
*
* @return PJ_TRUE if ICE session has been created and the
* negotiation is complete.
*/
PJ_DECL(pj_bool_t) pj_ice_strans_sess_is_complete(pj_ice_strans *ice_st);
/**
* Get the current/running component count. If ICE negotiation has not
* been started, the number of components will be equal to the number
* when the ICE stream transport was created. Once negotiation been
* started, the number of components will be the lowest number of
* component between local and remote agents.
*
* @param ice_st The ICE stream transport.
*
* @return The running number of components.
*/
PJ_DECL(unsigned) pj_ice_strans_get_running_comp_cnt(pj_ice_strans *ice_st);
/**
* Get the ICE username fragment and password of the ICE session. The
* local username fragment and password can only be retrieved once ICE
* session has been created with #pj_ice_strans_init_ice(). The remote
* username fragment and password can only be retrieved once ICE session
* has been started with #pj_ice_strans_start_ice().
*
* Note that the string returned by this function is only valid throughout
* the duration of the ICE session, and the application must not modify
* these strings. Once the ICE session has been stopped with
* #pj_ice_strans_stop_ice(), the pointer in the string will no longer be
* valid.
*
* @param ice_st The ICE stream transport.
* @param loc_ufrag Optional pointer to receive ICE username fragment
* of local endpoint from the ICE session.
* @param loc_pwd Optional pointer to receive ICE password of local
* endpoint from the ICE session.
* @param rem_ufrag Optional pointer to receive ICE username fragment
* of remote endpoint from the ICE session.
* @param rem_pwd Optional pointer to receive ICE password of remote
* endpoint from the ICE session.
*
* @return PJ_SUCCESS if the strings have been retrieved
* successfully.
*/
PJ_DECL(pj_status_t) pj_ice_strans_get_ufrag_pwd(pj_ice_strans *ice_st,
pj_str_t *loc_ufrag,
pj_str_t *loc_pwd,
pj_str_t *rem_ufrag,
pj_str_t *rem_pwd);
/**
* Get the number of local candidates for the specified component ID.
*
* @param ice_st The ICE stream transport.
* @param comp_id Component ID.
*
* @return The number of candidates.
*/
PJ_DECL(unsigned) pj_ice_strans_get_cands_count(pj_ice_strans *ice_st,
unsigned comp_id);
/**
* Enumerate the local candidates for the specified component.
*
* @param ice_st The ICE stream transport.
* @param comp_id Component ID.
* @param count On input, it specifies the maximum number of
* elements. On output, it will be filled with
* the number of candidates copied to the
* array.
* @param cand Array of candidates.
*
* @return PJ_SUCCESS, or the appropriate error code.
*/
PJ_DECL(pj_status_t) pj_ice_strans_enum_cands(pj_ice_strans *ice_st,
unsigned comp_id,
unsigned *count,
pj_ice_sess_cand cand[]);
/**
* Get the default candidate for the specified component. When this
* function is called before ICE negotiation completes, the default
* candidate is selected according to local preference criteria. When
* this function is called after ICE negotiation completes, the
* default candidate is the candidate that forms the valid pair.
*
* @param ice_st The ICE stream transport.
* @param comp_id Component ID.
* @param cand Pointer to receive the default candidate
* information.
*/
PJ_DECL(pj_status_t) pj_ice_strans_get_def_cand(pj_ice_strans *ice_st,
unsigned comp_id,
pj_ice_sess_cand *cand);
/**
* Get the current ICE role. ICE session must have been initialized
* before this function can be called.
*
* @param ice_st The ICE stream transport.
*
* @return Current ICE role.
*/
PJ_DECL(pj_ice_sess_role) pj_ice_strans_get_role(pj_ice_strans *ice_st);
/**
* Change session role. This happens for example when ICE session was
* created with controlled role when receiving an offer, but it turns out
* that the offer contains "a=ice-lite" attribute when the SDP gets
* inspected. ICE session must have been initialized before this function
* can be called.
*
* @param ice_st The ICE stream transport.
* @param new_role The new role to be set.
*
* @return PJ_SUCCESS on success, or the appropriate error.
*/
PJ_DECL(pj_status_t) pj_ice_strans_change_role(pj_ice_strans *ice_st,
pj_ice_sess_role new_role);
/**
* Start ICE connectivity checks. This function can only be called
* after the ICE session has been created in the ICE stream transport
* with #pj_ice_strans_init_ice().
*
* This function must be called once application has received remote
* candidate list (typically from the remote SDP). This function pairs
* local candidates with remote candidates, and starts ICE connectivity
* checks. The ICE session/transport will then notify the application
* via the callback when ICE connectivity checks completes, either
* successfully or with failure.
*
* @param ice_st The ICE stream transport.
* @param rem_ufrag Remote ufrag, as seen in the SDP received from
* the remote agent.
* @param rem_passwd Remote password, as seen in the SDP received from
* the remote agent.
* @param rcand_cnt Number of remote candidates in the array.
* @param rcand Remote candidates array.
*
* @return PJ_SUCCESS, or the appropriate error code.
*/
PJ_DECL(pj_status_t) pj_ice_strans_start_ice(pj_ice_strans *ice_st,
const pj_str_t *rem_ufrag,
const pj_str_t *rem_passwd,
unsigned rcand_cnt,
const pj_ice_sess_cand rcand[]);
/**
* Retrieve the candidate pair that has been nominated and successfully
* checked for the specified component. If ICE negotiation is still in
* progress or it has failed, this function will return NULL.
*
* @param ice_st The ICE stream transport.
* @param comp_id Component ID.
*
* @return The valid pair as ICE checklist structure if the
* pair exist.
*/
PJ_DECL(const pj_ice_sess_check*)
pj_ice_strans_get_valid_pair(const pj_ice_strans *ice_st,
unsigned comp_id);
/**
* Stop and destroy the ICE session inside this media transport. Application
* needs to call this function once the media session is over (the call has
* been disconnected).
*
* Application MAY reuse this ICE stream transport for subsequent calls.
* In this case, it must call #pj_ice_strans_stop_ice() when the call is
* disconnected, and reinitialize the ICE stream transport for subsequent
* call with #pj_ice_strans_init_ice()/#pj_ice_strans_start_ice(). In this
* case, the ICE stream transport will maintain the internal sockets and
* continue to send STUN keep-alive packets and TURN Refresh request to
* keep the NAT binding/TURN allocation open and to detect change in STUN
* mapped address.
*
* If application does not want to reuse the ICE stream transport for
* subsequent calls, it must call #pj_ice_strans_destroy() to destroy the
* ICE stream transport altogether.
*
* @param ice_st The ICE stream transport.
*
* @return PJ_SUCCESS, or the appropriate error code.
*/
PJ_DECL(pj_status_t) pj_ice_strans_stop_ice(pj_ice_strans *ice_st);
/**
* Send outgoing packet using this transport.
* Application can send data (normally RTP or RTCP packets) at any time
* by calling this function. This function takes a destination
* address as one of the arguments, and this destination address should
* be taken from the default transport address of the component (that is
* the address in SDP c= and m= lines, or in a=rtcp attribute).
* If ICE negotiation is in progress, this function will send the data
* to the destination address. Otherwise if ICE negotiation has completed
* successfully, this function will send the data to the nominated remote
* address, as negotiated by ICE.
*
* @param ice_st The ICE stream transport.
* @param comp_id Component ID.
* @param data The data or packet to be sent.
* @param data_len Size of data or packet, in bytes.
* @param dst_addr The destination address.
* @param dst_addr_len Length of destination address.
*
* @return PJ_SUCCESS if data is sent successfully.
*/
PJ_DECL(pj_status_t) pj_ice_strans_sendto(pj_ice_strans *ice_st,
unsigned comp_id,
const void *data,
pj_size_t data_len,
const pj_sockaddr_t *dst_addr,
int dst_addr_len);
/**
* @}
*/
PJ_END_DECL
#endif /* __PJNATH_ICE_STRANS_H__ */
|