Line data Source code
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 : #ifndef WEBRTC_MODULES_RTP_RTCP_INCLUDE_RTP_RTCP_H_
12 : #define WEBRTC_MODULES_RTP_RTCP_INCLUDE_RTP_RTCP_H_
13 :
14 : #include <set>
15 : #include <string>
16 : #include <utility>
17 : #include <vector>
18 :
19 : #include "webrtc/base/constructormagic.h"
20 : #include "webrtc/base/deprecation.h"
21 : #include "webrtc/base/optional.h"
22 : #include "webrtc/modules/include/module.h"
23 : #include "webrtc/modules/rtp_rtcp/include/flexfec_sender.h"
24 : #include "webrtc/modules/rtp_rtcp/include/rtp_rtcp_defines.h"
25 :
26 : namespace webrtc {
27 :
28 : // Forward declarations.
29 : class OverheadObserver;
30 : class RateLimiter;
31 : class ReceiveStatistics;
32 : class RemoteBitrateEstimator;
33 : class RtcEventLog;
34 : class RtpReceiver;
35 : class Transport;
36 : class VideoBitrateAllocationObserver;
37 :
38 : RTPExtensionType StringToRtpExtensionType(const std::string& extension);
39 :
40 : namespace rtcp {
41 : class TransportFeedback;
42 : }
43 :
44 0 : class RtpRtcp : public Module {
45 : public:
46 : struct Configuration {
47 : Configuration();
48 :
49 : // True for a audio version of the RTP/RTCP module object false will create
50 : // a video version.
51 : bool audio = false;
52 : bool receiver_only = false;
53 :
54 : // The clock to use to read time. If nullptr then system clock will be used.
55 : Clock* clock = nullptr;
56 :
57 : ReceiveStatistics* receive_statistics;
58 :
59 : // Transport object that will be called when packets are ready to be sent
60 : // out on the network.
61 : Transport* outgoing_transport = nullptr;
62 :
63 : // Called when the receiver request a intra frame.
64 : RtcpIntraFrameObserver* intra_frame_callback = nullptr;
65 :
66 : // Called when we receive a changed estimate from the receiver of out
67 : // stream.
68 : RtcpBandwidthObserver* bandwidth_callback = nullptr;
69 :
70 : TransportFeedbackObserver* transport_feedback_callback = nullptr;
71 : VideoBitrateAllocationObserver* bitrate_allocation_observer = nullptr;
72 : RtcpRttStats* rtt_stats = nullptr;
73 : RtcpPacketTypeCounterObserver* rtcp_packet_type_counter_observer = nullptr;
74 :
75 : // Estimates the bandwidth available for a set of streams from the same
76 : // client.
77 : RemoteBitrateEstimator* remote_bitrate_estimator = nullptr;
78 :
79 : // Spread any bursts of packets into smaller bursts to minimize packet loss.
80 : RtpPacketSender* paced_sender = nullptr;
81 :
82 : // Generate FlexFEC packets.
83 : // TODO(brandtr): Remove when FlexfecSender is wired up to PacedSender.
84 : FlexfecSender* flexfec_sender = nullptr;
85 :
86 : TransportSequenceNumberAllocator* transport_sequence_number_allocator =
87 : nullptr;
88 : BitrateStatisticsObserver* send_bitrate_observer = nullptr;
89 : FrameCountObserver* send_frame_count_observer = nullptr;
90 : SendSideDelayObserver* send_side_delay_observer = nullptr;
91 : RtcEventLog* event_log = nullptr;
92 : SendPacketObserver* send_packet_observer = nullptr;
93 : RateLimiter* retransmission_rate_limiter = nullptr;
94 : OverheadObserver* overhead_observer = nullptr;
95 :
96 : private:
97 : RTC_DISALLOW_COPY_AND_ASSIGN(Configuration);
98 : };
99 :
100 : // Create a RTP/RTCP module object using the system clock.
101 : // |configuration| - Configuration of the RTP/RTCP module.
102 : static RtpRtcp* CreateRtpRtcp(const RtpRtcp::Configuration& configuration);
103 :
104 : // **************************************************************************
105 : // Receiver functions
106 : // **************************************************************************
107 :
108 : virtual int32_t IncomingRtcpPacket(const uint8_t* incoming_packet,
109 : size_t incoming_packet_length) = 0;
110 :
111 : virtual void SetRemoteSSRC(uint32_t ssrc) = 0;
112 :
113 : // **************************************************************************
114 : // Sender
115 : // **************************************************************************
116 :
117 : // TODO(nisse): Deprecated. Kept temporarily, as an alias for the
118 : // new function which has slighly different semantics. Delete as
119 : // soon as known applications are updated.
120 0 : virtual int32_t SetMaxTransferUnit(uint16_t size) {
121 0 : SetMaxRtpPacketSize(size);
122 0 : return 0;
123 : }
124 :
125 : // Sets the maximum size of an RTP packet, including RTP headers.
126 : virtual void SetMaxRtpPacketSize(size_t size) = 0;
127 :
128 : // Returns max payload length.
129 : // Does not account for RTP headers and FEC/ULP/RED overhead (when FEC is
130 : // enabled).
131 : virtual size_t MaxPayloadSize() const = 0;
132 :
133 : // Returns max RTP packet size. Takes into account RTP headers and
134 : // FEC/ULP/RED overhead (when FEC is enabled).
135 : virtual size_t MaxRtpPacketSize() const = 0;
136 :
137 : // Sets codec name and payload type. Returns -1 on failure else 0.
138 : virtual int32_t RegisterSendPayload(const CodecInst& voice_codec) = 0;
139 :
140 : // Sets codec name and payload type. Return -1 on failure else 0.
141 : virtual int32_t RegisterSendPayload(const VideoCodec& video_codec) = 0;
142 :
143 : virtual void RegisterVideoSendPayload(int payload_type,
144 : const char* payload_name) = 0;
145 :
146 : // Unregisters a send payload.
147 : // |payload_type| - payload type of codec
148 : // Returns -1 on failure else 0.
149 : virtual int32_t DeRegisterSendPayload(int8_t payload_type) = 0;
150 :
151 : // (De)registers RTP header extension type and id.
152 : // Returns -1 on failure else 0.
153 : virtual int32_t RegisterSendRtpHeaderExtension(RTPExtensionType type,
154 : uint8_t id) = 0;
155 :
156 : virtual int32_t DeregisterSendRtpHeaderExtension(RTPExtensionType type) = 0;
157 :
158 : // Returns start timestamp.
159 : virtual uint32_t StartTimestamp() const = 0;
160 :
161 : // Sets start timestamp. Start timestamp is set to a random value if this
162 : // function is never called.
163 : virtual void SetStartTimestamp(uint32_t timestamp) = 0;
164 :
165 : // Returns SequenceNumber.
166 : virtual uint16_t SequenceNumber() const = 0;
167 :
168 : // Sets SequenceNumber, default is a random number.
169 : virtual void SetSequenceNumber(uint16_t seq) = 0;
170 :
171 : virtual void SetRtpState(const RtpState& rtp_state) = 0;
172 : virtual void SetRtxState(const RtpState& rtp_state) = 0;
173 : virtual RtpState GetRtpState() const = 0;
174 : virtual RtpState GetRtxState() const = 0;
175 :
176 : // Returns SSRC.
177 : virtual uint32_t SSRC() const = 0;
178 :
179 : // Set RID value for the RID header extension or RTCP SDES
180 : virtual int32_t SetRID(const char *rid) = 0;
181 :
182 : // Sets SSRC, default is a random number.
183 : virtual void SetSSRC(uint32_t ssrc) = 0;
184 :
185 : // Sets CSRC.
186 : // |csrcs| - vector of CSRCs
187 : virtual void SetCsrcs(const std::vector<uint32_t>& csrcs) = 0;
188 :
189 : // Turns on/off sending RTX (RFC 4588). The modes can be set as a combination
190 : // of values of the enumerator RtxMode.
191 : virtual void SetRtxSendStatus(int modes) = 0;
192 :
193 : // Returns status of sending RTX (RFC 4588). The returned value can be
194 : // a combination of values of the enumerator RtxMode.
195 : virtual int RtxSendStatus() const = 0;
196 :
197 : // Sets the SSRC to use when sending RTX packets. This doesn't enable RTX,
198 : // only the SSRC is set.
199 : virtual void SetRtxSsrc(uint32_t ssrc) = 0;
200 :
201 : // Sets the payload type to use when sending RTX packets. Note that this
202 : // doesn't enable RTX, only the payload type is set.
203 : virtual void SetRtxSendPayloadType(int payload_type,
204 : int associated_payload_type) = 0;
205 :
206 : // Returns the FlexFEC SSRC, if there is one.
207 : virtual rtc::Optional<uint32_t> FlexfecSsrc() const = 0;
208 :
209 : // Sets sending status. Sends kRtcpByeCode when going from true to false.
210 : // Returns -1 on failure else 0.
211 : virtual int32_t SetSendingStatus(bool sending) = 0;
212 :
213 : // Returns current sending status.
214 : virtual bool Sending() const = 0;
215 :
216 : // Starts/Stops media packets. On by default.
217 : virtual void SetSendingMediaStatus(bool sending) = 0;
218 :
219 : // Returns current media sending status.
220 : virtual bool SendingMedia() const = 0;
221 :
222 : // Returns current bitrate in Kbit/s.
223 : virtual void BitrateSent(uint32_t* total_rate,
224 : uint32_t* video_rate,
225 : uint32_t* fec_rate,
226 : uint32_t* nack_rate) const = 0;
227 :
228 : // Used by the codec module to deliver a video or audio frame for
229 : // packetization.
230 : // |frame_type| - type of frame to send
231 : // |payload_type| - payload type of frame to send
232 : // |timestamp| - timestamp of frame to send
233 : // |payload_data| - payload buffer of frame to send
234 : // |payload_size| - size of payload buffer to send
235 : // |fragmentation| - fragmentation offset data for fragmented frames such
236 : // as layers or RED
237 : // |transport_frame_id_out| - set to RTP timestamp.
238 : // Returns true on success.
239 : virtual bool SendOutgoingData(FrameType frame_type,
240 : int8_t payload_type,
241 : uint32_t timestamp,
242 : int64_t capture_time_ms,
243 : const uint8_t* payload_data,
244 : size_t payload_size,
245 : const RTPFragmentationHeader* fragmentation,
246 : const RTPVideoHeader* rtp_video_header,
247 : uint32_t* transport_frame_id_out) = 0;
248 :
249 : virtual bool TimeToSendPacket(uint32_t ssrc,
250 : uint16_t sequence_number,
251 : int64_t capture_time_ms,
252 : bool retransmission,
253 : int probe_cluster_id) = 0;
254 :
255 : virtual size_t TimeToSendPadding(size_t bytes, int probe_cluster_id) = 0;
256 :
257 : // Called on generation of new statistics after an RTP send.
258 : virtual void RegisterSendChannelRtpStatisticsCallback(
259 : StreamDataCountersCallback* callback) = 0;
260 : virtual StreamDataCountersCallback* GetSendChannelRtpStatisticsCallback()
261 : const = 0;
262 :
263 : // **************************************************************************
264 : // RTCP
265 : // **************************************************************************
266 :
267 : // Returns RTCP status.
268 : virtual RtcpMode RTCP() const = 0;
269 :
270 : // Sets RTCP status i.e on(compound or non-compound)/off.
271 : // |method| - RTCP method to use.
272 : virtual void SetRTCPStatus(RtcpMode method) = 0;
273 :
274 : // Sets RTCP CName (i.e unique identifier).
275 : // Returns -1 on failure else 0.
276 : virtual int32_t SetCNAME(const char* cname) = 0;
277 :
278 : // Returns remote CName.
279 : // Returns -1 on failure else 0.
280 : virtual int32_t RemoteCNAME(uint32_t remote_ssrc,
281 : char cname[RTCP_CNAME_SIZE]) const = 0;
282 :
283 : // Returns remote NTP.
284 : // Returns -1 on failure else 0.
285 : virtual int32_t RemoteNTP(uint32_t* received_ntp_secs,
286 : uint32_t* received_ntp_frac,
287 : uint32_t* rtcp_arrival_time_secs,
288 : uint32_t* rtcp_arrival_time_frac,
289 : uint32_t* rtcp_timestamp) const = 0;
290 :
291 : // Returns -1 on failure else 0.
292 : virtual int32_t AddMixedCNAME(uint32_t ssrc, const char* cname) = 0;
293 :
294 : // Returns -1 on failure else 0.
295 : virtual int32_t RemoveMixedCNAME(uint32_t ssrc) = 0;
296 :
297 : // Returns current RTT (round-trip time) estimate.
298 : // Returns -1 on failure else 0.
299 : virtual int32_t RTT(uint32_t remote_ssrc,
300 : int64_t* rtt,
301 : int64_t* avg_rtt,
302 : int64_t* min_rtt,
303 : int64_t* max_rtt) const = 0;
304 :
305 : // Forces a send of a RTCP packet. Periodic SR and RR are triggered via the
306 : // process function.
307 : // Returns -1 on failure else 0.
308 : virtual int32_t SendRTCP(RTCPPacketType rtcp_packet_type) = 0;
309 :
310 : // Forces a send of a RTCP packet with more than one packet type.
311 : // periodic SR and RR are triggered via the process function
312 : // Returns -1 on failure else 0.
313 : virtual int32_t SendCompoundRTCP(
314 : const std::set<RTCPPacketType>& rtcp_packet_types) = 0;
315 :
316 : // Notifies the sender about good state of the RTP receiver.
317 : virtual int32_t SendRTCPReferencePictureSelection(uint64_t picture_id) = 0;
318 :
319 : // Send a RTCP Slice Loss Indication (SLI).
320 : // |picture_id| - 6 least significant bits of picture_id.
321 : virtual int32_t SendRTCPSliceLossIndication(uint8_t picture_id) = 0;
322 :
323 : // Returns statistics of the amount of data sent.
324 : // Returns -1 on failure else 0.
325 : virtual int32_t DataCountersRTP(size_t* bytes_sent,
326 : uint32_t* packets_sent) const = 0;
327 :
328 : // Returns send statistics for the RTP and RTX stream.
329 : virtual void GetSendStreamDataCounters(
330 : StreamDataCounters* rtp_counters,
331 : StreamDataCounters* rtx_counters) const = 0;
332 :
333 : // Returns packet loss statistics for the RTP stream.
334 : virtual void GetRtpPacketLossStats(
335 : bool outgoing,
336 : uint32_t ssrc,
337 : struct RtpPacketLossStats* loss_stats) const = 0;
338 :
339 : // Returns received RTCP sender info.
340 : // Returns -1 on failure else 0.
341 : virtual int32_t RemoteRTCPStat(RTCPSenderInfo* sender_info) = 0;
342 :
343 : // Returns received RTCP report block.
344 : // Returns -1 on failure else 0.
345 : virtual int32_t RemoteRTCPStat(
346 : std::vector<RTCPReportBlock>* receive_blocks) const = 0;
347 :
348 : // (APP) Sets application specific data.
349 : // Returns -1 on failure else 0.
350 : virtual int32_t SetRTCPApplicationSpecificData(uint8_t sub_type,
351 : uint32_t name,
352 : const uint8_t* data,
353 : uint16_t length) = 0;
354 : // (XR) Sets VOIP metric.
355 : // Returns -1 on failure else 0.
356 : virtual int32_t SetRTCPVoIPMetrics(const RTCPVoIPMetric* VoIPMetric) = 0;
357 :
358 : // (XR) Sets Receiver Reference Time Report (RTTR) status.
359 : virtual void SetRtcpXrRrtrStatus(bool enable) = 0;
360 :
361 : // Returns current Receiver Reference Time Report (RTTR) status.
362 : virtual bool RtcpXrRrtrStatus() const = 0;
363 :
364 : // (REMB) Receiver Estimated Max Bitrate.
365 : virtual bool REMB() const = 0;
366 :
367 : virtual void SetREMBStatus(bool enable) = 0;
368 :
369 : virtual void SetREMBData(uint32_t bitrate,
370 : const std::vector<uint32_t>& ssrcs) = 0;
371 :
372 : // (TMMBR) Temporary Max Media Bit Rate
373 : virtual bool TMMBR() const = 0;
374 :
375 : virtual void SetTMMBRStatus(bool enable) = 0;
376 :
377 : // (NACK)
378 :
379 : // TODO(holmer): Propagate this API to VideoEngine.
380 : // Returns the currently configured selective retransmission settings.
381 : virtual int SelectiveRetransmissions() const = 0;
382 :
383 : // TODO(holmer): Propagate this API to VideoEngine.
384 : // Sets the selective retransmission settings, which will decide which
385 : // packets will be retransmitted if NACKed. Settings are constructed by
386 : // combining the constants in enum RetransmissionMode with bitwise OR.
387 : // All packets are retransmitted if kRetransmitAllPackets is set, while no
388 : // packets are retransmitted if kRetransmitOff is set.
389 : // By default all packets except FEC packets are retransmitted. For VP8
390 : // with temporal scalability only base layer packets are retransmitted.
391 : // Returns -1 on failure, otherwise 0.
392 : virtual int SetSelectiveRetransmissions(uint8_t settings) = 0;
393 :
394 : // Sends a Negative acknowledgement packet.
395 : // Returns -1 on failure else 0.
396 : // TODO(philipel): Deprecate this and start using SendNack instead, mostly
397 : // because we want a function that actually send NACK for the specified
398 : // packets.
399 : virtual int32_t SendNACK(const uint16_t* nack_list, uint16_t size) = 0;
400 :
401 : // Sends NACK for the packets specified.
402 : // Note: This assumes the caller keeps track of timing and doesn't rely on
403 : // the RTP module to do this.
404 : virtual void SendNack(const std::vector<uint16_t>& sequence_numbers) = 0;
405 :
406 : // Store the sent packets, needed to answer to a Negative acknowledgment
407 : // requests.
408 : virtual void SetStorePacketsStatus(bool enable, uint16_t numberToStore) = 0;
409 :
410 : // Returns true if the module is configured to store packets.
411 : virtual bool StorePackets() const = 0;
412 :
413 : // Called on receipt of RTCP report block from remote side.
414 : virtual void RegisterRtcpStatisticsCallback(
415 : RtcpStatisticsCallback* callback) = 0;
416 : virtual RtcpStatisticsCallback* GetRtcpStatisticsCallback() = 0;
417 : // BWE feedback packets.
418 : virtual bool SendFeedbackPacket(const rtcp::TransportFeedback& packet) = 0;
419 :
420 : virtual void SetVideoBitrateAllocation(const BitrateAllocation& bitrate) = 0;
421 :
422 : // **************************************************************************
423 : // Audio
424 : // **************************************************************************
425 :
426 : // This function is deprecated. It was previously used to determine when it
427 : // was time to send a DTMF packet in silence (CNG).
428 : // Returns -1 on failure else 0.
429 : RTC_DEPRECATED virtual int32_t SetAudioPacketSize(
430 : uint16_t packet_size_samples) = 0;
431 :
432 : // Sends a TelephoneEvent tone using RFC 2833 (4733).
433 : // Returns -1 on failure else 0.
434 : virtual int32_t SendTelephoneEventOutband(uint8_t key,
435 : uint16_t time_ms,
436 : uint8_t level) = 0;
437 :
438 : // Store the audio level in dBov for header-extension-for-audio-level-
439 : // indication.
440 : // This API shall be called before transmision of an RTP packet to ensure
441 : // that the |level| part of the extended RTP header is updated.
442 : // return -1 on failure else 0.
443 : virtual int32_t SetAudioLevel(uint8_t level_dbov) = 0;
444 :
445 : // **************************************************************************
446 : // Video
447 : // **************************************************************************
448 :
449 : // Set RED and ULPFEC payload types. A payload type of -1 means that the
450 : // corresponding feature is turned off. Note that we DO NOT support enabling
451 : // ULPFEC without enabling RED. However, we DO support enabling RED without
452 : // enabling ULPFEC. This is due to an RED/RTX workaround, where the receiver
453 : // assumes that RTX packets carry RED if RED has been configured in the SDP,
454 : // regardless of what RTX payload type mapping was negotiated in the SDP.
455 : // TODO(brandtr): Update this comment when we have removed the RED/RTX
456 : // send-side workaround, i.e., when we do not support enabling RED without
457 : // enabling ULPFEC.
458 : virtual void SetUlpfecConfig(int red_payload_type,
459 : int ulpfec_payload_type) = 0;
460 :
461 : // Set FEC rates, max frames before FEC is sent, and type of FEC masks.
462 : // Returns false on failure.
463 : virtual bool SetFecParameters(const FecProtectionParams& delta_params,
464 : const FecProtectionParams& key_params) = 0;
465 :
466 : // Deprecated version of member function above.
467 : RTC_DEPRECATED
468 : int32_t SetFecParameters(const FecProtectionParams* delta_params,
469 : const FecProtectionParams* key_params);
470 :
471 : // Set method for requestion a new key frame.
472 : // Returns -1 on failure else 0.
473 : virtual int32_t SetKeyFrameRequestMethod(KeyFrameRequestMethod method) = 0;
474 :
475 : // Sends a request for a keyframe.
476 : // Returns -1 on failure else 0.
477 : virtual int32_t RequestKeyFrame() = 0;
478 : };
479 :
480 : } // namespace webrtc
481 :
482 : #endif // WEBRTC_MODULES_RTP_RTCP_INCLUDE_RTP_RTCP_H_
|
