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_INCLUDE_RTP_RTCP_H_ 12 #define WEBRTC_MODULES_RTP_RTCP_INCLUDE_RTP_RTCP_H_ 13 14 #include <set> 15 #include <utility> 16 #include <vector> 17 18 #include "webrtc/modules/include/module.h" 19 #include "webrtc/modules/rtp_rtcp/include/rtp_rtcp_defines.h" 20 21 namespace webrtc { 22 // Forward declarations. 23 class ReceiveStatistics; 24 class RemoteBitrateEstimator; 25 class RtpReceiver; 26 class Transport; 27 namespace rtcp { 28 class TransportFeedback; 29 } 30 31 class RtpRtcp : public Module { 32 public: 33 struct Configuration { 34 Configuration(); 35 36 /* id - Unique identifier of this RTP/RTCP module object 37 * audio - True for a audio version of the RTP/RTCP module 38 * object false will create a video version 39 * clock - The clock to use to read time. If NULL object 40 * will be using the system clock. 41 * incoming_data - Callback object that will receive the incoming 42 * data. May not be NULL; default callback will do 43 * nothing. 44 * incoming_messages - Callback object that will receive the incoming 45 * RTP messages. May not be NULL; default callback 46 * will do nothing. 47 * outgoing_transport - Transport object that will be called when packets 48 * are ready to be sent out on the network 49 * intra_frame_callback - Called when the receiver request a intra frame. 50 * bandwidth_callback - Called when we receive a changed estimate from 51 * the receiver of out stream. 52 * audio_messages - Telephone events. May not be NULL; default 53 * callback will do nothing. 54 * remote_bitrate_estimator - Estimates the bandwidth available for a set of 55 * streams from the same client. 56 * paced_sender - Spread any bursts of packets into smaller 57 * bursts to minimize packet loss. 58 */ 59 bool audio; 60 bool receiver_only; 61 Clock* clock; 62 ReceiveStatistics* receive_statistics; 63 Transport* outgoing_transport; 64 RtcpIntraFrameObserver* intra_frame_callback; 65 RtcpBandwidthObserver* bandwidth_callback; 66 TransportFeedbackObserver* transport_feedback_callback; 67 RtcpRttStats* rtt_stats; 68 RtcpPacketTypeCounterObserver* rtcp_packet_type_counter_observer; 69 RtpAudioFeedback* audio_messages; 70 RemoteBitrateEstimator* remote_bitrate_estimator; 71 RtpPacketSender* paced_sender; 72 TransportSequenceNumberAllocator* transport_sequence_number_allocator; 73 BitrateStatisticsObserver* send_bitrate_observer; 74 FrameCountObserver* send_frame_count_observer; 75 SendSideDelayObserver* send_side_delay_observer; 76 }; 77 78 /* 79 * Create a RTP/RTCP module object using the system clock. 80 * 81 * configuration - Configuration of the RTP/RTCP module. 82 */ 83 static RtpRtcp* CreateRtpRtcp(const RtpRtcp::Configuration& configuration); 84 85 /************************************************************************** 86 * 87 * Receiver functions 88 * 89 ***************************************************************************/ 90 91 virtual int32_t IncomingRtcpPacket(const uint8_t* incoming_packet, 92 size_t incoming_packet_length) = 0; 93 94 virtual void SetRemoteSSRC(uint32_t ssrc) = 0; 95 96 /************************************************************************** 97 * 98 * Sender 99 * 100 ***************************************************************************/ 101 102 /* 103 * set MTU 104 * 105 * size - Max transfer unit in bytes, default is 1500 106 * 107 * return -1 on failure else 0 108 */ 109 virtual int32_t SetMaxTransferUnit(uint16_t size) = 0; 110 111 /* 112 * set transtport overhead 113 * default is IPv4 and UDP with no encryption 114 * 115 * TCP - true for TCP false UDP 116 * IPv6 - true for IP version 6 false for version 4 117 * authenticationOverhead - number of bytes to leave for an 118 * authentication header 119 * 120 * return -1 on failure else 0 121 */ 122 virtual int32_t SetTransportOverhead( 123 bool TCP, 124 bool IPV6, 125 uint8_t authenticationOverhead = 0) = 0; 126 127 /* 128 * Get max payload length 129 * 130 * A combination of the configuration MaxTransferUnit and 131 * TransportOverhead. 132 * Does not account FEC/ULP/RED overhead if FEC is enabled. 133 * Does not account for RTP headers 134 */ 135 virtual uint16_t MaxPayloadLength() const = 0; 136 137 /* 138 * Get max data payload length 139 * 140 * A combination of the configuration MaxTransferUnit, headers and 141 * TransportOverhead. 142 * Takes into account FEC/ULP/RED overhead if FEC is enabled. 143 * Takes into account RTP headers 144 */ 145 virtual uint16_t MaxDataPayloadLength() const = 0; 146 147 /* 148 * set codec name and payload type 149 * 150 * return -1 on failure else 0 151 */ 152 virtual int32_t RegisterSendPayload( 153 const CodecInst& voiceCodec) = 0; 154 155 /* 156 * set codec name and payload type 157 * 158 * return -1 on failure else 0 159 */ 160 virtual int32_t RegisterSendPayload( 161 const VideoCodec& videoCodec) = 0; 162 163 /* 164 * Unregister a send payload 165 * 166 * payloadType - payload type of codec 167 * 168 * return -1 on failure else 0 169 */ 170 virtual int32_t DeRegisterSendPayload(int8_t payloadType) = 0; 171 172 /* 173 * (De)register RTP header extension type and id. 174 * 175 * return -1 on failure else 0 176 */ 177 virtual int32_t RegisterSendRtpHeaderExtension(RTPExtensionType type, 178 uint8_t id) = 0; 179 180 virtual int32_t DeregisterSendRtpHeaderExtension(RTPExtensionType type) = 0; 181 182 /* 183 * get start timestamp 184 */ 185 virtual uint32_t StartTimestamp() const = 0; 186 187 /* 188 * configure start timestamp, default is a random number 189 * 190 * timestamp - start timestamp 191 */ 192 virtual void SetStartTimestamp(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 virtual void SetSequenceNumber(uint16_t seq) = 0; 203 204 // Returns true if the ssrc matched this module, false otherwise. 205 virtual bool SetRtpStateForSsrc(uint32_t ssrc, 206 const RtpState& rtp_state) = 0; 207 virtual bool GetRtpStateForSsrc(uint32_t ssrc, RtpState* rtp_state) = 0; 208 209 /* 210 * Get SSRC 211 */ 212 virtual uint32_t SSRC() const = 0; 213 214 /* 215 * configure SSRC, default is a random number 216 */ 217 virtual void SetSSRC(uint32_t ssrc) = 0; 218 219 /* 220 * Set CSRC 221 * 222 * csrcs - vector of CSRCs 223 */ 224 virtual void SetCsrcs(const std::vector<uint32_t>& csrcs) = 0; 225 226 /* 227 * Turn on/off sending RTX (RFC 4588). The modes can be set as a combination 228 * of values of the enumerator RtxMode. 229 */ 230 virtual void SetRtxSendStatus(int modes) = 0; 231 232 /* 233 * Get status of sending RTX (RFC 4588). The returned value can be 234 * a combination of values of the enumerator RtxMode. 235 */ 236 virtual int RtxSendStatus() const = 0; 237 238 // Sets the SSRC to use when sending RTX packets. This doesn't enable RTX, 239 // only the SSRC is set. 240 virtual void SetRtxSsrc(uint32_t ssrc) = 0; 241 242 // Sets the payload type to use when sending RTX packets. Note that this 243 // doesn't enable RTX, only the payload type is set. 244 virtual void SetRtxSendPayloadType(int payload_type, 245 int associated_payload_type) = 0; 246 247 // Gets the payload type pair of (RTX, associated) to use when sending RTX 248 // packets. 249 virtual std::pair<int, int> RtxSendPayloadType() const = 0; 250 251 /* 252 * sends kRtcpByeCode when going from true to false 253 * 254 * sending - on/off 255 * 256 * return -1 on failure else 0 257 */ 258 virtual int32_t SetSendingStatus(bool sending) = 0; 259 260 /* 261 * get send status 262 */ 263 virtual bool Sending() const = 0; 264 265 /* 266 * Starts/Stops media packets, on by default 267 * 268 * sending - on/off 269 */ 270 virtual void SetSendingMediaStatus(bool sending) = 0; 271 272 /* 273 * get send status 274 */ 275 virtual bool SendingMedia() const = 0; 276 277 /* 278 * get sent bitrate in Kbit/s 279 */ 280 virtual void BitrateSent(uint32_t* totalRate, 281 uint32_t* videoRate, 282 uint32_t* fecRate, 283 uint32_t* nackRate) const = 0; 284 285 /* 286 * Used by the codec module to deliver a video or audio frame for 287 * packetization. 288 * 289 * frameType - type of frame to send 290 * payloadType - payload type of frame to send 291 * timestamp - timestamp of frame to send 292 * payloadData - payload buffer of frame to send 293 * payloadSize - size of payload buffer to send 294 * fragmentation - fragmentation offset data for fragmented frames such 295 * as layers or RED 296 * 297 * return -1 on failure else 0 298 */ 299 virtual int32_t SendOutgoingData( 300 FrameType frameType, 301 int8_t payloadType, 302 uint32_t timeStamp, 303 int64_t capture_time_ms, 304 const uint8_t* payloadData, 305 size_t payloadSize, 306 const RTPFragmentationHeader* fragmentation = NULL, 307 const RTPVideoHeader* rtpVideoHdr = NULL) = 0; 308 309 virtual bool TimeToSendPacket(uint32_t ssrc, 310 uint16_t sequence_number, 311 int64_t capture_time_ms, 312 bool retransmission) = 0; 313 314 virtual size_t TimeToSendPadding(size_t bytes) = 0; 315 316 // Called on generation of new statistics after an RTP send. 317 virtual void RegisterSendChannelRtpStatisticsCallback( 318 StreamDataCountersCallback* callback) = 0; 319 virtual StreamDataCountersCallback* 320 GetSendChannelRtpStatisticsCallback() const = 0; 321 322 /************************************************************************** 323 * 324 * RTCP 325 * 326 ***************************************************************************/ 327 328 /* 329 * Get RTCP status 330 */ 331 virtual RtcpMode RTCP() const = 0; 332 333 /* 334 * configure RTCP status i.e on(compound or non- compound)/off 335 * 336 * method - RTCP method to use 337 */ 338 virtual void SetRTCPStatus(RtcpMode method) = 0; 339 340 /* 341 * Set RTCP CName (i.e unique identifier) 342 * 343 * return -1 on failure else 0 344 */ 345 virtual int32_t SetCNAME(const char* c_name) = 0; 346 347 /* 348 * Get remote CName 349 * 350 * return -1 on failure else 0 351 */ 352 virtual int32_t RemoteCNAME(uint32_t remoteSSRC, 353 char cName[RTCP_CNAME_SIZE]) const = 0; 354 355 /* 356 * Get remote NTP 357 * 358 * return -1 on failure else 0 359 */ 360 virtual int32_t RemoteNTP( 361 uint32_t *ReceivedNTPsecs, 362 uint32_t *ReceivedNTPfrac, 363 uint32_t *RTCPArrivalTimeSecs, 364 uint32_t *RTCPArrivalTimeFrac, 365 uint32_t *rtcp_timestamp) const = 0; 366 367 /* 368 * AddMixedCNAME 369 * 370 * return -1 on failure else 0 371 */ 372 virtual int32_t AddMixedCNAME(uint32_t SSRC, const char* c_name) = 0; 373 374 /* 375 * RemoveMixedCNAME 376 * 377 * return -1 on failure else 0 378 */ 379 virtual int32_t RemoveMixedCNAME(uint32_t SSRC) = 0; 380 381 /* 382 * Get RoundTripTime 383 * 384 * return -1 on failure else 0 385 */ 386 virtual int32_t RTT(uint32_t remoteSSRC, 387 int64_t* RTT, 388 int64_t* avgRTT, 389 int64_t* minRTT, 390 int64_t* maxRTT) const = 0; 391 392 /* 393 * Force a send of a RTCP packet 394 * periodic SR and RR are triggered via the process function 395 * 396 * return -1 on failure else 0 397 */ 398 virtual int32_t SendRTCP(RTCPPacketType rtcpPacketType) = 0; 399 400 /* 401 * Force a send of a RTCP packet with more than one packet type. 402 * periodic SR and RR are triggered via the process function 403 * 404 * return -1 on failure else 0 405 */ 406 virtual int32_t SendCompoundRTCP( 407 const std::set<RTCPPacketType>& rtcpPacketTypes) = 0; 408 409 /* 410 * Good state of RTP receiver inform sender 411 */ 412 virtual int32_t SendRTCPReferencePictureSelection( 413 const uint64_t pictureID) = 0; 414 415 /* 416 * Send a RTCP Slice Loss Indication (SLI) 417 * 6 least significant bits of pictureID 418 */ 419 virtual int32_t SendRTCPSliceLossIndication(uint8_t pictureID) = 0; 420 421 /* 422 * Statistics of the amount of data sent 423 * 424 * return -1 on failure else 0 425 */ 426 virtual int32_t DataCountersRTP( 427 size_t* bytesSent, 428 uint32_t* packetsSent) const = 0; 429 430 /* 431 * Get send statistics for the RTP and RTX stream. 432 */ 433 virtual void GetSendStreamDataCounters( 434 StreamDataCounters* rtp_counters, 435 StreamDataCounters* rtx_counters) const = 0; 436 437 /* 438 * Get packet loss statistics for the RTP stream. 439 */ 440 virtual void GetRtpPacketLossStats( 441 bool outgoing, 442 uint32_t ssrc, 443 struct RtpPacketLossStats* loss_stats) const = 0; 444 445 /* 446 * Get received RTCP sender info 447 * 448 * return -1 on failure else 0 449 */ 450 virtual int32_t RemoteRTCPStat(RTCPSenderInfo* senderInfo) = 0; 451 452 /* 453 * Get received RTCP report block 454 * 455 * return -1 on failure else 0 456 */ 457 virtual int32_t RemoteRTCPStat( 458 std::vector<RTCPReportBlock>* receiveBlocks) const = 0; 459 460 /* 461 * (APP) Application specific data 462 * 463 * return -1 on failure else 0 464 */ 465 virtual int32_t SetRTCPApplicationSpecificData(uint8_t subType, 466 uint32_t name, 467 const uint8_t* data, 468 uint16_t length) = 0; 469 /* 470 * (XR) VOIP metric 471 * 472 * return -1 on failure else 0 473 */ 474 virtual int32_t SetRTCPVoIPMetrics( 475 const RTCPVoIPMetric* VoIPMetric) = 0; 476 477 /* 478 * (XR) Receiver Reference Time Report 479 */ 480 virtual void SetRtcpXrRrtrStatus(bool enable) = 0; 481 482 virtual bool RtcpXrRrtrStatus() const = 0; 483 484 /* 485 * (REMB) Receiver Estimated Max Bitrate 486 */ 487 virtual bool REMB() const = 0; 488 489 virtual void SetREMBStatus(bool enable) = 0; 490 491 virtual void SetREMBData(uint32_t bitrate, 492 const std::vector<uint32_t>& ssrcs) = 0; 493 494 /* 495 * (TMMBR) Temporary Max Media Bit Rate 496 */ 497 virtual bool TMMBR() const = 0; 498 499 virtual void SetTMMBRStatus(bool enable) = 0; 500 501 /* 502 * (NACK) 503 */ 504 505 /* 506 * TODO(holmer): Propagate this API to VideoEngine. 507 * Returns the currently configured selective retransmission settings. 508 */ 509 virtual int SelectiveRetransmissions() const = 0; 510 511 /* 512 * TODO(holmer): Propagate this API to VideoEngine. 513 * Sets the selective retransmission settings, which will decide which 514 * packets will be retransmitted if NACKed. Settings are constructed by 515 * combining the constants in enum RetransmissionMode with bitwise OR. 516 * All packets are retransmitted if kRetransmitAllPackets is set, while no 517 * packets are retransmitted if kRetransmitOff is set. 518 * By default all packets except FEC packets are retransmitted. For VP8 519 * with temporal scalability only base layer packets are retransmitted. 520 * 521 * Returns -1 on failure, otherwise 0. 522 */ 523 virtual int SetSelectiveRetransmissions(uint8_t settings) = 0; 524 525 /* 526 * Send a Negative acknowledgement packet 527 * 528 * return -1 on failure else 0 529 */ 530 virtual int32_t SendNACK(const uint16_t* nackList, uint16_t size) = 0; 531 532 /* 533 * Store the sent packets, needed to answer to a Negative acknowledgement 534 * requests 535 */ 536 virtual void SetStorePacketsStatus(bool enable, uint16_t numberToStore) = 0; 537 538 // Returns true if the module is configured to store packets. 539 virtual bool StorePackets() const = 0; 540 541 // Called on receipt of RTCP report block from remote side. 542 virtual void RegisterRtcpStatisticsCallback( 543 RtcpStatisticsCallback* callback) = 0; 544 virtual RtcpStatisticsCallback* 545 GetRtcpStatisticsCallback() = 0; 546 // BWE feedback packets. 547 virtual bool SendFeedbackPacket(const rtcp::TransportFeedback& packet) = 0; 548 549 /************************************************************************** 550 * 551 * Audio 552 * 553 ***************************************************************************/ 554 555 /* 556 * set audio packet size, used to determine when it's time to send a DTMF 557 * packet in silence (CNG) 558 * 559 * return -1 on failure else 0 560 */ 561 virtual int32_t SetAudioPacketSize(uint16_t packetSizeSamples) = 0; 562 563 /* 564 * Send a TelephoneEvent tone using RFC 2833 (4733) 565 * 566 * return -1 on failure else 0 567 */ 568 virtual int32_t SendTelephoneEventOutband(uint8_t key, 569 uint16_t time_ms, 570 uint8_t level) = 0; 571 572 /* 573 * Set payload type for Redundant Audio Data RFC 2198 574 * 575 * return -1 on failure else 0 576 */ 577 virtual int32_t SetSendREDPayloadType(int8_t payloadType) = 0; 578 579 /* 580 * Get payload type for Redundant Audio Data RFC 2198 581 * 582 * return -1 on failure else 0 583 */ 584 // DEPRECATED. Use SendREDPayloadType below that takes output parameter 585 // by pointer instead of by reference. 586 // TODO(danilchap): Remove this when all callers have been updated. SendREDPayloadType(int8_t & payloadType)587 int32_t SendREDPayloadType(int8_t& payloadType) const { // NOLINT 588 return SendREDPayloadType(&payloadType); 589 } 590 virtual int32_t SendREDPayloadType(int8_t* payload_type) const = 0; 591 /* 592 * Store the audio level in dBov for header-extension-for-audio-level- 593 * indication. 594 * This API shall be called before transmision of an RTP packet to ensure 595 * that the |level| part of the extended RTP header is updated. 596 * 597 * return -1 on failure else 0. 598 */ 599 virtual int32_t SetAudioLevel(uint8_t level_dBov) = 0; 600 601 /************************************************************************** 602 * 603 * Video 604 * 605 ***************************************************************************/ 606 607 /* 608 * Set the target send bitrate 609 */ 610 virtual void SetTargetSendBitrate(uint32_t bitrate_bps) = 0; 611 612 /* 613 * Turn on/off generic FEC 614 */ 615 virtual void SetGenericFECStatus(bool enable, 616 uint8_t payload_type_red, 617 uint8_t payload_type_fec) = 0; 618 619 /* 620 * Get generic FEC setting 621 */ 622 // DEPRECATED. Use GenericFECStatus below that takes output parameters 623 // by pointers instead of by references. 624 // TODO(danilchap): Remove this when all callers have been updated. GenericFECStatus(bool & enable,uint8_t & payloadTypeRED,uint8_t & payloadTypeFEC)625 void GenericFECStatus(bool& enable, // NOLINT 626 uint8_t& payloadTypeRED, // NOLINT 627 uint8_t& payloadTypeFEC) { // NOLINT 628 GenericFECStatus(&enable, &payloadTypeRED, &payloadTypeFEC); 629 } 630 virtual void GenericFECStatus(bool* enable, 631 uint8_t* payload_type_red, 632 uint8_t* payload_type_fec) = 0; 633 634 virtual int32_t SetFecParameters( 635 const FecProtectionParams* delta_params, 636 const FecProtectionParams* key_params) = 0; 637 638 /* 639 * Set method for requestion a new key frame 640 * 641 * return -1 on failure else 0 642 */ 643 virtual int32_t SetKeyFrameRequestMethod(KeyFrameRequestMethod method) = 0; 644 645 /* 646 * send a request for a keyframe 647 * 648 * return -1 on failure else 0 649 */ 650 virtual int32_t RequestKeyFrame() = 0; 651 }; 652 } // namespace webrtc 653 #endif // WEBRTC_MODULES_RTP_RTCP_INCLUDE_RTP_RTCP_H_ 654