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     // Gets the canonical name (CNAME) parameter for RTCP reports on a
    175     // specific |channel|.
    176     virtual int GetRTCP_CNAME(int channel, char cName[256]) = 0;
    177 
    178     // Gets the canonical name (CNAME) parameter for incoming RTCP reports
    179     // on a specific channel.
    180     virtual int GetRemoteRTCP_CNAME(int channel, char cName[256]) = 0;
    181 
    182     // Gets RTCP data from incoming RTCP Sender Reports.
    183     virtual int GetRemoteRTCPData(
    184         int channel, unsigned int& NTPHigh, unsigned int& NTPLow,
    185         unsigned int& timestamp, unsigned int& playoutTimestamp,
    186         unsigned int* jitter = NULL, unsigned short* fractionLost = NULL) = 0;
    187 
    188     // Gets RTP statistics for a specific |channel|.
    189     virtual int GetRTPStatistics(
    190         int channel, unsigned int& averageJitterMs, unsigned int& maxJitterMs,
    191         unsigned int& discardedPackets) = 0;
    192 
    193     // Gets RTCP statistics for a specific |channel|.
    194     virtual int GetRTCPStatistics(int channel, CallStatistics& stats) = 0;
    195 
    196     // Gets the report block parts of the last received RTCP Sender Report (SR),
    197     // or RTCP Receiver Report (RR) on a specified |channel|. Each vector
    198     // element also contains the SSRC of the sender in addition to a report
    199     // block.
    200     virtual int GetRemoteRTCPReportBlocks(
    201         int channel, std::vector<ReportBlock>* receive_blocks) = 0;
    202 
    203     // Sets the Redundant Coding (RED) status on a specific |channel|.
    204     // TODO(minyue): Make SetREDStatus() pure virtual when fakewebrtcvoiceengine
    205     // in talk is ready.
    206     virtual int SetREDStatus(
    207         int channel, bool enable, int redPayloadtype = -1) { return -1; }
    208 
    209     // Gets the RED status on a specific |channel|.
    210     // TODO(minyue): Make GetREDStatus() pure virtual when fakewebrtcvoiceengine
    211     // in talk is ready.
    212     virtual int GetREDStatus(
    213         int channel, bool& enabled, int& redPayloadtype) { return -1; }
    214 
    215     // Sets the Forward Error Correction (FEC) status on a specific |channel|.
    216     // TODO(minyue): Remove SetFECStatus() when SetFECStatus() is replaced by
    217     // SetREDStatus() in fakewebrtcvoiceengine.
    218     virtual int SetFECStatus(
    219         int channel, bool enable, int redPayloadtype = -1) {
    220       return SetREDStatus(channel, enable, redPayloadtype);
    221     };
    222 
    223     // Gets the FEC status on a specific |channel|.
    224     // TODO(minyue): Remove GetFECStatus() when GetFECStatus() is replaced by
    225     // GetREDStatus() in fakewebrtcvoiceengine.
    226     virtual int GetFECStatus(
    227         int channel, bool& enabled, int& redPayloadtype) {
    228       return SetREDStatus(channel, enabled, redPayloadtype);
    229     }
    230 
    231     // This function enables Negative Acknowledgment (NACK) using RTCP,
    232     // implemented based on RFC 4585. NACK retransmits RTP packets if lost on
    233     // the network. This creates a lossless transport at the expense of delay.
    234     // If using NACK, NACK should be enabled on both endpoints in a call.
    235     virtual int SetNACKStatus(int channel,
    236                               bool enable,
    237                               int maxNoPackets) = 0;
    238 
    239     // Enables capturing of RTP packets to a binary file on a specific
    240     // |channel| and for a given |direction|. The file can later be replayed
    241     // using e.g. RTP Tools rtpplay since the binary file format is
    242     // compatible with the rtpdump format.
    243     virtual int StartRTPDump(
    244         int channel, const char fileNameUTF8[1024],
    245         RTPDirections direction = kRtpIncoming) = 0;
    246 
    247     // Disables capturing of RTP packets to a binary file on a specific
    248     // |channel| and for a given |direction|.
    249     virtual int StopRTPDump(
    250         int channel, RTPDirections direction = kRtpIncoming) = 0;
    251 
    252     // Gets the the current RTP capturing state for the specified
    253     // |channel| and |direction|.
    254     virtual int RTPDumpIsActive(
    255         int channel, RTPDirections direction = kRtpIncoming) = 0;
    256 
    257     // Sets video engine channel to receive incoming audio packets for
    258     // aggregated bandwidth estimation. Takes ownership of the ViENetwork
    259     // interface.
    260     virtual int SetVideoEngineBWETarget(int channel, ViENetwork* vie_network,
    261                                         int video_channel) {
    262       return 0;
    263     }
    264 
    265     // Will be removed. Don't use.
    266     virtual int RegisterRTPObserver(int channel,
    267             VoERTPObserver& observer) { return -1; };
    268     virtual int DeRegisterRTPObserver(int channel) { return -1; };
    269     virtual int RegisterRTCPObserver(
    270             int channel, VoERTCPObserver& observer) { return -1; };
    271     virtual int DeRegisterRTCPObserver(int channel) { return -1; };
    272     virtual int GetRemoteCSRCs(int channel,
    273             unsigned int arrCSRC[15]) { return -1; };
    274     virtual int InsertExtraRTPPacket(
    275             int channel, unsigned char payloadType, bool markerBit,
    276             const char* payloadData, unsigned short payloadSize) { return -1; };
    277     virtual int GetRemoteRTCPSenderInfo(
    278             int channel, SenderInfo* sender_info) { return -1; };
    279     virtual int SendApplicationDefinedRTCPPacket(
    280             int channel, unsigned char subType, unsigned int name,
    281             const char* data, unsigned short dataLengthInBytes) { return -1; };
    282     virtual int GetLastRemoteTimeStamp(int channel,
    283             uint32_t* lastRemoteTimeStamp) { return -1; };
    284 
    285 protected:
    286     VoERTP_RTCP() {}
    287     virtual ~VoERTP_RTCP() {}
    288 };
    289 
    290 }  // namespace webrtc
    291 
    292 #endif  // #ifndef WEBRTC_VOICE_ENGINE_VOE_RTP_RTCP_H
    293