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
  31 // This enumerator sets the RTCP mode.
  32 enum ViERTCPMode {
  33   kRtcpNone = 0,
  34   kRtcpCompound_RFC4585 = 1,
  35   kRtcpNonCompound_RFC5506 = 2
  36 };
  37
  38 // This enumerator describes the key frame request mode.
  39 enum ViEKeyFrameRequestMethod {
  40   kViEKeyFrameRequestNone = 0,
  41   kViEKeyFrameRequestPliRtcp = 1,
  42   kViEKeyFrameRequestFirRtp = 2,
  43   kViEKeyFrameRequestFirRtcp = 3
  44 };
  45
  46 enum StreamType {
  47   kViEStreamTypeNormal = 0,  // Normal media stream
  48   kViEStreamTypeRtx = 1  // Retransmission media stream
  49 };
  50
  51 enum BandwidthEstimationMode {
  52   kViEMultiStreamEstimation,
  53   kViESingleStreamEstimation
  54 };
  55
  56 // This class declares an abstract interface for a user defined observer. It is
  57 // up to the VideoEngine user to implement a derived class which implements the
  58 // observer class. The observer is registered using RegisterRTPObserver() and
  59 // deregistered using DeregisterRTPObserver().
  60 class WEBRTC_DLLEXPORT ViERTPObserver {
  61  public:
  62   // This method is called if SSRC of the incoming stream is changed.
  63   virtual void IncomingSSRCChanged(const int video_channel,
  64                                    const unsigned int SSRC) = 0;
  65
  66   // This method is called if a field in CSRC changes or if the number of
  67   // CSRCs changes.
  68   virtual void IncomingCSRCChanged(const int video_channel,
  69                                    const unsigned int CSRC,
  70                                    const bool added) = 0;
  71  protected:
  72   virtual ~ViERTPObserver() {}
  73 };
  74
  75 // This class declares an abstract interface for a user defined observer. It is
  76 // up to the VideoEngine user to implement a derived class which implements the
  77 // observer class. The observer is registered using RegisterRTCPObserver() and
  78 // deregistered using DeregisterRTCPObserver().
  79
  80 class WEBRTC_DLLEXPORT ViERTCPObserver {
  81  public:
  82   // This method is called if a application-defined RTCP packet has been
  83   // received.
  84   virtual void OnApplicationDataReceived(
  85       const int video_channel,
  86       const unsigned char sub_type,
  87       const unsigned int name,
  88       const char* data,
  89       const unsigned short data_length_in_bytes) = 0;
  90  protected:
  91   virtual ~ViERTCPObserver() {}
  92 };
  93
  94 class WEBRTC_DLLEXPORT ViERTP_RTCP {
  95  public:
  96   enum { KDefaultDeltaTransmitTimeSeconds = 15 };
  97   enum { KMaxRTCPCNameLength = 256 };
  98
  99   // Factory for the ViERTP_RTCP sub‐API and increases an internal reference
 100   // counter if successful. Returns NULL if the API is not supported or if
 101   // construction fails.
 102   static ViERTP_RTCP* GetInterface(VideoEngine* video_engine);
 103
 104   // Releases the ViERTP_RTCP sub-API and decreases an internal reference
 105   // counter. Returns the new reference count. This value should be zero
 106   // for all sub-API:s before the VideoEngine object can be safely deleted.
 107   virtual int Release() = 0;
 108
 109   // This function enables you to specify the RTP synchronization source
 110   // identifier (SSRC) explicitly.
 111   virtual int SetLocalSSRC(const int video_channel,
 112                            const unsigned int SSRC,
 113                            const StreamType usage = kViEStreamTypeNormal,
 114                            const unsigned char simulcast_idx = 0) = 0;
 115
 116   // This function gets the SSRC for the outgoing RTP stream for the specified
 117   // channel.
 118   virtual int GetLocalSSRC(const int video_channel,
 119                            unsigned int& SSRC) const = 0;
 120
 121   // This function map a incoming SSRC to a StreamType so that the engine
 122   // can know which is the normal stream and which is the RTX
 123   virtual int SetRemoteSSRCType(const int video_channel,
 124                                 const StreamType usage,
 125                                 const unsigned int SSRC) const = 0;
 126
 127   // This function gets the SSRC for the incoming RTP stream for the specified
 128   // channel.
 129   virtual int GetRemoteSSRC(const int video_channel,
 130                             unsigned int& SSRC) const = 0;
 131
 132   // This function returns the CSRCs of the incoming RTP packets.
 133   virtual int GetRemoteCSRCs(const int video_channel,
 134                              unsigned int CSRCs[kRtpCsrcSize]) const = 0;
 135
 136   // This sets a specific payload type for the RTX stream. Note that this
 137   // doesn't enable RTX, SetLocalSSRC must still be called to enable RTX.
 138   virtual int SetRtxSendPayloadType(const int video_channel,
 139                                     const uint8_t payload_type) = 0;
 140
 141   virtual int SetRtxReceivePayloadType(const int video_channel,
 142                                        const uint8_t payload_type) = 0;
 143
 144   // This function enables manual initialization of the sequence number. The
 145   // start sequence number is normally a random number.
 146   virtual int SetStartSequenceNumber(const int video_channel,
 147                                      unsigned short sequence_number) = 0;
 148
 149   // This function sets the RTCP status for the specified channel.
 150   // Default mode is kRtcpCompound_RFC4585.
 151   virtual int SetRTCPStatus(const int video_channel,
 152                             const ViERTCPMode rtcp_mode) = 0;
 153
 154   // This function gets the RTCP status for the specified channel.
 155   virtual int GetRTCPStatus(const int video_channel,
 156                             ViERTCPMode& rtcp_mode) const = 0;
 157
 158   // This function sets the RTCP canonical name (CNAME) for the RTCP reports
 159   // on a specific channel.
 160   virtual int SetRTCPCName(const int video_channel,
 161                            const char rtcp_cname[KMaxRTCPCNameLength]) = 0;
 162
 163   // This function gets the RTCP canonical name (CNAME) for the RTCP reports
 164   // sent the specified channel.
 165   virtual int GetRTCPCName(const int video_channel,
 166                            char rtcp_cname[KMaxRTCPCNameLength]) const = 0;
 167
 168   // This function gets the RTCP canonical name (CNAME) for the RTCP reports
 169   // received on the specified channel.
 170   virtual int GetRemoteRTCPCName(
 171       const int video_channel,
 172       char rtcp_cname[KMaxRTCPCNameLength]) const = 0;
 173
 174   // This function sends an RTCP APP packet on a specific channel.
 175   virtual int SendApplicationDefinedRTCPPacket(
 176       const int video_channel,
 177       const unsigned char sub_type,
 178       unsigned int name,
 179       const char* data,
 180       unsigned short data_length_in_bytes) = 0;
 181
 182   // This function enables Negative Acknowledgment (NACK) using RTCP,
 183   // implemented based on RFC 4585. NACK retransmits RTP packets if lost on
 184   // the network. This creates a lossless transport at the expense of delay.
 185   // If using NACK, NACK should be enabled on both endpoints in a call.
 186   virtual int SetNACKStatus(const int video_channel, const bool enable) = 0;
 187
 188   // This function enables Forward Error Correction (FEC) using RTCP,
 189   // implemented based on RFC 5109, to improve packet loss robustness. Extra
 190   // FEC packets are sent together with the usual media packets, hence
 191   // part of the bitrate will be used for FEC packets.
 192   virtual int SetFECStatus(const int video_channel,
 193                            const bool enable,
 194                            const unsigned char payload_typeRED,
 195                            const unsigned char payload_typeFEC) = 0;
 196
 197   // This function enables hybrid Negative Acknowledgment using RTCP
 198   // and Forward Error Correction (FEC) implemented based on RFC 5109,
 199   // to improve packet loss robustness. Extra
 200   // FEC packets are sent together with the usual media packets, hence will
 201   // part of the bitrate be used for FEC packets.
 202   // The hybrid mode will choose between nack only, fec only and both based on
 203   // network conditions. When both are applied, only packets that were not
 204   // recovered by the FEC will be nacked.
 205   virtual int SetHybridNACKFECStatus(const int video_channel,
 206                                      const bool enable,
 207                                      const unsigned char payload_typeRED,
 208                                      const unsigned char payload_typeFEC) = 0;
 209
 210   // Sets send side support for delayed video buffering (actual delay will
 211   // be exhibited on the receiver side).
 212   // Target delay should be set to zero for real-time mode.
 213   virtual int SetSenderBufferingMode(int video_channel,
 214                                      int target_delay_ms) = 0;
 215   // Sets receive side support for delayed video buffering. Target delay should
 216   // be set to zero for real-time mode.
 217   virtual int SetReceiverBufferingMode(int video_channel,
 218                                        int target_delay_ms) = 0;
 219
 220   // This function enables RTCP key frame requests.
 221   virtual int SetKeyFrameRequestMethod(
 222     const int video_channel, const ViEKeyFrameRequestMethod method) = 0;
 223
 224   // This function enables signaling of temporary bitrate constraints using
 225   // RTCP, implemented based on RFC4585.
 226   virtual int SetTMMBRStatus(const int video_channel, const bool enable) = 0;
 227
 228   // Enables and disables REMB packets for this channel. |sender| indicates
 229   // this channel is encoding, |receiver| tells the bitrate estimate for
 230   // this channel should be included in the REMB packet.
 231   virtual int SetRembStatus(int video_channel,
 232                             bool sender,
 233                             bool receiver) = 0;
 234
 235   // Enables RTP timestamp extension offset described in RFC 5450. This call
 236   // must be done before ViECodec::SetSendCodec is called.
 237   virtual int SetSendTimestampOffsetStatus(int video_channel,
 238                                            bool enable,
 239                                            int id) = 0;
 240
 241   virtual int SetReceiveTimestampOffsetStatus(int video_channel,
 242                                               bool enable,
 243                                               int id) = 0;
 244
 245   // Enables RTP absolute send time header extension. This call must be done
 246   // before ViECodec::SetSendCodec is called.
 247   virtual int SetSendAbsoluteSendTimeStatus(int video_channel,
 248                                             bool enable,
 249                                             int id) = 0;
 250
 251   // When enabled for a channel, *all* channels on the same transport will be
 252   // expected to include the absolute send time header extension.
 253   virtual int SetReceiveAbsoluteSendTimeStatus(int video_channel,
 254                                                bool enable,
 255                                                int id) = 0;
 256
 257   // Enables transmission smoothening, i.e. packets belonging to the same frame
 258   // will be sent over a longer period of time instead of sending them
 259   // back-to-back.
 260   virtual int SetTransmissionSmoothingStatus(int video_channel,
 261                                              bool enable) = 0;
 262
 263   // This function returns our locally created statistics of the received RTP
 264   // stream.
 265   virtual int GetReceivedRTCPStatistics(
 266       const int video_channel,
 267       unsigned short& fraction_lost,
 268       unsigned int& cumulative_lost,
 269       unsigned int& extended_max,
 270       unsigned int& jitter,
 271       int& rtt_ms) const = 0;
 272
 273   // This function returns statistics reported by the remote client in a RTCP
 274   // packet.
 275   virtual int GetSentRTCPStatistics(const int video_channel,
 276                                     unsigned short& fraction_lost,
 277                                     unsigned int& cumulative_lost,
 278                                     unsigned int& extended_max,
 279                                     unsigned int& jitter,
 280                                     int& rtt_ms) const = 0;
 281
 282   // The function gets statistics from the sent and received RTP streams.
 283   virtual int GetRTPStatistics(const int video_channel,
 284                                unsigned int& bytes_sent,
 285                                unsigned int& packets_sent,
 286                                unsigned int& bytes_received,
 287                                unsigned int& packets_received) const = 0;
 288
 289   // The function gets bandwidth usage statistics from the sent RTP streams in
 290   // bits/s.
 291   virtual int GetBandwidthUsage(const int video_channel,
 292                                 unsigned int& total_bitrate_sent,
 293                                 unsigned int& video_bitrate_sent,
 294                                 unsigned int& fec_bitrate_sent,
 295                                 unsigned int& nackBitrateSent) const = 0;
 296
 297   // This function gets the send-side estimated bandwidth available for video,
 298   // including overhead, in bits/s.
 299   virtual int GetEstimatedSendBandwidth(
 300       const int video_channel,
 301       unsigned int* estimated_bandwidth) const = 0;
 302
 303   // This function gets the receive-side estimated bandwidth available for
 304   // video, including overhead, in bits/s. |estimated_bandwidth| is 0 if there
 305   // is no valid estimate.
 306   virtual int GetEstimatedReceiveBandwidth(
 307       const int video_channel,
 308       unsigned int* estimated_bandwidth) const = 0;
 309
 310   // This function enables capturing of RTP packets to a binary file on a
 311   // specific channel and for a given direction. The file can later be
 312   // replayed using e.g. RTP Tools rtpplay since the binary file format is
 313   // compatible with the rtpdump format.
 314   virtual int StartRTPDump(const int video_channel,
 315                            const char file_nameUTF8[1024],
 316                            RTPDirections direction) = 0;
 317
 318   // This function disables capturing of RTP packets to a binary file on a
 319   // specific channel and for a given direction.
 320   virtual int StopRTPDump(const int video_channel,
 321                           RTPDirections direction) = 0;
 322
 323   // Registers an instance of a user implementation of the ViERTPObserver.
 324   virtual int RegisterRTPObserver(const int video_channel,
 325                                   ViERTPObserver& observer) = 0;
 326
 327   // Removes a registered instance of ViERTPObserver.
 328   virtual int DeregisterRTPObserver(const int video_channel) = 0;
 329
 330   // Registers an instance of a user implementation of the ViERTCPObserver.
 331   virtual int RegisterRTCPObserver(const int video_channel,
 332                                    ViERTCPObserver& observer) = 0;
 333
 334   // Removes a registered instance of ViERTCPObserver.
 335   virtual int DeregisterRTCPObserver(const int video_channel) = 0;
 336
 337  protected:
 338   ViERTP_RTCP() {}
 339   virtual ~ViERTP_RTCP() {}
 340 };
 341
 342 }  // namespace webrtc
 343
 344 #endif  // WEBRTC_VIDEO_ENGINE_INCLUDE_VIE_RTP_RTCP_H_