1 /* $Id$ */ 2 /* 3 * Copyright (C) 2013 Teluu Inc. (http://www.teluu.com) 4 * 5 * This program is free software; you can redistribute it and/or modify 6 * it under the terms of the GNU General Public License as published by 7 * the Free Software Foundation; either version 2 of the License, or 8 * (at your option) any later version. 9 * 10 * This program is distributed in the hope that it will be useful, 11 * but WITHOUT ANY WARRANTY; without even the implied warranty of 12 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the 13 * GNU General Public License for more details. 14 * 15 * You should have received a copy of the GNU General Public License 16 * along with this program; if not, write to the Free Software 17 * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA 18 */ 19 #ifndef __PJSUA2_UA_HPP__ 20 #define __PJSUA2_UA_HPP__ 21 22 /** 23 * @file pjsua2/endpoint.hpp 24 * @brief PJSUA2 Base Agent Operation 25 */ 26 #include <pjsua2/persistent.hpp> 27 #include <pjsua2/media.hpp> 28 #include <pjsua2/siptypes.hpp> 29 #include <list> 30 #include <map> 31 32 /** PJSUA2 API is inside pj namespace */ 33 namespace pj 34 { 35 36 /** 37 * @defgroup PJSUA2_UA Endpoint 38 * @ingroup PJSUA2_Ref 39 * @{ 40 */ 41 42 using std::string; 43 using std::vector; 44 45 46 ////////////////////////////////////////////////////////////////////////////// 47 48 /** 49 * Argument to Endpoint::onNatDetectionComplete() callback. 50 */ 51 struct OnNatDetectionCompleteParam 52 { 53 /** 54 * Status of the detection process. If this value is not PJ_SUCCESS, 55 * the detection has failed and \a nat_type field will contain 56 * PJ_STUN_NAT_TYPE_UNKNOWN. 57 */ 58 pj_status_t status; 59 60 /** 61 * The text describing the status, if the status is not PJ_SUCCESS. 62 */ 63 string reason; 64 65 /** 66 * This contains the NAT type as detected by the detection procedure. 67 * This value is only valid when the \a status is PJ_SUCCESS. 68 */ 69 pj_stun_nat_type natType; 70 71 /** 72 * Text describing that NAT type. 73 */ 74 string natTypeName; 75 76 }; 77 78 /** 79 * Argument to Endpoint::onNatCheckStunServersComplete() callback. 80 */ 81 struct OnNatCheckStunServersCompleteParam 82 { 83 /** 84 * Arbitrary user data that was passed to Endpoint::natCheckStunServers() 85 * function. 86 */ 87 Token userData; 88 89 /** 90 * This will contain PJ_SUCCESS if at least one usable STUN server 91 * is found, otherwise it will contain the last error code during 92 * the operation. 93 */ 94 pj_status_t status; 95 96 /** 97 * The server name that yields successful result. This will only 98 * contain value if status is successful. 99 */ 100 string name; 101 102 /** 103 * The server IP address and port in "IP:port" format. This will only 104 * contain value if status is successful. 105 */ 106 SocketAddress addr; 107 }; 108 109 /** 110 * Parameter of Endpoint::onTimer() callback. 111 */ 112 struct OnTimerParam 113 { 114 /** 115 * Arbitrary user data that was passed to Endpoint::utilTimerSchedule() 116 * function. 117 */ 118 Token userData; 119 120 /** 121 * The interval of this timer, in miliseconds. 122 */ 123 unsigned msecDelay; 124 }; 125 126 /** 127 * SSL certificate type and name structure. 128 */ 129 struct SslCertName 130 { 131 pj_ssl_cert_name_type type; /**< Name type */ 132 string name; /**< The name */ 133 134 public: 135 /** 136 * Default constructor 137 */ SslCertNamepj::SslCertName138 SslCertName() : type(PJ_SSL_CERT_NAME_UNKNOWN) 139 {} 140 }; 141 142 /** Array of SSL certificate type and name. */ 143 typedef std::vector<SslCertName> SslCertNameVector; 144 145 /** 146 * SSL certificate information. 147 */ 148 struct SslCertInfo 149 { 150 unsigned version; /**< Certificate version */ 151 unsigned char serialNo[20]; /**< Serial number, array 152 of octets, first index 153 is MSB */ 154 string subjectCn; /**< Subject common name */ 155 string subjectInfo; /**< One line subject, fields 156 are separated by slash, e.g: 157 "CN=sample.org/OU=HRD" */ 158 159 string issuerCn; /**< Issuer common name */ 160 string issuerInfo; /**< One line subject, fields 161 are separated by slash */ 162 163 TimeVal validityStart; /**< Validity start */ 164 TimeVal validityEnd; /**< Validity end */ 165 bool validityGmt; /**< Flag if validity 166 date/time use GMT */ 167 168 SslCertNameVector subjectAltName; /**< Subject alternative 169 name extension */ 170 171 string raw; /**< Raw certificate in PEM 172 format, only available 173 for remote certificate */ 174 175 public: 176 /** 177 * Constructor. 178 */ 179 SslCertInfo(); 180 181 /** 182 * Check if the info is set with empty values. 183 * 184 * @return True if the info is empty. 185 */ 186 bool isEmpty() const; 187 188 /** 189 * Convert from pjsip 190 */ 191 void fromPj(const pj_ssl_cert_info &info); 192 193 private: 194 bool empty; 195 }; 196 197 /** 198 * TLS transport information. 199 */ 200 struct TlsInfo 201 { 202 /** 203 * Describes whether secure socket connection is established, i.e: TLS/SSL 204 * handshaking has been done successfully. 205 */ 206 bool established; 207 208 /** 209 * Describes secure socket protocol being used, see #pj_ssl_sock_proto. 210 * Use bitwise OR operation to combine the protocol type. 211 */ 212 unsigned protocol; 213 214 /** 215 * Describes cipher suite being used, this will only be set when connection 216 * is established. 217 */ 218 pj_ssl_cipher cipher; 219 220 /** 221 * Describes cipher name being used, this will only be set when connection 222 * is established. 223 */ 224 string cipherName; 225 226 /** 227 * Describes local address. 228 */ 229 SocketAddress localAddr; 230 231 /** 232 * Describes remote address. 233 */ 234 SocketAddress remoteAddr; 235 236 /** 237 * Describes active local certificate info. Use SslCertInfo.isEmpty() 238 * to check if the local cert info is available. 239 */ 240 SslCertInfo localCertInfo; 241 242 /** 243 * Describes active remote certificate info. Use SslCertInfo.isEmpty() 244 * to check if the remote cert info is available. 245 */ 246 SslCertInfo remoteCertInfo; 247 248 /** 249 * Status of peer certificate verification. 250 */ 251 unsigned verifyStatus; 252 253 /** 254 * Error messages (if any) of peer certificate verification, based on 255 * the field verifyStatus above. 256 */ 257 StringVector verifyMsgs; 258 259 public: 260 /** 261 * Constructor. 262 */ 263 TlsInfo(); 264 265 /** 266 * Check if the info is set with empty values. 267 * 268 * @return True if the info is empty. 269 */ 270 bool isEmpty() const; 271 272 /** 273 * Convert from pjsip 274 */ 275 void fromPj(const pjsip_tls_state_info &info); 276 277 private: 278 bool empty; 279 }; 280 281 /** 282 * Parameter of Endpoint::onTransportState() callback. 283 */ 284 struct OnTransportStateParam 285 { 286 /** 287 * The transport handle. 288 */ 289 TransportHandle hnd; 290 291 /** 292 * The transport type. 293 */ 294 string type; 295 296 /** 297 * Transport current state. 298 */ 299 pjsip_transport_state state; 300 301 /** 302 * The last error code related to the transport state. 303 */ 304 pj_status_t lastError; 305 306 /** 307 * TLS transport info, only used if transport type is TLS. Use 308 * TlsInfo.isEmpty() to check if this info is available. 309 */ 310 TlsInfo tlsInfo; 311 }; 312 313 /** 314 * Parameter of Endpoint::onSelectAccount() callback. 315 */ 316 struct OnSelectAccountParam 317 { 318 /** 319 * The incoming request. 320 */ 321 SipRxData rdata; 322 323 /** 324 * The account index to be used to handle the request. 325 * Upon entry, this will be filled by the account index 326 * chosen by the library. Application may change it to 327 * another value to use another account. 328 */ 329 int accountIndex; 330 }; 331 332 /** 333 * Parameter of Endpoint::handleIpChange(). 334 */ 335 struct IpChangeParam { 336 /** 337 * If set to PJ_TRUE, this will restart the transport listener. 338 * 339 * Default : PJ_TRUE 340 */ 341 bool restartListener; 342 343 /** 344 * If \a restartListener is set to PJ_TRUE, some delay might be needed 345 * for the listener to be restarted. Use this to set the delay. 346 * 347 * Default : PJSUA_TRANSPORT_RESTART_DELAY_TIME 348 */ 349 unsigned restartLisDelay; 350 351 public: 352 /** 353 * Constructor. 354 */ 355 IpChangeParam(); 356 357 /** 358 * Export to pjsua_ip_change_param. 359 */ 360 pjsua_ip_change_param toPj() const; 361 362 /** 363 * Convert from pjsip 364 */ 365 void fromPj(const pjsua_ip_change_param ¶m); 366 }; 367 368 /** 369 * Information of Update contact on IP change progress. 370 */ 371 struct RegProgressParam 372 { 373 /** 374 * Indicate if this is a Register or Un-Register message. 375 */ 376 bool isRegister; 377 378 /** 379 * SIP status code received. 380 */ 381 int code; 382 }; 383 384 /** 385 * Parameter of Endpoint::onIpChangeProgress(). 386 */ 387 struct OnIpChangeProgressParam 388 { 389 /** 390 * The IP change progress operation. 391 */ 392 pjsua_ip_change_op op; 393 394 /** 395 * The operation progress status. 396 */ 397 pj_status_t status; 398 399 /** 400 * Information of the transport id. This is only available when the 401 * operation is PJSUA_IP_CHANGE_OP_RESTART_LIS. 402 */ 403 TransportId transportId; 404 405 /** 406 * Information of the account id. This is only available when the 407 * operation is: 408 * - PJSUA_IP_CHANGE_OP_ACC_SHUTDOWN_TP 409 * - PJSUA_IP_CHANGE_OP_ACC_UPDATE_CONTACT 410 * - PJSUA_IP_CHANGE_OP_ACC_HANGUP_CALLS 411 * - PJSUA_IP_CHANGE_OP_ACC_REINVITE_CALLS 412 */ 413 int accId; 414 415 /** 416 * Information of the call id. This is only available when the operation is 417 * PJSUA_IP_CHANGE_OP_ACC_HANGUP_CALLS or 418 * PJSUA_IP_CHANGE_OP_ACC_REINVITE_CALLS 419 */ 420 int callId; 421 422 /** 423 * Registration information. This is only available when the operation is 424 * PJSUA_IP_CHANGE_OP_ACC_UPDATE_CONTACT 425 */ 426 RegProgressParam regInfo; 427 }; 428 429 /** 430 * Parameter of Endpoint::onCallMediaEvent() callback. 431 */ 432 struct OnMediaEventParam 433 { 434 /** 435 * The media event. 436 */ 437 MediaEvent ev; 438 }; 439 440 ////////////////////////////////////////////////////////////////////////////// 441 /** 442 * SIP User Agent related settings. 443 */ 444 struct UaConfig : public PersistentObject 445 { 446 /** 447 * Maximum calls to support (default: 4). The value specified here 448 * must be smaller than the compile time maximum settings 449 * PJSUA_MAX_CALLS, which by default is 32. To increase this 450 * limit, the library must be recompiled with new PJSUA_MAX_CALLS 451 * value. 452 */ 453 unsigned maxCalls; 454 455 /** 456 * Number of worker threads. Normally application will want to have at 457 * least one worker thread, unless when it wants to poll the library 458 * periodically, which in this case the worker thread can be set to 459 * zero. 460 */ 461 unsigned threadCnt; 462 463 /** 464 * When this flag is non-zero, all callbacks that come from thread 465 * other than main thread will be posted to the main thread and 466 * to be executed by Endpoint::libHandleEvents() function. This 467 * includes the logging callback. Note that this will only work if 468 * threadCnt is set to zero and Endpoint::libHandleEvents() is 469 * performed by main thread. By default, the main thread is set 470 * from the thread that invoke Endpoint::libCreate() 471 * 472 * Default: false 473 */ 474 bool mainThreadOnly; 475 476 /** 477 * Array of nameservers to be used by the SIP resolver subsystem. 478 * The order of the name server specifies the priority (first name 479 * server will be used first, unless it is not reachable). 480 */ 481 StringVector nameserver; 482 483 /** 484 * Specify the URL of outbound proxies to visit for all outgoing requests. 485 * The outbound proxies will be used for all accounts, and it will 486 * be used to build the route set for outgoing requests. The final 487 * route set for outgoing requests will consists of the outbound proxies 488 * and the proxy configured in the account. 489 */ 490 StringVector outboundProxies; 491 492 /** 493 * Optional user agent string (default empty). If it's empty, no 494 * User-Agent header will be sent with outgoing requests. 495 */ 496 string userAgent; 497 498 /** 499 * Array of STUN servers to try. The library will try to resolve and 500 * contact each of the STUN server entry until it finds one that is 501 * usable. Each entry may be a domain name, host name, IP address, and 502 * it may contain an optional port number. For example: 503 * - "pjsip.org" (domain name) 504 * - "sip.pjsip.org" (host name) 505 * - "pjsip.org:33478" (domain name and a non-standard port number) 506 * - "10.0.0.1:3478" (IP address and port number) 507 * 508 * When nameserver is configured in the \a pjsua_config.nameserver field, 509 * if entry is not an IP address, it will be resolved with DNS SRV 510 * resolution first, and it will fallback to use DNS A resolution if this 511 * fails. Port number may be specified even if the entry is a domain name, 512 * in case the DNS SRV resolution should fallback to a non-standard port. 513 * 514 * When nameserver is not configured, entries will be resolved with 515 * pj_gethostbyname() if it's not an IP address. Port number may be 516 * specified if the server is not listening in standard STUN port. 517 */ 518 StringVector stunServer; 519 520 /** 521 * This specifies if the library should try to do an IPv6 resolution of 522 * the STUN servers if the IPv4 resolution fails. It can be useful 523 * in an IPv6-only environment, including on NAT64. 524 * 525 * Default: FALSE 526 */ 527 bool stunTryIpv6; 528 529 /** 530 * This specifies if the library startup should ignore failure with the 531 * STUN servers. If this is set to PJ_FALSE, the library will refuse to 532 * start if it fails to resolve or contact any of the STUN servers. 533 * 534 * Default: TRUE 535 */ 536 bool stunIgnoreFailure; 537 538 /** 539 * Support for adding and parsing NAT type in the SDP to assist 540 * troubleshooting. The valid values are: 541 * - 0: no information will be added in SDP, and parsing is disabled. 542 * - 1: only the NAT type number is added. 543 * - 2: add both NAT type number and name. 544 * 545 * Default: 1 546 */ 547 int natTypeInSdp; 548 549 /** 550 * Handle unsolicited NOTIFY requests containing message waiting 551 * indication (MWI) info. Unsolicited MWI is incoming NOTIFY requests 552 * which are not requested by client with SUBSCRIBE request. 553 * 554 * If this is enabled, the library will respond 200/OK to the NOTIFY 555 * request and forward the request to Endpoint::onMwiInfo() callback. 556 * 557 * See also AccountMwiConfig.enabled. 558 * 559 * Default: PJ_TRUE 560 */ 561 bool mwiUnsolicitedEnabled; 562 563 public: 564 /** 565 * Default constructor to initialize with default values. 566 */ 567 UaConfig(); 568 569 /** 570 * Construct from pjsua_config. 571 */ 572 void fromPj(const pjsua_config &ua_cfg); 573 574 /** 575 * Export to pjsua_config 576 */ 577 pjsua_config toPj() const; 578 579 /** 580 * Read this object from a container. 581 * 582 * @param node Container to write values from. 583 */ 584 virtual void readObject(const ContainerNode &node) PJSUA2_THROW(Error); 585 586 /** 587 * Write this object to a container. 588 * 589 * @param node Container to write values to. 590 */ 591 virtual void writeObject(ContainerNode &node) const PJSUA2_THROW(Error); 592 593 }; 594 595 596 /** 597 * Data containing log entry to be written by the LogWriter. 598 */ 599 struct LogEntry 600 { 601 /** Log verbosity level of this message */ 602 int level; 603 604 /** The log message */ 605 string msg; 606 607 /** ID of current thread */ 608 long threadId; 609 610 /** The name of the thread that writes this log */ 611 string threadName; 612 }; 613 614 615 /** 616 * Interface for writing log messages. Applications can inherit this class 617 * and supply it in the LogConfig structure to implement custom log 618 * writing facility. 619 */ 620 class LogWriter 621 { 622 public: 623 /** Destructor */ ~LogWriter()624 virtual ~LogWriter() {} 625 626 /** Write a log entry. */ 627 virtual void write(const LogEntry &entry) = 0; 628 }; 629 630 631 /** 632 * Logging configuration, which can be (optionally) specified when calling 633 * Lib::init(). 634 */ 635 struct LogConfig : public PersistentObject 636 { 637 /** Log incoming and outgoing SIP message? Yes! */ 638 unsigned msgLogging; 639 640 /** Input verbosity level. Value 5 is reasonable. */ 641 unsigned level; 642 643 /** Verbosity level for console. Value 4 is reasonable. */ 644 unsigned consoleLevel; 645 646 /** Log decoration. */ 647 unsigned decor; 648 649 /** Optional log filename if app wishes the library to write to log file. 650 */ 651 string filename; 652 653 /** 654 * Additional flags to be given to pj_file_open() when opening 655 * the log file. By default, the flag is PJ_O_WRONLY. Application 656 * may set PJ_O_APPEND here so that logs are appended to existing 657 * file instead of overwriting it. 658 * 659 * Default is 0. 660 */ 661 unsigned fileFlags; 662 663 /** 664 * Custom log writer, if required. This instance will be destroyed 665 * by the endpoint when the endpoint is destroyed. 666 */ 667 LogWriter *writer; 668 669 public: 670 /** Default constructor initialises with default values */ 671 LogConfig(); 672 673 /** Construct from pjsua_logging_config */ 674 void fromPj(const pjsua_logging_config &lc); 675 676 /** Generate pjsua_logging_config. */ 677 pjsua_logging_config toPj() const; 678 679 /** 680 * Read this object from a container. 681 * 682 * @param node Container to write values from. 683 */ 684 virtual void readObject(const ContainerNode &node) PJSUA2_THROW(Error); 685 686 /** 687 * Write this object to a container. 688 * 689 * @param node Container to write values to. 690 */ 691 virtual void writeObject(ContainerNode &node) const PJSUA2_THROW(Error); 692 }; 693 694 695 /** 696 * This structure describes media configuration, which will be specified 697 * when calling Lib::init(). 698 */ 699 struct MediaConfig : public PersistentObject 700 { 701 public: 702 /** 703 * Clock rate to be applied to the conference bridge. 704 * If value is zero, default clock rate will be used 705 * (PJSUA_DEFAULT_CLOCK_RATE, which by default is 16KHz). 706 */ 707 unsigned clockRate; 708 709 /** 710 * Clock rate to be applied when opening the sound device. 711 * If value is zero, conference bridge clock rate will be used. 712 */ 713 unsigned sndClockRate; 714 715 /** 716 * Channel count be applied when opening the sound device and 717 * conference bridge. 718 */ 719 unsigned channelCount; 720 721 /** 722 * Specify audio frame ptime. The value here will affect the 723 * samples per frame of both the sound device and the conference 724 * bridge. Specifying lower ptime will normally reduce the 725 * latency. 726 * 727 * Default value: PJSUA_DEFAULT_AUDIO_FRAME_PTIME 728 */ 729 unsigned audioFramePtime; 730 731 /** 732 * Specify maximum number of media ports to be created in the 733 * conference bridge. Since all media terminate in the bridge 734 * (calls, file player, file recorder, etc), the value must be 735 * large enough to support all of them. However, the larger 736 * the value, the more computations are performed. 737 * 738 * Default value: PJSUA_MAX_CONF_PORTS 739 */ 740 unsigned maxMediaPorts; 741 742 /** 743 * Specify whether the media manager should manage its own 744 * ioqueue for the RTP/RTCP sockets. If yes, ioqueue will be created 745 * and at least one worker thread will be created too. If no, 746 * the RTP/RTCP sockets will share the same ioqueue as SIP sockets, 747 * and no worker thread is needed. 748 * 749 * Normally application would say yes here, unless it wants to 750 * run everything from a single thread. 751 */ 752 bool hasIoqueue; 753 754 /** 755 * Specify the number of worker threads to handle incoming RTP 756 * packets. A value of one is recommended for most applications. 757 */ 758 unsigned threadCnt; 759 760 /** 761 * Media quality, 0-10, according to this table: 762 * 5-10: resampling use large filter, 763 * 3-4: resampling use small filter, 764 * 1-2: resampling use linear. 765 * The media quality also sets speex codec quality/complexity to the 766 * number. 767 * 768 * Default: 5 (PJSUA_DEFAULT_CODEC_QUALITY). 769 */ 770 unsigned quality; 771 772 /** 773 * Specify default codec ptime. 774 * 775 * Default: 0 (codec specific) 776 */ 777 unsigned ptime; 778 779 /** 780 * Disable VAD? 781 * 782 * Default: 0 (no (meaning VAD is enabled)) 783 */ 784 bool noVad; 785 786 /** 787 * iLBC mode (20 or 30). 788 * 789 * Default: 30 (PJSUA_DEFAULT_ILBC_MODE) 790 */ 791 unsigned ilbcMode; 792 793 /** 794 * Percentage of RTP packet to drop in TX direction 795 * (to simulate packet lost). 796 * 797 * Default: 0 798 */ 799 unsigned txDropPct; 800 801 /** 802 * Percentage of RTP packet to drop in RX direction 803 * (to simulate packet lost). 804 * 805 * Default: 0 806 */ 807 unsigned rxDropPct; 808 809 /** 810 * Echo canceller options (see pjmedia_echo_create()). 811 * Specify PJMEDIA_ECHO_USE_SW_ECHO here if application wishes 812 * to use software echo canceller instead of device EC. 813 * 814 * Default: 0. 815 */ 816 unsigned ecOptions; 817 818 /** 819 * Echo canceller tail length, in miliseconds. Setting this to zero 820 * will disable echo cancellation. 821 * 822 * Default: PJSUA_DEFAULT_EC_TAIL_LEN 823 */ 824 unsigned ecTailLen; 825 826 /** 827 * Audio capture buffer length, in milliseconds. 828 * 829 * Default: PJMEDIA_SND_DEFAULT_REC_LATENCY 830 */ 831 unsigned sndRecLatency; 832 833 /** 834 * Audio playback buffer length, in milliseconds. 835 * 836 * Default: PJMEDIA_SND_DEFAULT_PLAY_LATENCY 837 */ 838 unsigned sndPlayLatency; 839 840 /** 841 * Jitter buffer initial prefetch delay in msec. The value must be 842 * between jb_min_pre and jb_max_pre below. 843 * 844 * Default: -1 (to use default stream settings, currently 150 msec) 845 */ 846 int jbInit; 847 848 /** 849 * Jitter buffer minimum prefetch delay in msec. 850 * 851 * Default: -1 (to use default stream settings, currently 60 msec) 852 */ 853 int jbMinPre; 854 855 /** 856 * Jitter buffer maximum prefetch delay in msec. 857 * 858 * Default: -1 (to use default stream settings, currently 240 msec) 859 */ 860 int jbMaxPre; 861 862 /** 863 * Set maximum delay that can be accomodated by the jitter buffer msec. 864 * 865 * Default: -1 (to use default stream settings, currently 360 msec) 866 */ 867 int jbMax; 868 869 /** 870 * Set the algorithm the jitter buffer uses to discard frames in order to 871 * adjust the latency. 872 * 873 * Default: PJMEDIA_JB_DISCARD_PROGRESSIVE 874 */ 875 pjmedia_jb_discard_algo jbDiscardAlgo; 876 877 /** 878 * Specify idle time of sound device before it is automatically closed, 879 * in seconds. Use value -1 to disable the auto-close feature of sound 880 * device 881 * 882 * Default : 1 883 */ 884 int sndAutoCloseTime; 885 886 /** 887 * Specify whether built-in/native preview should be used if available. 888 * In some systems, video input devices have built-in capability to show 889 * preview window of the device. Using this built-in preview is preferable 890 * as it consumes less CPU power. If built-in preview is not available, 891 * the library will perform software rendering of the input. If this 892 * field is set to PJ_FALSE, software preview will always be used. 893 * 894 * Default: PJ_TRUE 895 */ 896 bool vidPreviewEnableNative; 897 898 public: 899 /** Default constructor initialises with default values */ 900 MediaConfig(); 901 902 /** Construct from pjsua_media_config. */ 903 void fromPj(const pjsua_media_config &mc); 904 905 /** Export */ 906 pjsua_media_config toPj() const; 907 908 /** 909 * Read this object from a container. 910 * 911 * @param node Container to write values from. 912 */ 913 virtual void readObject(const ContainerNode &node) PJSUA2_THROW(Error); 914 915 /** 916 * Write this object to a container. 917 * 918 * @param node Container to write values to. 919 */ 920 virtual void writeObject(ContainerNode &node) const PJSUA2_THROW(Error); 921 }; 922 923 924 /** 925 * Endpoint configuration 926 */ 927 struct EpConfig : public PersistentObject 928 { 929 /** UA config */ 930 UaConfig uaConfig; 931 932 /** Logging config */ 933 LogConfig logConfig; 934 935 /** Media config */ 936 MediaConfig medConfig; 937 938 /** 939 * Read this object from a container. 940 * 941 * @param node Container to write values from. 942 */ 943 virtual void readObject(const ContainerNode &node) PJSUA2_THROW(Error); 944 945 /** 946 * Write this object to a container. 947 * 948 * @param node Container to write values to. 949 */ 950 virtual void writeObject(ContainerNode &node) const PJSUA2_THROW(Error); 951 952 }; 953 954 /* This represents posted job */ 955 struct PendingJob 956 { 957 /** Perform the job */ 958 virtual void execute(bool is_pending) = 0; 959 960 /** Virtual destructor */ ~PendingJobpj::PendingJob961 virtual ~PendingJob() {} 962 }; 963 964 ////////////////////////////////////////////////////////////////////////////// 965 966 /** 967 * Endpoint represents an instance of pjsua library. There can only be 968 * one instance of pjsua library in an application, hence this class 969 * is a singleton. 970 */ 971 class Endpoint 972 { 973 public: 974 /** Retrieve the singleton instance of the endpoint */ 975 static Endpoint &instance() PJSUA2_THROW(Error); 976 977 /** Default constructor */ 978 Endpoint(); 979 980 /** Virtual destructor */ 981 virtual ~Endpoint(); 982 983 984 /************************************************************************* 985 * Base library operations 986 */ 987 988 /** 989 * Get library version. 990 */ 991 Version libVersion() const; 992 993 /** 994 * Instantiate pjsua application. Application must call this function before 995 * calling any other functions, to make sure that the underlying libraries 996 * are properly initialized. Once this function has returned success, 997 * application must call libDestroy() before quitting. 998 */ 999 void libCreate() PJSUA2_THROW(Error); 1000 1001 /** 1002 * Get library state. 1003 * 1004 * @return library state. 1005 */ 1006 pjsua_state libGetState() const; 1007 1008 /** 1009 * Initialize pjsua with the specified settings. All the settings are 1010 * optional, and the default values will be used when the config is not 1011 * specified. 1012 * 1013 * Note that create() MUST be called before calling this function. 1014 * 1015 * @param prmEpConfig Endpoint configurations 1016 */ 1017 void libInit( const EpConfig &prmEpConfig) PJSUA2_THROW(Error); 1018 1019 /** 1020 * Call this function after all initialization is done, so that the 1021 * library can do additional checking set up. Application may call this 1022 * function any time after init(). 1023 */ 1024 void libStart() PJSUA2_THROW(Error); 1025 1026 /** 1027 * Register a thread that was created by external or native API to the 1028 * library. Note that each time this function is called, it will allocate 1029 * some memory to store the thread description, which will only be freed 1030 * when the library is destroyed. 1031 * 1032 * @param name The optional name to be assigned to the thread. 1033 */ 1034 void libRegisterThread(const string &name) PJSUA2_THROW(Error); 1035 1036 /** 1037 * Check if this thread has been registered to the library. Note that 1038 * this function is only applicable for library main & worker threads and 1039 * external/native threads registered using libRegisterThread(). 1040 */ 1041 bool libIsThreadRegistered(); 1042 1043 /** 1044 * Stop all worker threads. 1045 */ 1046 void libStopWorkerThreads(); 1047 1048 /** 1049 * Poll pjsua for events, and if necessary block the caller thread for 1050 * the specified maximum interval (in miliseconds). 1051 * 1052 * Application doesn't normally need to call this function if it has 1053 * configured worker thread (\a thread_cnt field) in pjsua_config 1054 * structure, because polling then will be done by these worker threads 1055 * instead. 1056 * 1057 * If EpConfig::UaConfig::mainThreadOnly is enabled and this function 1058 * is called from the main thread (by default the main thread is thread 1059 * that calls libCreate()), this function will also scan and run any 1060 * pending jobs in the list. 1061 * 1062 * @param msec_timeout Maximum time to wait, in miliseconds. 1063 * 1064 * @return The number of events that have been handled during the 1065 * poll. Negative value indicates error, and application 1066 * can retrieve the error as (status = -return_value). 1067 */ 1068 int libHandleEvents(unsigned msec_timeout); 1069 1070 /** 1071 * Destroy pjsua. Application is recommended to perform graceful shutdown 1072 * before calling this function (such as unregister the account from the 1073 * SIP server, terminate presense subscription, and hangup active calls), 1074 * however, this function will do all of these if it finds there are 1075 * active sessions that need to be terminated. This function will 1076 * block for few seconds to wait for replies from remote. 1077 * 1078 * Application.may safely call this function more than once if it doesn't 1079 * keep track of it's state. 1080 * 1081 * @param prmFlags Combination of pjsua_destroy_flag enumeration. 1082 */ 1083 void libDestroy(unsigned prmFlags=0) PJSUA2_THROW(Error); 1084 1085 1086 /************************************************************************* 1087 * Utilities 1088 */ 1089 1090 /** 1091 * Retrieve the error string for the specified status code. 1092 * 1093 * @param prmErr The error code. 1094 */ 1095 string utilStrError(pj_status_t prmErr); 1096 1097 /** 1098 * Write a log message. 1099 * 1100 * @param prmLevel Log verbosity level (1-5) 1101 * @param prmSender The log sender. 1102 * @param prmMsg The log message. 1103 */ 1104 void utilLogWrite(int prmLevel, 1105 const string &prmSender, 1106 const string &prmMsg); 1107 1108 /** 1109 * Write a log entry. 1110 * Application must implement its own custom LogWriter and 1111 * this function will then call the LogWriter::write() method. 1112 * Note that this function does not call PJSIP's internal 1113 * logging functionality. For that, you should use 1114 * utilLogWrite(prmLevel, prmSender, prmMsg) above. 1115 * 1116 * @param e The log entry. 1117 */ 1118 void utilLogWrite(LogEntry &e); 1119 1120 /** 1121 * This is a utility function to verify that valid SIP url is given. If the 1122 * URL is a valid SIP/SIPS scheme, PJ_SUCCESS will be returned. 1123 * 1124 * @param prmUri The URL string. 1125 * 1126 * @return PJ_SUCCESS on success, or the appropriate error 1127 * code. 1128 * 1129 * @see utilVerifyUri() 1130 */ 1131 pj_status_t utilVerifySipUri(const string &prmUri); 1132 1133 /** 1134 * This is a utility function to verify that valid URI is given. Unlike 1135 * utilVerifySipUri(), this function will return PJ_SUCCESS if tel: URI 1136 * is given. 1137 * 1138 * @param prmUri The URL string. 1139 * 1140 * @return PJ_SUCCESS on success, or the appropriate error 1141 * code. 1142 * 1143 * @see pjsua_verify_sip_url() 1144 */ 1145 pj_status_t utilVerifyUri(const string &prmUri); 1146 1147 /** 1148 * Schedule a timer with the specified interval and user data. When the 1149 * interval elapsed, onTimer() callback will be 1150 * called. Note that the callback may be executed by different thread, 1151 * depending on whether worker thread is enabled or not. 1152 * 1153 * @param prmMsecDelay The time interval in msec. 1154 * @param prmUserData Arbitrary user data, to be given back to 1155 * application in the callback. 1156 * 1157 * @return Token to identify the timer, which could be 1158 * given to utilTimerCancel(). 1159 */ 1160 Token utilTimerSchedule(unsigned prmMsecDelay, 1161 Token prmUserData) PJSUA2_THROW(Error); 1162 1163 /** 1164 * Cancel previously scheduled timer with the specified timer token. 1165 * 1166 * @param prmToken The timer token, which was returned from 1167 * previous utilTimerSchedule() call. 1168 */ 1169 void utilTimerCancel(Token prmToken); 1170 1171 /** 1172 * Utility to register a pending job to be executed by main thread. 1173 * If EpConfig::UaConfig::mainThreadOnly is false, the job will be 1174 * executed immediately. 1175 * 1176 * @param job The job class. 1177 */ 1178 void utilAddPendingJob(PendingJob *job); 1179 1180 /** 1181 * Get cipher list supported by SSL/TLS backend. 1182 */ 1183 IntVector utilSslGetAvailableCiphers() PJSUA2_THROW(Error); 1184 1185 /************************************************************************* 1186 * NAT operations 1187 */ 1188 /** 1189 * This is a utility function to detect NAT type in front of this endpoint. 1190 * Once invoked successfully, this function will complete asynchronously 1191 * and report the result in onNatDetectionComplete(). 1192 * 1193 * After NAT has been detected and the callback is called, application can 1194 * get the detected NAT type by calling natGetType(). Application 1195 * can also perform NAT detection by calling natDetectType() 1196 * again at later time. 1197 * 1198 * Note that STUN must be enabled to run this function successfully. 1199 */ 1200 void natDetectType(void) PJSUA2_THROW(Error); 1201 1202 /** 1203 * Get the NAT type as detected by natDetectType() function. This 1204 * function will only return useful NAT type after natDetectType() 1205 * has completed successfully and onNatDetectionComplete() 1206 * callback has been called. 1207 * 1208 * Exception: if this function is called while detection is in progress, 1209 * PJ_EPENDING exception will be raised. 1210 */ 1211 pj_stun_nat_type natGetType() PJSUA2_THROW(Error); 1212 1213 /** 1214 * Update the STUN servers list. The libInit() must have been called 1215 * before calling this function. 1216 * 1217 * @param prmServers Array of STUN servers to try. The endpoint 1218 * will try to resolve and contact each of the 1219 * STUN server entry until it finds one that is 1220 * usable. Each entry may be a domain name, host 1221 * name, IP address, and it may contain an 1222 * optional port number. For example: 1223 * - "pjsip.org" (domain name) 1224 * - "sip.pjsip.org" (host name) 1225 * - "pjsip.org:33478" (domain name and a non- 1226 * standard port number) 1227 * - "10.0.0.1:3478" (IP address and port number) 1228 * @param prmWait Specify if the function should block until 1229 * it gets the result. In this case, the 1230 * function will block while the resolution 1231 * is being done, and the callback 1232 * onNatCheckStunServersComplete() will be called 1233 * before this function returns. 1234 * 1235 */ 1236 void natUpdateStunServers(const StringVector &prmServers, 1237 bool prmWait) PJSUA2_THROW(Error); 1238 1239 /** 1240 * Auxiliary function to resolve and contact each of the STUN server 1241 * entries (sequentially) to find which is usable. The libInit() must 1242 * have been called before calling this function. 1243 * 1244 * @param prmServers Array of STUN servers to try. The endpoint 1245 * will try to resolve and contact each of the 1246 * STUN server entry until it finds one that is 1247 * usable. Each entry may be a domain name, host 1248 * name, IP address, and it may contain an 1249 * optional port number. For example: 1250 * - "pjsip.org" (domain name) 1251 * - "sip.pjsip.org" (host name) 1252 * - "pjsip.org:33478" (domain name and a non- 1253 * standard port number) 1254 * - "10.0.0.1:3478" (IP address and port number) 1255 * @param prmWait Specify if the function should block until 1256 * it gets the result. In this case, the function 1257 * will block while the resolution is being done, 1258 * and the callback will be called before this 1259 * function returns. 1260 * @param prmUserData Arbitrary user data to be passed back to 1261 * application in the callback. 1262 * 1263 * @see natCancelCheckStunServers() 1264 */ 1265 void natCheckStunServers(const StringVector &prmServers, 1266 bool prmWait, 1267 Token prmUserData) PJSUA2_THROW(Error); 1268 1269 /** 1270 * Cancel pending STUN resolution which match the specified token. 1271 * 1272 * @param token The token to match. This token was given to 1273 * natCheckStunServers() 1274 * @param notify_cb Boolean to control whether the callback should 1275 * be called for cancelled resolutions. When the 1276 * callback is called, the status in the result 1277 * will be set as PJ_ECANCELLED. 1278 * 1279 * Exception: PJ_ENOTFOUND if there is no matching one, or other error. 1280 */ 1281 void natCancelCheckStunServers(Token token, 1282 bool notify_cb = false) PJSUA2_THROW(Error); 1283 1284 /************************************************************************* 1285 * Transport operations 1286 */ 1287 1288 /** 1289 * Create and start a new SIP transport according to the specified 1290 * settings. 1291 * 1292 * @param type Transport type. 1293 * @param cfg Transport configuration. 1294 * 1295 * @return The transport ID. 1296 */ 1297 TransportId transportCreate(pjsip_transport_type_e type, 1298 const TransportConfig &cfg) PJSUA2_THROW(Error); 1299 1300 /** 1301 * Enumerate all transports currently created in the system. This 1302 * function will return all transport IDs, and application may then 1303 * call transportGetInfo() function to retrieve detailed information 1304 * about the transport. 1305 * 1306 * @return Array of transport IDs. 1307 */ 1308 IntVector transportEnum() PJSUA2_THROW(Error); 1309 1310 /** 1311 * Get information about transport. 1312 * 1313 * @param id Transport ID. 1314 * 1315 * @return Transport info. 1316 */ 1317 TransportInfo transportGetInfo(TransportId id) PJSUA2_THROW(Error); 1318 1319 /** 1320 * Disable a transport or re-enable it. By default transport is always 1321 * enabled after it is created. Disabling a transport does not necessarily 1322 * close the socket, it will only discard incoming messages and prevent 1323 * the transport from being used to send outgoing messages. 1324 * 1325 * @param id Transport ID. 1326 * @param enabled Enable or disable the transport. 1327 * 1328 */ 1329 void transportSetEnable(TransportId id, bool enabled) PJSUA2_THROW(Error); 1330 1331 /** 1332 * Close the transport. The system will wait until all transactions are 1333 * closed while preventing new users from using the transport, and will 1334 * close the transport when its usage count reaches zero. 1335 * 1336 * @param id Transport ID. 1337 */ 1338 void transportClose(TransportId id) PJSUA2_THROW(Error); 1339 1340 /** 1341 * Start graceful shutdown procedure for this transport handle. After 1342 * graceful shutdown has been initiated, no new reference can be 1343 * obtained for the transport. However, existing objects that currently 1344 * uses the transport may still use this transport to send and receive 1345 * packets. After all objects release their reference to this transport, 1346 * the transport will be destroyed immediately. 1347 * 1348 * Note: application normally uses this API after obtaining the handle 1349 * from onTransportState() callback. 1350 * 1351 * @param tp The transport. 1352 */ 1353 void transportShutdown(TransportHandle tp) PJSUA2_THROW(Error); 1354 1355 /************************************************************************* 1356 * Call operations 1357 */ 1358 1359 /** 1360 * Terminate all calls. This will initiate call hangup for all 1361 * currently active calls. 1362 */ 1363 void hangupAllCalls(void); 1364 1365 /************************************************************************* 1366 * Media operations 1367 */ 1368 1369 /** 1370 * Add media to the media list. 1371 * 1372 * @param media media to be added. 1373 */ 1374 void mediaAdd(AudioMedia &media); 1375 1376 /** 1377 * Remove media from the media list. 1378 * 1379 * @param media media to be removed. 1380 */ 1381 void mediaRemove(AudioMedia &media); 1382 1383 /** 1384 * Check if media has been added to the media list. 1385 * 1386 * @param media media to be check. 1387 * 1388 * @return True if media has been added, false otherwise. 1389 */ 1390 bool mediaExists(const AudioMedia &media) const; 1391 1392 /** 1393 * Get maximum number of media port. 1394 * 1395 * @return Maximum number of media port in the conference bridge. 1396 */ 1397 unsigned mediaMaxPorts() const; 1398 1399 /** 1400 * Get current number of active media port in the bridge. 1401 * 1402 * @return The number of active media port. 1403 */ 1404 unsigned mediaActivePorts() const; 1405 1406 #if !DEPRECATED_FOR_TICKET_2232 1407 /** 1408 * Warning: deprecated, use mediaEnumPorts2() instead. This function is 1409 * not safe in multithreaded environment. 1410 * 1411 * Enumerate all media port. 1412 * 1413 * @return The list of media port. 1414 */ 1415 const AudioMediaVector &mediaEnumPorts() const PJSUA2_THROW(Error); 1416 #endif 1417 1418 /** 1419 * Enumerate all audio media port. 1420 * 1421 * @return The list of audio media port. 1422 */ 1423 AudioMediaVector2 mediaEnumPorts2() const PJSUA2_THROW(Error); 1424 1425 /** 1426 * Enumerate all video media port. 1427 * 1428 * @return The list of video media port. 1429 */ 1430 VideoMediaVector mediaEnumVidPorts() const PJSUA2_THROW(Error); 1431 1432 /** 1433 * Get the instance of Audio Device Manager. 1434 * 1435 * @return The Audio Device Manager. 1436 */ 1437 AudDevManager &audDevManager(); 1438 1439 /** 1440 * Get the instance of Video Device Manager. 1441 * 1442 * @return The Video Device Manager. 1443 */ 1444 VidDevManager &vidDevManager(); 1445 1446 /************************************************************************* 1447 * Codec management operations 1448 */ 1449 1450 #if !DEPRECATED_FOR_TICKET_2232 1451 /** 1452 * Warning: deprecated, use codecEnum2() instead. This function is not 1453 * safe in multithreaded environment. 1454 * 1455 * Enum all supported codecs in the system. 1456 * 1457 * @return Array of codec info. 1458 */ 1459 const CodecInfoVector &codecEnum() PJSUA2_THROW(Error); 1460 #endif 1461 1462 /** 1463 * Enum all supported codecs in the system. 1464 * 1465 * @return Array of codec info. 1466 */ 1467 CodecInfoVector2 codecEnum2() const PJSUA2_THROW(Error); 1468 1469 /** 1470 * Change codec priority. 1471 * 1472 * @param codec_id Codec ID, which is a string that uniquely identify 1473 * the codec (such as "speex/8000"). 1474 * @param priority Codec priority, 0-255, where zero means to disable 1475 * the codec. 1476 * 1477 */ 1478 void codecSetPriority(const string &codec_id, 1479 pj_uint8_t priority) PJSUA2_THROW(Error); 1480 1481 /** 1482 * Get codec parameters. 1483 * 1484 * @param codec_id Codec ID. 1485 * 1486 * @return Codec parameters. If codec is not found, Error 1487 * will be thrown. 1488 * 1489 */ 1490 CodecParam codecGetParam(const string &codec_id) const PJSUA2_THROW(Error); 1491 1492 /** 1493 * Set codec parameters. 1494 * 1495 * @param codec_id Codec ID. 1496 * @param param Codec parameter to set. Set to NULL to reset 1497 * codec parameter to library default settings. 1498 * 1499 */ 1500 void codecSetParam(const string &codec_id, 1501 const CodecParam param) PJSUA2_THROW(Error); 1502 1503 #if !DEPRECATED_FOR_TICKET_2232 1504 /** 1505 * Warning: deprecated, use videoCodecEnum2() instead. This function is 1506 * not safe in multithreaded environment. 1507 * 1508 * Enum all supported video codecs in the system. 1509 * 1510 * @return Array of video codec info. 1511 */ 1512 const CodecInfoVector &videoCodecEnum() PJSUA2_THROW(Error); 1513 #endif 1514 1515 /** 1516 * Enum all supported video codecs in the system. 1517 * 1518 * @return Array of video codec info. 1519 */ 1520 CodecInfoVector2 videoCodecEnum2() const PJSUA2_THROW(Error); 1521 1522 /** 1523 * Change video codec priority. 1524 * 1525 * @param codec_id Codec ID, which is a string that uniquely identify 1526 * the codec (such as "H263/90000"). Please see pjsua 1527 * manual or pjmedia codec reference for details. 1528 * @param priority Codec priority, 0-255, where zero means to disable 1529 * the codec. 1530 * 1531 */ 1532 void videoCodecSetPriority(const string &codec_id, 1533 pj_uint8_t priority) PJSUA2_THROW(Error); 1534 1535 /** 1536 * Get video codec parameters. 1537 * 1538 * @param codec_id Codec ID. 1539 * 1540 * @return Codec parameters. If codec is not found, Error 1541 * will be thrown. 1542 * 1543 */ 1544 VidCodecParam getVideoCodecParam(const string &codec_id) const 1545 PJSUA2_THROW(Error); 1546 1547 /** 1548 * Set video codec parameters. 1549 * 1550 * @param codec_id Codec ID. 1551 * @param param Codec parameter to set. 1552 * 1553 */ 1554 void setVideoCodecParam(const string &codec_id, 1555 const VidCodecParam ¶m) PJSUA2_THROW(Error); 1556 1557 /** 1558 * Reset video codec parameters to library default settings. 1559 * 1560 * @param codec_id Codec ID. 1561 * 1562 */ 1563 void resetVideoCodecParam(const string &codec_id) PJSUA2_THROW(Error); 1564 1565 #if defined(PJMEDIA_HAS_OPUS_CODEC) && (PJMEDIA_HAS_OPUS_CODEC!=0) 1566 /** 1567 * Get codec Opus config. 1568 * 1569 */ 1570 CodecOpusConfig getCodecOpusConfig() const PJSUA2_THROW(Error); 1571 1572 /** 1573 * Set codec Opus config. 1574 * 1575 * @param opus_cfg Codec Opus configuration. 1576 * 1577 */ 1578 void setCodecOpusConfig(const CodecOpusConfig &opus_cfg) 1579 PJSUA2_THROW(Error); 1580 #endif 1581 1582 /** 1583 * Enumerate all SRTP crypto-suite names. 1584 * 1585 * @return The list of SRTP crypto-suite name. 1586 */ 1587 StringVector srtpCryptoEnum() PJSUA2_THROW(Error); 1588 1589 /************************************************************************* 1590 * IP Change 1591 */ 1592 1593 /** 1594 * Inform the stack that IP address change event was detected. 1595 * The stack will: 1596 * 1. Restart the listener (this step is configurable via 1597 * \a IpChangeParam.restartListener). 1598 * 2. Shutdown the transport used by account registration (this step is 1599 * configurable via \a AccountConfig.ipChangeConfig.shutdownTp). 1600 * 3. Update contact URI by sending re-Registration (this step is 1601 * configurable via a\ AccountConfig.natConfig.contactRewriteUse and 1602 * a\ AccountConfig.natConfig.contactRewriteMethod) 1603 * 4. Hangup active calls (this step is configurable via 1604 * a\ AccountConfig.ipChangeConfig.hangupCalls) or 1605 * continue the call by sending re-INVITE 1606 * (configurable via \a AccountConfig.ipChangeConfig.reinviteFlags). 1607 * 1608 * @param param The IP change parameter, have a look at #IpChangeParam. 1609 * 1610 * @return PJ_SUCCESS on success, other on error. 1611 */ 1612 void handleIpChange(const IpChangeParam ¶m) PJSUA2_THROW(Error); 1613 1614 public: 1615 /* 1616 * Overrideables callbacks 1617 */ 1618 1619 /** 1620 * Callback when the Endpoint has finished performing NAT type 1621 * detection that is initiated with natDetectType(). 1622 * 1623 * @param prm Callback parameters containing the detection 1624 * result. 1625 */ onNatDetectionComplete(const OnNatDetectionCompleteParam & prm)1626 virtual void onNatDetectionComplete( 1627 const OnNatDetectionCompleteParam &prm) 1628 { PJ_UNUSED_ARG(prm); } 1629 1630 /** 1631 * Callback when the Endpoint has finished performing STUN server 1632 * checking that is initiated when calling libInit(), or by 1633 * calling natCheckStunServers() or natUpdateStunServers(). 1634 * 1635 * @param prm Callback parameters. 1636 */ onNatCheckStunServersComplete(const OnNatCheckStunServersCompleteParam & prm)1637 virtual void onNatCheckStunServersComplete( 1638 const OnNatCheckStunServersCompleteParam &prm) 1639 { PJ_UNUSED_ARG(prm); } 1640 1641 /** 1642 * This callback is called when transport state has changed. 1643 * 1644 * @param prm Callback parameters. 1645 */ onTransportState(const OnTransportStateParam & prm)1646 virtual void onTransportState( 1647 const OnTransportStateParam &prm) 1648 { PJ_UNUSED_ARG(prm); } 1649 1650 /** 1651 * Callback when a timer has fired. The timer was scheduled by 1652 * utilTimerSchedule(). 1653 * 1654 * @param prm Callback parameters. 1655 */ onTimer(const OnTimerParam & prm)1656 virtual void onTimer(const OnTimerParam &prm) 1657 { PJ_UNUSED_ARG(prm); } 1658 1659 /** 1660 * This callback can be used by application to override the account 1661 * to be used to handle an incoming message. Initially, the account to 1662 * be used will be calculated automatically by the library. This initial 1663 * account will be used if application does not implement this callback, 1664 * or application sets an invalid account upon returning from this 1665 * callback. 1666 * 1667 * Note that currently the incoming messages requiring account assignment 1668 * are INVITE, MESSAGE, SUBSCRIBE, and unsolicited NOTIFY. This callback 1669 * may be called before the callback of the SIP event itself, i.e: 1670 * incoming call, pager, subscription, or unsolicited-event. 1671 * 1672 * @param prm Callback parameters. 1673 */ onSelectAccount(OnSelectAccountParam & prm)1674 virtual void onSelectAccount(OnSelectAccountParam &prm) 1675 { PJ_UNUSED_ARG(prm); } 1676 1677 /** 1678 * Calling #handleIpChange() may involve different operation. This 1679 * callback is called to report the progress of each enabled operation. 1680 * 1681 * @param prm Callback parameters. 1682 * 1683 */ onIpChangeProgress(OnIpChangeProgressParam & prm)1684 virtual void onIpChangeProgress(OnIpChangeProgressParam &prm) 1685 { PJ_UNUSED_ARG(prm); } 1686 1687 /** 1688 * Notification about media events such as video notifications. This 1689 * callback will most likely be called from media threads, thus 1690 * application must not perform heavy processing in this callback. 1691 * If application needs to perform more complex tasks to handle the 1692 * event, it should post the task to another thread. 1693 * 1694 * @param prm Callback parameter. 1695 */ onMediaEvent(OnMediaEventParam & prm)1696 virtual void onMediaEvent(OnMediaEventParam &prm) 1697 { PJ_UNUSED_ARG(prm); } 1698 1699 private: 1700 static Endpoint *instance_; // static instance 1701 LogWriter *writer; // Custom writer, if any 1702 AudDevManager audioDevMgr; 1703 VidDevManager videoDevMgr; 1704 #if !DEPRECATED_FOR_TICKET_2232 1705 CodecInfoVector codecInfoList; 1706 CodecInfoVector videoCodecInfoList; 1707 #endif 1708 std::map<pj_thread_t*, pj_thread_desc*> threadDescMap; 1709 pj_mutex_t *threadDescMutex; 1710 #if !DEPRECATED_FOR_TICKET_2232 1711 AudioMediaVector mediaList; 1712 pj_mutex_t *mediaListMutex; 1713 #endif 1714 1715 /* Pending logging */ 1716 bool mainThreadOnly; 1717 void *mainThread; 1718 unsigned pendingJobSize; 1719 std::list<PendingJob*> pendingJobs; 1720 1721 void performPendingJobs(); 1722 1723 /* Endpoint static callbacks */ 1724 static void logFunc(int level, const char *data, int len); 1725 static void stun_resolve_cb(const pj_stun_resolve_result *result); 1726 static void on_timer(pj_timer_heap_t *timer_heap, 1727 struct pj_timer_entry *entry); 1728 static void on_nat_detect(const pj_stun_nat_detect_result *res); 1729 static void on_transport_state(pjsip_transport *tp, 1730 pjsip_transport_state state, 1731 const pjsip_transport_state_info *info); 1732 1733 private: 1734 /* 1735 * Account & Call lookups 1736 */ 1737 static Account *lookupAcc(int acc_id, const char *op); 1738 static Call *lookupCall(int call_id, const char *op); 1739 1740 /* static callbacks */ 1741 static void on_incoming_call(pjsua_acc_id acc_id, 1742 pjsua_call_id call_id, 1743 pjsip_rx_data *rdata); 1744 static void on_reg_started(pjsua_acc_id acc_id, 1745 pj_bool_t renew); 1746 static void on_reg_state2(pjsua_acc_id acc_id, 1747 pjsua_reg_info *info); 1748 static void on_incoming_subscribe(pjsua_acc_id acc_id, 1749 pjsua_srv_pres *srv_pres, 1750 pjsua_buddy_id buddy_id, 1751 const pj_str_t *from, 1752 pjsip_rx_data *rdata, 1753 pjsip_status_code *code, 1754 pj_str_t *reason, 1755 pjsua_msg_data *msg_data); 1756 static void on_pager2(pjsua_call_id call_id, 1757 const pj_str_t *from, 1758 const pj_str_t *to, 1759 const pj_str_t *contact, 1760 const pj_str_t *mime_type, 1761 const pj_str_t *body, 1762 pjsip_rx_data *rdata, 1763 pjsua_acc_id acc_id); 1764 static void on_pager_status2(pjsua_call_id call_id, 1765 const pj_str_t *to, 1766 const pj_str_t *body, 1767 void *user_data, 1768 pjsip_status_code status, 1769 const pj_str_t *reason, 1770 pjsip_tx_data *tdata, 1771 pjsip_rx_data *rdata, 1772 pjsua_acc_id acc_id); 1773 static void on_typing2(pjsua_call_id call_id, 1774 const pj_str_t *from, 1775 const pj_str_t *to, 1776 const pj_str_t *contact, 1777 pj_bool_t is_typing, 1778 pjsip_rx_data *rdata, 1779 pjsua_acc_id acc_id); 1780 static void on_mwi_info(pjsua_acc_id acc_id, 1781 pjsua_mwi_info *mwi_info); 1782 static void on_acc_find_for_incoming(const pjsip_rx_data *rdata, 1783 pjsua_acc_id* acc_id); 1784 static void on_buddy_state(pjsua_buddy_id buddy_id); 1785 static void on_buddy_evsub_state(pjsua_buddy_id buddy_id, 1786 pjsip_evsub *sub, 1787 pjsip_event *event); 1788 // Call callbacks 1789 static void on_call_state(pjsua_call_id call_id, pjsip_event *e); 1790 static void on_call_tsx_state(pjsua_call_id call_id, 1791 pjsip_transaction *tsx, 1792 pjsip_event *e); 1793 static void on_call_media_state(pjsua_call_id call_id); 1794 static void on_call_sdp_created(pjsua_call_id call_id, 1795 pjmedia_sdp_session *sdp, 1796 pj_pool_t *pool, 1797 const pjmedia_sdp_session *rem_sdp); 1798 static void on_stream_precreate(pjsua_call_id call_id, 1799 pjsua_on_stream_precreate_param *param); 1800 static void on_stream_created2(pjsua_call_id call_id, 1801 pjsua_on_stream_created_param *param); 1802 static void on_stream_destroyed(pjsua_call_id call_id, 1803 pjmedia_stream *strm, 1804 unsigned stream_idx); 1805 static void on_dtmf_digit(pjsua_call_id call_id, int digit); 1806 static void on_dtmf_digit2(pjsua_call_id call_id, 1807 const pjsua_dtmf_info *info); 1808 static void on_dtmf_event(pjsua_call_id call_id, 1809 const pjsua_dtmf_event *event); 1810 static void on_call_transfer_request(pjsua_call_id call_id, 1811 const pj_str_t *dst, 1812 pjsip_status_code *code); 1813 static void on_call_transfer_request2(pjsua_call_id call_id, 1814 const pj_str_t *dst, 1815 pjsip_status_code *code, 1816 pjsua_call_setting *opt); 1817 static void on_call_transfer_status(pjsua_call_id call_id, 1818 int st_code, 1819 const pj_str_t *st_text, 1820 pj_bool_t final, 1821 pj_bool_t *p_cont); 1822 static void on_call_replace_request(pjsua_call_id call_id, 1823 pjsip_rx_data *rdata, 1824 int *st_code, 1825 pj_str_t *st_text); 1826 static void on_call_replace_request2(pjsua_call_id call_id, 1827 pjsip_rx_data *rdata, 1828 int *st_code, 1829 pj_str_t *st_text, 1830 pjsua_call_setting *opt); 1831 static void on_call_replaced(pjsua_call_id old_call_id, 1832 pjsua_call_id new_call_id); 1833 static void on_call_rx_offer(pjsua_call_id call_id, 1834 const pjmedia_sdp_session *offer, 1835 void *reserved, 1836 pjsip_status_code *code, 1837 pjsua_call_setting *opt); 1838 static void on_call_rx_reinvite(pjsua_call_id call_id, 1839 const pjmedia_sdp_session *offer, 1840 pjsip_rx_data *rdata, 1841 void *reserved, 1842 pj_bool_t *async, 1843 pjsip_status_code *code, 1844 pjsua_call_setting *opt); 1845 static void on_call_tx_offer(pjsua_call_id call_id, 1846 void *reserved, 1847 pjsua_call_setting *opt); 1848 static pjsip_redirect_op on_call_redirected(pjsua_call_id call_id, 1849 const pjsip_uri *target, 1850 const pjsip_event *e); 1851 static pj_status_t 1852 on_call_media_transport_state(pjsua_call_id call_id, 1853 const pjsua_med_tp_state_info *info); 1854 static void on_media_event(pjmedia_event *event); 1855 static void on_call_media_event(pjsua_call_id call_id, 1856 unsigned med_idx, 1857 pjmedia_event *event); 1858 static pjmedia_transport* 1859 on_create_media_transport(pjsua_call_id call_id, 1860 unsigned media_idx, 1861 pjmedia_transport *base_tp, 1862 unsigned flags); 1863 static void 1864 on_create_media_transport_srtp(pjsua_call_id call_id, 1865 unsigned media_idx, 1866 pjmedia_srtp_setting *srtp_opt); 1867 1868 static void 1869 on_ip_change_progress(pjsua_ip_change_op op, 1870 pj_status_t status, 1871 const pjsua_ip_change_op_info *info); 1872 1873 private: 1874 void clearCodecInfoList(CodecInfoVector &codec_list); 1875 void updateCodecInfoList(pjsua_codec_info pj_codec[], unsigned count, 1876 CodecInfoVector &codec_list); 1877 1878 }; 1879 1880 1881 1882 /** 1883 * @} PJSUA2_UA 1884 */ 1885 1886 } 1887 /* End pj namespace */ 1888 1889 1890 #endif /* __PJSUA2_UA_HPP__ */ 1891 1892