blob: b8dbb677dd55eeb21b010ac9d00fde6330e5b631 [file] [log] [blame]
Steve Anton6e634bf2017-11-13 10:44:53 -08001/*
2 * Copyright 2017 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
Steve Anton10542f22019-01-11 09:11:00 -080011#ifndef PC_RTP_TRANSCEIVER_H_
12#define PC_RTP_TRANSCEIVER_H_
Steve Anton6e634bf2017-11-13 10:44:53 -080013
Harald Alvestrand5761e7b2021-01-29 14:45:08 +000014#include <stddef.h>
15
16#include <algorithm>
17#include <functional>
Steve Anton6e634bf2017-11-13 10:44:53 -080018#include <string>
19#include <vector>
20
Harald Alvestrand5761e7b2021-01-29 14:45:08 +000021#include "absl/types/optional.h"
22#include "api/array_view.h"
23#include "api/media_types.h"
Harald Alvestrand5761e7b2021-01-29 14:45:08 +000024#include "api/rtc_error.h"
25#include "api/rtp_parameters.h"
Harald Alvestrand5761e7b2021-01-29 14:45:08 +000026#include "api/rtp_transceiver_direction.h"
Steve Anton10542f22019-01-11 09:11:00 -080027#include "api/rtp_transceiver_interface.h"
Harald Alvestrand5761e7b2021-01-29 14:45:08 +000028#include "api/scoped_refptr.h"
29#include "api/task_queue/task_queue_base.h"
Ruslan Burakov501bfba2019-02-11 10:29:19 +010030#include "pc/channel_interface.h"
Florent Castelli2d9d82e2019-04-23 19:25:51 +020031#include "pc/channel_manager.h"
Markus Handella1b82012021-05-26 18:56:30 +020032#include "pc/proxy.h"
Steve Anton10542f22019-01-11 09:11:00 -080033#include "pc/rtp_receiver.h"
Markus Handelle93fe6c2021-05-20 22:46:31 +020034#include "pc/rtp_receiver_proxy.h"
Steve Anton10542f22019-01-11 09:11:00 -080035#include "pc/rtp_sender.h"
Markus Handelle93fe6c2021-05-20 22:46:31 +020036#include "pc/rtp_sender_proxy.h"
Harald Alvestrand5761e7b2021-01-29 14:45:08 +000037#include "rtc_base/ref_counted_object.h"
Tommi99c8a802021-04-27 15:00:00 +020038#include "rtc_base/task_utils/pending_task_safety_flag.h"
Harald Alvestrand5761e7b2021-01-29 14:45:08 +000039#include "rtc_base/third_party/sigslot/sigslot.h"
40#include "rtc_base/thread_annotations.h"
Steve Anton6e634bf2017-11-13 10:44:53 -080041
42namespace webrtc {
43
44// Implementation of the public RtpTransceiverInterface.
45//
46// The RtpTransceiverInterface is only intended to be used with a PeerConnection
47// that enables Unified Plan SDP. Thus, the methods that only need to implement
48// public API features and are not used internally can assume exactly one sender
49// and receiver.
50//
51// Since the RtpTransceiver is used internally by PeerConnection for tracking
52// RtpSenders, RtpReceivers, and BaseChannels, and PeerConnection needs to be
53// backwards compatible with Plan B SDP, this implementation is more flexible
54// than that required by the WebRTC specification.
55//
56// With Plan B SDP, an RtpTransceiver can have any number of senders and
57// receivers which map to a=ssrc lines in the m= section.
58// With Unified Plan SDP, an RtpTransceiver will have exactly one sender and one
59// receiver which are encapsulated by the m= section.
60//
61// This class manages the RtpSenders, RtpReceivers, and BaseChannel associated
62// with this m= section. Since the transceiver, senders, and receivers are
63// reference counted and can be referenced from JavaScript (in Chromium), these
64// objects must be ready to live for an arbitrary amount of time. The
65// BaseChannel is not reference counted and is owned by the ChannelManager, so
66// the PeerConnection must take care of creating/deleting the BaseChannel and
67// setting the channel reference in the transceiver to null when it has been
68// deleted.
69//
70// The RtpTransceiver is specialized to either audio or video according to the
71// MediaType specified in the constructor. Audio RtpTransceivers will have
72// AudioRtpSenders, AudioRtpReceivers, and a VoiceChannel. Video RtpTransceivers
73// will have VideoRtpSenders, VideoRtpReceivers, and a VideoChannel.
74class RtpTransceiver final
Steve Anton60776752018-01-10 11:51:34 -080075 : public rtc::RefCountedObject<RtpTransceiverInterface>,
76 public sigslot::has_slots<> {
Steve Anton6e634bf2017-11-13 10:44:53 -080077 public:
Steve Anton79e79602017-11-20 10:25:56 -080078 // Construct a Plan B-style RtpTransceiver with no senders, receivers, or
79 // channel set.
Artem Titov880fa812021-07-30 22:30:23 +020080 // `media_type` specifies the type of RtpTransceiver (and, by transitivity,
Steve Anton6e634bf2017-11-13 10:44:53 -080081 // the type of senders, receivers, and channel). Can either by audio or video.
Tommi99c8a802021-04-27 15:00:00 +020082 RtpTransceiver(cricket::MediaType media_type,
83 cricket::ChannelManager* channel_manager);
Steve Anton79e79602017-11-20 10:25:56 -080084 // Construct a Unified Plan-style RtpTransceiver with the given sender and
85 // receiver. The media type will be derived from the media types of the sender
86 // and receiver. The sender and receiver should have the same media type.
Artem Titov880fa812021-07-30 22:30:23 +020087 // `HeaderExtensionsToOffer` is used for initializing the return value of
Markus Handell0357b3e2020-03-16 13:40:51 +010088 // HeaderExtensionsToOffer().
Steve Anton79e79602017-11-20 10:25:56 -080089 RtpTransceiver(
90 rtc::scoped_refptr<RtpSenderProxyWithInternal<RtpSenderInternal>> sender,
91 rtc::scoped_refptr<RtpReceiverProxyWithInternal<RtpReceiverInternal>>
Florent Castelli2d9d82e2019-04-23 19:25:51 +020092 receiver,
Markus Handell0357b3e2020-03-16 13:40:51 +010093 cricket::ChannelManager* channel_manager,
Harald Alvestrand280054f2020-11-10 13:12:53 +000094 std::vector<RtpHeaderExtensionCapability> HeaderExtensionsToOffer,
95 std::function<void()> on_negotiation_needed);
Steve Anton6e634bf2017-11-13 10:44:53 -080096 ~RtpTransceiver() override;
97
Steve Anton6e634bf2017-11-13 10:44:53 -080098 // Returns the Voice/VideoChannel set for this transceiver. May be null if
99 // the transceiver is not in the currently set local/remote description.
Amit Hilbuchdd9390c2018-11-13 16:26:05 -0800100 cricket::ChannelInterface* channel() const { return channel_; }
Steve Anton6e634bf2017-11-13 10:44:53 -0800101
102 // Sets the Voice/VideoChannel. The caller must pass in the correct channel
Tomas Gunnarsson4f8a58c2022-01-19 11:36:23 +0100103 // implementation based on the type of the transceiver. The call must
104 // furthermore be made on the signaling thread.
105 //
106 // `channel`: The channel instance to be associated with the transceiver.
107 // When a valid pointer is passed for `channel`, the state of the object
108 // is expected to be newly constructed and not initalized for network
109 // activity (see next parameter for more).
110 //
111 // NOTE: For all practical purposes, the ownership of the channel
112 // object should be considered to lie with the transceiver until
113 // `SetChannel()` is called again with nullptr set as the new channel.
114 // Moving forward, this parameter will change to either be a
115 // std::unique_ptr<> or the full construction of the channel object will
116 // be moved to happen within the context of the transceiver class.
117 //
118 // `transport_lookup`: When `channel` points to a valid channel object, this
119 // callback function will be used to look up the `RtpTransport` object
120 // to associate with the channel via `BaseChannel::SetRtpTransport`.
121 // The lookup function will be called on the network thread, synchronously
122 // during the call to `SetChannel`. This means that the caller of
123 // `SetChannel()` may provide a callback function that references state
124 // that exists within the calling scope of SetChannel (e.g. a variable
125 // on the stack).
126 // The reason for this design is to limit the number of times we jump
127 // synchronously to the network thread from the signaling thread.
128 // The callback allows us to combine the transport lookup with network
129 // state initialization of the channel object.
130 void SetChannel(cricket::ChannelInterface* channel,
131 std::function<RtpTransportInternal*(const std::string&)>
132 transport_lookup);
Steve Anton6e634bf2017-11-13 10:44:53 -0800133
134 // Adds an RtpSender of the appropriate type to be owned by this transceiver.
135 // Must not be null.
136 void AddSender(
137 rtc::scoped_refptr<RtpSenderProxyWithInternal<RtpSenderInternal>> sender);
138
139 // Removes the given RtpSender. Returns false if the sender is not owned by
140 // this transceiver.
141 bool RemoveSender(RtpSenderInterface* sender);
142
143 // Returns a vector of the senders owned by this transceiver.
144 std::vector<rtc::scoped_refptr<RtpSenderProxyWithInternal<RtpSenderInternal>>>
145 senders() const {
146 return senders_;
147 }
148
149 // Adds an RtpReceiver of the appropriate type to be owned by this
150 // transceiver. Must not be null.
151 void AddReceiver(
152 rtc::scoped_refptr<RtpReceiverProxyWithInternal<RtpReceiverInternal>>
153 receiver);
154
155 // Removes the given RtpReceiver. Returns false if the sender is not owned by
156 // this transceiver.
157 bool RemoveReceiver(RtpReceiverInterface* receiver);
158
159 // Returns a vector of the receivers owned by this transceiver.
160 std::vector<
161 rtc::scoped_refptr<RtpReceiverProxyWithInternal<RtpReceiverInternal>>>
162 receivers() const {
163 return receivers_;
164 }
165
Steve Antonf9381f02017-12-14 10:23:57 -0800166 // Returns the backing object for the transceiver's Unified Plan sender.
167 rtc::scoped_refptr<RtpSenderInternal> sender_internal() const;
168
169 // Returns the backing object for the transceiver's Unified Plan receiver.
170 rtc::scoped_refptr<RtpReceiverInternal> receiver_internal() const;
171
Steve Antondcc3c022017-12-22 16:02:54 -0800172 // RtpTransceivers are not associated until they have a corresponding media
173 // section set in SetLocalDescription or SetRemoteDescription. Therefore,
174 // when setting a local offer we need a way to remember which transceiver was
175 // used to create which media section in the offer. Storing the mline index
176 // in CreateOffer is specified in JSEP to allow us to do that.
Danil Chapovalov66cadcc2018-06-19 16:47:43 +0200177 absl::optional<size_t> mline_index() const { return mline_index_; }
178 void set_mline_index(absl::optional<size_t> mline_index) {
Steve Antondcc3c022017-12-22 16:02:54 -0800179 mline_index_ = mline_index;
180 }
181
182 // Sets the MID for this transceiver. If the MID is not null, then the
183 // transceiver is considered "associated" with the media section that has the
184 // same MID.
Danil Chapovalov66cadcc2018-06-19 16:47:43 +0200185 void set_mid(const absl::optional<std::string>& mid) { mid_ = mid; }
Steve Antondcc3c022017-12-22 16:02:54 -0800186
187 // Sets the intended direction for this transceiver. Intended to be used
188 // internally over SetDirection since this does not trigger a negotiation
189 // needed callback.
190 void set_direction(RtpTransceiverDirection direction) {
191 direction_ = direction;
192 }
193
194 // Sets the current direction for this transceiver as negotiated in an offer/
195 // answer exchange. The current direction is null before an answer with this
196 // transceiver has been set.
197 void set_current_direction(RtpTransceiverDirection direction);
198
Steve Anton0f5400a2018-07-17 14:25:36 -0700199 // Sets the fired direction for this transceiver. The fired direction is null
200 // until SetRemoteDescription is called or an answer is set (either local or
201 // remote).
202 void set_fired_direction(RtpTransceiverDirection direction);
203
Steve Antonf9381f02017-12-14 10:23:57 -0800204 // According to JSEP rules for SetRemoteDescription, RtpTransceivers can be
205 // reused only if they were added by AddTrack.
206 void set_created_by_addtrack(bool created_by_addtrack) {
207 created_by_addtrack_ = created_by_addtrack;
208 }
Eldar Rello353a7182019-11-25 18:49:44 +0200209 // If AddTrack has been called then transceiver can't be removed during
210 // rollback.
211 void set_reused_for_addtrack(bool reused_for_addtrack) {
212 reused_for_addtrack_ = reused_for_addtrack;
213 }
214
Steve Antonf9381f02017-12-14 10:23:57 -0800215 bool created_by_addtrack() const { return created_by_addtrack_; }
216
Eldar Rello353a7182019-11-25 18:49:44 +0200217 bool reused_for_addtrack() const { return reused_for_addtrack_; }
218
Steve Antonf9381f02017-12-14 10:23:57 -0800219 // Returns true if this transceiver has ever had the current direction set to
220 // sendonly or sendrecv.
221 bool has_ever_been_used_to_send() const {
222 return has_ever_been_used_to_send_;
223 }
224
Harald Alvestrand6060df52020-08-11 09:54:02 +0200225 // Informs the transceiver that its owning
226 // PeerConnection is closed.
227 void SetPeerConnectionClosed();
228
Harald Alvestrandc75c4282020-08-26 12:17:54 +0000229 // Executes the "stop the RTCRtpTransceiver" procedure from
230 // the webrtc-pc specification, described under the stop() method.
231 void StopTransceiverProcedure();
232
Steve Anton52d86772018-02-20 15:48:12 -0800233 // Fired when the RtpTransceiver state changes such that negotiation is now
234 // needed (e.g., in response to a direction change).
Harald Alvestrand280054f2020-11-10 13:12:53 +0000235 // sigslot::signal0<> SignalNegotiationNeeded;
Steve Anton52d86772018-02-20 15:48:12 -0800236
Steve Anton6e634bf2017-11-13 10:44:53 -0800237 // RtpTransceiverInterface implementation.
Steve Anton69470252018-02-09 11:43:08 -0800238 cricket::MediaType media_type() const override;
Danil Chapovalov66cadcc2018-06-19 16:47:43 +0200239 absl::optional<std::string> mid() const override;
Steve Anton6e634bf2017-11-13 10:44:53 -0800240 rtc::scoped_refptr<RtpSenderInterface> sender() const override;
241 rtc::scoped_refptr<RtpReceiverInterface> receiver() const override;
242 bool stopped() const override;
Harald Alvestrand6060df52020-08-11 09:54:02 +0200243 bool stopping() const override;
Steve Anton6e634bf2017-11-13 10:44:53 -0800244 RtpTransceiverDirection direction() const override;
Harald Alvestrand6060df52020-08-11 09:54:02 +0200245 RTCError SetDirectionWithError(
246 RtpTransceiverDirection new_direction) override;
Danil Chapovalov66cadcc2018-06-19 16:47:43 +0200247 absl::optional<RtpTransceiverDirection> current_direction() const override;
Steve Anton0f5400a2018-07-17 14:25:36 -0700248 absl::optional<RtpTransceiverDirection> fired_direction() const override;
Harald Alvestrand6060df52020-08-11 09:54:02 +0200249 RTCError StopStandard() override;
250 void StopInternal() override;
Florent Castelli2d9d82e2019-04-23 19:25:51 +0200251 RTCError SetCodecPreferences(
252 rtc::ArrayView<RtpCodecCapability> codecs) override;
253 std::vector<RtpCodecCapability> codec_preferences() const override {
254 return codec_preferences_;
255 }
Markus Handell0357b3e2020-03-16 13:40:51 +0100256 std::vector<RtpHeaderExtensionCapability> HeaderExtensionsToOffer()
257 const override;
Markus Handell5932fe12020-12-17 22:19:40 +0100258 std::vector<RtpHeaderExtensionCapability> HeaderExtensionsNegotiated()
259 const override;
Markus Handell755c65d2020-06-24 01:06:10 +0200260 RTCError SetOfferedRtpHeaderExtensions(
261 rtc::ArrayView<const RtpHeaderExtensionCapability>
262 header_extensions_to_offer) override;
Steve Anton6e634bf2017-11-13 10:44:53 -0800263
Tommicc7a3682021-05-04 14:59:38 +0200264 // Called on the signaling thread when the local or remote content description
265 // is updated. Used to update the negotiated header extensions.
266 // TODO(tommi): The implementation of this method is currently very simple and
267 // only used for updating the negotiated headers. However, we're planning to
268 // move all the updates done on the channel from the transceiver into this
269 // method. This will happen with the ownership of the channel object being
270 // moved into the transceiver.
271 void OnNegotiationUpdate(SdpType sdp_type,
272 const cricket::MediaContentDescription* content);
273
Steve Anton6e634bf2017-11-13 10:44:53 -0800274 private:
Tommi99c8a802021-04-27 15:00:00 +0200275 void OnFirstPacketReceived();
Harald Alvestrand6060df52020-08-11 09:54:02 +0200276 void StopSendingAndReceiving();
Steve Anton60776752018-01-10 11:51:34 -0800277
Harald Alvestrand6060df52020-08-11 09:54:02 +0200278 // Enforce that this object is created, used and destroyed on one thread.
Tommi99c8a802021-04-27 15:00:00 +0200279 TaskQueueBase* const thread_;
Steve Anton6e634bf2017-11-13 10:44:53 -0800280 const bool unified_plan_;
281 const cricket::MediaType media_type_;
Tommi99c8a802021-04-27 15:00:00 +0200282 rtc::scoped_refptr<PendingTaskSafetyFlag> signaling_thread_safety_;
Steve Anton6e634bf2017-11-13 10:44:53 -0800283 std::vector<rtc::scoped_refptr<RtpSenderProxyWithInternal<RtpSenderInternal>>>
284 senders_;
285 std::vector<
286 rtc::scoped_refptr<RtpReceiverProxyWithInternal<RtpReceiverInternal>>>
287 receivers_;
288
Tommi99c8a802021-04-27 15:00:00 +0200289 bool stopped_ RTC_GUARDED_BY(thread_) = false;
Harald Alvestrand6060df52020-08-11 09:54:02 +0200290 bool stopping_ RTC_GUARDED_BY(thread_) = false;
291 bool is_pc_closed_ = false;
Steve Anton6e634bf2017-11-13 10:44:53 -0800292 RtpTransceiverDirection direction_ = RtpTransceiverDirection::kInactive;
Danil Chapovalov66cadcc2018-06-19 16:47:43 +0200293 absl::optional<RtpTransceiverDirection> current_direction_;
Steve Anton0f5400a2018-07-17 14:25:36 -0700294 absl::optional<RtpTransceiverDirection> fired_direction_;
Danil Chapovalov66cadcc2018-06-19 16:47:43 +0200295 absl::optional<std::string> mid_;
296 absl::optional<size_t> mline_index_;
Steve Antonf9381f02017-12-14 10:23:57 -0800297 bool created_by_addtrack_ = false;
Eldar Rello353a7182019-11-25 18:49:44 +0200298 bool reused_for_addtrack_ = false;
Steve Antonf9381f02017-12-14 10:23:57 -0800299 bool has_ever_been_used_to_send_ = false;
Steve Anton6e634bf2017-11-13 10:44:53 -0800300
Amit Hilbuchdd9390c2018-11-13 16:26:05 -0800301 cricket::ChannelInterface* channel_ = nullptr;
Florent Castelli2d9d82e2019-04-23 19:25:51 +0200302 cricket::ChannelManager* channel_manager_ = nullptr;
303 std::vector<RtpCodecCapability> codec_preferences_;
Markus Handell755c65d2020-06-24 01:06:10 +0200304 std::vector<RtpHeaderExtensionCapability> header_extensions_to_offer_;
Tommicc7a3682021-05-04 14:59:38 +0200305
Artem Titov880fa812021-07-30 22:30:23 +0200306 // `negotiated_header_extensions_` is read and written to on the signaling
Tommicc7a3682021-05-04 14:59:38 +0200307 // thread from the SdpOfferAnswerHandler class (e.g.
308 // PushdownMediaDescription().
309 cricket::RtpHeaderExtensions negotiated_header_extensions_
310 RTC_GUARDED_BY(thread_);
311
Harald Alvestrand280054f2020-11-10 13:12:53 +0000312 const std::function<void()> on_negotiation_needed_;
Steve Anton6e634bf2017-11-13 10:44:53 -0800313};
314
Mirko Bonadei9d9b8de2021-02-26 09:51:26 +0100315BEGIN_PRIMARY_PROXY_MAP(RtpTransceiver)
Harald Alvestrand5761e7b2021-01-29 14:45:08 +0000316
Mirko Bonadei9d9b8de2021-02-26 09:51:26 +0100317PROXY_PRIMARY_THREAD_DESTRUCTOR()
Tomas Gunnarssonfc83cdc2020-09-10 13:04:50 +0200318BYPASS_PROXY_CONSTMETHOD0(cricket::MediaType, media_type)
Nico Weber22f99252019-02-20 10:13:16 -0500319PROXY_CONSTMETHOD0(absl::optional<std::string>, mid)
320PROXY_CONSTMETHOD0(rtc::scoped_refptr<RtpSenderInterface>, sender)
321PROXY_CONSTMETHOD0(rtc::scoped_refptr<RtpReceiverInterface>, receiver)
322PROXY_CONSTMETHOD0(bool, stopped)
Harald Alvestrand6060df52020-08-11 09:54:02 +0200323PROXY_CONSTMETHOD0(bool, stopping)
Nico Weber22f99252019-02-20 10:13:16 -0500324PROXY_CONSTMETHOD0(RtpTransceiverDirection, direction)
Harald Alvestrand6060df52020-08-11 09:54:02 +0200325PROXY_METHOD1(webrtc::RTCError, SetDirectionWithError, RtpTransceiverDirection)
Nico Weber22f99252019-02-20 10:13:16 -0500326PROXY_CONSTMETHOD0(absl::optional<RtpTransceiverDirection>, current_direction)
327PROXY_CONSTMETHOD0(absl::optional<RtpTransceiverDirection>, fired_direction)
Harald Alvestrand6060df52020-08-11 09:54:02 +0200328PROXY_METHOD0(webrtc::RTCError, StopStandard)
329PROXY_METHOD0(void, StopInternal)
Florent Castelli2d9d82e2019-04-23 19:25:51 +0200330PROXY_METHOD1(webrtc::RTCError,
331 SetCodecPreferences,
332 rtc::ArrayView<RtpCodecCapability>)
333PROXY_CONSTMETHOD0(std::vector<RtpCodecCapability>, codec_preferences)
Markus Handell0357b3e2020-03-16 13:40:51 +0100334PROXY_CONSTMETHOD0(std::vector<RtpHeaderExtensionCapability>,
335 HeaderExtensionsToOffer)
Markus Handell5932fe12020-12-17 22:19:40 +0100336PROXY_CONSTMETHOD0(std::vector<RtpHeaderExtensionCapability>,
337 HeaderExtensionsNegotiated)
Markus Handell755c65d2020-06-24 01:06:10 +0200338PROXY_METHOD1(webrtc::RTCError,
339 SetOfferedRtpHeaderExtensions,
340 rtc::ArrayView<const RtpHeaderExtensionCapability>)
Markus Handell3d46d0b2021-05-27 21:42:57 +0200341END_PROXY_MAP(RtpTransceiver)
Steve Anton6e634bf2017-11-13 10:44:53 -0800342
343} // namespace webrtc
344
Steve Anton10542f22019-01-11 09:11:00 -0800345#endif // PC_RTP_TRANSCEIVER_H_