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 __PJSUA_H__ 21 #define __PJSUA_H__ 22 23 /** 24 * @file pjsua.h 25 * @brief PJSUA API. 26 */ 27 28 29 /* Include all PJSIP core headers. */ 30 #include <pjsip.h> 31 32 /* Include all PJMEDIA headers. */ 33 #include <pjmedia.h> 34 35 /* Include all PJMEDIA-CODEC headers. */ 36 #include <pjmedia-codec.h> 37 38 /* Videodev too */ 39 #include <pjmedia_videodev.h> 40 41 /* Include all PJSIP-UA headers */ 42 #include <pjsip_ua.h> 43 44 /* Include all PJSIP-SIMPLE headers */ 45 #include <pjsip_simple.h> 46 47 /* Include all PJNATH headers */ 48 #include <pjnath.h> 49 50 /* Include all PJLIB-UTIL headers. */ 51 #include <pjlib-util.h> 52 53 /* Include all PJLIB headers. */ 54 #include <pjlib.h> 55 56 57 PJ_BEGIN_DECL 58 59 60 /** 61 * @defgroup PJSUA_LIB PJSUA API - High Level Softphone API 62 * @brief Very high level API for constructing SIP UA applications. 63 * @{ 64 * 65 * @section pjsua_api_intro A SIP User Agent API for C/C++ 66 * 67 * PJSUA API is very high level API for constructing SIP multimedia user agent 68 * applications. It wraps together the signaling and media functionalities 69 * into an easy to use call API, provides account management, buddy 70 * management, presence, instant messaging, along with multimedia 71 * features such as conferencing, file streaming, local playback, 72 * voice recording, and so on. 73 * 74 * @subsection pjsua_for_c_cpp C/C++ Binding 75 * Application must link with <b>pjsua-lib</b> to use this API. In addition, 76 * this library depends on the following libraries: 77 * - <b>pjsip-ua</b>, 78 * - <b>pjsip-simple</b>, 79 * - <b>pjsip-core</b>, 80 * - <b>pjmedia</b>, 81 * - <b>pjmedia-codec</b>, 82 * - <b>pjlib-util</b>, and 83 * - <b>pjlib</b>, 84 * 85 * so application must also link with these libraries as well. For more 86 * information, please refer to 87 * <A HREF="http://www.pjsip.org/using.htm">Getting Started with PJSIP</A> 88 * page. 89 * 90 * @section pjsua_samples 91 * 92 * Few samples are provided: 93 * 94 - @ref page_pjsip_sample_simple_pjsuaua_c\n 95 Very simple SIP User Agent with registration, call, and media, using 96 PJSUA-API, all in under 200 lines of code. 97 98 - @ref page_pjsip_samples_pjsua\n 99 This is the reference implementation for PJSIP and PJMEDIA. 100 PJSUA is a console based application, designed to be simple enough 101 to be readble, but powerful enough to demonstrate all features 102 available in PJSIP and PJMEDIA.\n 103 104 * @section root_using_pjsua_lib Using PJSUA API 105 * 106 * Please refer to @ref PJSUA_LIB_BASE on how to create and initialize the API. 107 * And then see the Modules on the bottom of this page for more information 108 * about specific subject. 109 */ 110 111 112 113 /***************************************************************************** 114 * BASE API 115 */ 116 117 /** 118 * @defgroup PJSUA_LIB_BASE PJSUA-API Basic API 119 * @ingroup PJSUA_LIB 120 * @brief Basic application creation/initialization, logging configuration, etc. 121 * @{ 122 * 123 * The base PJSUA API controls PJSUA creation, initialization, and startup, and 124 * also provides various auxiliary functions. 125 * 126 * @section using_pjsua_lib Using PJSUA Library 127 * 128 * @subsection creating_pjsua_lib Creating PJSUA 129 * 130 * Before anything else, application must create PJSUA by calling 131 * #pjsua_create(). 132 * This, among other things, will initialize PJLIB, which is crucial before 133 * any PJLIB functions can be called, PJLIB-UTIL, and create a SIP endpoint. 134 * 135 * After this function is called, application can create a memory pool (with 136 * #pjsua_pool_create()) and read configurations from command line or file to 137 * build the settings to initialize PJSUA below. 138 * 139 * @subsection init_pjsua_lib Initializing PJSUA 140 * 141 * After PJSUA is created, application can initialize PJSUA by calling 142 * #pjsua_init(). This function takes several optional configuration settings 143 * in the argument, if application wants to set them. 144 * 145 * @subsubsection init_pjsua_lib_c_cpp PJSUA-LIB Initialization (in C) 146 * Sample code to initialize PJSUA in C code: 147 \code 148 149 #include <pjsua-lib/pjsua.h> 150 151 #define THIS_FILE __FILE__ 152 153 static pj_status_t app_init(void) 154 { 155 pjsua_config ua_cfg; 156 pjsua_logging_config log_cfg; 157 pjsua_media_config media_cfg; 158 pj_status_t status; 159 160 // Must create pjsua before anything else! 161 status = pjsua_create(); 162 if (status != PJ_SUCCESS) { 163 pjsua_perror(THIS_FILE, "Error initializing pjsua", status); 164 return status; 165 } 166 167 // Initialize configs with default settings. 168 pjsua_config_default(&ua_cfg); 169 pjsua_logging_config_default(&log_cfg); 170 pjsua_media_config_default(&media_cfg); 171 172 // At the very least, application would want to override 173 // the call callbacks in pjsua_config: 174 ua_cfg.cb.on_incoming_call = ... 175 ua_cfg.cb.on_call_state = .. 176 ... 177 178 // Customize other settings (or initialize them from application specific 179 // configuration file): 180 ... 181 182 // Initialize pjsua 183 status = pjsua_init(&ua_cfg, &log_cfg, &media_cfg); 184 if (status != PJ_SUCCESS) { 185 pjsua_perror(THIS_FILE, "Error initializing pjsua", status); 186 return status; 187 } 188 . 189 ... 190 } 191 \endcode 192 * 193 * 194 195 196 * @subsection other_init_pjsua_lib Other Initialization 197 * 198 * After PJSUA is initialized with #pjsua_init(), application will normally 199 * need/want to perform the following tasks: 200 * 201 * - create SIP transport with #pjsua_transport_create(). Application would 202 * to call #pjsua_transport_create() for each transport types that it 203 * wants to support (for example, UDP, TCP, and TLS). Please see 204 * @ref PJSUA_LIB_TRANSPORT section for more info. 205 * - create one or more SIP accounts with #pjsua_acc_add() or 206 * #pjsua_acc_add_local(). The SIP account is used for registering with 207 * the SIP server, if any. Please see @ref PJSUA_LIB_ACC for more info. 208 * - add one or more buddies with #pjsua_buddy_add(). Please see 209 * @ref PJSUA_LIB_BUDDY section for more info. 210 * - optionally configure the sound device, codec settings, and other 211 * media settings. Please see @ref PJSUA_LIB_MEDIA for more info. 212 * 213 * 214 * @subsection starting_pjsua_lib Starting PJSUA 215 * 216 * After all initializations have been done, application must call 217 * #pjsua_start() to start PJSUA. This function will check that all settings 218 * have been properly configured, and apply default settings when they haven't, 219 * or report error status when it is unable to recover from missing settings. 220 * 221 * Most settings can be changed during run-time. For example, application 222 * may add, modify, or delete accounts, buddies, or change media settings 223 * during run-time. 224 * 225 * @subsubsection starting_pjsua_lib_c C Example for Starting PJSUA 226 * Sample code: 227 \code 228 static pj_status_t app_run(void) 229 { 230 pj_status_t status; 231 232 // Start pjsua 233 status = pjsua_start(); 234 if (status != PJ_SUCCESS) { 235 pjsua_destroy(); 236 pjsua_perror(THIS_FILE, "Error starting pjsua", status); 237 return status; 238 } 239 240 // Run application loop 241 while (1) { 242 char choice[10]; 243 244 printf("Select menu: "); 245 fgets(choice, sizeof(choice), stdin); 246 ... 247 } 248 } 249 \endcode 250 251 */ 252 253 /** Constant to identify invalid ID for all sorts of IDs. */ 254 enum pjsua_invalid_id_const_ 255 { 256 PJSUA_INVALID_ID = -1 257 }; 258 259 /** Disabled features temporarily for media reorganization */ 260 #define DISABLED_FOR_TICKET_1185 0 261 262 /** Call identification */ 263 typedef int pjsua_call_id; 264 265 /** Account identification */ 266 typedef int pjsua_acc_id; 267 268 /** Buddy identification */ 269 typedef int pjsua_buddy_id; 270 271 /** File player identification */ 272 typedef int pjsua_player_id; 273 274 /** File recorder identification */ 275 typedef int pjsua_recorder_id; 276 277 /** Conference port identification */ 278 typedef int pjsua_conf_port_id; 279 280 /** Opaque declaration for server side presence subscription */ 281 typedef struct pjsua_srv_pres pjsua_srv_pres; 282 283 /** Forward declaration for pjsua_msg_data */ 284 typedef struct pjsua_msg_data pjsua_msg_data; 285 286 /** Forward declaration for pj_stun_resolve_result */ 287 typedef struct pj_stun_resolve_result pj_stun_resolve_result; 288 289 /** 290 * Initial memory block for PJSUA. 291 */ 292 #ifndef PJSUA_POOL_LEN 293 # define PJSUA_POOL_LEN 1000 294 #endif 295 296 /** 297 * Memory increment for PJSUA. 298 */ 299 #ifndef PJSUA_POOL_INC 300 # define PJSUA_POOL_INC 1000 301 #endif 302 303 /** 304 * Initial memory block for PJSUA account. 305 */ 306 #ifndef PJSUA_POOL_LEN_ACC 307 # define PJSUA_POOL_LEN_ACC 512 308 #endif 309 310 /** 311 * Memory increment for PJSUA account. 312 */ 313 #ifndef PJSUA_POOL_INC_ACC 314 # define PJSUA_POOL_INC_ACC 256 315 #endif 316 317 /** 318 * Maximum proxies in account. 319 */ 320 #ifndef PJSUA_ACC_MAX_PROXIES 321 # define PJSUA_ACC_MAX_PROXIES 8 322 #endif 323 324 /** 325 * Default value of SRTP mode usage. Valid values are PJMEDIA_SRTP_DISABLED, 326 * PJMEDIA_SRTP_OPTIONAL, and PJMEDIA_SRTP_MANDATORY. 327 */ 328 #ifndef PJSUA_DEFAULT_USE_SRTP 329 #define PJSUA_DEFAULT_USE_SRTP PJMEDIA_SRTP_DISABLED 330 #endif 331 332 /** 333 * Default value of secure signaling requirement for SRTP. 334 * Valid values are: 335 * 0: SRTP does not require secure signaling 336 * 1: SRTP requires secure transport such as TLS 337 * 2: SRTP requires secure end-to-end transport (SIPS) 338 */ 339 #ifndef PJSUA_DEFAULT_SRTP_SECURE_SIGNALING 340 #define PJSUA_DEFAULT_SRTP_SECURE_SIGNALING 1 341 #endif 342 343 /** 344 * Controls whether PJSUA-LIB should add ICE media feature tag 345 * parameter (the ";+sip.ice" parameter) to Contact header if ICE 346 * is enabled in the config. 347 * 348 * Default: 1 349 */ 350 #ifndef PJSUA_ADD_ICE_TAGS 351 # define PJSUA_ADD_ICE_TAGS 1 352 #endif 353 354 /** 355 * Timeout value used to acquire mutex lock on a particular call. 356 * 357 * Default: 2000 ms 358 */ 359 #ifndef PJSUA_ACQUIRE_CALL_TIMEOUT 360 # define PJSUA_ACQUIRE_CALL_TIMEOUT 2000 361 #endif 362 363 /** 364 * Is video enabled. 365 */ 366 #ifndef PJSUA_HAS_VIDEO 367 # define PJSUA_HAS_VIDEO PJMEDIA_HAS_VIDEO 368 #endif 369 370 371 /** 372 * Interval between two keyframe requests, in milliseconds. 373 * 374 * Default: 3000 ms 375 */ 376 #ifndef PJSUA_VID_REQ_KEYFRAME_INTERVAL 377 # define PJSUA_VID_REQ_KEYFRAME_INTERVAL 3000 378 #endif 379 380 381 /** 382 * Specify whether timer heap events will be polled by a separate worker 383 * thread. If this is set/enabled, a worker thread will be dedicated to 384 * poll timer heap events only, and the rest worker thread(s) will poll 385 * ioqueue/network events only. 386 * 387 * Note that if worker thread count setting (i.e: pjsua_config.thread_cnt) 388 * is set to zero, this setting will be ignored. 389 * 390 * Default: 0 (disabled) 391 */ 392 #ifndef PJSUA_SEPARATE_WORKER_FOR_TIMER 393 # define PJSUA_SEPARATE_WORKER_FOR_TIMER 0 394 #endif 395 396 397 /** 398 * Specify whether pjsua should disable automatically sending initial 399 * answer 100/Trying for incoming calls. If disabled, application can 400 * later send 100/Trying if it wishes using pjsua_call_answer(). 401 * 402 * Default: 0 (automatic sending enabled) 403 */ 404 #ifndef PJSUA_DISABLE_AUTO_SEND_100 405 # define PJSUA_DISABLE_AUTO_SEND_100 0 406 #endif 407 408 409 /** 410 * Default options that will be passed when creating ice transport. 411 * See #pjmedia_transport_ice_options. 412 */ 413 #ifndef PJSUA_ICE_TRANSPORT_OPTION 414 # define PJSUA_ICE_TRANSPORT_OPTION 0 415 #endif 416 417 /** 418 * Interval of checking for any new ICE candidate when trickle ICE is active. 419 * Trickle ICE gathers local ICE candidates, such as STUN and TURN candidates, 420 * in the background, while SDP offer/answer negotiation is being performed. 421 * Later, when any new ICE candidate is found, the endpoint will convey 422 * the candidate to the remote endpoint via SIP INFO. 423 * 424 * Default: 100 ms 425 */ 426 #ifndef PJSUA_TRICKLE_ICE_NEW_CAND_CHECK_INTERVAL 427 # define PJSUA_TRICKLE_ICE_NEW_CAND_CHECK_INTERVAL 100 428 #endif 429 430 431 /** 432 * This enumeration represents pjsua state. 433 */ 434 typedef enum pjsua_state 435 { 436 /** 437 * The library has not been initialized. 438 */ 439 PJSUA_STATE_NULL, 440 441 /** 442 * After pjsua_create() is called but before pjsua_init() is called. 443 */ 444 PJSUA_STATE_CREATED, 445 446 /** 447 * After pjsua_init() is called but before pjsua_start() is called. 448 */ 449 PJSUA_STATE_INIT, 450 451 /** 452 * After pjsua_start() is called but before everything is running. 453 */ 454 PJSUA_STATE_STARTING, 455 456 /** 457 * After pjsua_start() is called and before pjsua_destroy() is called. 458 */ 459 PJSUA_STATE_RUNNING, 460 461 /** 462 * After pjsua_destroy() is called but before the function returns. 463 */ 464 PJSUA_STATE_CLOSING 465 466 } pjsua_state; 467 468 469 /** 470 * Logging configuration, which can be (optionally) specified when calling 471 * #pjsua_init(). Application must call #pjsua_logging_config_default() to 472 * initialize this structure with the default values. 473 */ 474 typedef struct pjsua_logging_config 475 { 476 /** 477 * Log incoming and outgoing SIP message? Yes! 478 */ 479 pj_bool_t msg_logging; 480 481 /** 482 * Input verbosity level. Value 5 is reasonable. 483 */ 484 unsigned level; 485 486 /** 487 * Verbosity level for console. Value 4 is reasonable. 488 */ 489 unsigned console_level; 490 491 /** 492 * Log decoration. 493 */ 494 unsigned decor; 495 496 /** 497 * Optional log filename. 498 */ 499 pj_str_t log_filename; 500 501 /** 502 * Additional flags to be given to #pj_file_open() when opening 503 * the log file. By default, the flag is PJ_O_WRONLY. Application 504 * may set PJ_O_APPEND here so that logs are appended to existing 505 * file instead of overwriting it. 506 * 507 * Default is 0. 508 */ 509 unsigned log_file_flags; 510 511 /** 512 * Optional callback function to be called to write log to 513 * application specific device. This function will be called for 514 * log messages on input verbosity level. 515 */ 516 void (*cb)(int level, const char *data, int len); 517 518 519 } pjsua_logging_config; 520 521 522 /** 523 * Use this function to initialize logging config. 524 * 525 * @param cfg The logging config to be initialized. 526 */ 527 PJ_DECL(void) pjsua_logging_config_default(pjsua_logging_config *cfg); 528 529 530 /** 531 * Use this function to duplicate logging config. 532 * 533 * @param pool Pool to use. 534 * @param dst Destination config. 535 * @param src Source config. 536 */ 537 PJ_DECL(void) pjsua_logging_config_dup(pj_pool_t *pool, 538 pjsua_logging_config *dst, 539 const pjsua_logging_config *src); 540 541 542 /** 543 * Structure to be passed on MWI callback. 544 */ 545 typedef struct pjsua_mwi_info 546 { 547 pjsip_evsub *evsub; /**< Event subscription session, for 548 reference. */ 549 pjsip_rx_data *rdata; /**< The received NOTIFY request. */ 550 } pjsua_mwi_info; 551 552 553 /** 554 * Structure to be passed on registration callback. 555 */ 556 typedef struct pjsua_reg_info 557 { 558 struct pjsip_regc_cbparam *cbparam; /**< Parameters returned by 559 registration callback. */ 560 pjsip_regc *regc; /**< Client registration 561 structure. */ 562 pj_bool_t renew; /**< Non-zero for registration and 563 zero for unregistration. */ 564 } pjsua_reg_info; 565 566 567 /** 568 * Media stream info. 569 */ 570 typedef struct pjsua_stream_info 571 { 572 /** Media type of this stream. */ 573 pjmedia_type type; 574 575 /** Stream info (union). */ 576 union { 577 /** Audio stream info */ 578 pjmedia_stream_info aud; 579 580 /** Video stream info */ 581 pjmedia_vid_stream_info vid; 582 } info; 583 584 } pjsua_stream_info; 585 586 587 /** 588 * Media stream statistic. 589 */ 590 typedef struct pjsua_stream_stat 591 { 592 /** RTCP statistic. */ 593 pjmedia_rtcp_stat rtcp; 594 595 /** Jitter buffer statistic. */ 596 pjmedia_jb_state jbuf; 597 598 } pjsua_stream_stat; 599 600 601 /** 602 * Structure to be passed to on stream precreate callback. 603 * See #on_stream_precreate(). 604 */ 605 typedef struct pjsua_on_stream_precreate_param 606 { 607 /** 608 * Stream index in the media session, read-only. 609 */ 610 unsigned stream_idx; 611 612 /** 613 * Parameters that the stream will be created from. 614 */ 615 pjsua_stream_info stream_info; 616 } pjsua_on_stream_precreate_param; 617 618 619 /** 620 * Structure to be passed to on stream created callback. 621 * See #on_stream_created2(). 622 */ 623 typedef struct pjsua_on_stream_created_param 624 { 625 /** 626 * The audio media stream, read-only. 627 */ 628 pjmedia_stream *stream; 629 630 /** 631 * Stream index in the audio media session, read-only. 632 */ 633 unsigned stream_idx; 634 635 /** 636 * Specify if PJSUA should take ownership of the port returned in 637 * the port parameter below. If set to PJ_TRUE, 638 * pjmedia_port_destroy() will be called on the port when it is 639 * no longer needed. 640 * 641 * Default: PJ_FALSE 642 */ 643 pj_bool_t destroy_port; 644 645 /** 646 * On input, it specifies the audio media port of the stream. Application 647 * may modify this pointer to point to different media port to be 648 * registered to the conference bridge. 649 */ 650 pjmedia_port *port; 651 652 } pjsua_on_stream_created_param; 653 654 655 /** 656 * Enumeration of media transport state types. 657 */ 658 typedef enum pjsua_med_tp_st 659 { 660 /** Null, this is the state before media transport is created. */ 661 PJSUA_MED_TP_NULL, 662 663 /** 664 * Just before media transport is created, which can finish 665 * asynchronously later. 666 */ 667 PJSUA_MED_TP_CREATING, 668 669 /** Media transport creation is completed, but not initialized yet. */ 670 PJSUA_MED_TP_IDLE, 671 672 /** Initialized (media_create() has been called). */ 673 PJSUA_MED_TP_INIT, 674 675 /** Running (media_start() has been called). */ 676 PJSUA_MED_TP_RUNNING, 677 678 /** Disabled (transport is initialized, but media is being disabled). */ 679 PJSUA_MED_TP_DISABLED 680 681 } pjsua_med_tp_st; 682 683 684 /** 685 * Structure to be passed on media transport state callback. 686 */ 687 typedef struct pjsua_med_tp_state_info 688 { 689 /** 690 * The media index. 691 */ 692 unsigned med_idx; 693 694 /** 695 * The media transport state 696 */ 697 pjsua_med_tp_st state; 698 699 /** 700 * The last error code related to the media transport state. 701 */ 702 pj_status_t status; 703 704 /** 705 * Optional SIP error code. 706 */ 707 int sip_err_code; 708 709 /** 710 * Optional extended info, the content is specific for each transport type. 711 */ 712 void *ext_info; 713 714 } pjsua_med_tp_state_info; 715 716 717 /** 718 * Type of callback to be called when media transport state is changed. 719 * 720 * @param call_id The call ID. 721 * @param info The media transport state info. 722 * 723 * @return The callback must return PJ_SUCCESS at the moment. 724 */ 725 typedef pj_status_t 726 (*pjsua_med_tp_state_cb)(pjsua_call_id call_id, 727 const pjsua_med_tp_state_info *info); 728 729 730 /** 731 * Typedef of callback to be registered to #pjsua_resolve_stun_servers() 732 * and to be called when STUN resolution completes. 733 */ 734 typedef void (*pj_stun_resolve_cb)(const pj_stun_resolve_result *result); 735 736 737 /** 738 * This enumeration specifies the options for custom media transport creation. 739 */ 740 typedef enum pjsua_create_media_transport_flag 741 { 742 /** 743 * This flag indicates that the media transport must also close its 744 * "member" or "child" transport when pjmedia_transport_close() is 745 * called. If this flag is not specified, then the media transport 746 * must not call pjmedia_transport_close() of its member transport. 747 */ 748 PJSUA_MED_TP_CLOSE_MEMBER = 1 749 750 } pjsua_create_media_transport_flag; 751 752 753 /** 754 * Specify SRTP media transport settings. 755 */ 756 typedef struct pjsua_srtp_opt 757 { 758 /** 759 * Specify the number of crypto suite settings. If set to zero, all 760 * available cryptos will be enabled. Note that available crypto names 761 * can be enumerated using pjmedia_srtp_enum_crypto(). 762 * 763 * Default is zero. 764 */ 765 unsigned crypto_count; 766 767 /** 768 * Specify individual crypto suite setting and its priority order. 769 * 770 * Notes for DTLS-SRTP keying: 771 * - Currently only supports these cryptos: AES_CM_128_HMAC_SHA1_80, 772 * AES_CM_128_HMAC_SHA1_32, AEAD_AES_256_GCM, and AEAD_AES_128_GCM. 773 * - SRTP key is not configurable. 774 */ 775 pjmedia_srtp_crypto crypto[PJMEDIA_SRTP_MAX_CRYPTOS]; 776 777 /** 778 * Specify the number of enabled keying methods. If set to zero, all 779 * keyings will be enabled. Maximum value is PJMEDIA_SRTP_MAX_KEYINGS. 780 * Note that available keying methods can be enumerated using 781 * pjmedia_srtp_enum_keying(). 782 * 783 * Default is zero (all keyings are enabled with priority order: 784 * SDES, DTLS-SRTP). 785 */ 786 unsigned keying_count; 787 788 /** 789 * Specify enabled keying methods and its priority order. Keying method 790 * with higher priority will be given earlier chance to process the SDP, 791 * for example as currently only one keying is supported in the SDP offer, 792 * keying with first priority will be likely used in the SDP offer. 793 */ 794 pjmedia_srtp_keying_method keying[PJMEDIA_SRTP_KEYINGS_COUNT]; 795 796 } pjsua_srtp_opt; 797 798 799 /** 800 * This enumeration specifies the contact rewrite method. 801 */ 802 typedef enum pjsua_contact_rewrite_method 803 { 804 /** 805 * The Contact update will be done by sending unregistration 806 * to the currently registered Contact, while simultaneously sending new 807 * registration (with different Call-ID) for the updated Contact. 808 */ 809 PJSUA_CONTACT_REWRITE_UNREGISTER = 1, 810 811 /** 812 * The Contact update will be done in a single, current 813 * registration session, by removing the current binding (by setting its 814 * Contact's expires parameter to zero) and adding a new Contact binding, 815 * all done in a single request. 816 */ 817 PJSUA_CONTACT_REWRITE_NO_UNREG = 2, 818 819 /** 820 * The Contact update will be done when receiving any registration final 821 * response. If this flag is not specified, contact update will only be 822 * done upon receiving 2xx response. This flag MUST be used with 823 * PJSUA_CONTACT_REWRITE_UNREGISTER or PJSUA_CONTACT_REWRITE_NO_UNREG 824 * above to specify how the Contact update should be performed when 825 * receiving 2xx response. 826 */ 827 PJSUA_CONTACT_REWRITE_ALWAYS_UPDATE = 4 828 829 } pjsua_contact_rewrite_method; 830 831 832 /** 833 * This enumeration specifies the operation when handling IP change. 834 */ 835 typedef enum pjsua_ip_change_op { 836 /** 837 * Hasn't start ip change process. 838 */ 839 PJSUA_IP_CHANGE_OP_NULL, 840 841 /** 842 * The restart listener process. 843 */ 844 PJSUA_IP_CHANGE_OP_RESTART_LIS, 845 846 /** 847 * The shutdown transport process. 848 */ 849 PJSUA_IP_CHANGE_OP_ACC_SHUTDOWN_TP, 850 851 /** 852 * The update contact process. 853 */ 854 PJSUA_IP_CHANGE_OP_ACC_UPDATE_CONTACT, 855 856 /** 857 * The hanging up call process. 858 */ 859 PJSUA_IP_CHANGE_OP_ACC_HANGUP_CALLS, 860 861 /** 862 * The re-INVITE call process. 863 */ 864 PJSUA_IP_CHANGE_OP_ACC_REINVITE_CALLS, 865 866 /** 867 * The ip change process has completed. 868 */ 869 PJSUA_IP_CHANGE_OP_COMPLETED 870 871 } pjsua_ip_change_op; 872 873 874 /** 875 * This will contain the information of the callback \a on_ip_change_progress. 876 */ 877 typedef union pjsua_ip_change_op_info { 878 /** 879 * The information from listener restart operation. 880 */ 881 struct { 882 int transport_id; 883 } lis_restart; 884 885 /** 886 * The information from shutdown transport. 887 */ 888 struct { 889 int acc_id; 890 } acc_shutdown_tp; 891 892 /** 893 * The information from updating contact. 894 */ 895 struct { 896 pjsua_acc_id acc_id; 897 pj_bool_t is_register; /**< SIP Register if PJ_TRUE. */ 898 int code; /**< SIP status code received. */ 899 } acc_update_contact; 900 901 /** 902 * The information from hanging up call operation. 903 */ 904 struct { 905 pjsua_acc_id acc_id; 906 pjsua_call_id call_id; 907 } acc_hangup_calls; 908 909 /** 910 * The information from re-Invite call operation. 911 */ 912 struct { 913 pjsua_acc_id acc_id; 914 pjsua_call_id call_id; 915 } acc_reinvite_calls; 916 } pjsua_ip_change_op_info; 917 918 919 /** 920 * This enumeration specifies DTMF method. 921 */ 922 typedef enum pjsua_dtmf_method { 923 /** 924 * Send DTMF using RFC2833. 925 */ 926 PJSUA_DTMF_METHOD_RFC2833, 927 928 /** 929 * Send DTMF using SIP INFO. 930 * Notes: 931 * - This method is not finalized in any standard/rfc, however it is 932 * commonly used. 933 * - Warning: in case the remote doesn't support SIP INFO, response might 934 * not be sent and the sender will deal this as timeout and disconnect 935 * the call. 936 */ 937 PJSUA_DTMF_METHOD_SIP_INFO 938 939 } pjsua_dtmf_method; 940 941 942 /** 943 * Constant to specify unknown duration in \a pjsua_dtmf_info and 944 * \a pjsua_dtmf_event. 945 */ 946 #define PJSUA_UNKNOWN_DTMF_DURATION ((unsigned)-1) 947 948 949 /** 950 * This will contain the information of the callback \a on_dtmf_digit2. 951 */ 952 typedef struct pjsua_dtmf_info { 953 /** 954 * The method used to send DTMF. 955 */ 956 pjsua_dtmf_method method; 957 958 /** 959 * DTMF ASCII digit. 960 */ 961 unsigned digit; 962 963 /** 964 * DTMF signal duration. If the duration is unknown, this value is set to 965 * PJSUA_UNKNOWN_DTMF_DURATION. 966 */ 967 unsigned duration; 968 969 } pjsua_dtmf_info; 970 971 972 /** 973 * This will contain the information of the callback \a on_dtmf_event. 974 */ 975 typedef struct pjsua_dtmf_event { 976 /** 977 * The method used to send DTMF. 978 */ 979 pjsua_dtmf_method method; 980 981 /** 982 * The timestamp identifying the begin of the event. Timestamp units are 983 * expressed in milliseconds. 984 * Note that this value should only be used to compare multiple events 985 * received via the same method relatively to each other, as the time-base 986 * is randomized. 987 */ 988 unsigned timestamp; 989 990 /** 991 * DTMF ASCII digit. 992 */ 993 unsigned digit; 994 995 /** 996 * DTMF signal duration in milliseconds. Interpretation of the duration 997 * depends on the flag PJMEDIA_STREAM_DTMF_IS_END. 998 * If PJMEDIA_STREAM_DTMF_IS_END is set, this contains the total duration 999 * of the DTMF signal or PJSUA_UNKNOWN_DTMF_DURATION if the duration is 1000 * unknown. 1001 * If PJMEDIA_STREAM_DTMF_IS_END is not set, this contains the duration 1002 * of the DTMF signal received up to this point in time. 1003 * A duration of "0" indicates an infinitely long duration. 1004 */ 1005 unsigned duration; 1006 1007 /** 1008 * Flags indicating additional information about the DTMF event. 1009 * If PJMEDIA_STREAM_DTMF_IS_UPDATE is set, the event was already 1010 * indicated earlier. The new indication contains an updated event 1011 * duration. 1012 * If PJMEDIA_STREAM_DTMF_IS_END is set, the event has ended and this 1013 * indication contains the final event duration. Note that end 1014 * indications might get lost. Hence it is not guaranteed to receive 1015 * an event with PJMEDIA_STREAM_DTMF_IS_END for every event. 1016 */ 1017 unsigned flags; 1018 } pjsua_dtmf_event; 1019 1020 1021 /** 1022 * Call settings. 1023 */ 1024 typedef struct pjsua_call_setting 1025 { 1026 /** 1027 * Bitmask of #pjsua_call_flag constants. 1028 * 1029 * Default: PJSUA_CALL_INCLUDE_DISABLED_MEDIA 1030 */ 1031 unsigned flag; 1032 1033 /** 1034 * This flag controls what methods to request keyframe are allowed on 1035 * the call. Value is bitmask of #pjsua_vid_req_keyframe_method. 1036 * 1037 * Default: (PJSUA_VID_REQ_KEYFRAME_SIP_INFO | 1038 * PJSUA_VID_REQ_KEYFRAME_RTCP_PLI) 1039 */ 1040 unsigned req_keyframe_method; 1041 1042 /** 1043 * Number of simultaneous active audio streams for this call. Setting 1044 * this to zero will disable audio in this call. 1045 * 1046 * Default: 1 1047 */ 1048 unsigned aud_cnt; 1049 1050 /** 1051 * Number of simultaneous active video streams for this call. Setting 1052 * this to zero will disable video in this call. 1053 * 1054 * Default: 1 (if video feature is enabled, otherwise it is zero) 1055 */ 1056 unsigned vid_cnt; 1057 1058 } pjsua_call_setting; 1059 1060 1061 /** 1062 * This structure describes application callback to receive various event 1063 * notification from PJSUA-API. All of these callbacks are OPTIONAL, 1064 * although definitely application would want to implement some of 1065 * the important callbacks (such as \a on_incoming_call). 1066 */ 1067 typedef struct pjsua_callback 1068 { 1069 /** 1070 * Notify application when call state has changed. 1071 * Application may then query the call info to get the 1072 * detail call states by calling pjsua_call_get_info() function. 1073 * 1074 * @param call_id The call index. 1075 * @param e Event which causes the call state to change. 1076 */ 1077 void (*on_call_state)(pjsua_call_id call_id, pjsip_event *e); 1078 1079 /** 1080 * Notify application on incoming call. 1081 * 1082 * @param acc_id The account which match the incoming call. 1083 * @param call_id The call id that has just been created for 1084 * the call. 1085 * @param rdata The incoming INVITE request. 1086 */ 1087 void (*on_incoming_call)(pjsua_acc_id acc_id, pjsua_call_id call_id, 1088 pjsip_rx_data *rdata); 1089 1090 /** 1091 * This is a general notification callback which is called whenever 1092 * a transaction within the call has changed state. Application can 1093 * implement this callback for example to monitor the state of 1094 * outgoing requests, or to answer unhandled incoming requests 1095 * (such as INFO) with a final response. 1096 * 1097 * @param call_id Call identification. 1098 * @param tsx The transaction which has changed state. 1099 * @param e Transaction event that caused the state change. 1100 */ 1101 void (*on_call_tsx_state)(pjsua_call_id call_id, 1102 pjsip_transaction *tsx, 1103 pjsip_event *e); 1104 1105 /** 1106 * Notify application when media state in the call has changed. 1107 * Normal application would need to implement this callback, e.g. 1108 * to connect the call's media to sound device. When ICE is used, 1109 * this callback will also be called to report ICE negotiation 1110 * failure. When DTLS-SRTP is used, this callback will also be called 1111 * to report DTLS negotiation failure. 1112 * 1113 * @param call_id The call index. 1114 */ 1115 void (*on_call_media_state)(pjsua_call_id call_id); 1116 1117 1118 /** 1119 * Notify application when a call has just created a local SDP (for 1120 * initial or subsequent SDP offer/answer). Application can implement 1121 * this callback to modify the SDP, before it is being sent and/or 1122 * negotiated with remote SDP, for example to apply per account/call 1123 * basis codecs priority or to add custom/proprietary SDP attributes. 1124 * 1125 * @param call_id The call index. 1126 * @param sdp The SDP has just been created. 1127 * @param pool The pool instance, application should use this pool 1128 * to modify the SDP. 1129 * @param rem_sdp The remote SDP, will be NULL if local is SDP offerer. 1130 */ 1131 void (*on_call_sdp_created)(pjsua_call_id call_id, 1132 pjmedia_sdp_session *sdp, 1133 pj_pool_t *pool, 1134 const pjmedia_sdp_session *rem_sdp); 1135 1136 /** 1137 * Notify application when an audio media session is about to be created 1138 * (as opposed to #on_stream_created() and #on_stream_created2() which are 1139 * called *after* the session has been created). The application may change 1140 * stream parameters like the jitter buffer size. 1141 * 1142 * @param call_id Call identification. 1143 * @param param The on stream precreate callback parameter. 1144 */ 1145 void (*on_stream_precreate)(pjsua_call_id call_id, 1146 pjsua_on_stream_precreate_param *param); 1147 1148 /** 1149 * Notify application when audio media session is created and before it is 1150 * registered to the conference bridge. Application may return different 1151 * audio media port if it has added media processing port to the stream. 1152 * This media port then will be added to the conference bridge instead. 1153 * 1154 * Note: if implemented, #on_stream_created2() callback will be called 1155 * instead of this one. 1156 * 1157 * @param call_id Call identification. 1158 * @param strm Audio media stream. 1159 * @param stream_idx Stream index in the audio media session. 1160 * @param p_port On input, it specifies the audio media port of the 1161 * stream. Application may modify this pointer to 1162 * point to different media port to be registered 1163 * to the conference bridge. 1164 */ 1165 void (*on_stream_created)(pjsua_call_id call_id, 1166 pjmedia_stream *strm, 1167 unsigned stream_idx, 1168 pjmedia_port **p_port); 1169 1170 /** 1171 * Notify application when audio media session is created and before it is 1172 * registered to the conference bridge. Application may return different 1173 * audio media port if it has added media processing port to the stream. 1174 * This media port then will be added to the conference bridge instead. 1175 * 1176 * @param call_id Call identification. 1177 * @param param The on stream created callback parameter. 1178 */ 1179 void (*on_stream_created2)(pjsua_call_id call_id, 1180 pjsua_on_stream_created_param *param); 1181 1182 /** 1183 * Notify application when audio media session has been unregistered from 1184 * the conference bridge and about to be destroyed. 1185 * 1186 * @param call_id Call identification. 1187 * @param strm Audio media stream. 1188 * @param stream_idx Stream index in the audio media session. 1189 */ 1190 void (*on_stream_destroyed)(pjsua_call_id call_id, 1191 pjmedia_stream *strm, 1192 unsigned stream_idx); 1193 1194 /** 1195 * Notify application upon incoming DTMF digits using RFC 2833 payload 1196 * formats. This callback will not be called if app implements \a 1197 * on_dtmf_digit2() or \a on_dtmf_event(). 1198 * 1199 * @param call_id The call index. 1200 * @param digit DTMF ASCII digit. 1201 */ 1202 void (*on_dtmf_digit)(pjsua_call_id call_id, int digit); 1203 1204 /** 1205 * Notify application upon incoming DTMF digits using the method specified 1206 * in \a pjsua_dtmf_method. This callback will not be called if app 1207 * implements \a on_dtmf_event(). 1208 * 1209 * @param call_id The call index. 1210 * @param info The DTMF info. 1211 */ 1212 void (*on_dtmf_digit2)(pjsua_call_id call_id, const pjsua_dtmf_info *info); 1213 1214 /** 1215 * Notify application upon incoming DTMF digits using the method specified 1216 * in \a pjsua_dtmf_method. Includes additional information about events 1217 * received via RTP. 1218 * 1219 * @param call_id The call index. 1220 * @param event The DTMF event. 1221 */ 1222 void (*on_dtmf_event)(pjsua_call_id call_id, 1223 const pjsua_dtmf_event *event); 1224 1225 /** 1226 * Notify application on call being transferred (i.e. REFER is received). 1227 * Application can decide to accept/reject transfer request 1228 * by setting the code (default is 202). When this callback 1229 * is not defined, the default behavior is to accept the 1230 * transfer. See also on_call_transfer_request2() callback for 1231 * the version with \a pjsua_call_setting in the argument list. 1232 * 1233 * @param call_id The call index. 1234 * @param dst The destination where the call will be 1235 * transferred to. 1236 * @param code Status code to be returned for the call transfer 1237 * request. On input, it contains status code 202. 1238 */ 1239 void (*on_call_transfer_request)(pjsua_call_id call_id, 1240 const pj_str_t *dst, 1241 pjsip_status_code *code); 1242 1243 /** 1244 * Notify application on call being transferred (i.e. REFER is received). 1245 * Application can decide to accept/reject transfer request 1246 * by setting the code (default is 202). When this callback 1247 * is not defined, the default behavior is to accept the 1248 * transfer. 1249 * 1250 * @param call_id The call index. 1251 * @param dst The destination where the call will be 1252 * transferred to. 1253 * @param code Status code to be returned for the call transfer 1254 * request. On input, it contains status code 202. 1255 * @param opt The current call setting, application can update 1256 * this setting for the call being transferred. 1257 */ 1258 void (*on_call_transfer_request2)(pjsua_call_id call_id, 1259 const pj_str_t *dst, 1260 pjsip_status_code *code, 1261 pjsua_call_setting *opt); 1262 1263 /** 1264 * Notify application of the status of previously sent call 1265 * transfer request. Application can monitor the status of the 1266 * call transfer request, for example to decide whether to 1267 * terminate existing call. 1268 * 1269 * @param call_id Call ID. 1270 * @param st_code Status progress of the transfer request. 1271 * @param st_text Status progress text. 1272 * @param final If non-zero, no further notification will 1273 * be reported. The st_code specified in 1274 * this callback is the final status. 1275 * @param p_cont Initially will be set to non-zero, application 1276 * can set this to FALSE if it no longer wants 1277 * to receie further notification (for example, 1278 * after it hangs up the call). 1279 */ 1280 void (*on_call_transfer_status)(pjsua_call_id call_id, 1281 int st_code, 1282 const pj_str_t *st_text, 1283 pj_bool_t final, 1284 pj_bool_t *p_cont); 1285 1286 /** 1287 * Notify application about incoming INVITE with Replaces header. 1288 * Application may reject the request by setting non-2xx code. 1289 * See also on_call_replace_request2() callback for the version 1290 * with \a pjsua_call_setting in the argument list. 1291 * 1292 * @param call_id The call ID to be replaced. 1293 * @param rdata The incoming INVITE request to replace the call. 1294 * @param st_code Status code to be set by application. Application 1295 * should only return a final status (200-699). 1296 * @param st_text Optional status text to be set by application. 1297 */ 1298 void (*on_call_replace_request)(pjsua_call_id call_id, 1299 pjsip_rx_data *rdata, 1300 int *st_code, 1301 pj_str_t *st_text); 1302 1303 /** 1304 * Notify application about incoming INVITE with Replaces header. 1305 * Application may reject the request by setting non-2xx code. 1306 * 1307 * @param call_id The call ID to be replaced. 1308 * @param rdata The incoming INVITE request to replace the call. 1309 * @param st_code Status code to be set by application. Application 1310 * should only return a final status (200-699). 1311 * @param st_text Optional status text to be set by application. 1312 * @param opt The current call setting, application can update 1313 * this setting for the call being replaced. 1314 */ 1315 void (*on_call_replace_request2)(pjsua_call_id call_id, 1316 pjsip_rx_data *rdata, 1317 int *st_code, 1318 pj_str_t *st_text, 1319 pjsua_call_setting *opt); 1320 1321 /** 1322 * Notify application that an existing call has been replaced with 1323 * a new call. This happens when PJSUA-API receives incoming INVITE 1324 * request with Replaces header. 1325 * 1326 * After this callback is called, normally PJSUA-API will disconnect 1327 * \a old_call_id and establish \a new_call_id. 1328 * 1329 * @param old_call_id Existing call which to be replaced with the 1330 * new call. 1331 * @param new_call_id The new call. 1332 * @param rdata The incoming INVITE with Replaces request. 1333 */ 1334 void (*on_call_replaced)(pjsua_call_id old_call_id, 1335 pjsua_call_id new_call_id); 1336 1337 1338 /** 1339 * Notify application when call has received new offer from remote 1340 * (i.e. re-INVITE/UPDATE with SDP is received, or from the 1341 * INVITE response in the case that the initial outgoing INVITE 1342 * has no SDP). Application can 1343 * decide to accept/reject the offer by setting the code (default 1344 * is 200). If the offer is accepted, application can update the 1345 * call setting to be applied in the answer. When this callback is 1346 * not defined, the default behavior is to accept the offer using 1347 * current call setting. 1348 * 1349 * Note: this callback may not be called if \a on_call_rx_reinvite() 1350 * is implemented. 1351 * 1352 * @param call_id The call index. 1353 * @param offer The new offer received. 1354 * @param reserved Reserved param, currently not used. 1355 * @param code Status code to be returned for answering the 1356 * offer. On input, it contains status code 200. 1357 * Currently, valid values are only 200 and 488. 1358 * @param opt The current call setting, application can update 1359 * this setting for answering the offer. 1360 */ 1361 void (*on_call_rx_offer)(pjsua_call_id call_id, 1362 const pjmedia_sdp_session *offer, 1363 void *reserved, 1364 pjsip_status_code *code, 1365 pjsua_call_setting *opt); 1366 1367 1368 /** 1369 * Notify application when call has received a re-INVITE with offer 1370 * from the peer. It allows more fine-grained control over the response 1371 * to a re-INVITE. If application sets async to PJ_TRUE, it can send 1372 * the reply manually using the function #pjsua_call_answer_with_sdp(). 1373 * Otherwise, by default the re-INVITE will be answered automatically 1374 * after the callback returns. 1375 * 1376 * Currently, this callback is only called for re-INVITE with 1377 * SDP, but app should be prepared to handle the case of re-INVITE 1378 * without SDP. 1379 * 1380 * Remarks: If manually answering at a later timing, application may 1381 * need to monitor on_call_tsx_state() callback to check whether 1382 * the re-INVITE is already answered automatically with 487 due to 1383 * being cancelled. 1384 * 1385 * Note: on_call_rx_offer() will still be called after this callback, 1386 * but only if async is PJ_FALSE and code is 200. 1387 * 1388 * @param call_id The call index. 1389 * @param offer Remote offer. 1390 * @param rdata The received re-INVITE request. 1391 * @param reserved Reserved param, currently not used. 1392 * @param async On input, it is PJ_FALSE. Set to PJ_TRUE if 1393 * app wants to manually answer the re-INVITE. 1394 * @param code Status code to be returned for answering the 1395 * offer. On input, it contains status code 200. 1396 * Currently, valid values are only 200 and 488. 1397 * @param opt The current call setting, application can update 1398 * this setting for answering the offer. 1399 */ 1400 void (*on_call_rx_reinvite)(pjsua_call_id call_id, 1401 const pjmedia_sdp_session *offer, 1402 pjsip_rx_data *rdata, 1403 void *reserved, 1404 pj_bool_t *async, 1405 pjsip_status_code *code, 1406 pjsua_call_setting *opt); 1407 1408 1409 /** 1410 * Notify application when call has received INVITE with no SDP offer. 1411 * Application can update the call setting (e.g: add audio/video), or 1412 * enable/disable codecs, or update other media session settings from 1413 * within the callback, however, as mandated by the standard (RFC3261 1414 * section 14.2), it must ensure that the update overlaps with the 1415 * existing media session (in codecs, transports, or other parameters) 1416 * that require support from the peer, this is to avoid the need for 1417 * the peer to reject the offer. 1418 * 1419 * When this callback is not defined, the default behavior is to send 1420 * SDP offer using current active media session (with all enabled codecs 1421 * on each media type). 1422 * 1423 * @param call_id The call index. 1424 * @param reserved Reserved param, currently not used. 1425 * @param opt The current call setting, application can update 1426 * this setting for generating the offer. 1427 */ 1428 void (*on_call_tx_offer)(pjsua_call_id call_id, 1429 void *reserved, 1430 pjsua_call_setting *opt); 1431 1432 1433 /** 1434 * Notify application when registration or unregistration has been 1435 * initiated. Note that this only notifies the initial registration 1436 * and unregistration. Once registration session is active, subsequent 1437 * refresh will not cause this callback to be called. 1438 * 1439 * @param acc_id The account ID. 1440 * @param renew Non-zero for registration and zero for 1441 * unregistration. 1442 */ 1443 void (*on_reg_started)(pjsua_acc_id acc_id, pj_bool_t renew); 1444 1445 /** 1446 * This is the alternative version of the \a on_reg_started() callback with 1447 * \a pjsua_reg_info argument. 1448 * 1449 * @param acc_id The account ID. 1450 * @param info The registration info. 1451 */ 1452 void (*on_reg_started2)(pjsua_acc_id acc_id, 1453 pjsua_reg_info *info); 1454 1455 /** 1456 * Notify application when registration status has changed. 1457 * Application may then query the account info to get the 1458 * registration details. 1459 * 1460 * @param acc_id The account ID. 1461 */ 1462 void (*on_reg_state)(pjsua_acc_id acc_id); 1463 1464 /** 1465 * Notify application when registration status has changed. 1466 * Application may inspect the registration info to get the 1467 * registration status details. 1468 * 1469 * @param acc_id The account ID. 1470 * @param info The registration info. 1471 */ 1472 void (*on_reg_state2)(pjsua_acc_id acc_id, pjsua_reg_info *info); 1473 1474 /** 1475 * Notification when incoming SUBSCRIBE request is received. Application 1476 * may use this callback to authorize the incoming subscribe request 1477 * (e.g. ask user permission if the request should be granted). 1478 * 1479 * If this callback is not implemented, all incoming presence subscription 1480 * requests will be accepted. 1481 * 1482 * If this callback is implemented, application has several choices on 1483 * what to do with the incoming request: 1484 * - it may reject the request immediately by specifying non-200 class 1485 * final response in the \a code argument. 1486 * - it may immediately accept the request by specifying 200 as the 1487 * \a code argument. This is the default value if application doesn't 1488 * set any value to the \a code argument. In this case, the library 1489 * will automatically send NOTIFY request upon returning from this 1490 * callback. 1491 * - it may delay the processing of the request, for example to request 1492 * user permission whether to accept or reject the request. In this 1493 * case, the application MUST set the \a code argument to 202, then 1494 * IMMEDIATELY calls #pjsua_pres_notify() with state 1495 * PJSIP_EVSUB_STATE_PENDING and later calls #pjsua_pres_notify() 1496 * again to accept or reject the subscription request. 1497 * 1498 * Any \a code other than 200 and 202 will be treated as 200. 1499 * 1500 * Application MUST return from this callback immediately (e.g. it must 1501 * not block in this callback while waiting for user confirmation). 1502 * 1503 * @param srv_pres Server presence subscription instance. If 1504 * application delays the acceptance of the request, 1505 * it will need to specify this object when calling 1506 * #pjsua_pres_notify(). 1507 * @param acc_id Account ID most appropriate for this request. 1508 * @param buddy_id ID of the buddy matching the sender of the 1509 * request, if any, or PJSUA_INVALID_ID if no 1510 * matching buddy is found. 1511 * @param from The From URI of the request. 1512 * @param rdata The incoming request. 1513 * @param code The status code to respond to the request. The 1514 * default value is 200. Application may set this 1515 * to other final status code to accept or reject 1516 * the request. 1517 * @param reason The reason phrase to respond to the request. 1518 * @param msg_data If the application wants to send additional 1519 * headers in the response, it can put it in this 1520 * parameter. 1521 */ 1522 void (*on_incoming_subscribe)(pjsua_acc_id acc_id, 1523 pjsua_srv_pres *srv_pres, 1524 pjsua_buddy_id buddy_id, 1525 const pj_str_t *from, 1526 pjsip_rx_data *rdata, 1527 pjsip_status_code *code, 1528 pj_str_t *reason, 1529 pjsua_msg_data *msg_data); 1530 1531 /** 1532 * Notification when server side subscription state has changed. 1533 * This callback is optional as application normally does not need 1534 * to do anything to maintain server side presence subscription. 1535 * 1536 * @param acc_id The account ID. 1537 * @param srv_pres Server presence subscription object. 1538 * @param remote_uri Remote URI string. 1539 * @param state New subscription state. 1540 * @param event PJSIP event that triggers the state change. 1541 */ 1542 void (*on_srv_subscribe_state)(pjsua_acc_id acc_id, 1543 pjsua_srv_pres *srv_pres, 1544 const pj_str_t *remote_uri, 1545 pjsip_evsub_state state, 1546 pjsip_event *event); 1547 1548 /** 1549 * Notify application when the buddy state has changed. 1550 * Application may then query the buddy into to get the details. 1551 * 1552 * @param buddy_id The buddy id. 1553 */ 1554 void (*on_buddy_state)(pjsua_buddy_id buddy_id); 1555 1556 1557 /** 1558 * Notify application when the state of client subscription session 1559 * associated with a buddy has changed. Application may use this 1560 * callback to retrieve more detailed information about the state 1561 * changed event. 1562 * 1563 * @param buddy_id The buddy id. 1564 * @param sub Event subscription session. 1565 * @param event The event which triggers state change event. 1566 */ 1567 void (*on_buddy_evsub_state)(pjsua_buddy_id buddy_id, 1568 pjsip_evsub *sub, 1569 pjsip_event *event); 1570 1571 /** 1572 * Notify application on incoming pager (i.e. MESSAGE request). 1573 * Argument call_id will be -1 if MESSAGE request is not related to an 1574 * existing call. 1575 * 1576 * See also \a on_pager2() callback for the version with \a pjsip_rx_data 1577 * passed as one of the argument. 1578 * 1579 * @param call_id Containts the ID of the call where the IM was 1580 * sent, or PJSUA_INVALID_ID if the IM was sent 1581 * outside call context. 1582 * @param from URI of the sender. 1583 * @param to URI of the destination message. 1584 * @param contact The Contact URI of the sender, if present. 1585 * @param mime_type MIME type of the message. 1586 * @param body The message content. 1587 */ 1588 void (*on_pager)(pjsua_call_id call_id, const pj_str_t *from, 1589 const pj_str_t *to, const pj_str_t *contact, 1590 const pj_str_t *mime_type, const pj_str_t *body); 1591 1592 /** 1593 * This is the alternative version of the \a on_pager() callback with 1594 * \a pjsip_rx_data argument. 1595 * 1596 * @param call_id Containts the ID of the call where the IM was 1597 * sent, or PJSUA_INVALID_ID if the IM was sent 1598 * outside call context. 1599 * @param from URI of the sender. 1600 * @param to URI of the destination message. 1601 * @param contact The Contact URI of the sender, if present. 1602 * @param mime_type MIME type of the message. 1603 * @param body The message content. 1604 * @param rdata The incoming MESSAGE request. 1605 * @param acc_id Account ID most suitable for this message. 1606 */ 1607 void (*on_pager2)(pjsua_call_id call_id, const pj_str_t *from, 1608 const pj_str_t *to, const pj_str_t *contact, 1609 const pj_str_t *mime_type, const pj_str_t *body, 1610 pjsip_rx_data *rdata, pjsua_acc_id acc_id); 1611 1612 /** 1613 * Notify application about the delivery status of outgoing pager 1614 * request. See also on_pager_status2() callback for the version with 1615 * \a pjsip_rx_data in the argument list. 1616 * 1617 * @param call_id Containts the ID of the call where the IM was 1618 * sent, or PJSUA_INVALID_ID if the IM was sent 1619 * outside call context. 1620 * @param to Destination URI. 1621 * @param body Message body. 1622 * @param user_data Arbitrary data that was specified when sending 1623 * IM message. 1624 * @param status Delivery status. 1625 * @param reason Delivery status reason. 1626 */ 1627 void (*on_pager_status)(pjsua_call_id call_id, 1628 const pj_str_t *to, 1629 const pj_str_t *body, 1630 void *user_data, 1631 pjsip_status_code status, 1632 const pj_str_t *reason); 1633 1634 /** 1635 * Notify application about the delivery status of outgoing pager 1636 * request. 1637 * 1638 * @param call_id Containts the ID of the call where the IM was 1639 * sent, or PJSUA_INVALID_ID if the IM was sent 1640 * outside call context. 1641 * @param to Destination URI. 1642 * @param body Message body. 1643 * @param user_data Arbitrary data that was specified when sending 1644 * IM message. 1645 * @param status Delivery status. 1646 * @param reason Delivery status reason. 1647 * @param tdata The original MESSAGE request. 1648 * @param rdata The incoming MESSAGE response, or NULL if the 1649 * message transaction fails because of time out 1650 * or transport error. 1651 * @param acc_id Account ID from this the instant message was 1652 * send. 1653 */ 1654 void (*on_pager_status2)(pjsua_call_id call_id, 1655 const pj_str_t *to, 1656 const pj_str_t *body, 1657 void *user_data, 1658 pjsip_status_code status, 1659 const pj_str_t *reason, 1660 pjsip_tx_data *tdata, 1661 pjsip_rx_data *rdata, 1662 pjsua_acc_id acc_id); 1663 1664 /** 1665 * Notify application about typing indication. 1666 * 1667 * @param call_id Containts the ID of the call where the IM was 1668 * sent, or PJSUA_INVALID_ID if the IM was sent 1669 * outside call context. 1670 * @param from URI of the sender. 1671 * @param to URI of the destination message. 1672 * @param contact The Contact URI of the sender, if present. 1673 * @param is_typing Non-zero if peer is typing, or zero if peer 1674 * has stopped typing a message. 1675 */ 1676 void (*on_typing)(pjsua_call_id call_id, const pj_str_t *from, 1677 const pj_str_t *to, const pj_str_t *contact, 1678 pj_bool_t is_typing); 1679 1680 /** 1681 * Notify application about typing indication. 1682 * 1683 * @param call_id Containts the ID of the call where the IM was 1684 * sent, or PJSUA_INVALID_ID if the IM was sent 1685 * outside call context. 1686 * @param from URI of the sender. 1687 * @param to URI of the destination message. 1688 * @param contact The Contact URI of the sender, if present. 1689 * @param is_typing Non-zero if peer is typing, or zero if peer 1690 * has stopped typing a message. 1691 * @param rdata The received request. 1692 * @param acc_id Account ID most suitable for this message. 1693 */ 1694 void (*on_typing2)(pjsua_call_id call_id, const pj_str_t *from, 1695 const pj_str_t *to, const pj_str_t *contact, 1696 pj_bool_t is_typing, pjsip_rx_data *rdata, 1697 pjsua_acc_id acc_id); 1698 1699 /** 1700 * Callback when the library has finished performing NAT type 1701 * detection. 1702 * 1703 * @param res NAT detection result. 1704 */ 1705 void (*on_nat_detect)(const pj_stun_nat_detect_result *res); 1706 1707 /** 1708 * This callback is called when the call is about to resend the 1709 * INVITE request to the specified target, following the previously 1710 * received redirection response. 1711 * 1712 * Application may accept the redirection to the specified target, 1713 * reject this target only and make the session continue to try the next 1714 * target in the list if such target exists, stop the whole 1715 * redirection process altogether and cause the session to be 1716 * disconnected, or defer the decision to ask for user confirmation. 1717 * 1718 * This callback is optional. If this callback is not implemented, 1719 * the default behavior is to NOT follow the redirection response. 1720 * 1721 * @param call_id The call ID. 1722 * @param target The current target to be tried. 1723 * @param e The event that caused this callback to be called. 1724 * This could be the receipt of 3xx response, or 1725 * 4xx/5xx response received for the INVITE sent to 1726 * subsequent targets, or NULL if this callback is 1727 * called from within #pjsua_call_process_redirect() 1728 * context. 1729 * 1730 * @return Action to be performed for the target. Set this 1731 * parameter to one of the value below: 1732 * - PJSIP_REDIRECT_ACCEPT: immediately accept the 1733 * redirection. When set, the call will immediately 1734 * resend INVITE request to the target. 1735 * - PJSIP_REDIRECT_ACCEPT_REPLACE: immediately accept 1736 * the redirection and replace the To header with the 1737 * current target. When set, the call will immediately 1738 * resend INVITE request to the target. 1739 * - PJSIP_REDIRECT_REJECT: immediately reject this 1740 * target. The call will continue retrying with 1741 * next target if present, or disconnect the call 1742 * if there is no more target to try. 1743 * - PJSIP_REDIRECT_STOP: stop the whole redirection 1744 * process and immediately disconnect the call. The 1745 * on_call_state() callback will be called with 1746 * PJSIP_INV_STATE_DISCONNECTED state immediately 1747 * after this callback returns. 1748 * - PJSIP_REDIRECT_PENDING: set to this value if 1749 * no decision can be made immediately (for example 1750 * to request confirmation from user). Application 1751 * then MUST call #pjsua_call_process_redirect() 1752 * to either accept or reject the redirection upon 1753 * getting user decision. 1754 */ 1755 pjsip_redirect_op (*on_call_redirected)(pjsua_call_id call_id, 1756 const pjsip_uri *target, 1757 const pjsip_event *e); 1758 1759 /** 1760 * This callback is called when message waiting indication subscription 1761 * state has changed. Application can then query the subscription state 1762 * by calling #pjsip_evsub_get_state(). 1763 * 1764 * @param acc_id The account ID. 1765 * @param evsub The subscription instance. 1766 */ 1767 void (*on_mwi_state)(pjsua_acc_id acc_id, pjsip_evsub *evsub); 1768 1769 /** 1770 * This callback is called when a NOTIFY request for message summary / 1771 * message waiting indication is received. 1772 * 1773 * @param acc_id The account ID. 1774 * @param mwi_info Structure containing details of the event, 1775 * including the received NOTIFY request in the 1776 * \a rdata field. 1777 */ 1778 void (*on_mwi_info)(pjsua_acc_id acc_id, pjsua_mwi_info *mwi_info); 1779 1780 /** 1781 * This callback is called when transport state is changed. See also 1782 * #pjsip_tp_state_callback. 1783 */ 1784 pjsip_tp_state_callback on_transport_state; 1785 1786 /** 1787 * This callback is called when media transport state is changed. See 1788 * also #pjsua_med_tp_state_cb. 1789 */ 1790 pjsua_med_tp_state_cb on_call_media_transport_state; 1791 1792 /** 1793 * This callback is called to report error in ICE media transport. 1794 * Currently it is used to report TURN Refresh error. 1795 * 1796 * @param index Transport index. 1797 * @param op Operation which trigger the failure. 1798 * @param status Error status. 1799 * @param param Additional info about the event. Currently this will 1800 * always be set to NULL. 1801 */ 1802 void (*on_ice_transport_error)(int index, pj_ice_strans_op op, 1803 pj_status_t status, void *param); 1804 1805 /** 1806 * Callback when the sound device is about to be opened or closed. 1807 * This callback will be called even when null sound device or no 1808 * sound device is configured by the application (i.e. the 1809 * #pjsua_set_null_snd_dev() and #pjsua_set_no_snd_dev() APIs). 1810 * Application can use the API #pjsua_get_snd_dev() to get the info 1811 * about which sound device is going to be opened/closed. 1812 * 1813 * This callback is mostly useful when the application wants to manage 1814 * the sound device by itself (i.e. with #pjsua_set_no_snd_dev()), 1815 * to get notified when it should open or close the sound device. 1816 * 1817 * @param operation The value will be set to 0 to signal that sound 1818 * device is about to be closed, and 1 to be opened. 1819 * 1820 * @return The callback must return PJ_SUCCESS at the moment. 1821 */ 1822 pj_status_t (*on_snd_dev_operation)(int operation); 1823 1824 /** 1825 * Notification about media events such as video notifications. This 1826 * callback will most likely be called from media threads, thus 1827 * application must not perform heavy processing in this callback. 1828 * Especially, application must not destroy the call or media in this 1829 * callback. If application needs to perform more complex tasks to 1830 * handle the event, it should post the task to another thread. 1831 * 1832 * @param call_id The call id. 1833 * @param med_idx The media stream index. 1834 * @param event The media event. 1835 */ 1836 void (*on_call_media_event)(pjsua_call_id call_id, 1837 unsigned med_idx, 1838 pjmedia_event *event); 1839 1840 /** 1841 * This callback can be used by application to implement custom media 1842 * transport adapter for the call, or to replace the media transport 1843 * with something completely new altogether. 1844 * 1845 * This callback is called when a new call is created. The library has 1846 * created a media transport for the call, and it is provided as the 1847 * \a base_tp argument of this callback. Upon returning, the callback 1848 * must return an instance of media transport to be used by the call. 1849 * 1850 * @param call_id Call ID 1851 * @param media_idx The media index in the SDP for which this media 1852 * transport will be used. 1853 * @param base_tp The media transport which otherwise will be 1854 * used by the call has this callback not been 1855 * implemented. 1856 * @param flags Bitmask from pjsua_create_media_transport_flag. 1857 * 1858 * @return The callback must return an instance of media 1859 * transport to be used by the call. 1860 */ 1861 pjmedia_transport* (*on_create_media_transport)(pjsua_call_id call_id, 1862 unsigned media_idx, 1863 pjmedia_transport *base_tp, 1864 unsigned flags); 1865 1866 /** 1867 * Warning: deprecated and may be removed in future release. Application 1868 * can set SRTP crypto settings (including keys) and keying methods 1869 * via pjsua_srtp_opt in pjsua_config and pjsua_acc_config. 1870 * See also ticket #2100. 1871 * 1872 * This callback is called before SRTP media transport is created. 1873 * Application can modify the SRTP setting \a srtp_opt to specify 1874 * the cryptos & keys and keying methods which are going to be used. 1875 * Note that only some fields of pjmedia_srtp_setting can be overriden 1876 * from this callback, i.e: "crypto_count", "crypto", "keying_count", 1877 * "keying", and "use" (only for initial INVITE), any modification in 1878 * other fields will be ignored. 1879 * 1880 * @param call_id Call ID 1881 * @param media_idx The media index in the SDP for which this SRTP 1882 * media transport will be used. 1883 * @param srtp_opt The SRTP setting. Application can modify this. 1884 */ 1885 void (*on_create_media_transport_srtp)(pjsua_call_id call_id, 1886 unsigned media_idx, 1887 pjmedia_srtp_setting *srtp_opt); 1888 1889 /** 1890 * This callback can be used by application to override the account 1891 * to be used to handle an incoming message. Initially, the account to 1892 * be used will be calculated automatically by the library. This initial 1893 * account will be used if application does not implement this callback, 1894 * or application sets an invalid account upon returning from this 1895 * callback. 1896 * 1897 * Note that currently the incoming messages requiring account assignment 1898 * are INVITE, MESSAGE, SUBSCRIBE, and unsolicited NOTIFY. This callback 1899 * may be called before the callback of the SIP event itself, i.e: 1900 * incoming call, pager, subscription, or unsolicited-event. 1901 * 1902 * @param rdata The incoming message. 1903 * @param acc_id On input, initial account ID calculated automatically 1904 * by the library. On output, the account ID prefered 1905 * by application to handle the incoming message. 1906 */ 1907 void (*on_acc_find_for_incoming)(const pjsip_rx_data *rdata, 1908 pjsua_acc_id* acc_id); 1909 1910 /** 1911 * Calling #pjsua_init() will initiate an async process to resolve and 1912 * contact each of the STUN server entries to find which is usable. 1913 * This callback is called when the process is complete, and can be 1914 * used by the application to start creating and registering accounts. 1915 * This way, the accounts can avoid call setup delay caused by pending 1916 * STUN resolution. 1917 * 1918 * See also #pj_stun_resolve_cb. 1919 */ 1920 pj_stun_resolve_cb on_stun_resolution_complete; 1921 1922 /** 1923 * Calling #pjsua_handle_ip_change() may involve different operation. This 1924 * callback is called to report the progress of each enabled operation. 1925 * 1926 * @param op The operation. 1927 * @param status The status of operation. 1928 * @param info The info from the operation 1929 * 1930 */ 1931 void (*on_ip_change_progress)(pjsua_ip_change_op op, 1932 pj_status_t status, 1933 const pjsua_ip_change_op_info *info); 1934 1935 /** 1936 * Notification about media events such as video notifications. This 1937 * callback will most likely be called from media threads, thus 1938 * application must not perform heavy processing in this callback. 1939 * If application needs to perform more complex tasks to handle 1940 * the event, it should post the task to another thread. 1941 * 1942 * @param event The media event. 1943 */ 1944 void (*on_media_event)(pjmedia_event *event); 1945 1946 } pjsua_callback; 1947 1948 1949 /** 1950 * This enumeration specifies the usage of SIP Session Timers extension. 1951 */ 1952 typedef enum pjsua_sip_timer_use 1953 { 1954 /** 1955 * When this flag is specified, Session Timers will not be used in any 1956 * session, except it is explicitly required in the remote request. 1957 */ 1958 PJSUA_SIP_TIMER_INACTIVE, 1959 1960 /** 1961 * When this flag is specified, Session Timers will be used in all 1962 * sessions whenever remote supports and uses it. 1963 */ 1964 PJSUA_SIP_TIMER_OPTIONAL, 1965 1966 /** 1967 * When this flag is specified, Session Timers support will be 1968 * a requirement for the remote to be able to establish a session. 1969 */ 1970 PJSUA_SIP_TIMER_REQUIRED, 1971 1972 /** 1973 * When this flag is specified, Session Timers will always be used 1974 * in all sessions, regardless whether remote supports/uses it or not. 1975 */ 1976 PJSUA_SIP_TIMER_ALWAYS 1977 1978 } pjsua_sip_timer_use; 1979 1980 1981 /** 1982 * This constants controls the use of 100rel extension. 1983 */ 1984 typedef enum pjsua_100rel_use 1985 { 1986 /** 1987 * Not used. For UAC, support for 100rel will be indicated in Supported 1988 * header so that peer can opt to use it if it wants to. As UAS, this 1989 * option will NOT cause 100rel to be used even if UAC indicates that 1990 * it supports this feature. 1991 */ 1992 PJSUA_100REL_NOT_USED, 1993 1994 /** 1995 * Mandatory. UAC will place 100rel in Require header, and UAS will 1996 * reject incoming calls unless it has 100rel in Supported header. 1997 */ 1998 PJSUA_100REL_MANDATORY, 1999 2000 /** 2001 * Optional. Similar to PJSUA_100REL_NOT_USED, except that as UAS, this 2002 * option will cause 100rel to be used if UAC indicates that it supports it. 2003 */ 2004 PJSUA_100REL_OPTIONAL 2005 2006 } pjsua_100rel_use; 2007 2008 2009 /** 2010 * This structure describes the settings to control the API and 2011 * user agent behavior, and can be specified when calling #pjsua_init(). 2012 * Before setting the values, application must call #pjsua_config_default() 2013 * to initialize this structure with the default values. 2014 */ 2015 typedef struct pjsua_config 2016 { 2017 2018 /** 2019 * Maximum calls to support (default: 4). The value specified here 2020 * must be smaller than or equal to the compile time maximum settings 2021 * PJSUA_MAX_CALLS. To increase this limit, the library must be 2022 * recompiled with new PJSUA_MAX_CALLS value. 2023 */ 2024 unsigned max_calls; 2025 2026 /** 2027 * Number of worker threads. Normally application will want to have at 2028 * least one worker thread, unless when it wants to poll the library 2029 * periodically, which in this case the worker thread can be set to 2030 * zero. 2031 */ 2032 unsigned thread_cnt; 2033 2034 /** 2035 * Number of nameservers. If no name server is configured, the SIP SRV 2036 * resolution would be disabled, and domain will be resolved with 2037 * standard pj_gethostbyname() function. 2038 */ 2039 unsigned nameserver_count; 2040 2041 /** 2042 * Array of nameservers to be used by the SIP resolver subsystem. 2043 * The order of the name server specifies the priority (first name 2044 * server will be used first, unless it is not reachable). 2045 */ 2046 pj_str_t nameserver[4]; 2047 2048 /** 2049 * Force loose-route to be used in all route/proxy URIs (outbound_proxy 2050 * and account's proxy settings). When this setting is enabled, the 2051 * library will check all the route/proxy URIs specified in the settings 2052 * and append ";lr" parameter to the URI if the parameter is not present. 2053 * 2054 * Default: 1 2055 */ 2056 pj_bool_t force_lr; 2057 2058 /** 2059 * Number of outbound proxies in the \a outbound_proxy array. 2060 */ 2061 unsigned outbound_proxy_cnt; 2062 2063 /** 2064 * Specify the URL of outbound proxies to visit for all outgoing requests. 2065 * The outbound proxies will be used for all accounts, and it will 2066 * be used to build the route set for outgoing requests. The final 2067 * route set for outgoing requests will consists of the outbound proxies 2068 * and the proxy configured in the account. 2069 */ 2070 pj_str_t outbound_proxy[4]; 2071 2072 /** 2073 * Warning: deprecated, please use \a stun_srv field instead. To maintain 2074 * backward compatibility, if \a stun_srv_cnt is zero then the value of 2075 * this field will be copied to \a stun_srv field, if present. 2076 * 2077 * Specify domain name to be resolved with DNS SRV resolution to get the 2078 * address of the STUN server. Alternatively application may specify 2079 * \a stun_host instead. 2080 * 2081 * If DNS SRV resolution failed for this domain, then DNS A resolution 2082 * will be performed only if \a stun_host is specified. 2083 */ 2084 pj_str_t stun_domain; 2085 2086 /** 2087 * Warning: deprecated, please use \a stun_srv field instead. To maintain 2088 * backward compatibility, if \a stun_srv_cnt is zero then the value of 2089 * this field will be copied to \a stun_srv field, if present. 2090 * 2091 * Specify STUN server to be used, in "HOST[:PORT]" format. If port is 2092 * not specified, default port 3478 will be used. 2093 */ 2094 pj_str_t stun_host; 2095 2096 /** 2097 * Number of STUN server entries in \a stun_srv array. 2098 */ 2099 unsigned stun_srv_cnt; 2100 2101 /** 2102 * Array of STUN servers to try. The library will try to resolve and 2103 * contact each of the STUN server entry until it finds one that is 2104 * usable. Each entry may be a domain name, host name, IP address, and 2105 * it may contain an optional port number. For example: 2106 * - "pjsip.org" (domain name) 2107 * - "sip.pjsip.org" (host name) 2108 * - "pjsip.org:33478" (domain name and a non-standard port number) 2109 * - "10.0.0.1:3478" (IP address and port number) 2110 * 2111 * When nameserver is configured in the \a pjsua_config.nameserver field, 2112 * if entry is not an IP address, it will be resolved with DNS SRV 2113 * resolution first, and it will fallback to use DNS A resolution if this 2114 * fails. Port number may be specified even if the entry is a domain name, 2115 * in case the DNS SRV resolution should fallback to a non-standard port. 2116 * 2117 * When nameserver is not configured, entries will be resolved with 2118 * #pj_gethostbyname() if it's not an IP address. Port number may be 2119 * specified if the server is not listening in standard STUN port. 2120 */ 2121 pj_str_t stun_srv[8]; 2122 2123 /** 2124 * This specifies if the library should try to do an IPv6 resolution of 2125 * the STUN servers if the IPv4 resolution fails. It can be useful 2126 * in an IPv6-only environment, including on NAT64. 2127 * 2128 * Default: PJ_FALSE 2129 */ 2130 pj_bool_t stun_try_ipv6; 2131 2132 /** 2133 * This specifies if the library should ignore failure with the 2134 * STUN servers. If this is set to PJ_FALSE, the library will refuse to 2135 * start if it fails to resolve or contact any of the STUN servers. 2136 * 2137 * This setting will also determine what happens if STUN servers are 2138 * unavailable during runtime (if set to PJ_FALSE, calls will 2139 * directly fail, otherwise (if PJ_TRUE) call medias will 2140 * fallback to proceed as though not using STUN servers. 2141 * 2142 * Default: PJ_TRUE 2143 */ 2144 pj_bool_t stun_ignore_failure; 2145 2146 /** 2147 * This specifies whether STUN requests for resolving socket mapped 2148 * address should use the new format, i.e: having STUN magic cookie 2149 * in its transaction ID. 2150 * 2151 * Default: PJ_FALSE 2152 */ 2153 pj_bool_t stun_map_use_stun2; 2154 2155 /** 2156 * Support for adding and parsing NAT type in the SDP to assist 2157 * troubleshooting. The valid values are: 2158 * - 0: no information will be added in SDP, and parsing is disabled. 2159 * - 1: only the NAT type number is added. 2160 * - 2: add both NAT type number and name. 2161 * 2162 * Default: 1 2163 */ 2164 int nat_type_in_sdp; 2165 2166 /** 2167 * Specify how the support for reliable provisional response (100rel/ 2168 * PRACK) should be used by default. Note that this setting can be 2169 * further customized in account configuration (#pjsua_acc_config). 2170 * 2171 * Default: PJSUA_100REL_NOT_USED 2172 */ 2173 pjsua_100rel_use require_100rel; 2174 2175 /** 2176 * Specify the usage of Session Timers for all sessions. See the 2177 * #pjsua_sip_timer_use for possible values. Note that this setting can be 2178 * further customized in account configuration (#pjsua_acc_config). 2179 * 2180 * Default: PJSUA_SIP_TIMER_OPTIONAL 2181 */ 2182 pjsua_sip_timer_use use_timer; 2183 2184 /** 2185 * Handle unsolicited NOTIFY requests containing message waiting 2186 * indication (MWI) info. Unsolicited MWI is incoming NOTIFY requests 2187 * which are not requested by client with SUBSCRIBE request. 2188 * 2189 * If this is enabled, the library will respond 200/OK to the NOTIFY 2190 * request and forward the request to \a on_mwi_info() callback. 2191 * 2192 * See also \a mwi_enabled field #on pjsua_acc_config. 2193 * 2194 * Default: PJ_TRUE 2195 * 2196 */ 2197 pj_bool_t enable_unsolicited_mwi; 2198 2199 /** 2200 * Specify Session Timer settings, see #pjsip_timer_setting. 2201 * Note that this setting can be further customized in account 2202 * configuration (#pjsua_acc_config). 2203 */ 2204 pjsip_timer_setting timer_setting; 2205 2206 /** 2207 * Number of credentials in the credential array. 2208 */ 2209 unsigned cred_count; 2210 2211 /** 2212 * Array of credentials. These credentials will be used by all accounts, 2213 * and can be used to authenticate against outbound proxies. If the 2214 * credential is specific to the account, then application should set 2215 * the credential in the pjsua_acc_config rather than the credential 2216 * here. 2217 */ 2218 pjsip_cred_info cred_info[PJSUA_ACC_MAX_PROXIES]; 2219 2220 /** 2221 * Application callback to receive various event notifications from 2222 * the library. 2223 */ 2224 pjsua_callback cb; 2225 2226 /** 2227 * Optional user agent string (default empty). If it's empty, no 2228 * User-Agent header will be sent with outgoing requests. 2229 */ 2230 pj_str_t user_agent; 2231 2232 /** 2233 * Specify default value of secure media transport usage. 2234 * Valid values are PJMEDIA_SRTP_DISABLED, PJMEDIA_SRTP_OPTIONAL, and 2235 * PJMEDIA_SRTP_MANDATORY. 2236 * 2237 * Note that this setting can be further customized in account 2238 * configuration (#pjsua_acc_config). 2239 * 2240 * Default: #PJSUA_DEFAULT_USE_SRTP 2241 */ 2242 pjmedia_srtp_use use_srtp; 2243 2244 /** 2245 * Specify whether SRTP requires secure signaling to be used. This option 2246 * is only used when \a use_srtp option above is non-zero. 2247 * 2248 * Valid values are: 2249 * 0: SRTP does not require secure signaling 2250 * 1: SRTP requires secure transport such as TLS 2251 * 2: SRTP requires secure end-to-end transport (SIPS) 2252 * 2253 * Note that this setting can be further customized in account 2254 * configuration (#pjsua_acc_config). 2255 * 2256 * Default: #PJSUA_DEFAULT_SRTP_SECURE_SIGNALING 2257 */ 2258 int srtp_secure_signaling; 2259 2260 /** 2261 * This setting has been deprecated and will be ignored. 2262 */ 2263 pj_bool_t srtp_optional_dup_offer; 2264 2265 /** 2266 * Specify SRTP transport setting. Application can initialize it with 2267 * default values using pjsua_srtp_opt_default(). 2268 */ 2269 pjsua_srtp_opt srtp_opt; 2270 2271 /** 2272 * Disconnect other call legs when more than one 2xx responses for 2273 * outgoing INVITE are received due to forking. Currently the library 2274 * is not able to handle simultaneous forked media, so disconnecting 2275 * the other call legs is necessary. 2276 * 2277 * With this setting enabled, the library will handle only one of the 2278 * connected call leg, and the other connected call legs will be 2279 * disconnected. 2280 * 2281 * Default: PJ_TRUE (only disable this setting for testing purposes). 2282 */ 2283 pj_bool_t hangup_forked_call; 2284 2285 } pjsua_config; 2286 2287 2288 /** 2289 * Flags to be given to pjsua_destroy2() 2290 */ 2291 typedef enum pjsua_destroy_flag 2292 { 2293 /** 2294 * Allow sending outgoing messages (such as unregistration, event 2295 * unpublication, BYEs, unsubscription, etc.), but do not wait for 2296 * responses. This is useful to perform "best effort" clean up 2297 * without delaying the shutdown process waiting for responses. 2298 */ 2299 PJSUA_DESTROY_NO_RX_MSG = 1, 2300 2301 /** 2302 * If this flag is set, do not send any outgoing messages at all. 2303 * This flag is useful if application knows that the network which 2304 * the messages are to be sent on is currently down. 2305 */ 2306 PJSUA_DESTROY_NO_TX_MSG = 2, 2307 2308 /** 2309 * Do not send or receive messages during destroy. This flag is 2310 * shorthand for PJSUA_DESTROY_NO_RX_MSG + PJSUA_DESTROY_NO_TX_MSG. 2311 */ 2312 PJSUA_DESTROY_NO_NETWORK = PJSUA_DESTROY_NO_RX_MSG | 2313 PJSUA_DESTROY_NO_TX_MSG 2314 2315 } pjsua_destroy_flag; 2316 2317 /** 2318 * Use this function to initialize pjsua config. 2319 * 2320 * @param cfg pjsua config to be initialized. 2321 */ 2322 PJ_DECL(void) pjsua_config_default(pjsua_config *cfg); 2323 2324 2325 /** The implementation has been moved to sip_auth.h */ 2326 #define pjsip_cred_dup pjsip_cred_info_dup 2327 2328 2329 /** 2330 * Duplicate pjsua_config. 2331 * 2332 * @param pool The pool to get memory from. 2333 * @param dst Destination config. 2334 * @param src Source config. 2335 */ 2336 PJ_DECL(void) pjsua_config_dup(pj_pool_t *pool, 2337 pjsua_config *dst, 2338 const pjsua_config *src); 2339 2340 2341 /** 2342 * This structure describes additional information to be sent with 2343 * outgoing SIP message. It can (optionally) be specified for example 2344 * with #pjsua_call_make_call(), #pjsua_call_answer(), #pjsua_call_hangup(), 2345 * #pjsua_call_set_hold(), #pjsua_call_send_im(), and many more. 2346 * 2347 * Application MUST call #pjsua_msg_data_init() to initialize this 2348 * structure before setting its values. 2349 */ 2350 struct pjsua_msg_data 2351 { 2352 /** 2353 * Optional remote target URI (i.e. Target header). If NULL, the target 2354 * will be set to the remote URI (To header). This field is used by 2355 * pjsua_call_make_call(), pjsua_im_send(), pjsua_call_reinvite(), 2356 * pjsua_call_set_hold(), and pjsua_call_update(). 2357 */ 2358 pj_str_t target_uri; 2359 2360 /** 2361 * Additional message headers as linked list. Application can add 2362 * headers to the list by creating the header, either from the heap/pool 2363 * or from temporary local variable, and add the header using 2364 * linked list operation. See pjsua_app.c for some sample codes. 2365 */ 2366 pjsip_hdr hdr_list; 2367 2368 /** 2369 * MIME type of optional message body. 2370 */ 2371 pj_str_t content_type; 2372 2373 /** 2374 * Optional message body to be added to the message, only when the 2375 * message doesn't have a body. 2376 */ 2377 pj_str_t msg_body; 2378 2379 /** 2380 * Content type of the multipart body. If application wants to send 2381 * multipart message bodies, it puts the parts in \a parts and set 2382 * the content type in \a multipart_ctype. If the message already 2383 * contains a body, the body will be added to the multipart bodies. 2384 */ 2385 pjsip_media_type multipart_ctype; 2386 2387 /** 2388 * List of multipart parts. If application wants to send multipart 2389 * message bodies, it puts the parts in \a parts and set the content 2390 * type in \a multipart_ctype. If the message already contains a body, 2391 * the body will be added to the multipart bodies. 2392 */ 2393 pjsip_multipart_part multipart_parts; 2394 }; 2395 2396 2397 /** 2398 * Initialize message data. 2399 * 2400 * @param msg_data Message data to be initialized. 2401 */ 2402 PJ_DECL(void) pjsua_msg_data_init(pjsua_msg_data *msg_data); 2403 2404 2405 /** 2406 * Clone message data. 2407 * 2408 * @param pool Pool to allocate memory for the new message data. 2409 * @param rhs Message data to be cloned. 2410 * 2411 * @return The new message data. 2412 */ 2413 PJ_DECL(pjsua_msg_data*) pjsua_msg_data_clone(pj_pool_t *pool, 2414 const pjsua_msg_data *rhs); 2415 2416 2417 /** 2418 * Instantiate pjsua application. Application must call this function before 2419 * calling any other functions, to make sure that the underlying libraries 2420 * are properly initialized. Once this function has returned success, 2421 * application must call pjsua_destroy() before quitting. 2422 * 2423 * @return PJ_SUCCESS on success, or the appropriate error code. 2424 */ 2425 PJ_DECL(pj_status_t) pjsua_create(void); 2426 2427 2428 /** Forward declaration */ 2429 typedef struct pjsua_media_config pjsua_media_config; 2430 2431 2432 /** 2433 * Initialize pjsua with the specified settings. All the settings are 2434 * optional, and the default values will be used when the config is not 2435 * specified. 2436 * 2437 * Note that #pjsua_create() MUST be called before calling this function. 2438 * 2439 * @param ua_cfg User agent configuration. 2440 * @param log_cfg Optional logging configuration. 2441 * @param media_cfg Optional media configuration. 2442 * 2443 * @return PJ_SUCCESS on success, or the appropriate error code. 2444 */ 2445 PJ_DECL(pj_status_t) pjsua_init(const pjsua_config *ua_cfg, 2446 const pjsua_logging_config *log_cfg, 2447 const pjsua_media_config *media_cfg); 2448 2449 2450 /** 2451 * Application is recommended to call this function after all initialization 2452 * is done, so that the library can do additional checking set up 2453 * additional 2454 * 2455 * Application may call this function anytime after #pjsua_init(). 2456 * 2457 * @return PJ_SUCCESS on success, or the appropriate error code. 2458 */ 2459 PJ_DECL(pj_status_t) pjsua_start(void); 2460 2461 2462 /** 2463 * Destroy pjsua. Application is recommended to perform graceful shutdown 2464 * before calling this function (such as unregister the account from the SIP 2465 * server, terminate presense subscription, and hangup active calls), however, 2466 * this function will do all of these if it finds there are active sessions 2467 * that need to be terminated. This function will approximately block for 2468 * one second to wait for replies from remote. 2469 * 2470 * Application.may safely call this function more than once if it doesn't 2471 * keep track of it's state. 2472 * 2473 * @see pjsua_destroy2() 2474 * 2475 * @return PJ_SUCCESS on success, or the appropriate error code. 2476 */ 2477 PJ_DECL(pj_status_t) pjsua_destroy(void); 2478 2479 2480 /** 2481 * Retrieve pjsua state. 2482 * 2483 * @return pjsua state. 2484 */ 2485 PJ_DECL(pjsua_state) pjsua_get_state(void); 2486 2487 2488 /** 2489 * Variant of destroy with additional flags. 2490 * 2491 * @param flags Combination of pjsua_destroy_flag enumeration. 2492 * 2493 * @return PJ_SUCCESS on success, or the appropriate error code. 2494 */ 2495 PJ_DECL(pj_status_t) pjsua_destroy2(unsigned flags); 2496 2497 2498 /** 2499 * Poll pjsua for events, and if necessary block the caller thread for 2500 * the specified maximum interval (in miliseconds). 2501 * 2502 * Application doesn't normally need to call this function if it has 2503 * configured worker thread (\a thread_cnt field) in pjsua_config structure, 2504 * because polling then will be done by these worker threads instead. 2505 * 2506 * @param msec_timeout Maximum time to wait, in miliseconds. 2507 * 2508 * @return The number of events that have been handled during the 2509 * poll. Negative value indicates error, and application 2510 * can retrieve the error as (status = -return_value). 2511 */ 2512 PJ_DECL(int) pjsua_handle_events(unsigned msec_timeout); 2513 2514 2515 /** 2516 * Signal all worker threads to quit. This will only wait until internal 2517 * threads are done. 2518 */ 2519 PJ_DECL(void) pjsua_stop_worker_threads(void); 2520 2521 2522 /** 2523 * Create memory pool to be used by the application. Once application 2524 * finished using the pool, it must be released with pj_pool_release(). 2525 * 2526 * @param name Optional pool name. 2527 * @param init_size Initial size of the pool. 2528 * @param increment Increment size. 2529 * 2530 * @return The pool, or NULL when there's no memory. 2531 */ 2532 PJ_DECL(pj_pool_t*) pjsua_pool_create(const char *name, pj_size_t init_size, 2533 pj_size_t increment); 2534 2535 2536 /** 2537 * Application can call this function at any time (after pjsua_create(), of 2538 * course) to change logging settings. 2539 * 2540 * @param c Logging configuration. 2541 * 2542 * @return PJ_SUCCESS on success, or the appropriate error code. 2543 */ 2544 PJ_DECL(pj_status_t) pjsua_reconfigure_logging(const pjsua_logging_config *c); 2545 2546 2547 /** 2548 * Internal function to get SIP endpoint instance of pjsua, which is 2549 * needed for example to register module, create transports, etc. 2550 * Only valid after #pjsua_init() is called. 2551 * 2552 * @return SIP endpoint instance. 2553 */ 2554 PJ_DECL(pjsip_endpoint*) pjsua_get_pjsip_endpt(void); 2555 2556 /** 2557 * Internal function to get media endpoint instance. 2558 * Only valid after #pjsua_init() is called. 2559 * 2560 * @return Media endpoint instance. 2561 */ 2562 PJ_DECL(pjmedia_endpt*) pjsua_get_pjmedia_endpt(void); 2563 2564 /** 2565 * Internal function to get PJSUA pool factory. 2566 * Only valid after #pjsua_create() is called. 2567 * 2568 * @return Pool factory currently used by PJSUA. 2569 */ 2570 PJ_DECL(pj_pool_factory*) pjsua_get_pool_factory(void); 2571 2572 2573 2574 /***************************************************************************** 2575 * Utilities. 2576 * 2577 */ 2578 2579 /** 2580 * This structure is used to represent the result of the STUN server 2581 * resolution and testing, the #pjsua_resolve_stun_servers() function. 2582 * This structure will be passed in #pj_stun_resolve_cb callback. 2583 */ 2584 struct pj_stun_resolve_result 2585 { 2586 /** 2587 * Arbitrary data that was passed to #pjsua_resolve_stun_servers() 2588 * function. 2589 */ 2590 void *token; 2591 2592 /** 2593 * This will contain PJ_SUCCESS if at least one usable STUN server 2594 * is found, otherwise it will contain the last error code during 2595 * the operation. 2596 */ 2597 pj_status_t status; 2598 2599 /** 2600 * The server name that yields successful result. This will only 2601 * contain value if status is successful. 2602 */ 2603 pj_str_t name; 2604 2605 /** 2606 * The server IP address. This will only contain value if status 2607 * is successful. 2608 */ 2609 pj_sockaddr addr; 2610 2611 /** 2612 * The index of the usable STUN server. 2613 */ 2614 unsigned index; 2615 }; 2616 2617 2618 /** 2619 * This structure describe the parameter passed to #pjsua_handle_ip_change(). 2620 */ 2621 typedef struct pjsua_ip_change_param 2622 { 2623 /** 2624 * If set to PJ_TRUE, this will restart the transport listener. 2625 * 2626 * Default : PJ_TRUE 2627 */ 2628 pj_bool_t restart_listener; 2629 2630 /** 2631 * If \a restart listener is set to PJ_TRUE, some delay might be needed 2632 * for the listener to be restarted. Use this to set the delay. 2633 * 2634 * Default : PJSUA_TRANSPORT_RESTART_DELAY_TIME 2635 */ 2636 unsigned restart_lis_delay; 2637 2638 } pjsua_ip_change_param; 2639 2640 2641 /** 2642 * This structure describe the account config specific to IP address change. 2643 */ 2644 typedef struct pjsua_ip_change_acc_cfg 2645 { 2646 /** 2647 * Shutdown the transport used for account registration. If this is set to 2648 * PJ_TRUE, the transport will be shutdown altough it's used by multiple 2649 * account. Shutdown transport will be followed by re-Registration if 2650 * pjsua_acc_config.allow_contact_rewrite is enabled. 2651 * 2652 * Default: PJ_TRUE 2653 */ 2654 pj_bool_t shutdown_tp; 2655 2656 /** 2657 * Hangup active calls associated with the account. If this is set to 2658 * PJ_TRUE, then the calls will be hang up. 2659 * 2660 * Default: PJ_FALSE 2661 */ 2662 pj_bool_t hangup_calls; 2663 2664 /** 2665 * Specify the call flags used in the re-INVITE when \a hangup_calls is set 2666 * to PJ_FALSE. If this is set to 0, no re-INVITE will be sent. The 2667 * re-INVITE will be sent after re-Registration is finished. 2668 * 2669 * Default: PJSUA_CALL_REINIT_MEDIA | PJSUA_CALL_UPDATE_CONTACT | 2670 * PJSUA_CALL_UPDATE_VIA 2671 */ 2672 unsigned reinvite_flags; 2673 2674 } pjsua_ip_change_acc_cfg; 2675 2676 2677 /** 2678 * Call this function to initialize \a pjsua_ip_change_param with default 2679 * values. 2680 * 2681 * @param param The IP change param to be initialized. 2682 */ 2683 PJ_DECL(void) pjsua_ip_change_param_default(pjsua_ip_change_param *param); 2684 2685 2686 /** 2687 * This is a utility function to detect NAT type in front of this 2688 * endpoint. Once invoked successfully, this function will complete 2689 * asynchronously and report the result in \a on_nat_detect() callback 2690 * of pjsua_callback. 2691 * 2692 * After NAT has been detected and the callback is called, application can 2693 * get the detected NAT type by calling #pjsua_get_nat_type(). Application 2694 * can also perform NAT detection by calling #pjsua_detect_nat_type() 2695 * again at later time. 2696 * 2697 * Note that STUN must be enabled to run this function successfully. 2698 * 2699 * @return PJ_SUCCESS on success, or the appropriate error code. 2700 */ 2701 PJ_DECL(pj_status_t) pjsua_detect_nat_type(void); 2702 2703 2704 /** 2705 * Get the NAT type as detected by #pjsua_detect_nat_type() function. 2706 * This function will only return useful NAT type after #pjsua_detect_nat_type() 2707 * has completed successfully and \a on_nat_detect() callback has been called. 2708 * 2709 * @param type NAT type. 2710 * 2711 * @return When detection is in progress, this function will 2712 * return PJ_EPENDING and \a type will be set to 2713 * PJ_STUN_NAT_TYPE_UNKNOWN. After NAT type has been 2714 * detected successfully, this function will return 2715 * PJ_SUCCESS and \a type will be set to the correct 2716 * value. Other return values indicate error and 2717 * \a type will be set to PJ_STUN_NAT_TYPE_ERR_UNKNOWN. 2718 * 2719 * @see pjsua_call_get_rem_nat_type() 2720 */ 2721 PJ_DECL(pj_status_t) pjsua_get_nat_type(pj_stun_nat_type *type); 2722 2723 2724 /** 2725 * Update the STUN servers list. The #pjsua_init() must have been called 2726 * before calling this function. 2727 * 2728 * @param count Number of STUN server entries. 2729 * @param srv Array of STUN server entries to try. Please see 2730 * the \a stun_srv field in the #pjsua_config 2731 * documentation about the format of this entry. 2732 * @param wait Specify non-zero to make the function block until 2733 * it gets the result. In this case, the function 2734 * will block while the resolution is being done, 2735 * and the callback will be called before this function 2736 * returns. 2737 * 2738 * @return If \a wait parameter is non-zero, this will return 2739 * PJ_SUCCESS if one usable STUN server is found. 2740 * Otherwise it will always return PJ_SUCCESS, and 2741 * application will be notified about the result in 2742 * the callback #on_stun_resolution_complete. 2743 */ 2744 PJ_DECL(pj_status_t) pjsua_update_stun_servers(unsigned count, pj_str_t srv[], 2745 pj_bool_t wait); 2746 2747 2748 /** 2749 * Auxiliary function to resolve and contact each of the STUN server 2750 * entries (sequentially) to find which is usable. The #pjsua_init() must 2751 * have been called before calling this function. 2752 * 2753 * @param count Number of STUN server entries to try. 2754 * @param srv Array of STUN server entries to try. Please see 2755 * the \a stun_srv field in the #pjsua_config 2756 * documentation about the format of this entry. 2757 * @param wait Specify non-zero to make the function block until 2758 * it gets the result. In this case, the function 2759 * will block while the resolution is being done, 2760 * and the callback will be called before this function 2761 * returns. 2762 * @param token Arbitrary token to be passed back to application 2763 * in the callback. 2764 * @param cb Callback to be called to notify the result of 2765 * the function. 2766 * 2767 * @return If \a wait parameter is non-zero, this will return 2768 * PJ_SUCCESS if one usable STUN server is found. 2769 * Otherwise it will always return PJ_SUCCESS, and 2770 * application will be notified about the result in 2771 * the callback. 2772 */ 2773 PJ_DECL(pj_status_t) pjsua_resolve_stun_servers(unsigned count, 2774 pj_str_t srv[], 2775 pj_bool_t wait, 2776 void *token, 2777 pj_stun_resolve_cb cb); 2778 2779 /** 2780 * Cancel pending STUN resolution which match the specified token. 2781 * 2782 * @param token The token to match. This token was given to 2783 * #pjsua_resolve_stun_servers() 2784 * @param notify_cb Boolean to control whether the callback should 2785 * be called for cancelled resolutions. When the 2786 * callback is called, the status in the result 2787 * will be set as PJ_ECANCELLED. 2788 * 2789 * @return PJ_SUCCESS if there is at least one pending STUN 2790 * resolution cancelled, or PJ_ENOTFOUND if there is 2791 * no matching one, or other error. 2792 */ 2793 PJ_DECL(pj_status_t) pjsua_cancel_stun_resolution(void *token, 2794 pj_bool_t notify_cb); 2795 2796 2797 /** 2798 * This is a utility function to verify that valid SIP url is given. If the 2799 * URL is a valid SIP/SIPS scheme, PJ_SUCCESS will be returned. 2800 * 2801 * @param url The URL, as NULL terminated string. 2802 * 2803 * @return PJ_SUCCESS on success, or the appropriate error code. 2804 * 2805 * @see pjsua_verify_url() 2806 */ 2807 PJ_DECL(pj_status_t) pjsua_verify_sip_url(const char *url); 2808 2809 2810 /** 2811 * This is a utility function to verify that valid URI is given. Unlike 2812 * pjsua_verify_sip_url(), this function will return PJ_SUCCESS if tel: URI 2813 * is given. 2814 * 2815 * @param url The URL, as NULL terminated string. 2816 * 2817 * @return PJ_SUCCESS on success, or the appropriate error code. 2818 * 2819 * @see pjsua_verify_sip_url() 2820 */ 2821 PJ_DECL(pj_status_t) pjsua_verify_url(const char *url); 2822 2823 2824 /** 2825 * Schedule a timer entry. Note that the timer callback may be executed 2826 * by different thread, depending on whether worker thread is enabled or 2827 * not. 2828 * 2829 * @param entry Timer heap entry. 2830 * @param delay The interval to expire. 2831 * 2832 * @return PJ_SUCCESS on success, or the appropriate error code. 2833 * 2834 * @see pjsip_endpt_schedule_timer() 2835 */ 2836 #if PJ_TIMER_DEBUG 2837 #define pjsua_schedule_timer(e,d) pjsua_schedule_timer_dbg(e,d,\ 2838 __FILE__,__LINE__) 2839 2840 PJ_DECL(pj_status_t) pjsua_schedule_timer_dbg(pj_timer_entry *entry, 2841 const pj_time_val *delay, 2842 const char *src_file, 2843 int src_line); 2844 #else 2845 PJ_DECL(pj_status_t) pjsua_schedule_timer(pj_timer_entry *entry, 2846 const pj_time_val *delay); 2847 #endif 2848 2849 /** 2850 * Schedule a callback function to be called after a specified time interval. 2851 * Note that the callback may be executed by different thread, depending on 2852 * whether worker thread is enabled or not. 2853 * 2854 * @param cb The callback function. 2855 * @param user_data The user data. 2856 * @param msec_delay The time interval in msec. 2857 * 2858 * @return PJ_SUCCESS on success, or the appropriate error code. 2859 */ 2860 #if PJ_TIMER_DEBUG 2861 #define pjsua_schedule_timer2(cb,u,d) \ 2862 pjsua_schedule_timer2_dbg(cb,u,d,__FILE__,__LINE__) 2863 2864 PJ_DECL(pj_status_t) pjsua_schedule_timer2_dbg(void (*cb)(void *user_data), 2865 void *user_data, 2866 unsigned msec_delay, 2867 const char *src_file, 2868 int src_line); 2869 #else 2870 PJ_DECL(pj_status_t) pjsua_schedule_timer2(void (*cb)(void *user_data), 2871 void *user_data, 2872 unsigned msec_delay); 2873 #endif 2874 2875 /** 2876 * Cancel the previously scheduled timer. 2877 * 2878 * @param entry Timer heap entry. 2879 * 2880 * @see pjsip_endpt_cancel_timer() 2881 */ 2882 PJ_DECL(void) pjsua_cancel_timer(pj_timer_entry *entry); 2883 2884 2885 /** 2886 * This is a utility function to display error message for the specified 2887 * error code. The error message will be sent to the log. 2888 * 2889 * @param sender The log sender field. 2890 * @param title Message title for the error. 2891 * @param status Status code. 2892 */ 2893 PJ_DECL(void) pjsua_perror(const char *sender, const char *title, 2894 pj_status_t status); 2895 2896 2897 /** 2898 * This is a utility function to dump the stack states to log, using 2899 * verbosity level 3. 2900 * 2901 * @param detail Will print detailed output (such as list of 2902 * SIP transactions) when non-zero. 2903 */ 2904 PJ_DECL(void) pjsua_dump(pj_bool_t detail); 2905 2906 2907 /** 2908 * Inform the stack that IP address change event was detected. 2909 * The stack will: 2910 * 1. Restart the listener (this step is configurable via 2911 * \a pjsua_ip_change_param.restart_listener). 2912 * 2. Shutdown the transport used by account registration (this step is 2913 * configurable via \a pjsua_acc_config.ip_change_cfg.shutdown_tp). 2914 * 3. Update contact URI by sending re-Registration (this step is configurable 2915 * via a\ pjsua_acc_config.allow_contact_rewrite and 2916 * a\ pjsua_acc_config.contact_rewrite_method) 2917 * 4. Hangup active calls (this step is configurable via 2918 * a\ pjsua_acc_config.ip_change_cfg.hangup_calls) or 2919 * continue the call by sending re-INVITE 2920 * (configurable via \a pjsua_acc_config.ip_change_cfg.reinvite_flags). 2921 * 2922 * @param param The IP change parameter, have a look at 2923 * #pjsua_ip_change_param. 2924 * 2925 * @return PJ_SUCCESS on success, other on error. 2926 */ 2927 PJ_DECL(pj_status_t) pjsua_handle_ip_change( 2928 const pjsua_ip_change_param *param); 2929 2930 2931 /** 2932 * @} 2933 */ 2934 2935 2936 2937 /***************************************************************************** 2938 * TRANSPORT API 2939 */ 2940 2941 /** 2942 * @defgroup PJSUA_LIB_TRANSPORT PJSUA-API Signaling Transport 2943 * @ingroup PJSUA_LIB 2944 * @brief API for managing SIP transports 2945 * @{ 2946 * 2947 * PJSUA-API supports creating multiple transport instances, for example UDP, 2948 * TCP, and TLS transport. SIP transport must be created before adding an 2949 * account. 2950 */ 2951 2952 2953 /** SIP transport identification. 2954 */ 2955 typedef int pjsua_transport_id; 2956 2957 2958 /** 2959 * Transport configuration for creating transports for both SIP 2960 * and media. Before setting some values to this structure, application 2961 * MUST call #pjsua_transport_config_default() to initialize its 2962 * values with default settings. 2963 */ 2964 typedef struct pjsua_transport_config 2965 { 2966 /** 2967 * UDP port number to bind locally. This setting MUST be specified 2968 * even when default port is desired. If the value is zero, the 2969 * transport will be bound to any available port, and application 2970 * can query the port by querying the transport info. 2971 */ 2972 unsigned port; 2973 2974 /** 2975 * Specify the port range for socket binding, relative to the start 2976 * port number specified in \a port. Note that this setting is only 2977 * applicable when the start port number is non zero. 2978 * 2979 * Default value is zero. 2980 */ 2981 unsigned port_range; 2982 2983 /** 2984 * Optional address to advertise as the address of this transport. 2985 * Application can specify any address or hostname for this field, 2986 * for example it can point to one of the interface address in the 2987 * system, or it can point to the public address of a NAT router 2988 * where port mappings have been configured for the application. 2989 * 2990 * Note: this option can be used for both UDP and TCP as well! 2991 */ 2992 pj_str_t public_addr; 2993 2994 /** 2995 * Optional address where the socket should be bound to. This option 2996 * SHOULD only be used to selectively bind the socket to particular 2997 * interface (instead of 0.0.0.0), and SHOULD NOT be used to set the 2998 * published address of a transport (the public_addr field should be 2999 * used for that purpose). 3000 * 3001 * Note that unlike public_addr field, the address (or hostname) here 3002 * MUST correspond to the actual interface address in the host, since 3003 * this address will be specified as bind() argument. 3004 */ 3005 pj_str_t bound_addr; 3006 3007 /** 3008 * This specifies TLS settings for TLS transport. It is only be used 3009 * when this transport config is being used to create a SIP TLS 3010 * transport. 3011 */ 3012 pjsip_tls_setting tls_setting; 3013 3014 /** 3015 * QoS traffic type to be set on this transport. When application wants 3016 * to apply QoS tagging to the transport, it's preferable to set this 3017 * field rather than \a qos_param fields since this is more portable. 3018 * 3019 * Default is QoS not set. 3020 */ 3021 pj_qos_type qos_type; 3022 3023 /** 3024 * Set the low level QoS parameters to the transport. This is a lower 3025 * level operation than setting the \a qos_type field and may not be 3026 * supported on all platforms. 3027 * 3028 * Default is QoS not set. 3029 */ 3030 pj_qos_params qos_params; 3031 3032 /** 3033 * Specify options to be set on the transport. 3034 * 3035 * By default there is no options. 3036 * 3037 */ 3038 pj_sockopt_params sockopt_params; 3039 3040 } pjsua_transport_config; 3041 3042 3043 /** 3044 * Call this function to initialize UDP config with default values. 3045 * 3046 * @param cfg The UDP config to be initialized. 3047 */ 3048 PJ_DECL(void) pjsua_transport_config_default(pjsua_transport_config *cfg); 3049 3050 3051 /** 3052 * Duplicate transport config. 3053 * 3054 * @param pool The pool. 3055 * @param dst The destination config. 3056 * @param src The source config. 3057 */ 3058 PJ_DECL(void) pjsua_transport_config_dup(pj_pool_t *pool, 3059 pjsua_transport_config *dst, 3060 const pjsua_transport_config *src); 3061 3062 3063 /** 3064 * This structure describes transport information returned by 3065 * #pjsua_transport_get_info() function. 3066 */ 3067 typedef struct pjsua_transport_info 3068 { 3069 /** 3070 * PJSUA transport identification. 3071 */ 3072 pjsua_transport_id id; 3073 3074 /** 3075 * Transport type. 3076 */ 3077 pjsip_transport_type_e type; 3078 3079 /** 3080 * Transport type name. 3081 */ 3082 pj_str_t type_name; 3083 3084 /** 3085 * Transport string info/description. 3086 */ 3087 pj_str_t info; 3088 3089 /** 3090 * Transport flag (see ##pjsip_transport_flags_e). 3091 */ 3092 unsigned flag; 3093 3094 /** 3095 * Local address length. 3096 */ 3097 unsigned addr_len; 3098 3099 /** 3100 * Local/bound address. 3101 */ 3102 pj_sockaddr local_addr; 3103 3104 /** 3105 * Published address (or transport address name). 3106 */ 3107 pjsip_host_port local_name; 3108 3109 /** 3110 * Current number of objects currently referencing this transport. 3111 */ 3112 unsigned usage_count; 3113 3114 3115 } pjsua_transport_info; 3116 3117 3118 /** 3119 * Create and start a new SIP transport according to the specified 3120 * settings. 3121 * 3122 * @param type Transport type. 3123 * @param cfg Transport configuration. 3124 * @param p_id Optional pointer to receive transport ID. 3125 * 3126 * @return PJ_SUCCESS on success, or the appropriate error code. 3127 */ 3128 PJ_DECL(pj_status_t) pjsua_transport_create(pjsip_transport_type_e type, 3129 const pjsua_transport_config *cfg, 3130 pjsua_transport_id *p_id); 3131 3132 /** 3133 * Register transport that has been created by application. This function 3134 * is useful if application wants to implement custom SIP transport and use 3135 * it with pjsua. 3136 * 3137 * @param tp Transport instance. 3138 * @param p_id Optional pointer to receive transport ID. 3139 * 3140 * @return PJ_SUCCESS on success, or the appropriate error code. 3141 */ 3142 PJ_DECL(pj_status_t) pjsua_transport_register(pjsip_transport *tp, 3143 pjsua_transport_id *p_id); 3144 3145 3146 /** 3147 * Register transport factory that has been created by application. 3148 * This function is useful if application wants to implement custom SIP 3149 * transport and use it with pjsua. 3150 * 3151 * @param tf Transport factory instance. 3152 * @param p_id Optional pointer to receive transport ID. 3153 * 3154 * @return PJ_SUCCESS on success, or the appropriate error code. 3155 */ 3156 PJ_DECL(pj_status_t) pjsua_tpfactory_register( pjsip_tpfactory *tf, 3157 pjsua_transport_id *p_id); 3158 3159 /** 3160 * Enumerate all transports currently created in the system. This function 3161 * will return all transport IDs, and application may then call 3162 * #pjsua_transport_get_info() function to retrieve detailed information 3163 * about the transport. 3164 * 3165 * @param id Array to receive transport ids. 3166 * @param count In input, specifies the maximum number of elements. 3167 * On return, it contains the actual number of elements. 3168 * 3169 * @return PJ_SUCCESS on success, or the appropriate error code. 3170 */ 3171 PJ_DECL(pj_status_t) pjsua_enum_transports( pjsua_transport_id id[], 3172 unsigned *count ); 3173 3174 3175 /** 3176 * Get information about transports. 3177 * 3178 * @param id Transport ID. 3179 * @param info Pointer to receive transport info. 3180 * 3181 * @return PJ_SUCCESS on success, or the appropriate error code. 3182 */ 3183 PJ_DECL(pj_status_t) pjsua_transport_get_info(pjsua_transport_id id, 3184 pjsua_transport_info *info); 3185 3186 3187 /** 3188 * Disable a transport or re-enable it. By default transport is always 3189 * enabled after it is created. Disabling a transport does not necessarily 3190 * close the socket, it will only discard incoming messages and prevent 3191 * the transport from being used to send outgoing messages. 3192 * 3193 * @param id Transport ID. 3194 * @param enabled Non-zero to enable, zero to disable. 3195 * 3196 * @return PJ_SUCCESS on success, or the appropriate error code. 3197 */ 3198 PJ_DECL(pj_status_t) pjsua_transport_set_enable(pjsua_transport_id id, 3199 pj_bool_t enabled); 3200 3201 3202 /** 3203 * Close the transport. The system will wait until all transactions are 3204 * closed while preventing new users from using the transport, and will 3205 * close the transport when it is safe to do so. 3206 * 3207 * NOTE: Forcefully closing transport (force = PJ_TRUE) is deprecated, 3208 * since any pending transactions that are using the transport may not 3209 * terminate properly and can even crash. Application wishing to immediately 3210 * close the transport for the purpose of restarting it should use 3211 * #pjsua_handle_ip_change() instead. 3212 * 3213 * @param id Transport ID. 3214 * @param force Must be PJ_FALSE. force = PJ_TRUE is deprecated. 3215 * 3216 * @return PJ_SUCCESS on success, or the appropriate error code. 3217 */ 3218 PJ_DECL(pj_status_t) pjsua_transport_close( pjsua_transport_id id, 3219 pj_bool_t force ); 3220 3221 3222 /** 3223 * Start the listener of the transport. This is useful when listener is not 3224 * automatically started when creating the transport. 3225 * 3226 * @param id Transport ID. 3227 * @param cfg The new transport config used by the listener. 3228 * Only port, public_addr and bound_addr are used at the 3229 * moment. 3230 * 3231 * @return PJ_SUCCESS on success, or the appropriate error code. 3232 */ 3233 PJ_DECL(pj_status_t) pjsua_transport_lis_start( pjsua_transport_id id, 3234 const pjsua_transport_config *cfg); 3235 3236 3237 /** 3238 * @} 3239 */ 3240 3241 3242 3243 3244 /***************************************************************************** 3245 * ACCOUNT API 3246 */ 3247 3248 3249 /** 3250 * @defgroup PJSUA_LIB_ACC PJSUA-API Accounts Management 3251 * @ingroup PJSUA_LIB 3252 * @brief PJSUA Accounts management 3253 * @{ 3254 * 3255 * PJSUA accounts provide identity (or identities) of the user who is currently 3256 * using the application. In SIP terms, the identity is used as the <b>From</b> 3257 * header in outgoing requests. 3258 * 3259 * PJSUA-API supports creating and managing multiple accounts. The maximum 3260 * number of accounts is limited by a compile time constant 3261 * <tt>PJSUA_MAX_ACC</tt>. 3262 * 3263 * Account may or may not have client registration associated with it. 3264 * An account is also associated with <b>route set</b> and some <b>authentication 3265 * credentials</b>, which are used when sending SIP request messages using the 3266 * account. An account also has presence's <b>online status</b>, which 3267 * will be reported to remote peer when they subscribe to the account's 3268 * presence, or which is published to a presence server if presence 3269 * publication is enabled for the account. 3270 * 3271 * At least one account MUST be created in the application. If no user 3272 * association is required, application can create a userless account by 3273 * calling #pjsua_acc_add_local(). A userless account identifies local endpoint 3274 * instead of a particular user, and it correspond with a particular 3275 * transport instance. 3276 * 3277 * Also one account must be set as the <b>default account</b>, which is used as 3278 * the account to use when PJSUA fails to match a request with any other 3279 * accounts. 3280 * 3281 * When sending outgoing SIP requests (such as making calls or sending 3282 * instant messages), normally PJSUA requires the application to specify 3283 * which account to use for the request. If no account is specified, 3284 * PJSUA may be able to select the account by matching the destination 3285 * domain name, and fall back to default account when no match is found. 3286 */ 3287 3288 /** 3289 * Maximum accounts. 3290 */ 3291 #ifndef PJSUA_MAX_ACC 3292 # define PJSUA_MAX_ACC 8 3293 #endif 3294 3295 3296 /** 3297 * Default registration interval. 3298 */ 3299 #ifndef PJSUA_REG_INTERVAL 3300 # define PJSUA_REG_INTERVAL 300 3301 #endif 3302 3303 3304 /** 3305 * Default maximum time to wait for account unregistration transactions to 3306 * complete during library shutdown sequence. 3307 * 3308 * Default: 4000 (4 seconds) 3309 */ 3310 #ifndef PJSUA_UNREG_TIMEOUT 3311 # define PJSUA_UNREG_TIMEOUT 4000 3312 #endif 3313 3314 3315 /** 3316 * Default PUBLISH expiration 3317 */ 3318 #ifndef PJSUA_PUBLISH_EXPIRATION 3319 # define PJSUA_PUBLISH_EXPIRATION PJSIP_PUBC_EXPIRATION_NOT_SPECIFIED 3320 #endif 3321 3322 3323 /** 3324 * Default account priority. 3325 */ 3326 #ifndef PJSUA_DEFAULT_ACC_PRIORITY 3327 # define PJSUA_DEFAULT_ACC_PRIORITY 0 3328 #endif 3329 3330 3331 /** 3332 * Maximum time to wait for unpublication transaction(s) to complete 3333 * during shutdown process, before sending unregistration. The library 3334 * tries to wait for the unpublication (un-PUBLISH) to complete before 3335 * sending REGISTER request to unregister the account, during library 3336 * shutdown process. If the value is set too short, it is possible that 3337 * the unregistration is sent before unpublication completes, causing 3338 * unpublication request to fail. 3339 * 3340 * Default: 2000 (2 seconds) 3341 */ 3342 #ifndef PJSUA_UNPUBLISH_MAX_WAIT_TIME_MSEC 3343 # define PJSUA_UNPUBLISH_MAX_WAIT_TIME_MSEC 2000 3344 #endif 3345 3346 3347 /** 3348 * Default auto retry re-registration interval, in seconds. Set to 0 3349 * to disable this. Application can set the timer on per account basis 3350 * by setting the pjsua_acc_config.reg_retry_interval field instead. 3351 * 3352 * Default: 300 (5 minutes) 3353 */ 3354 #ifndef PJSUA_REG_RETRY_INTERVAL 3355 # define PJSUA_REG_RETRY_INTERVAL 300 3356 #endif 3357 3358 /** 3359 * When the registration is successfull, the auto registration refresh will 3360 * be sent before it expires. Setting this to 0 will disable it. 3361 * This is useful for app that uses Push Notification and doesn't require auto 3362 * registration refresh. App can periodically send refresh registration or 3363 * send it before making a call.= 3364 * See https://github.com/pjsip/pjproject/pull/2652 for more info. 3365 * 3366 * Default: 1 (enabled) 3367 */ 3368 #ifndef PJSUA_REG_AUTO_REG_REFRESH 3369 # define PJSUA_REG_AUTO_REG_REFRESH 1 3370 #endif 3371 3372 /** 3373 * This macro specifies the default value for \a contact_rewrite_method 3374 * field in pjsua_acc_config. It specifies how Contact update will be 3375 * done with the registration, if \a allow_contact_rewrite is enabled in 3376 * the account config. See \a pjsua_contact_rewrite_method for the options. 3377 * 3378 * Value PJSUA_CONTACT_REWRITE_UNREGISTER(1) is the legacy behavior. 3379 * 3380 * Default value: PJSUA_CONTACT_REWRITE_NO_UNREG(2) | 3381 * PJSUA_CONTACT_REWRITE_ALWAYS_UPDATE(4) 3382 */ 3383 #ifndef PJSUA_CONTACT_REWRITE_METHOD 3384 # define PJSUA_CONTACT_REWRITE_METHOD (PJSUA_CONTACT_REWRITE_NO_UNREG | \ 3385 PJSUA_CONTACT_REWRITE_ALWAYS_UPDATE) 3386 #endif 3387 3388 3389 /** 3390 * Bit value used in pjsua_acc_config.reg_use_proxy field to indicate that 3391 * the global outbound proxy list should be added to the REGISTER request. 3392 */ 3393 #define PJSUA_REG_USE_OUTBOUND_PROXY 1 3394 3395 3396 /** 3397 * Bit value used in pjsua_acc_config.reg_use_proxy field to indicate that 3398 * the account proxy list should be added to the REGISTER request. 3399 */ 3400 #define PJSUA_REG_USE_ACC_PROXY 2 3401 3402 3403 /** 3404 * This enumeration specifies how we should offer call hold request to 3405 * remote peer. The default value is set by compile time constant 3406 * PJSUA_CALL_HOLD_TYPE_DEFAULT, and application may control the setting 3407 * on per-account basis by manipulating \a call_hold_type field in 3408 * #pjsua_acc_config. 3409 */ 3410 typedef enum pjsua_call_hold_type 3411 { 3412 /** 3413 * This will follow RFC 3264 recommendation to use a=sendonly, 3414 * a=recvonly, and a=inactive attribute as means to signal call 3415 * hold status. This is the correct value to use. 3416 */ 3417 PJSUA_CALL_HOLD_TYPE_RFC3264, 3418 3419 /** 3420 * This will use the old and deprecated method as specified in RFC 2543, 3421 * and will offer c=0.0.0.0 in the SDP instead. Using this has many 3422 * drawbacks such as inability to keep the media transport alive while 3423 * the call is being put on hold, and should only be used if remote 3424 * does not understand RFC 3264 style call hold offer. 3425 */ 3426 PJSUA_CALL_HOLD_TYPE_RFC2543 3427 3428 } pjsua_call_hold_type; 3429 3430 3431 /** 3432 * Specify the default call hold type to be used in #pjsua_acc_config. 3433 * 3434 * Default is PJSUA_CALL_HOLD_TYPE_RFC3264, and there's no reason to change 3435 * this except if you're communicating with an old/non-standard peer. 3436 */ 3437 #ifndef PJSUA_CALL_HOLD_TYPE_DEFAULT 3438 # define PJSUA_CALL_HOLD_TYPE_DEFAULT PJSUA_CALL_HOLD_TYPE_RFC3264 3439 #endif 3440 3441 /** 3442 * This enumeration controls the use of STUN in the account. 3443 */ 3444 typedef enum pjsua_stun_use 3445 { 3446 /** 3447 * Follow the default setting in the global \a pjsua_config. 3448 */ 3449 PJSUA_STUN_USE_DEFAULT, 3450 3451 /** 3452 * Disable STUN. If STUN is not enabled in the global \a pjsua_config, 3453 * this setting has no effect. 3454 */ 3455 PJSUA_STUN_USE_DISABLED, 3456 3457 /** 3458 * Retry other STUN servers if the STUN server selected during 3459 * startup (#pjsua_init()) or after calling #pjsua_update_stun_servers() 3460 * is unavailable during runtime. This setting is valid only for 3461 * account's media STUN setting and if the call is using UDP media 3462 * transport. 3463 */ 3464 PJSUA_STUN_RETRY_ON_FAILURE 3465 3466 } pjsua_stun_use; 3467 3468 /** 3469 * This enumeration controls the use of ICE settings in the account. 3470 */ 3471 typedef enum pjsua_ice_config_use 3472 { 3473 /** 3474 * Use the default settings in the global \a pjsua_media_config. 3475 */ 3476 PJSUA_ICE_CONFIG_USE_DEFAULT, 3477 3478 /** 3479 * Use the custom \a pjsua_ice_config setting in the account. 3480 */ 3481 PJSUA_ICE_CONFIG_USE_CUSTOM 3482 3483 } pjsua_ice_config_use; 3484 3485 /** 3486 * This enumeration controls the use of TURN settings in the account. 3487 */ 3488 typedef enum pjsua_turn_config_use 3489 { 3490 /** 3491 * Use the default setting in the global \a pjsua_media_config. 3492 */ 3493 PJSUA_TURN_CONFIG_USE_DEFAULT, 3494 3495 /** 3496 * Use the custom \a pjsua_turn_config setting in the account. 3497 */ 3498 PJSUA_TURN_CONFIG_USE_CUSTOM 3499 3500 } pjsua_turn_config_use; 3501 3502 /** 3503 * ICE setting. This setting is used in the pjsua_acc_config. 3504 */ 3505 typedef struct pjsua_ice_config 3506 { 3507 /** 3508 * Enable ICE. 3509 */ 3510 pj_bool_t enable_ice; 3511 3512 /** 3513 * Set the maximum number of host candidates. 3514 * 3515 * Default: -1 (maximum not set) 3516 */ 3517 int ice_max_host_cands; 3518 3519 /** 3520 * ICE session options. 3521 */ 3522 pj_ice_sess_options ice_opt; 3523 3524 /** 3525 * Disable RTCP component. 3526 * 3527 * Default: no 3528 */ 3529 pj_bool_t ice_no_rtcp; 3530 3531 /** 3532 * Send re-INVITE/UPDATE every after ICE connectivity check regardless 3533 * the default ICE transport address is changed or not. When this is set 3534 * to PJ_FALSE, re-INVITE/UPDATE will be sent only when the default ICE 3535 * transport address is changed. 3536 * 3537 * Default: yes 3538 */ 3539 pj_bool_t ice_always_update; 3540 3541 } pjsua_ice_config; 3542 3543 /** 3544 * TURN setting. This setting is used in the pjsua_acc_config. 3545 */ 3546 typedef struct pjsua_turn_config 3547 { 3548 /** 3549 * Enable TURN candidate in ICE. 3550 */ 3551 pj_bool_t enable_turn; 3552 3553 /** 3554 * Specify TURN domain name or host name, in in "DOMAIN:PORT" or 3555 * "HOST:PORT" format. 3556 */ 3557 pj_str_t turn_server; 3558 3559 /** 3560 * Specify the connection type to be used to the TURN server. Valid 3561 * values are PJ_TURN_TP_UDP, PJ_TURN_TP_TCP or PJ_TURN_TP_TLS. 3562 * 3563 * Default: PJ_TURN_TP_UDP 3564 */ 3565 pj_turn_tp_type turn_conn_type; 3566 3567 /** 3568 * Specify the credential to authenticate with the TURN server. 3569 */ 3570 pj_stun_auth_cred turn_auth_cred; 3571 3572 /** 3573 * This specifies TLS settings for TURN TLS. It is only be used 3574 * when this TLS is used to connect to the TURN server. 3575 */ 3576 pj_turn_sock_tls_cfg turn_tls_setting; 3577 3578 } pjsua_turn_config; 3579 3580 /** 3581 * Specify how IPv6 transport should be used in account config. 3582 */ 3583 typedef enum pjsua_ipv6_use 3584 { 3585 /** 3586 * IPv6 is not used. 3587 */ 3588 PJSUA_IPV6_DISABLED, 3589 3590 /** 3591 * IPv6 is enabled. 3592 */ 3593 PJSUA_IPV6_ENABLED 3594 3595 } pjsua_ipv6_use; 3596 3597 /** 3598 * Specify NAT64 options to be used in account config. 3599 */ 3600 typedef enum pjsua_nat64_opt 3601 { 3602 /** 3603 * NAT64 is not used. 3604 */ 3605 PJSUA_NAT64_DISABLED, 3606 3607 /** 3608 * NAT64 is enabled. 3609 */ 3610 PJSUA_NAT64_ENABLED 3611 3612 } pjsua_nat64_opt; 3613 3614 3615 /** 3616 * This structure describes account configuration to be specified when 3617 * adding a new account with #pjsua_acc_add(). Application MUST initialize 3618 * this structure first by calling #pjsua_acc_config_default(). 3619 */ 3620 typedef struct pjsua_acc_config 3621 { 3622 /** 3623 * Arbitrary user data to be associated with the newly created account. 3624 * Application may set this later with #pjsua_acc_set_user_data() and 3625 * retrieve it with #pjsua_acc_get_user_data(). 3626 */ 3627 void *user_data; 3628 3629 /** 3630 * Account priority, which is used to control the order of matching 3631 * incoming/outgoing requests. The higher the number means the higher 3632 * the priority is, and the account will be matched first. 3633 */ 3634 int priority; 3635 3636 /** 3637 * The full SIP URL for the account. The value can take name address or 3638 * URL format, and will look something like "sip:account@serviceprovider" 3639 * or "\"Display Name\" <sip:account@provider>". 3640 * 3641 * This field is mandatory. 3642 */ 3643 pj_str_t id; 3644 3645 /** 3646 * This is the URL to be put in the request URI for the registration, 3647 * and will look something like "sip:serviceprovider". 3648 * 3649 * This field should be specified if registration is desired. If the 3650 * value is empty, no account registration will be performed. 3651 */ 3652 pj_str_t reg_uri; 3653 3654 /** 3655 * The optional custom SIP headers to be put in the registration 3656 * request. 3657 */ 3658 pjsip_hdr reg_hdr_list; 3659 3660 /** 3661 * Additional parameters that will be appended in the Contact header 3662 * for this account. This will only affect REGISTER requests and 3663 * will be appended after \a contact_params; 3664 * 3665 * The parameters should be preceeded by semicolon, and all strings must 3666 * be properly escaped. Example: 3667 * ";my-param=X;another-param=Hi%20there" 3668 */ 3669 pj_str_t reg_contact_params; 3670 3671 /** 3672 * The optional custom SIP headers to be put in the presence 3673 * subscription request. 3674 */ 3675 pjsip_hdr sub_hdr_list; 3676 3677 /** 3678 * Subscribe to message waiting indication events (RFC 3842). 3679 * 3680 * See also \a enable_unsolicited_mwi field on #pjsua_config. 3681 * 3682 * Default: no 3683 */ 3684 pj_bool_t mwi_enabled; 3685 3686 /** 3687 * Specify the default expiration time for Message Waiting Indication 3688 * (RFC 3842) event subscription. This must not be zero. 3689 * 3690 * Default: PJSIP_MWI_DEFAULT_EXPIRES 3691 */ 3692 unsigned mwi_expires; 3693 3694 /** 3695 * If this flag is set, the presence information of this account will 3696 * be PUBLISH-ed to the server where the account belongs. 3697 * 3698 * Default: PJ_FALSE 3699 */ 3700 pj_bool_t publish_enabled; 3701 3702 /** 3703 * Event publication options. 3704 */ 3705 pjsip_publishc_opt publish_opt; 3706 3707 /** 3708 * Maximum time to wait for unpublication transaction(s) to complete 3709 * during shutdown process, before sending unregistration. The library 3710 * tries to wait for the unpublication (un-PUBLISH) to complete before 3711 * sending REGISTER request to unregister the account, during library 3712 * shutdown process. If the value is set too short, it is possible that 3713 * the unregistration is sent before unpublication completes, causing 3714 * unpublication request to fail. 3715 * 3716 * Default: PJSUA_UNPUBLISH_MAX_WAIT_TIME_MSEC 3717 */ 3718 unsigned unpublish_max_wait_time_msec; 3719 3720 /** 3721 * Authentication preference. 3722 */ 3723 pjsip_auth_clt_pref auth_pref; 3724 3725 /** 3726 * Optional PIDF tuple ID for outgoing PUBLISH and NOTIFY. If this value 3727 * is not specified, a random string will be used. 3728 */ 3729 pj_str_t pidf_tuple_id; 3730 3731 /** 3732 * Optional URI to be put as Contact for this account. It is recommended 3733 * that this field is left empty, so that the value will be calculated 3734 * automatically based on the transport address. 3735 */ 3736 pj_str_t force_contact; 3737 3738 /** 3739 * Additional parameters that will be appended in the Contact header 3740 * for this account. This will affect the Contact header in all SIP 3741 * messages sent on behalf of this account, including but not limited to 3742 * REGISTER, INVITE, and SUBCRIBE requests or responses. 3743 * 3744 * The parameters should be preceeded by semicolon, and all strings must 3745 * be properly escaped. Example: 3746 * ";my-param=X;another-param=Hi%20there" 3747 */ 3748 pj_str_t contact_params; 3749 3750 /** 3751 * Additional URI parameters that will be appended in the Contact URI 3752 * for this account. This will affect the Contact URI in all SIP 3753 * messages sent on behalf of this account, including but not limited to 3754 * REGISTER, INVITE, and SUBCRIBE requests or responses. 3755 * 3756 * The parameters should be preceeded by semicolon, and all strings must 3757 * be properly escaped. Example: 3758 * ";my-param=X;another-param=Hi%20there" 3759 */ 3760 pj_str_t contact_uri_params; 3761 3762 /** 3763 * Specify how support for reliable provisional response (100rel/ 3764 * PRACK) should be used for all sessions in this account. See the 3765 * documentation of pjsua_100rel_use enumeration for more info. 3766 * 3767 * Default: The default value is taken from the value of 3768 * require_100rel in pjsua_config. 3769 */ 3770 pjsua_100rel_use require_100rel; 3771 3772 /** 3773 * Specify the usage of Session Timers for all sessions. See the 3774 * #pjsua_sip_timer_use for possible values. 3775 * 3776 * Default: PJSUA_SIP_TIMER_OPTIONAL 3777 */ 3778 pjsua_sip_timer_use use_timer; 3779 3780 /** 3781 * Specify Session Timer settings, see #pjsip_timer_setting. 3782 */ 3783 pjsip_timer_setting timer_setting; 3784 3785 /** 3786 * Number of proxies in the proxy array below. 3787 */ 3788 unsigned proxy_cnt; 3789 3790 /** 3791 * Optional URI of the proxies to be visited for all outgoing requests 3792 * that are using this account (REGISTER, INVITE, etc). Application need 3793 * to specify these proxies if the service provider requires that requests 3794 * destined towards its network should go through certain proxies first 3795 * (for example, border controllers). 3796 * 3797 * These proxies will be put in the route set for this account, with 3798 * maintaining the orders (the first proxy in the array will be visited 3799 * first). If global outbound proxies are configured in pjsua_config, 3800 * then these account proxies will be placed after the global outbound 3801 * proxies in the routeset. 3802 */ 3803 pj_str_t proxy[PJSUA_ACC_MAX_PROXIES]; 3804 3805 /** 3806 * If remote sends SDP answer containing more than one format or codec in 3807 * the media line, send re-INVITE or UPDATE with just one codec to lock 3808 * which codec to use. 3809 * 3810 * Default: 1 (Yes). Set to zero to disable. 3811 */ 3812 unsigned lock_codec; 3813 3814 /** 3815 * Optional interval for registration, in seconds. If the value is zero, 3816 * default interval will be used (PJSUA_REG_INTERVAL, 300 seconds). 3817 */ 3818 unsigned reg_timeout; 3819 3820 /** 3821 * Specify the number of seconds to refresh the client registration 3822 * before the registration expires. 3823 * 3824 * Default: PJSIP_REGISTER_CLIENT_DELAY_BEFORE_REFRESH, 5 seconds 3825 */ 3826 unsigned reg_delay_before_refresh; 3827 3828 /** 3829 * Specify the maximum time to wait for unregistration requests to 3830 * complete during library shutdown sequence. 3831 * 3832 * Default: PJSUA_UNREG_TIMEOUT 3833 */ 3834 unsigned unreg_timeout; 3835 3836 /** 3837 * Number of credentials in the credential array. 3838 */ 3839 unsigned cred_count; 3840 3841 /** 3842 * Array of credentials. If registration is desired, normally there should 3843 * be at least one credential specified, to successfully authenticate 3844 * against the service provider. More credentials can be specified, for 3845 * example when the requests are expected to be challenged by the 3846 * proxies in the route set. 3847 */ 3848 pjsip_cred_info cred_info[PJSUA_ACC_MAX_PROXIES]; 3849 3850 /** 3851 * Optionally bind this account to specific transport. This normally is 3852 * not a good idea, as account should be able to send requests using 3853 * any available transports according to the destination. But some 3854 * application may want to have explicit control over the transport to 3855 * use, so in that case it can set this field. 3856 * 3857 * Default: -1 (PJSUA_INVALID_ID) 3858 * 3859 * @see pjsua_acc_set_transport() 3860 */ 3861 pjsua_transport_id transport_id; 3862 3863 /** 3864 * This option is used to update the transport address and the Contact 3865 * header of REGISTER request. When this option is enabled, the library 3866 * will keep track of the public IP address from the response of REGISTER 3867 * request. Once it detects that the address has changed, it will 3868 * unregister current Contact, update the Contact with transport address 3869 * learned from Via header, and register a new Contact to the registrar. 3870 * This will also update the public name of UDP transport if STUN is 3871 * configured. 3872 * 3873 * See also contact_rewrite_method field. 3874 * 3875 * Default: 1 (yes) 3876 */ 3877 pj_bool_t allow_contact_rewrite; 3878 3879 /** 3880 * Specify how Contact update will be done with the registration, if 3881 * \a allow_contact_rewrite is enabled. The value is bitmask combination of 3882 * \a pjsua_contact_rewrite_method. See also pjsua_contact_rewrite_method. 3883 * 3884 * Value PJSUA_CONTACT_REWRITE_UNREGISTER(1) is the legacy behavior. 3885 * 3886 * Default value: PJSUA_CONTACT_REWRITE_METHOD 3887 * (PJSUA_CONTACT_REWRITE_NO_UNREG | PJSUA_CONTACT_REWRITE_ALWAYS_UPDATE) 3888 */ 3889 int contact_rewrite_method; 3890 3891 /** 3892 * Specify if source TCP port should be used as the initial Contact 3893 * address if TCP/TLS transport is used. Note that this feature will 3894 * be automatically turned off when nameserver is configured because 3895 * it may yield different destination address due to DNS SRV resolution. 3896 * Also some platforms are unable to report the local address of the 3897 * TCP socket when it is still connecting. In these cases, this 3898 * feature will also be turned off. 3899 * 3900 * Default: PJ_TRUE (yes). 3901 */ 3902 pj_bool_t contact_use_src_port; 3903 3904 /** 3905 * This option is used to overwrite the "sent-by" field of the Via header 3906 * for outgoing messages with the same interface address as the one in 3907 * the REGISTER request, as long as the request uses the same transport 3908 * instance as the previous REGISTER request. 3909 * 3910 * Default: 1 (yes) 3911 */ 3912 pj_bool_t allow_via_rewrite; 3913 3914 /** 3915 * This option controls whether the IP address in SDP should be replaced 3916 * with the IP address found in Via header of the REGISTER response, ONLY 3917 * when STUN and ICE are not used. If the value is FALSE (the original 3918 * behavior), then the local IP address will be used. If TRUE, and when 3919 * STUN and ICE are disabled, then the IP address found in registration 3920 * response will be used. 3921 * 3922 * Default: PJ_FALSE (no) 3923 */ 3924 pj_bool_t allow_sdp_nat_rewrite; 3925 3926 /** 3927 * Control the use of SIP outbound feature. SIP outbound is described in 3928 * RFC 5626 to enable proxies or registrar to send inbound requests back 3929 * to UA using the same connection initiated by the UA for its 3930 * registration. This feature is highly useful in NAT-ed deployemtns, 3931 * hence it is enabled by default. 3932 * 3933 * Note: currently SIP outbound can only be used with TCP and TLS 3934 * transports. If UDP is used for the registration, the SIP outbound 3935 * feature will be silently ignored for the account. 3936 * 3937 * Default: PJ_TRUE 3938 */ 3939 unsigned use_rfc5626; 3940 3941 /** 3942 * Specify SIP outbound (RFC 5626) instance ID to be used by this 3943 * application. If empty, an instance ID will be generated based on 3944 * the hostname of this agent. If application specifies this parameter, the 3945 * value will look like "<urn:uuid:00000000-0000-1000-8000-AABBCCDDEEFF>" 3946 * without the doublequote. 3947 * 3948 * Default: empty 3949 */ 3950 pj_str_t rfc5626_instance_id; 3951 3952 /** 3953 * Specify SIP outbound (RFC 5626) registration ID. The default value 3954 * is empty, which would cause the library to automatically generate 3955 * a suitable value. 3956 * 3957 * Default: empty 3958 */ 3959 pj_str_t rfc5626_reg_id; 3960 3961 /** 3962 * Set the interval for periodic keep-alive transmission for this account. 3963 * If this value is zero, keep-alive will be disabled for this account. 3964 * The keep-alive transmission will be sent to the registrar's address, 3965 * after successful registration. 3966 * 3967 * Default: 15 (seconds) 3968 */ 3969 unsigned ka_interval; 3970 3971 /** 3972 * Specify the data to be transmitted as keep-alive packets. 3973 * 3974 * Default: CR-LF 3975 */ 3976 pj_str_t ka_data; 3977 3978 /** 3979 * Specify whether incoming video should be shown to screen by default. 3980 * This applies to incoming call (INVITE), incoming re-INVITE, and 3981 * incoming UPDATE requests. 3982 * 3983 * Regardless of this setting, application can detect incoming video 3984 * by implementing \a on_call_media_state() callback and enumerating 3985 * the media stream(s) with #pjsua_call_get_info(). Once incoming 3986 * video is recognised, application may retrieve the window associated 3987 * with the incoming video and show or hide it with 3988 * #pjsua_vid_win_set_show(). 3989 * 3990 * Default: PJ_FALSE 3991 */ 3992 pj_bool_t vid_in_auto_show; 3993 3994 /** 3995 * Specify whether outgoing video should be activated by default when 3996 * making outgoing calls and/or when incoming video is detected. This 3997 * applies to incoming and outgoing calls, incoming re-INVITE, and 3998 * incoming UPDATE. If the setting is non-zero, outgoing video 3999 * transmission will be started as soon as response to these requests 4000 * is sent (or received). 4001 * 4002 * Regardless of the value of this setting, application can start and 4003 * stop outgoing video transmission with #pjsua_call_set_vid_strm(). 4004 * 4005 * Default: PJ_FALSE 4006 */ 4007 pj_bool_t vid_out_auto_transmit; 4008 4009 /** 4010 * Specify video window's flags. The value is a bitmask combination of 4011 * #pjmedia_vid_dev_wnd_flag. 4012 * 4013 * Default: 0 4014 */ 4015 unsigned vid_wnd_flags; 4016 4017 /** 4018 * Specify the default capture device to be used by this account. If 4019 * \a vid_out_auto_transmit is enabled, this device will be used for 4020 * capturing video. 4021 * 4022 * Default: PJMEDIA_VID_DEFAULT_CAPTURE_DEV 4023 */ 4024 pjmedia_vid_dev_index vid_cap_dev; 4025 4026 /** 4027 * Specify the default rendering device to be used by this account. 4028 * 4029 * Default: PJMEDIA_VID_DEFAULT_RENDER_DEV 4030 */ 4031 pjmedia_vid_dev_index vid_rend_dev; 4032 4033 /** 4034 * Specify the send rate control for video stream. 4035 * 4036 * Default: see #pjmedia_vid_stream_rc_config 4037 */ 4038 pjmedia_vid_stream_rc_config vid_stream_rc_cfg; 4039 4040 /** 4041 * Specify the send keyframe config for video stream. 4042 * 4043 * Default: see #pjmedia_vid_stream_sk_config 4044 */ 4045 pjmedia_vid_stream_sk_config vid_stream_sk_cfg; 4046 4047 /** 4048 * Media transport config. 4049 */ 4050 pjsua_transport_config rtp_cfg; 4051 4052 /** 4053 * Specify NAT64 options. 4054 * 4055 * Default: PJSUA_NAT64_DISABLED 4056 */ 4057 pjsua_nat64_opt nat64_opt; 4058 4059 /** 4060 * Specify whether IPv6 should be used on media. 4061 */ 4062 pjsua_ipv6_use ipv6_media_use; 4063 4064 /** 4065 * Control the use of STUN for the SIP signaling. 4066 * 4067 * Default: PJSUA_STUN_USE_DEFAULT 4068 */ 4069 pjsua_stun_use sip_stun_use; 4070 4071 /** 4072 * Control the use of STUN for the media transports. 4073 * 4074 * Default: PJSUA_STUN_RETRY_ON_FAILURE 4075 */ 4076 pjsua_stun_use media_stun_use; 4077 4078 /** 4079 * Use loopback media transport. This may be useful if application 4080 * doesn't want PJSIP to create real media transports/sockets, such as 4081 * when using third party media. 4082 * 4083 * Default: PJ_FALSE 4084 */ 4085 pj_bool_t use_loop_med_tp; 4086 4087 /** 4088 * Enable local loopback when loop_med_tp_use is set to PJ_TRUE. 4089 * If enabled, packets sent to the transport will be sent back to 4090 * the streams attached to the transport. 4091 * 4092 * Default: PJ_FALSE 4093 */ 4094 pj_bool_t enable_loopback; 4095 4096 /** 4097 * Control the use of ICE in the account. By default, the settings in the 4098 * \a pjsua_media_config will be used. 4099 * 4100 * Default: PJSUA_ICE_CONFIG_USE_DEFAULT 4101 */ 4102 pjsua_ice_config_use ice_cfg_use; 4103 4104 /** 4105 * The custom ICE setting for this account. This setting will only be 4106 * used if \a ice_cfg_use is set to PJSUA_ICE_CONFIG_USE_CUSTOM 4107 */ 4108 pjsua_ice_config ice_cfg; 4109 4110 /** 4111 * Control the use of TURN in the account. By default, the settings in the 4112 * \a pjsua_media_config will be used 4113 * 4114 * Default: PJSUA_TURN_CONFIG_USE_DEFAULT 4115 */ 4116 pjsua_turn_config_use turn_cfg_use; 4117 4118 /** 4119 * The custom TURN setting for this account. This setting will only be 4120 * used if \a turn_cfg_use is set to PJSUA_TURN_CONFIG_USE_CUSTOM 4121 */ 4122 pjsua_turn_config turn_cfg; 4123 4124 /** 4125 * Specify whether secure media transport should be used for this account. 4126 * Valid values are PJMEDIA_SRTP_DISABLED, PJMEDIA_SRTP_OPTIONAL, and 4127 * PJMEDIA_SRTP_MANDATORY. 4128 * 4129 * Default: #PJSUA_DEFAULT_USE_SRTP 4130 */ 4131 pjmedia_srtp_use use_srtp; 4132 4133 /** 4134 * Specify whether SRTP requires secure signaling to be used. This option 4135 * is only used when \a use_srtp option above is non-zero. 4136 * 4137 * Valid values are: 4138 * 0: SRTP does not require secure signaling 4139 * 1: SRTP requires secure transport such as TLS 4140 * 2: SRTP requires secure end-to-end transport (SIPS) 4141 * 4142 * Default: #PJSUA_DEFAULT_SRTP_SECURE_SIGNALING 4143 */ 4144 int srtp_secure_signaling; 4145 4146 /** 4147 * This setting has been deprecated and will be ignored. 4148 */ 4149 pj_bool_t srtp_optional_dup_offer; 4150 4151 /** 4152 * Specify SRTP transport setting. Application can initialize it with 4153 * default values using pjsua_srtp_opt_default(). 4154 */ 4155 pjsua_srtp_opt srtp_opt; 4156 4157 /** 4158 * Specify interval of auto registration retry upon registration failure, 4159 * in seconds. Set to 0 to disable auto re-registration. Note that 4160 * registration will only be automatically retried for temporal failures 4161 * considered to be recoverable in relatively short term, such as: 4162 * 408 (Request Timeout), 480 (Temporarily Unavailable), 4163 * 500 (Internal Server Error), 502 (Bad Gateway), 4164 * 503 (Service Unavailable), 504 (Server Timeout), 4165 * 6xx (global failure), and failure caused by transport problem. 4166 * For registration retry caused by transport failure, the first retry 4167 * will be done after \a reg_first_retry_interval seconds instead. 4168 * Note that the interval will be randomized slightly by some seconds 4169 * (specified in \a reg_retry_random_interval) to avoid all clients 4170 * re-registering at the same time. 4171 * 4172 * See also \a reg_first_retry_interval setting. 4173 * 4174 * Default: #PJSUA_REG_RETRY_INTERVAL 4175 */ 4176 unsigned reg_retry_interval; 4177 4178 /** 4179 * This specifies the interval for the first registration retry. The 4180 * registration retry is explained in \a reg_retry_interval. Note that 4181 * the value here will also be randomized by some seconds (specified 4182 * in \a reg_retry_random_interval) to avoid all clients re-registering 4183 * at the same time. 4184 * 4185 * Default: 0 4186 */ 4187 unsigned reg_first_retry_interval; 4188 4189 /** 4190 * This specifies maximum randomized value to be added/substracted 4191 * to/from the registration retry interval specified in \a 4192 * reg_retry_interval and \a reg_first_retry_interval, in second. 4193 * This is useful to avoid all clients re-registering at the same time. 4194 * For example, if the registration retry interval is set to 100 seconds 4195 * and this is set to 10 seconds, the actual registration retry interval 4196 * will be in the range of 90 to 110 seconds. 4197 * 4198 * Default: 10 4199 */ 4200 unsigned reg_retry_random_interval; 4201 4202 /** 4203 * Specify whether calls of the configured account should be dropped 4204 * after registration failure and an attempt of re-registration has 4205 * also failed. 4206 * 4207 * Default: PJ_FALSE (disabled) 4208 */ 4209 pj_bool_t drop_calls_on_reg_fail; 4210 4211 /** 4212 * Specify how the registration uses the outbound and account proxy 4213 * settings. This controls if and what Route headers will appear in 4214 * the REGISTER request of this account. The value is bitmask combination 4215 * of PJSUA_REG_USE_OUTBOUND_PROXY and PJSUA_REG_USE_ACC_PROXY bits. 4216 * If the value is set to 0, the REGISTER request will not use any proxy 4217 * (i.e. it will not have any Route headers). 4218 * 4219 * Default: 3 (PJSUA_REG_USE_OUTBOUND_PROXY | PJSUA_REG_USE_ACC_PROXY) 4220 */ 4221 unsigned reg_use_proxy; 4222 4223 #if defined(PJMEDIA_STREAM_ENABLE_KA) && (PJMEDIA_STREAM_ENABLE_KA != 0) 4224 /** 4225 * Specify whether stream keep-alive and NAT hole punching with 4226 * non-codec-VAD mechanism (see @ref PJMEDIA_STREAM_ENABLE_KA) is enabled 4227 * for this account. 4228 * 4229 * Default: PJ_FALSE (disabled) 4230 */ 4231 pj_bool_t use_stream_ka; 4232 4233 /** 4234 * Specify the keepalive configuration for stream. 4235 * 4236 * Default: see #pjmedia_stream_ka_config 4237 */ 4238 pjmedia_stream_ka_config stream_ka_cfg; 4239 #endif 4240 4241 /** 4242 * Specify how to offer call hold to remote peer. Please see the 4243 * documentation on #pjsua_call_hold_type for more info. 4244 * 4245 * Default: PJSUA_CALL_HOLD_TYPE_DEFAULT 4246 */ 4247 pjsua_call_hold_type call_hold_type; 4248 4249 4250 /** 4251 * Specify whether the account should register as soon as it is 4252 * added to the UA. Application can set this to PJ_FALSE and control 4253 * the registration manually with pjsua_acc_set_registration(). 4254 * 4255 * Default: PJ_TRUE 4256 */ 4257 pj_bool_t register_on_acc_add; 4258 4259 /** 4260 * Specify account configuration specific to IP address change used when 4261 * calling #pjsua_handle_ip_change(). 4262 */ 4263 pjsua_ip_change_acc_cfg ip_change_cfg; 4264 4265 /** 4266 * Enable RTP and RTCP multiplexing. 4267 */ 4268 pj_bool_t enable_rtcp_mux; 4269 4270 /** 4271 * RTCP Feedback configuration. 4272 */ 4273 pjmedia_rtcp_fb_setting rtcp_fb_cfg; 4274 4275 } pjsua_acc_config; 4276 4277 4278 /** 4279 * Initialize ICE config from a media config. If the \a pool argument 4280 * is NULL, a simple memcpy() will be used. 4281 * 4282 * @param pool Memory to duplicate strings. 4283 * @param dst Destination config. 4284 * @param src Source config. 4285 */ 4286 PJ_DECL(void) pjsua_ice_config_from_media_config(pj_pool_t *pool, 4287 pjsua_ice_config *dst, 4288 const pjsua_media_config *src); 4289 4290 /** 4291 * Clone. If the \a pool argument is NULL, a simple memcpy() will be used. 4292 * 4293 * @param pool Memory to duplicate strings. 4294 * @param dst Destination config. 4295 * @param src Source config. 4296 */ 4297 PJ_DECL(void) pjsua_ice_config_dup( pj_pool_t *pool, 4298 pjsua_ice_config *dst, 4299 const pjsua_ice_config *src); 4300 4301 /** 4302 * Initialize TURN config from a media config. If the \a pool argument 4303 * is NULL, a simple memcpy() will be used. 4304 * 4305 * @param pool Memory to duplicate strings. 4306 * @param dst Destination config. 4307 * @param src Source config. 4308 */ 4309 PJ_DECL(void) pjsua_turn_config_from_media_config(pj_pool_t *pool, 4310 pjsua_turn_config *dst, 4311 const pjsua_media_config *src); 4312 4313 /** 4314 * Clone. If the \a pool argument is NULL, a simple memcpy() will be used. 4315 * 4316 * @param pool Memory to duplicate strings. 4317 * @param dst Destination config. 4318 * @param src Source config. 4319 */ 4320 PJ_DECL(void) pjsua_turn_config_dup(pj_pool_t *pool, 4321 pjsua_turn_config *dst, 4322 const pjsua_turn_config *src); 4323 4324 4325 /** 4326 * Call this function to initialize SRTP config with default values. 4327 * 4328 * @param cfg The SRTP config to be initialized. 4329 */ 4330 PJ_DECL(void) pjsua_srtp_opt_default(pjsua_srtp_opt *cfg); 4331 4332 4333 /** 4334 * Duplicate SRTP transport setting. If the \a pool argument is NULL, 4335 * a simple memcpy() will be used. 4336 * 4337 * @param pool Memory to duplicate strings. 4338 * @param dst Destination setting. 4339 * @param src Source setting. 4340 * @param check_str If set to TRUE, the function will check if strings 4341 * are identical before copying. Identical strings 4342 * will not be duplicated. 4343 * If set to FALSE, all strings will be duplicated. 4344 */ 4345 PJ_DECL(void) pjsua_srtp_opt_dup(pj_pool_t *pool, pjsua_srtp_opt *dst, 4346 const pjsua_srtp_opt *src, 4347 pj_bool_t check_str); 4348 4349 4350 /** 4351 * Call this function to initialize account config with default values. 4352 * 4353 * @param cfg The account config to be initialized. 4354 */ 4355 PJ_DECL(void) pjsua_acc_config_default(pjsua_acc_config *cfg); 4356 4357 4358 /** 4359 * Duplicate account config. 4360 * 4361 * @param pool Pool to be used for duplicating the config. 4362 * @param dst Destination configuration. 4363 * @param src Source configuration. 4364 */ 4365 PJ_DECL(void) pjsua_acc_config_dup(pj_pool_t *pool, 4366 pjsua_acc_config *dst, 4367 const pjsua_acc_config *src); 4368 4369 4370 /** 4371 * Account info. Application can query account info by calling 4372 * #pjsua_acc_get_info(). 4373 */ 4374 typedef struct pjsua_acc_info 4375 { 4376 /** 4377 * The account ID. 4378 */ 4379 pjsua_acc_id id; 4380 4381 /** 4382 * Flag to indicate whether this is the default account. 4383 */ 4384 pj_bool_t is_default; 4385 4386 /** 4387 * Account URI 4388 */ 4389 pj_str_t acc_uri; 4390 4391 /** 4392 * Flag to tell whether this account has registration setting 4393 * (reg_uri is not empty). 4394 */ 4395 pj_bool_t has_registration; 4396 4397 /** 4398 * An up to date expiration interval for account registration session, 4399 * PJSIP_EXPIRES_NOT_SPECIFIED if the account doesn't have reg session. 4400 */ 4401 unsigned expires; 4402 4403 /** 4404 * Last registration status code. If status code is zero, the account 4405 * is currently not registered. Any other value indicates the SIP 4406 * status code of the registration. 4407 */ 4408 pjsip_status_code status; 4409 4410 /** 4411 * Last registration error code. When the status field contains a SIP 4412 * status code that indicates a registration failure, last registration 4413 * error code contains the error code that causes the failure. In any 4414 * other case, its value is zero. 4415 */ 4416 pj_status_t reg_last_err; 4417 4418 /** 4419 * String describing the registration status. 4420 */ 4421 pj_str_t status_text; 4422 4423 /** 4424 * Presence online status for this account. 4425 */ 4426 pj_bool_t online_status; 4427 4428 /** 4429 * Presence online status text. 4430 */ 4431 pj_str_t online_status_text; 4432 4433 /** 4434 * Extended RPID online status information. 4435 */ 4436 pjrpid_element rpid; 4437 4438 /** 4439 * Buffer that is used internally to store the status text. 4440 */ 4441 char buf_[PJ_ERR_MSG_SIZE]; 4442 4443 } pjsua_acc_info; 4444 4445 4446 4447 /** 4448 * Get number of current accounts. 4449 * 4450 * @return Current number of accounts. 4451 */ 4452 PJ_DECL(unsigned) pjsua_acc_get_count(void); 4453 4454 4455 /** 4456 * Check if the specified account ID is valid. 4457 * 4458 * @param acc_id Account ID to check. 4459 * 4460 * @return Non-zero if account ID is valid. 4461 */ 4462 PJ_DECL(pj_bool_t) pjsua_acc_is_valid(pjsua_acc_id acc_id); 4463 4464 4465 /** 4466 * Set default account to be used when incoming and outgoing 4467 * requests doesn't match any accounts. 4468 * 4469 * @param acc_id The account ID to be used as default. 4470 * 4471 * @return PJ_SUCCESS on success. 4472 */ 4473 PJ_DECL(pj_status_t) pjsua_acc_set_default(pjsua_acc_id acc_id); 4474 4475 4476 /** 4477 * Get default account to be used when receiving incoming requests (calls), 4478 * when the destination of the incoming call doesn't match any other 4479 * accounts. 4480 * 4481 * @return The default account ID, or PJSUA_INVALID_ID if no 4482 * default account is configured. 4483 */ 4484 PJ_DECL(pjsua_acc_id) pjsua_acc_get_default(void); 4485 4486 4487 /** 4488 * Add a new account to pjsua. PJSUA must have been initialized (with 4489 * #pjsua_init()) before calling this function. If registration is configured 4490 * for this account, this function would also start the SIP registration 4491 * session with the SIP registrar server. This SIP registration session 4492 * will be maintained internally by the library, and application doesn't 4493 * need to do anything to maintain the registration session. 4494 * 4495 * 4496 * @param acc_cfg Account configuration. 4497 * @param is_default If non-zero, this account will be set as the default 4498 * account. The default account will be used when sending 4499 * outgoing requests (e.g. making call) when no account is 4500 * specified, and when receiving incoming requests when the 4501 * request does not match any accounts. It is recommended 4502 * that default account is set to local/LAN account. 4503 * @param p_acc_id Pointer to receive account ID of the new account. 4504 * 4505 * @return PJ_SUCCESS on success, or the appropriate error code. 4506 */ 4507 PJ_DECL(pj_status_t) pjsua_acc_add(const pjsua_acc_config *acc_cfg, 4508 pj_bool_t is_default, 4509 pjsua_acc_id *p_acc_id); 4510 4511 4512 /** 4513 * Add a local account. A local account is used to identify local endpoint 4514 * instead of a specific user, and for this reason, a transport ID is needed 4515 * to obtain the local address information. 4516 * 4517 * @param tid Transport ID to generate account address. 4518 * @param is_default If non-zero, this account will be set as the default 4519 * account. The default account will be used when sending 4520 * outgoing requests (e.g. making call) when no account is 4521 * specified, and when receiving incoming requests when the 4522 * request does not match any accounts. It is recommended 4523 * that default account is set to local/LAN account. 4524 * @param p_acc_id Pointer to receive account ID of the new account. 4525 * 4526 * @return PJ_SUCCESS on success, or the appropriate error code. 4527 */ 4528 PJ_DECL(pj_status_t) pjsua_acc_add_local(pjsua_transport_id tid, 4529 pj_bool_t is_default, 4530 pjsua_acc_id *p_acc_id); 4531 4532 /** 4533 * Set arbitrary data to be associated with the account. 4534 * 4535 * @param acc_id The account ID. 4536 * @param user_data User/application data. 4537 * 4538 * @return PJ_SUCCESS on success, or the appropriate error code. 4539 */ 4540 PJ_DECL(pj_status_t) pjsua_acc_set_user_data(pjsua_acc_id acc_id, 4541 void *user_data); 4542 4543 4544 /** 4545 * Retrieve arbitrary data associated with the account. 4546 * 4547 * @param acc_id The account ID. 4548 * 4549 * @return The user data. In the case where the account ID is 4550 * not valid, NULL is returned. 4551 */ 4552 PJ_DECL(void*) pjsua_acc_get_user_data(pjsua_acc_id acc_id); 4553 4554 4555 /** 4556 * Delete an account. This will unregister the account from the SIP server, 4557 * if necessary, and terminate server side presence subscriptions associated 4558 * with this account. 4559 * 4560 * @param acc_id Id of the account to be deleted. 4561 * 4562 * @return PJ_SUCCESS on success, or the appropriate error code. 4563 */ 4564 PJ_DECL(pj_status_t) pjsua_acc_del(pjsua_acc_id acc_id); 4565 4566 4567 /** 4568 * Get current config for the account. This will copy current account setting 4569 * to the specified parameter. Note that all pointers in the settings will 4570 * point to the original settings in the account and application must not 4571 * modify the values in any way. Application must also take care that these 4572 * data is only valid until the account is destroyed. 4573 * 4574 * @param acc_id The account ID. 4575 * @param pool Pool to duplicate the config. 4576 * @param acc_cfg Structure to receive the settings. 4577 * 4578 * @return PJ_SUCCESS on success, or the appropriate error code. 4579 */ 4580 PJ_DECL(pj_status_t) pjsua_acc_get_config(pjsua_acc_id acc_id, 4581 pj_pool_t *pool, 4582 pjsua_acc_config *acc_cfg); 4583 4584 4585 /** 4586 * Modify account configuration setting. This function may trigger 4587 * unregistration (of old account setting) and re-registration (of the new 4588 * account setting), e.g: changing account ID, credential, registar, or 4589 * proxy setting. 4590 * 4591 * Note: 4592 * - when the new config triggers unregistration, the pjsua callback 4593 * on_reg_state()/on_reg_state2() for the unregistration will not be called 4594 * and any failure in the unregistration will be ignored, so if application 4595 * needs to be sure about the unregistration status, it should unregister 4596 * manually and wait for the callback before calling this function 4597 * - when the new config triggers re-registration and the re-registration 4598 * fails, the account setting will not be reverted back to the old setting 4599 * and the account will be in unregistered state. 4600 * 4601 * @param acc_id Id of the account to be modified. 4602 * @param acc_cfg New account configuration. 4603 * 4604 * @return PJ_SUCCESS on success, or the appropriate error code. 4605 */ 4606 PJ_DECL(pj_status_t) pjsua_acc_modify(pjsua_acc_id acc_id, 4607 const pjsua_acc_config *acc_cfg); 4608 4609 4610 /** 4611 * Modify account's presence status to be advertised to remote/presence 4612 * subscribers. This would trigger the sending of outgoing NOTIFY request 4613 * if there are server side presence subscription for this account, and/or 4614 * outgoing PUBLISH if presence publication is enabled for this account. 4615 * 4616 * @see pjsua_acc_set_online_status2() 4617 * 4618 * @param acc_id The account ID. 4619 * @param is_online True of false. 4620 * 4621 * @return PJ_SUCCESS on success, or the appropriate error code. 4622 */ 4623 PJ_DECL(pj_status_t) pjsua_acc_set_online_status(pjsua_acc_id acc_id, 4624 pj_bool_t is_online); 4625 4626 /** 4627 * Modify account's presence status to be advertised to remote/presence 4628 * subscribers. This would trigger the sending of outgoing NOTIFY request 4629 * if there are server side presence subscription for this account, and/or 4630 * outgoing PUBLISH if presence publication is enabled for this account. 4631 * 4632 * @see pjsua_acc_set_online_status() 4633 * 4634 * @param acc_id The account ID. 4635 * @param is_online True of false. 4636 * @param pr Extended information in subset of RPID format 4637 * which allows setting custom presence text. 4638 * 4639 * @return PJ_SUCCESS on success, or the appropriate error code. 4640 */ 4641 PJ_DECL(pj_status_t) pjsua_acc_set_online_status2(pjsua_acc_id acc_id, 4642 pj_bool_t is_online, 4643 const pjrpid_element *pr); 4644 4645 /** 4646 * Update registration or perform unregistration. If registration is 4647 * configured for this account, then initial SIP REGISTER will be sent 4648 * when the account is added with #pjsua_acc_add(). Application normally 4649 * only need to call this function if it wants to manually update the 4650 * registration or to unregister from the server. 4651 * 4652 * @param acc_id The account ID. 4653 * @param renew If renew argument is zero, this will start 4654 * unregistration process. 4655 * 4656 * @return PJ_SUCCESS on success, or the appropriate error code. 4657 */ 4658 PJ_DECL(pj_status_t) pjsua_acc_set_registration(pjsua_acc_id acc_id, 4659 pj_bool_t renew); 4660 4661 /** 4662 * Get information about the specified account. 4663 * 4664 * @param acc_id Account identification. 4665 * @param info Pointer to receive account information. 4666 * 4667 * @return PJ_SUCCESS on success, or the appropriate error code. 4668 */ 4669 PJ_DECL(pj_status_t) pjsua_acc_get_info(pjsua_acc_id acc_id, 4670 pjsua_acc_info *info); 4671 4672 4673 /** 4674 * Enumerate all account currently active in the library. This will fill 4675 * the array with the account Ids, and application can then query the 4676 * account information for each id with #pjsua_acc_get_info(). 4677 * 4678 * @see pjsua_acc_enum_info(). 4679 * 4680 * @param ids Array of account IDs to be initialized. 4681 * @param count In input, specifies the maximum number of elements. 4682 * On return, it contains the actual number of elements. 4683 * 4684 * @return PJ_SUCCESS on success, or the appropriate error code. 4685 */ 4686 PJ_DECL(pj_status_t) pjsua_enum_accs(pjsua_acc_id ids[], 4687 unsigned *count ); 4688 4689 4690 /** 4691 * Enumerate account informations. 4692 * 4693 * @param info Array of account infos to be initialized. 4694 * @param count In input, specifies the maximum number of elements. 4695 * On return, it contains the actual number of elements. 4696 * 4697 * @return PJ_SUCCESS on success, or the appropriate error code. 4698 */ 4699 PJ_DECL(pj_status_t) pjsua_acc_enum_info( pjsua_acc_info info[], 4700 unsigned *count ); 4701 4702 4703 /** 4704 * This is an internal function to find the most appropriate account to 4705 * used to reach to the specified URL. 4706 * 4707 * @param url The remote URL to reach. 4708 * 4709 * @return Account id. 4710 */ 4711 PJ_DECL(pjsua_acc_id) pjsua_acc_find_for_outgoing(const pj_str_t *url); 4712 4713 4714 /** 4715 * This is an internal function to find the most appropriate account to be 4716 * used to handle incoming calls. 4717 * 4718 * @param rdata The incoming request message. 4719 * 4720 * @return Account id. 4721 */ 4722 PJ_DECL(pjsua_acc_id) pjsua_acc_find_for_incoming(pjsip_rx_data *rdata); 4723 4724 4725 /** 4726 * Create arbitrary requests using the account. Application should only use 4727 * this function to create auxiliary requests outside dialog, such as 4728 * OPTIONS, and use the call or presence API to create dialog related 4729 * requests. 4730 * 4731 * @param acc_id The account ID. 4732 * @param method The SIP method of the request. 4733 * @param target Target URI. 4734 * @param p_tdata Pointer to receive the request. 4735 * 4736 * @return PJ_SUCCESS or the error code. 4737 */ 4738 PJ_DECL(pj_status_t) pjsua_acc_create_request(pjsua_acc_id acc_id, 4739 const pjsip_method *method, 4740 const pj_str_t *target, 4741 pjsip_tx_data **p_tdata); 4742 4743 4744 /** 4745 * Create a suitable Contact header value, based on the specified target URI 4746 * for the specified account. 4747 * 4748 * @param pool Pool to allocate memory for the string. 4749 * @param contact The string where the Contact will be stored. 4750 * @param acc_id Account ID. 4751 * @param uri Destination URI of the request. 4752 * 4753 * @return PJ_SUCCESS on success, other on error. 4754 */ 4755 PJ_DECL(pj_status_t) pjsua_acc_create_uac_contact( pj_pool_t *pool, 4756 pj_str_t *contact, 4757 pjsua_acc_id acc_id, 4758 const pj_str_t *uri); 4759 4760 4761 4762 /** 4763 * Create a suitable Contact header value, based on the information in the 4764 * incoming request. 4765 * 4766 * @param pool Pool to allocate memory for the string. 4767 * @param contact The string where the Contact will be stored. 4768 * @param acc_id Account ID. 4769 * @param rdata Incoming request. 4770 * 4771 * @return PJ_SUCCESS on success, other on error. 4772 */ 4773 PJ_DECL(pj_status_t) pjsua_acc_create_uas_contact( pj_pool_t *pool, 4774 pj_str_t *contact, 4775 pjsua_acc_id acc_id, 4776 pjsip_rx_data *rdata ); 4777 4778 4779 /** 4780 * Lock/bind this account to a specific transport/listener. Normally 4781 * application shouldn't need to do this, as transports will be selected 4782 * automatically by the stack according to the destination. 4783 * 4784 * When account is locked/bound to a specific transport, all outgoing 4785 * requests from this account will use the specified transport (this 4786 * includes SIP registration, dialog (call and event subscription), and 4787 * out-of-dialog requests such as MESSAGE). 4788 * 4789 * Note that transport_id may be specified in pjsua_acc_config too. 4790 * 4791 * @param acc_id The account ID. 4792 * @param tp_id The transport ID. 4793 * 4794 * @return PJ_SUCCESS on success. 4795 */ 4796 PJ_DECL(pj_status_t) pjsua_acc_set_transport(pjsua_acc_id acc_id, 4797 pjsua_transport_id tp_id); 4798 4799 4800 /** 4801 * @} 4802 */ 4803 4804 4805 /***************************************************************************** 4806 * CALLS API 4807 */ 4808 4809 4810 /** 4811 * @defgroup PJSUA_LIB_CALL PJSUA-API Calls Management 4812 * @ingroup PJSUA_LIB 4813 * @brief Call manipulation. 4814 * @{ 4815 */ 4816 4817 /** 4818 * Maximum simultaneous calls. 4819 */ 4820 #ifndef PJSUA_MAX_CALLS 4821 # define PJSUA_MAX_CALLS 4 4822 #endif 4823 4824 /** 4825 * Maximum active video windows 4826 */ 4827 #ifndef PJSUA_MAX_VID_WINS 4828 # define PJSUA_MAX_VID_WINS 16 4829 #endif 4830 4831 /** 4832 * Video window ID. 4833 */ 4834 typedef int pjsua_vid_win_id; 4835 4836 4837 /** 4838 * This enumeration specifies the media status of a call, and it's part 4839 * of pjsua_call_info structure. 4840 */ 4841 typedef enum pjsua_call_media_status 4842 { 4843 /** 4844 * Call currently has no media, or the media is not used. 4845 */ 4846 PJSUA_CALL_MEDIA_NONE, 4847 4848 /** 4849 * The media is active 4850 */ 4851 PJSUA_CALL_MEDIA_ACTIVE, 4852 4853 /** 4854 * The media is currently put on hold by local endpoint 4855 */ 4856 PJSUA_CALL_MEDIA_LOCAL_HOLD, 4857 4858 /** 4859 * The media is currently put on hold by remote endpoint 4860 */ 4861 PJSUA_CALL_MEDIA_REMOTE_HOLD, 4862 4863 /** 4864 * The media has reported error (e.g. ICE negotiation) 4865 */ 4866 PJSUA_CALL_MEDIA_ERROR 4867 4868 } pjsua_call_media_status; 4869 4870 4871 /** 4872 * Enumeration of video keyframe request methods. Keyframe request is 4873 * triggered by decoder, usually when the incoming video stream cannot 4874 * be decoded properly due to missing video keyframe. 4875 */ 4876 typedef enum pjsua_vid_req_keyframe_method 4877 { 4878 /** 4879 * Requesting keyframe via SIP INFO message. Note that incoming keyframe 4880 * request via SIP INFO will always be handled even if this flag is unset. 4881 */ 4882 PJSUA_VID_REQ_KEYFRAME_SIP_INFO = 1, 4883 4884 /** 4885 * Requesting keyframe via Picture Loss Indication of RTCP feedback. 4886 */ 4887 PJSUA_VID_REQ_KEYFRAME_RTCP_PLI = 2 4888 4889 } pjsua_vid_req_keyframe_method; 4890 4891 4892 /** 4893 * Call media information. 4894 */ 4895 typedef struct pjsua_call_media_info 4896 { 4897 /** Media index in SDP. */ 4898 unsigned index; 4899 4900 /** Media type. */ 4901 pjmedia_type type; 4902 4903 /** Media direction. */ 4904 pjmedia_dir dir; 4905 4906 /** Call media status. */ 4907 pjsua_call_media_status status; 4908 4909 /** The specific media stream info. */ 4910 union { 4911 /** Audio stream */ 4912 struct { 4913 /** The conference port number for the call. */ 4914 pjsua_conf_port_id conf_slot; 4915 } aud; 4916 4917 /** Video stream */ 4918 struct { 4919 /** 4920 * The window id for incoming video, if any, or 4921 * PJSUA_INVALID_ID. 4922 */ 4923 pjsua_vid_win_id win_in; 4924 4925 /** 4926 * The video conference port number for the call in decoding 4927 * direction. 4928 */ 4929 pjsua_conf_port_id dec_slot; 4930 4931 /** 4932 * The video conference port number for the call in encoding 4933 * direction. 4934 */ 4935 pjsua_conf_port_id enc_slot; 4936 4937 /** 4938 * The video capture device for outgoing transmission, 4939 * if any, or PJMEDIA_VID_INVALID_DEV 4940 */ 4941 pjmedia_vid_dev_index cap_dev; 4942 4943 } vid; 4944 } stream; 4945 4946 } pjsua_call_media_info; 4947 4948 4949 /** 4950 * This structure describes the information and current status of a call. 4951 */ 4952 typedef struct pjsua_call_info 4953 { 4954 /** Call identification. */ 4955 pjsua_call_id id; 4956 4957 /** Initial call role (UAC == caller) */ 4958 pjsip_role_e role; 4959 4960 /** The account ID where this call belongs. */ 4961 pjsua_acc_id acc_id; 4962 4963 /** Local URI */ 4964 pj_str_t local_info; 4965 4966 /** Local Contact */ 4967 pj_str_t local_contact; 4968 4969 /** Remote URI */ 4970 pj_str_t remote_info; 4971 4972 /** Remote contact */ 4973 pj_str_t remote_contact; 4974 4975 /** Dialog Call-ID string. */ 4976 pj_str_t call_id; 4977 4978 /** Call setting */ 4979 pjsua_call_setting setting; 4980 4981 /** Call state */ 4982 pjsip_inv_state state; 4983 4984 /** Text describing the state */ 4985 pj_str_t state_text; 4986 4987 /** Last status code heard, which can be used as cause code */ 4988 pjsip_status_code last_status; 4989 4990 /** The reason phrase describing the status. */ 4991 pj_str_t last_status_text; 4992 4993 /** Media status of the default audio stream. Default audio stream 4994 * is chosen according to this priority: 4995 * 1. enabled, i.e: SDP media port not zero 4996 * 2. transport protocol in the SDP matching account config's 4997 * secure media transport usage (\a use_srtp field). 4998 * 3. active, i.e: SDP media direction is not "inactive" 4999 * 4. media order (according to the SDP). 5000 */ 5001 pjsua_call_media_status media_status; 5002 5003 /** Media direction of the default audio stream. 5004 * See \a media_status above on how the default is chosen. 5005 */ 5006 pjmedia_dir media_dir; 5007 5008 /** The conference port number for the default audio stream. 5009 * See \a media_status above on how the default is chosen. 5010 */ 5011 pjsua_conf_port_id conf_slot; 5012 5013 /** Number of active media info in this call. */ 5014 unsigned media_cnt; 5015 5016 /** Array of active media information. */ 5017 pjsua_call_media_info media[PJMEDIA_MAX_SDP_MEDIA]; 5018 5019 /** Number of provisional media info in this call. */ 5020 unsigned prov_media_cnt; 5021 5022 /** Array of provisional media information. This contains the media info 5023 * in the provisioning state, that is when the media session is being 5024 * created/updated (SDP offer/answer is on progress). 5025 */ 5026 pjsua_call_media_info prov_media[PJMEDIA_MAX_SDP_MEDIA]; 5027 5028 /** Up-to-date call connected duration (zero when call is not 5029 * established) 5030 */ 5031 pj_time_val connect_duration; 5032 5033 /** Total call duration, including set-up time */ 5034 pj_time_val total_duration; 5035 5036 /** Flag if remote was SDP offerer */ 5037 pj_bool_t rem_offerer; 5038 5039 /** Number of audio streams offered by remote */ 5040 unsigned rem_aud_cnt; 5041 5042 /** Number of video streams offered by remote */ 5043 unsigned rem_vid_cnt; 5044 5045 /** Internal */ 5046 struct { 5047 char local_info[PJSIP_MAX_URL_SIZE]; 5048 char local_contact[PJSIP_MAX_URL_SIZE]; 5049 char remote_info[PJSIP_MAX_URL_SIZE]; 5050 char remote_contact[PJSIP_MAX_URL_SIZE]; 5051 char call_id[128]; 5052 char last_status_text[128]; 5053 } buf_; 5054 5055 } pjsua_call_info; 5056 5057 /** 5058 * Flags to be given to various call APIs. More than one flags may be 5059 * specified by bitmasking them. 5060 */ 5061 typedef enum pjsua_call_flag 5062 { 5063 /** 5064 * When the call is being put on hold, specify this flag to unhold it. 5065 * This flag is only valid for #pjsua_call_reinvite() and 5066 * #pjsua_call_update(). Note: for compatibility reason, this flag must 5067 * have value of 1 because previously the unhold option is specified as 5068 * boolean value. 5069 */ 5070 PJSUA_CALL_UNHOLD = 1, 5071 5072 /** 5073 * Update the local invite session's contact with the contact URI from 5074 * the account. This flag is only valid for #pjsua_call_set_hold2(), 5075 * #pjsua_call_reinvite() and #pjsua_call_update(). This flag is useful 5076 * in IP address change situation, after the local account's Contact has 5077 * been updated (typically with re-registration) use this flag to update 5078 * the invite session with the new Contact and to inform this new Contact 5079 * to the remote peer with the outgoing re-INVITE or UPDATE. 5080 */ 5081 PJSUA_CALL_UPDATE_CONTACT = 2, 5082 5083 /** 5084 * Include SDP "m=" line with port set to zero for each disabled media 5085 * (i.e when aud_cnt or vid_cnt is set to zero). This flag is only valid 5086 * for #pjsua_call_make_call(), #pjsua_call_reinvite(), and 5087 * #pjsua_call_update(). Note that even this flag is applicable in 5088 * #pjsua_call_reinvite() and #pjsua_call_update(), it will only take 5089 * effect when the re-INVITE/UPDATE operation regenerates SDP offer, 5090 * such as changing audio or video count in the call setting. 5091 */ 5092 PJSUA_CALL_INCLUDE_DISABLED_MEDIA = 4, 5093 5094 /** 5095 * Do not send SDP when sending INVITE or UPDATE. This flag is only valid 5096 * for #pjsua_call_make_call(), #pjsua_call_reinvite()/reinvite2(), or 5097 * #pjsua_call_update()/update2(). For re-invite/update, specifying 5098 * PJSUA_CALL_UNHOLD will take precedence over this flag. 5099 */ 5100 PJSUA_CALL_NO_SDP_OFFER = 8, 5101 5102 /** 5103 * Deinitialize and recreate media, including media transport. This flag 5104 * is useful in IP address change situation, if the media transport 5105 * address (or address family) changes, for example during IPv4/IPv6 5106 * network handover. 5107 * This flag is only valid for #pjsua_call_reinvite()/reinvite2(), or 5108 * #pjsua_call_update()/update2(). 5109 * 5110 * Warning: If the re-INVITE/UPDATE fails, the old media will not be 5111 * reverted. 5112 */ 5113 PJSUA_CALL_REINIT_MEDIA = 16, 5114 5115 /** 5116 * Update the local invite session's Via with the via address from 5117 * the account. This flag is only valid for #pjsua_call_set_hold2(), 5118 * #pjsua_call_reinvite() and #pjsua_call_update(). Similar to 5119 * the flag PJSUA_CALL_UPDATE_CONTACT above, this flag is useful 5120 * in IP address change situation, after the local account's Via has 5121 * been updated (typically with re-registration). 5122 */ 5123 PJSUA_CALL_UPDATE_VIA = 32, 5124 5125 /** 5126 * Update dialog target to URI specified in pjsua_msg_data.target_uri. 5127 * This flag is only valid for pjsua_call_set_hold(), 5128 * pjsua_call_reinvite(), and pjsua_call_update(). This flag can be 5129 * useful in IP address change scenario where IP version has been changed 5130 * and application needs to update target IP address. 5131 */ 5132 PJSUA_CALL_UPDATE_TARGET = 64 5133 5134 } pjsua_call_flag; 5135 5136 /** 5137 * This enumeration represents video stream operation on a call. 5138 * See also #pjsua_call_vid_strm_op_param for further info. 5139 */ 5140 typedef enum pjsua_call_vid_strm_op 5141 { 5142 /** 5143 * No operation 5144 */ 5145 PJSUA_CALL_VID_STRM_NO_OP, 5146 5147 /** 5148 * Add a new video stream. This will add a new m=video line to 5149 * the media, regardless of whether existing video is/are present 5150 * or not. This will cause re-INVITE or UPDATE to be sent to remote 5151 * party. 5152 */ 5153 PJSUA_CALL_VID_STRM_ADD, 5154 5155 /** 5156 * Remove/disable an existing video stream. This will 5157 * cause re-INVITE or UPDATE to be sent to remote party. 5158 */ 5159 PJSUA_CALL_VID_STRM_REMOVE, 5160 5161 /** 5162 * Change direction of a video stream. This operation can be used 5163 * to activate or deactivate an existing video media. This will 5164 * cause re-INVITE or UPDATE to be sent to remote party. 5165 */ 5166 PJSUA_CALL_VID_STRM_CHANGE_DIR, 5167 5168 /** 5169 * Change capture device of a video stream. This will not send 5170 * re-INVITE or UPDATE to remote party. 5171 */ 5172 PJSUA_CALL_VID_STRM_CHANGE_CAP_DEV, 5173 5174 /** 5175 * Start transmitting video stream. This will cause previously 5176 * stopped stream to start transmitting again. Note that no 5177 * re-INVITE/UPDATE is to be transmitted to remote since this 5178 * operation only operates on local stream. 5179 */ 5180 PJSUA_CALL_VID_STRM_START_TRANSMIT, 5181 5182 /** 5183 * Stop transmitting video stream. This will cause the stream to 5184 * be paused in TX direction, causing it to stop sending any video 5185 * packets. No re-INVITE/UPDATE is to be transmitted to remote 5186 * with this operation. 5187 */ 5188 PJSUA_CALL_VID_STRM_STOP_TRANSMIT, 5189 5190 /** 5191 * Send keyframe in the video stream. This will force the stream to 5192 * generate and send video keyframe as soon as possible. No 5193 * re-INVITE/UPDATE is to be transmitted to remote with this operation. 5194 */ 5195 PJSUA_CALL_VID_STRM_SEND_KEYFRAME 5196 5197 } pjsua_call_vid_strm_op; 5198 5199 5200 /** 5201 * Parameters for video stream operation on a call. Application should 5202 * use #pjsua_call_vid_strm_op_param_default() to initialize this structure 5203 * with its default values. 5204 */ 5205 typedef struct pjsua_call_vid_strm_op_param 5206 { 5207 /** 5208 * Specify the media stream index. This can be set to -1 to denote 5209 * the default video stream in the call, which is the first active 5210 * video stream or any first video stream if none is active. 5211 * 5212 * This field is valid for all video stream operations, except 5213 * PJSUA_CALL_VID_STRM_ADD. 5214 * 5215 * Default: -1 (first active video stream, or any first video stream 5216 * if none is active) 5217 */ 5218 int med_idx; 5219 5220 /** 5221 * Specify the media stream direction. 5222 * 5223 * This field is valid for the following video stream operations: 5224 * PJSUA_CALL_VID_STRM_ADD and PJSUA_CALL_VID_STRM_CHANGE_DIR. 5225 * 5226 * Default: PJMEDIA_DIR_ENCODING_DECODING 5227 */ 5228 pjmedia_dir dir; 5229 5230 /** 5231 * Specify the video capture device ID. This can be set to 5232 * PJMEDIA_VID_DEFAULT_CAPTURE_DEV to specify the default capture 5233 * device as configured in the account. 5234 * 5235 * This field is valid for the following video stream operations: 5236 * PJSUA_CALL_VID_STRM_ADD and PJSUA_CALL_VID_STRM_CHANGE_CAP_DEV. 5237 * 5238 * Default: PJMEDIA_VID_DEFAULT_CAPTURE_DEV. 5239 */ 5240 pjmedia_vid_dev_index cap_dev; 5241 5242 } pjsua_call_vid_strm_op_param; 5243 5244 5245 /** 5246 * Specify the default signal duration when sending DTMF using SIP INFO. 5247 * 5248 * Default is 160 5249 */ 5250 #ifndef PJSUA_CALL_SEND_DTMF_DURATION_DEFAULT 5251 # define PJSUA_CALL_SEND_DTMF_DURATION_DEFAULT 160 5252 #endif 5253 5254 5255 /** 5256 * Parameters for sending DTMF. Application should use 5257 * #pjsua_call_send_dtmf_param_default() to initialize this structure 5258 * with its default values. 5259 */ 5260 typedef struct pjsua_call_send_dtmf_param 5261 { 5262 /** 5263 * The method used to send DTMF. 5264 * 5265 * Default: PJSUA_DTMF_METHOD_RFC2833 5266 */ 5267 pjsua_dtmf_method method; 5268 5269 /** 5270 * The signal duration used for the DTMF. 5271 * 5272 * Default: PJSUA_CALL_SEND_DTMF_DURATION_DEFAULT 5273 */ 5274 unsigned duration; 5275 5276 /** 5277 * The DTMF digits to be sent. 5278 */ 5279 pj_str_t digits; 5280 5281 } pjsua_call_send_dtmf_param; 5282 5283 5284 /** 5285 * Initialize call settings. 5286 * 5287 * @param opt The call setting to be initialized. 5288 */ 5289 PJ_DECL(void) pjsua_call_setting_default(pjsua_call_setting *opt); 5290 5291 5292 /** 5293 * Initialize video stream operation param with default values. 5294 * 5295 * @param param The video stream operation param to be initialized. 5296 */ 5297 PJ_DECL(void) 5298 pjsua_call_vid_strm_op_param_default(pjsua_call_vid_strm_op_param *param); 5299 5300 5301 /** 5302 * Initialize send DTMF param with default values. 5303 * 5304 * @param param The send DTMF param to be initialized. 5305 */ 5306 PJ_DECL(void) 5307 pjsua_call_send_dtmf_param_default(pjsua_call_send_dtmf_param *param); 5308 5309 5310 /** 5311 * Get maximum number of calls configured in pjsua. 5312 * 5313 * @return Maximum number of calls configured. 5314 */ 5315 PJ_DECL(unsigned) pjsua_call_get_max_count(void); 5316 5317 /** 5318 * Get the number of current calls. The number includes active calls 5319 * (pjsua_call_is_active(call_id) == PJ_TRUE), as well as calls that 5320 * are no longer active but still in the process of hanging up. 5321 * 5322 * @return Number of current calls. 5323 */ 5324 PJ_DECL(unsigned) pjsua_call_get_count(void); 5325 5326 /** 5327 * Enumerate all active calls. Application may then query the information and 5328 * state of each call by calling #pjsua_call_get_info(). 5329 * 5330 * @param ids Array of account IDs to be initialized. 5331 * @param count In input, specifies the maximum number of elements. 5332 * On return, it contains the actual number of elements. 5333 * 5334 * @return PJ_SUCCESS on success, or the appropriate error code. 5335 */ 5336 PJ_DECL(pj_status_t) pjsua_enum_calls(pjsua_call_id ids[], 5337 unsigned *count); 5338 5339 5340 /** 5341 * Make outgoing call to the specified URI using the specified account. 5342 * 5343 * @param acc_id The account to be used. 5344 * @param dst_uri URI to be put in the To header (normally is the same 5345 * as the target URI). 5346 * @param opt Optional call setting. This should be initialized 5347 * using #pjsua_call_setting_default(). 5348 * @param user_data Arbitrary user data to be attached to the call, and 5349 * can be retrieved later. 5350 * @param msg_data Optional headers etc to be added to outgoing INVITE 5351 * request, or NULL if no custom header is desired. 5352 * @param p_call_id Pointer to receive call identification. 5353 * 5354 * @return PJ_SUCCESS on success, or the appropriate error code. 5355 */ 5356 PJ_DECL(pj_status_t) pjsua_call_make_call(pjsua_acc_id acc_id, 5357 const pj_str_t *dst_uri, 5358 const pjsua_call_setting *opt, 5359 void *user_data, 5360 const pjsua_msg_data *msg_data, 5361 pjsua_call_id *p_call_id); 5362 5363 5364 /** 5365 * Check if the specified call has active INVITE session and the INVITE 5366 * session has not been disconnected. 5367 * 5368 * @param call_id Call identification. 5369 * 5370 * @return Non-zero if call is active. 5371 */ 5372 PJ_DECL(pj_bool_t) pjsua_call_is_active(pjsua_call_id call_id); 5373 5374 5375 /** 5376 * Check if call has an active media session. 5377 * 5378 * @param call_id Call identification. 5379 * 5380 * @return Non-zero if yes. 5381 */ 5382 PJ_DECL(pj_bool_t) pjsua_call_has_media(pjsua_call_id call_id); 5383 5384 5385 /** 5386 * Get the conference port identification associated with the call. 5387 * 5388 * @param call_id Call identification. 5389 * 5390 * @return Conference port ID, or PJSUA_INVALID_ID when the 5391 * media has not been established or is not active. 5392 */ 5393 PJ_DECL(pjsua_conf_port_id) pjsua_call_get_conf_port(pjsua_call_id call_id); 5394 5395 5396 /** 5397 * Get the video window associated with the call. Note that this function 5398 * will only evaluate the first video stream in the call, to query any other 5399 * video stream, use pjsua_call_get_info(). 5400 * 5401 * @param call_id Call identification. 5402 * 5403 * @return Video window, or PJSUA_INVALID_ID when the 5404 * media has not been established or is not active. 5405 */ 5406 PJ_DECL(pjsua_vid_win_id) pjsua_call_get_vid_win(pjsua_call_id call_id); 5407 5408 5409 /** 5410 * Get the video conference port identification associated with the call. 5411 * Note that this function will only evaluate the first video stream in 5412 * the call, to query any other video stream, use pjsua_call_get_info(). 5413 * 5414 * @param call_id Call identification. 5415 * @param dir Port direction to be queried. Valid values are 5416 * PJMEDIA_DIR_ENCODING and PJMEDIA_DIR_DECODING only. 5417 * 5418 * @return Conference port ID, or PJSUA_INVALID_ID when the 5419 * media has not been established or is not active. 5420 */ 5421 PJ_DECL(pjsua_conf_port_id) pjsua_call_get_vid_conf_port( 5422 pjsua_call_id call_id, 5423 pjmedia_dir dir); 5424 5425 /** 5426 * Obtain detail information about the specified call. 5427 * 5428 * @param call_id Call identification. 5429 * @param info Call info to be initialized. 5430 * 5431 * @return PJ_SUCCESS on success, or the appropriate error code. 5432 */ 5433 PJ_DECL(pj_status_t) pjsua_call_get_info(pjsua_call_id call_id, 5434 pjsua_call_info *info); 5435 5436 /** 5437 * Check if remote peer support the specified capability. 5438 * 5439 * @param call_id Call identification. 5440 * @param htype The header type to be checked, which value may be: 5441 * - PJSIP_H_ACCEPT 5442 * - PJSIP_H_ALLOW 5443 * - PJSIP_H_SUPPORTED 5444 * @param hname If htype specifies PJSIP_H_OTHER, then the header 5445 * name must be supplied in this argument. Otherwise the 5446 * value must be set to NULL. 5447 * @param token The capability token to check. For example, if \a 5448 * htype is PJSIP_H_ALLOW, then \a token specifies the 5449 * method names; if \a htype is PJSIP_H_SUPPORTED, then 5450 * \a token specifies the extension names such as 5451 * "100rel". 5452 * 5453 * @return PJSIP_DIALOG_CAP_SUPPORTED if the specified capability 5454 * is explicitly supported, see @pjsip_dialog_cap_status 5455 * for more info. 5456 */ 5457 PJ_DECL(pjsip_dialog_cap_status) pjsua_call_remote_has_cap( 5458 pjsua_call_id call_id, 5459 int htype, 5460 const pj_str_t *hname, 5461 const pj_str_t *token); 5462 5463 /** 5464 * Attach application specific data to the call. Application can then 5465 * inspect this data by calling #pjsua_call_get_user_data(). 5466 * 5467 * @param call_id Call identification. 5468 * @param user_data Arbitrary data to be attached to the call. 5469 * 5470 * @return The user data. 5471 */ 5472 PJ_DECL(pj_status_t) pjsua_call_set_user_data(pjsua_call_id call_id, 5473 void *user_data); 5474 5475 5476 /** 5477 * Get user data attached to the call, which has been previously set with 5478 * #pjsua_call_set_user_data(). 5479 * 5480 * @param call_id Call identification. 5481 * 5482 * @return The user data. 5483 */ 5484 PJ_DECL(void*) pjsua_call_get_user_data(pjsua_call_id call_id); 5485 5486 5487 /** 5488 * Get the NAT type of remote's endpoint. This is a proprietary feature 5489 * of PJSUA-LIB which sends its NAT type in the SDP when \a nat_type_in_sdp 5490 * is set in #pjsua_config. 5491 * 5492 * This function can only be called after SDP has been received from remote, 5493 * which means for incoming call, this function can be called as soon as 5494 * call is received as long as incoming call contains SDP, and for outgoing 5495 * call, this function can be called only after SDP is received (normally in 5496 * 200/OK response to INVITE). As a general case, application should call 5497 * this function after or in \a on_call_media_state() callback. 5498 * 5499 * @param call_id Call identification. 5500 * @param p_type Pointer to store the NAT type. Application can then 5501 * retrieve the string description of the NAT type 5502 * by calling pj_stun_get_nat_name(). 5503 * 5504 * @return PJ_SUCCESS on success. 5505 * 5506 * @see pjsua_get_nat_type(), nat_type_in_sdp 5507 */ 5508 PJ_DECL(pj_status_t) pjsua_call_get_rem_nat_type(pjsua_call_id call_id, 5509 pj_stun_nat_type *p_type); 5510 5511 /** 5512 * Send response to incoming INVITE request. Depending on the status 5513 * code specified as parameter, this function may send provisional 5514 * response, establish the call, or terminate the call. See also 5515 * #pjsua_call_answer2(). 5516 * 5517 * @param call_id Incoming call identification. 5518 * @param code Status code, (100-699). 5519 * @param reason Optional reason phrase. If NULL, default text 5520 * will be used. 5521 * @param msg_data Optional list of headers etc to be added to outgoing 5522 * response message. Note that this message data will 5523 * be persistent in all next answers/responses for this 5524 * INVITE request. 5525 * 5526 * @return PJ_SUCCESS on success, or the appropriate error code. 5527 */ 5528 PJ_DECL(pj_status_t) pjsua_call_answer(pjsua_call_id call_id, 5529 unsigned code, 5530 const pj_str_t *reason, 5531 const pjsua_msg_data *msg_data); 5532 5533 5534 /** 5535 * Send response to incoming INVITE request with call setting param. 5536 * Depending on the status code specified as parameter, this function may 5537 * send provisional response, establish the call, or terminate the call. 5538 * Notes about call setting: 5539 * - if call setting is changed in the subsequent call to this function, 5540 * only the first call setting supplied will applied. So normally 5541 * application will not supply call setting before getting confirmation 5542 * from the user. 5543 * - if no call setting is supplied when SDP has to be sent, i.e: answer 5544 * with status code 183 or 2xx, the default call setting will be used, 5545 * check #pjsua_call_setting for its default values. 5546 * 5547 * @param call_id Incoming call identification. 5548 * @param opt Optional call setting. 5549 * @param code Status code, (100-699). 5550 * @param reason Optional reason phrase. If NULL, default text 5551 * will be used. 5552 * @param msg_data Optional list of headers etc to be added to outgoing 5553 * response message. Note that this message data will 5554 * be persistent in all next answers/responses for this 5555 * INVITE request. 5556 * 5557 * @return PJ_SUCCESS on success, or the appropriate error code. 5558 */ 5559 PJ_DECL(pj_status_t) pjsua_call_answer2(pjsua_call_id call_id, 5560 const pjsua_call_setting *opt, 5561 unsigned code, 5562 const pj_str_t *reason, 5563 const pjsua_msg_data *msg_data); 5564 5565 5566 /** 5567 * Same as #pjsua_call_answer2() but this function will set the SDP 5568 * answer first before sending the response. 5569 * 5570 * @param call_id Incoming call identification. 5571 * @param sdp SDP answer. 5572 * @param opt Optional call setting. 5573 * @param code Status code, (100-699). 5574 * @param reason Optional reason phrase. If NULL, default text 5575 * will be used. 5576 * @param msg_data Optional list of headers etc to be added to outgoing 5577 * response message. Note that this message data will 5578 * be persistent in all next answers/responses for this 5579 * INVITE request. 5580 * 5581 * @return PJ_SUCCESS on success, or the appropriate error code. 5582 */ 5583 PJ_DECL(pj_status_t) 5584 pjsua_call_answer_with_sdp(pjsua_call_id call_id, 5585 const pjmedia_sdp_session *sdp, 5586 const pjsua_call_setting *opt, 5587 unsigned code, 5588 const pj_str_t *reason, 5589 const pjsua_msg_data *msg_data); 5590 5591 5592 /** 5593 * Hangup call by using method that is appropriate according to the 5594 * call state. This function is different than answering the call with 5595 * 3xx-6xx response (with #pjsua_call_answer()), in that this function 5596 * will hangup the call regardless of the state and role of the call, 5597 * while #pjsua_call_answer() only works with incoming calls on EARLY 5598 * state. 5599 * 5600 * After calling this function, media will be deinitialized (call media 5601 * callbacks, if any, will still be received) and then, on_call_state() 5602 * will be immediately called with state DISCONNECTED. No further 5603 * call callbacks will be received after this. The call hangup process 5604 * itself (sending BYE, waiting for the response, and resource cleanup) 5605 * will continue in the background and the call slot can be reused only 5606 * after this process is completed. If application has limited call slots 5607 * and would like to check if there are any free slots remaining, it can 5608 * query the number of free slots using the APIs: 5609 * pjsua_call_get_max_count()-pjsua_call_get_count() 5610 * 5611 * Note that on_call_tsx_state() will not be called when using this API. 5612 * 5613 * @param call_id Call identification. 5614 * @param code Optional status code to be sent when we're rejecting 5615 * incoming call. If the value is zero, "603/Decline" 5616 * will be sent. 5617 * @param reason Optional reason phrase to be sent when we're rejecting 5618 * incoming call. If NULL, default text will be used. 5619 * @param msg_data Optional list of headers etc to be added to outgoing 5620 * request/response message. 5621 * 5622 * @return PJ_SUCCESS on success, or the appropriate error code. 5623 */ 5624 PJ_DECL(pj_status_t) pjsua_call_hangup(pjsua_call_id call_id, 5625 unsigned code, 5626 const pj_str_t *reason, 5627 const pjsua_msg_data *msg_data); 5628 5629 /** 5630 * Accept or reject redirection response. Application MUST call this function 5631 * after it signaled PJSIP_REDIRECT_PENDING in the \a on_call_redirected() 5632 * callback, to notify the call whether to accept or reject the redirection 5633 * to the current target. Application can use the combination of 5634 * PJSIP_REDIRECT_PENDING command in \a on_call_redirected() callback and 5635 * this function to ask for user permission before redirecting the call. 5636 * 5637 * Note that if the application chooses to reject or stop redirection (by 5638 * using PJSIP_REDIRECT_REJECT or PJSIP_REDIRECT_STOP respectively), the 5639 * call disconnection callback will be called before this function returns. 5640 * And if the application rejects the target, the \a on_call_redirected() 5641 * callback may also be called before this function returns if there is 5642 * another target to try. 5643 * 5644 * @param call_id The call ID. 5645 * @param cmd Redirection operation to be applied to the current 5646 * target. The semantic of this argument is similar 5647 * to the description in the \a on_call_redirected() 5648 * callback, except that the PJSIP_REDIRECT_PENDING is 5649 * not accepted here. 5650 * 5651 * @return PJ_SUCCESS on successful operation. 5652 */ 5653 PJ_DECL(pj_status_t) pjsua_call_process_redirect(pjsua_call_id call_id, 5654 pjsip_redirect_op cmd); 5655 5656 /** 5657 * Put the specified call on hold. This will send re-INVITE with the 5658 * appropriate SDP to inform remote that the call is being put on hold. 5659 * The final status of the request itself will be reported on the 5660 * \a on_call_media_state() callback, which inform the application that 5661 * the media state of the call has changed. 5662 * 5663 * @param call_id Call identification. 5664 * @param msg_data Optional message components to be sent with 5665 * the request. 5666 * 5667 * @return PJ_SUCCESS on success, or the appropriate error code. 5668 */ 5669 PJ_DECL(pj_status_t) pjsua_call_set_hold(pjsua_call_id call_id, 5670 const pjsua_msg_data *msg_data); 5671 5672 /** 5673 * Put the specified call on hold. This will send re-INVITE with the 5674 * appropriate SDP to inform remote that the call is being put on hold. 5675 * The final status of the request itself will be reported on the 5676 * \a on_call_media_state() callback, which inform the application that 5677 * the media state of the call has changed. 5678 * 5679 * @param call_id Call identification. 5680 * @param options Bitmask of pjsua_call_flag constants. Currently, only 5681 * the flag PJSUA_CALL_UPDATE_CONTACT can be used. 5682 * @param msg_data Optional message components to be sent with 5683 * the request. 5684 * 5685 * @return PJ_SUCCESS on success, or the appropriate error code. 5686 */ 5687 PJ_DECL(pj_status_t) pjsua_call_set_hold2(pjsua_call_id call_id, 5688 unsigned options, 5689 const pjsua_msg_data *msg_data); 5690 5691 /** 5692 * Send re-INVITE request or release hold. 5693 * The final status of the request itself will be reported on the 5694 * \a on_call_media_state() callback, which inform the application that 5695 * the media state of the call has changed. 5696 * 5697 * @param call_id Call identification. 5698 * @param options Bitmask of pjsua_call_flag constants. Note that 5699 * for compatibility, specifying PJ_TRUE here is 5700 * equal to specifying PJSUA_CALL_UNHOLD flag. 5701 * @param msg_data Optional message components to be sent with 5702 * the request. 5703 * 5704 * @return PJ_SUCCESS on success, or the appropriate error code. 5705 */ 5706 PJ_DECL(pj_status_t) pjsua_call_reinvite(pjsua_call_id call_id, 5707 unsigned options, 5708 const pjsua_msg_data *msg_data); 5709 5710 5711 /** 5712 * Send re-INVITE request or release hold. 5713 * The final status of the request itself will be reported on the 5714 * \a on_call_media_state() callback, which inform the application that 5715 * the media state of the call has changed. 5716 * 5717 * @param call_id Call identification. 5718 * @param opt Optional call setting, if NULL, the current call 5719 * setting will be used. Note that to release hold 5720 * or update contact or omit SDP offer, this parameter 5721 * cannot be NULL and it must specify appropriate flags, 5722 * e.g: PJSUA_CALL_UNHOLD, PJSUA_CALL_UPDATE_CONTACT, 5723 * PJSUA_CALL_NO_SDP_OFFER. 5724 * @param msg_data Optional message components to be sent with 5725 * the request. 5726 * 5727 * @return PJ_SUCCESS on success, or the appropriate error code. 5728 */ 5729 PJ_DECL(pj_status_t) pjsua_call_reinvite2(pjsua_call_id call_id, 5730 const pjsua_call_setting *opt, 5731 const pjsua_msg_data *msg_data); 5732 5733 5734 /** 5735 * Send UPDATE request. 5736 * 5737 * @param call_id Call identification. 5738 * @param options Bitmask of pjsua_call_flag constants. 5739 * @param msg_data Optional message components to be sent with 5740 * the request. 5741 * 5742 * @return PJ_SUCCESS on success, or the appropriate error code. 5743 */ 5744 PJ_DECL(pj_status_t) pjsua_call_update(pjsua_call_id call_id, 5745 unsigned options, 5746 const pjsua_msg_data *msg_data); 5747 5748 5749 /** 5750 * Send UPDATE request. 5751 * 5752 * @param call_id Call identification. 5753 * @param opt Optional call setting, if NULL, the current call 5754 * setting will be used. Note that to release hold 5755 * or update contact or omit SDP offer, this parameter 5756 * cannot be NULL and it must specify appropriate flags, 5757 * e.g: PJSUA_CALL_UNHOLD, PJSUA_CALL_UPDATE_CONTACT, 5758 * PJSUA_CALL_NO_SDP_OFFER. 5759 * @param msg_data Optional message components to be sent with 5760 * the request. 5761 * 5762 * @return PJ_SUCCESS on success, or the appropriate error code. 5763 */ 5764 PJ_DECL(pj_status_t) pjsua_call_update2(pjsua_call_id call_id, 5765 const pjsua_call_setting *opt, 5766 const pjsua_msg_data *msg_data); 5767 5768 5769 /** 5770 * Initiate call transfer to the specified address. This function will send 5771 * REFER request to instruct remote call party to initiate a new INVITE 5772 * session to the specified destination/target. 5773 * 5774 * If application is interested to monitor the successfulness and 5775 * the progress of the transfer request, it can implement 5776 * \a on_call_transfer_status() callback which will report the progress 5777 * of the call transfer request. 5778 * 5779 * @param call_id The call id to be transferred. 5780 * @param dest URI of new target to be contacted. The URI may be 5781 * in name address or addr-spec format. 5782 * @param msg_data Optional message components to be sent with 5783 * the request. 5784 * 5785 * @return PJ_SUCCESS on success, or the appropriate error code. 5786 */ 5787 PJ_DECL(pj_status_t) pjsua_call_xfer(pjsua_call_id call_id, 5788 const pj_str_t *dest, 5789 const pjsua_msg_data *msg_data); 5790 5791 /** 5792 * Flag to indicate that "Require: replaces" should not be put in the 5793 * outgoing INVITE request caused by REFER request created by 5794 * #pjsua_call_xfer_replaces(). 5795 */ 5796 #define PJSUA_XFER_NO_REQUIRE_REPLACES 1 5797 5798 /** 5799 * Initiate attended call transfer. This function will send REFER request 5800 * to instruct remote call party to initiate new INVITE session to the URL 5801 * of \a dest_call_id. The party at \a dest_call_id then should "replace" 5802 * the call with us with the new call from the REFER recipient. 5803 * 5804 * @param call_id The call id to be transferred. 5805 * @param dest_call_id The call id to be replaced. 5806 * @param options Application may specify PJSUA_XFER_NO_REQUIRE_REPLACES 5807 * to suppress the inclusion of "Require: replaces" in 5808 * the outgoing INVITE request created by the REFER 5809 * request. 5810 * @param msg_data Optional message components to be sent with 5811 * the request. 5812 * 5813 * @return PJ_SUCCESS on success, or the appropriate error code. 5814 */ 5815 PJ_DECL(pj_status_t) pjsua_call_xfer_replaces(pjsua_call_id call_id, 5816 pjsua_call_id dest_call_id, 5817 unsigned options, 5818 const pjsua_msg_data *msg_data); 5819 5820 /** 5821 * Send DTMF digits to remote using RFC 2833 payload formats. Use 5822 * #pjsua_call_send_dtmf() to send DTMF using SIP INFO or other method in 5823 * \a pjsua_dtmf_method. App can use \a on_dtmf_digit() or \a on_dtmf_digit2() 5824 * callback to monitor incoming DTMF. 5825 * 5826 * @param call_id Call identification. 5827 * @param digits DTMF string digits to be sent as described on RFC 2833 5828 * section 3.10. If PJMEDIA_HAS_DTMF_FLASH is enabled, 5829 * character 'R' is used to represent the 5830 * event type 16 (flash) as stated in RFC 4730. 5831 * 5832 * @return PJ_SUCCESS on success, or the appropriate error code. 5833 */ 5834 PJ_DECL(pj_status_t) pjsua_call_dial_dtmf(pjsua_call_id call_id, 5835 const pj_str_t *digits); 5836 5837 /** 5838 * Send DTMF digits to remote. Use this method to send DTMF using the method in 5839 * \a pjsua_dtmf_method. This method will call #pjsua_call_dial_dtmf() when 5840 * sending DTMF using \a PJSUA_DTMF_METHOD_RFC2833. Note that 5841 * \a on_dtmf_digit() callback can only monitor incoming DTMF using RFC 2833. 5842 * App can use \a on_dtmf_digit2() to monitor incoming DTMF using the method in 5843 * \a pjsua_dtmf_method. Note that \a on_dtmf_digit() will not be called once 5844 * \a on_dtmf_digit2() is implemented. 5845 * 5846 * @param call_id Call identification. 5847 * @param param The send DTMF parameter. 5848 * 5849 * @return PJ_SUCCESS on success, or the appropriate error code. 5850 */ 5851 PJ_DECL(pj_status_t) pjsua_call_send_dtmf(pjsua_call_id call_id, 5852 const pjsua_call_send_dtmf_param *param); 5853 5854 /** 5855 * Send instant messaging inside INVITE session. 5856 * 5857 * @param call_id Call identification. 5858 * @param mime_type Optional MIME type. If NULL, then "text/plain" is 5859 * assumed. 5860 * @param content The message content. Can be NULL if msg_data specifies 5861 * body and/or multipart. 5862 * @param msg_data Optional list of headers etc to be included in outgoing 5863 * request. The body descriptor in the msg_data is 5864 * ignored if parameter 'content' is set. 5865 * @param user_data Optional user data, which will be given back when 5866 * the IM callback is called. 5867 * 5868 * @return PJ_SUCCESS on success, or the appropriate error code. 5869 */ 5870 PJ_DECL(pj_status_t) pjsua_call_send_im( pjsua_call_id call_id, 5871 const pj_str_t *mime_type, 5872 const pj_str_t *content, 5873 const pjsua_msg_data *msg_data, 5874 void *user_data); 5875 5876 5877 /** 5878 * Send IM typing indication inside INVITE session. 5879 * 5880 * @param call_id Call identification. 5881 * @param is_typing Non-zero to indicate to remote that local person is 5882 * currently typing an IM. 5883 * @param msg_data Optional list of headers etc to be included in outgoing 5884 * request. 5885 * 5886 * @return PJ_SUCCESS on success, or the appropriate error code. 5887 */ 5888 PJ_DECL(pj_status_t) pjsua_call_send_typing_ind(pjsua_call_id call_id, 5889 pj_bool_t is_typing, 5890 const pjsua_msg_data*msg_data); 5891 5892 /** 5893 * Send arbitrary request with the call. This is useful for example to send 5894 * INFO request. Note that application should not use this function to send 5895 * requests which would change the invite session's state, such as re-INVITE, 5896 * UPDATE, PRACK, and BYE. 5897 * 5898 * @param call_id Call identification. 5899 * @param method SIP method of the request. 5900 * @param msg_data Optional message body and/or list of headers to be 5901 * included in outgoing request. 5902 * 5903 * @return PJ_SUCCESS on success, or the appropriate error code. 5904 */ 5905 PJ_DECL(pj_status_t) pjsua_call_send_request(pjsua_call_id call_id, 5906 const pj_str_t *method, 5907 const pjsua_msg_data *msg_data); 5908 5909 5910 /** 5911 * Terminate all calls. This will initiate #pjsua_call_hangup() for all 5912 * currently active calls. 5913 */ 5914 PJ_DECL(void) pjsua_call_hangup_all(void); 5915 5916 5917 /** 5918 * Dump call and media statistics to string. 5919 * 5920 * @param call_id Call identification. 5921 * @param with_media Non-zero to include media information too. 5922 * @param buffer Buffer where the statistics are to be written to. 5923 * @param maxlen Maximum length of buffer. 5924 * @param indent Spaces for left indentation. 5925 * 5926 * @return PJ_SUCCESS on success. 5927 */ 5928 PJ_DECL(pj_status_t) pjsua_call_dump(pjsua_call_id call_id, 5929 pj_bool_t with_media, 5930 char *buffer, 5931 unsigned maxlen, 5932 const char *indent); 5933 5934 /** 5935 * Get the media stream index of the default video stream in the call. 5936 * Typically this will just retrieve the stream index of the first 5937 * activated video stream in the call. If none is active, it will return 5938 * the first inactive video stream. 5939 * 5940 * @param call_id Call identification. 5941 * 5942 * @return The media stream index or -1 if no video stream 5943 * is present in the call. 5944 */ 5945 PJ_DECL(int) pjsua_call_get_vid_stream_idx(pjsua_call_id call_id); 5946 5947 5948 /** 5949 * Determine if video stream for the specified call is currently running 5950 * (i.e. has been created, started, and not being paused) for the specified 5951 * direction. 5952 * 5953 * @param call_id Call identification. 5954 * @param med_idx Media stream index, or -1 to specify default video 5955 * media. 5956 * @param dir The direction to be checked. 5957 * 5958 * @return PJ_TRUE if stream is currently running for the 5959 * specified direction. 5960 */ 5961 PJ_DECL(pj_bool_t) pjsua_call_vid_stream_is_running(pjsua_call_id call_id, 5962 int med_idx, 5963 pjmedia_dir dir); 5964 5965 /** 5966 * Add, remove, modify, and/or manipulate video media stream for the 5967 * specified call. This may trigger a re-INVITE or UPDATE to be sent 5968 * for the call. 5969 * 5970 * @param call_id Call identification. 5971 * @param op The video stream operation to be performed, 5972 * possible values are #pjsua_call_vid_strm_op. 5973 * @param param The parameters for the video stream operation, 5974 * or NULL for the default parameter values 5975 * (see #pjsua_call_vid_strm_op_param). 5976 * 5977 * @return PJ_SUCCESS on success or the appropriate error. 5978 */ 5979 PJ_DECL(pj_status_t) pjsua_call_set_vid_strm ( 5980 pjsua_call_id call_id, 5981 pjsua_call_vid_strm_op op, 5982 const pjsua_call_vid_strm_op_param *param); 5983 5984 5985 /** 5986 * Get media stream info for the specified media index. 5987 * 5988 * @param call_id The call identification. 5989 * @param med_idx Media stream index. 5990 * @param psi To be filled with the stream info. 5991 * 5992 * @return PJ_SUCCESS on success or the appropriate error. 5993 */ 5994 PJ_DECL(pj_status_t) pjsua_call_get_stream_info(pjsua_call_id call_id, 5995 unsigned med_idx, 5996 pjsua_stream_info *psi); 5997 5998 /** 5999 * Get media stream statistic for the specified media index. 6000 * 6001 * @param call_id The call identification. 6002 * @param med_idx Media stream index. 6003 * @param psi To be filled with the stream statistic. 6004 * 6005 * @return PJ_SUCCESS on success or the appropriate error. 6006 */ 6007 PJ_DECL(pj_status_t) pjsua_call_get_stream_stat(pjsua_call_id call_id, 6008 unsigned med_idx, 6009 pjsua_stream_stat *stat); 6010 6011 /** 6012 * Get media transport info for the specified media index. 6013 * 6014 * @param call_id The call identification. 6015 * @param med_idx Media stream index. 6016 * @param t To be filled with the transport info. 6017 * 6018 * @return PJ_SUCCESS on success or the appropriate error. 6019 */ 6020 PJ_DECL(pj_status_t) 6021 pjsua_call_get_med_transport_info(pjsua_call_id call_id, 6022 unsigned med_idx, 6023 pjmedia_transport_info *t); 6024 6025 6026 6027 /** 6028 * @} 6029 */ 6030 6031 6032 /***************************************************************************** 6033 * BUDDY API 6034 */ 6035 6036 6037 /** 6038 * @defgroup PJSUA_LIB_BUDDY PJSUA-API Buddy, Presence, and Instant Messaging 6039 * @ingroup PJSUA_LIB 6040 * @brief Buddy management, buddy's presence, and instant messaging. 6041 * @{ 6042 * 6043 * This section describes PJSUA-APIs related to buddies management, 6044 * presence management, and instant messaging. 6045 */ 6046 6047 /** 6048 * Max buddies in buddy list. 6049 */ 6050 #ifndef PJSUA_MAX_BUDDIES 6051 # define PJSUA_MAX_BUDDIES 256 6052 #endif 6053 6054 6055 /** 6056 * This specifies how long the library should wait before retrying failed 6057 * SUBSCRIBE request, and there is no rule to automatically resubscribe 6058 * (for example, no "retry-after" parameter in Subscription-State header). 6059 * 6060 * This also controls the duration before failed PUBLISH request will be 6061 * retried. 6062 * 6063 * Default: 300 seconds 6064 */ 6065 #ifndef PJSUA_PRES_TIMER 6066 # define PJSUA_PRES_TIMER 300 6067 #endif 6068 6069 6070 /** 6071 * This structure describes buddy configuration when adding a buddy to 6072 * the buddy list with #pjsua_buddy_add(). Application MUST initialize 6073 * the structure with #pjsua_buddy_config_default() to initialize this 6074 * structure with default configuration. 6075 */ 6076 typedef struct pjsua_buddy_config 6077 { 6078 /** 6079 * Buddy URL or name address. 6080 */ 6081 pj_str_t uri; 6082 6083 /** 6084 * Specify whether presence subscription should start immediately. 6085 */ 6086 pj_bool_t subscribe; 6087 6088 /** 6089 * Specify arbitrary application data to be associated with with 6090 * the buddy object. 6091 */ 6092 void *user_data; 6093 6094 } pjsua_buddy_config; 6095 6096 6097 /** 6098 * This enumeration describes basic buddy's online status. 6099 */ 6100 typedef enum pjsua_buddy_status 6101 { 6102 /** 6103 * Online status is unknown (possibly because no presence subscription 6104 * has been established). 6105 */ 6106 PJSUA_BUDDY_STATUS_UNKNOWN, 6107 6108 /** 6109 * Buddy is known to be online. 6110 */ 6111 PJSUA_BUDDY_STATUS_ONLINE, 6112 6113 /** 6114 * Buddy is offline. 6115 */ 6116 PJSUA_BUDDY_STATUS_OFFLINE, 6117 6118 } pjsua_buddy_status; 6119 6120 6121 6122 /** 6123 * This structure describes buddy info, which can be retrieved by calling 6124 * #pjsua_buddy_get_info(). 6125 */ 6126 typedef struct pjsua_buddy_info 6127 { 6128 /** 6129 * The buddy ID. 6130 */ 6131 pjsua_buddy_id id; 6132 6133 /** 6134 * The full URI of the buddy, as specified in the configuration. 6135 */ 6136 pj_str_t uri; 6137 6138 /** 6139 * Buddy's Contact, only available when presence subscription has 6140 * been established to the buddy. 6141 */ 6142 pj_str_t contact; 6143 6144 /** 6145 * Buddy's online status. 6146 */ 6147 pjsua_buddy_status status; 6148 6149 /** 6150 * Text to describe buddy's online status. 6151 */ 6152 pj_str_t status_text; 6153 6154 /** 6155 * Flag to indicate that we should monitor the presence information for 6156 * this buddy (normally yes, unless explicitly disabled). 6157 */ 6158 pj_bool_t monitor_pres; 6159 6160 /** 6161 * If \a monitor_pres is enabled, this specifies the last state of the 6162 * presence subscription. If presence subscription session is currently 6163 * active, the value will be PJSIP_EVSUB_STATE_ACTIVE. If presence 6164 * subscription request has been rejected, the value will be 6165 * PJSIP_EVSUB_STATE_TERMINATED, and the termination reason will be 6166 * specified in \a sub_term_reason. 6167 */ 6168 pjsip_evsub_state sub_state; 6169 6170 /** 6171 * String representation of subscription state. 6172 */ 6173 const char *sub_state_name; 6174 6175 /** 6176 * Specifies the last presence subscription termination code. This would 6177 * return the last status of the SUBSCRIBE request. If the subscription 6178 * is terminated with NOTIFY by the server, this value will be set to 6179 * 200, and subscription termination reason will be given in the 6180 * \a sub_term_reason field. 6181 */ 6182 unsigned sub_term_code; 6183 6184 /** 6185 * Specifies the last presence subscription termination reason. If 6186 * presence subscription is currently active, the value will be empty. 6187 */ 6188 pj_str_t sub_term_reason; 6189 6190 /** 6191 * Extended RPID information about the person. 6192 */ 6193 pjrpid_element rpid; 6194 6195 /** 6196 * Extended presence info. 6197 */ 6198 pjsip_pres_status pres_status; 6199 6200 /** 6201 * Internal buffer. 6202 */ 6203 char buf_[512]; 6204 6205 } pjsua_buddy_info; 6206 6207 6208 /** 6209 * Set default values to the buddy config. 6210 */ 6211 PJ_DECL(void) pjsua_buddy_config_default(pjsua_buddy_config *cfg); 6212 6213 6214 /** 6215 * Get total number of buddies. 6216 * 6217 * @return Number of buddies. 6218 */ 6219 PJ_DECL(unsigned) pjsua_get_buddy_count(void); 6220 6221 6222 /** 6223 * Check if buddy ID is valid. 6224 * 6225 * @param buddy_id Buddy ID to check. 6226 * 6227 * @return Non-zero if buddy ID is valid. 6228 */ 6229 PJ_DECL(pj_bool_t) pjsua_buddy_is_valid(pjsua_buddy_id buddy_id); 6230 6231 6232 /** 6233 * Enumerate all buddy IDs in the buddy list. Application then can use 6234 * #pjsua_buddy_get_info() to get the detail information for each buddy 6235 * id. 6236 * 6237 * @param ids Array of ids to be initialized. 6238 * @param count On input, specifies max elements in the array. 6239 * On return, it contains actual number of elements 6240 * that have been initialized. 6241 * 6242 * @return PJ_SUCCESS on success, or the appropriate error code. 6243 */ 6244 PJ_DECL(pj_status_t) pjsua_enum_buddies(pjsua_buddy_id ids[], 6245 unsigned *count); 6246 6247 /** 6248 * Find the buddy ID with the specified URI. 6249 * 6250 * @param uri The buddy URI. 6251 * 6252 * @return The buddy ID, or PJSUA_INVALID_ID if not found. 6253 */ 6254 PJ_DECL(pjsua_buddy_id) pjsua_buddy_find(const pj_str_t *uri); 6255 6256 6257 /** 6258 * Get detailed buddy info. 6259 * 6260 * @param buddy_id The buddy identification. 6261 * @param info Pointer to receive information about buddy. 6262 * 6263 * @return PJ_SUCCESS on success, or the appropriate error code. 6264 */ 6265 PJ_DECL(pj_status_t) pjsua_buddy_get_info(pjsua_buddy_id buddy_id, 6266 pjsua_buddy_info *info); 6267 6268 /** 6269 * Set the user data associated with the buddy object. 6270 * 6271 * @param buddy_id The buddy identification. 6272 * @param user_data Arbitrary application data to be associated with 6273 * the buddy object. 6274 * 6275 * @return PJ_SUCCESS on success, or the appropriate error code. 6276 */ 6277 PJ_DECL(pj_status_t) pjsua_buddy_set_user_data(pjsua_buddy_id buddy_id, 6278 void *user_data); 6279 6280 6281 /** 6282 * Get the user data associated with the budy object. 6283 * 6284 * @param buddy_id The buddy identification. 6285 * 6286 * @return The application data. 6287 */ 6288 PJ_DECL(void*) pjsua_buddy_get_user_data(pjsua_buddy_id buddy_id); 6289 6290 6291 /** 6292 * Add new buddy to the buddy list. If presence subscription is enabled 6293 * for this buddy, this function will also start the presence subscription 6294 * session immediately. 6295 * 6296 * @param buddy_cfg Buddy configuration. 6297 * @param p_buddy_id Pointer to receive buddy ID. 6298 * 6299 * @return PJ_SUCCESS on success, or the appropriate error code. 6300 */ 6301 PJ_DECL(pj_status_t) pjsua_buddy_add(const pjsua_buddy_config *buddy_cfg, 6302 pjsua_buddy_id *p_buddy_id); 6303 6304 6305 /** 6306 * Delete the specified buddy from the buddy list. Any presence subscription 6307 * to this buddy will be terminated. 6308 * 6309 * @param buddy_id Buddy identification. 6310 * 6311 * @return PJ_SUCCESS on success, or the appropriate error code. 6312 */ 6313 PJ_DECL(pj_status_t) pjsua_buddy_del(pjsua_buddy_id buddy_id); 6314 6315 6316 /** 6317 * Enable/disable buddy's presence monitoring. Once buddy's presence is 6318 * subscribed, application will be informed about buddy's presence status 6319 * changed via \a on_buddy_state() callback. 6320 * 6321 * @param buddy_id Buddy identification. 6322 * @param subscribe Specify non-zero to activate presence subscription to 6323 * the specified buddy. 6324 * 6325 * @return PJ_SUCCESS on success, or the appropriate error code. 6326 */ 6327 PJ_DECL(pj_status_t) pjsua_buddy_subscribe_pres(pjsua_buddy_id buddy_id, 6328 pj_bool_t subscribe); 6329 6330 6331 /** 6332 * Update the presence information for the buddy. Although the library 6333 * periodically refreshes the presence subscription for all buddies, some 6334 * application may want to refresh the buddy's presence subscription 6335 * immediately, and in this case it can use this function to accomplish 6336 * this. 6337 * 6338 * Note that the buddy's presence subscription will only be initiated 6339 * if presence monitoring is enabled for the buddy. See 6340 * #pjsua_buddy_subscribe_pres() for more info. Also if presence subscription 6341 * for the buddy is already active, this function will not do anything. 6342 * 6343 * Once the presence subscription is activated successfully for the buddy, 6344 * application will be notified about the buddy's presence status in the 6345 * on_buddy_state() callback. 6346 * 6347 * @param buddy_id Buddy identification. 6348 * 6349 * @return PJ_SUCCESS on success, or the appropriate error code. 6350 */ 6351 PJ_DECL(pj_status_t) pjsua_buddy_update_pres(pjsua_buddy_id buddy_id); 6352 6353 6354 /** 6355 * Send NOTIFY to inform account presence status or to terminate server 6356 * side presence subscription. If application wants to reject the incoming 6357 * request, it should set the \a state to PJSIP_EVSUB_STATE_TERMINATED. 6358 * 6359 * @param acc_id Account ID. 6360 * @param srv_pres Server presence subscription instance. 6361 * @param state New state to set. 6362 * @param state_str Optionally specify the state string name, if state 6363 * is not "active", "pending", or "terminated". 6364 * @param reason If the new state is PJSIP_EVSUB_STATE_TERMINATED, 6365 * optionally specify the termination reason. 6366 * @param with_body If the new state is PJSIP_EVSUB_STATE_TERMINATED, 6367 * this specifies whether the NOTIFY request should 6368 * contain message body containing account's presence 6369 * information. 6370 * @param msg_data Optional list of headers to be sent with the NOTIFY 6371 * request. 6372 * 6373 * @return PJ_SUCCESS on success. 6374 */ 6375 PJ_DECL(pj_status_t) pjsua_pres_notify(pjsua_acc_id acc_id, 6376 pjsua_srv_pres *srv_pres, 6377 pjsip_evsub_state state, 6378 const pj_str_t *state_str, 6379 const pj_str_t *reason, 6380 pj_bool_t with_body, 6381 const pjsua_msg_data *msg_data); 6382 6383 /** 6384 * Dump presence subscriptions to log. 6385 * 6386 * @param verbose Yes or no. 6387 */ 6388 PJ_DECL(void) pjsua_pres_dump(pj_bool_t verbose); 6389 6390 6391 /** 6392 * The MESSAGE method (defined in pjsua_im.c) 6393 */ 6394 extern const pjsip_method pjsip_message_method; 6395 6396 6397 /** 6398 * The INFO method (defined in pjsua_call.c) 6399 */ 6400 extern const pjsip_method pjsip_info_method; 6401 6402 6403 /** 6404 * Send instant messaging outside dialog, using the specified account for 6405 * route set and authentication. 6406 * 6407 * @param acc_id Account ID to be used to send the request. 6408 * @param to Remote URI. 6409 * @param mime_type Optional MIME type. If NULL, then "text/plain" is 6410 * assumed. 6411 * @param content The message content. Can be NULL if msg_data specifies 6412 * body and/or multipart. 6413 * @param msg_data Optional list of headers etc to be included in outgoing 6414 * request. The body descriptor in the msg_data is 6415 * ignored if parameter 'content' is set. 6416 * @param user_data Optional user data, which will be given back when 6417 * the IM callback is called. 6418 * 6419 * @return PJ_SUCCESS on success, or the appropriate error code. 6420 */ 6421 PJ_DECL(pj_status_t) pjsua_im_send(pjsua_acc_id acc_id, 6422 const pj_str_t *to, 6423 const pj_str_t *mime_type, 6424 const pj_str_t *content, 6425 const pjsua_msg_data *msg_data, 6426 void *user_data); 6427 6428 6429 /** 6430 * Send typing indication outside dialog. 6431 * 6432 * @param acc_id Account ID to be used to send the request. 6433 * @param to Remote URI. 6434 * @param is_typing If non-zero, it tells remote person that local person 6435 * is currently composing an IM. 6436 * @param msg_data Optional list of headers etc to be added to outgoing 6437 * request. 6438 * 6439 * @return PJ_SUCCESS on success, or the appropriate error code. 6440 */ 6441 PJ_DECL(pj_status_t) pjsua_im_typing(pjsua_acc_id acc_id, 6442 const pj_str_t *to, 6443 pj_bool_t is_typing, 6444 const pjsua_msg_data *msg_data); 6445 6446 6447 6448 /** 6449 * @} 6450 */ 6451 6452 6453 /***************************************************************************** 6454 * MEDIA API 6455 */ 6456 6457 6458 /** 6459 * @defgroup PJSUA_LIB_MEDIA PJSUA-API Media Manipulation 6460 * @ingroup PJSUA_LIB 6461 * @brief Media manipulation. 6462 * @{ 6463 * 6464 * PJSUA has rather powerful media features, which are built around the 6465 * PJMEDIA conference bridge. Basically, all media "ports" (such as calls, WAV 6466 * players, WAV playlist, file recorders, sound device, tone generators, etc) 6467 * are terminated in the conference bridge, and application can manipulate 6468 * the interconnection between these terminations freely. 6469 * 6470 * The conference bridge provides powerful switching and mixing functionality 6471 * for application. With the conference bridge, each conference slot (e.g. 6472 * a call) can transmit to multiple destinations, and one destination can 6473 * receive from multiple sources. If more than one media terminations are 6474 * terminated in the same slot, the conference bridge will mix the signal 6475 * automatically. 6476 * 6477 * Application connects one media termination/slot to another by calling 6478 * #pjsua_conf_connect() function. This will establish <b>unidirectional</b> 6479 * media flow from the source termination to the sink termination. To 6480 * establish bidirectional media flow, application wound need to make another 6481 * call to #pjsua_conf_connect(), this time inverting the source and 6482 * destination slots in the parameter. 6483 * 6484 * For example, to stream a WAV file to remote call, application may use 6485 * the following steps: 6486 * 6487 \code 6488 6489 pj_status_t stream_to_call( pjsua_call_id call_id ) 6490 { 6491 pjsua_player_id player_id; 6492 6493 status = pjsua_player_create("mysong.wav", 0, &player_id); 6494 if (status != PJ_SUCCESS) 6495 return status; 6496 6497 status = pjsua_conf_connect( pjsua_player_get_conf_port(), 6498 pjsua_call_get_conf_port() ); 6499 } 6500 \endcode 6501 * 6502 * 6503 * Other features of PJSUA media: 6504 * - efficient N to M interconnections between media terminations. 6505 * - media termination can be connected to itself to create loopback 6506 * media. 6507 * - the media termination may have different clock rates, and resampling 6508 * will be done automatically by conference bridge. 6509 * - media terminations may also have different frame time; the 6510 * conference bridge will perform the necessary bufferring to adjust 6511 * the difference between terminations. 6512 * - interconnections are removed automatically when media termination 6513 * is removed from the bridge. 6514 * - sound device may be changed even when there are active media 6515 * interconnections. 6516 * - correctly report call's media quality (in #pjsua_call_dump()) from 6517 * RTCP packet exchange. 6518 */ 6519 6520 /** 6521 * Use PJMEDIA for media? Set this to zero when using third party media 6522 * stack. 6523 */ 6524 #ifndef PJSUA_MEDIA_HAS_PJMEDIA 6525 # define PJSUA_MEDIA_HAS_PJMEDIA 1 6526 #endif /* PJSUA_MEDIA_HAS_PJMEDIA */ 6527 6528 6529 /** 6530 * Specify whether the third party stream has the capability of retrieving 6531 * the stream info, i.e: pjmedia_stream_get_info() and 6532 * pjmedia_vid_stream_get_info(). Currently this capability is required 6533 * by smart media update and call dump. 6534 */ 6535 #ifndef PJSUA_THIRD_PARTY_STREAM_HAS_GET_INFO 6536 # define PJSUA_THIRD_PARTY_STREAM_HAS_GET_INFO 0 6537 #endif 6538 6539 6540 /** 6541 * Specify whether the third party stream has the capability of retrieving 6542 * the stream statistics, i.e: pjmedia_stream_get_stat() and 6543 * pjmedia_vid_stream_get_stat(). Currently this capability is required 6544 * by call dump. 6545 */ 6546 #ifndef PJSUA_THIRD_PARTY_STREAM_HAS_GET_STAT 6547 # define PJSUA_THIRD_PARTY_STREAM_HAS_GET_STAT 0 6548 #endif 6549 6550 6551 /** 6552 * Max ports in the conference bridge. This setting is the default value 6553 * for pjsua_media_config.max_media_ports. 6554 */ 6555 #ifndef PJSUA_MAX_CONF_PORTS 6556 # define PJSUA_MAX_CONF_PORTS 254 6557 #endif 6558 6559 /** 6560 * The default clock rate to be used by the conference bridge. This setting 6561 * is the default value for pjsua_media_config.clock_rate. 6562 */ 6563 #ifndef PJSUA_DEFAULT_CLOCK_RATE 6564 # define PJSUA_DEFAULT_CLOCK_RATE 16000 6565 #endif 6566 6567 /** 6568 * Default frame length in the conference bridge. This setting 6569 * is the default value for pjsua_media_config.audio_frame_ptime. 6570 */ 6571 #ifndef PJSUA_DEFAULT_AUDIO_FRAME_PTIME 6572 # define PJSUA_DEFAULT_AUDIO_FRAME_PTIME 20 6573 #endif 6574 6575 6576 /** 6577 * Default codec quality settings. This setting is the default value 6578 * for pjsua_media_config.quality. 6579 */ 6580 #ifndef PJSUA_DEFAULT_CODEC_QUALITY 6581 # define PJSUA_DEFAULT_CODEC_QUALITY 8 6582 #endif 6583 6584 /** 6585 * Default iLBC mode. This setting is the default value for 6586 * pjsua_media_config.ilbc_mode. 6587 */ 6588 #ifndef PJSUA_DEFAULT_ILBC_MODE 6589 # define PJSUA_DEFAULT_ILBC_MODE 30 6590 #endif 6591 6592 /** 6593 * The default echo canceller tail length. This setting 6594 * is the default value for pjsua_media_config.ec_tail_len. 6595 */ 6596 #ifndef PJSUA_DEFAULT_EC_TAIL_LEN 6597 # define PJSUA_DEFAULT_EC_TAIL_LEN 200 6598 #endif 6599 6600 6601 /** 6602 * The maximum file player. 6603 */ 6604 #ifndef PJSUA_MAX_PLAYERS 6605 # define PJSUA_MAX_PLAYERS 32 6606 #endif 6607 6608 6609 /** 6610 * The maximum file player. 6611 */ 6612 #ifndef PJSUA_MAX_RECORDERS 6613 # define PJSUA_MAX_RECORDERS 32 6614 #endif 6615 6616 6617 /** 6618 * Enable/disable "c=" line in SDP session level. Set to zero to disable it. 6619 */ 6620 #ifndef PJSUA_SDP_SESS_HAS_CONN 6621 # define PJSUA_SDP_SESS_HAS_CONN 0 6622 #endif 6623 6624 6625 /** 6626 * Specify the delay needed when restarting the transport/listener. 6627 * e.g: 10 msec on Linux or Android, and 0 on the other platforms. 6628 */ 6629 #ifndef PJSUA_TRANSPORT_RESTART_DELAY_TIME 6630 # define PJSUA_TRANSPORT_RESTART_DELAY_TIME 10 6631 #endif 6632 6633 6634 /** 6635 * This structure describes media configuration, which will be specified 6636 * when calling #pjsua_init(). Application MUST initialize this structure 6637 * by calling #pjsua_media_config_default(). 6638 */ 6639 struct pjsua_media_config 6640 { 6641 /** 6642 * Clock rate to be applied to the conference bridge. 6643 * If value is zero, default clock rate will be used 6644 * (PJSUA_DEFAULT_CLOCK_RATE, which by default is 16KHz). 6645 */ 6646 unsigned clock_rate; 6647 6648 /** 6649 * Clock rate to be applied when opening the sound device. 6650 * If value is zero, conference bridge clock rate will be used. 6651 */ 6652 unsigned snd_clock_rate; 6653 6654 /** 6655 * Channel count be applied when opening the sound device and 6656 * conference bridge. 6657 */ 6658 unsigned channel_count; 6659 6660 /** 6661 * Specify audio frame ptime. The value here will affect the 6662 * samples per frame of both the sound device and the conference 6663 * bridge. Specifying lower ptime will normally reduce the 6664 * latency. 6665 * 6666 * Default value: PJSUA_DEFAULT_AUDIO_FRAME_PTIME 6667 */ 6668 unsigned audio_frame_ptime; 6669 6670 /** 6671 * Specify maximum number of media ports to be created in the 6672 * conference bridge. Since all media terminate in the bridge 6673 * (calls, file player, file recorder, etc), the value must be 6674 * large enough to support all of them. However, the larger 6675 * the value, the more computations are performed. 6676 * 6677 * Default value: PJSUA_MAX_CONF_PORTS 6678 */ 6679 unsigned max_media_ports; 6680 6681 /** 6682 * Specify whether the media manager should manage its own 6683 * ioqueue for the RTP/RTCP sockets. If yes, ioqueue will be created 6684 * and at least one worker thread will be created too. If no, 6685 * the RTP/RTCP sockets will share the same ioqueue as SIP sockets, 6686 * and no worker thread is needed. 6687 * 6688 * Normally application would say yes here, unless it wants to 6689 * run everything from a single thread. 6690 */ 6691 pj_bool_t has_ioqueue; 6692 6693 /** 6694 * Specify the number of worker threads to handle incoming RTP 6695 * packets. A value of one is recommended for most applications. 6696 */ 6697 unsigned thread_cnt; 6698 6699 /** 6700 * Media quality, 0-10, according to this table: 6701 * 5-10: resampling use large filter, 6702 * 3-4: resampling use small filter, 6703 * 1-2: resampling use linear. 6704 * The media quality also sets speex codec quality/complexity to the 6705 * number. 6706 * 6707 * Default: 5 (PJSUA_DEFAULT_CODEC_QUALITY). 6708 */ 6709 unsigned quality; 6710 6711 /** 6712 * Specify default codec ptime. 6713 * 6714 * Default: 0 (codec specific) 6715 */ 6716 unsigned ptime; 6717 6718 /** 6719 * Disable VAD? 6720 * 6721 * Default: 0 (no (meaning VAD is enabled)) 6722 */ 6723 pj_bool_t no_vad; 6724 6725 /** 6726 * iLBC mode (20 or 30). 6727 * 6728 * Default: 30 (PJSUA_DEFAULT_ILBC_MODE) 6729 */ 6730 unsigned ilbc_mode; 6731 6732 /** 6733 * Percentage of RTP packet to drop in TX direction 6734 * (to simulate packet lost). 6735 * 6736 * Default: 0 6737 */ 6738 unsigned tx_drop_pct; 6739 6740 /** 6741 * Percentage of RTP packet to drop in RX direction 6742 * (to simulate packet lost). 6743 * 6744 * Default: 0 6745 */ 6746 unsigned rx_drop_pct; 6747 6748 /** 6749 * Echo canceller options (see #pjmedia_echo_create()). 6750 * Specify PJMEDIA_ECHO_USE_SW_ECHO here if application wishes 6751 * to use software echo canceller instead of device EC. 6752 * 6753 * Default: 0. 6754 */ 6755 unsigned ec_options; 6756 6757 /** 6758 * Echo canceller tail length, in miliseconds. 6759 * 6760 * Default: PJSUA_DEFAULT_EC_TAIL_LEN 6761 */ 6762 unsigned ec_tail_len; 6763 6764 /** 6765 * Audio capture buffer length, in milliseconds. 6766 * 6767 * Default: PJMEDIA_SND_DEFAULT_REC_LATENCY 6768 */ 6769 unsigned snd_rec_latency; 6770 6771 /** 6772 * Audio playback buffer length, in milliseconds. 6773 * 6774 * Default: PJMEDIA_SND_DEFAULT_PLAY_LATENCY 6775 */ 6776 unsigned snd_play_latency; 6777 6778 /** 6779 * Jitter buffer initial prefetch delay in msec. The value must be 6780 * between jb_min_pre and jb_max_pre below. If the value is 0, 6781 * prefetching will be disabled. 6782 * 6783 * Default: -1 (to use default stream settings, currently 0) 6784 */ 6785 int jb_init; 6786 6787 /** 6788 * Jitter buffer minimum prefetch delay in msec. 6789 * 6790 * Default: -1 (to use default stream settings, currently 60 msec) 6791 */ 6792 int jb_min_pre; 6793 6794 /** 6795 * Jitter buffer maximum prefetch delay in msec. 6796 * 6797 * Default: -1 (to use default stream settings, currently 240 msec) 6798 */ 6799 int jb_max_pre; 6800 6801 /** 6802 * Set maximum delay that can be accomodated by the jitter buffer msec. 6803 * 6804 * Default: -1 (to use default stream settings, currently 360 msec) 6805 */ 6806 int jb_max; 6807 6808 /** 6809 * Set the algorithm the jitter buffer uses to discard frames in order to 6810 * adjust the latency. 6811 * 6812 * Default: PJMEDIA_JB_DISCARD_PROGRESSIVE 6813 */ 6814 pjmedia_jb_discard_algo jb_discard_algo; 6815 6816 /** 6817 * Enable ICE 6818 */ 6819 pj_bool_t enable_ice; 6820 6821 /** 6822 * Set the maximum number of host candidates. 6823 * 6824 * Default: -1 (maximum not set) 6825 */ 6826 int ice_max_host_cands; 6827 6828 /** 6829 * ICE session options. 6830 */ 6831 pj_ice_sess_options ice_opt; 6832 6833 /** 6834 * Disable RTCP component. 6835 * 6836 * Default: no 6837 */ 6838 pj_bool_t ice_no_rtcp; 6839 6840 /** 6841 * Send re-INVITE/UPDATE every after ICE connectivity check regardless 6842 * the default ICE transport address is changed or not. When this is set 6843 * to PJ_FALSE, re-INVITE/UPDATE will be sent only when the default ICE 6844 * transport address is changed. 6845 * 6846 * Default: yes 6847 */ 6848 pj_bool_t ice_always_update; 6849 6850 /** 6851 * Enable TURN relay candidate in ICE. 6852 */ 6853 pj_bool_t enable_turn; 6854 6855 /** 6856 * Specify TURN domain name or host name, in in "DOMAIN:PORT" or 6857 * "HOST:PORT" format. 6858 */ 6859 pj_str_t turn_server; 6860 6861 /** 6862 * Specify the connection type to be used to the TURN server. Valid 6863 * values are PJ_TURN_TP_UDP, PJ_TURN_TP_TCP or PJ_TURN_TP_TLS. 6864 * 6865 * Default: PJ_TURN_TP_UDP 6866 */ 6867 pj_turn_tp_type turn_conn_type; 6868 6869 /** 6870 * Specify the credential to authenticate with the TURN server. 6871 */ 6872 pj_stun_auth_cred turn_auth_cred; 6873 6874 /** 6875 * This specifies TLS settings for TLS transport. It is only be used 6876 * when this TLS is used to connect to the TURN server. 6877 */ 6878 pj_turn_sock_tls_cfg turn_tls_setting; 6879 6880 /** 6881 * Specify idle time of sound device before it is automatically closed, 6882 * in seconds. Use value -1 to disable the auto-close feature of sound 6883 * device 6884 * 6885 * Default : 1 6886 */ 6887 int snd_auto_close_time; 6888 6889 /** 6890 * Specify whether built-in/native preview should be used if available. 6891 * In some systems, video input devices have built-in capability to show 6892 * preview window of the device. Using this built-in preview is preferable 6893 * as it consumes less CPU power. If built-in preview is not available, 6894 * the library will perform software rendering of the input. If this 6895 * field is set to PJ_FALSE, software preview will always be used. 6896 * 6897 * Default: PJ_TRUE 6898 */ 6899 pj_bool_t vid_preview_enable_native; 6900 6901 /** 6902 * Disable smart media update (ticket #1568). The smart media update 6903 * will check for any changes in the media properties after a successful 6904 * SDP negotiation and the media will only be reinitialized when any 6905 * change is found. When it is disabled, media streams will always be 6906 * reinitialized after a successful SDP negotiation. 6907 * 6908 * Note for third party media, the smart media update requires stream info 6909 * retrieval capability, see #PJSUA_THIRD_PARTY_STREAM_HAS_GET_INFO. 6910 * 6911 * Default: PJ_FALSE 6912 */ 6913 pj_bool_t no_smart_media_update; 6914 6915 /** 6916 * Omit RTCP SDES and BYE in outgoing RTCP packet, this setting will be 6917 * applied for both audio and video streams. Note that, when RTCP SDES 6918 * and BYE are set to be omitted, RTCP SDES will still be sent once when 6919 * the stream starts/stops and RTCP BYE will be sent once when the stream 6920 * stops. 6921 * 6922 * Default: PJ_FALSE 6923 */ 6924 pj_bool_t no_rtcp_sdes_bye; 6925 6926 /** 6927 * Optional callback for audio frame preview right before queued to 6928 * the speaker. 6929 * Notes: 6930 * - application MUST NOT block or perform long operation in the callback 6931 * as the callback may be executed in sound device thread 6932 * - when using software echo cancellation, application MUST NOT modify 6933 * the audio data from within the callback, otherwise the echo canceller 6934 * will not work properly. 6935 */ 6936 void (*on_aud_prev_play_frame)(pjmedia_frame *frame); 6937 6938 /** 6939 * Optional callback for audio frame preview recorded from the microphone 6940 * before being processed by any media component such as software echo 6941 * canceller. 6942 * Notes: 6943 * - application MUST NOT block or perform long operation in the callback 6944 * as the callback may be executed in sound device thread 6945 * - when using software echo cancellation, application MUST NOT modify 6946 * the audio data from within the callback, otherwise the echo canceller 6947 * will not work properly. 6948 */ 6949 void (*on_aud_prev_rec_frame)(pjmedia_frame *frame); 6950 }; 6951 6952 6953 /** 6954 * Use this function to initialize media config. 6955 * 6956 * @param cfg The media config to be initialized. 6957 */ 6958 PJ_DECL(void) pjsua_media_config_default(pjsua_media_config *cfg); 6959 6960 6961 /** 6962 * This structure describes codec information, which can be retrieved by 6963 * calling #pjsua_enum_codecs(). 6964 */ 6965 typedef struct pjsua_codec_info 6966 { 6967 /** 6968 * Codec unique identification. 6969 */ 6970 pj_str_t codec_id; 6971 6972 /** 6973 * Codec priority (integer 0-255). 6974 */ 6975 pj_uint8_t priority; 6976 6977 /** 6978 * Codec description. 6979 */ 6980 pj_str_t desc; 6981 6982 /** 6983 * Internal buffer. 6984 */ 6985 char buf_[64]; 6986 6987 } pjsua_codec_info; 6988 6989 6990 /** 6991 * This structure describes information about a particular media port that 6992 * has been registered into the conference bridge. Application can query 6993 * this info by calling #pjsua_conf_get_port_info(). 6994 */ 6995 typedef struct pjsua_conf_port_info 6996 { 6997 /** Conference port number. */ 6998 pjsua_conf_port_id slot_id; 6999 7000 /** Port name. */ 7001 pj_str_t name; 7002 7003 /** Format. */ 7004 pjmedia_format format; 7005 7006 /** Clock rate. */ 7007 unsigned clock_rate; 7008 7009 /** Number of channels. */ 7010 unsigned channel_count; 7011 7012 /** Samples per frame */ 7013 unsigned samples_per_frame; 7014 7015 /** Bits per sample */ 7016 unsigned bits_per_sample; 7017 7018 /** Tx level adjustment. */ 7019 float tx_level_adj; 7020 7021 /** Rx level adjustment. */ 7022 float rx_level_adj; 7023 7024 /** Number of listeners in the array. */ 7025 unsigned listener_cnt; 7026 7027 /** Array of listeners (in other words, ports where this port is 7028 * transmitting to). 7029 */ 7030 pjsua_conf_port_id listeners[PJSUA_MAX_CONF_PORTS]; 7031 7032 } pjsua_conf_port_info; 7033 7034 7035 /** 7036 * This structure holds information about custom media transport to 7037 * be registered to pjsua. 7038 */ 7039 typedef struct pjsua_media_transport 7040 { 7041 /** 7042 * Media socket information containing the address information 7043 * of the RTP and RTCP socket. 7044 */ 7045 pjmedia_sock_info skinfo; 7046 7047 /** 7048 * The media transport instance. 7049 */ 7050 pjmedia_transport *transport; 7051 7052 } pjsua_media_transport; 7053 7054 7055 /** 7056 * Sound device index constants. 7057 */ 7058 typedef enum pjsua_snd_dev_id 7059 { 7060 /** 7061 * Constant to denote default capture device. 7062 */ 7063 PJSUA_SND_DEFAULT_CAPTURE_DEV = PJMEDIA_AUD_DEFAULT_CAPTURE_DEV, 7064 7065 /** 7066 * Constant to denote default playback device. 7067 */ 7068 PJSUA_SND_DEFAULT_PLAYBACK_DEV = PJMEDIA_AUD_DEFAULT_PLAYBACK_DEV, 7069 7070 /** 7071 * Constant to denote that no sound device is being used. 7072 */ 7073 PJSUA_SND_NO_DEV = PJMEDIA_AUD_INVALID_DEV, 7074 7075 /** 7076 * Constant to denote null sound device. 7077 */ 7078 PJSUA_SND_NULL_DEV = -99 7079 7080 } pjsua_snd_dev_id; 7081 7082 /** 7083 * This enumeration specifies the sound device mode. 7084 */ 7085 typedef enum pjsua_snd_dev_mode 7086 { 7087 /** 7088 * Open sound device without mic (speaker only). 7089 */ 7090 PJSUA_SND_DEV_SPEAKER_ONLY = 1, 7091 7092 /** 7093 * Do not open sound device, after setting the sound device. 7094 */ 7095 PJSUA_SND_DEV_NO_IMMEDIATE_OPEN = 2 7096 7097 } pjsua_snd_dev_mode; 7098 7099 7100 /** 7101 * This structure specifies the parameters to set the sound device. 7102 * Use pjsua_snd_dev_param_default() to initialize this structure with 7103 * default values. 7104 */ 7105 typedef struct pjsua_snd_dev_param 7106 { 7107 /* 7108 * Capture dev id. 7109 * 7110 * Default: PJMEDIA_AUD_DEFAULT_CAPTURE_DEV 7111 */ 7112 int capture_dev; 7113 7114 /* 7115 * Playback dev id. 7116 * 7117 * Default: PJMEDIA_AUD_DEFAULT_PLAYBACK_DEV 7118 */ 7119 int playback_dev; 7120 7121 /* 7122 * Sound device mode, refer to #pjsua_snd_dev_mode. 7123 * 7124 * Default: 0 7125 */ 7126 unsigned mode; 7127 7128 } pjsua_snd_dev_param; 7129 7130 7131 /** 7132 * Initialize pjsua_snd_dev_param with default values. 7133 * 7134 * @param prm The parameter. 7135 */ 7136 PJ_DECL(void) pjsua_snd_dev_param_default(pjsua_snd_dev_param *prm); 7137 7138 7139 /** 7140 * This structure specifies the parameters for conference ports connection. 7141 * Use pjsua_conf_connect_param_default() to initialize this structure with 7142 * default values. 7143 */ 7144 typedef struct pjsua_conf_connect_param 7145 { 7146 /* 7147 * Signal level adjustment from the source to the sink to make it 7148 * louder or quieter. Value 1.0 means no level adjustment, 7149 * while value 0 means to mute the port. 7150 * 7151 * Default: 1.0 7152 */ 7153 float level; 7154 7155 } pjsua_conf_connect_param; 7156 7157 7158 /** 7159 * Initialize pjsua_conf_connect_param with default values. 7160 * 7161 * @param prm The parameter. 7162 */ 7163 PJ_DECL(void) pjsua_conf_connect_param_default(pjsua_conf_connect_param *prm); 7164 7165 7166 /** 7167 * Get maxinum number of conference ports. 7168 * 7169 * @return Maximum number of ports in the conference bridge. 7170 */ 7171 PJ_DECL(unsigned) pjsua_conf_get_max_ports(void); 7172 7173 7174 /** 7175 * Get current number of active ports in the bridge. 7176 * 7177 * @return The number. 7178 */ 7179 PJ_DECL(unsigned) pjsua_conf_get_active_ports(void); 7180 7181 7182 /** 7183 * Enumerate all conference ports. 7184 * 7185 * @param id Array of conference port ID to be initialized. 7186 * @param count On input, specifies max elements in the array. 7187 * On return, it contains actual number of elements 7188 * that have been initialized. 7189 * 7190 * @return PJ_SUCCESS on success, or the appropriate error code. 7191 */ 7192 PJ_DECL(pj_status_t) pjsua_enum_conf_ports(pjsua_conf_port_id id[], 7193 unsigned *count); 7194 7195 7196 /** 7197 * Get information about the specified conference port 7198 * 7199 * @param port_id Port identification. 7200 * @param info Pointer to store the port info. 7201 * 7202 * @return PJ_SUCCESS on success, or the appropriate error code. 7203 */ 7204 PJ_DECL(pj_status_t) pjsua_conf_get_port_info( pjsua_conf_port_id port_id, 7205 pjsua_conf_port_info *info); 7206 7207 7208 /** 7209 * Add arbitrary media port to PJSUA's conference bridge. Application 7210 * can use this function to add the media port that it creates. For 7211 * media ports that are created by PJSUA-LIB (such as calls, file player, 7212 * or file recorder), PJSUA-LIB will automatically add the port to 7213 * the bridge. 7214 * 7215 * @param pool Pool to use. 7216 * @param port Media port to be added to the bridge. 7217 * @param p_id Optional pointer to receive the conference 7218 * slot id. 7219 * 7220 * @return PJ_SUCCESS on success, or the appropriate error code. 7221 */ 7222 PJ_DECL(pj_status_t) pjsua_conf_add_port(pj_pool_t *pool, 7223 pjmedia_port *port, 7224 pjsua_conf_port_id *p_id); 7225 7226 7227 /** 7228 * Remove arbitrary slot from the conference bridge. Application should only 7229 * call this function if it registered the port manually with previous call 7230 * to #pjsua_conf_add_port(). 7231 * 7232 * @param port_id The slot id of the port to be removed. 7233 * 7234 * @return PJ_SUCCESS on success, or the appropriate error code. 7235 */ 7236 PJ_DECL(pj_status_t) pjsua_conf_remove_port(pjsua_conf_port_id port_id); 7237 7238 7239 /** 7240 * Establish unidirectional media flow from souce to sink. One source 7241 * may transmit to multiple destinations/sink. And if multiple 7242 * sources are transmitting to the same sink, the media will be mixed 7243 * together. Source and sink may refer to the same ID, effectively 7244 * looping the media. 7245 * 7246 * If bidirectional media flow is desired, application needs to call 7247 * this function twice, with the second one having the arguments 7248 * reversed. 7249 * 7250 * @param source Port ID of the source media/transmitter. 7251 * @param sink Port ID of the destination media/received. 7252 * 7253 * @return PJ_SUCCESS on success, or the appropriate error code. 7254 */ 7255 PJ_DECL(pj_status_t) pjsua_conf_connect(pjsua_conf_port_id source, 7256 pjsua_conf_port_id sink); 7257 7258 /** 7259 * Establish unidirectional media flow from source to sink. One source 7260 * may transmit to multiple destinations/sink. And if multiple 7261 * sources are transmitting to the same sink, the media will be mixed 7262 * together. Source and sink may refer to the same ID, effectively 7263 * looping the media. 7264 * 7265 * Signal level from the source to the sink can be adjusted by making 7266 * it louder or quieter via the parameter param. The level adjustment 7267 * will apply to a specific connection only (i.e. only for the signal 7268 * from the source to the sink), as compared to 7269 * pjsua_conf_adjust_tx_level()/pjsua_conf_adjust_rx_level() which 7270 * applies to all signals from/to that port. The signal adjustment 7271 * will be cumulative, in this following order: 7272 * signal from the source will be adjusted with the level specified 7273 * in pjsua_conf_adjust_rx_level(), then with the level specified 7274 * via this API, and finally with the level specified to the sink's 7275 * pjsua_conf_adjust_tx_level(). 7276 * 7277 * If bidirectional media flow is desired, application needs to call 7278 * this function twice, with the second one having the arguments 7279 * reversed. 7280 * 7281 * @param source Port ID of the source media/transmitter. 7282 * @param sink Port ID of the destination media/received. 7283 * @param prm Conference port connection param. If set to 7284 * NULL, default values will be used. 7285 * 7286 * @return PJ_SUCCESS on success, or the appropriate error code. 7287 */ 7288 PJ_DECL(pj_status_t) pjsua_conf_connect2(pjsua_conf_port_id source, 7289 pjsua_conf_port_id sink, 7290 const pjsua_conf_connect_param *prm); 7291 7292 7293 /** 7294 * Disconnect media flow from the source to destination port. 7295 * 7296 * @param source Port ID of the source media/transmitter. 7297 * @param sink Port ID of the destination media/received. 7298 * 7299 * @return PJ_SUCCESS on success, or the appropriate error code. 7300 */ 7301 PJ_DECL(pj_status_t) pjsua_conf_disconnect(pjsua_conf_port_id source, 7302 pjsua_conf_port_id sink); 7303 7304 7305 /** 7306 * Adjust the signal level to be transmitted from the bridge to the 7307 * specified port by making it louder or quieter. 7308 * 7309 * @param slot The conference bridge slot number. 7310 * @param level Signal level adjustment. Value 1.0 means no level 7311 * adjustment, while value 0 means to mute the port. 7312 * 7313 * @return PJ_SUCCESS on success, or the appropriate error code. 7314 */ 7315 PJ_DECL(pj_status_t) pjsua_conf_adjust_tx_level(pjsua_conf_port_id slot, 7316 float level); 7317 7318 /** 7319 * Adjust the signal level to be received from the specified port (to 7320 * the bridge) by making it louder or quieter. 7321 * 7322 * @param slot The conference bridge slot number. 7323 * @param level Signal level adjustment. Value 1.0 means no level 7324 * adjustment, while value 0 means to mute the port. 7325 * 7326 * @return PJ_SUCCESS on success, or the appropriate error code. 7327 */ 7328 PJ_DECL(pj_status_t) pjsua_conf_adjust_rx_level(pjsua_conf_port_id slot, 7329 float level); 7330 7331 /** 7332 * Get last signal level transmitted to or received from the specified port. 7333 * The signal level is an integer value in zero to 255, with zero indicates 7334 * no signal, and 255 indicates the loudest signal level. 7335 * 7336 * @param slot The conference bridge slot number. 7337 * @param tx_level Optional argument to receive the level of signal 7338 * transmitted to the specified port (i.e. the direction 7339 * is from the bridge to the port). 7340 * @param rx_level Optional argument to receive the level of signal 7341 * received from the port (i.e. the direction is from the 7342 * port to the bridge). 7343 * 7344 * @return PJ_SUCCESS on success. 7345 */ 7346 PJ_DECL(pj_status_t) pjsua_conf_get_signal_level(pjsua_conf_port_id slot, 7347 unsigned *tx_level, 7348 unsigned *rx_level); 7349 7350 7351 /***************************************************************************** 7352 * File player and playlist. 7353 */ 7354 7355 /** 7356 * Create a file player, and automatically add this player to 7357 * the conference bridge. 7358 * 7359 * @param filename The filename to be played. Currently only 7360 * WAV files are supported, and the WAV file MUST be 7361 * formatted as 16bit PCM mono/single channel (any 7362 * clock rate is supported). 7363 * @param options Optional option flag. Application may specify 7364 * PJMEDIA_FILE_NO_LOOP to prevent playback loop. 7365 * @param p_id Pointer to receive player ID. 7366 * 7367 * @return PJ_SUCCESS on success, or the appropriate error code. 7368 */ 7369 PJ_DECL(pj_status_t) pjsua_player_create(const pj_str_t *filename, 7370 unsigned options, 7371 pjsua_player_id *p_id); 7372 7373 7374 /** 7375 * Create a file playlist media port, and automatically add the port 7376 * to the conference bridge. 7377 * 7378 * @param file_names Array of file names to be added to the play list. 7379 * Note that the files must have the same clock rate, 7380 * number of channels, and number of bits per sample. 7381 * @param file_count Number of files in the array. 7382 * @param label Optional label to be set for the media port. 7383 * @param options Optional option flag. Application may specify 7384 * PJMEDIA_FILE_NO_LOOP to prevent looping. 7385 * @param p_id Optional pointer to receive player ID. 7386 * 7387 * @return PJ_SUCCESS on success, or the appropriate error code. 7388 */ 7389 PJ_DECL(pj_status_t) pjsua_playlist_create(const pj_str_t file_names[], 7390 unsigned file_count, 7391 const pj_str_t *label, 7392 unsigned options, 7393 pjsua_player_id *p_id); 7394 7395 /** 7396 * Get conference port ID associated with player or playlist. 7397 * 7398 * @param id The file player ID. 7399 * 7400 * @return Conference port ID associated with this player. 7401 */ 7402 PJ_DECL(pjsua_conf_port_id) pjsua_player_get_conf_port(pjsua_player_id id); 7403 7404 7405 /** 7406 * Get the media port for the player or playlist. 7407 * 7408 * @param id The player ID. 7409 * @param p_port The media port associated with the player. 7410 * 7411 * @return PJ_SUCCESS on success. 7412 */ 7413 PJ_DECL(pj_status_t) pjsua_player_get_port(pjsua_player_id id, 7414 pjmedia_port **p_port); 7415 7416 /** 7417 * Get additional info about the file player. This operation is not valid 7418 * for playlist. 7419 * 7420 * @param port The file player ID. 7421 * @param info The info. 7422 * 7423 * @return PJ_SUCCESS on success or the appropriate error code. 7424 */ 7425 PJ_DECL(pj_status_t) pjsua_player_get_info(pjsua_player_id id, 7426 pjmedia_wav_player_info *info); 7427 7428 7429 /** 7430 * Get playback position. This operation is not valid for playlist. 7431 * 7432 * @param id The file player ID. 7433 * 7434 * @return The current playback position, in samples. On error, 7435 * return the error code as negative value. 7436 */ 7437 PJ_DECL(pj_ssize_t) pjsua_player_get_pos(pjsua_player_id id); 7438 7439 /** 7440 * Set playback position. This operation is not valid for playlist. 7441 * 7442 * @param id The file player ID. 7443 * @param samples The playback position, in samples. Application can 7444 * specify zero to re-start the playback. 7445 * 7446 * @return PJ_SUCCESS on success, or the appropriate error code. 7447 */ 7448 PJ_DECL(pj_status_t) pjsua_player_set_pos(pjsua_player_id id, 7449 pj_uint32_t samples); 7450 7451 /** 7452 * Close the file of playlist, remove the player from the bridge, and free 7453 * resources associated with the file player or playlist. 7454 * 7455 * @param id The file player ID. 7456 * 7457 * @return PJ_SUCCESS on success, or the appropriate error code. 7458 */ 7459 PJ_DECL(pj_status_t) pjsua_player_destroy(pjsua_player_id id); 7460 7461 7462 /***************************************************************************** 7463 * File recorder. 7464 */ 7465 7466 /** 7467 * Create a file recorder, and automatically connect this recorder to 7468 * the conference bridge. The recorder currently supports recording WAV file. 7469 * The type of the recorder to use is determined by the extension of the file 7470 * (e.g. ".wav"). 7471 * 7472 * @param filename Output file name. The function will determine the 7473 * default format to be used based on the file extension. 7474 * Currently ".wav" is supported on all platforms. 7475 * @param enc_type Optionally specify the type of encoder to be used to 7476 * compress the media, if the file can support different 7477 * encodings. This value must be zero for now. 7478 * @param enc_param Optionally specify codec specific parameter to be 7479 * passed to the file writer. 7480 * For .WAV recorder, this value must be NULL. 7481 * @param max_size Maximum file size. Specify zero or -1 to remove size 7482 * limitation. This value must be zero or -1 for now. 7483 * @param options Optional options. 7484 * @param p_id Pointer to receive the recorder instance. 7485 * 7486 * @return PJ_SUCCESS on success, or the appropriate error code. 7487 */ 7488 PJ_DECL(pj_status_t) pjsua_recorder_create(const pj_str_t *filename, 7489 unsigned enc_type, 7490 void *enc_param, 7491 pj_ssize_t max_size, 7492 unsigned options, 7493 pjsua_recorder_id *p_id); 7494 7495 7496 /** 7497 * Get conference port associated with recorder. 7498 * 7499 * @param id The recorder ID. 7500 * 7501 * @return Conference port ID associated with this recorder. 7502 */ 7503 PJ_DECL(pjsua_conf_port_id) pjsua_recorder_get_conf_port(pjsua_recorder_id id); 7504 7505 7506 /** 7507 * Get the media port for the recorder. 7508 * 7509 * @param id The recorder ID. 7510 * @param p_port The media port associated with the recorder. 7511 * 7512 * @return PJ_SUCCESS on success. 7513 */ 7514 PJ_DECL(pj_status_t) pjsua_recorder_get_port(pjsua_recorder_id id, 7515 pjmedia_port **p_port); 7516 7517 7518 /** 7519 * Destroy recorder (this will complete recording). 7520 * 7521 * @param id The recorder ID. 7522 * 7523 * @return PJ_SUCCESS on success, or the appropriate error code. 7524 */ 7525 PJ_DECL(pj_status_t) pjsua_recorder_destroy(pjsua_recorder_id id); 7526 7527 7528 /***************************************************************************** 7529 * Sound devices. 7530 */ 7531 7532 /** 7533 * Enum all audio devices installed in the system. 7534 * 7535 * @param info Array of info to be initialized. 7536 * @param count On input, specifies max elements in the array. 7537 * On return, it contains actual number of elements 7538 * that have been initialized. 7539 * 7540 * @return PJ_SUCCESS on success, or the appropriate error code. 7541 */ 7542 PJ_DECL(pj_status_t) pjsua_enum_aud_devs(pjmedia_aud_dev_info info[], 7543 unsigned *count); 7544 7545 /** 7546 * Enum all sound devices installed in the system (old API). 7547 * 7548 * @param info Array of info to be initialized. 7549 * @param count On input, specifies max elements in the array. 7550 * On return, it contains actual number of elements 7551 * that have been initialized. 7552 * 7553 * @return PJ_SUCCESS on success, or the appropriate error code. 7554 */ 7555 PJ_DECL(pj_status_t) pjsua_enum_snd_devs(pjmedia_snd_dev_info info[], 7556 unsigned *count); 7557 7558 /** 7559 * Get currently active sound devices. If sound devices has not been created 7560 * (for example when pjsua_start() is not called), it is possible that 7561 * the function returns PJ_SUCCESS with -1 as device IDs. 7562 * See also #pjsua_snd_dev_id constants. 7563 * 7564 * @param capture_dev On return it will be filled with device ID of the 7565 * capture device. 7566 * @param playback_dev On return it will be filled with device ID of the 7567 * device ID of the playback device. 7568 * 7569 * @return PJ_SUCCESS on success, or the appropriate error code. 7570 */ 7571 PJ_DECL(pj_status_t) pjsua_get_snd_dev(int *capture_dev, 7572 int *playback_dev); 7573 7574 7575 /** 7576 * Select or change sound device. Application may call this function at 7577 * any time to replace current sound device. 7578 * 7579 * @param capture_dev Device ID of the capture device. 7580 * @param playback_dev Device ID of the playback device. 7581 * 7582 * @return PJ_SUCCESS on success, or the appropriate error code. 7583 */ 7584 PJ_DECL(pj_status_t) pjsua_set_snd_dev(int capture_dev, 7585 int playback_dev); 7586 7587 /** 7588 * Select or change sound device according to the specified param. 7589 * 7590 * @param snd_param Sound device param. 7591 * 7592 * @return PJ_SUCCESS on success, or the appropriate error code. 7593 */ 7594 PJ_DECL(pj_status_t) pjsua_set_snd_dev2(pjsua_snd_dev_param *snd_param); 7595 7596 7597 /** 7598 * Set pjsua to use null sound device. The null sound device only provides 7599 * the timing needed by the conference bridge, and will not interract with 7600 * any hardware. 7601 * 7602 * @return PJ_SUCCESS on success, or the appropriate error code. 7603 */ 7604 PJ_DECL(pj_status_t) pjsua_set_null_snd_dev(void); 7605 7606 7607 /** 7608 * Disconnect the main conference bridge from any sound devices, and let 7609 * application connect the bridge to it's own sound device/master port. 7610 * 7611 * @return The port interface of the conference bridge, 7612 * so that application can connect this to it's own 7613 * sound device or master port. 7614 */ 7615 PJ_DECL(pjmedia_port*) pjsua_set_no_snd_dev(void); 7616 7617 7618 /** 7619 * Change the echo cancellation settings. 7620 * 7621 * The behavior of this function depends on whether the sound device is 7622 * currently active, and if it is, whether device or software AEC is 7623 * being used. 7624 * 7625 * If the sound device is currently active, and if the device supports AEC, 7626 * this function will forward the change request to the device and it will 7627 * be up to the device on whether support the request. If software AEC is 7628 * being used (the software EC will be used if the device does not support 7629 * AEC), this function will change the software EC settings. In all cases, 7630 * the setting will be saved for future opening of the sound device. 7631 * 7632 * If the sound device is not currently active, this will only change the 7633 * default AEC settings and the setting will be applied next time the 7634 * sound device is opened. 7635 * 7636 * @param tail_ms The tail length, in miliseconds. Set to zero to 7637 * disable AEC. 7638 * @param options Options to be passed to pjmedia_echo_create(). 7639 * Normally the value should be zero. 7640 * 7641 * @return PJ_SUCCESS on success. 7642 */ 7643 PJ_DECL(pj_status_t) pjsua_set_ec(unsigned tail_ms, unsigned options); 7644 7645 7646 /** 7647 * Get current echo canceller tail length. 7648 * 7649 * @param p_tail_ms Pointer to receive the tail length, in miliseconds. 7650 * If AEC is disabled, the value will be zero. 7651 * 7652 * @return PJ_SUCCESS on success. 7653 */ 7654 PJ_DECL(pj_status_t) pjsua_get_ec_tail(unsigned *p_tail_ms); 7655 7656 7657 /** 7658 * Get echo canceller statistics. 7659 * 7660 * @param p_stat Pointer to receive the stat. 7661 * 7662 * @return PJ_SUCCESS on success, or the appropriate error 7663 * code. 7664 */ 7665 PJ_DECL(pj_status_t) pjsua_get_ec_stat(pjmedia_echo_stat *p_stat); 7666 7667 7668 /** 7669 * Check whether the sound device is currently active. The sound device 7670 * may be inactive if the application has set the auto close feature to 7671 * non-zero (the snd_auto_close_time setting in #pjsua_media_config), or 7672 * if null sound device or no sound device has been configured via the 7673 * #pjsua_set_no_snd_dev() function. 7674 */ 7675 PJ_DECL(pj_bool_t) pjsua_snd_is_active(void); 7676 7677 7678 /** 7679 * Configure sound device setting to the sound device being used. If sound 7680 * device is currently active, the function will forward the setting to the 7681 * sound device instance to be applied immediately, if it supports it. 7682 * 7683 * The setting will be saved for future opening of the sound device, if the 7684 * "keep" argument is set to non-zero. If the sound device is currently 7685 * inactive, and the "keep" argument is false, this function will return 7686 * error. 7687 * 7688 * Note that in case the setting is kept for future use, it will be applied 7689 * to any devices, even when application has changed the sound device to be 7690 * used. 7691 * 7692 * Note also that the echo cancellation setting should be set with 7693 * #pjsua_set_ec() API instead. 7694 * 7695 * See also #pjmedia_aud_stream_set_cap() for more information about setting 7696 * an audio device capability. 7697 * 7698 * @param cap The sound device setting to change. 7699 * @param pval Pointer to value. Please see #pjmedia_aud_dev_cap 7700 * documentation about the type of value to be 7701 * supplied for each setting. 7702 * @param keep Specify whether the setting is to be kept for future 7703 * use. 7704 * 7705 * @return PJ_SUCCESS on success or the appropriate error code. 7706 */ 7707 PJ_DECL(pj_status_t) pjsua_snd_set_setting(pjmedia_aud_dev_cap cap, 7708 const void *pval, 7709 pj_bool_t keep); 7710 7711 /** 7712 * Retrieve a sound device setting. If sound device is currently active, 7713 * the function will forward the request to the sound device. If sound device 7714 * is currently inactive, and if application had previously set the setting 7715 * and mark the setting as kept, then that setting will be returned. 7716 * Otherwise, this function will return error. 7717 * 7718 * Note that echo cancellation settings should be retrieved with 7719 * #pjsua_get_ec_tail() API instead. 7720 * 7721 * @param cap The sound device setting to retrieve. 7722 * @param pval Pointer to receive the value. 7723 * Please see #pjmedia_aud_dev_cap documentation about 7724 * the type of value to be supplied for each setting. 7725 * 7726 * @return PJ_SUCCESS on success or the appropriate error code. 7727 */ 7728 PJ_DECL(pj_status_t) pjsua_snd_get_setting(pjmedia_aud_dev_cap cap, 7729 void *pval); 7730 7731 7732 /** 7733 * Opaque type of extra sound device, an additional sound device 7734 * beside the primary sound device (the one instantiated via 7735 * pjsua_set_snd_dev() or pjsua_set_snd_dev2()). This sound device is 7736 * also registered to conference bridge so it can be used as a normal 7737 * conference bridge port, e.g: connect it to/from other ports, 7738 * adjust/check audio level, etc. The conference bridge port ID can be 7739 * queried using pjsua_ext_snd_dev_get_conf_port(). 7740 * 7741 * Application may also use this API to improve media clock. Normally 7742 * media clock is driven by sound device in master port, but unfortunately 7743 * some sound devices may produce jittery clock. To improve media clock, 7744 * application can install Null Sound Device (i.e: using 7745 * pjsua_set_null_snd_dev()), which will act as a master port, and instantiate 7746 * the sound device as extra sound device. 7747 * 7748 * Note that extra sound device will not have auto-close upon idle feature. 7749 * Also note that currently extra sound device only supports mono channel. 7750 */ 7751 typedef struct pjsua_ext_snd_dev pjsua_ext_snd_dev; 7752 7753 7754 /** 7755 * Create an extra sound device and register it to conference bridge. 7756 * 7757 * @param snd_param Sound device port param. Currently this only supports 7758 * mono channel, so channel count must be set to 1. 7759 * @param p_snd The extra sound device instance. 7760 * 7761 * @return PJ_SUCCESS on success or the appropriate error code. 7762 */ 7763 PJ_DECL(pj_status_t) pjsua_ext_snd_dev_create(pjmedia_snd_port_param *param, 7764 pjsua_ext_snd_dev **p_snd); 7765 7766 7767 /** 7768 * Destroy an extra sound device and unregister it from conference bridge. 7769 * 7770 * @param p_snd The extra sound device instance. 7771 * 7772 * @return PJ_SUCCESS on success or the appropriate error code. 7773 */ 7774 PJ_DECL(pj_status_t) pjsua_ext_snd_dev_destroy(pjsua_ext_snd_dev *snd); 7775 7776 7777 /** 7778 * Get sound port instance of an extra sound device. 7779 * 7780 * @param snd The extra sound device instance. 7781 * 7782 * @return The sound port instance. 7783 */ 7784 PJ_DECL(pjmedia_snd_port*) pjsua_ext_snd_dev_get_snd_port( 7785 pjsua_ext_snd_dev *snd); 7786 7787 /** 7788 * Get conference port ID of an extra sound device. 7789 * 7790 * @param snd The extra sound device instance. 7791 * 7792 * @return The conference port ID. 7793 */ 7794 PJ_DECL(pjsua_conf_port_id) pjsua_ext_snd_dev_get_conf_port( 7795 pjsua_ext_snd_dev *snd); 7796 7797 7798 /***************************************************************************** 7799 * Codecs. 7800 */ 7801 7802 /** 7803 * Enum all supported codecs in the system. 7804 * 7805 * @param id Array of ID to be initialized. 7806 * @param count On input, specifies max elements in the array. 7807 * On return, it contains actual number of elements 7808 * that have been initialized. 7809 * 7810 * @return PJ_SUCCESS on success, or the appropriate error code. 7811 */ 7812 PJ_DECL(pj_status_t) pjsua_enum_codecs( pjsua_codec_info id[], 7813 unsigned *count ); 7814 7815 7816 /** 7817 * Change codec priority. 7818 * 7819 * @param codec_id Codec ID, which is a string that uniquely identify 7820 * the codec (such as "speex/8000"). Please see pjsua 7821 * manual or pjmedia codec reference for details. 7822 * @param priority Codec priority, 0-255, where zero means to disable 7823 * the codec. 7824 * 7825 * @return PJ_SUCCESS on success, or the appropriate error code. 7826 */ 7827 PJ_DECL(pj_status_t) pjsua_codec_set_priority( const pj_str_t *codec_id, 7828 pj_uint8_t priority ); 7829 7830 7831 /** 7832 * Get codec parameters. 7833 * 7834 * @param codec_id Codec ID. 7835 * @param param Structure to receive codec parameters. 7836 * 7837 * @return PJ_SUCCESS on success, or the appropriate error code. 7838 */ 7839 PJ_DECL(pj_status_t) pjsua_codec_get_param( const pj_str_t *codec_id, 7840 pjmedia_codec_param *param ); 7841 7842 7843 /** 7844 * Set codec parameters. 7845 * 7846 * @param codec_id Codec ID. 7847 * @param param Codec parameter to set. Set to NULL to reset 7848 * codec parameter to library default settings. 7849 * 7850 * @return PJ_SUCCESS on success, or the appropriate error code. 7851 */ 7852 PJ_DECL(pj_status_t) pjsua_codec_set_param( const pj_str_t *codec_id, 7853 const pjmedia_codec_param *param); 7854 7855 7856 #if DISABLED_FOR_TICKET_1185 7857 /** 7858 * Create UDP media transports for all the calls. This function creates 7859 * one UDP media transport for each call. 7860 * 7861 * @param cfg Media transport configuration. The "port" field in the 7862 * configuration is used as the start port to bind the 7863 * sockets. 7864 * 7865 * @return PJ_SUCCESS on success, or the appropriate error code. 7866 */ 7867 PJ_DECL(pj_status_t) 7868 pjsua_media_transports_create(const pjsua_transport_config *cfg); 7869 7870 7871 /** 7872 * Register custom media transports to be used by calls. There must 7873 * enough media transports for all calls. 7874 * 7875 * @param tp The media transport array. 7876 * @param count Number of elements in the array. This number MUST 7877 * match the number of maximum calls configured when 7878 * pjsua is created. 7879 * @param auto_delete Flag to indicate whether the transports should be 7880 * destroyed when pjsua is shutdown. 7881 * 7882 * @return PJ_SUCCESS on success, or the appropriate error code. 7883 */ 7884 PJ_DECL(pj_status_t) 7885 pjsua_media_transports_attach( pjsua_media_transport tp[], 7886 unsigned count, 7887 pj_bool_t auto_delete); 7888 #endif 7889 7890 7891 /* end of MEDIA API */ 7892 /** 7893 * @} 7894 */ 7895 7896 7897 /***************************************************************************** 7898 * VIDEO API 7899 */ 7900 7901 7902 /** 7903 * @defgroup PJSUA_LIB_VIDEO PJSUA-API Video 7904 * @ingroup PJSUA_LIB 7905 * @brief Video support 7906 * @{ 7907 */ 7908 7909 /* 7910 * Video devices API 7911 */ 7912 7913 /** 7914 * Get the number of video devices installed in the system. 7915 * 7916 * @return The number of devices. 7917 */ 7918 PJ_DECL(unsigned) pjsua_vid_dev_count(void); 7919 7920 /** 7921 * Retrieve the video device info for the specified device index. 7922 * 7923 * @param id The device index. 7924 * @param vdi Device info to be initialized. 7925 * 7926 * @return PJ_SUCCESS on success, or the appropriate error code. 7927 */ 7928 PJ_DECL(pj_status_t) pjsua_vid_dev_get_info(pjmedia_vid_dev_index id, 7929 pjmedia_vid_dev_info *vdi); 7930 7931 /** 7932 * Check whether the video capture device is currently active, i.e. if 7933 * a video preview has been started or there is a video call using 7934 * the device. This function will return PJ_FALSE for video renderer device. 7935 * 7936 * @param id The video device index. 7937 * 7938 * @return PJ_TRUE if active, PJ_FALSE otherwise. 7939 */ 7940 PJ_DECL(pj_bool_t) pjsua_vid_dev_is_active(pjmedia_vid_dev_index id); 7941 7942 /** 7943 * Configure the capability of a video capture device. If the device is 7944 * currently active (i.e. if there is a video call using the device or 7945 * a video preview has been started), the function will forward the setting 7946 * to the video device instance to be applied immediately, if it supports it. 7947 * 7948 * The setting will be saved for future opening of the video device, if the 7949 * "keep" argument is set to non-zero. If the video device is currently 7950 * inactive, and the "keep" argument is false, this function will return 7951 * error. 7952 * 7953 * Note: This function will only works for video capture devices. To 7954 * configure the setting of video renderer device instances, use 7955 * pjsua_vid_win API instead. 7956 * 7957 * Warning: If application refreshes the video device list, it needs to 7958 * manually update the settings to reflect the newly updated video device 7959 * indexes. See #pjmedia_vid_dev_refresh() for more information. 7960 * 7961 * See also #pjmedia_vid_stream_set_cap() for more information about setting 7962 * a video device capability. 7963 * 7964 * @param id The video device index. 7965 * @param cap The video device capability to change. 7966 * @param pval Pointer to value. Please see #pjmedia_vid_dev_cap 7967 * documentation about the type of value to be 7968 * supplied for each setting. 7969 * 7970 * @return PJ_SUCCESS on success or the appropriate error code. 7971 */ 7972 PJ_DECL(pj_status_t) pjsua_vid_dev_set_setting(pjmedia_vid_dev_index id, 7973 pjmedia_vid_dev_cap cap, 7974 const void *pval, 7975 pj_bool_t keep); 7976 7977 /** 7978 * Retrieve the value of a video capture device setting. If the device is 7979 * currently active (i.e. if there is a video call using the device or 7980 * a video preview has been started), the function will forward the request 7981 * to the video device. If video device is currently inactive, and if 7982 * application had previously set the setting and mark the setting as kept, 7983 * then that setting will be returned. Otherwise, this function will return 7984 * error. 7985 * The function only works for video capture device. 7986 * 7987 * @param id The video device index. 7988 * @param cap The video device capability to retrieve. 7989 * @param pval Pointer to receive the value. 7990 * Please see #pjmedia_vid_dev_cap documentation about 7991 * the type of value to be supplied for each setting. 7992 * 7993 * @return PJ_SUCCESS on success or the appropriate error code. 7994 */ 7995 PJ_DECL(pj_status_t) pjsua_vid_dev_get_setting(pjmedia_vid_dev_index id, 7996 pjmedia_vid_dev_cap cap, 7997 void *pval); 7998 7999 /** 8000 * Enum all video devices installed in the system. 8001 * 8002 * @param info Array of info to be initialized. 8003 * @param count On input, specifies max elements in the array. 8004 * On return, it contains actual number of elements 8005 * that have been initialized. 8006 * 8007 * @return PJ_SUCCESS on success, or the appropriate error code. 8008 */ 8009 PJ_DECL(pj_status_t) pjsua_vid_enum_devs(pjmedia_vid_dev_info info[], 8010 unsigned *count); 8011 8012 8013 /* 8014 * Video preview API 8015 */ 8016 8017 /** 8018 * Parameters for starting video preview with pjsua_vid_preview_start(). 8019 * Application should initialize this structure with 8020 * pjsua_vid_preview_param_default(). 8021 */ 8022 typedef struct pjsua_vid_preview_param 8023 { 8024 /** 8025 * Device ID for the video renderer to be used for rendering the 8026 * capture stream for preview. This parameter is ignored if native 8027 * preview is being used. 8028 * 8029 * Default: PJMEDIA_VID_DEFAULT_RENDER_DEV 8030 */ 8031 pjmedia_vid_dev_index rend_id; 8032 8033 /** 8034 * Show window initially. 8035 * 8036 * Default: PJ_TRUE. 8037 */ 8038 pj_bool_t show; 8039 8040 /** 8041 * Window flags. The value is a bitmask combination of 8042 * #pjmedia_vid_dev_wnd_flag. 8043 * 8044 * Default: 0. 8045 */ 8046 unsigned wnd_flags; 8047 8048 /** 8049 * Media format. Initialize this with #pjmedia_format_init_video(). 8050 * If left unitialized, this parameter will not be used. 8051 */ 8052 pjmedia_format format; 8053 8054 /** 8055 * Optional output window to be used to display the video preview. 8056 * This parameter will only be used if the video device supports 8057 * PJMEDIA_VID_DEV_CAP_OUTPUT_WINDOW capability and the capability 8058 * is not read-only. 8059 */ 8060 pjmedia_vid_dev_hwnd wnd; 8061 8062 } pjsua_vid_preview_param; 8063 8064 8065 /** 8066 * Initialize pjsua_vid_preview_param 8067 * 8068 * @param p The parameter to be initialized. 8069 */ 8070 PJ_DECL(void) pjsua_vid_preview_param_default(pjsua_vid_preview_param *p); 8071 8072 /** 8073 * Determine if the specified video input device has built-in native 8074 * preview capability. This is a convenience function that is equal to 8075 * querying device's capability for PJMEDIA_VID_DEV_CAP_INPUT_PREVIEW 8076 * capability. 8077 * 8078 * @param id The capture device ID. 8079 * 8080 * @return PJ_TRUE if it has. 8081 */ 8082 PJ_DECL(pj_bool_t) pjsua_vid_preview_has_native(pjmedia_vid_dev_index id); 8083 8084 /** 8085 * Start video preview window for the specified capture device. 8086 * 8087 * @param id The capture device ID where its preview will be 8088 * started. 8089 * @param p Optional video preview parameters. Specify NULL 8090 * to use default values. 8091 * 8092 * @return PJ_SUCCESS on success, or the appropriate error code. 8093 */ 8094 PJ_DECL(pj_status_t) pjsua_vid_preview_start(pjmedia_vid_dev_index id, 8095 const pjsua_vid_preview_param *p); 8096 8097 /** 8098 * Get the preview window handle associated with the capture device, if any. 8099 * 8100 * @param id The capture device ID. 8101 * 8102 * @return The window ID of the preview window for the 8103 * specified capture device ID, or PJSUA_INVALID_ID if 8104 * preview has not been started for the device. 8105 */ 8106 PJ_DECL(pjsua_vid_win_id) pjsua_vid_preview_get_win(pjmedia_vid_dev_index id); 8107 8108 /** 8109 * Get video conference slot ID of the specified capture device, if any. 8110 * 8111 * @param id The capture device ID. 8112 * 8113 * @return The video conference slot ID of the specified capture 8114 * device ID, or PJSUA_INVALID_ID if preview has not been 8115 * started for the device. 8116 */ 8117 PJ_DECL(pjsua_conf_port_id) pjsua_vid_preview_get_vid_conf_port( 8118 pjmedia_vid_dev_index id); 8119 8120 /** 8121 * Stop video preview. 8122 * 8123 * @param id The capture device ID. 8124 * 8125 * @return PJ_SUCCESS on success, or the appropriate error code. 8126 */ 8127 PJ_DECL(pj_status_t) pjsua_vid_preview_stop(pjmedia_vid_dev_index id); 8128 8129 8130 /* 8131 * Video window manipulation API. 8132 */ 8133 8134 /** 8135 * This structure describes video window info. 8136 */ 8137 typedef struct pjsua_vid_win_info 8138 { 8139 /** 8140 * Flag to indicate whether this window is a native window, 8141 * such as created by built-in preview device. If this field is 8142 * PJ_TRUE, only the native window handle field of this 8143 * structure is valid. 8144 */ 8145 pj_bool_t is_native; 8146 8147 /** 8148 * Native window handle. 8149 */ 8150 pjmedia_vid_dev_hwnd hwnd; 8151 8152 /** 8153 * Renderer device ID. 8154 */ 8155 pjmedia_vid_dev_index rdr_dev; 8156 8157 /** 8158 * Renderer port ID in the video conference bridge. 8159 */ 8160 pjsua_conf_port_id slot_id; 8161 8162 /** 8163 * Window show status. The window is hidden if false. 8164 */ 8165 pj_bool_t show; 8166 8167 /** 8168 * Window position. 8169 */ 8170 pjmedia_coord pos; 8171 8172 /** 8173 * Window size. 8174 */ 8175 pjmedia_rect_size size; 8176 8177 } pjsua_vid_win_info; 8178 8179 8180 /** 8181 * Enumerates all video windows. 8182 * 8183 * @param id Array of window ID to be initialized. 8184 * @param count On input, specifies max elements in the array. 8185 * On return, it contains actual number of elements 8186 * that have been initialized. 8187 * 8188 * @return PJ_SUCCESS on success, or the appropriate error code. 8189 */ 8190 PJ_DECL(pj_status_t) pjsua_vid_enum_wins(pjsua_vid_win_id wids[], 8191 unsigned *count); 8192 8193 8194 /** 8195 * Get window info. 8196 * 8197 * @param wid The video window ID. 8198 * @param wi The video window info to be initialized. 8199 * 8200 * @return PJ_SUCCESS on success, or the appropriate error code. 8201 */ 8202 PJ_DECL(pj_status_t) pjsua_vid_win_get_info(pjsua_vid_win_id wid, 8203 pjsua_vid_win_info *wi); 8204 8205 /** 8206 * Show or hide window. This operation is not valid for native windows 8207 * (pjsua_vid_win_info.is_native=PJ_TRUE), on which native windowing API 8208 * must be used instead. 8209 * 8210 * @param wid The video window ID. 8211 * @param show Set to PJ_TRUE to show the window, PJ_FALSE to 8212 * hide the window. 8213 * 8214 * @return PJ_SUCCESS on success, or the appropriate error code. 8215 */ 8216 PJ_DECL(pj_status_t) pjsua_vid_win_set_show(pjsua_vid_win_id wid, 8217 pj_bool_t show); 8218 8219 /** 8220 * Set video window position. This operation is not valid for native windows 8221 * (pjsua_vid_win_info.is_native=PJ_TRUE), on which native windowing API 8222 * must be used instead. 8223 * 8224 * @param wid The video window ID. 8225 * @param pos The window position. 8226 * 8227 * @return PJ_SUCCESS on success, or the appropriate error code. 8228 */ 8229 PJ_DECL(pj_status_t) pjsua_vid_win_set_pos(pjsua_vid_win_id wid, 8230 const pjmedia_coord *pos); 8231 8232 /** 8233 * Resize window. This operation is not valid for native windows 8234 * (pjsua_vid_win_info.is_native=PJ_TRUE), on which native windowing API 8235 * must be used instead. 8236 * 8237 * @param wid The video window ID. 8238 * @param size The new window size. 8239 * 8240 * @return PJ_SUCCESS on success, or the appropriate error code. 8241 */ 8242 PJ_DECL(pj_status_t) pjsua_vid_win_set_size(pjsua_vid_win_id wid, 8243 const pjmedia_rect_size *size); 8244 8245 /** 8246 * Set output window. This operation is valid only when the underlying 8247 * video device supports PJMEDIA_VIDEO_DEV_CAP_OUTPUT_WINDOW capability AND 8248 * allows the output window to be changed on-the-fly. Currently it is only 8249 * supported on Android. 8250 * 8251 * @param wid The video window ID. 8252 * @param win The new output window. 8253 * 8254 * @return PJ_SUCCESS on success, or the appropriate error code. 8255 */ 8256 PJ_DECL(pj_status_t) pjsua_vid_win_set_win(pjsua_vid_win_id wid, 8257 const pjmedia_vid_dev_hwnd *win); 8258 8259 /** 8260 * Rotate the video window. This function will change the video orientation 8261 * and also possibly the video window size (width and height get swapped). 8262 * This operation is not valid for native windows (pjsua_vid_win_info.is_native 8263 * =PJ_TRUE), on which native windowing API must be used instead. 8264 * 8265 * @param wid The video window ID. 8266 * @param angle The rotation angle in degrees, must be multiple of 90. 8267 * Specify positive value for clockwise rotation or 8268 * negative value for counter-clockwise rotation. 8269 * 8270 * @return PJ_SUCCESS on success, or the appropriate error code. 8271 */ 8272 PJ_DECL(pj_status_t) pjsua_vid_win_rotate(pjsua_vid_win_id wid, 8273 int angle); 8274 8275 8276 /** 8277 * Set video window full-screen. This operation is valid only when the 8278 * underlying video device supports PJMEDIA_VID_DEV_CAP_OUTPUT_FULLSCREEN 8279 * capability. Currently it is only supported on SDL backend. 8280 * 8281 * @param wid The video window ID. 8282 * @param enabled Set to PJ_TRUE if full screen is desired, PJ_FALSE 8283 * otherwise. 8284 * 8285 * @return PJ_SUCCESS on success, or the appropriate error code. 8286 */ 8287 PJ_DECL(pj_status_t) pjsua_vid_win_set_fullscreen(pjsua_vid_win_id wid, 8288 pj_bool_t enabled); 8289 8290 /* 8291 * Video codecs API 8292 */ 8293 8294 /** 8295 * Enum all supported video codecs in the system. 8296 * 8297 * @param id Array of ID to be initialized. 8298 * @param count On input, specifies max elements in the array. 8299 * On return, it contains actual number of elements 8300 * that have been initialized. 8301 * 8302 * @return PJ_SUCCESS on success, or the appropriate error code. 8303 */ 8304 PJ_DECL(pj_status_t) pjsua_vid_enum_codecs( pjsua_codec_info id[], 8305 unsigned *count ); 8306 8307 8308 /** 8309 * Change video codec priority. 8310 * 8311 * @param codec_id Codec ID, which is a string that uniquely identify 8312 * the codec (such as "H263/90000"). Please see pjsua 8313 * manual or pjmedia codec reference for details. 8314 * @param priority Codec priority, 0-255, where zero means to disable 8315 * the codec. 8316 * 8317 * @return PJ_SUCCESS on success, or the appropriate error code. 8318 */ 8319 PJ_DECL(pj_status_t) pjsua_vid_codec_set_priority( const pj_str_t *codec_id, 8320 pj_uint8_t priority ); 8321 8322 8323 /** 8324 * Get video codec parameters. 8325 * 8326 * @param codec_id Codec ID. 8327 * @param param Structure to receive video codec parameters. 8328 * 8329 * @return PJ_SUCCESS on success, or the appropriate error code. 8330 */ 8331 PJ_DECL(pj_status_t) pjsua_vid_codec_get_param( 8332 const pj_str_t *codec_id, 8333 pjmedia_vid_codec_param *param); 8334 8335 8336 /** 8337 * Set video codec parameters. 8338 * 8339 * @param codec_id Codec ID. 8340 * @param param Codec parameter to set. Set to NULL to reset 8341 * codec parameter to library default settings. 8342 * 8343 * @return PJ_SUCCESS on success, or the appropriate error code. 8344 */ 8345 PJ_DECL(pj_status_t) pjsua_vid_codec_set_param( 8346 const pj_str_t *codec_id, 8347 const pjmedia_vid_codec_param *param); 8348 8349 8350 /* 8351 * Video conference API 8352 */ 8353 8354 /** 8355 * This structure describes information about a particular video media port 8356 * that has been registered into the video conference bridge. Application 8357 * can query this info by calling #pjsua_vid_conf_get_port_info(). 8358 */ 8359 typedef struct pjsua_vid_conf_port_info 8360 { 8361 /** Conference port number. */ 8362 pjsua_conf_port_id slot_id; 8363 8364 /** Port name. */ 8365 pj_str_t name; 8366 8367 /** Format. */ 8368 pjmedia_format format; 8369 8370 /** Number of listeners in the array. */ 8371 unsigned listener_cnt; 8372 8373 /** Array of listeners (in other words, ports where this port is 8374 * transmitting to). 8375 */ 8376 pjsua_conf_port_id listeners[PJSUA_MAX_CONF_PORTS]; 8377 8378 /** Number of transmitters in the array. */ 8379 unsigned transmitter_cnt; 8380 8381 /** Array of transmitters (in other words, ports where this port is 8382 * receiving from). 8383 */ 8384 pjsua_conf_port_id transmitters[PJSUA_MAX_CONF_PORTS]; 8385 8386 } pjsua_vid_conf_port_info; 8387 8388 8389 /** 8390 * Get current number of active ports in the bridge. 8391 * 8392 * @return The number. 8393 */ 8394 PJ_DECL(unsigned) pjsua_vid_conf_get_active_ports(void); 8395 8396 8397 /** 8398 * Enumerate all video conference ports. 8399 * 8400 * @param id Array of conference port ID to be initialized. 8401 * @param count On input, specifies max elements in the array. 8402 * On return, it contains actual number of elements 8403 * that have been initialized. 8404 * 8405 * @return PJ_SUCCESS on success, or the appropriate error code. 8406 */ 8407 PJ_DECL(pj_status_t) pjsua_vid_conf_enum_ports(pjsua_conf_port_id id[], 8408 unsigned *count); 8409 8410 8411 /** 8412 * Get information about the specified video conference port 8413 * 8414 * @param port_id Port identification. 8415 * @param info Pointer to store the port info. 8416 * 8417 * @return PJ_SUCCESS on success, or the appropriate error code. 8418 */ 8419 PJ_DECL(pj_status_t) pjsua_vid_conf_get_port_info( 8420 pjsua_conf_port_id port_id, 8421 pjsua_vid_conf_port_info *info); 8422 8423 8424 /** 8425 * Add arbitrary video media port to PJSUA's video conference bridge. 8426 * Application can use this function to add the media port that it creates. 8427 * For media ports that are created by PJSUA-LIB (such as calls, AVI player), 8428 * PJSUA-LIB will automatically add the port to the bridge. 8429 * 8430 * @param pool Pool to use. 8431 * @param port Media port to be added to the bridge. 8432 * @param param Currently this is not used and must be set to NULL. 8433 * @param p_id Optional pointer to receive the conference 8434 * slot id. 8435 * 8436 * @return PJ_SUCCESS on success, or the appropriate error code. 8437 */ 8438 PJ_DECL(pj_status_t) pjsua_vid_conf_add_port(pj_pool_t *pool, 8439 pjmedia_port *port, 8440 const void *param, 8441 pjsua_conf_port_id *p_id); 8442 8443 8444 /** 8445 * Remove arbitrary slot from the video conference bridge. Application should 8446 * only call this function if it registered the port manually with previous 8447 * call to #pjsua_vid_conf_add_port(). 8448 * 8449 * @param port_id The slot id of the port to be removed. 8450 * 8451 * @return PJ_SUCCESS on success, or the appropriate error code. 8452 */ 8453 PJ_DECL(pj_status_t) pjsua_vid_conf_remove_port(pjsua_conf_port_id port_id); 8454 8455 8456 /** 8457 * Establish unidirectional video flow from souce to sink. One source 8458 * may transmit to multiple destinations/sink. And if multiple 8459 * sources are transmitting to the same sink, the video will be mixed 8460 * together (currently, each source will be resized down so all sources will 8461 * occupy the same portion in the sink video frame). Source and sink may 8462 * refer to the same ID, effectively looping the media. 8463 * 8464 * If bidirectional media flow is desired, application needs to call 8465 * this function twice, with the second one having the arguments 8466 * reversed. 8467 * 8468 * @param source Port ID of the source media/transmitter. 8469 * @param sink Port ID of the destination media/received. 8470 * @param param Currently this is not used and must be set to NULL. 8471 * 8472 * @return PJ_SUCCESS on success, or the appropriate error code. 8473 */ 8474 PJ_DECL(pj_status_t) pjsua_vid_conf_connect(pjsua_conf_port_id source, 8475 pjsua_conf_port_id sink, 8476 const void *param); 8477 8478 8479 /** 8480 * Disconnect video flow from the source to destination port. 8481 * 8482 * @param source Port ID of the source media/transmitter. 8483 * @param sink Port ID of the destination media/received. 8484 * 8485 * @return PJ_SUCCESS on success, or the appropriate error code. 8486 */ 8487 PJ_DECL(pj_status_t) pjsua_vid_conf_disconnect(pjsua_conf_port_id source, 8488 pjsua_conf_port_id sink); 8489 8490 8491 8492 /* end of VIDEO API */ 8493 /** 8494 * @} 8495 */ 8496 8497 8498 /** 8499 * @} 8500 */ 8501 8502 PJ_END_DECL 8503 8504 8505 #endif /* __PJSUA_H__ */ 8506