src/third_party/webrtc/video_engine/include/vie_rtp_rtcp.h

   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 // This sub-API supports the following functionalities:
  12 //  - Callbacks for RTP and RTCP events such as modified SSRC or CSRC.
  13 //  - SSRC handling.
  14 //  - Transmission of RTCP reports.
  15 //  - Obtaining RTCP data from incoming RTCP sender reports.
  16 //  - RTP and RTCP statistics (jitter, packet loss, RTT etc.).
  17 //  - Forward Error Correction (FEC).
  18 //  - Writing RTP and RTCP packets to binary files for off‐line analysis of the
  19 //    call quality.
  20 //  - Inserting extra RTP packets into active audio stream.
  21
  22 #ifndef WEBRTC_VIDEO_ENGINE_INCLUDE_VIE_RTP_RTCP_H_
  23 #define WEBRTC_VIDEO_ENGINE_INCLUDE_VIE_RTP_RTCP_H_
  24
  25 #include "webrtc/common_types.h"
  26
  27 namespace webrtc {
  28
  29 class VideoEngine;
  30 struct ReceiveBandwidthEstimatorStats;
  31
  32 // This enumerator sets the RTCP mode.
  33 enum ViERTCPMode {
  34   kRtcpNone = 0,
  35   kRtcpCompound_RFC4585 = 1,
  36   kRtcpNonCompound_RFC5506 = 2
  37 };
  38
  39 // This enumerator describes the key frame request mode.
  40 enum ViEKeyFrameRequestMethod {
  41   kViEKeyFrameRequestNone = 0,
  42   kViEKeyFrameRequestPliRtcp = 1,
  43   kViEKeyFrameRequestFirRtp = 2,
  44   kViEKeyFrameRequestFirRtcp = 3
  45 };
  46
  47 enum StreamType {
  48   kViEStreamTypeNormal = 0,  // Normal media stream
  49   kViEStreamTypeRtx = 1  // Retransmission media stream
  50 };
  51
  52 enum BandwidthEstimationMode {
  53   kViEMultiStreamEstimation,
  54   kViESingleStreamEstimation
  55 };
  56
  57 // This class declares an abstract interface for a user defined observer. It is
  58 // up to the VideoEngine user to implement a derived class which implements the
  59 // observer class. The observer is registered using RegisterRTPObserver() and
  60 // deregistered using DeregisterRTPObserver().
  61 class WEBRTC_DLLEXPORT ViERTPObserver {
  62  public:
  63   // This method is called if SSRC of the incoming stream is changed.
  64   virtual void IncomingSSRCChanged(const int video_channel,
  65                                    const unsigned int SSRC) = 0;
  66
  67   // This method is called if a field in CSRC changes or if the number of
  68   // CSRCs changes.
  69   virtual void IncomingCSRCChanged(const int video_channel,
  70                                    const unsigned int CSRC,
  71                                    const bool added) = 0;
  72  protected:
  73   virtual ~ViERTPObserver() {}
  74 };
  75
  76 // This class declares an abstract interface for a user defined observer. It is
  77 // up to the VideoEngine user to implement a derived class which implements the
  78 // observer class. The observer is registered using RegisterRTCPObserver() and
  79 // deregistered using DeregisterRTCPObserver().
  80
  81 class WEBRTC_DLLEXPORT ViERTCPObserver {
  82  public:
  83   // This method is called if a application-defined RTCP packet has been
  84   // received.
  85   virtual void OnApplicationDataReceived(
  86       const int video_channel,
  87       const unsigned char sub_type,
  88       const unsigned int name,
  89       const char* data,
  90       const unsigned short data_length_in_bytes) = 0;
  91  protected:
  92   virtual ~ViERTCPObserver() {}
  93 };
  94
  95 class WEBRTC_DLLEXPORT ViERTP_RTCP {
  96  public:
  97   enum { KDefaultDeltaTransmitTimeSeconds = 15 };
  98   enum { KMaxRTCPCNameLength = 256 };
  99
 100   // Factory for the ViERTP_RTCP sub‐API and increases an internal reference
 101   // counter if successful. Returns NULL if the API is not supported or if
 102   // construction fails.
 103   static ViERTP_RTCP* GetInterface(VideoEngine* video_engine);
 104
 105   // Releases the ViERTP_RTCP sub-API and decreases an internal reference
 106   // counter. Returns the new reference count. This value should be zero
 107   // for all sub-API:s before the VideoEngine object can be safely deleted.
 108   virtual int Release() = 0;
 109
 110   // This function enables you to specify the RTP synchronization source
 111   // identifier (SSRC) explicitly.
 112   virtual int SetLocalSSRC(const int video_channel,
 113                            const unsigned int SSRC,
 114                            const StreamType usage = kViEStreamTypeNormal,
 115                            const unsigned char simulcast_idx = 0) = 0;
 116
 117   // This function gets the SSRC for the outgoing RTP stream for the specified
 118   // channel.
 119   virtual int GetLocalSSRC(const int video_channel,
 120                            unsigned int& SSRC) const = 0;
 121
 122   // This function map a incoming SSRC to a StreamType so that the engine
 123   // can know which is the normal stream and which is the RTX
 124   virtual int SetRemoteSSRCType(const int video_channel,
 125                                 const StreamType usage,
 126                                 const unsigned int SSRC) const = 0;
 127
 128   // This function gets the SSRC for the incoming RTP stream for the specified
 129   // channel.
 130   virtual int GetRemoteSSRC(const int video_channel,
 131                             unsigned int& SSRC) const = 0;
 132
 133   // This function returns the CSRCs of the incoming RTP packets.
 134   virtual int GetRemoteCSRCs(const int video_channel,
 135                              unsigned int CSRCs[kRtpCsrcSize]) const = 0;
 136
 137   // This sets a specific payload type for the RTX stream. Note that this
 138   // doesn't enable RTX, SetLocalSSRC must still be called to enable RTX.
 139   virtual int SetRtxSendPayloadType(const int video_channel,
 140                                     const uint8_t payload_type) = 0;
 141
 142   virtual int SetRtxReceivePayloadType(const int video_channel,
 143                                        const uint8_t payload_type) = 0;
 144
 145   // This function enables manual initialization of the sequence number. The
 146   // start sequence number is normally a random number.
 147   virtual int SetStartSequenceNumber(const int video_channel,
 148                                      unsigned short sequence_number) = 0;
 149
 150   // This function sets the RTCP status for the specified channel.
 151   // Default mode is kRtcpCompound_RFC4585.
 152   virtual int SetRTCPStatus(const int video_channel,
 153                             const ViERTCPMode rtcp_mode) = 0;
 154
 155   // This function gets the RTCP status for the specified channel.
 156   virtual int GetRTCPStatus(const int video_channel,
 157                             ViERTCPMode& rtcp_mode) const = 0;
 158
 159   // This function sets the RTCP canonical name (CNAME) for the RTCP reports
 160   // on a specific channel.
 161   virtual int SetRTCPCName(const int video_channel,
 162                            const char rtcp_cname[KMaxRTCPCNameLength]) = 0;
 163
 164   // This function gets the RTCP canonical name (CNAME) for the RTCP reports
 165   // sent the specified channel.
 166   virtual int GetRTCPCName(const int video_channel,
 167                            char rtcp_cname[KMaxRTCPCNameLength]) const = 0;
 168
 169   // This function gets the RTCP canonical name (CNAME) for the RTCP reports
 170   // received on the specified channel.
 171   virtual int GetRemoteRTCPCName(
 172       const int video_channel,
 173       char rtcp_cname[KMaxRTCPCNameLength]) const = 0;
 174
 175   // This function sends an RTCP APP packet on a specific channel.
 176   virtual int SendApplicationDefinedRTCPPacket(
 177       const int video_channel,
 178       const unsigned char sub_type,
 179       unsigned int name,
 180       const char* data,
 181       unsigned short data_length_in_bytes) = 0;
 182
 183   // This function enables Negative Acknowledgment (NACK) using RTCP,
 184   // implemented based on RFC 4585. NACK retransmits RTP packets if lost on
 185   // the network. This creates a lossless transport at the expense of delay.
 186   // If using NACK, NACK should be enabled on both endpoints in a call.
 187   virtual int SetNACKStatus(const int video_channel, const bool enable) = 0;
 188
 189   // This function enables Forward Error Correction (FEC) using RTCP,
 190   // implemented based on RFC 5109, to improve packet loss robustness. Extra
 191   // FEC packets are sent together with the usual media packets, hence
 192   // part of the bitrate will be used for FEC packets.
 193   virtual int SetFECStatus(const int video_channel,
 194                            const bool enable,
 195                            const unsigned char payload_typeRED,
 196                            const unsigned char payload_typeFEC) = 0;
 197
 198   // This function enables hybrid Negative Acknowledgment using RTCP
 199   // and Forward Error Correction (FEC) implemented based on RFC 5109,
 200   // to improve packet loss robustness. Extra
 201   // FEC packets are sent together with the usual media packets, hence will
 202   // part of the bitrate be used for FEC packets.
 203   // The hybrid mode will choose between nack only, fec only and both based on
 204   // network conditions. When both are applied, only packets that were not
 205   // recovered by the FEC will be nacked.
 206   virtual int SetHybridNACKFECStatus(const int video_channel,
 207                                      const bool enable,
 208                                      const unsigned char payload_typeRED,
 209                                      const unsigned char payload_typeFEC) = 0;
 210
 211   // Sets send side support for delayed video buffering (actual delay will
 212   // be exhibited on the receiver side).
 213   // Target delay should be set to zero for real-time mode.
 214   virtual int SetSenderBufferingMode(int video_channel,
 215                                      int target_delay_ms) = 0;
 216   // Sets receive side support for delayed video buffering. Target delay should
 217   // be set to zero for real-time mode.
 218   virtual int SetReceiverBufferingMode(int video_channel,
 219                                        int target_delay_ms) = 0;
 220
 221   // This function enables RTCP key frame requests.
 222   virtual int SetKeyFrameRequestMethod(
 223     const int video_channel, const ViEKeyFrameRequestMethod method) = 0;
 224
 225   // This function enables signaling of temporary bitrate constraints using
 226   // RTCP, implemented based on RFC4585.
 227   virtual int SetTMMBRStatus(const int video_channel, const bool enable) = 0;
 228
 229   // Enables and disables REMB packets for this channel. |sender| indicates
 230   // this channel is encoding, |receiver| tells the bitrate estimate for
 231   // this channel should be included in the REMB packet.
 232   virtual int SetRembStatus(int video_channel,
 233                             bool sender,
 234                             bool receiver) = 0;
 235
 236   // Enables RTP timestamp extension offset described in RFC 5450. This call
 237   // must be done before ViECodec::SetSendCodec is called.
 238   virtual int SetSendTimestampOffsetStatus(int video_channel,
 239                                            bool enable,
 240                                            int id) = 0;
 241
 242   virtual int SetReceiveTimestampOffsetStatus(int video_channel,
 243                                               bool enable,
 244                                               int id) = 0;
 245
 246   // Enables RTP absolute send time header extension. This call must be done
 247   // before ViECodec::SetSendCodec is called.
 248   virtual int SetSendAbsoluteSendTimeStatus(int video_channel,
 249                                             bool enable,
 250                                             int id) = 0;
 251
 252   // When enabled for a channel, *all* channels on the same transport will be
 253   // expected to include the absolute send time header extension.
 254   virtual int SetReceiveAbsoluteSendTimeStatus(int video_channel,
 255                                                bool enable,
 256                                                int id) = 0;
 257
 258   // Enables/disables RTCP Receiver Reference Time Report Block extension/
 259   // DLRR Report Block extension (RFC 3611).
 260   // TODO(asapersson): Remove default implementation.
 261   virtual int SetRtcpXrRrtrStatus(int video_channel, bool enable) { return -1; }
 262
 263   // Enables transmission smoothening, i.e. packets belonging to the same frame
 264   // will be sent over a longer period of time instead of sending them
 265   // back-to-back.
 266   virtual int SetTransmissionSmoothingStatus(int video_channel,
 267                                              bool enable) = 0;
 268
 269   // This function returns our locally created statistics of the received RTP
 270   // stream.
 271   virtual int GetReceiveChannelRtcpStatistics(const int video_channel,
 272                                               RtcpStatistics& basic_stats,
 273                                               int& rtt_ms) const = 0;
 274
 275   // This function returns statistics reported by the remote client in a RTCP
 276   // packet.
 277   virtual int GetSendChannelRtcpStatistics(const int video_channel,
 278                                            RtcpStatistics& basic_stats,
 279                                            int& rtt_ms) const = 0;
 280
 281   // TODO(sprang): Temporary hacks to prevent libjingle build from failing,
 282   // remove when libjingle has been lifted to support webrtc issue 2589
 283   virtual int GetReceivedRTCPStatistics(const int video_channel,
 284                                 unsigned short& fraction_lost,
 285                                 unsigned int& cumulative_lost,
 286                                 unsigned int& extended_max,
 287                                 unsigned int& jitter,
 288                                 int& rtt_ms) const {
 289     RtcpStatistics stats;
 290     int ret_code = GetReceiveChannelRtcpStatistics(video_channel,
 291                                              stats,
 292                                              rtt_ms);
 293     fraction_lost = stats.fraction_lost;
 294     cumulative_lost = stats.cumulative_lost;
 295     extended_max = stats.extended_max_sequence_number;
 296     jitter = stats.jitter;
 297     return ret_code;
 298   }
 299   virtual int GetSentRTCPStatistics(const int video_channel,
 300                             unsigned short& fraction_lost,
 301                             unsigned int& cumulative_lost,
 302                             unsigned int& extended_max,
 303                             unsigned int& jitter,
 304                             int& rtt_ms) const {
 305     RtcpStatistics stats;
 306     int ret_code = GetSendChannelRtcpStatistics(video_channel,
 307                                                 stats,
 308                                                 rtt_ms);
 309     fraction_lost = stats.fraction_lost;
 310     cumulative_lost = stats.cumulative_lost;
 311     extended_max = stats.extended_max_sequence_number;
 312     jitter = stats.jitter;
 313     return ret_code;
 314   }
 315
 316
 317   virtual int RegisterSendChannelRtcpStatisticsCallback(
 318       int video_channel, RtcpStatisticsCallback* callback) = 0;
 319
 320   virtual int DeregisterSendChannelRtcpStatisticsCallback(
 321       int video_channel, RtcpStatisticsCallback* callback) = 0;
 322
 323   virtual int RegisterReceiveChannelRtcpStatisticsCallback(
 324       int video_channel, RtcpStatisticsCallback* callback) = 0;
 325
 326   virtual int DeregisterReceiveChannelRtcpStatisticsCallback(
 327       int video_channel, RtcpStatisticsCallback* callback) = 0;
 328
 329   // The function gets statistics from the sent and received RTP streams.
 330   virtual int GetRtpStatistics(const int video_channel,
 331                                StreamDataCounters& sent,
 332                                StreamDataCounters& received) const = 0;
 333
 334   // TODO(sprang): Temporary hacks to prevent libjingle build from failing,
 335   // remove when libjingle has been lifted to support webrtc issue 2589
 336   virtual int GetRTPStatistics(const int video_channel,
 337                        unsigned int& bytes_sent,
 338                        unsigned int& packets_sent,
 339                        unsigned int& bytes_received,
 340                        unsigned int& packets_received) const {
 341     StreamDataCounters sent;
 342     StreamDataCounters received;
 343     int ret_code = GetRtpStatistics(video_channel, sent, received);
 344     bytes_sent = sent.bytes;
 345     packets_sent = sent.packets;
 346     bytes_received = received.bytes;
 347     packets_received = received.packets;
 348     return ret_code;
 349   }
 350
 351   virtual int RegisterSendChannelRtpStatisticsCallback(
 352       int video_channel, StreamDataCountersCallback* callback) = 0;
 353
 354   virtual int DeregisterSendChannelRtpStatisticsCallback(
 355       int video_channel, StreamDataCountersCallback* callback) = 0;
 356
 357   virtual int RegisterReceiveChannelRtpStatisticsCallback(
 358       int video_channel, StreamDataCountersCallback* callback) = 0;
 359
 360   virtual int DeregisterReceiveChannelRtpStatisticsCallback(
 361       int video_channel, StreamDataCountersCallback* callback) = 0;
 362
 363   // The function gets bandwidth usage statistics from the sent RTP streams in
 364   // bits/s.
 365   virtual int GetBandwidthUsage(const int video_channel,
 366                                 unsigned int& total_bitrate_sent,
 367                                 unsigned int& video_bitrate_sent,
 368                                 unsigned int& fec_bitrate_sent,
 369                                 unsigned int& nackBitrateSent) const = 0;
 370
 371   // (De)Register an observer, called whenever the send bitrate is updated
 372   virtual int RegisterSendBitrateObserver(
 373       int video_channel,
 374       BitrateStatisticsObserver* observer) = 0;
 375
 376   virtual int DeregisterSendBitrateObserver(
 377       int video_channel,
 378       BitrateStatisticsObserver* observer) = 0;
 379
 380   // This function gets the send-side estimated bandwidth available for video,
 381   // including overhead, in bits/s.
 382   virtual int GetEstimatedSendBandwidth(
 383       const int video_channel,
 384       unsigned int* estimated_bandwidth) const = 0;
 385
 386   // This function gets the receive-side estimated bandwidth available for
 387   // video, including overhead, in bits/s. |estimated_bandwidth| is 0 if there
 388   // is no valid estimate.
 389   virtual int GetEstimatedReceiveBandwidth(
 390       const int video_channel,
 391       unsigned int* estimated_bandwidth) const = 0;
 392
 393   // This function gets the receive-side bandwidth esitmator statistics.
 394   // TODO(jiayl): remove the default impl when libjingle's FakeWebRtcVideoEngine
 395   // is updated.
 396   virtual int GetReceiveBandwidthEstimatorStats(
 397       const int video_channel,
 398       ReceiveBandwidthEstimatorStats* output) const { return -1; }
 399
 400   // This function enables capturing of RTP packets to a binary file on a
 401   // specific channel and for a given direction. The file can later be
 402   // replayed using e.g. RTP Tools rtpplay since the binary file format is
 403   // compatible with the rtpdump format.
 404   virtual int StartRTPDump(const int video_channel,
 405                            const char file_nameUTF8[1024],
 406                            RTPDirections direction) = 0;
 407
 408   // This function disables capturing of RTP packets to a binary file on a
 409   // specific channel and for a given direction.
 410   virtual int StopRTPDump(const int video_channel,
 411                           RTPDirections direction) = 0;
 412
 413   // Registers an instance of a user implementation of the ViERTPObserver.
 414   virtual int RegisterRTPObserver(const int video_channel,
 415                                   ViERTPObserver& observer) = 0;
 416
 417   // Removes a registered instance of ViERTPObserver.
 418   virtual int DeregisterRTPObserver(const int video_channel) = 0;
 419
 420   // Registers an instance of a user implementation of the ViERTCPObserver.
 421   virtual int RegisterRTCPObserver(const int video_channel,
 422                                    ViERTCPObserver& observer) = 0;
 423
 424   // Removes a registered instance of ViERTCPObserver.
 425   virtual int DeregisterRTCPObserver(const int video_channel) = 0;
 426
 427   // Registers and instance of a user implementation of ViEFrameCountObserver
 428   virtual int RegisterSendFrameCountObserver(
 429       int video_channel, FrameCountObserver* observer) = 0;
 430
 431   // Removes a registered instance of a ViEFrameCountObserver
 432   virtual int DeregisterSendFrameCountObserver(
 433       int video_channel, FrameCountObserver* observer) = 0;
 434
 435  protected:
 436   virtual ~ViERTP_RTCP() {}
 437 };
 438
 439 }  // namespace webrtc
 440
 441 #endif  // WEBRTC_VIDEO_ENGINE_INCLUDE_VIE_RTP_RTCP_H_