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
45namespace webrtc {
46
47class VoiceEngine;
48
49// VoERTPObserver
50class WEBRTC_DLLEXPORT VoERTPObserver {
51 public:
52  virtual void OnIncomingCSRCChanged(int channel,
53                                     unsigned int CSRC,
54                                     bool added) = 0;
55
56  virtual void OnIncomingSSRCChanged(int channel, unsigned int SSRC) = 0;
57
58 protected:
59  virtual ~VoERTPObserver() {}
60};
61
62// CallStatistics
63struct CallStatistics {
64  unsigned short fractionLost;
65  unsigned int cumulativeLost;
66  unsigned int extendedMax;
67  unsigned int jitterSamples;
68  int64_t rttMs;
69  size_t bytesSent;
70  int packetsSent;
71  size_t bytesReceived;
72  int packetsReceived;
73  // The capture ntp time (in local timebase) of the first played out audio
74  // frame.
75  int64_t capture_start_ntp_time_ms_;
76};
77
78// See section 6.4.1 in http://www.ietf.org/rfc/rfc3550.txt for details.
79struct SenderInfo {
80  uint32_t NTP_timestamp_high;
81  uint32_t NTP_timestamp_low;
82  uint32_t RTP_timestamp;
83  uint32_t sender_packet_count;
84  uint32_t sender_octet_count;
85};
86
87// See section 6.4.2 in http://www.ietf.org/rfc/rfc3550.txt for details.
88struct ReportBlock {
89  uint32_t sender_SSRC;  // SSRC of sender
90  uint32_t source_SSRC;
91  uint8_t fraction_lost;
92  uint32_t cumulative_num_packets_lost;
93  uint32_t extended_highest_sequence_number;
94  uint32_t interarrival_jitter;
95  uint32_t last_SR_timestamp;
96  uint32_t delay_since_last_SR;
97};
98
99// VoERTP_RTCP
100class WEBRTC_DLLEXPORT VoERTP_RTCP {
101 public:
102  // Factory for the VoERTP_RTCP sub-API. Increases an internal
103  // reference counter if successful. Returns NULL if the API is not
104  // supported or if construction fails.
105  static VoERTP_RTCP* GetInterface(VoiceEngine* voiceEngine);
106
107  // Releases the VoERTP_RTCP sub-API and decreases an internal
108  // reference counter. Returns the new reference count. This value should
109  // be zero for all sub-API:s before the VoiceEngine object can be safely
110  // deleted.
111  virtual int Release() = 0;
112
113  // Sets the local RTP synchronization source identifier (SSRC) explicitly.
114  virtual int SetLocalSSRC(int channel, unsigned int ssrc) = 0;
115
116  // Gets the local RTP SSRC of a specified |channel|.
117  virtual int GetLocalSSRC(int channel, unsigned int& ssrc) = 0;
118
119  // Gets the SSRC of the incoming RTP packets.
120  virtual int GetRemoteSSRC(int channel, unsigned int& ssrc) = 0;
121
122  // Sets the status of rtp-audio-level-indication on a specific |channel|.
123  virtual int SetSendAudioLevelIndicationStatus(int channel,
124                                                bool enable,
125                                                unsigned char id = 1) = 0;
126
127  // Sets the status of receiving rtp-audio-level-indication on a specific
128  // |channel|.
129  virtual int SetReceiveAudioLevelIndicationStatus(int channel,
130                                                   bool enable,
131                                                   unsigned char id = 1) {
132    // TODO(wu): Remove default implementation once talk is updated.
133    return 0;
134  }
135
136  // Sets the status of sending absolute sender time on a specific |channel|.
137  virtual int SetSendAbsoluteSenderTimeStatus(int channel,
138                                              bool enable,
139                                              unsigned char id) = 0;
140
141  // Sets status of receiving absolute sender time on a specific |channel|.
142  virtual int SetReceiveAbsoluteSenderTimeStatus(int channel,
143                                                 bool enable,
144                                                 unsigned char id) = 0;
145
146  // Sets the RTCP status on a specific |channel|.
147  virtual int SetRTCPStatus(int channel, bool enable) = 0;
148
149  // Gets the RTCP status on a specific |channel|.
150  virtual int GetRTCPStatus(int channel, bool& enabled) = 0;
151
152  // Sets the canonical name (CNAME) parameter for RTCP reports on a
153  // specific |channel|.
154  virtual int SetRTCP_CNAME(int channel, const char cName[256]) = 0;
155
156  // TODO(holmer): Remove this API once it has been removed from
157  // fakewebrtcvoiceengine.h.
158  virtual int GetRTCP_CNAME(int channel, char cName[256]) { return -1; }
159
160  // Gets the canonical name (CNAME) parameter for incoming RTCP reports
161  // on a specific channel.
162  virtual int GetRemoteRTCP_CNAME(int channel, char cName[256]) = 0;
163
164  // Gets RTCP data from incoming RTCP Sender Reports.
165  virtual int GetRemoteRTCPData(int channel,
166                                unsigned int& NTPHigh,
167                                unsigned int& NTPLow,
168                                unsigned int& timestamp,
169                                unsigned int& playoutTimestamp,
170                                unsigned int* jitter = NULL,
171                                unsigned short* fractionLost = NULL) = 0;
172
173  // Gets RTP statistics for a specific |channel|.
174  virtual int GetRTPStatistics(int channel,
175                               unsigned int& averageJitterMs,
176                               unsigned int& maxJitterMs,
177                               unsigned int& discardedPackets) = 0;
178
179  // Gets RTCP statistics for a specific |channel|.
180  virtual int GetRTCPStatistics(int channel, CallStatistics& stats) = 0;
181
182  // Gets the report block parts of the last received RTCP Sender Report (SR),
183  // or RTCP Receiver Report (RR) on a specified |channel|. Each vector
184  // element also contains the SSRC of the sender in addition to a report
185  // block.
186  virtual int GetRemoteRTCPReportBlocks(
187      int channel,
188      std::vector<ReportBlock>* receive_blocks) = 0;
189
190  // Sets the Redundant Coding (RED) status on a specific |channel|.
191  // TODO(minyue): Make SetREDStatus() pure virtual when fakewebrtcvoiceengine
192  // in talk is ready.
193  virtual int SetREDStatus(int channel, bool enable, int redPayloadtype = -1) {
194    return -1;
195  }
196
197  // Gets the RED status on a specific |channel|.
198  // TODO(minyue): Make GetREDStatus() pure virtual when fakewebrtcvoiceengine
199  // in talk is ready.
200  virtual int GetREDStatus(int channel, bool& enabled, int& redPayloadtype) {
201    return -1;
202  }
203
204  // This function enables Negative Acknowledgment (NACK) using RTCP,
205  // implemented based on RFC 4585. NACK retransmits RTP packets if lost on
206  // the network. This creates a lossless transport at the expense of delay.
207  // If using NACK, NACK should be enabled on both endpoints in a call.
208  virtual int SetNACKStatus(int channel, bool enable, int maxNoPackets) = 0;
209
210 protected:
211  VoERTP_RTCP() {}
212  virtual ~VoERTP_RTCP() {}
213};
214
215}  // namespace webrtc
216
217#endif  // #ifndef WEBRTC_VOICE_ENGINE_VOE_RTP_RTCP_H
218