1 /* $Id$ */ 2 /* 3 * Copyright (C) 2012-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_CALL_HPP__ 20 #define __PJSUA2_CALL_HPP__ 21 22 /** 23 * @file pjsua2/call.hpp 24 * @brief PJSUA2 Call manipulation 25 */ 26 #include <pjsua-lib/pjsua.h> 27 #include <pjsua2/media.hpp> 28 29 /** PJSUA2 API is inside pj namespace */ 30 namespace pj 31 { 32 33 /** 34 * @defgroup PJSUA2_CALL Call 35 * @ingroup PJSUA2_Ref 36 */ 37 38 /** 39 * @defgroup PJSUA2_Call_Data_Structure Call Related Types 40 * @ingroup PJSUA2_DS 41 * @{ 42 */ 43 44 using std::string; 45 using std::vector; 46 47 ////////////////////////////////////////////////////////////////////////////// 48 49 /** 50 * Media stream, corresponds to pjmedia_stream 51 */ 52 typedef void *MediaStream; 53 54 /** 55 * Media transport, corresponds to pjmedia_transport 56 */ 57 typedef void *MediaTransport; 58 59 /** 60 * This structure describes statistics state. 61 */ 62 struct MathStat 63 { 64 int n; /**< number of samples */ 65 int max; /**< maximum value */ 66 int min; /**< minimum value */ 67 int last; /**< last value */ 68 int mean; /**< mean */ 69 70 public: 71 /** 72 * Default constructor 73 */ 74 MathStat(); 75 76 /** 77 * Convert from pjsip 78 */ 79 void fromPj(const pj_math_stat &prm); 80 }; 81 82 /** 83 * Types of loss detected. 84 */ 85 struct LossType 86 { 87 unsigned burst; /**< Burst/sequential packet lost detected */ 88 unsigned random; /**< Random packet lost detected. */ 89 }; 90 91 /** 92 * Unidirectional RTP stream statistics. 93 */ 94 struct RtcpStreamStat 95 { 96 TimeVal update; /**< Time of last update. */ 97 unsigned updateCount;/**< Number of updates (to calculate avg) */ 98 unsigned pkt; /**< Total number of packets */ 99 unsigned bytes; /**< Total number of payload/bytes */ 100 unsigned discard; /**< Total number of discarded packets. */ 101 unsigned loss; /**< Total number of packets lost */ 102 unsigned reorder; /**< Total number of out of order packets */ 103 unsigned dup; /**< Total number of duplicates packets */ 104 105 MathStat lossPeriodUsec; /**< Loss period statistics */ 106 107 LossType lossType; /**< Types of loss detected. */ 108 109 MathStat jitterUsec; /**< Jitter statistics */ 110 111 public: 112 /** 113 * Convert from pjsip 114 */ 115 void fromPj(const pjmedia_rtcp_stream_stat &prm); 116 }; 117 118 /** 119 * RTCP SDES structure. 120 */ 121 struct RtcpSdes 122 { 123 string cname; /**< RTCP SDES type CNAME. */ 124 string name; /**< RTCP SDES type NAME. */ 125 string email; /**< RTCP SDES type EMAIL. */ 126 string phone; /**< RTCP SDES type PHONE. */ 127 string loc; /**< RTCP SDES type LOC. */ 128 string tool; /**< RTCP SDES type TOOL. */ 129 string note; /**< RTCP SDES type NOTE. */ 130 131 public: 132 /** 133 * Convert from pjsip 134 */ 135 void fromPj(const pjmedia_rtcp_sdes &prm); 136 }; 137 138 /** 139 * Bidirectional RTP stream statistics. 140 */ 141 struct RtcpStat 142 { 143 TimeVal start; /**< Time when session was created */ 144 145 RtcpStreamStat txStat; /**< Encoder stream statistics. */ 146 RtcpStreamStat rxStat; /**< Decoder stream statistics. */ 147 148 MathStat rttUsec; /**< Round trip delay statistic. */ 149 150 pj_uint32_t rtpTxLastTs; /**< Last TX RTP timestamp. */ 151 pj_uint16_t rtpTxLastSeq; /**< Last TX RTP sequence. */ 152 153 MathStat rxIpdvUsec; /**< Statistics of IP packet delay 154 variation in receiving 155 direction. It is only used when 156 PJMEDIA_RTCP_STAT_HAS_IPDV is 157 set to non-zero. */ 158 159 MathStat rxRawJitterUsec;/**< Statistic of raw jitter in 160 receiving direction. It is only 161 used when 162 PJMEDIA_RTCP_STAT_HAS_RAW_JITTER 163 is set to non-zero. */ 164 165 RtcpSdes peerSdes; /**< Peer SDES. */ 166 167 public: 168 /** 169 * Convert from pjsip 170 */ 171 void fromPj(const pjmedia_rtcp_stat &prm); 172 }; 173 174 /** 175 * This structure describes jitter buffer state. 176 */ 177 struct JbufState 178 { 179 /* Setting */ 180 unsigned frameSize; /**< Individual frame size, in bytes. */ 181 unsigned minPrefetch; /**< Minimum allowed prefetch, in frms. */ 182 unsigned maxPrefetch; /**< Maximum allowed prefetch, in frms. */ 183 184 /* Status */ 185 unsigned burst; /**< Current burst level, in frames */ 186 unsigned prefetch; /**< Current prefetch value, in frames */ 187 unsigned size; /**< Current buffer size, in frames. */ 188 189 /* Statistic */ 190 unsigned avgDelayMsec; /**< Average delay, in ms. */ 191 unsigned minDelayMsec; /**< Minimum delay, in ms. */ 192 unsigned maxDelayMsec; /**< Maximum delay, in ms. */ 193 unsigned devDelayMsec; /**< Standard deviation of delay, in ms.*/ 194 unsigned avgBurst; /**< Average burst, in frames. */ 195 unsigned lost; /**< Number of lost frames. */ 196 unsigned discard; /**< Number of discarded frames. */ 197 unsigned empty; /**< Number of empty on GET events. */ 198 199 public: 200 /** 201 * Convert from pjsip 202 */ 203 void fromPj(const pjmedia_jb_state &prm); 204 }; 205 206 /** 207 * This structure describes SDP session description. It corresponds to the 208 * pjmedia_sdp_session structure. 209 */ 210 struct SdpSession 211 { 212 /** 213 * The whole SDP as a string. 214 */ 215 string wholeSdp; 216 217 /** 218 * Pointer to its original pjmedia_sdp_session. Only valid when the struct 219 * is converted from PJSIP's pjmedia_sdp_session. 220 */ 221 void *pjSdpSession; 222 223 public: 224 /** 225 * Convert from pjsip 226 */ 227 void fromPj(const pjmedia_sdp_session &sdp); 228 }; 229 230 231 /** 232 * This structure describes media transport informations. It corresponds to the 233 * pjmedia_transport_info structure. The address name field can be empty string 234 * if the address in the pjmedia_transport_info is invalid. 235 */ 236 struct MediaTransportInfo 237 { 238 /** 239 * Address to be advertised as the local address for the RTP socket, 240 * which does not need to be equal as the bound address (for example, 241 * this address can be the address resolved with STUN). 242 */ 243 SocketAddress localRtpName; 244 245 /** 246 * Address to be advertised as the local address for the RTCP socket, 247 * which does not need to be equal as the bound address (for example, 248 * this address can be the address resolved with STUN). 249 */ 250 SocketAddress localRtcpName; 251 252 /** 253 * Remote address where RTP originated from. This can be empty string if 254 * no data is received from the remote. 255 */ 256 SocketAddress srcRtpName; 257 258 /** 259 * Remote address where RTCP originated from. This can be empty string if 260 * no data is recevied from the remote. 261 */ 262 SocketAddress srcRtcpName; 263 264 public: 265 /** 266 * Convert from pjsip 267 */ 268 void fromPj(const pjmedia_transport_info &info); 269 }; 270 271 ////////////////////////////////////////////////////////////////////////////// 272 273 /** 274 * Call settings. 275 */ 276 struct CallSetting 277 { 278 /** 279 * Bitmask of pjsua_call_flag constants. 280 * 281 * Default: PJSUA_CALL_INCLUDE_DISABLED_MEDIA 282 */ 283 unsigned flag; 284 285 /** 286 * This flag controls what methods to request keyframe are allowed on 287 * the call. Value is bitmask of pjsua_vid_req_keyframe_method. 288 * 289 * Default: PJSUA_VID_REQ_KEYFRAME_SIP_INFO | 290 * PJSUA_VID_REQ_KEYFRAME_RTCP_PLI 291 */ 292 unsigned reqKeyframeMethod; 293 294 /** 295 * Number of simultaneous active audio streams for this call. Setting 296 * this to zero will disable audio in this call. 297 * 298 * Default: 1 299 */ 300 unsigned audioCount; 301 302 /** 303 * Number of simultaneous active video streams for this call. Setting 304 * this to zero will disable video in this call. 305 * 306 * Default: 1 (if video feature is enabled, otherwise it is zero) 307 */ 308 unsigned videoCount; 309 310 public: 311 /** 312 * Default constructor initializes with empty or default values. 313 */ 314 CallSetting(bool useDefaultValues = false); 315 316 /** 317 * Check if the settings are set with empty values. 318 * 319 * @return True if the settings are empty. 320 */ 321 bool isEmpty() const; 322 323 /** 324 * Convert from pjsip 325 */ 326 void fromPj(const pjsua_call_setting &prm); 327 328 /** 329 * Convert to pjsip 330 */ 331 pjsua_call_setting toPj() const; 332 }; 333 334 /** 335 * Call media information. 336 * 337 * Application can query conference bridge port of this media using 338 * Call::getAudioMedia() if the media type is audio, 339 * or Call::getEncodingVideoMedia()/Call::getDecodingVideoMedia() 340 * if the media type is video. 341 */ 342 struct CallMediaInfo 343 { 344 /** 345 * Media index in SDP. 346 */ 347 unsigned index; 348 349 /** 350 * Media type. 351 */ 352 pjmedia_type type; 353 354 /** 355 * Media direction. 356 */ 357 pjmedia_dir dir; 358 359 /** 360 * Call media status. 361 */ 362 pjsua_call_media_status status; 363 364 /** 365 * Warning: this is deprecated, application can query conference bridge 366 * port of this media using Call::getAudioMedia(). 367 * 368 * The conference port number for the call. Only valid if the media type 369 * is audio. 370 */ 371 int audioConfSlot; 372 373 /** 374 * The window id for incoming video, if any, or 375 * PJSUA_INVALID_ID. Only valid if the media type is video. 376 */ 377 pjsua_vid_win_id videoIncomingWindowId; 378 379 /** 380 * The video window instance for incoming video. Only valid if 381 * videoIncomingWindowId is not PJSUA_INVALID_ID and 382 * the media type is video. 383 */ 384 VideoWindow videoWindow; 385 386 /** 387 * The video capture device for outgoing transmission, if any, 388 * or PJMEDIA_VID_INVALID_DEV. Only valid if the media type is video. 389 */ 390 pjmedia_vid_dev_index videoCapDev; 391 392 public: 393 /** 394 * Default constructor 395 */ 396 CallMediaInfo(); 397 398 /** 399 * Convert from pjsip 400 */ 401 void fromPj(const pjsua_call_media_info &prm); 402 }; 403 404 /** Array of call media info */ 405 typedef std::vector<CallMediaInfo> CallMediaInfoVector; 406 407 /** 408 * Call information. Application can query the call information 409 * by calling Call::getInfo(). 410 */ 411 struct CallInfo 412 { 413 /** 414 * Call identification. 415 */ 416 pjsua_call_id id; 417 418 /** 419 * Initial call role (UAC == caller) 420 */ 421 pjsip_role_e role; 422 423 /** 424 * The account ID where this call belongs. 425 */ 426 pjsua_acc_id accId; 427 428 /** 429 * Local URI 430 */ 431 string localUri; 432 433 /** 434 * Local Contact 435 */ 436 string localContact; 437 438 /** 439 * Remote URI 440 */ 441 string remoteUri; 442 443 /** 444 * Remote contact 445 */ 446 string remoteContact; 447 448 /** 449 * Dialog Call-ID string. 450 */ 451 string callIdString; 452 453 /** 454 * Call setting 455 */ 456 CallSetting setting; 457 458 /** 459 * Call state 460 */ 461 pjsip_inv_state state; 462 463 /** 464 * Text describing the state 465 */ 466 string stateText; 467 468 /** 469 * Last status code heard, which can be used as cause code 470 */ 471 pjsip_status_code lastStatusCode; 472 473 /** 474 * The reason phrase describing the last status. 475 */ 476 string lastReason; 477 478 /** 479 * Array of active media information. 480 */ 481 CallMediaInfoVector media; 482 483 /** 484 * Array of provisional media information. This contains the media info 485 * in the provisioning state, that is when the media session is being 486 * created/updated (SDP offer/answer is on progress). 487 */ 488 CallMediaInfoVector provMedia; 489 490 /** 491 * Up-to-date call connected duration (zero when call is not 492 * established) 493 */ 494 TimeVal connectDuration; 495 496 /** 497 * Total call duration, including set-up time 498 */ 499 TimeVal totalDuration; 500 501 /** 502 * Flag if remote was SDP offerer 503 */ 504 bool remOfferer; 505 506 /** 507 * Number of audio streams offered by remote 508 */ 509 unsigned remAudioCount; 510 511 /** 512 * Number of video streams offered by remote 513 */ 514 unsigned remVideoCount; 515 516 public: 517 /** 518 * Default constructor 519 */ CallInfopj::CallInfo520 CallInfo() : id(PJSUA_INVALID_ID), 521 role(PJSIP_ROLE_UAC), 522 state(PJSIP_INV_STATE_NULL), 523 lastStatusCode(PJSIP_SC_NULL) 524 {} 525 526 /** 527 * Convert from pjsip 528 */ 529 void fromPj(const pjsua_call_info &pci); 530 }; 531 532 /** 533 * Media stream info. 534 */ 535 struct StreamInfo 536 { 537 /** 538 * Media type of this stream. 539 */ 540 pjmedia_type type; 541 542 /** 543 * Transport protocol (RTP/AVP, etc.) 544 */ 545 pjmedia_tp_proto proto; 546 547 /** 548 * Media direction. 549 */ 550 pjmedia_dir dir; 551 552 /** 553 * Remote RTP address 554 */ 555 SocketAddress remoteRtpAddress; 556 557 /** 558 * Optional remote RTCP address 559 */ 560 SocketAddress remoteRtcpAddress; 561 562 /** 563 * Outgoing codec payload type. 564 */ 565 unsigned txPt; 566 567 /** 568 * Incoming codec payload type. 569 */ 570 unsigned rxPt; 571 572 /** 573 * Codec name. 574 */ 575 string codecName; 576 577 /** 578 * Codec clock rate. 579 */ 580 unsigned codecClockRate; 581 582 /** 583 * Optional audio codec param. 584 */ 585 CodecParam audCodecParam; 586 587 /** 588 * Optional video codec param. 589 */ 590 VidCodecParam vidCodecParam; 591 592 /** 593 * Jitter buffer init delay in msec. 594 */ 595 int jbInit; 596 597 /** 598 * Jitter buffer minimum prefetch delay in msec. 599 */ 600 int jbMinPre; 601 602 /** 603 * Jitter buffer maximum prefetch delay in msec. 604 */ 605 int jbMaxPre; 606 607 /** 608 * Jitter buffer max delay in msec. 609 */ 610 int jbMax; 611 612 /** 613 * Jitter buffer discard algorithm. 614 */ 615 pjmedia_jb_discard_algo jbDiscardAlgo; 616 617 #if defined(PJMEDIA_STREAM_ENABLE_KA) && PJMEDIA_STREAM_ENABLE_KA!=0 618 /** 619 * Stream keep-alive and NAT hole punch (see #PJMEDIA_STREAM_ENABLE_KA) is 620 * enabled? 621 */ 622 bool useKa; 623 #endif 624 625 /** 626 * Disable automatic sending of RTCP SDES and BYE. 627 */ 628 bool rtcpSdesByeDisabled; 629 630 public: 631 /** 632 * Default constructor 633 */ StreamInfopj::StreamInfo634 StreamInfo() : type(PJMEDIA_TYPE_NONE), 635 proto(PJMEDIA_TP_PROTO_NONE), 636 dir(PJMEDIA_DIR_NONE) 637 {} 638 639 /** 640 * Convert from pjsip 641 */ 642 void fromPj(const pjsua_stream_info &info); 643 }; 644 645 /** 646 * Media stream statistic. 647 */ 648 struct StreamStat 649 { 650 /** 651 * RTCP statistic. 652 */ 653 RtcpStat rtcp; 654 655 /** 656 * Jitter buffer statistic. 657 */ 658 JbufState jbuf; 659 660 public: 661 /** 662 * Convert from pjsip 663 */ 664 void fromPj(const pjsua_stream_stat &prm); 665 }; 666 667 /** 668 * This structure contains parameters for Call::onCallState() callback. 669 */ 670 struct OnCallStateParam 671 { 672 /** 673 * Event which causes the call state to change. 674 */ 675 SipEvent e; 676 }; 677 678 /** 679 * This structure contains parameters for Call::onCallTsxState() callback. 680 */ 681 struct OnCallTsxStateParam 682 { 683 /** 684 * Transaction event that caused the state change. 685 */ 686 SipEvent e; 687 }; 688 689 /** 690 * This structure contains parameters for Call::onCallMediaState() callback. 691 */ 692 struct OnCallMediaStateParam 693 { 694 }; 695 696 /** 697 * This structure contains parameters for Call::onCallSdpCreated() callback. 698 */ 699 struct OnCallSdpCreatedParam 700 { 701 /** 702 * The SDP has just been created. 703 */ 704 SdpSession sdp; 705 706 /** 707 * The remote SDP, will be empty if local is SDP offerer. 708 */ 709 SdpSession remSdp; 710 }; 711 712 /** 713 * This structure contains parameters for Call::onStreamPreCreate() 714 * callback. 715 */ 716 struct OnStreamPreCreateParam 717 { 718 /** 719 * Stream index in the media session, read-only. 720 */ 721 unsigned streamIdx; 722 723 /** 724 * Parameters that the stream will be created from. 725 */ 726 StreamInfo streamInfo; 727 }; 728 729 /** 730 * This structure contains parameters for Call::onStreamCreated() 731 * callback. 732 */ 733 struct OnStreamCreatedParam 734 { 735 /** 736 * Audio media stream, read-only. 737 */ 738 MediaStream stream; 739 740 /** 741 * Stream index in the audio media session, read-only. 742 */ 743 unsigned streamIdx; 744 745 /** 746 * Specify if PJSUA2 should take ownership of the port returned in 747 * the pPort parameter below. If set to PJ_TRUE, 748 * pjmedia_port_destroy() will be called on the port when it is 749 * no longer needed. 750 * 751 * Default: PJ_FALSE 752 */ 753 bool destroyPort; 754 755 /** 756 * On input, it specifies the audio media port of the stream. Application 757 * may modify this pointer to point to different media port to be 758 * registered to the conference bridge. 759 */ 760 MediaPort pPort; 761 }; 762 763 /** 764 * This structure contains parameters for Call::onStreamDestroyed() 765 * callback. 766 */ 767 struct OnStreamDestroyedParam 768 { 769 /** 770 * Audio media stream. 771 */ 772 MediaStream stream; 773 774 /** 775 * Stream index in the audio media session. 776 */ 777 unsigned streamIdx; 778 }; 779 780 /** 781 * This structure contains parameters for Call::onDtmfDigit() 782 * callback. 783 */ 784 struct OnDtmfDigitParam 785 { 786 /** 787 * DTMF sending method. 788 */ 789 pjsua_dtmf_method method; 790 791 /** 792 * DTMF ASCII digit. 793 */ 794 string digit; 795 796 /** 797 * DTMF signal duration. If the duration is unknown, this value is set to 798 * PJSUA_UNKNOWN_DTMF_DURATION. 799 */ 800 unsigned duration; 801 }; 802 803 /** 804 * This structure contains parameters for Call::onDtmfEvent() 805 * callback. 806 */ 807 struct OnDtmfEventParam 808 { 809 /** 810 * DTMF sending method. 811 */ 812 pjsua_dtmf_method method; 813 814 /** 815 * The timestamp identifying the begin of the event. Timestamp units are 816 * expressed in milliseconds. 817 * Note that this value should only be used to compare multiple events 818 * received via the same method relatively to each other, as the time-base 819 * is randomized. 820 */ 821 unsigned timestamp; 822 823 /** 824 * DTMF ASCII digit. 825 */ 826 string digit; 827 828 /** 829 * DTMF signal duration in milliseconds. Interpretation of the duration 830 * depends on the flag PJMEDIA_STREAM_DTMF_IS_END. 831 * depends on the method. 832 * If the method is PJSUA_DTMF_METHOD_SIP_INFO, this contains the total 833 * duration of the DTMF signal or PJSUA_UNKNOWN_DTMF_DURATION if no signal 834 * duration was indicated. 835 * If the method is PJSUA_DTMF_METHOD_RFC2833, this contains the total 836 * duration of the DTMF signal received up to this point in time. 837 */ 838 unsigned duration; 839 840 /** 841 * Flags indicating additional information about the DTMF event. 842 * If PJMEDIA_STREAM_DTMF_IS_UPDATE is set, the event was already 843 * indicated earlier. The new indication contains an updated event 844 * duration. 845 * If PJMEDIA_STREAM_DTMF_IS_END is set, the event has ended and this 846 * indication contains the final event duration. Note that end 847 * indications might get lost. Hence it is not guaranteed to receive 848 * an event with PJMEDIA_STREAM_DTMF_IS_END for every event. 849 */ 850 unsigned flags; 851 }; 852 853 /** 854 * This structure contains parameters for Call::onCallTransferRequest() 855 * callback. 856 */ 857 struct OnCallTransferRequestParam 858 { 859 /** 860 * The destination where the call will be transferred to. 861 */ 862 string dstUri; 863 864 /** 865 * Status code to be returned for the call transfer request. On input, 866 * it contains status code 202. 867 */ 868 pjsip_status_code statusCode; 869 870 /** 871 * The current call setting, application can update this setting 872 * for the call being transferred. 873 */ 874 CallSetting opt; 875 876 /** 877 * New Call derived object instantiated by application when the call 878 * transfer is about to be accepted. 879 */ 880 Call *newCall; 881 }; 882 883 /** 884 * This structure contains parameters for Call::onCallTransferStatus() 885 * callback. 886 */ 887 struct OnCallTransferStatusParam 888 { 889 /** 890 * Status progress of the transfer request. 891 */ 892 pjsip_status_code statusCode; 893 894 /** 895 * Status progress reason. 896 */ 897 string reason; 898 899 /** 900 * If true, no further notification will be reported. The statusCode 901 * specified in this callback is the final status. 902 */ 903 bool finalNotify; 904 905 /** 906 * Initially will be set to true, application can set this to false 907 * if it no longer wants to receive further notification (for example, 908 * after it hangs up the call). 909 */ 910 bool cont; 911 }; 912 913 /** 914 * This structure contains parameters for Call::onCallReplaceRequest() 915 * callback. 916 */ 917 struct OnCallReplaceRequestParam 918 { 919 /** 920 * The incoming INVITE request to replace the call. 921 */ 922 SipRxData rdata; 923 924 /** 925 * Status code to be set by application. Application should only 926 * return a final status (200-699) 927 */ 928 pjsip_status_code statusCode; 929 930 /** 931 * Optional status text to be set by application. 932 */ 933 string reason; 934 935 /** 936 * The current call setting, application can update this setting for 937 * the call being replaced. 938 */ 939 CallSetting opt; 940 }; 941 942 /** 943 * This structure contains parameters for Call::onCallReplaced() callback. 944 */ 945 struct OnCallReplacedParam 946 { 947 /** 948 * The new call id. 949 */ 950 pjsua_call_id newCallId; 951 952 /** 953 * New Call derived object instantiated by application. 954 */ 955 Call *newCall; 956 }; 957 958 /** 959 * This structure contains parameters for Call::onCallRxOffer() callback. 960 */ 961 struct OnCallRxOfferParam 962 { 963 /** 964 * The new offer received. 965 */ 966 SdpSession offer; 967 968 /** 969 * Status code to be returned for answering the offer. On input, 970 * it contains status code 200. Currently, valid values are only 971 * 200 and 488. 972 */ 973 pjsip_status_code statusCode; 974 975 /** 976 * The current call setting, application can update this setting for 977 * answering the offer. 978 */ 979 CallSetting opt; 980 }; 981 982 /** 983 * This structure contains parameters for Call::onCallRxReinvite() callback. 984 */ 985 struct OnCallRxReinviteParam 986 { 987 /** 988 * The new offer received. 989 */ 990 SdpSession offer; 991 992 /** 993 * The incoming re-INVITE. 994 */ 995 SipRxData rdata; 996 997 /** 998 * On input, it is false. Set to true if app wants to manually answer 999 * the re-INVITE. 1000 */ 1001 bool isAsync; 1002 1003 /** 1004 * Status code to be returned for answering the offer. On input, 1005 * it contains status code 200. Currently, valid values are only 1006 * 200 and 488. 1007 */ 1008 pjsip_status_code statusCode; 1009 1010 /** 1011 * The current call setting, application can update this setting for 1012 * answering the offer. 1013 */ 1014 CallSetting opt; 1015 }; 1016 1017 /** 1018 * This structure contains parameters for Call::onCallTxOffer() callback. 1019 */ 1020 struct OnCallTxOfferParam 1021 { 1022 /** 1023 * The current call setting, application can update this setting for 1024 * generating the offer. Note that application should maintain any 1025 * active media to avoid the need for the peer to reject the offer. 1026 */ 1027 CallSetting opt; 1028 }; 1029 1030 /** 1031 * This structure contains parameters for Call::onCallRedirected() callback. 1032 */ 1033 struct OnCallRedirectedParam 1034 { 1035 /** 1036 * The current target to be tried. 1037 */ 1038 string targetUri; 1039 1040 /** 1041 * The event that caused this callback to be called. 1042 * This could be the receipt of 3xx response, or 4xx/5xx response 1043 * received for the INVITE sent to subsequent targets, or empty 1044 * (e.type == PJSIP_EVENT_UNKNOWN) 1045 * if this callback is called from within Call::processRedirect() 1046 * context. 1047 */ 1048 SipEvent e; 1049 }; 1050 1051 /** 1052 * This structure contains parameters for Call::onCallMediaEvent() callback. 1053 */ 1054 struct OnCallMediaEventParam 1055 { 1056 /** 1057 * The media stream index. 1058 */ 1059 unsigned medIdx; 1060 1061 /** 1062 * The media event. 1063 */ 1064 MediaEvent ev; 1065 }; 1066 1067 /** 1068 * This structure contains parameters for Call::onCallMediaTransportState() 1069 * callback. 1070 */ 1071 struct OnCallMediaTransportStateParam 1072 { 1073 /** 1074 * The media index. 1075 */ 1076 unsigned medIdx; 1077 1078 /** 1079 * The media transport state 1080 */ 1081 pjsua_med_tp_st state; 1082 1083 /** 1084 * The last error code related to the media transport state. 1085 */ 1086 pj_status_t status; 1087 1088 /** 1089 * Optional SIP error code. 1090 */ 1091 int sipErrorCode; 1092 }; 1093 1094 /** 1095 * This structure contains parameters for Call::onCreateMediaTransport() 1096 * callback. 1097 */ 1098 struct OnCreateMediaTransportParam 1099 { 1100 /** 1101 * The media index in the SDP for which this media transport will be used. 1102 */ 1103 unsigned mediaIdx; 1104 1105 /** 1106 * The media transport which otherwise will be used by the call has this 1107 * callback not been implemented. Application can change this to its own 1108 * instance of media transport to be used by the call. 1109 */ 1110 MediaTransport mediaTp; 1111 1112 /** 1113 * Bitmask from pjsua_create_media_transport_flag. 1114 */ 1115 unsigned flags; 1116 }; 1117 1118 /** 1119 * This structure contains parameters for Call::onCreateMediaTransportSrtp() 1120 * callback. 1121 */ 1122 struct OnCreateMediaTransportSrtpParam 1123 { 1124 /** 1125 * The media index in the SDP for which the SRTP media transport 1126 * will be used. 1127 */ 1128 unsigned mediaIdx; 1129 1130 /** 1131 * Specify whether secure media transport should be used. Application 1132 * can modify this only for initial INVITE. 1133 * Valid values are PJMEDIA_SRTP_DISABLED, PJMEDIA_SRTP_OPTIONAL, and 1134 * PJMEDIA_SRTP_MANDATORY. 1135 */ 1136 pjmedia_srtp_use srtpUse; 1137 1138 /** 1139 * Application can modify this to specify the cryptos and keys 1140 * which are going to be used. 1141 */ 1142 SrtpCryptoVector cryptos; 1143 }; 1144 1145 /** 1146 * @} // PJSUA2_Call_Data_Structure 1147 */ 1148 1149 /** 1150 * @addtogroup PJSUA2_CALL 1151 * @{ 1152 */ 1153 1154 /** 1155 * This structure contains parameters for Call::answer(), Call::hangup(), 1156 * Call::reinvite(), Call::update(), Call::xfer(), Call::xferReplaces(), 1157 * Call::setHold(). 1158 */ 1159 struct CallOpParam 1160 { 1161 /** 1162 * The call setting. 1163 */ 1164 CallSetting opt; 1165 1166 /** 1167 * Status code. 1168 */ 1169 pjsip_status_code statusCode; 1170 1171 /** 1172 * Reason phrase. 1173 */ 1174 string reason; 1175 1176 /** 1177 * Options. 1178 */ 1179 unsigned options; 1180 1181 /** 1182 * List of headers etc to be added to outgoing response message. 1183 * Note that this message data will be persistent in all next 1184 * answers/responses for this INVITE request. 1185 */ 1186 SipTxOption txOption; 1187 1188 /** 1189 * SDP answer. Currently only used for Call::answer(). 1190 */ 1191 SdpSession sdp; 1192 1193 public: 1194 /** 1195 * Default constructor initializes with zero/empty values. 1196 * Setting useDefaultCallSetting to true will initialize opt with default 1197 * call setting values. 1198 */ 1199 CallOpParam(bool useDefaultCallSetting = false); 1200 }; 1201 1202 /** 1203 * This structure contains parameters for Call::sendRequest() 1204 */ 1205 struct CallSendRequestParam 1206 { 1207 /** 1208 * SIP method of the request. 1209 */ 1210 string method; 1211 1212 /** 1213 * Message body and/or list of headers etc to be included in 1214 * outgoing request. 1215 */ 1216 SipTxOption txOption; 1217 1218 public: 1219 /** 1220 * Default constructor initializes with zero/empty values. 1221 */ 1222 CallSendRequestParam(); 1223 }; 1224 1225 /** 1226 * This structure contains parameters for Call::vidSetStream() 1227 */ 1228 struct CallVidSetStreamParam 1229 { 1230 /** 1231 * Specify the media stream index. This can be set to -1 to denote 1232 * the default video stream in the call, which is the first active 1233 * video stream or any first video stream if none is active. 1234 * 1235 * This field is valid for all video stream operations, except 1236 * PJSUA_CALL_VID_STRM_ADD. 1237 * 1238 * Default: -1 (first active video stream, or any first video stream 1239 * if none is active) 1240 */ 1241 int medIdx; 1242 1243 /** 1244 * Specify the media stream direction. 1245 * 1246 * This field is valid for the following video stream operations: 1247 * PJSUA_CALL_VID_STRM_ADD and PJSUA_CALL_VID_STRM_CHANGE_DIR. 1248 * 1249 * Default: PJMEDIA_DIR_ENCODING_DECODING 1250 */ 1251 pjmedia_dir dir; 1252 1253 /** 1254 * Specify the video capture device ID. This can be set to 1255 * PJMEDIA_VID_DEFAULT_CAPTURE_DEV to specify the default capture 1256 * device as configured in the account. 1257 * 1258 * This field is valid for the following video stream operations: 1259 * PJSUA_CALL_VID_STRM_ADD and PJSUA_CALL_VID_STRM_CHANGE_CAP_DEV. 1260 * 1261 * Default: PJMEDIA_VID_DEFAULT_CAPTURE_DEV. 1262 */ 1263 pjmedia_vid_dev_index capDev; 1264 1265 public: 1266 /** 1267 * Default constructor 1268 */ 1269 CallVidSetStreamParam(); 1270 }; 1271 1272 /** 1273 * This structure contains parameters for Call::sendDtmf() 1274 */ 1275 struct CallSendDtmfParam 1276 { 1277 /** 1278 * The method used to send DTMF. 1279 * 1280 * Default: PJSUA_DTMF_METHOD_RFC2833 1281 */ 1282 pjsua_dtmf_method method; 1283 1284 /** 1285 * The signal duration used for the DTMF. 1286 * 1287 * Default: PJSUA_CALL_SEND_DTMF_DURATION_DEFAULT 1288 */ 1289 unsigned duration; 1290 1291 /** 1292 * The DTMF digits to be sent. 1293 */ 1294 string digits; 1295 1296 public: 1297 /** 1298 * Default constructor initialize with default value. 1299 */ 1300 CallSendDtmfParam(); 1301 1302 /** 1303 * Convert to pjsip. 1304 */ 1305 pjsua_call_send_dtmf_param toPj() const; 1306 1307 /** 1308 * Convert from pjsip. 1309 */ 1310 void fromPj(const pjsua_call_send_dtmf_param ¶m); 1311 }; 1312 1313 /** 1314 * Call. 1315 */ 1316 class Call 1317 { 1318 public: 1319 /** 1320 * Constructor. 1321 */ 1322 Call(Account& acc, int call_id = PJSUA_INVALID_ID); 1323 1324 /** 1325 * Destructor. 1326 */ 1327 virtual ~Call(); 1328 1329 /** 1330 * Obtain detail information about this call. 1331 * 1332 * @return Call info. 1333 */ 1334 CallInfo getInfo() const PJSUA2_THROW(Error); 1335 1336 /** 1337 * Check if this call has active INVITE session and the INVITE 1338 * session has not been disconnected. 1339 * 1340 * @return True if call is active. 1341 */ 1342 bool isActive() const; 1343 1344 /** 1345 * Get PJSUA-LIB call ID or index associated with this call. 1346 * 1347 * @return Integer greater than or equal to zero. 1348 */ 1349 int getId() const; 1350 1351 /** 1352 * Get the Call class for the specified call Id. 1353 * 1354 * @param call_id The call ID to lookup 1355 * 1356 * @return The Call instance or NULL if not found. 1357 */ 1358 static Call *lookup(int call_id); 1359 1360 /** 1361 * Check if call has an active media session. 1362 * 1363 * @return True if yes. 1364 */ 1365 bool hasMedia() const; 1366 1367 /** 1368 * Warning: deprecated, use getAudioMedia() instead. This function is not 1369 * safe in multithreaded environment. 1370 * 1371 * Get media for the specified media index. 1372 * 1373 * @param med_idx Media index. 1374 * 1375 * @return The media or NULL if invalid or inactive. 1376 */ 1377 Media *getMedia(unsigned med_idx) const; 1378 1379 /** 1380 * Get audio media for the specified media index. If the specified media 1381 * index is not audio or invalid or inactive, exception will be thrown. 1382 * 1383 * @param med_idx Media index, or -1 to specify any first audio 1384 * media registered in the conference bridge. 1385 * 1386 * @return The audio media. 1387 */ 1388 AudioMedia getAudioMedia(int med_idx) const PJSUA2_THROW(Error); 1389 1390 /** 1391 * Get video media in encoding direction for the specified media index. 1392 * If the specified media index is not video or invalid or the direction 1393 * is receive only, exception will be thrown. 1394 * 1395 * @param med_idx Media index, or -1 to specify any first video 1396 * media with encoding direction registered in the 1397 * conference bridge. 1398 * 1399 * @return The video media. 1400 */ 1401 VideoMedia getEncodingVideoMedia(int med_idx) const PJSUA2_THROW(Error); 1402 1403 /** 1404 * Get video media in decoding direction for the specified media index. 1405 * If the specified media index is not video or invalid or the direction 1406 * is send only, exception will be thrown. 1407 * 1408 * @param med_idx Media index, or -1 to specify any first video 1409 * media with decoding direction registered in the 1410 * conference bridge. 1411 * 1412 * @return The video media. 1413 */ 1414 VideoMedia getDecodingVideoMedia(int med_idx) const PJSUA2_THROW(Error); 1415 1416 /** 1417 * Check if remote peer support the specified capability. 1418 * 1419 * @param htype The header type (pjsip_hdr_e) to be checked, which 1420 * value may be: 1421 * - PJSIP_H_ACCEPT 1422 * - PJSIP_H_ALLOW 1423 * - PJSIP_H_SUPPORTED 1424 * @param hname If htype specifies PJSIP_H_OTHER, then the header 1425 * name must be supplied in this argument. Otherwise 1426 * the value must be set to empty string (""). 1427 * @param token The capability token to check. For example, if \a 1428 * htype is PJSIP_H_ALLOW, then \a token specifies the 1429 * method names; if \a htype is PJSIP_H_SUPPORTED, then 1430 * \a token specifies the extension names such as 1431 * "100rel". 1432 * 1433 * @return PJSIP_DIALOG_CAP_SUPPORTED if the specified 1434 * capability is explicitly supported, see 1435 * pjsip_dialog_cap_status for more info. 1436 */ 1437 pjsip_dialog_cap_status remoteHasCap(int htype, 1438 const string &hname, 1439 const string &token) const; 1440 1441 /** 1442 * Attach application specific data to the call. Application can then 1443 * inspect this data by calling getUserData(). 1444 * 1445 * @param user_data Arbitrary data to be attached to the call. 1446 */ 1447 void setUserData(Token user_data); 1448 1449 /** 1450 * Get user data attached to the call, which has been previously set with 1451 * setUserData(). 1452 * 1453 * @return The user data. 1454 */ 1455 Token getUserData() const; 1456 1457 /** 1458 * Get the NAT type of remote's endpoint. This is a proprietary feature 1459 * of PJSUA-LIB which sends its NAT type in the SDP when \a natTypeInSdp 1460 * is set in UaConfig. 1461 * 1462 * This function can only be called after SDP has been received from remote, 1463 * which means for incoming call, this function can be called as soon as 1464 * call is received as long as incoming call contains SDP, and for outgoing 1465 * call, this function can be called only after SDP is received (normally in 1466 * 200/OK response to INVITE). As a general case, application should call 1467 * this function after or in \a onCallMediaState() callback. 1468 * 1469 * @return The NAT type. 1470 * 1471 * @see Endpoint::natGetType(), natTypeInSdp 1472 */ 1473 pj_stun_nat_type getRemNatType() PJSUA2_THROW(Error); 1474 1475 /** 1476 * Make outgoing call to the specified URI. 1477 * 1478 * @param dst_uri URI to be put in the To header (normally is the same 1479 * as the target URI). 1480 * @param prm.opt Optional call setting. 1481 * @param prm.txOption Optional headers etc to be added to outgoing INVITE 1482 * request. 1483 */ 1484 void makeCall(const string &dst_uri, const CallOpParam &prm) 1485 PJSUA2_THROW(Error); 1486 1487 /** 1488 * Send response to incoming INVITE request with call setting param. 1489 * Depending on the status code specified as parameter, this function may 1490 * send provisional response, establish the call, or terminate the call. 1491 * Notes about call setting: 1492 * - if call setting is changed in the subsequent call to this function, 1493 * only the first call setting supplied will applied. So normally 1494 * application will not supply call setting before getting confirmation 1495 * from the user. 1496 * - if no call setting is supplied when SDP has to be sent, i.e: answer 1497 * with status code 183 or 2xx, the default call setting will be used, 1498 * check CallSetting for its default values. 1499 * 1500 * @param prm.opt Optional call setting. 1501 * @param prm.statusCode Status code, (100-699). 1502 * @param prm.reason Optional reason phrase. If empty, default text 1503 * will be used. 1504 * @param prm.txOption Optional list of headers etc to be added to outgoing 1505 * response message. Note that this message data will 1506 * be persistent in all next answers/responses for this 1507 * INVITE request. 1508 */ 1509 void answer(const CallOpParam &prm) PJSUA2_THROW(Error); 1510 1511 /** 1512 * Hangup call by using method that is appropriate according to the 1513 * call state. This function is different than answering the call with 1514 * 3xx-6xx response (with answer()), in that this function 1515 * will hangup the call regardless of the state and role of the call, 1516 * while answer() only works with incoming calls on EARLY 1517 * state. 1518 * 1519 * @param prm.statusCode 1520 * Optional status code to be sent when we're rejecting 1521 * incoming call. If the value is zero, "603/Decline" 1522 * will be sent. 1523 * @param prm.reason Optional reason phrase to be sent when we're 1524 * rejecting incoming call. If empty, default text 1525 * will be used. 1526 * @param prm.txOption Optional list of headers etc to be added to outgoing 1527 * request/response message. 1528 */ 1529 void hangup(const CallOpParam &prm) PJSUA2_THROW(Error); 1530 1531 /** 1532 * Put the specified call on hold. This will send re-INVITE with the 1533 * appropriate SDP to inform remote that the call is being put on hold. 1534 * The final status of the request itself will be reported on the 1535 * \a onCallMediaState() callback, which inform the application that 1536 * the media state of the call has changed. 1537 * 1538 * @param prm.options Bitmask of pjsua_call_flag constants. Currently, 1539 * only the flag PJSUA_CALL_UPDATE_CONTACT can be used. 1540 * @param prm.txOption Optional message components to be sent with 1541 * the request. 1542 */ 1543 void setHold(const CallOpParam &prm) PJSUA2_THROW(Error); 1544 1545 /** 1546 * Send re-INVITE. 1547 * The final status of the request itself will be reported on the 1548 * \a onCallMediaState() callback, which inform the application that 1549 * the media state of the call has changed. 1550 * 1551 * @param prm.opt Optional call setting, if empty, the current call 1552 * setting will remain unchanged. 1553 * @param prm.opt.flag Bitmask of pjsua_call_flag constants. Specifying 1554 * PJSUA_CALL_UNHOLD here will release call hold. 1555 * @param prm.txOption Optional message components to be sent with 1556 * the request. 1557 */ 1558 void reinvite(const CallOpParam &prm) PJSUA2_THROW(Error); 1559 1560 /** 1561 * Send UPDATE request. 1562 * 1563 * @param prm.opt Optional call setting, if empty, the current call 1564 * setting will remain unchanged. 1565 * @param prm.txOption Optional message components to be sent with 1566 * the request. 1567 */ 1568 void update(const CallOpParam &prm) PJSUA2_THROW(Error); 1569 1570 /** 1571 * Initiate call transfer to the specified address. This function will send 1572 * REFER request to instruct remote call party to initiate a new INVITE 1573 * session to the specified destination/target. 1574 * 1575 * If application is interested to monitor the successfulness and 1576 * the progress of the transfer request, it can implement 1577 * \a onCallTransferStatus() callback which will report the progress 1578 * of the call transfer request. 1579 * 1580 * @param dest URI of new target to be contacted. The URI may be 1581 * in name address or addr-spec format. 1582 * @param prm.txOption Optional message components to be sent with 1583 * the request. 1584 */ 1585 void xfer(const string &dest, const CallOpParam &prm) PJSUA2_THROW(Error); 1586 1587 /** 1588 * Initiate attended call transfer. This function will send REFER request 1589 * to instruct remote call party to initiate new INVITE session to the URL 1590 * of \a destCall. The party at \a dest_call then should "replace" 1591 * the call with us with the new call from the REFER recipient. 1592 * 1593 * @param dest_call The call to be replaced. 1594 * @param prm.options Application may specify 1595 * PJSUA_XFER_NO_REQUIRE_REPLACES to suppress the 1596 * inclusion of "Require: replaces" in 1597 * the outgoing INVITE request created by the REFER 1598 * request. 1599 * @param prm.txOption Optional message components to be sent with 1600 * the request. 1601 */ 1602 void xferReplaces(const Call& dest_call, 1603 const CallOpParam &prm) PJSUA2_THROW(Error); 1604 1605 /** 1606 * Accept or reject redirection response. Application MUST call this 1607 * function after it signaled PJSIP_REDIRECT_PENDING in the 1608 * \a onCallRedirected() callback, 1609 * to notify the call whether to accept or reject the redirection 1610 * to the current target. Application can use the combination of 1611 * PJSIP_REDIRECT_PENDING command in \a onCallRedirected() callback and 1612 * this function to ask for user permission before redirecting the call. 1613 * 1614 * Note that if the application chooses to reject or stop redirection (by 1615 * using PJSIP_REDIRECT_REJECT or PJSIP_REDIRECT_STOP respectively), the 1616 * call disconnection callback will be called before this function returns. 1617 * And if the application rejects the target, the \a onCallRedirected() 1618 * callback may also be called before this function returns if there is 1619 * another target to try. 1620 * 1621 * @param cmd Redirection operation to be applied to the current 1622 * target. The semantic of this argument is similar 1623 * to the description in the \a onCallRedirected() 1624 * callback, except that the PJSIP_REDIRECT_PENDING is 1625 * not accepted here. 1626 */ 1627 void processRedirect(pjsip_redirect_op cmd) PJSUA2_THROW(Error); 1628 1629 /** 1630 * Send DTMF digits to remote using RFC 2833 payload formats. 1631 * 1632 * @param digits DTMF string digits to be sent. 1633 */ 1634 void dialDtmf(const string &digits) PJSUA2_THROW(Error); 1635 1636 /** 1637 * Send DTMF digits to remote. 1638 * 1639 * @param param The send DTMF parameter. 1640 */ 1641 void sendDtmf(const CallSendDtmfParam ¶m) PJSUA2_THROW(Error); 1642 1643 /** 1644 * Send instant messaging inside INVITE session. 1645 * 1646 * @param prm.contentType 1647 * MIME type. 1648 * @param prm.content The message content. 1649 * @param prm.txOption Optional list of headers etc to be included in 1650 * outgoing request. The body descriptor in the 1651 * txOption is ignored. 1652 * @param prm.userData Optional user data, which will be given back when 1653 * the IM callback is called. 1654 */ 1655 void sendInstantMessage(const SendInstantMessageParam& prm) 1656 PJSUA2_THROW(Error); 1657 1658 /** 1659 * Send IM typing indication inside INVITE session. 1660 * 1661 * @param prm.isTyping True to indicate to remote that local person is 1662 * currently typing an IM. 1663 * @param prm.txOption Optional list of headers etc to be included in 1664 * outgoing request. 1665 */ 1666 void sendTypingIndication(const SendTypingIndicationParam &prm) 1667 PJSUA2_THROW(Error); 1668 1669 /** 1670 * Send arbitrary request with the call. This is useful for example to send 1671 * INFO request. Note that application should not use this function to send 1672 * requests which would change the invite session's state, such as 1673 * re-INVITE, UPDATE, PRACK, and BYE. 1674 * 1675 * @param prm.method SIP method of the request. 1676 * @param prm.txOption Optional message body and/or list of headers to be 1677 * included in outgoing request. 1678 */ 1679 void sendRequest(const CallSendRequestParam &prm) PJSUA2_THROW(Error); 1680 1681 /** 1682 * Dump call and media statistics to string. 1683 * 1684 * @param with_media True to include media information too. 1685 * @param indent Spaces for left indentation. 1686 * 1687 * @return Call dump and media statistics string. 1688 */ 1689 string dump(bool with_media, const string indent) PJSUA2_THROW(Error); 1690 1691 /** 1692 * Get the media stream index of the default video stream in the call. 1693 * Typically this will just retrieve the stream index of the first 1694 * activated video stream in the call. If none is active, it will return 1695 * the first inactive video stream. 1696 * 1697 * @return The media stream index or -1 if no video stream 1698 * is present in the call. 1699 */ 1700 int vidGetStreamIdx() const; 1701 1702 /** 1703 * Determine if video stream for the specified call is currently running 1704 * (i.e. has been created, started, and not being paused) for the specified 1705 * direction. 1706 * 1707 * @param med_idx Media stream index, or -1 to specify default video 1708 * media. 1709 * @param dir The direction to be checked. 1710 * 1711 * @return True if stream is currently running for the 1712 * specified direction. 1713 */ 1714 bool vidStreamIsRunning(int med_idx, pjmedia_dir dir) const; 1715 1716 /** 1717 * Add, remove, modify, and/or manipulate video media stream for the 1718 * specified call. This may trigger a re-INVITE or UPDATE to be sent 1719 * for the call. 1720 * 1721 * @param op The video stream operation to be performed, 1722 * possible values are pjsua_call_vid_strm_op. 1723 * @param param The parameters for the video stream operation 1724 * (see CallVidSetStreamParam). 1725 */ 1726 void vidSetStream(pjsua_call_vid_strm_op op, 1727 const CallVidSetStreamParam ¶m) PJSUA2_THROW(Error); 1728 1729 /** 1730 * Get media stream info for the specified media index. 1731 * 1732 * @param med_idx Media stream index. 1733 * 1734 * @return The stream info. 1735 */ 1736 StreamInfo getStreamInfo(unsigned med_idx) const PJSUA2_THROW(Error); 1737 1738 /** 1739 * Get media stream statistic for the specified media index. 1740 * 1741 * @param med_idx Media stream index. 1742 * 1743 * @return The stream statistic. 1744 */ 1745 StreamStat getStreamStat(unsigned med_idx) const PJSUA2_THROW(Error); 1746 1747 /** 1748 * Get media transport info for the specified media index. 1749 * 1750 * @param med_idx Media stream index. 1751 * 1752 * @return The transport info. 1753 */ 1754 MediaTransportInfo getMedTransportInfo(unsigned med_idx) const 1755 PJSUA2_THROW(Error); 1756 1757 /** 1758 * Internal function (callled by Endpoint( to process update to call 1759 * medias when call media state changes. 1760 */ 1761 void processMediaUpdate(OnCallMediaStateParam &prm); 1762 1763 /** 1764 * Internal function (called by Endpoint) to process call state change. 1765 */ 1766 void processStateChange(OnCallStateParam &prm); 1767 1768 public: 1769 /* 1770 * Callbacks 1771 */ 1772 /** 1773 * Notify application when call state has changed. 1774 * Application may then query the call info to get the 1775 * detail call states by calling getInfo() function. 1776 * 1777 * @param prm Callback parameter. 1778 */ onCallState(OnCallStateParam & prm)1779 virtual void onCallState(OnCallStateParam &prm) 1780 { PJ_UNUSED_ARG(prm); } 1781 1782 /** 1783 * This is a general notification callback which is called whenever 1784 * a transaction within the call has changed state. Application can 1785 * implement this callback for example to monitor the state of 1786 * outgoing requests, or to answer unhandled incoming requests 1787 * (such as INFO) with a final response. 1788 * 1789 * @param prm Callback parameter. 1790 */ onCallTsxState(OnCallTsxStateParam & prm)1791 virtual void onCallTsxState(OnCallTsxStateParam &prm) 1792 { PJ_UNUSED_ARG(prm); } 1793 1794 /** 1795 * Notify application when media state in the call has changed. 1796 * Normal application would need to implement this callback, e.g. 1797 * to connect the call's media to sound device. When ICE is used, 1798 * this callback will also be called to report ICE negotiation 1799 * failure. 1800 * 1801 * @param prm Callback parameter. 1802 */ onCallMediaState(OnCallMediaStateParam & prm)1803 virtual void onCallMediaState(OnCallMediaStateParam &prm) 1804 { PJ_UNUSED_ARG(prm); } 1805 1806 /** 1807 * Notify application when a call has just created a local SDP (for 1808 * initial or subsequent SDP offer/answer). Application can implement 1809 * this callback to modify the SDP, before it is being sent and/or 1810 * negotiated with remote SDP, for example to apply per account/call 1811 * basis codecs priority or to add custom/proprietary SDP attributes. 1812 * 1813 * @param prm Callback parameter. 1814 */ onCallSdpCreated(OnCallSdpCreatedParam & prm)1815 virtual void onCallSdpCreated(OnCallSdpCreatedParam &prm) 1816 { PJ_UNUSED_ARG(prm); } 1817 1818 /** 1819 * Notify application when an audio media session is about to be created 1820 * (as opposed to #on_stream_created() and #on_stream_created2() which are 1821 * called *after* the session has been created). The application may change 1822 * stream parameters like the jitter buffer size. 1823 * 1824 * @param prm Callback parameter. 1825 */ onStreamPreCreate(OnStreamPreCreateParam & prm)1826 virtual void onStreamPreCreate(OnStreamPreCreateParam &prm) 1827 { PJ_UNUSED_ARG(prm); } 1828 1829 /** 1830 * Notify application when audio media session is created and before it is 1831 * registered to the conference bridge. Application may return different 1832 * audio media port if it has added media processing port to the stream. 1833 * This media port then will be added to the conference bridge instead. 1834 * 1835 * @param prm Callback parameter. 1836 */ onStreamCreated(OnStreamCreatedParam & prm)1837 virtual void onStreamCreated(OnStreamCreatedParam &prm) 1838 { PJ_UNUSED_ARG(prm); } 1839 1840 /** 1841 * Notify application when audio media session has been unregistered from 1842 * the conference bridge and about to be destroyed. 1843 * 1844 * @param prm Callback parameter. 1845 */ onStreamDestroyed(OnStreamDestroyedParam & prm)1846 virtual void onStreamDestroyed(OnStreamDestroyedParam &prm) 1847 { PJ_UNUSED_ARG(prm); } 1848 1849 /** 1850 * Notify application upon incoming DTMF digits. 1851 * 1852 * @param prm Callback parameter. 1853 */ onDtmfDigit(OnDtmfDigitParam & prm)1854 virtual void onDtmfDigit(OnDtmfDigitParam &prm) 1855 { PJ_UNUSED_ARG(prm); } 1856 1857 /** 1858 * Notify application upon incoming DTMF events. 1859 * 1860 * @param prm Callback parameter. 1861 */ onDtmfEvent(OnDtmfEventParam & prm)1862 virtual void onDtmfEvent(OnDtmfEventParam &prm) 1863 { PJ_UNUSED_ARG(prm); } 1864 1865 /** 1866 * Notify application on call being transferred (i.e. REFER is received). 1867 * Application can decide to accept/reject transfer request by setting 1868 * the code (default is 202). When this callback is not implemented, 1869 * the default behavior is to accept the transfer. 1870 * 1871 * If application decides to accept the transfer request, it must also 1872 * instantiate the new Call object for the transfer operation and return 1873 * this new Call object to prm.newCall. 1874 * 1875 * If application does not specify new Call object, library will reuse the 1876 * existing Call object for initiating the new call (to the transfer 1877 * destination). In this case, any events from both calls (transferred and 1878 * transferring) will be delivered to the same Call object, where the call 1879 * ID will be switched back and forth between callbacks. Application must 1880 * be careful to not destroy the Call object when receiving disconnection 1881 * event of the transferred call after the transfer process is completed. 1882 * 1883 * @param prm Callback parameter. 1884 */ onCallTransferRequest(OnCallTransferRequestParam & prm)1885 virtual void onCallTransferRequest(OnCallTransferRequestParam &prm) 1886 { PJ_UNUSED_ARG(prm); } 1887 1888 /** 1889 * Notify application of the status of previously sent call 1890 * transfer request. Application can monitor the status of the 1891 * call transfer request, for example to decide whether to 1892 * terminate existing call. 1893 * 1894 * @param prm Callback parameter. 1895 */ onCallTransferStatus(OnCallTransferStatusParam & prm)1896 virtual void onCallTransferStatus(OnCallTransferStatusParam &prm) 1897 { PJ_UNUSED_ARG(prm); } 1898 1899 /** 1900 * Notify application about incoming INVITE with Replaces header. 1901 * Application may reject the request by setting non-2xx code. 1902 * 1903 * @param prm Callback parameter. 1904 */ onCallReplaceRequest(OnCallReplaceRequestParam & prm)1905 virtual void onCallReplaceRequest(OnCallReplaceRequestParam &prm) 1906 { PJ_UNUSED_ARG(prm); } 1907 1908 /** 1909 * Notify application that an existing call has been replaced with 1910 * a new call. This happens when PJSUA-API receives incoming INVITE 1911 * request with Replaces header. 1912 * 1913 * After this callback is called, normally PJSUA-API will disconnect 1914 * this call and establish a new call. To be able to control the call, 1915 * e.g: hold, transfer, change media parameters, application must 1916 * instantiate a new Call object for the new call using call ID 1917 * specified in prm.newCallId, and return the Call object via 1918 * prm.newCall. 1919 * 1920 * @param prm Callback parameter. 1921 */ onCallReplaced(OnCallReplacedParam & prm)1922 virtual void onCallReplaced(OnCallReplacedParam &prm) 1923 { PJ_UNUSED_ARG(prm); } 1924 1925 /** 1926 * Notify application when call has received new offer from remote 1927 * (i.e. re-INVITE/UPDATE with SDP is received). Application can 1928 * decide to accept/reject the offer by setting the code (default 1929 * is 200). If the offer is accepted, application can update the 1930 * call setting to be applied in the answer. When this callback is 1931 * not implemented, the default behavior is to accept the offer using 1932 * current call setting. 1933 * 1934 * @param prm Callback parameter. 1935 */ onCallRxOffer(OnCallRxOfferParam & prm)1936 virtual void onCallRxOffer(OnCallRxOfferParam &prm) 1937 { PJ_UNUSED_ARG(prm); } 1938 1939 /** 1940 * Notify application when call has received a re-INVITE offer from 1941 * the peer. It allows more fine-grained control over the response to 1942 * a re-INVITE. If application sets async to PJ_TRUE, it can send 1943 * the reply manually using the function #Call::answer() and setting 1944 * the SDP answer. Otherwise, by default the re-INVITE will be 1945 * answered automatically after the callback returns. 1946 * 1947 * Currently, this callback is only called for re-INVITE with 1948 * SDP, but app should be prepared to handle the case of re-INVITE 1949 * without SDP. 1950 * 1951 * Remarks: If manually answering at a later timing, application may 1952 * need to monitor onCallTsxState() callback to check whether 1953 * the re-INVITE is already answered automatically with 487 due to 1954 * being cancelled. 1955 * 1956 * Note: onCallRxOffer() will still be called after this callback, 1957 * but only if prm.async is false and prm.code is 200. 1958 */ onCallRxReinvite(OnCallRxReinviteParam & prm)1959 virtual void onCallRxReinvite(OnCallRxReinviteParam &prm) 1960 { PJ_UNUSED_ARG(prm); } 1961 1962 1963 /** 1964 * Notify application when call has received INVITE with no SDP offer. 1965 * Application can update the call setting (e.g: add audio/video), or 1966 * enable/disable codecs, or update other media session settings from 1967 * within the callback, however, as mandated by the standard (RFC3261 1968 * section 14.2), it must ensure that the update overlaps with the 1969 * existing media session (in codecs, transports, or other parameters) 1970 * that require support from the peer, this is to avoid the need for 1971 * the peer to reject the offer. 1972 * 1973 * When this callback is not implemented, the default behavior is to send 1974 * SDP offer using current active media session (with all enabled codecs 1975 * on each media type). 1976 * 1977 * @param prm Callback parameter. 1978 */ onCallTxOffer(OnCallTxOfferParam & prm)1979 virtual void onCallTxOffer(OnCallTxOfferParam &prm) 1980 { PJ_UNUSED_ARG(prm); } 1981 1982 /** 1983 * Notify application on incoming MESSAGE request. 1984 * 1985 * @param prm Callback parameter. 1986 */ onInstantMessage(OnInstantMessageParam & prm)1987 virtual void onInstantMessage(OnInstantMessageParam &prm) 1988 { PJ_UNUSED_ARG(prm); } 1989 1990 /** 1991 * Notify application about the delivery status of outgoing MESSAGE 1992 * request. 1993 * 1994 * @param prm Callback parameter. 1995 */ onInstantMessageStatus(OnInstantMessageStatusParam & prm)1996 virtual void onInstantMessageStatus(OnInstantMessageStatusParam &prm) 1997 { PJ_UNUSED_ARG(prm); } 1998 1999 /** 2000 * Notify application about typing indication. 2001 * 2002 * @param prm Callback parameter. 2003 */ onTypingIndication(OnTypingIndicationParam & prm)2004 virtual void onTypingIndication(OnTypingIndicationParam &prm) 2005 { PJ_UNUSED_ARG(prm); } 2006 2007 /** 2008 * This callback is called when the call is about to resend the 2009 * INVITE request to the specified target, following the previously 2010 * received redirection response. 2011 * 2012 * Application may accept the redirection to the specified target, 2013 * reject this target only and make the session continue to try the next 2014 * target in the list if such target exists, stop the whole 2015 * redirection process altogether and cause the session to be 2016 * disconnected, or defer the decision to ask for user confirmation. 2017 * 2018 * This callback is optional, 2019 * the default behavior is to NOT follow the redirection response. 2020 * 2021 * @param prm Callback parameter. 2022 * 2023 * @return Action to be performed for the target. Set this 2024 * parameter to one of the value below: 2025 * - PJSIP_REDIRECT_ACCEPT: immediately accept the 2026 * redirection. When set, the call will immediately 2027 * resend INVITE request to the target. 2028 * - PJSIP_REDIRECT_ACCEPT_REPLACE: immediately accept 2029 * the redirection and replace the To header with the 2030 * current target. When set, the call will immediately 2031 * resend INVITE request to the target. 2032 * - PJSIP_REDIRECT_REJECT: immediately reject this 2033 * target. The call will continue retrying with 2034 * next target if present, or disconnect the call 2035 * if there is no more target to try. 2036 * - PJSIP_REDIRECT_STOP: stop the whole redirection 2037 * process and immediately disconnect the call. The 2038 * onCallState() callback will be called with 2039 * PJSIP_INV_STATE_DISCONNECTED state immediately 2040 * after this callback returns. 2041 * - PJSIP_REDIRECT_PENDING: set to this value if 2042 * no decision can be made immediately (for example 2043 * to request confirmation from user). Application 2044 * then MUST call processRedirect() 2045 * to either accept or reject the redirection upon 2046 * getting user decision. 2047 */ onCallRedirected(OnCallRedirectedParam & prm)2048 virtual pjsip_redirect_op onCallRedirected(OnCallRedirectedParam &prm) 2049 { 2050 PJ_UNUSED_ARG(prm); 2051 return PJSIP_REDIRECT_STOP; 2052 } 2053 2054 /** 2055 * This callback is called when media transport state is changed. 2056 * 2057 * @param prm Callback parameter. 2058 */ onCallMediaTransportState(OnCallMediaTransportStateParam & prm)2059 virtual void onCallMediaTransportState(OnCallMediaTransportStateParam &prm) 2060 { PJ_UNUSED_ARG(prm); } 2061 2062 /** 2063 * Notification about media events such as video notifications. This 2064 * callback will most likely be called from media threads, thus 2065 * application must not perform heavy processing in this callback. 2066 * Especially, application must not destroy the call or media in this 2067 * callback. If application needs to perform more complex tasks to 2068 * handle the event, it should post the task to another thread. 2069 * 2070 * @param prm Callback parameter. 2071 */ onCallMediaEvent(OnCallMediaEventParam & prm)2072 virtual void onCallMediaEvent(OnCallMediaEventParam &prm) 2073 { PJ_UNUSED_ARG(prm); } 2074 2075 /** 2076 * This callback can be used by application to implement custom media 2077 * transport adapter for the call, or to replace the media transport 2078 * with something completely new altogether. 2079 * 2080 * This callback is called when a new call is created. The library has 2081 * created a media transport for the call, and it is provided as the 2082 * \a mediaTp argument of this callback. The callback may change it 2083 * with the instance of media transport to be used by the call. 2084 * 2085 * @param prm Callback parameter. 2086 */ 2087 virtual void onCreateMediaTransport(OnCreateMediaTransportParam & prm)2088 onCreateMediaTransport(OnCreateMediaTransportParam &prm) 2089 { PJ_UNUSED_ARG(prm); } 2090 2091 /** 2092 * Warning: deprecated and may be removed in future release. 2093 * Application can set SRTP crypto settings (including keys) and 2094 * keying methods via AccountConfig.mediaConfig.srtpOpt. 2095 * See also ticket #2100. 2096 * 2097 * This callback is called when SRTP media transport is created. 2098 * Application can modify the SRTP setting \a srtpOpt to specify 2099 * the cryptos and keys which are going to be used. Note that 2100 * application should not modify the field 2101 * \a pjmedia_srtp_setting.close_member_tp and can only modify 2102 * the field \a pjmedia_srtp_setting.use for initial INVITE. 2103 * 2104 * @param prm Callback parameter. 2105 */ 2106 virtual void onCreateMediaTransportSrtp(OnCreateMediaTransportSrtpParam & prm)2107 onCreateMediaTransportSrtp(OnCreateMediaTransportSrtpParam &prm) 2108 { PJ_UNUSED_ARG(prm); } 2109 2110 private: 2111 friend class Endpoint; 2112 2113 Account &acc; 2114 pjsua_call_id id; 2115 Token userData; 2116 std::vector<Media *> medias; 2117 pj_pool_t *sdp_pool; 2118 Call *child; /* New outgoing call in call transfer. */ 2119 }; 2120 2121 /** 2122 * @} // PJSUA2_CALL 2123 */ 2124 2125 } // namespace pj 2126 2127 #endif /* __PJSUA2_CALL_HPP__ */ 2128 2129