Miscellaneous updates to PeerConnectionInterface comments
NoTry: true
Bug: None
Change-Id: I9cf4f77e4775ff9b97c71f6a9bdb2d7f159e7048
Reviewed-on: https://webrtc-review.googlesource.com/57240
Commit-Queue: Steve Anton <steveanton@webrtc.org>
Reviewed-by: Seth Hampson <shampson@webrtc.org>
Reviewed-by: Taylor Brandstetter <deadbeef@webrtc.org>
Cr-Commit-Position: refs/heads/master@{#22192}diff --git a/api/peerconnectioninterface.h b/api/peerconnectioninterface.h
index 9463c34..7f7b910 100644
--- a/api/peerconnectioninterface.h
+++ b/api/peerconnectioninterface.h
@@ -9,7 +9,7 @@
*/
// This file contains the PeerConnection interface as defined in
-// http://dev.w3.org/2011/webrtc/editor/webrtc.html#peer-to-peer-connections.
+// https://w3c.github.io/webrtc-pc/#peer-to-peer-connections
//
// The PeerConnectionFactory class provides factory methods to create
// PeerConnection, MediaStream and MediaStreamTrack objects.
@@ -164,7 +164,7 @@
class PeerConnectionInterface : public rtc::RefCountInterface {
public:
- // See http://dev.w3.org/2011/webrtc/editor/webrtc.html#state-definitions .
+ // See https://w3c.github.io/webrtc-pc/#state-definitions
enum SignalingState {
kStable,
kHaveLocalOffer,
@@ -242,14 +242,14 @@
kAll
};
- // https://tools.ietf.org/html/draft-ietf-rtcweb-jsep-08#section-4.1.1
+ // https://tools.ietf.org/html/draft-ietf-rtcweb-jsep-24#section-4.1.1
enum BundlePolicy {
kBundlePolicyBalanced,
kBundlePolicyMaxBundle,
kBundlePolicyMaxCompat
};
- // https://tools.ietf.org/html/draft-ietf-rtcweb-jsep-09#section-4.1.1
+ // https://tools.ietf.org/html/draft-ietf-rtcweb-jsep-24#section-4.1.1
enum RtcpMuxPolicy {
kRtcpMuxPolicyNegotiate,
kRtcpMuxPolicyRequire,
@@ -350,7 +350,7 @@
////////////////////////////////////////////////////////////////////////
// The below few fields mirror the standard RTCConfiguration dictionary:
- // https://www.w3.org/TR/webrtc/#rtcconfiguration-dictionary
+ // https://w3c.github.io/webrtc-pc/#rtcconfiguration-dictionary
////////////////////////////////////////////////////////////////////////
// TODO(pthatcher): Rename this ice_servers, but update Chromium
@@ -522,14 +522,14 @@
// kPlanB will cause PeerConnection to create offers and answers with at
// most one audio and one video m= section with multiple RtpSenders and
// RtpReceivers specified as multiple a=ssrc lines within the section. This
- // will also cause PeerConnection to reject offers/answers with multiple m=
- // sections of the same media type.
+ // will also cause PeerConnection to ignore all but the first m= section of
+ // the same media type.
//
// kUnifiedPlan will cause PeerConnection to create offers and answers with
// multiple m= sections where each m= section maps to one RtpSender and one
- // RtpReceiver (an RtpTransceiver), either both audio or both video. Plan B
- // style offers or answers will be rejected in calls to SetLocalDescription
- // or SetRemoteDescription.
+ // RtpReceiver (an RtpTransceiver), either both audio or both video. This
+ // will also cause PeerConnection to ignore all but the first a=ssrc lines
+ // that form a Plan B stream.
//
// For users who only send at most one audio and one video track, this
// choice does not matter and should be left as kDefault.
@@ -539,8 +539,6 @@
//
// For users who wish to send multiple audio/video streams and/or wish to
// use the new RtpTransceiver API, specify kUnifiedPlan.
- //
- // TODO(steveanton): Implement support for kUnifiedPlan.
SdpSemantics sdp_semantics = SdpSemantics::kDefault;
//
@@ -556,8 +554,9 @@
// The default value for constraint offerToReceiveX:true.
static const int kOfferToReceiveMediaTrue = 1;
- // These have been removed from the standard in favor of the "transceiver"
- // API, but given that we don't support that API, we still have them here.
+ // These options are left as backwards compatibility for clients who need
+ // "Plan B" semantics. Clients who have switched to "Unified Plan" semantics
+ // should use the RtpTransceiver API (AddTransceiver) instead.
//
// offer_to_receive_X set to 1 will cause a media description to be
// generated in the offer, even if no tracks of that type have been added.
@@ -599,10 +598,14 @@
};
// Accessor methods to active local streams.
+ // This method is not supported with kUnifiedPlan semantics. Please use
+ // GetSenders() instead.
virtual rtc::scoped_refptr<StreamCollectionInterface>
local_streams() = 0;
// Accessor methods to remote streams.
+ // This method is not supported with kUnifiedPlan semantics. Please use
+ // GetReceivers() instead.
virtual rtc::scoped_refptr<StreamCollectionInterface>
remote_streams() = 0;
@@ -615,11 +618,17 @@
// stream, with the one difference that if "stream->AddTrack(...)" is called
// later, the PeerConnection will automatically pick up the new track. Though
// this functionality will be deprecated in the future.
+ //
+ // This method is not supported with kUnifiedPlan semantics. Please use
+ // AddTrack instead.
virtual bool AddStream(MediaStreamInterface* stream) = 0;
// Remove a MediaStream from this PeerConnection.
// Note that a SessionDescription negotiation is needed before the
// remote peer is notified.
+ //
+ // This method is not supported with kUnifiedPlan semantics. Please use
+ // RemoveTrack instead.
virtual void RemoveStream(MediaStreamInterface* stream) = 0;
// Add a new MediaStreamTrack to be sent on this PeerConnection, and return
@@ -643,7 +652,11 @@
// signature with stream labels.
virtual rtc::scoped_refptr<RtpSenderInterface> AddTrack(
MediaStreamTrackInterface* track,
- std::vector<MediaStreamInterface*> streams) = 0;
+ std::vector<MediaStreamInterface*> streams) {
+ // Default implementation provided so downstream implementations can remove
+ // this.
+ return nullptr;
+ }
// Remove an RtpSender from this PeerConnection.
// Returns true on success.
@@ -721,29 +734,34 @@
//
// |stream_id| is used to populate the msid attribute; if empty, one will
// be generated automatically.
+ //
+ // This method is not supported with kUnifiedPlan semantics. Please use
+ // AddTransceiver instead.
virtual rtc::scoped_refptr<RtpSenderInterface> CreateSender(
const std::string& kind,
const std::string& stream_id) {
return rtc::scoped_refptr<RtpSenderInterface>();
}
- // Get all RtpSenders, created either through AddStream, AddTrack, or
- // CreateSender. Note that these are "Plan B SDP" RtpSenders, not "Unified
- // Plan SDP" RtpSenders, which means that all senders of a specific media
- // type share the same media description.
+ // If Plan B semantics are specified, gets all RtpSenders, created either
+ // through AddStream, AddTrack, or CreateSender. All senders of a specific
+ // media type share the same media description.
+ //
+ // If Unified Plan semantics are specified, gets the RtpSender for each
+ // RtpTransceiver.
virtual std::vector<rtc::scoped_refptr<RtpSenderInterface>> GetSenders()
const {
return std::vector<rtc::scoped_refptr<RtpSenderInterface>>();
}
- // Get all RtpReceivers, created when a remote description is applied.
- // Note that these are "Plan B SDP" RtpReceivers, not "Unified Plan SDP"
- // RtpReceivers, which means that all receivers of a specific media type
- // share the same media description.
+ // If Plan B semantics are specified, gets all RtpReceivers created when a
+ // remote description is applied. All receivers of a specific media type share
+ // the same media description. It is also possible to have a media description
+ // with no associated RtpReceivers, if the directional attribute does not
+ // indicate that the remote peer is sending any media.
//
- // It is also possible to have a media description with no associated
- // RtpReceivers, if the directional attribute does not indicate that the
- // remote peer is sending any media.
+ // If Unified Plan semantics are specified, gets the RtpReceiver for each
+ // RtpTransceiver.
virtual std::vector<rtc::scoped_refptr<RtpReceiverInterface>> GetReceivers()
const {
return std::vector<rtc::scoped_refptr<RtpReceiverInterface>>();
@@ -751,6 +769,7 @@
// Get all RtpTransceivers, created either through AddTransceiver, AddTrack or
// by a remote description applied with SetRemoteDescription.
+ //
// Note: This method is only available when Unified Plan is enabled (see
// RTCConfiguration).
virtual std::vector<rtc::scoped_refptr<RtpTransceiverInterface>>
@@ -767,7 +786,7 @@
// break third party projects. As soon as they have been updated this should
// be changed to "= 0;".
virtual void GetStats(RTCStatsCollectorCallback* callback) {}
- // Clear cached stats in the rtcstatscollector.
+ // Clear cached stats in the RTCStatsCollector.
// Exposed for testing while waiting for automatic cache clear to work.
// https://bugs.webrtc.org/8693
virtual void ClearStatsCache() {}
@@ -1053,7 +1072,7 @@
// Called when the ICE connection receiving status changes.
virtual void OnIceConnectionReceivingChange(bool receiving) {}
- // This is called when a receiver and its track is created.
+ // This is called when a receiver and its track are created.
// TODO(zhihuang): Make this pure virtual when all subclasses implement it.
// Note: This is called with both Plan B and Unified Plan semantics. Unified
// Plan users should prefer OnTrack, OnAddTrack is only called as backwards