1 /* 2 * Copyright (c) 2012 The WebRTC project authors. All Rights Reserved. 3 * 4 * Use of this source code is governed by a BSD-style license 5 * that can be found in the LICENSE file in the root of the source 6 * tree. An additional intellectual property rights grant can be found 7 * in the file PATENTS. All contributing project authors may 8 * be found in the AUTHORS file in the root of the source tree. 9 */ 10 11 #ifndef WEBRTC_MODULES_RTP_RTCP_INTERFACE_RTP_RTCP_H_ 12 #define WEBRTC_MODULES_RTP_RTCP_INTERFACE_RTP_RTCP_H_ 13 14 #include <vector> 15 16 #include "webrtc/modules/interface/module.h" 17 #include "webrtc/modules/rtp_rtcp/interface/rtp_rtcp_defines.h" 18 19 namespace webrtc { 20 // Forward declarations. 21 class PacedSender; 22 class ReceiveStatistics; 23 class RemoteBitrateEstimator; 24 class RtpReceiver; 25 class Transport; 26 27 class RtpRtcp : public Module { 28 public: 29 struct Configuration { 30 Configuration(); 31 32 /* id - Unique identifier of this RTP/RTCP module object 33 * audio - True for a audio version of the RTP/RTCP module 34 * object false will create a video version 35 * clock - The clock to use to read time. If NULL object 36 * will be using the system clock. 37 * incoming_data - Callback object that will receive the incoming 38 * data. May not be NULL; default callback will do 39 * nothing. 40 * incoming_messages - Callback object that will receive the incoming 41 * RTP messages. May not be NULL; default callback 42 * will do nothing. 43 * outgoing_transport - Transport object that will be called when packets 44 * are ready to be sent out on the network 45 * rtcp_feedback - Callback object that will receive the incoming 46 * RTCP messages. 47 * intra_frame_callback - Called when the receiver request a intra frame. 48 * bandwidth_callback - Called when we receive a changed estimate from 49 * the receiver of out stream. 50 * audio_messages - Telehone events. May not be NULL; default callback 51 * will do nothing. 52 * remote_bitrate_estimator - Estimates the bandwidth available for a set of 53 * streams from the same client. 54 * paced_sender - Spread any bursts of packets into smaller 55 * bursts to minimize packet loss. 56 */ 57 int32_t id; 58 bool audio; 59 Clock* clock; 60 RtpRtcp* default_module; 61 ReceiveStatistics* receive_statistics; 62 Transport* outgoing_transport; 63 RtcpFeedback* rtcp_feedback; 64 RtcpIntraFrameObserver* intra_frame_callback; 65 RtcpBandwidthObserver* bandwidth_callback; 66 RtcpRttStats* rtt_stats; 67 RtpAudioFeedback* audio_messages; 68 RemoteBitrateEstimator* remote_bitrate_estimator; 69 PacedSender* paced_sender; 70 }; 71 72 /* 73 * Create a RTP/RTCP module object using the system clock. 74 * 75 * configuration - Configuration of the RTP/RTCP module. 76 */ 77 static RtpRtcp* CreateRtpRtcp(const RtpRtcp::Configuration& configuration); 78 79 /************************************************************************** 80 * 81 * Receiver functions 82 * 83 ***************************************************************************/ 84 85 virtual int32_t IncomingRtcpPacket(const uint8_t* incoming_packet, 86 uint16_t incoming_packet_length) = 0; 87 88 virtual void SetRemoteSSRC(const uint32_t ssrc) = 0; 89 90 /************************************************************************** 91 * 92 * Sender 93 * 94 ***************************************************************************/ 95 96 /* 97 * set MTU 98 * 99 * size - Max transfer unit in bytes, default is 1500 100 * 101 * return -1 on failure else 0 102 */ 103 virtual int32_t SetMaxTransferUnit(const uint16_t size) = 0; 104 105 /* 106 * set transtport overhead 107 * default is IPv4 and UDP with no encryption 108 * 109 * TCP - true for TCP false UDP 110 * IPv6 - true for IP version 6 false for version 4 111 * authenticationOverhead - number of bytes to leave for an 112 * authentication header 113 * 114 * return -1 on failure else 0 115 */ 116 virtual int32_t SetTransportOverhead( 117 const bool TCP, 118 const bool IPV6, 119 const uint8_t authenticationOverhead = 0) = 0; 120 121 /* 122 * Get max payload length 123 * 124 * A combination of the configuration MaxTransferUnit and 125 * TransportOverhead. 126 * Does not account FEC/ULP/RED overhead if FEC is enabled. 127 * Does not account for RTP headers 128 */ 129 virtual uint16_t MaxPayloadLength() const = 0; 130 131 /* 132 * Get max data payload length 133 * 134 * A combination of the configuration MaxTransferUnit, headers and 135 * TransportOverhead. 136 * Takes into account FEC/ULP/RED overhead if FEC is enabled. 137 * Takes into account RTP headers 138 */ 139 virtual uint16_t MaxDataPayloadLength() const = 0; 140 141 /* 142 * set codec name and payload type 143 * 144 * return -1 on failure else 0 145 */ 146 virtual int32_t RegisterSendPayload( 147 const CodecInst& voiceCodec) = 0; 148 149 /* 150 * set codec name and payload type 151 * 152 * return -1 on failure else 0 153 */ 154 virtual int32_t RegisterSendPayload( 155 const VideoCodec& videoCodec) = 0; 156 157 /* 158 * Unregister a send payload 159 * 160 * payloadType - payload type of codec 161 * 162 * return -1 on failure else 0 163 */ 164 virtual int32_t DeRegisterSendPayload( 165 const int8_t payloadType) = 0; 166 167 /* 168 * (De)register RTP header extension type and id. 169 * 170 * return -1 on failure else 0 171 */ 172 virtual int32_t RegisterSendRtpHeaderExtension( 173 const RTPExtensionType type, 174 const uint8_t id) = 0; 175 176 virtual int32_t DeregisterSendRtpHeaderExtension( 177 const RTPExtensionType type) = 0; 178 179 /* 180 * get start timestamp 181 */ 182 virtual uint32_t StartTimestamp() const = 0; 183 184 /* 185 * configure start timestamp, default is a random number 186 * 187 * timestamp - start timestamp 188 * 189 * return -1 on failure else 0 190 */ 191 virtual int32_t SetStartTimestamp( 192 const uint32_t timestamp) = 0; 193 194 /* 195 * Get SequenceNumber 196 */ 197 virtual uint16_t SequenceNumber() const = 0; 198 199 /* 200 * Set SequenceNumber, default is a random number 201 * 202 * return -1 on failure else 0 203 */ 204 virtual int32_t SetSequenceNumber(const uint16_t seq) = 0; 205 206 /* 207 * Get SSRC 208 */ 209 virtual uint32_t SSRC() const = 0; 210 211 /* 212 * configure SSRC, default is a random number 213 * 214 * return -1 on failure else 0 215 */ 216 virtual void SetSSRC(const uint32_t ssrc) = 0; 217 218 /* 219 * Get CSRC 220 * 221 * arrOfCSRC - array of CSRCs 222 * 223 * return -1 on failure else number of valid entries in the array 224 */ 225 virtual int32_t CSRCs( 226 uint32_t arrOfCSRC[kRtpCsrcSize]) const = 0; 227 228 /* 229 * Set CSRC 230 * 231 * arrOfCSRC - array of CSRCs 232 * arrLength - number of valid entries in the array 233 * 234 * return -1 on failure else 0 235 */ 236 virtual int32_t SetCSRCs( 237 const uint32_t arrOfCSRC[kRtpCsrcSize], 238 const uint8_t arrLength) = 0; 239 240 /* 241 * includes CSRCs in RTP header if enabled 242 * 243 * include CSRC - on/off 244 * 245 * default:on 246 * 247 * return -1 on failure else 0 248 */ 249 virtual int32_t SetCSRCStatus(const bool include) = 0; 250 251 /* 252 * Turn on/off sending RTX (RFC 4588). The modes can be set as a combination 253 * of values of the enumerator RtxMode. 254 */ 255 virtual void SetRTXSendStatus(int modes) = 0; 256 257 // Sets the SSRC to use when sending RTX packets. This doesn't enable RTX, 258 // only the SSRC is set. 259 virtual void SetRtxSsrc(uint32_t ssrc) = 0; 260 261 // Sets the payload type to use when sending RTX packets. Note that this 262 // doesn't enable RTX, only the payload type is set. 263 virtual void SetRtxSendPayloadType(int payload_type) = 0; 264 265 /* 266 * Get status of sending RTX (RFC 4588) on a specific SSRC. 267 */ 268 virtual void RTXSendStatus(int* modes, uint32_t* ssrc, 269 int* payloadType) const = 0; 270 271 /* 272 * sends kRtcpByeCode when going from true to false 273 * 274 * sending - on/off 275 * 276 * return -1 on failure else 0 277 */ 278 virtual int32_t SetSendingStatus(const bool sending) = 0; 279 280 /* 281 * get send status 282 */ 283 virtual bool Sending() const = 0; 284 285 /* 286 * Starts/Stops media packets, on by default 287 * 288 * sending - on/off 289 * 290 * return -1 on failure else 0 291 */ 292 virtual int32_t SetSendingMediaStatus(const bool sending) = 0; 293 294 /* 295 * get send status 296 */ 297 virtual bool SendingMedia() const = 0; 298 299 /* 300 * get sent bitrate in Kbit/s 301 */ 302 virtual void BitrateSent(uint32_t* totalRate, 303 uint32_t* videoRate, 304 uint32_t* fecRate, 305 uint32_t* nackRate) const = 0; 306 307 /* 308 * Called on any new send bitrate estimate. 309 */ 310 virtual void RegisterVideoBitrateObserver( 311 BitrateStatisticsObserver* observer) = 0; 312 virtual BitrateStatisticsObserver* GetVideoBitrateObserver() const = 0; 313 314 /* 315 * Used by the codec module to deliver a video or audio frame for 316 * packetization. 317 * 318 * frameType - type of frame to send 319 * payloadType - payload type of frame to send 320 * timestamp - timestamp of frame to send 321 * payloadData - payload buffer of frame to send 322 * payloadSize - size of payload buffer to send 323 * fragmentation - fragmentation offset data for fragmented frames such 324 * as layers or RED 325 * 326 * return -1 on failure else 0 327 */ 328 virtual int32_t SendOutgoingData( 329 const FrameType frameType, 330 const int8_t payloadType, 331 const uint32_t timeStamp, 332 int64_t capture_time_ms, 333 const uint8_t* payloadData, 334 const uint32_t payloadSize, 335 const RTPFragmentationHeader* fragmentation = NULL, 336 const RTPVideoHeader* rtpVideoHdr = NULL) = 0; 337 338 virtual bool TimeToSendPacket(uint32_t ssrc, 339 uint16_t sequence_number, 340 int64_t capture_time_ms, 341 bool retransmission) = 0; 342 343 virtual int TimeToSendPadding(int bytes) = 0; 344 345 virtual void RegisterSendFrameCountObserver( 346 FrameCountObserver* observer) = 0; 347 virtual FrameCountObserver* GetSendFrameCountObserver() const = 0; 348 349 virtual bool GetSendSideDelay(int* avg_send_delay_ms, 350 int* max_send_delay_ms) const = 0; 351 352 // Called on generation of new statistics after an RTP send. 353 virtual void RegisterSendChannelRtpStatisticsCallback( 354 StreamDataCountersCallback* callback) = 0; 355 virtual StreamDataCountersCallback* 356 GetSendChannelRtpStatisticsCallback() const = 0; 357 358 /************************************************************************** 359 * 360 * RTCP 361 * 362 ***************************************************************************/ 363 364 /* 365 * Get RTCP status 366 */ 367 virtual RTCPMethod RTCP() const = 0; 368 369 /* 370 * configure RTCP status i.e on(compound or non- compound)/off 371 * 372 * method - RTCP method to use 373 * 374 * return -1 on failure else 0 375 */ 376 virtual int32_t SetRTCPStatus(const RTCPMethod method) = 0; 377 378 /* 379 * Set RTCP CName (i.e unique identifier) 380 * 381 * return -1 on failure else 0 382 */ 383 virtual int32_t SetCNAME(const char cName[RTCP_CNAME_SIZE]) = 0; 384 385 /* 386 * Get RTCP CName (i.e unique identifier) 387 * 388 * return -1 on failure else 0 389 */ 390 virtual int32_t CNAME(char cName[RTCP_CNAME_SIZE]) = 0; 391 392 /* 393 * Get remote CName 394 * 395 * return -1 on failure else 0 396 */ 397 virtual int32_t RemoteCNAME( 398 const uint32_t remoteSSRC, 399 char cName[RTCP_CNAME_SIZE]) const = 0; 400 401 /* 402 * Get remote NTP 403 * 404 * return -1 on failure else 0 405 */ 406 virtual int32_t RemoteNTP( 407 uint32_t *ReceivedNTPsecs, 408 uint32_t *ReceivedNTPfrac, 409 uint32_t *RTCPArrivalTimeSecs, 410 uint32_t *RTCPArrivalTimeFrac, 411 uint32_t *rtcp_timestamp) const = 0; 412 413 /* 414 * AddMixedCNAME 415 * 416 * return -1 on failure else 0 417 */ 418 virtual int32_t AddMixedCNAME( 419 const uint32_t SSRC, 420 const char cName[RTCP_CNAME_SIZE]) = 0; 421 422 /* 423 * RemoveMixedCNAME 424 * 425 * return -1 on failure else 0 426 */ 427 virtual int32_t RemoveMixedCNAME(const uint32_t SSRC) = 0; 428 429 /* 430 * Get RoundTripTime 431 * 432 * return -1 on failure else 0 433 */ 434 virtual int32_t RTT(const uint32_t remoteSSRC, 435 uint16_t* RTT, 436 uint16_t* avgRTT, 437 uint16_t* minRTT, 438 uint16_t* maxRTT) const = 0 ; 439 440 /* 441 * Reset RoundTripTime statistics 442 * 443 * return -1 on failure else 0 444 */ 445 virtual int32_t ResetRTT(const uint32_t remoteSSRC)= 0 ; 446 447 /* 448 * Force a send of a RTCP packet 449 * normal SR and RR are triggered via the process function 450 * 451 * return -1 on failure else 0 452 */ 453 virtual int32_t SendRTCP( 454 uint32_t rtcpPacketType = kRtcpReport) = 0; 455 456 /* 457 * Good state of RTP receiver inform sender 458 */ 459 virtual int32_t SendRTCPReferencePictureSelection( 460 const uint64_t pictureID) = 0; 461 462 /* 463 * Send a RTCP Slice Loss Indication (SLI) 464 * 6 least significant bits of pictureID 465 */ 466 virtual int32_t SendRTCPSliceLossIndication( 467 const uint8_t pictureID) = 0; 468 469 /* 470 * Reset RTP data counters for the sending side 471 * 472 * return -1 on failure else 0 473 */ 474 virtual int32_t ResetSendDataCountersRTP() = 0; 475 476 /* 477 * statistics of the amount of data sent and received 478 * 479 * return -1 on failure else 0 480 */ 481 virtual int32_t DataCountersRTP( 482 uint32_t* bytesSent, 483 uint32_t* packetsSent) const = 0; 484 /* 485 * Get received RTCP sender info 486 * 487 * return -1 on failure else 0 488 */ 489 virtual int32_t RemoteRTCPStat(RTCPSenderInfo* senderInfo) = 0; 490 491 /* 492 * Get received RTCP report block 493 * 494 * return -1 on failure else 0 495 */ 496 virtual int32_t RemoteRTCPStat( 497 std::vector<RTCPReportBlock>* receiveBlocks) const = 0; 498 /* 499 * Set received RTCP report block 500 * 501 * return -1 on failure else 0 502 */ 503 virtual int32_t AddRTCPReportBlock( 504 const uint32_t SSRC, 505 const RTCPReportBlock* receiveBlock) = 0; 506 507 /* 508 * RemoveRTCPReportBlock 509 * 510 * return -1 on failure else 0 511 */ 512 virtual int32_t RemoveRTCPReportBlock(const uint32_t SSRC) = 0; 513 514 /* 515 * Get number of sent and received RTCP packet types. 516 */ 517 virtual void GetRtcpPacketTypeCounters( 518 RtcpPacketTypeCounter* packets_sent, 519 RtcpPacketTypeCounter* packets_received) const = 0; 520 521 /* 522 * (APP) Application specific data 523 * 524 * return -1 on failure else 0 525 */ 526 virtual int32_t SetRTCPApplicationSpecificData( 527 const uint8_t subType, 528 const uint32_t name, 529 const uint8_t* data, 530 const uint16_t length) = 0; 531 /* 532 * (XR) VOIP metric 533 * 534 * return -1 on failure else 0 535 */ 536 virtual int32_t SetRTCPVoIPMetrics( 537 const RTCPVoIPMetric* VoIPMetric) = 0; 538 539 /* 540 * (XR) Receiver Reference Time Report 541 */ 542 virtual void SetRtcpXrRrtrStatus(bool enable) = 0; 543 544 virtual bool RtcpXrRrtrStatus() const = 0; 545 546 /* 547 * (REMB) Receiver Estimated Max Bitrate 548 */ 549 virtual bool REMB() const = 0; 550 551 virtual int32_t SetREMBStatus(const bool enable) = 0; 552 553 virtual int32_t SetREMBData(const uint32_t bitrate, 554 const uint8_t numberOfSSRC, 555 const uint32_t* SSRC) = 0; 556 557 /* 558 * (IJ) Extended jitter report. 559 */ 560 virtual bool IJ() const = 0; 561 562 virtual int32_t SetIJStatus(const bool enable) = 0; 563 564 /* 565 * (TMMBR) Temporary Max Media Bit Rate 566 */ 567 virtual bool TMMBR() const = 0; 568 569 /* 570 * 571 * return -1 on failure else 0 572 */ 573 virtual int32_t SetTMMBRStatus(const bool enable) = 0; 574 575 /* 576 * (NACK) 577 */ 578 579 /* 580 * TODO(holmer): Propagate this API to VideoEngine. 581 * Returns the currently configured selective retransmission settings. 582 */ 583 virtual int SelectiveRetransmissions() const = 0; 584 585 /* 586 * TODO(holmer): Propagate this API to VideoEngine. 587 * Sets the selective retransmission settings, which will decide which 588 * packets will be retransmitted if NACKed. Settings are constructed by 589 * combining the constants in enum RetransmissionMode with bitwise OR. 590 * All packets are retransmitted if kRetransmitAllPackets is set, while no 591 * packets are retransmitted if kRetransmitOff is set. 592 * By default all packets except FEC packets are retransmitted. For VP8 593 * with temporal scalability only base layer packets are retransmitted. 594 * 595 * Returns -1 on failure, otherwise 0. 596 */ 597 virtual int SetSelectiveRetransmissions(uint8_t settings) = 0; 598 599 /* 600 * Send a Negative acknowledgement packet 601 * 602 * return -1 on failure else 0 603 */ 604 virtual int32_t SendNACK(const uint16_t* nackList, 605 const uint16_t size) = 0; 606 607 /* 608 * Store the sent packets, needed to answer to a Negative acknowledgement 609 * requests 610 * 611 * return -1 on failure else 0 612 */ 613 virtual int32_t SetStorePacketsStatus( 614 const bool enable, 615 const uint16_t numberToStore) = 0; 616 617 // Returns true if the module is configured to store packets. 618 virtual bool StorePackets() const = 0; 619 620 // Called on receipt of RTCP report block from remote side. 621 virtual void RegisterSendChannelRtcpStatisticsCallback( 622 RtcpStatisticsCallback* callback) = 0; 623 virtual RtcpStatisticsCallback* 624 GetSendChannelRtcpStatisticsCallback() = 0; 625 626 /************************************************************************** 627 * 628 * Audio 629 * 630 ***************************************************************************/ 631 632 /* 633 * set audio packet size, used to determine when it's time to send a DTMF 634 * packet in silence (CNG) 635 * 636 * return -1 on failure else 0 637 */ 638 virtual int32_t SetAudioPacketSize( 639 const uint16_t packetSizeSamples) = 0; 640 641 /* 642 * SendTelephoneEventActive 643 * 644 * return true if we currently send a telephone event and 100 ms after an 645 * event is sent used to prevent the telephone event tone to be recorded 646 * by the microphone and send inband just after the tone has ended. 647 */ 648 virtual bool SendTelephoneEventActive( 649 int8_t& telephoneEvent) const = 0; 650 651 /* 652 * Send a TelephoneEvent tone using RFC 2833 (4733) 653 * 654 * return -1 on failure else 0 655 */ 656 virtual int32_t SendTelephoneEventOutband( 657 const uint8_t key, 658 const uint16_t time_ms, 659 const uint8_t level) = 0; 660 661 /* 662 * Set payload type for Redundant Audio Data RFC 2198 663 * 664 * return -1 on failure else 0 665 */ 666 virtual int32_t SetSendREDPayloadType( 667 const int8_t payloadType) = 0; 668 669 /* 670 * Get payload type for Redundant Audio Data RFC 2198 671 * 672 * return -1 on failure else 0 673 */ 674 virtual int32_t SendREDPayloadType( 675 int8_t& payloadType) const = 0; 676 677 /* 678 * Store the audio level in dBov for header-extension-for-audio-level- 679 * indication. 680 * This API shall be called before transmision of an RTP packet to ensure 681 * that the |level| part of the extended RTP header is updated. 682 * 683 * return -1 on failure else 0. 684 */ 685 virtual int32_t SetAudioLevel(const uint8_t level_dBov) = 0; 686 687 /************************************************************************** 688 * 689 * Video 690 * 691 ***************************************************************************/ 692 693 /* 694 * Set the estimated camera delay in MS 695 * 696 * return -1 on failure else 0 697 */ 698 virtual int32_t SetCameraDelay(const int32_t delayMS) = 0; 699 700 /* 701 * Set the target send bitrate 702 */ 703 virtual void SetTargetSendBitrate( 704 const std::vector<uint32_t>& stream_bitrates) = 0; 705 706 /* 707 * Turn on/off generic FEC 708 * 709 * return -1 on failure else 0 710 */ 711 virtual int32_t SetGenericFECStatus( 712 const bool enable, 713 const uint8_t payloadTypeRED, 714 const uint8_t payloadTypeFEC) = 0; 715 716 /* 717 * Get generic FEC setting 718 * 719 * return -1 on failure else 0 720 */ 721 virtual int32_t GenericFECStatus(bool& enable, 722 uint8_t& payloadTypeRED, 723 uint8_t& payloadTypeFEC) = 0; 724 725 726 virtual int32_t SetFecParameters( 727 const FecProtectionParams* delta_params, 728 const FecProtectionParams* key_params) = 0; 729 730 /* 731 * Set method for requestion a new key frame 732 * 733 * return -1 on failure else 0 734 */ 735 virtual int32_t SetKeyFrameRequestMethod( 736 const KeyFrameRequestMethod method) = 0; 737 738 /* 739 * send a request for a keyframe 740 * 741 * return -1 on failure else 0 742 */ 743 virtual int32_t RequestKeyFrame() = 0; 744 }; 745 } // namespace webrtc 746 #endif // WEBRTC_MODULES_RTP_RTCP_INTERFACE_RTP_RTCP_H_ 747