rtp_transceiver_interface.h (8310B)
1 /* 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 11 #ifndef API_RTP_TRANSCEIVER_INTERFACE_H_ 12 #define API_RTP_TRANSCEIVER_INTERFACE_H_ 13 14 #include <optional> 15 #include <string> 16 #include <vector> 17 18 #include "absl/base/attributes.h" 19 #include "api/array_view.h" 20 #include "api/media_types.h" 21 #include "api/ref_count.h" 22 #include "api/rtc_error.h" 23 #include "api/rtp_parameters.h" 24 #include "api/rtp_receiver_interface.h" 25 #include "api/rtp_sender_interface.h" 26 #include "api/rtp_transceiver_direction.h" 27 #include "api/scoped_refptr.h" 28 #include "rtc_base/system/rtc_export.h" 29 30 namespace webrtc { 31 32 // Structure for initializing an RtpTransceiver in a call to 33 // PeerConnectionInterface::AddTransceiver. 34 // https://w3c.github.io/webrtc-pc/#dom-rtcrtptransceiverinit 35 struct RTC_EXPORT RtpTransceiverInit final { 36 RtpTransceiverInit(); 37 RtpTransceiverInit(const RtpTransceiverInit&); 38 ~RtpTransceiverInit(); 39 // Direction of the RtpTransceiver. See RtpTransceiverInterface::direction(). 40 RtpTransceiverDirection direction = RtpTransceiverDirection::kSendRecv; 41 42 // The added RtpTransceiver will be added to these streams. 43 std::vector<std::string> stream_ids; 44 45 std::vector<RtpEncodingParameters> send_encodings; 46 }; 47 48 // 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 62 class RTC_EXPORT RtpTransceiverInterface : public RefCountInterface { 63 public: 64 // Media type of the transceiver. Any sender(s)/receiver(s) will have this 65 // type as well. 66 virtual MediaType media_type() const = 0; 67 68 // 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 72 virtual std::optional<std::string> mid() const = 0; 73 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 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 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 93 // 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 100 virtual bool stopping() const = 0; 101 102 // 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 112 // TODO(hta): Deprecate SetDirection without error and rename 113 // SetDirectionWithError to SetDirection, remove default implementations. 114 ABSL_DEPRECATED("Use SetDirectionWithError instead") 115 virtual void SetDirection(RtpTransceiverDirection new_direction); 116 virtual RTCError SetDirectionWithError(RtpTransceiverDirection new_direction); 117 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 122 virtual std::optional<RtpTransceiverDirection> current_direction() const = 0; 123 124 // 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. 129 virtual std::optional<RtpTransceiverDirection> fired_direction() const; 130 131 // 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. 134 // https://w3c.github.io/webrtc-pc/#dom-rtcrtptransceiver-stop 135 // 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(); 143 ABSL_DEPRECATED("Use StopStandard instead") virtual void Stop(); 144 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 148 virtual RTCError SetCodecPreferences( 149 ArrayView<RtpCodecCapability> codecs) = 0; 150 virtual std::vector<RtpCodecCapability> codec_preferences() const = 0; 151 152 // Returns the set of header extensions that was set 153 // with SetHeaderExtensionsToNegotiate, 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> 157 GetHeaderExtensionsToNegotiate() const = 0; 158 159 // Returns either the empty set 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> 163 GetNegotiatedHeaderExtensions() const = 0; 164 165 // The SetHeaderExtensionsToNegotiate 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 RTCError SetHeaderExtensionsToNegotiate( 169 ArrayView<const RtpHeaderExtensionCapability> header_extensions) = 0; 170 171 protected: 172 ~RtpTransceiverInterface() override = default; 173 }; 174 175 } // namespace webrtc 176 177 #endif // API_RTP_TRANSCEIVER_INTERFACE_H_