Home | History | Annotate | Download | only in include
      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 //
     13 //  - Callbacks for RTP and RTCP events such as modified SSRC or CSRC.
     14 //  - SSRC handling.
     15 //  - Transmission of RTCP sender reports.
     16 //  - Obtaining RTCP data from incoming RTCP sender reports.
     17 //  - RTP and RTCP statistics (jitter, packet loss, RTT etc.).
     18 //  - Redundant Coding (RED)
     19 //  - Writing RTP and RTCP packets to binary files for off-line analysis of
     20 //    the call quality.
     21 //
     22 // Usage example, omitting error checking:
     23 //
     24 //  using namespace webrtc;
     25 //  VoiceEngine* voe = VoiceEngine::Create();
     26 //  VoEBase* base = VoEBase::GetInterface(voe);
     27 //  VoERTP_RTCP* rtp_rtcp  = VoERTP_RTCP::GetInterface(voe);
     28 //  base->Init();
     29 //  int ch = base->CreateChannel();
     30 //  ...
     31 //  rtp_rtcp->SetLocalSSRC(ch, 12345);
     32 //  ...
     33 //  base->DeleteChannel(ch);
     34 //  base->Terminate();
     35 //  base->Release();
     36 //  rtp_rtcp->Release();
     37 //  VoiceEngine::Delete(voe);
     38 //
     39 #ifndef WEBRTC_VOICE_ENGINE_VOE_RTP_RTCP_H
     40 #define WEBRTC_VOICE_ENGINE_VOE_RTP_RTCP_H
     41 
     42 #include <vector>
     43 #include "webrtc/common_types.h"
     44 
     45 namespace webrtc {
     46 
     47 class ViENetwork;
     48 class VoiceEngine;
     49 
     50 // VoERTPObserver
     51 class WEBRTC_DLLEXPORT VoERTPObserver
     52 {
     53 public:
     54     virtual void OnIncomingCSRCChanged(
     55         int channel, unsigned int CSRC, bool added) = 0;
     56 
     57     virtual void OnIncomingSSRCChanged(
     58         int channel, unsigned int SSRC) = 0;
     59 
     60 protected:
     61     virtual ~VoERTPObserver() {}
     62 };
     63 
     64 // VoERTCPObserver
     65 class WEBRTC_DLLEXPORT VoERTCPObserver
     66 {
     67 public:
     68     virtual void OnApplicationDataReceived(
     69         int channel, unsigned char subType,
     70         unsigned int name, const unsigned char* data,
     71         unsigned short dataLengthInBytes) = 0;
     72 
     73 protected:
     74     virtual ~VoERTCPObserver() {}
     75 };
     76 
     77 // CallStatistics
     78 struct CallStatistics
     79 {
     80     unsigned short fractionLost;
     81     unsigned int cumulativeLost;
     82     unsigned int extendedMax;
     83     unsigned int jitterSamples;
     84     int rttMs;
     85     int bytesSent;
     86     int packetsSent;
     87     int bytesReceived;
     88     int packetsReceived;
     89     // The capture ntp time (in local timebase) of the first played out audio
     90     // frame.
     91     int64_t capture_start_ntp_time_ms_;
     92 };
     93 
     94 // See section 6.4.1 in http://www.ietf.org/rfc/rfc3550.txt for details.
     95 struct SenderInfo {
     96   uint32_t NTP_timestamp_high;
     97   uint32_t NTP_timestamp_low;
     98   uint32_t RTP_timestamp;
     99   uint32_t sender_packet_count;
    100   uint32_t sender_octet_count;
    101 };
    102 
    103 // See section 6.4.2 in http://www.ietf.org/rfc/rfc3550.txt for details.
    104 struct ReportBlock {
    105   uint32_t sender_SSRC; // SSRC of sender
    106   uint32_t source_SSRC;
    107   uint8_t fraction_lost;
    108   uint32_t cumulative_num_packets_lost;
    109   uint32_t extended_highest_sequence_number;
    110   uint32_t interarrival_jitter;
    111   uint32_t last_SR_timestamp;
    112   uint32_t delay_since_last_SR;
    113 };
    114 
    115 // VoERTP_RTCP
    116 class WEBRTC_DLLEXPORT VoERTP_RTCP
    117 {
    118 public:
    119 
    120     // Factory for the VoERTP_RTCP sub-API. Increases an internal
    121     // reference counter if successful. Returns NULL if the API is not
    122     // supported or if construction fails.
    123     static VoERTP_RTCP* GetInterface(VoiceEngine* voiceEngine);
    124 
    125     // Releases the VoERTP_RTCP sub-API and decreases an internal
    126     // reference counter. Returns the new reference count. This value should
    127     // be zero for all sub-API:s before the VoiceEngine object can be safely
    128     // deleted.
    129     virtual int Release() = 0;
    130 
    131     // Sets the local RTP synchronization source identifier (SSRC) explicitly.
    132     virtual int SetLocalSSRC(int channel, unsigned int ssrc) = 0;
    133 
    134     // Gets the local RTP SSRC of a specified |channel|.
    135     virtual int GetLocalSSRC(int channel, unsigned int& ssrc) = 0;
    136 
    137     // Gets the SSRC of the incoming RTP packets.
    138     virtual int GetRemoteSSRC(int channel, unsigned int& ssrc) = 0;
    139 
    140     // Sets the status of rtp-audio-level-indication on a specific |channel|.
    141     virtual int SetSendAudioLevelIndicationStatus(int channel,
    142                                                   bool enable,
    143                                                   unsigned char id = 1) = 0;
    144 
    145     // Sets the status of receiving rtp-audio-level-indication on a specific
    146     // |channel|.
    147     virtual int SetReceiveAudioLevelIndicationStatus(int channel,
    148                                                      bool enable,
    149                                                      unsigned char id = 1) {
    150       // TODO(wu): Remove default implementation once talk is updated.
    151       return 0;
    152     }
    153 
    154     // Sets the status of sending absolute sender time on a specific |channel|.
    155     virtual int SetSendAbsoluteSenderTimeStatus(int channel,
    156                                                 bool enable,
    157                                                 unsigned char id) = 0;
    158 
    159     // Sets status of receiving absolute sender time on a specific |channel|.
    160     virtual int SetReceiveAbsoluteSenderTimeStatus(int channel,
    161                                                    bool enable,
    162                                                    unsigned char id) = 0;
    163 
    164     // Sets the RTCP status on a specific |channel|.
    165     virtual int SetRTCPStatus(int channel, bool enable) = 0;
    166 
    167     // Gets the RTCP status on a specific |channel|.
    168     virtual int GetRTCPStatus(int channel, bool& enabled) = 0;
    169 
    170     // Sets the canonical name (CNAME) parameter for RTCP reports on a
    171     // specific |channel|.
    172     virtual int SetRTCP_CNAME(int channel, const char cName[256]) = 0;
    173 
    174     // TODO(holmer): Remove this API once it has been removed from
    175     // fakewebrtcvoiceengine.h.
    176     virtual int GetRTCP_CNAME(int channel, char cName[256]) {
    177       return -1;
    178     }
    179 
    180     // Gets the canonical name (CNAME) parameter for incoming RTCP reports
    181     // on a specific channel.
    182     virtual int GetRemoteRTCP_CNAME(int channel, char cName[256]) = 0;
    183 
    184     // Gets RTCP data from incoming RTCP Sender Reports.
    185     virtual int GetRemoteRTCPData(
    186         int channel, unsigned int& NTPHigh, unsigned int& NTPLow,
    187         unsigned int& timestamp, unsigned int& playoutTimestamp,
    188         unsigned int* jitter = NULL, unsigned short* fractionLost = NULL) = 0;
    189 
    190     // Gets RTP statistics for a specific |channel|.
    191     virtual int GetRTPStatistics(
    192         int channel, unsigned int& averageJitterMs, unsigned int& maxJitterMs,
    193         unsigned int& discardedPackets) = 0;
    194 
    195     // Gets RTCP statistics for a specific |channel|.
    196     virtual int GetRTCPStatistics(int channel, CallStatistics& stats) = 0;
    197 
    198     // Gets the report block parts of the last received RTCP Sender Report (SR),
    199     // or RTCP Receiver Report (RR) on a specified |channel|. Each vector
    200     // element also contains the SSRC of the sender in addition to a report
    201     // block.
    202     virtual int GetRemoteRTCPReportBlocks(
    203         int channel, std::vector<ReportBlock>* receive_blocks) = 0;
    204 
    205     // Sets the Redundant Coding (RED) status on a specific |channel|.
    206     // TODO(minyue): Make SetREDStatus() pure virtual when fakewebrtcvoiceengine
    207     // in talk is ready.
    208     virtual int SetREDStatus(
    209         int channel, bool enable, int redPayloadtype = -1) { return -1; }
    210 
    211     // Gets the RED status on a specific |channel|.
    212     // TODO(minyue): Make GetREDStatus() pure virtual when fakewebrtcvoiceengine
    213     // in talk is ready.
    214     virtual int GetREDStatus(
    215         int channel, bool& enabled, int& redPayloadtype) { return -1; }
    216 
    217     // Sets the Forward Error Correction (FEC) status on a specific |channel|.
    218     // TODO(minyue): Remove SetFECStatus() when SetFECStatus() is replaced by
    219     // SetREDStatus() in fakewebrtcvoiceengine.
    220     virtual int SetFECStatus(
    221         int channel, bool enable, int redPayloadtype = -1) {
    222       return SetREDStatus(channel, enable, redPayloadtype);
    223     };
    224 
    225     // Gets the FEC status on a specific |channel|.
    226     // TODO(minyue): Remove GetFECStatus() when GetFECStatus() is replaced by
    227     // GetREDStatus() in fakewebrtcvoiceengine.
    228     virtual int GetFECStatus(
    229         int channel, bool& enabled, int& redPayloadtype) {
    230       return SetREDStatus(channel, enabled, redPayloadtype);
    231     }
    232 
    233     // This function enables Negative Acknowledgment (NACK) using RTCP,
    234     // implemented based on RFC 4585. NACK retransmits RTP packets if lost on
    235     // the network. This creates a lossless transport at the expense of delay.
    236     // If using NACK, NACK should be enabled on both endpoints in a call.
    237     virtual int SetNACKStatus(int channel,
    238                               bool enable,
    239                               int maxNoPackets) = 0;
    240 
    241     // Enables capturing of RTP packets to a binary file on a specific
    242     // |channel| and for a given |direction|. The file can later be replayed
    243     // using e.g. RTP Tools rtpplay since the binary file format is
    244     // compatible with the rtpdump format.
    245     virtual int StartRTPDump(
    246         int channel, const char fileNameUTF8[1024],
    247         RTPDirections direction = kRtpIncoming) = 0;
    248 
    249     // Disables capturing of RTP packets to a binary file on a specific
    250     // |channel| and for a given |direction|.
    251     virtual int StopRTPDump(
    252         int channel, RTPDirections direction = kRtpIncoming) = 0;
    253 
    254     // Gets the the current RTP capturing state for the specified
    255     // |channel| and |direction|.
    256     virtual int RTPDumpIsActive(
    257         int channel, RTPDirections direction = kRtpIncoming) = 0;
    258 
    259     // Sets video engine channel to receive incoming audio packets for
    260     // aggregated bandwidth estimation. Takes ownership of the ViENetwork
    261     // interface.
    262     virtual int SetVideoEngineBWETarget(int channel, ViENetwork* vie_network,
    263                                         int video_channel) {
    264       return 0;
    265     }
    266 
    267     // Will be removed. Don't use.
    268     virtual int RegisterRTPObserver(int channel,
    269             VoERTPObserver& observer) { return -1; };
    270     virtual int DeRegisterRTPObserver(int channel) { return -1; };
    271     virtual int RegisterRTCPObserver(
    272             int channel, VoERTCPObserver& observer) { return -1; };
    273     virtual int DeRegisterRTCPObserver(int channel) { return -1; };
    274     virtual int GetRemoteCSRCs(int channel,
    275             unsigned int arrCSRC[15]) { return -1; };
    276     virtual int InsertExtraRTPPacket(
    277             int channel, unsigned char payloadType, bool markerBit,
    278             const char* payloadData, unsigned short payloadSize) { return -1; };
    279     virtual int GetRemoteRTCPSenderInfo(
    280             int channel, SenderInfo* sender_info) { return -1; };
    281     virtual int SendApplicationDefinedRTCPPacket(
    282             int channel, unsigned char subType, unsigned int name,
    283             const char* data, unsigned short dataLengthInBytes) { return -1; };
    284     virtual int GetLastRemoteTimeStamp(int channel,
    285             uint32_t* lastRemoteTimeStamp) { return -1; };
    286 
    287 protected:
    288     VoERTP_RTCP() {}
    289     virtual ~VoERTP_RTCP() {}
    290 };
    291 
    292 }  // namespace webrtc
    293 
    294 #endif  // #ifndef WEBRTC_VOICE_ENGINE_VOE_RTP_RTCP_H
    295