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 ViENetwork;
48class VoiceEngine;
49
50// VoERTPObserver
51class WEBRTC_DLLEXPORT VoERTPObserver
52{
53public:
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
60protected:
61    virtual ~VoERTPObserver() {}
62};
63
64// VoERTCPObserver
65class WEBRTC_DLLEXPORT VoERTCPObserver
66{
67public:
68    virtual void OnApplicationDataReceived(
69        int channel, unsigned char subType,
70        unsigned int name, const unsigned char* data,
71        unsigned short dataLengthInBytes) = 0;
72
73protected:
74    virtual ~VoERTCPObserver() {}
75};
76
77// CallStatistics
78struct 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.
95struct 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.
104struct 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
116class WEBRTC_DLLEXPORT VoERTP_RTCP
117{
118public:
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
287protected:
288    VoERTP_RTCP() {}
289    virtual ~VoERTP_RTCP() {}
290};
291
292}  // namespace webrtc
293
294#endif  // #ifndef WEBRTC_VOICE_ENGINE_VOE_RTP_RTCP_H
295