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/disables RTCP Receiver Reference Time Report Block extension/
 258   // DLRR Report Block extension (RFC 3611).
 259   // TODO(asapersson): Remove default implementation.
 260   virtual int SetRtcpXrRrtrStatus(int video_channel, bool enable) { return -1; }
 261
 262   // Enables transmission smoothening, i.e. packets belonging to the same frame
 263   // will be sent over a longer period of time instead of sending them
 264   // back-to-back.
 265   virtual int SetTransmissionSmoothingStatus(int video_channel,
 266                                              bool enable) = 0;
 267
 268   // This function returns our locally created statistics of the received RTP
 269   // stream.
 270   virtual int GetReceiveChannelRtcpStatistics(const int video_channel,
 271                                               RtcpStatistics& basic_stats,
 272                                               int& rtt_ms) const = 0;
 273
 274   // This function returns statistics reported by the remote client in a RTCP
 275   // packet.
 276   virtual int GetSendChannelRtcpStatistics(const int video_channel,
 277                                            RtcpStatistics& basic_stats,
 278                                            int& rtt_ms) const = 0;
 279
 280   // TODO(sprang): Temporary hacks to prevent libjingle build from failing,
 281   // remove when libjingle has been lifted to support webrtc issue 2589
 282   virtual int GetReceivedRTCPStatistics(const int video_channel,
 283                                 unsigned short& fraction_lost,
 284                                 unsigned int& cumulative_lost,
 285                                 unsigned int& extended_max,
 286                                 unsigned int& jitter,
 287                                 int& rtt_ms) const {
 288     RtcpStatistics stats;
 289     int ret_code = GetReceiveChannelRtcpStatistics(video_channel,
 290                                              stats,
 291                                              rtt_ms);
 292     fraction_lost = stats.fraction_lost;
 293     cumulative_lost = stats.cumulative_lost;
 294     extended_max = stats.extended_max_sequence_number;
 295     jitter = stats.jitter;
 296     return ret_code;
 297   }
 298   virtual int GetSentRTCPStatistics(const int video_channel,
 299                             unsigned short& fraction_lost,
 300                             unsigned int& cumulative_lost,
 301                             unsigned int& extended_max,
 302                             unsigned int& jitter,
 303                             int& rtt_ms) const {
 304     RtcpStatistics stats;
 305     int ret_code = GetSendChannelRtcpStatistics(video_channel,
 306                                                 stats,
 307                                                 rtt_ms);
 308     fraction_lost = stats.fraction_lost;
 309     cumulative_lost = stats.cumulative_lost;
 310     extended_max = stats.extended_max_sequence_number;
 311     jitter = stats.jitter;
 312     return ret_code;
 313   }
 314
 315
 316   virtual int RegisterSendChannelRtcpStatisticsCallback(
 317       int video_channel, RtcpStatisticsCallback* callback) = 0;
 318
 319   virtual int DeregisterSendChannelRtcpStatisticsCallback(
 320       int video_channel, RtcpStatisticsCallback* callback) = 0;
 321
 322   virtual int RegisterReceiveChannelRtcpStatisticsCallback(
 323       int video_channel, RtcpStatisticsCallback* callback) = 0;
 324
 325   virtual int DeregisterReceiveChannelRtcpStatisticsCallback(
 326       int video_channel, RtcpStatisticsCallback* callback) = 0;
 327
 328   // The function gets statistics from the sent and received RTP streams.
 329   virtual int GetRtpStatistics(const int video_channel,
 330                                StreamDataCounters& sent,
 331                                StreamDataCounters& received) const = 0;
 332
 333   // TODO(sprang): Temporary hacks to prevent libjingle build from failing,
 334   // remove when libjingle has been lifted to support webrtc issue 2589
 335   virtual int GetRTPStatistics(const int video_channel,
 336                        unsigned int& bytes_sent,
 337                        unsigned int& packets_sent,
 338                        unsigned int& bytes_received,
 339                        unsigned int& packets_received) const {
 340     StreamDataCounters sent;
 341     StreamDataCounters received;
 342     int ret_code = GetRtpStatistics(video_channel, sent, received);
 343     bytes_sent = sent.bytes;
 344     packets_sent = sent.packets;
 345     bytes_received = received.bytes;
 346     packets_received = received.packets;
 347     return ret_code;
 348   }
 349
 350   virtual int RegisterSendChannelRtpStatisticsCallback(
 351       int video_channel, StreamDataCountersCallback* callback) = 0;
 352
 353   virtual int DeregisterSendChannelRtpStatisticsCallback(
 354       int video_channel, StreamDataCountersCallback* callback) = 0;
 355
 356   virtual int RegisterReceiveChannelRtpStatisticsCallback(
 357       int video_channel, StreamDataCountersCallback* callback) = 0;
 358
 359   virtual int DeregisterReceiveChannelRtpStatisticsCallback(
 360       int video_channel, StreamDataCountersCallback* callback) = 0;
 361
 362   // The function gets bandwidth usage statistics from the sent RTP streams in
 363   // bits/s.
 364   virtual int GetBandwidthUsage(const int video_channel,
 365                                 unsigned int& total_bitrate_sent,
 366                                 unsigned int& video_bitrate_sent,
 367                                 unsigned int& fec_bitrate_sent,
 368                                 unsigned int& nackBitrateSent) const = 0;
 369
 370   // (De)Register an observer, called whenever the send bitrate is updated
 371   virtual int RegisterSendBitrateObserver(
 372       int video_channel,
 373       BitrateStatisticsObserver* observer) = 0;
 374
 375   virtual int DeregisterSendBitrateObserver(
 376       int video_channel,
 377       BitrateStatisticsObserver* observer) = 0;
 378
 379   // This function gets the send-side estimated bandwidth available for video,
 380   // including overhead, in bits/s.
 381   virtual int GetEstimatedSendBandwidth(
 382       const int video_channel,
 383       unsigned int* estimated_bandwidth) const = 0;
 384
 385   // This function gets the receive-side estimated bandwidth available for
 386   // video, including overhead, in bits/s. |estimated_bandwidth| is 0 if there
 387   // is no valid estimate.
 388   virtual int GetEstimatedReceiveBandwidth(
 389       const int video_channel,
 390       unsigned int* estimated_bandwidth) const = 0;
 391
 392   // This function enables capturing of RTP packets to a binary file on a
 393   // specific channel and for a given direction. The file can later be
 394   // replayed using e.g. RTP Tools rtpplay since the binary file format is
 395   // compatible with the rtpdump format.
 396   virtual int StartRTPDump(const int video_channel,
 397                            const char file_nameUTF8[1024],
 398                            RTPDirections direction) = 0;
 399
 400   // This function disables capturing of RTP packets to a binary file on a
 401   // specific channel and for a given direction.
 402   virtual int StopRTPDump(const int video_channel,
 403                           RTPDirections direction) = 0;
 404
 405   // Registers an instance of a user implementation of the ViERTPObserver.
 406   virtual int RegisterRTPObserver(const int video_channel,
 407                                   ViERTPObserver& observer) = 0;
 408
 409   // Removes a registered instance of ViERTPObserver.
 410   virtual int DeregisterRTPObserver(const int video_channel) = 0;
 411
 412   // Registers an instance of a user implementation of the ViERTCPObserver.
 413   virtual int RegisterRTCPObserver(const int video_channel,
 414                                    ViERTCPObserver& observer) = 0;
 415
 416   // Removes a registered instance of ViERTCPObserver.
 417   virtual int DeregisterRTCPObserver(const int video_channel) = 0;
 418
 419   // Registers and instance of a user implementation of ViEFrameCountObserver
 420   virtual int RegisterSendFrameCountObserver(
 421       int video_channel, FrameCountObserver* observer) = 0;
 422
 423   // Removes a registered instance of a ViEFrameCountObserver
 424   virtual int DeregisterSendFrameCountObserver(
 425       int video_channel, FrameCountObserver* observer) = 0;
 426
 427  protected:
 428   virtual ~ViERTP_RTCP() {}
 429 };
 430
 431 }  // namespace webrtc
 432
 433 #endif  // WEBRTC_VIDEO_ENGINE_INCLUDE_VIE_RTP_RTCP_H_