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_ACCOUNT_HPP__ 20 #define __PJSUA2_ACCOUNT_HPP__ 21 22 /** 23 * @file pjsua2/account.hpp 24 * @brief PJSUA2 Account operations 25 */ 26 #include <pjsua-lib/pjsua.h> 27 #include <pjsua2/persistent.hpp> 28 #include <pjsua2/presence.hpp> 29 #include <pjsua2/siptypes.hpp> 30 31 /** PJSUA2 API is inside pj namespace */ 32 namespace pj 33 { 34 35 /** 36 * @defgroup PJSUA2_ACC Account 37 * @ingroup PJSUA2_Ref 38 * @{ 39 */ 40 41 using std::string; 42 43 /** 44 * Account registration config. This will be specified in AccountConfig. 45 */ 46 struct AccountRegConfig : public PersistentObject 47 { 48 /** 49 * This is the URL to be put in the request URI for the registration, 50 * and will look something like "sip:serviceprovider". 51 * 52 * This field should be specified if registration is desired. If the 53 * value is empty, no account registration will be performed. 54 */ 55 string registrarUri; 56 57 /** 58 * Specify whether the account should register as soon as it is 59 * added to the UA. Application can set this to PJ_FALSE and control 60 * the registration manually with pjsua_acc_set_registration(). 61 * 62 * Default: True 63 */ 64 bool registerOnAdd; 65 66 /** 67 * The optional custom SIP headers to be put in the registration 68 * request. 69 */ 70 SipHeaderVector headers; 71 72 /** 73 * Additional parameters that will be appended in the Contact header 74 * of the registration requests. This will be appended after 75 * \a AccountSipConfig.contactParams; 76 * 77 * The parameters should be preceeded by semicolon, and all strings must 78 * be properly escaped. Example: 79 * ";my-param=X;another-param=Hi%20there" 80 */ 81 string contactParams; 82 83 /** 84 * Optional interval for registration, in seconds. If the value is zero, 85 * default interval will be used (PJSUA_REG_INTERVAL, 300 seconds). 86 */ 87 unsigned timeoutSec; 88 89 /** 90 * Specify interval of auto registration retry upon registration failure 91 * (including caused by transport problem), in second. Set to 0 to 92 * disable auto re-registration. Note that if the registration retry 93 * occurs because of transport failure, the first retry will be done 94 * after \a firstRetryIntervalSec seconds instead. Also note that 95 * the interval will be randomized slightly by some seconds (specified 96 * in \a reg_retry_random_interval) to avoid all clients re-registering 97 * at the same time. 98 * 99 * See also \a firstRetryIntervalSec and \a randomRetryIntervalSec 100 * settings. 101 * 102 * Default: PJSUA_REG_RETRY_INTERVAL 103 */ 104 unsigned retryIntervalSec; 105 106 /** 107 * This specifies the interval for the first registration retry. The 108 * registration retry is explained in \a retryIntervalSec. Note that 109 * the value here will also be randomized by some seconds (specified 110 * in \a reg_retry_random_interval) to avoid all clients re-registering 111 * at the same time. 112 * 113 * See also \a retryIntervalSec and \a randomRetryIntervalSec settings. 114 * 115 * Default: 0 116 */ 117 unsigned firstRetryIntervalSec; 118 119 /** 120 * This specifies maximum randomized value to be added/substracted 121 * to/from the registration retry interval specified in \a 122 * reg_retry_interval and \a reg_first_retry_interval, in second. 123 * This is useful to avoid all clients re-registering at the same time. 124 * For example, if the registration retry interval is set to 100 seconds 125 * and this is set to 10 seconds, the actual registration retry interval 126 * will be in the range of 90 to 110 seconds. 127 * 128 * See also \a retryIntervalSec and \a firstRetryIntervalSec settings. 129 * 130 * Default: 10 131 */ 132 unsigned randomRetryIntervalSec; 133 134 /** 135 * Specify the number of seconds to refresh the client registration 136 * before the registration expires. 137 * 138 * Default: PJSIP_REGISTER_CLIENT_DELAY_BEFORE_REFRESH, 5 seconds 139 */ 140 unsigned delayBeforeRefreshSec; 141 142 /** 143 * Specify whether calls of the configured account should be dropped 144 * after registration failure and an attempt of re-registration has 145 * also failed. 146 * 147 * Default: FALSE (disabled) 148 */ 149 bool dropCallsOnFail; 150 151 /** 152 * Specify the maximum time to wait for unregistration requests to 153 * complete during library shutdown sequence. 154 * 155 * Default: PJSUA_UNREG_TIMEOUT 156 */ 157 unsigned unregWaitMsec; 158 159 /** 160 * Specify how the registration uses the outbound and account proxy 161 * settings. This controls if and what Route headers will appear in 162 * the REGISTER request of this account. The value is bitmask combination 163 * of PJSUA_REG_USE_OUTBOUND_PROXY and PJSUA_REG_USE_ACC_PROXY bits. 164 * If the value is set to 0, the REGISTER request will not use any proxy 165 * (i.e. it will not have any Route headers). 166 * 167 * Default: 3 (PJSUA_REG_USE_OUTBOUND_PROXY | PJSUA_REG_USE_ACC_PROXY) 168 */ 169 unsigned proxyUse; 170 171 public: 172 /** 173 * Read this object from a container node. 174 * 175 * @param node Container to read values from. 176 */ 177 virtual void readObject(const ContainerNode &node) PJSUA2_THROW(Error); 178 179 /** 180 * Write this object to a container node. 181 * 182 * @param node Container to write values to. 183 */ 184 virtual void writeObject(ContainerNode &node) const PJSUA2_THROW(Error); 185 186 }; 187 188 /** Array of SIP credentials */ 189 typedef std::vector<AuthCredInfo> AuthCredInfoVector; 190 191 /** 192 * Various SIP settings for the account. This will be specified in 193 * AccountConfig. 194 */ 195 struct AccountSipConfig : public PersistentObject 196 { 197 /** 198 * Array of credentials. If registration is desired, normally there should 199 * be at least one credential specified, to successfully authenticate 200 * against the service provider. More credentials can be specified, for 201 * example when the requests are expected to be challenged by the 202 * proxies in the route set. 203 */ 204 AuthCredInfoVector authCreds; 205 206 /** 207 * Array of proxy servers to visit for outgoing requests. Each of the 208 * entry is translated into one Route URI. 209 */ 210 StringVector proxies; 211 212 /** 213 * Optional URI to be put as Contact for this account. It is recommended 214 * that this field is left empty, so that the value will be calculated 215 * automatically based on the transport address. 216 */ 217 string contactForced; 218 219 /** 220 * Additional parameters that will be appended in the Contact header 221 * for this account. This will affect the Contact header in all SIP 222 * messages sent on behalf of this account, including but not limited to 223 * REGISTER, INVITE, and SUBCRIBE requests or responses. 224 * 225 * The parameters should be preceeded by semicolon, and all strings must 226 * be properly escaped. Example: 227 * ";my-param=X;another-param=Hi%20there" 228 */ 229 string contactParams; 230 231 /** 232 * Additional URI parameters that will be appended in the Contact URI 233 * for this account. This will affect the Contact URI in all SIP 234 * messages sent on behalf of this account, including but not limited to 235 * REGISTER, INVITE, and SUBCRIBE requests or responses. 236 * 237 * The parameters should be preceeded by semicolon, and all strings must 238 * be properly escaped. Example: 239 * ";my-param=X;another-param=Hi%20there" 240 */ 241 string contactUriParams; 242 243 244 /** 245 * If this flag is set, the authentication client framework will 246 * send an empty Authorization header in each initial request. 247 * Default is no. 248 */ 249 bool authInitialEmpty; 250 251 /** 252 * Specify the algorithm to use when empty Authorization header 253 * is to be sent for each initial request (see above) 254 */ 255 string authInitialAlgorithm; 256 257 /** 258 * Optionally bind this account to specific transport. This normally is 259 * not a good idea, as account should be able to send requests using 260 * any available transports according to the destination. But some 261 * application may want to have explicit control over the transport to 262 * use, so in that case it can set this field. 263 * 264 * Default: -1 (PJSUA_INVALID_ID) 265 * 266 * @see Account::setTransport() 267 */ 268 TransportId transportId; 269 270 public: 271 /** 272 * Read this object from a container node. 273 * 274 * @param node Container to read values from. 275 */ 276 virtual void readObject(const ContainerNode &node) PJSUA2_THROW(Error); 277 278 /** 279 * Write this object to a container node. 280 * 281 * @param node Container to write values to. 282 */ 283 virtual void writeObject(ContainerNode &node) const PJSUA2_THROW(Error); 284 }; 285 286 /** 287 * Account's call settings. This will be specified in AccountConfig. 288 */ 289 struct AccountCallConfig : public PersistentObject 290 { 291 /** 292 * Specify how to offer call hold to remote peer. Please see the 293 * documentation on pjsua_call_hold_type for more info. 294 * 295 * Default: PJSUA_CALL_HOLD_TYPE_DEFAULT 296 */ 297 pjsua_call_hold_type holdType; 298 299 /** 300 * Specify how support for reliable provisional response (100rel/ 301 * PRACK) should be used for all sessions in this account. See the 302 * documentation of pjsua_100rel_use enumeration for more info. 303 * 304 * Default: PJSUA_100REL_NOT_USED 305 */ 306 pjsua_100rel_use prackUse; 307 308 /** 309 * Specify the usage of Session Timers for all sessions. See the 310 * pjsua_sip_timer_use for possible values. 311 * 312 * Default: PJSUA_SIP_TIMER_OPTIONAL 313 */ 314 pjsua_sip_timer_use timerUse; 315 316 /** 317 * Specify minimum Session Timer expiration period, in seconds. 318 * Must not be lower than 90. Default is 90. 319 */ 320 unsigned timerMinSESec; 321 322 /** 323 * Specify Session Timer expiration period, in seconds. 324 * Must not be lower than timerMinSE. Default is 1800. 325 */ 326 unsigned timerSessExpiresSec; 327 328 public: 329 /** 330 * Default constructor 331 */ AccountCallConfigpj::AccountCallConfig332 AccountCallConfig() : holdType(PJSUA_CALL_HOLD_TYPE_DEFAULT), 333 prackUse(PJSUA_100REL_NOT_USED), 334 timerUse(PJSUA_SIP_TIMER_OPTIONAL) 335 {} 336 337 /** 338 * Read this object from a container node. 339 * 340 * @param node Container to read values from. 341 */ 342 virtual void readObject(const ContainerNode &node) PJSUA2_THROW(Error); 343 344 /** 345 * Write this object to a container node. 346 * 347 * @param node Container to write values to. 348 */ 349 virtual void writeObject(ContainerNode &node) const PJSUA2_THROW(Error); 350 }; 351 352 /** 353 * Account presence config. This will be specified in AccountConfig. 354 */ 355 struct AccountPresConfig : public PersistentObject 356 { 357 /** 358 * The optional custom SIP headers to be put in the presence 359 * subscription request. 360 */ 361 SipHeaderVector headers; 362 363 /** 364 * If this flag is set, the presence information of this account will 365 * be PUBLISH-ed to the server where the account belongs. 366 * 367 * Default: PJ_FALSE 368 */ 369 bool publishEnabled; 370 371 /** 372 * Specify whether the client publication session should queue the 373 * PUBLISH request should there be another PUBLISH transaction still 374 * pending. If this is set to false, the client will return error 375 * on the PUBLISH request if there is another PUBLISH transaction still 376 * in progress. 377 * 378 * Default: PJSIP_PUBLISHC_QUEUE_REQUEST (TRUE) 379 */ 380 bool publishQueue; 381 382 /** 383 * Maximum time to wait for unpublication transaction(s) to complete 384 * during shutdown process, before sending unregistration. The library 385 * tries to wait for the unpublication (un-PUBLISH) to complete before 386 * sending REGISTER request to unregister the account, during library 387 * shutdown process. If the value is set too short, it is possible that 388 * the unregistration is sent before unpublication completes, causing 389 * unpublication request to fail. 390 * 391 * Value is in milliseconds. 392 * 393 * Default: PJSUA_UNPUBLISH_MAX_WAIT_TIME_MSEC (2000) 394 */ 395 unsigned publishShutdownWaitMsec; 396 397 /** 398 * Optional PIDF tuple ID for outgoing PUBLISH and NOTIFY. If this value 399 * is not specified, a random string will be used. 400 */ 401 string pidfTupleId; 402 403 public: 404 /** 405 * Read this object from a container node. 406 * 407 * @param node Container to read values from. 408 */ 409 virtual void readObject(const ContainerNode &node) PJSUA2_THROW(Error); 410 411 /** 412 * Write this object to a container node. 413 * 414 * @param node Container to write values to. 415 */ 416 virtual void writeObject(ContainerNode &node) const PJSUA2_THROW(Error); 417 }; 418 419 /** 420 * Account MWI (Message Waiting Indication) settings. This will be specified 421 * in AccountConfig. 422 */ 423 struct AccountMwiConfig : public PersistentObject 424 { 425 /** 426 * Subscribe to message waiting indication events (RFC 3842). 427 * 428 * See also UaConfig.mwiUnsolicitedEnabled setting. 429 * 430 * Default: FALSE 431 */ 432 bool enabled; 433 434 /** 435 * Specify the default expiration time (in seconds) for Message 436 * Waiting Indication (RFC 3842) event subscription. This must not 437 * be zero. 438 * 439 * Default: PJSIP_MWI_DEFAULT_EXPIRES (3600) 440 */ 441 unsigned expirationSec; 442 443 public: 444 /** 445 * Read this object from a container node. 446 * 447 * @param node Container to read values from. 448 */ 449 virtual void readObject(const ContainerNode &node) PJSUA2_THROW(Error); 450 451 /** 452 * Write this object to a container node. 453 * 454 * @param node Container to write values to. 455 */ 456 virtual void writeObject(ContainerNode &node) const PJSUA2_THROW(Error); 457 }; 458 459 /** 460 * Account's NAT (Network Address Translation) settings. This will be 461 * specified in AccountConfig. 462 */ 463 struct AccountNatConfig : public PersistentObject 464 { 465 /** 466 * Control the use of STUN for the SIP signaling. 467 * 468 * Default: PJSUA_STUN_USE_DEFAULT 469 */ 470 pjsua_stun_use sipStunUse; 471 472 /** 473 * Control the use of STUN for the media transports. 474 * 475 * Default: PJSUA_STUN_USE_DEFAULT 476 */ 477 pjsua_stun_use mediaStunUse; 478 479 /** 480 * Specify NAT64 options. 481 * 482 * Default: PJSUA_NAT64_DISABLED 483 */ 484 pjsua_nat64_opt nat64Opt; 485 486 /** 487 * Enable ICE for the media transport. 488 * 489 * Default: False 490 */ 491 bool iceEnabled; 492 493 /** 494 * Set trickle ICE mode for ICE media transport. 495 * 496 * Default: PJ_ICE_SESS_TRICKLE_DISABLED 497 */ 498 pj_ice_sess_trickle iceTrickle; 499 500 /** 501 * Set the maximum number of ICE host candidates. 502 * 503 * Default: -1 (maximum not set) 504 */ 505 int iceMaxHostCands; 506 507 /** 508 * Specify whether to use aggressive nomination. 509 * 510 * Default: True 511 */ 512 bool iceAggressiveNomination; 513 514 /** 515 * For controlling agent if it uses regular nomination, specify the delay 516 * to perform nominated check (connectivity check with USE-CANDIDATE 517 * attribute) after all components have a valid pair. 518 * 519 * Default value is PJ_ICE_NOMINATED_CHECK_DELAY. 520 */ 521 unsigned iceNominatedCheckDelayMsec; 522 523 /** 524 * For a controlled agent, specify how long it wants to wait (in 525 * milliseconds) for the controlling agent to complete sending 526 * connectivity check with nominated flag set to true for all components 527 * after the controlled agent has found that all connectivity checks in 528 * its checklist have been completed and there is at least one successful 529 * (but not nominated) check for every component. 530 * 531 * Default value for this option is 532 * ICE_CONTROLLED_AGENT_WAIT_NOMINATION_TIMEOUT. Specify -1 to disable 533 * this timer. 534 */ 535 int iceWaitNominationTimeoutMsec; 536 537 /** 538 * Disable RTCP component. 539 * 540 * Default: False 541 */ 542 bool iceNoRtcp; 543 544 /** 545 * Always send re-INVITE/UPDATE after ICE negotiation regardless of whether 546 * the default ICE transport address is changed or not. When this is set 547 * to False, re-INVITE/UPDATE will be sent only when the default ICE 548 * transport address is changed. 549 * 550 * Default: yes 551 */ 552 bool iceAlwaysUpdate; 553 554 /** 555 * Enable TURN candidate in ICE. 556 */ 557 bool turnEnabled; 558 559 /** 560 * Specify TURN domain name or host name, in in "DOMAIN:PORT" or 561 * "HOST:PORT" format. 562 */ 563 string turnServer; 564 565 /** 566 * Specify the connection type to be used to the TURN server. Valid 567 * values are PJ_TURN_TP_UDP or PJ_TURN_TP_TCP. 568 * 569 * Default: PJ_TURN_TP_UDP 570 */ 571 pj_turn_tp_type turnConnType; 572 573 /** 574 * Specify the username to authenticate with the TURN server. 575 */ 576 string turnUserName; 577 578 /** 579 * Specify the type of password. Currently this must be zero to 580 * indicate plain-text password will be used in the password. 581 */ 582 int turnPasswordType; 583 584 /** 585 * Specify the password to authenticate with the TURN server. 586 */ 587 string turnPassword; 588 589 /** 590 * This option is used to update the transport address and the Contact 591 * header of REGISTER request. When this option is enabled, the library 592 * will keep track of the public IP address from the response of REGISTER 593 * request. Once it detects that the address has changed, it will 594 * unregister current Contact, update the Contact with transport address 595 * learned from Via header, and register a new Contact to the registrar. 596 * This will also update the public name of UDP transport if STUN is 597 * configured. 598 * 599 * See also contactRewriteMethod field. 600 * 601 * Default: TRUE 602 */ 603 int contactRewriteUse; 604 605 /** 606 * Specify how Contact update will be done with the registration, if 607 * \a contactRewriteEnabled is enabled. The value is bitmask combination of 608 * \a pjsua_contact_rewrite_method. See also pjsua_contact_rewrite_method. 609 * 610 * Value PJSUA_CONTACT_REWRITE_UNREGISTER(1) is the legacy behavior. 611 * 612 * Default value: PJSUA_CONTACT_REWRITE_METHOD 613 * (PJSUA_CONTACT_REWRITE_NO_UNREG | PJSUA_CONTACT_REWRITE_ALWAYS_UPDATE) 614 */ 615 int contactRewriteMethod; 616 617 /** 618 * Specify if source TCP port should be used as the initial Contact 619 * address if TCP/TLS transport is used. Note that this feature will 620 * be automatically turned off when nameserver is configured because 621 * it may yield different destination address due to DNS SRV resolution. 622 * Also some platforms are unable to report the local address of the 623 * TCP socket when it is still connecting. In these cases, this 624 * feature will also be turned off. 625 * 626 * Default: 1 (yes). 627 */ 628 int contactUseSrcPort; 629 630 /** 631 * This option is used to overwrite the "sent-by" field of the Via header 632 * for outgoing messages with the same interface address as the one in 633 * the REGISTER request, as long as the request uses the same transport 634 * instance as the previous REGISTER request. 635 * 636 * Default: TRUE 637 */ 638 int viaRewriteUse; 639 640 /** 641 * This option controls whether the IP address in SDP should be replaced 642 * with the IP address found in Via header of the REGISTER response, ONLY 643 * when STUN and ICE are not used. If the value is FALSE (the original 644 * behavior), then the local IP address will be used. If TRUE, and when 645 * STUN and ICE are disabled, then the IP address found in registration 646 * response will be used. 647 * 648 * Default: PJ_FALSE (no) 649 */ 650 int sdpNatRewriteUse; 651 652 /** 653 * Control the use of SIP outbound feature. SIP outbound is described in 654 * RFC 5626 to enable proxies or registrar to send inbound requests back 655 * to UA using the same connection initiated by the UA for its 656 * registration. This feature is highly useful in NAT-ed deployemtns, 657 * hence it is enabled by default. 658 * 659 * Note: currently SIP outbound can only be used with TCP and TLS 660 * transports. If UDP is used for the registration, the SIP outbound 661 * feature will be silently ignored for the account. 662 * 663 * Default: TRUE 664 */ 665 int sipOutboundUse; 666 667 /** 668 * Specify SIP outbound (RFC 5626) instance ID to be used by this 669 * account. If empty, an instance ID will be generated based on 670 * the hostname of this agent. If application specifies this parameter, the 671 * value will look like "<urn:uuid:00000000-0000-1000-8000-AABBCCDDEEFF>" 672 * without the double-quotes. 673 * 674 * Default: empty 675 */ 676 string sipOutboundInstanceId; 677 678 /** 679 * Specify SIP outbound (RFC 5626) registration ID. The default value 680 * is empty, which would cause the library to automatically generate 681 * a suitable value. 682 * 683 * Default: empty 684 */ 685 string sipOutboundRegId; 686 687 /** 688 * Set the interval for periodic keep-alive transmission for this account. 689 * If this value is zero, keep-alive will be disabled for this account. 690 * The keep-alive transmission will be sent to the registrar's address, 691 * after successful registration. 692 * 693 * Default: 15 (seconds) 694 */ 695 unsigned udpKaIntervalSec; 696 697 /** 698 * Specify the data to be transmitted as keep-alive packets. 699 * 700 * Default: CR-LF 701 */ 702 string udpKaData; 703 704 public: 705 /** 706 * Default constructor 707 */ AccountNatConfigpj::AccountNatConfig708 AccountNatConfig() : sipStunUse(PJSUA_STUN_USE_DEFAULT), 709 mediaStunUse(PJSUA_STUN_USE_DEFAULT), 710 nat64Opt(PJSUA_NAT64_DISABLED), 711 turnConnType(PJ_TURN_TP_UDP) 712 {} 713 714 /** 715 * Read this object from a container node. 716 * 717 * @param node Container to read values from. 718 */ 719 virtual void readObject(const ContainerNode &node) PJSUA2_THROW(Error); 720 721 /** 722 * Write this object to a container node. 723 * 724 * @param node Container to write values to. 725 */ 726 virtual void writeObject(ContainerNode &node) const PJSUA2_THROW(Error); 727 }; 728 729 /** 730 * SRTP crypto. 731 */ 732 struct SrtpCrypto 733 { 734 /** 735 * Optional key. If empty, a random key will be autogenerated. 736 */ 737 string key; 738 739 /** 740 * Crypto name. 741 */ 742 string name; 743 744 /** 745 * Flags, bitmask from #pjmedia_srtp_crypto_option 746 */ 747 unsigned flags; 748 749 public: 750 /** 751 * Convert from pjsip 752 */ 753 void fromPj(const pjmedia_srtp_crypto &prm); 754 755 /** 756 * Convert to pjsip 757 */ 758 pjmedia_srtp_crypto toPj() const; 759 }; 760 761 /* Array of SRTP cryptos. */ 762 typedef std::vector<SrtpCrypto> SrtpCryptoVector; 763 764 /** 765 * SRTP settings. 766 */ 767 struct SrtpOpt : public PersistentObject 768 { 769 /** 770 * Specify SRTP cryptos. If empty, all crypto will be enabled. 771 * Available crypto can be enumerated using Endpoint::srtpCryptoEnum(). 772 * 773 * Default: empty. 774 */ 775 SrtpCryptoVector cryptos; 776 777 /** 778 * Specify SRTP keying methods, valid keying method is defined in 779 * pjmedia_srtp_keying_method. If empty, all keying methods will be 780 * enabled with priority order: SDES, DTLS-SRTP. 781 * 782 * Default: empty. 783 */ 784 IntVector keyings; 785 786 public: 787 /** 788 * Default constructor initializes with default values. 789 */ 790 SrtpOpt(); 791 792 /** 793 * Convert from pjsip 794 */ 795 void fromPj(const pjsua_srtp_opt &prm); 796 797 /** 798 * Convert to pjsip 799 */ 800 pjsua_srtp_opt toPj() const; 801 802 public: 803 /** 804 * Read this object from a container node. 805 * 806 * @param node Container to read values from. 807 */ 808 virtual void readObject(const ContainerNode &node) PJSUA2_THROW(Error); 809 810 /** 811 * Write this object to a container node. 812 * 813 * @param node Container to write values to. 814 */ 815 virtual void writeObject(ContainerNode &node) const PJSUA2_THROW(Error); 816 }; 817 818 /** 819 * RTCP Feedback capability. 820 */ 821 struct RtcpFbCap 822 { 823 /** 824 * Specify the codecs to which the capability is applicable. Codec ID is 825 * using the same format as in pjmedia_codec_mgr_find_codecs_by_id() and 826 * pjmedia_vid_codec_mgr_find_codecs_by_id(), e.g: "L16/8000/1", "PCMU", 827 * "H264". This can also be an asterisk ("*") to represent all codecs. 828 */ 829 string codecId; 830 831 /** 832 * Specify the RTCP Feedback type. 833 */ 834 pjmedia_rtcp_fb_type type; 835 836 /** 837 * Specify the type name if RTCP Feedback type is PJMEDIA_RTCP_FB_OTHER. 838 */ 839 string typeName; 840 841 /** 842 * Specify the RTCP Feedback parameters. 843 */ 844 string param; 845 846 public: 847 /** 848 * Constructor. 849 */ RtcpFbCappj::RtcpFbCap850 RtcpFbCap() : type(PJMEDIA_RTCP_FB_OTHER) 851 {} 852 853 /** 854 * Convert from pjsip 855 */ 856 void fromPj(const pjmedia_rtcp_fb_cap &prm); 857 858 /** 859 * Convert to pjsip 860 */ 861 pjmedia_rtcp_fb_cap toPj() const; 862 }; 863 864 /* Array of RTCP Feedback capabilities. */ 865 typedef std::vector<RtcpFbCap> RtcpFbCapVector; 866 867 868 /** 869 * RTCP Feedback settings. 870 */ 871 struct RtcpFbConfig : public PersistentObject 872 { 873 /** 874 * Specify whether transport protocol in SDP media description uses 875 * RTP/AVP instead of RTP/AVPF. Note that the standard mandates to signal 876 * AVPF profile, but it may cause SDP negotiation failure when negotiating 877 * with endpoints that does not support RTCP Feedback (including older 878 * version of PJSIP). 879 * 880 * Default: false. 881 */ 882 bool dontUseAvpf; 883 884 /** 885 * RTCP Feedback capabilities. 886 */ 887 RtcpFbCapVector caps; 888 889 public: 890 /** 891 * Constructor. 892 */ 893 RtcpFbConfig(); 894 895 /** 896 * Convert from pjsip 897 */ 898 void fromPj(const pjmedia_rtcp_fb_setting &prm); 899 900 /** 901 * Convert to pjsip 902 */ 903 pjmedia_rtcp_fb_setting toPj() const; 904 905 public: 906 /** 907 * Read this object from a container node. 908 * 909 * @param node Container to read values from. 910 */ 911 virtual void readObject(const ContainerNode &node) PJSUA2_THROW(Error); 912 913 /** 914 * Write this object to a container node. 915 * 916 * @param node Container to write values to. 917 */ 918 virtual void writeObject(ContainerNode &node) const PJSUA2_THROW(Error); 919 }; 920 921 /** 922 * Account media config (applicable for both audio and video). This will be 923 * specified in AccountConfig. 924 */ 925 struct AccountMediaConfig : public PersistentObject 926 { 927 /** 928 * Media transport (RTP) configuration. 929 */ 930 TransportConfig transportConfig; 931 932 /** 933 * If remote sends SDP answer containing more than one format or codec in 934 * the media line, send re-INVITE or UPDATE with just one codec to lock 935 * which codec to use. 936 * 937 * Default: True (Yes). 938 */ 939 bool lockCodecEnabled; 940 941 /** 942 * Specify whether stream keep-alive and NAT hole punching with 943 * non-codec-VAD mechanism (see PJMEDIA_STREAM_ENABLE_KA) is enabled 944 * for this account. 945 * 946 * Default: False 947 */ 948 bool streamKaEnabled; 949 950 /** 951 * Specify whether secure media transport should be used for this account. 952 * Valid values are PJMEDIA_SRTP_DISABLED, PJMEDIA_SRTP_OPTIONAL, and 953 * PJMEDIA_SRTP_MANDATORY. 954 * 955 * Default: PJSUA_DEFAULT_USE_SRTP 956 */ 957 pjmedia_srtp_use srtpUse; 958 959 /** 960 * Specify whether SRTP requires secure signaling to be used. This option 961 * is only used when \a use_srtp option above is non-zero. 962 * 963 * Valid values are: 964 * 0: SRTP does not require secure signaling 965 * 1: SRTP requires secure transport such as TLS 966 * 2: SRTP requires secure end-to-end transport (SIPS) 967 * 968 * Default: PJSUA_DEFAULT_SRTP_SECURE_SIGNALING 969 */ 970 int srtpSecureSignaling; 971 972 /** 973 * Specify SRTP settings, like cryptos and keying methods. 974 */ 975 SrtpOpt srtpOpt; 976 977 /** 978 * Specify whether IPv6 should be used on media. Default is not used. 979 */ 980 pjsua_ipv6_use ipv6Use; 981 982 /** 983 * Enable RTP and RTCP multiplexing. 984 */ 985 bool rtcpMuxEnabled; 986 987 /** 988 * RTCP Feedback settings. 989 */ 990 RtcpFbConfig rtcpFbConfig; 991 992 public: 993 /** 994 * Default constructor 995 */ AccountMediaConfigpj::AccountMediaConfig996 AccountMediaConfig() : srtpUse(PJSUA_DEFAULT_USE_SRTP), 997 ipv6Use(PJSUA_IPV6_DISABLED) 998 {} 999 1000 /** 1001 * Read this object from a container node. 1002 * 1003 * @param node Container to read values from. 1004 */ 1005 virtual void readObject(const ContainerNode &node) PJSUA2_THROW(Error); 1006 1007 /** 1008 * Write this object to a container node. 1009 * 1010 * @param node Container to write values to. 1011 */ 1012 virtual void writeObject(ContainerNode &node) const PJSUA2_THROW(Error); 1013 }; 1014 1015 /** 1016 * Account video config. This will be specified in AccountConfig. 1017 */ 1018 struct AccountVideoConfig : public PersistentObject 1019 { 1020 /** 1021 * Specify whether incoming video should be shown to screen by default. 1022 * This applies to incoming call (INVITE), incoming re-INVITE, and 1023 * incoming UPDATE requests. 1024 * 1025 * Regardless of this setting, application can detect incoming video 1026 * by implementing \a on_call_media_state() callback and enumerating 1027 * the media stream(s) with pjsua_call_get_info(). Once incoming 1028 * video is recognised, application may retrieve the window associated 1029 * with the incoming video and show or hide it with 1030 * pjsua_vid_win_set_show(). 1031 * 1032 * Default: False 1033 */ 1034 bool autoShowIncoming; 1035 1036 /** 1037 * Specify whether outgoing video should be activated by default when 1038 * making outgoing calls and/or when incoming video is detected. This 1039 * applies to incoming and outgoing calls, incoming re-INVITE, and 1040 * incoming UPDATE. If the setting is non-zero, outgoing video 1041 * transmission will be started as soon as response to these requests 1042 * is sent (or received). 1043 * 1044 * Regardless of the value of this setting, application can start and 1045 * stop outgoing video transmission with pjsua_call_set_vid_strm(). 1046 * 1047 * Default: False 1048 */ 1049 bool autoTransmitOutgoing; 1050 1051 /** 1052 * Specify video window's flags. The value is a bitmask combination of 1053 * pjmedia_vid_dev_wnd_flag. 1054 * 1055 * Default: 0 1056 */ 1057 unsigned windowFlags; 1058 1059 /** 1060 * Specify the default capture device to be used by this account. If 1061 * vidOutAutoTransmit is enabled, this device will be used for 1062 * capturing video. 1063 * 1064 * Default: PJMEDIA_VID_DEFAULT_CAPTURE_DEV 1065 */ 1066 pjmedia_vid_dev_index defaultCaptureDevice; 1067 1068 /** 1069 * Specify the default rendering device to be used by this account. 1070 * 1071 * Default: PJMEDIA_VID_DEFAULT_RENDER_DEV 1072 */ 1073 pjmedia_vid_dev_index defaultRenderDevice; 1074 1075 /** 1076 * Rate control method. 1077 * 1078 * Default: PJMEDIA_VID_STREAM_RC_SIMPLE_BLOCKING. 1079 */ 1080 pjmedia_vid_stream_rc_method rateControlMethod; 1081 1082 /** 1083 * Upstream/outgoing bandwidth. If this is set to zero, the video stream 1084 * will use codec maximum bitrate setting. 1085 * 1086 * Default: 0 (follow codec maximum bitrate). 1087 */ 1088 unsigned rateControlBandwidth; 1089 1090 /** 1091 * The number of keyframe to be sent after the stream is created. 1092 * 1093 * Default: PJMEDIA_VID_STREAM_START_KEYFRAME_CNT 1094 */ 1095 unsigned startKeyframeCount; 1096 1097 /** 1098 * The keyframe sending interval after the stream is created. 1099 * 1100 * Default: PJMEDIA_VID_STREAM_START_KEYFRAME_INTERVAL_MSEC 1101 */ 1102 unsigned startKeyframeInterval; 1103 1104 1105 public: 1106 /** 1107 * Default constructor 1108 */ AccountVideoConfigpj::AccountVideoConfig1109 AccountVideoConfig() : 1110 rateControlMethod(PJMEDIA_VID_STREAM_RC_SIMPLE_BLOCKING) 1111 {} 1112 1113 /** 1114 * Read this object from a container node. 1115 * 1116 * @param node Container to read values from. 1117 */ 1118 virtual void readObject(const ContainerNode &node) PJSUA2_THROW(Error); 1119 1120 /** 1121 * Write this object to a container node. 1122 * 1123 * @param node Container to write values to. 1124 */ 1125 virtual void writeObject(ContainerNode &node) const PJSUA2_THROW(Error); 1126 }; 1127 1128 /** 1129 * Account config specific to IP address change. 1130 */ 1131 typedef struct AccountIpChangeConfig 1132 { 1133 /** 1134 * Shutdown the transport used for account registration. If this is set to 1135 * PJ_TRUE, the transport will be shutdown altough it's used by multiple 1136 * account. Shutdown transport will be followed by re-Registration if 1137 * AccountConfig.natConfig.contactRewriteUse is enabled. 1138 * 1139 * Default: true 1140 */ 1141 bool shutdownTp; 1142 1143 /** 1144 * Hangup active calls associated with the acount. If this is set to true, 1145 * then the calls will be hang up. 1146 * 1147 * Default: false 1148 */ 1149 bool hangupCalls; 1150 1151 /** 1152 * Specify the call flags used in the re-INVITE when \a hangupCalls is set 1153 * to false. If this is set to 0, no re-INVITE will be sent. The 1154 * re-INVITE will be sent after re-Registration is finished. 1155 * 1156 * Default: PJSUA_CALL_REINIT_MEDIA | PJSUA_CALL_UPDATE_CONTACT | 1157 * PJSUA_CALL_UPDATE_VIA 1158 */ 1159 unsigned reinviteFlags; 1160 1161 public: 1162 /** 1163 * Virtual destructor 1164 */ ~AccountIpChangeConfigpj::AccountIpChangeConfig1165 virtual ~AccountIpChangeConfig() 1166 {} 1167 1168 /** 1169 * Read this object from a container node. 1170 * 1171 * @param node Container to read values from. 1172 */ 1173 virtual void readObject(const ContainerNode &node) PJSUA2_THROW(Error); 1174 1175 /** 1176 * Write this object to a container node. 1177 * 1178 * @param node Container to write values to. 1179 */ 1180 virtual void writeObject(ContainerNode &node) const PJSUA2_THROW(Error); 1181 1182 } AccountIpChangeConfig; 1183 1184 /** 1185 * Account configuration. 1186 */ 1187 struct AccountConfig : public PersistentObject 1188 { 1189 /** 1190 * Account priority, which is used to control the order of matching 1191 * incoming/outgoing requests. The higher the number means the higher 1192 * the priority is, and the account will be matched first. 1193 */ 1194 int priority; 1195 1196 /** 1197 * The Address of Record or AOR, that is full SIP URL that identifies the 1198 * account. The value can take name address or URL format, and will look 1199 * something like "sip:account@serviceprovider". 1200 * 1201 * This field is mandatory. 1202 */ 1203 string idUri; 1204 1205 /** 1206 * Registration settings. 1207 */ 1208 AccountRegConfig regConfig; 1209 1210 /** 1211 * SIP settings. 1212 */ 1213 AccountSipConfig sipConfig; 1214 1215 /** 1216 * Call settings. 1217 */ 1218 AccountCallConfig callConfig; 1219 1220 /** 1221 * Presence settings. 1222 */ 1223 AccountPresConfig presConfig; 1224 1225 /** 1226 * MWI (Message Waiting Indication) settings. 1227 */ 1228 AccountMwiConfig mwiConfig; 1229 1230 /** 1231 * NAT settings. 1232 */ 1233 AccountNatConfig natConfig; 1234 1235 /** 1236 * Media settings (applicable for both audio and video). 1237 */ 1238 AccountMediaConfig mediaConfig; 1239 1240 /** 1241 * Video settings. 1242 */ 1243 AccountVideoConfig videoConfig; 1244 1245 /** 1246 * IP Change settings. 1247 */ 1248 AccountIpChangeConfig ipChangeConfig; 1249 1250 public: 1251 /** 1252 * Default constructor will initialize with default values. 1253 */ 1254 AccountConfig(); 1255 1256 /** 1257 * This will return a temporary pjsua_acc_config instance, which contents 1258 * are only valid as long as this AccountConfig structure remains valid 1259 * AND no modifications are done to it AND no further toPj() function call 1260 * is made. Any call to toPj() function will invalidate the content of 1261 * temporary pjsua_acc_config that was returned by the previous call. 1262 */ 1263 void toPj(pjsua_acc_config &cfg) const; 1264 1265 /** 1266 * Initialize from pjsip. 1267 */ 1268 void fromPj(const pjsua_acc_config &prm, const pjsua_media_config *mcfg); 1269 1270 /** 1271 * Read this object from a container node. 1272 * 1273 * @param node Container to read values from. 1274 */ 1275 virtual void readObject(const ContainerNode &node) PJSUA2_THROW(Error); 1276 1277 /** 1278 * Write this object to a container node. 1279 * 1280 * @param node Container to write values to. 1281 */ 1282 virtual void writeObject(ContainerNode &node) const PJSUA2_THROW(Error); 1283 }; 1284 1285 1286 /** 1287 * Account information. Application can query the account information 1288 * by calling Account::getInfo(). 1289 */ 1290 struct AccountInfo 1291 { 1292 /** 1293 * The account ID. 1294 */ 1295 pjsua_acc_id id; 1296 1297 /** 1298 * Flag to indicate whether this is the default account. 1299 */ 1300 bool isDefault; 1301 1302 /** 1303 * Account URI 1304 */ 1305 string uri; 1306 1307 /** 1308 * Flag to tell whether this account has registration setting 1309 * (reg_uri is not empty). 1310 */ 1311 bool regIsConfigured; 1312 1313 /** 1314 * Flag to tell whether this account is currently registered 1315 * (has active registration session). 1316 */ 1317 bool regIsActive; 1318 1319 /** 1320 * An up to date expiration interval for account registration session. 1321 */ 1322 unsigned regExpiresSec; 1323 1324 /** 1325 * Last registration status code. If status code is zero, the account 1326 * is currently not registered. Any other value indicates the SIP 1327 * status code of the registration. 1328 */ 1329 pjsip_status_code regStatus; 1330 1331 /** 1332 * String describing the registration status. 1333 */ 1334 string regStatusText; 1335 1336 /** 1337 * Last registration error code. When the status field contains a SIP 1338 * status code that indicates a registration failure, last registration 1339 * error code contains the error code that causes the failure. In any 1340 * other case, its value is zero. 1341 */ 1342 pj_status_t regLastErr; 1343 1344 /** 1345 * Presence online status for this account. 1346 */ 1347 bool onlineStatus; 1348 1349 /** 1350 * Presence online status text. 1351 */ 1352 string onlineStatusText; 1353 1354 public: 1355 /** 1356 * Default constructor 1357 */ AccountInfopj::AccountInfo1358 AccountInfo() : regStatus(PJSIP_SC_NULL) 1359 {} 1360 1361 /** Import from pjsip data */ 1362 void fromPj(const pjsua_acc_info &pai); 1363 }; 1364 1365 /** 1366 * This structure contains parameters for onIncomingCall() account callback. 1367 */ 1368 struct OnIncomingCallParam 1369 { 1370 /** 1371 * The library call ID allocated for the new call. 1372 */ 1373 int callId; 1374 1375 /** 1376 * The incoming INVITE request. 1377 */ 1378 SipRxData rdata; 1379 }; 1380 1381 /** 1382 * This structure contains parameters for onRegStarted() account callback. 1383 */ 1384 struct OnRegStartedParam 1385 { 1386 /** 1387 * True for registration and False for unregistration. 1388 */ 1389 bool renew; 1390 }; 1391 1392 /** 1393 * This structure contains parameters for onRegState() account callback. 1394 */ 1395 struct OnRegStateParam 1396 { 1397 /** 1398 * Registration operation status. 1399 */ 1400 pj_status_t status; 1401 1402 /** 1403 * SIP status code received. 1404 */ 1405 pjsip_status_code code; 1406 1407 /** 1408 * SIP reason phrase received. 1409 */ 1410 string reason; 1411 1412 /** 1413 * The incoming message. 1414 */ 1415 SipRxData rdata; 1416 1417 /** 1418 * Next expiration interval. 1419 */ 1420 unsigned expiration; 1421 }; 1422 1423 /** 1424 * This structure contains parameters for onIncomingSubscribe() callback. 1425 */ 1426 struct OnIncomingSubscribeParam 1427 { 1428 /** 1429 * Server presence subscription instance. If application delays 1430 * the acceptance of the request, it will need to specify this object 1431 * when calling Account::presNotify(). 1432 */ 1433 void *srvPres; 1434 1435 /** 1436 * Sender URI. 1437 */ 1438 string fromUri; 1439 1440 /** 1441 * The incoming message. 1442 */ 1443 SipRxData rdata; 1444 1445 /** 1446 * The status code to respond to the request. The default value is 200. 1447 * Application may set this to other final status code to accept or 1448 * reject the request. 1449 */ 1450 pjsip_status_code code; 1451 1452 /** 1453 * The reason phrase to respond to the request. 1454 */ 1455 string reason; 1456 1457 /** 1458 * Additional data to be sent with the response, if any. 1459 */ 1460 SipTxOption txOption; 1461 }; 1462 1463 /** 1464 * Parameters for onInstantMessage() account callback. 1465 */ 1466 struct OnInstantMessageParam 1467 { 1468 /** 1469 * Sender From URI. 1470 */ 1471 string fromUri; 1472 1473 /** 1474 * To URI of the request. 1475 */ 1476 string toUri; 1477 1478 /** 1479 * Contact URI of the sender. 1480 */ 1481 string contactUri; 1482 1483 /** 1484 * MIME type of the message body. 1485 */ 1486 string contentType; 1487 1488 /** 1489 * The message body. 1490 */ 1491 string msgBody; 1492 1493 /** 1494 * The whole message. 1495 */ 1496 SipRxData rdata; 1497 }; 1498 1499 /** 1500 * Parameters for onInstantMessageStatus() account callback. 1501 */ 1502 struct OnInstantMessageStatusParam 1503 { 1504 /** 1505 * Token or a user data that was associated with the pager 1506 * transmission. 1507 */ 1508 Token userData; 1509 1510 /** 1511 * Destination URI. 1512 */ 1513 string toUri; 1514 1515 /** 1516 * The message body. 1517 */ 1518 string msgBody; 1519 1520 /** 1521 * The SIP status code of the transaction. 1522 */ 1523 pjsip_status_code code; 1524 1525 /** 1526 * The reason phrase of the transaction. 1527 */ 1528 string reason; 1529 1530 /** 1531 * The incoming response that causes this callback to be called. 1532 * If the transaction fails because of time out or transport error, 1533 * the content will be empty. 1534 */ 1535 SipRxData rdata; 1536 }; 1537 1538 /** 1539 * Parameters for onTypingIndication() account callback. 1540 */ 1541 struct OnTypingIndicationParam 1542 { 1543 /** 1544 * Sender/From URI. 1545 */ 1546 string fromUri; 1547 1548 /** 1549 * To URI. 1550 */ 1551 string toUri; 1552 1553 /** 1554 * The Contact URI. 1555 */ 1556 string contactUri; 1557 1558 /** 1559 * Boolean to indicate if sender is typing. 1560 */ 1561 bool isTyping; 1562 1563 /** 1564 * The whole message buffer. 1565 */ 1566 SipRxData rdata; 1567 }; 1568 1569 /** 1570 * Parameters for onMwiInfo() account callback. 1571 */ 1572 struct OnMwiInfoParam 1573 { 1574 /** 1575 * MWI subscription state. 1576 */ 1577 pjsip_evsub_state state; 1578 1579 /** 1580 * The whole message buffer. 1581 */ 1582 SipRxData rdata; 1583 }; 1584 1585 /** 1586 * Parameters for presNotify() account method. 1587 */ 1588 struct PresNotifyParam 1589 { 1590 /** 1591 * Server presence subscription instance. 1592 */ 1593 void *srvPres; 1594 1595 /** 1596 * Server presence subscription state to set. 1597 */ 1598 pjsip_evsub_state state; 1599 1600 /** 1601 * Optionally specify the state string name, if state is not "active", 1602 * "pending", or "terminated". 1603 */ 1604 string stateStr; 1605 1606 /** 1607 * If the new state is PJSIP_EVSUB_STATE_TERMINATED, optionally specify 1608 * the termination reason. 1609 */ 1610 string reason; 1611 1612 /** 1613 * If the new state is PJSIP_EVSUB_STATE_TERMINATED, this specifies 1614 * whether the NOTIFY request should contain message body containing 1615 * account's presence information. 1616 */ 1617 bool withBody; 1618 1619 /** 1620 * Optional list of headers to be sent with the NOTIFY request. 1621 */ 1622 SipTxOption txOption; 1623 }; 1624 1625 1626 /** 1627 * Wrapper class for Buddy matching algo. 1628 * 1629 * Default algo is a simple substring lookup of search-token in the 1630 * Buddy URIs, with case sensitive. Application can implement its own 1631 * matching algo by overriding this class and specifying its instance 1632 * in Account::findBuddy(). 1633 */ 1634 class FindBuddyMatch 1635 { 1636 public: 1637 /** 1638 * Default algo implementation. 1639 */ match(const string & token,const Buddy & buddy)1640 virtual bool match(const string &token, const Buddy &buddy) 1641 { 1642 BuddyInfo bi = buddy.getInfo(); 1643 return bi.uri.find(token) != string::npos; 1644 } 1645 1646 /** 1647 * Destructor. 1648 */ ~FindBuddyMatch()1649 virtual ~FindBuddyMatch() {} 1650 }; 1651 1652 1653 /** 1654 * Account. 1655 */ 1656 class Account 1657 { 1658 public: 1659 /** 1660 * Constructor. 1661 */ 1662 Account(); 1663 1664 /** 1665 * Destructor. Note that if the account is deleted, it will also delete 1666 * the corresponding account in the PJSUA-LIB. 1667 * 1668 * If application implements a derived class, the derived class should 1669 * call shutdown() in the beginning stage in its destructor, or 1670 * alternatively application should call shutdown() before deleting 1671 * the derived class instance. This is to avoid race condition between 1672 * the derived class destructor and Account callbacks. 1673 */ 1674 virtual ~Account(); 1675 1676 /** 1677 * Create the account. 1678 * 1679 * If application implements a derived class, the derived class should 1680 * call shutdown() in the beginning stage in its destructor, or 1681 * alternatively application should call shutdown() before deleting 1682 * the derived class instance. This is to avoid race condition between 1683 * the derived class destructor and Account callbacks. 1684 * 1685 * @param cfg The account config. 1686 * @param make_default Make this the default account. 1687 */ 1688 void create(const AccountConfig &cfg, 1689 bool make_default=false) PJSUA2_THROW(Error); 1690 1691 /** 1692 * Shutdown the account. This will initiate unregistration if needed, 1693 * and delete the corresponding account in the PJSUA-LIB. 1694 * 1695 * Note that application must delete all Buddy instances belong to this 1696 * account before shutting down the account. 1697 * 1698 * If application implements a derived class, the derived class should 1699 * call this method in the beginning stage in its destructor, or 1700 * alternatively application should call this method before deleting 1701 * the derived class instance. This is to avoid race condition between 1702 * the derived class destructor and Account callbacks. 1703 */ 1704 void shutdown(); 1705 1706 /** 1707 * Modify the account to use the specified account configuration. 1708 * Depending on the changes, this may cause unregistration or 1709 * reregistration on the account. 1710 * 1711 * @param cfg New account config to be applied to the 1712 * account. 1713 */ 1714 void modify(const AccountConfig &cfg) PJSUA2_THROW(Error); 1715 1716 /** 1717 * Check if this account is still valid. 1718 * 1719 * @return True if it is. 1720 */ 1721 bool isValid() const; 1722 1723 /** 1724 * Set this as default account to be used when incoming and outgoing 1725 * requests don't match any accounts. 1726 */ 1727 void setDefault() PJSUA2_THROW(Error); 1728 1729 /** 1730 * Check if this account is the default account. Default account will be 1731 * used for incoming and outgoing requests that don't match any other 1732 * accounts. 1733 * 1734 * @return True if this is the default account. 1735 */ 1736 bool isDefault() const; 1737 1738 /** 1739 * Get PJSUA-LIB account ID or index associated with this account. 1740 * 1741 * @return Integer greater than or equal to zero. 1742 */ 1743 int getId() const; 1744 1745 /** 1746 * Get the Account class for the specified account Id. 1747 * 1748 * @param acc_id The account ID to lookup 1749 * 1750 * @return The Account instance or NULL if not found. 1751 */ 1752 static Account *lookup(int acc_id); 1753 1754 /** 1755 * Get account info. 1756 * 1757 * @return Account info. 1758 */ 1759 AccountInfo getInfo() const PJSUA2_THROW(Error); 1760 1761 /** 1762 * Update registration or perform unregistration. Application normally 1763 * only needs to call this function if it wants to manually update the 1764 * registration or to unregister from the server. 1765 * 1766 * @param renew If False, this will start unregistration 1767 * process. 1768 */ 1769 void setRegistration(bool renew) PJSUA2_THROW(Error); 1770 1771 /** 1772 * Set or modify account's presence online status to be advertised to 1773 * remote/presence subscribers. This would trigger the sending of 1774 * outgoing NOTIFY request if there are server side presence subscription 1775 * for this account, and/or outgoing PUBLISH if presence publication is 1776 * enabled for this account. 1777 * 1778 * @param pres_st Presence online status. 1779 */ 1780 void setOnlineStatus(const PresenceStatus &pres_st) PJSUA2_THROW(Error); 1781 1782 /** 1783 * Lock/bind this account to a specific transport/listener. Normally 1784 * application shouldn't need to do this, as transports will be selected 1785 * automatically by the library according to the destination. 1786 * 1787 * When account is locked/bound to a specific transport, all outgoing 1788 * requests from this account will use the specified transport (this 1789 * includes SIP registration, dialog (call and event subscription), and 1790 * out-of-dialog requests such as MESSAGE). 1791 * 1792 * Note that transport id may be specified in AccountConfig too. 1793 * 1794 * @param tp_id The transport ID. 1795 */ 1796 void setTransport(TransportId tp_id) PJSUA2_THROW(Error); 1797 1798 /** 1799 * Send NOTIFY to inform account presence status or to terminate server 1800 * side presence subscription. If application wants to reject the incoming 1801 * request, it should set the param \a PresNotifyParam.state to 1802 * PJSIP_EVSUB_STATE_TERMINATED. 1803 * 1804 * @param prm The sending NOTIFY parameter. 1805 */ 1806 void presNotify(const PresNotifyParam &prm) PJSUA2_THROW(Error); 1807 1808 #if !DEPRECATED_FOR_TICKET_2232 1809 /** 1810 * Warning: deprecated, use enumBuddies2() instead. This function is not 1811 * safe in multithreaded environment. 1812 * 1813 * Enumerate all buddies of the account. 1814 * 1815 * @return The buddy list. 1816 */ 1817 const BuddyVector& enumBuddies() const PJSUA2_THROW(Error); 1818 #endif 1819 1820 /** 1821 * Enumerate all buddies of the account. 1822 * 1823 * @return The buddy list. 1824 */ 1825 BuddyVector2 enumBuddies2() const PJSUA2_THROW(Error); 1826 1827 #if !DEPRECATED_FOR_TICKET_2232 1828 /** 1829 * Warning: deprecated, use findBuddy2 instead. This function is not 1830 * safe in multithreaded environment. 1831 * 1832 * Find a buddy in the buddy list with the specified URI. 1833 * 1834 * Exception: if buddy is not found, PJ_ENOTFOUND will be thrown. 1835 * 1836 * @param uri The buddy URI. 1837 * @param buddy_match The buddy match algo. 1838 * 1839 * @return The pointer to buddy. 1840 */ 1841 Buddy* findBuddy(string uri, FindBuddyMatch *buddy_match = NULL) const 1842 PJSUA2_THROW(Error); 1843 #endif 1844 1845 /** 1846 * Find a buddy in the buddy list with the specified URI. 1847 * 1848 * Exception: if buddy is not found, PJ_ENOTFOUND will be thrown. 1849 * 1850 * @param uri The buddy URI. 1851 * 1852 * @return The pointer to buddy. 1853 */ 1854 Buddy findBuddy2(string uri) const PJSUA2_THROW(Error); 1855 1856 public: 1857 /* 1858 * Callbacks 1859 */ 1860 /** 1861 * Notify application on incoming call. 1862 * 1863 * @param prm Callback parameter. 1864 */ onIncomingCall(OnIncomingCallParam & prm)1865 virtual void onIncomingCall(OnIncomingCallParam &prm) 1866 { PJ_UNUSED_ARG(prm); } 1867 1868 /** 1869 * Notify application when registration or unregistration has been 1870 * initiated. Note that this only notifies the initial registration 1871 * and unregistration. Once registration session is active, subsequent 1872 * refresh will not cause this callback to be called. 1873 * 1874 * @param prm Callback parameter. 1875 */ onRegStarted(OnRegStartedParam & prm)1876 virtual void onRegStarted(OnRegStartedParam &prm) 1877 { PJ_UNUSED_ARG(prm); } 1878 1879 /** 1880 * Notify application when registration status has changed. 1881 * Application may then query the account info to get the 1882 * registration details. 1883 * 1884 * @param prm Callback parameter. 1885 */ onRegState(OnRegStateParam & prm)1886 virtual void onRegState(OnRegStateParam &prm) 1887 { PJ_UNUSED_ARG(prm); } 1888 1889 /** 1890 * Notification when incoming SUBSCRIBE request is received. Application 1891 * may use this callback to authorize the incoming subscribe request 1892 * (e.g. ask user permission if the request should be granted). 1893 * 1894 * If this callback is not implemented, all incoming presence subscription 1895 * requests will be accepted. 1896 * 1897 * If this callback is implemented, application has several choices on 1898 * what to do with the incoming request: 1899 * - it may reject the request immediately by specifying non-200 class 1900 * final response in the IncomingSubscribeParam.code parameter. 1901 * - it may immediately accept the request by specifying 200 as the 1902 * IncomingSubscribeParam.code parameter. This is the default value if 1903 * application doesn't set any value to the IncomingSubscribeParam.code 1904 * parameter. In this case, the library will automatically send NOTIFY 1905 * request upon returning from this callback. 1906 * - it may delay the processing of the request, for example to request 1907 * user permission whether to accept or reject the request. In this 1908 * case, the application MUST set the IncomingSubscribeParam.code 1909 * argument to 202, then IMMEDIATELY calls presNotify() with 1910 * state PJSIP_EVSUB_STATE_PENDING and later calls presNotify() 1911 * again to accept or reject the subscription request. 1912 * 1913 * Any IncomingSubscribeParam.code other than 200 and 202 will be treated 1914 * as 200. 1915 * 1916 * Application MUST return from this callback immediately (e.g. it must 1917 * not block in this callback while waiting for user confirmation). 1918 * 1919 * @param prm Callback parameter. 1920 */ onIncomingSubscribe(OnIncomingSubscribeParam & prm)1921 virtual void onIncomingSubscribe(OnIncomingSubscribeParam &prm) 1922 { PJ_UNUSED_ARG(prm); } 1923 1924 /** 1925 * Notify application on incoming instant message or pager (i.e. MESSAGE 1926 * request) that was received outside call context. 1927 * 1928 * @param prm Callback parameter. 1929 */ onInstantMessage(OnInstantMessageParam & prm)1930 virtual void onInstantMessage(OnInstantMessageParam &prm) 1931 { PJ_UNUSED_ARG(prm); } 1932 1933 /** 1934 * Notify application about the delivery status of outgoing pager/instant 1935 * message (i.e. MESSAGE) request. 1936 * 1937 * @param prm Callback parameter. 1938 */ onInstantMessageStatus(OnInstantMessageStatusParam & prm)1939 virtual void onInstantMessageStatus(OnInstantMessageStatusParam &prm) 1940 { PJ_UNUSED_ARG(prm); } 1941 1942 /** 1943 * Notify application about typing indication. 1944 * 1945 * @param prm Callback parameter. 1946 */ onTypingIndication(OnTypingIndicationParam & prm)1947 virtual void onTypingIndication(OnTypingIndicationParam &prm) 1948 { PJ_UNUSED_ARG(prm); } 1949 1950 /** 1951 * Notification about MWI (Message Waiting Indication) status change. 1952 * This callback can be called upon the status change of the 1953 * SUBSCRIBE request (for example, 202/Accepted to SUBSCRIBE is received) 1954 * or when a NOTIFY reqeust is received. 1955 * 1956 * @param prm Callback parameter. 1957 */ onMwiInfo(OnMwiInfoParam & prm)1958 virtual void onMwiInfo(OnMwiInfoParam &prm) 1959 { PJ_UNUSED_ARG(prm); } 1960 1961 1962 private: 1963 friend class Endpoint; 1964 friend class Buddy; 1965 1966 /** 1967 * An internal function to add a Buddy to Account buddy list. 1968 * This method is used by Buddy::create(). 1969 */ 1970 void addBuddy(Buddy *buddy); 1971 1972 /** 1973 * An internal function to remove a Buddy from Account buddy list. 1974 * This method is used by Buddy::~Buddy(). 1975 */ 1976 void removeBuddy(Buddy *buddy); 1977 1978 1979 private: 1980 pjsua_acc_id id; 1981 string tmpReason; // for saving response's reason 1982 #if !DEPRECATED_FOR_TICKET_2232 1983 BuddyVector buddyList; 1984 #endif 1985 }; 1986 1987 /** 1988 * @} // PJSUA2_ACC 1989 */ 1990 1991 } // namespace pj 1992 1993 #endif /* __PJSUA2_ACCOUNT_HPP__ */ 1994 1995