blob: c9d911fac1a8c696a3033454e2cc4a3503513f1e [file] [log] [blame]
Steve Anton6e634bf2017-11-13 18:44:531/*
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 17:11:0011#ifndef API_RTP_TRANSCEIVER_INTERFACE_H_
12#define API_RTP_TRANSCEIVER_INTERFACE_H_
Steve Anton6e634bf2017-11-13 18:44:5313
14#include <string>
Steve Anton9158ef62017-11-27 21:01:5215#include <vector>
Steve Anton6e634bf2017-11-13 18:44:5316
Danil Chapovalove9041612021-02-22 11:43:3917#include "absl/base/attributes.h"
Danil Chapovalov0bc58cf2018-06-21 11:32:5618#include "absl/types/optional.h"
Danil Chapovalov6e9d8952018-04-09 18:30:5119#include "api/array_view.h"
Steve Anton10542f22019-01-11 17:11:0020#include "api/media_types.h"
21#include "api/rtp_parameters.h"
22#include "api/rtp_receiver_interface.h"
23#include "api/rtp_sender_interface.h"
Markus Handell0357b3e2020-03-16 12:40:5124#include "api/rtp_transceiver_direction.h"
Mirko Bonadeid9708072019-01-25 19:26:4825#include "api/scoped_refptr.h"
Steve Anton10542f22019-01-11 17:11:0026#include "rtc_base/ref_count.h"
Mirko Bonadei66e76792019-04-02 09:33:5927#include "rtc_base/system/rtc_export.h"
Steve Anton6e634bf2017-11-13 18:44:5328
29namespace webrtc {
30
Steve Anton9158ef62017-11-27 21:01:5231// Structure for initializing an RtpTransceiver in a call to
32// PeerConnectionInterface::AddTransceiver.
33// https://w3c.github.io/webrtc-pc/#dom-rtcrtptransceiverinit
Mirko Bonadei66e76792019-04-02 09:33:5934struct RTC_EXPORT RtpTransceiverInit final {
Mirko Bonadei79eb4dd2018-07-19 08:39:3035 RtpTransceiverInit();
Mirko Bonadei2ffed6d2018-07-20 09:09:3236 RtpTransceiverInit(const RtpTransceiverInit&);
Mirko Bonadei79eb4dd2018-07-19 08:39:3037 ~RtpTransceiverInit();
Steve Anton9158ef62017-11-27 21:01:5238 // Direction of the RtpTransceiver. See RtpTransceiverInterface::direction().
39 RtpTransceiverDirection direction = RtpTransceiverDirection::kSendRecv;
40
41 // The added RtpTransceiver will be added to these streams.
Seth Hampson513449e2018-03-06 17:35:5642 std::vector<std::string> stream_ids;
Steve Anton9158ef62017-11-27 21:01:5243
44 // TODO(bugs.webrtc.org/7600): Not implemented.
45 std::vector<RtpEncodingParameters> send_encodings;
46};
47
Steve Anton6e634bf2017-11-13 18:44:5348// The RtpTransceiverInterface maps to the RTCRtpTransceiver defined by the
49// WebRTC specification. A transceiver represents a combination of an RtpSender
50// and an RtpReceiver than share a common mid. As defined in JSEP, an
51// RtpTransceiver is said to be associated with a media description if its mid
52// property is non-null; otherwise, it is said to be disassociated.
53// JSEP: https://tools.ietf.org/html/draft-ietf-rtcweb-jsep-24
54//
55// Note that RtpTransceivers are only supported when using PeerConnection with
56// Unified Plan SDP.
57//
58// This class is thread-safe.
59//
60// WebRTC specification for RTCRtpTransceiver, the JavaScript analog:
61// https://w3c.github.io/webrtc-pc/#dom-rtcrtptransceiver
Mirko Bonadei35214fc2019-09-23 12:54:2862class RTC_EXPORT RtpTransceiverInterface : public rtc::RefCountInterface {
Steve Anton6e634bf2017-11-13 18:44:5363 public:
Steve Anton69470252018-02-09 19:43:0864 // Media type of the transceiver. Any sender(s)/receiver(s) will have this
65 // type as well.
66 virtual cricket::MediaType media_type() const = 0;
67
Steve Anton6e634bf2017-11-13 18:44:5368 // The mid attribute is the mid negotiated and present in the local and
69 // remote descriptions. Before negotiation is complete, the mid value may be
70 // null. After rollbacks, the value may change from a non-null value to null.
71 // https://w3c.github.io/webrtc-pc/#dom-rtcrtptransceiver-mid
Danil Chapovalov0bc58cf2018-06-21 11:32:5672 virtual absl::optional<std::string> mid() const = 0;
Steve Anton6e634bf2017-11-13 18:44:5373
74 // The sender attribute exposes the RtpSender corresponding to the RTP media
75 // that may be sent with the transceiver's mid. The sender is always present,
76 // regardless of the direction of media.
77 // https://w3c.github.io/webrtc-pc/#dom-rtcrtptransceiver-sender
78 virtual rtc::scoped_refptr<RtpSenderInterface> sender() const = 0;
79
80 // The receiver attribute exposes the RtpReceiver corresponding to the RTP
81 // media that may be received with the transceiver's mid. The receiver is
82 // always present, regardless of the direction of media.
83 // https://w3c.github.io/webrtc-pc/#dom-rtcrtptransceiver-receiver
84 virtual rtc::scoped_refptr<RtpReceiverInterface> receiver() const = 0;
85
86 // The stopped attribute indicates that the sender of this transceiver will no
87 // longer send, and that the receiver will no longer receive. It is true if
88 // either stop has been called or if setting the local or remote description
89 // has caused the RtpTransceiver to be stopped.
90 // https://w3c.github.io/webrtc-pc/#dom-rtcrtptransceiver-stopped
91 virtual bool stopped() const = 0;
92
Harald Alvestrand6060df52020-08-11 07:54:0293 // The stopping attribute indicates that the user has indicated that the
94 // sender of this transceiver will stop sending, and that the receiver will
95 // no longer receive. It is always true if stopped() is true.
96 // If stopping() is true and stopped() is false, it means that the
97 // transceiver's stop() method has been called, but the negotiation with
98 // the other end for shutting down the transceiver is not yet done.
99 // https://w3c.github.io/webrtc-pc/#dfn-stopping-0
Harald Alvestrand4f199502022-01-17 21:20:49100 virtual bool stopping() const = 0;
Harald Alvestrand6060df52020-08-11 07:54:02101
Steve Anton6e634bf2017-11-13 18:44:53102 // The direction attribute indicates the preferred direction of this
103 // transceiver, which will be used in calls to CreateOffer and CreateAnswer.
104 // https://w3c.github.io/webrtc-pc/#dom-rtcrtptransceiver-direction
105 virtual RtpTransceiverDirection direction() const = 0;
106
107 // Sets the preferred direction of this transceiver. An update of
108 // directionality does not take effect immediately. Instead, future calls to
109 // CreateOffer and CreateAnswer mark the corresponding media descriptions as
110 // sendrecv, sendonly, recvonly, or inactive.
111 // https://w3c.github.io/webrtc-pc/#dom-rtcrtptransceiver-direction
Harald Alvestrand6060df52020-08-11 07:54:02112 // TODO(hta): Deprecate SetDirection without error and rename
113 // SetDirectionWithError to SetDirection, remove default implementations.
Danil Chapovalove9041612021-02-22 11:43:39114 ABSL_DEPRECATED("Use SetDirectionWithError instead")
115 virtual void SetDirection(RtpTransceiverDirection new_direction);
Harald Alvestrand6060df52020-08-11 07:54:02116 virtual RTCError SetDirectionWithError(RtpTransceiverDirection new_direction);
Steve Anton6e634bf2017-11-13 18:44:53117
118 // The current_direction attribute indicates the current direction negotiated
119 // for this transceiver. If this transceiver has never been represented in an
120 // offer/answer exchange, or if the transceiver is stopped, the value is null.
121 // https://w3c.github.io/webrtc-pc/#dom-rtcrtptransceiver-currentdirection
Danil Chapovalov0bc58cf2018-06-21 11:32:56122 virtual absl::optional<RtpTransceiverDirection> current_direction() const = 0;
Steve Anton6e634bf2017-11-13 18:44:53123
Steve Anton0f5400a2018-07-17 21:25:36124 // An internal slot designating for which direction the relevant
125 // PeerConnection events have been fired. This is to ensure that events like
126 // OnAddTrack only get fired once even if the same session description is
127 // applied again.
128 // Exposed in the public interface for use by Chromium.
Mirko Bonadei79eb4dd2018-07-19 08:39:30129 virtual absl::optional<RtpTransceiverDirection> fired_direction() const;
Steve Anton0f5400a2018-07-17 21:25:36130
Harald Alvestrand6060df52020-08-11 07:54:02131 // Initiates a stop of the transceiver.
132 // The stop is complete when stopped() returns true.
133 // A stopped transceiver can be reused for a different track.
Steve Anton6e634bf2017-11-13 18:44:53134 // https://w3c.github.io/webrtc-pc/#dom-rtcrtptransceiver-stop
Harald Alvestrand6060df52020-08-11 07:54:02135 // TODO(hta): Rename to Stop() when users of the non-standard Stop() are
136 // updated.
137 virtual RTCError StopStandard();
138
139 // Stops a transceiver immediately, without waiting for signalling.
140 // This is an internal function, and is exposed for historical reasons.
141 // https://w3c.github.io/webrtc-pc/#dfn-stop-the-rtcrtptransceiver
142 virtual void StopInternal();
Danil Chapovalove9041612021-02-22 11:43:39143 ABSL_DEPRECATED("Use StopStandard instead") virtual void Stop();
Steve Anton6e634bf2017-11-13 18:44:53144
145 // The SetCodecPreferences method overrides the default codec preferences used
146 // by WebRTC for this transceiver.
147 // https://w3c.github.io/webrtc-pc/#dom-rtcrtptransceiver-setcodecpreferences
Florent Castelli2d9d82e2019-04-23 17:25:51148 virtual RTCError SetCodecPreferences(
Harald Alvestrand4f199502022-01-17 21:20:49149 rtc::ArrayView<RtpCodecCapability> codecs) = 0;
150 virtual std::vector<RtpCodecCapability> codec_preferences() const = 0;
Steve Anton6e634bf2017-11-13 18:44:53151
Markus Handell0357b3e2020-03-16 12:40:51152 // Readonly attribute which contains the set of header extensions that was set
153 // with SetOfferedRtpHeaderExtensions, or a default set if it has not been
154 // called.
155 // https://w3c.github.io/webrtc-extensions/#rtcrtptransceiver-interface
156 virtual std::vector<RtpHeaderExtensionCapability> HeaderExtensionsToOffer()
Harald Alvestrand4f199502022-01-17 21:20:49157 const = 0;
Markus Handell0357b3e2020-03-16 12:40:51158
Markus Handell5932fe12020-12-17 21:19:40159 // Readonly attribute which is either empty if negotation has not yet
160 // happened, or a vector of the negotiated header extensions.
161 // https://w3c.github.io/webrtc-extensions/#rtcrtptransceiver-interface
162 virtual std::vector<RtpHeaderExtensionCapability> HeaderExtensionsNegotiated()
Harald Alvestrand4f199502022-01-17 21:20:49163 const = 0;
Markus Handell5932fe12020-12-17 21:19:40164
Markus Handell755c65d2020-06-23 23:06:10165 // The SetOfferedRtpHeaderExtensions method modifies the next SDP negotiation
166 // so that it negotiates use of header extensions which are not kStopped.
167 // https://w3c.github.io/webrtc-extensions/#rtcrtptransceiver-interface
168 virtual webrtc::RTCError SetOfferedRtpHeaderExtensions(
169 rtc::ArrayView<const RtpHeaderExtensionCapability>
Harald Alvestrand4f199502022-01-17 21:20:49170 header_extensions_to_offer) = 0;
Markus Handell755c65d2020-06-23 23:06:10171
Steve Anton6e634bf2017-11-13 18:44:53172 protected:
Mirko Bonadei79eb4dd2018-07-19 08:39:30173 ~RtpTransceiverInterface() override = default;
Steve Anton6e634bf2017-11-13 18:44:53174};
175
176} // namespace webrtc
177
Steve Anton10542f22019-01-11 17:11:00178#endif // API_RTP_TRANSCEIVER_INTERFACE_H_