From ab6ea6b7b1c1ca0a01e1820faf4b77b3fb2ce229 Mon Sep 17 00:00:00 2001 From: Steve Anton Date: Mon, 26 Feb 2018 14:23:09 -0800 Subject: [PATCH] Miscellaneous updates to PeerConnectionInterface comments NoTry: true Bug: None Change-Id: I9cf4f77e4775ff9b97c71f6a9bdb2d7f159e7048 Reviewed-on: https://webrtc-review.googlesource.com/57240 Commit-Queue: Steve Anton Reviewed-by: Seth Hampson Reviewed-by: Taylor Brandstetter Cr-Commit-Position: refs/heads/master@{#22192} --- api/peerconnectioninterface.h | 75 ++++++++++++++++++++++------------- 1 file changed, 47 insertions(+), 28 deletions(-) diff --git a/api/peerconnectioninterface.h b/api/peerconnectioninterface.h index 9463c34c63..7f7b910dce 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 @@ enum class SdpSemantics { kDefault, kPlanB, kUnifiedPlan }; 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 @@ class PeerConnectionInterface : public rtc::RefCountInterface { 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 @@ class PeerConnectionInterface : public rtc::RefCountInterface { //////////////////////////////////////////////////////////////////////// // 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 @@ class PeerConnectionInterface : public rtc::RefCountInterface { // 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 @@ class PeerConnectionInterface : public rtc::RefCountInterface { // // 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 @@ class PeerConnectionInterface : public rtc::RefCountInterface { // 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 @@ class PeerConnectionInterface : public rtc::RefCountInterface { }; // Accessor methods to active local streams. + // This method is not supported with kUnifiedPlan semantics. Please use + // GetSenders() instead. virtual rtc::scoped_refptr local_streams() = 0; // Accessor methods to remote streams. + // This method is not supported with kUnifiedPlan semantics. Please use + // GetReceivers() instead. virtual rtc::scoped_refptr remote_streams() = 0; @@ -615,11 +618,17 @@ class PeerConnectionInterface : public rtc::RefCountInterface { // 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 @@ class PeerConnectionInterface : public rtc::RefCountInterface { // signature with stream labels. virtual rtc::scoped_refptr AddTrack( MediaStreamTrackInterface* track, - std::vector streams) = 0; + std::vector 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 @@ class PeerConnectionInterface : public rtc::RefCountInterface { // // |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 CreateSender( const std::string& kind, const std::string& stream_id) { return rtc::scoped_refptr(); } - // 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> GetSenders() const { return std::vector>(); } - // 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> GetReceivers() const { return std::vector>(); @@ -751,6 +769,7 @@ class PeerConnectionInterface : public rtc::RefCountInterface { // 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> @@ -767,7 +786,7 @@ class PeerConnectionInterface : public rtc::RefCountInterface { // 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 @@ class PeerConnectionObserver { // 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