Adding more comments to every header file in api/ subdirectory.
Many of these interfaces are not intuitive, or are the way they are for
complex historical reasons, so it would be nice to document these things
for future developers.
Also, many nonstandard things (such as RTCConfiguration options) were
not documented at all before this CL.
BUG=webrtc:7131
TBR=pthatcher@webrtc.org
NOTRY=True
Review-Url: https://codereview.webrtc.org/2680273002
Cr-Commit-Position: refs/heads/master@{#16485}
diff --git a/webrtc/api/datachannelinterface.h b/webrtc/api/datachannelinterface.h
index 5fa657d..92bdee2 100644
--- a/webrtc/api/datachannelinterface.h
+++ b/webrtc/api/datachannelinterface.h
@@ -24,31 +24,43 @@
namespace webrtc {
+// C++ version of: https://www.w3.org/TR/webrtc/#idl-def-rtcdatachannelinit
+// TODO(deadbeef): Use rtc::Optional for the "-1 if unset" things.
struct DataChannelInit {
- DataChannelInit()
- : reliable(false),
- ordered(true),
- maxRetransmitTime(-1),
- maxRetransmits(-1),
- negotiated(false),
- id(-1) {
- }
+ // Deprecated. Reliability is assumed, and channel will be unreliable if
+ // maxRetransmitTime or MaxRetransmits is set.
+ bool reliable = false;
- bool reliable; // Deprecated.
- bool ordered; // True if ordered delivery is required.
- int maxRetransmitTime; // The max period of time in milliseconds in which
- // retransmissions will be sent. After this time, no
- // more retransmissions will be sent. -1 if unset.
- int maxRetransmits; // The max number of retransmissions. -1 if unset.
- std::string protocol; // This is set by the application and opaque to the
- // WebRTC implementation.
- bool negotiated; // True if the channel has been externally negotiated
- // and we do not send an in-band signalling in the
- // form of an "open" message.
- int id; // The stream id, or SID, for SCTP data channels. -1
- // if unset.
+ // True if ordered delivery is required.
+ bool ordered = true;
+
+ // The max period of time in milliseconds in which retransmissions will be
+ // sent. After this time, no more retransmissions will be sent. -1 if unset.
+ //
+ // Cannot be set along with |maxRetransmits|.
+ int maxRetransmitTime = -1;
+
+ // The max number of retransmissions. -1 if unset.
+ //
+ // Cannot be set along with |maxRetransmitTime|.
+ int maxRetransmits = -1;
+
+ // This is set by the application and opaque to the WebRTC implementation.
+ std::string protocol;
+
+ // True if the channel has been externally negotiated and we do not send an
+ // in-band signalling in the form of an "open" message. If this is true, |id|
+ // below must be set; otherwise it should be unset and will be negotiated
+ // in-band.
+ bool negotiated = false;
+
+ // The stream id, or SID, for SCTP data channels. -1 if unset (see above).
+ int id = -1;
};
+// At the JavaScript level, data can be passed in as a string or a blob, so
+// this structure's |binary| flag tells whether the data should be interpreted
+// as binary or text.
struct DataBuffer {
DataBuffer(const rtc::CopyOnWriteBuffer& data, bool binary)
: data(data),
@@ -68,6 +80,10 @@
bool binary;
};
+// Used to implement RTCDataChannel events.
+//
+// The code responding to these callbacks should unwind the stack before
+// using any other webrtc APIs; re-entrancy is not supported.
class DataChannelObserver {
public:
// The data channel state have changed.
@@ -83,7 +99,8 @@
class DataChannelInterface : public rtc::RefCountInterface {
public:
- // Keep in sync with DataChannel.java:State and
+ // C++ version of: https://www.w3.org/TR/webrtc/#idl-def-rtcdatachannelstate
+ // Unlikely to change, but keep in sync with DataChannel.java:State and
// RTCDataChannel.h:RTCDataChannelState.
enum DataState {
kConnecting,
@@ -107,14 +124,20 @@
return "";
}
+ // Used to receive events from the data channel. Only one observer can be
+ // registered at a time. UnregisterObserver should be called before the
+ // observer object is destroyed.
virtual void RegisterObserver(DataChannelObserver* observer) = 0;
virtual void UnregisterObserver() = 0;
+
// The label attribute represents a label that can be used to distinguish this
// DataChannel object from other DataChannel objects.
virtual std::string label() const = 0;
- virtual bool reliable() const = 0;
- // TODO(tommyw): Remove these dummy implementations when all classes have
+ // The accessors below simply return the properties from the DataChannelInit
+ // the data channel was constructed with.
+ virtual bool reliable() const = 0;
+ // TODO(deadbeef): Remove these dummy implementations when all classes have
// implemented these APIs. They should all just return the values the
// DataChannel was created with.
virtual bool ordered() const { return false; }
@@ -123,18 +146,33 @@
virtual std::string protocol() const { return std::string(); }
virtual bool negotiated() const { return false; }
+ // Returns the ID from the DataChannelInit, if it was negotiated out-of-band.
+ // If negotiated in-band, this ID will be populated once the DTLS role is
+ // determined, and until then this will return -1.
virtual int id() const = 0;
virtual DataState state() const = 0;
virtual uint32_t messages_sent() const = 0;
virtual uint64_t bytes_sent() const = 0;
virtual uint32_t messages_received() const = 0;
virtual uint64_t bytes_received() const = 0;
- // The buffered_amount returns the number of bytes of application data
- // (UTF-8 text and binary data) that have been queued using SendBuffer but
- // have not yet been transmitted to the network.
+
+ // Returns the number of bytes of application data (UTF-8 text and binary
+ // data) that have been queued using Send but have not yet been processed at
+ // the SCTP level. See comment above Send below.
virtual uint64_t buffered_amount() const = 0;
+
+ // Begins the graceful data channel closing procedure. See:
+ // https://tools.ietf.org/html/draft-ietf-rtcweb-data-channel-13#section-6.7
virtual void Close() = 0;
- // Sends |data| to the remote peer.
+
+ // Sends |data| to the remote peer. If the data can't be sent at the SCTP
+ // level (due to congestion control), it's buffered at the data channel level,
+ // up to a maximum of 16MB. If Send is called while this buffer is full, the
+ // data channel will be closed abruptly.
+ //
+ // So, it's important to use buffered_amount() and OnBufferedAmountChange to
+ // ensure the data channel is used efficiently but without filling this
+ // buffer.
virtual bool Send(const DataBuffer& buffer) = 0;
protected:
diff --git a/webrtc/api/dtmfsenderinterface.h b/webrtc/api/dtmfsenderinterface.h
index a4d270d..a1ef3ec 100644
--- a/webrtc/api/dtmfsenderinterface.h
+++ b/webrtc/api/dtmfsenderinterface.h
@@ -16,12 +16,11 @@
#include "webrtc/api/mediastreaminterface.h"
#include "webrtc/base/refcount.h"
-// This file contains interfaces for DtmfSender.
-
namespace webrtc {
-// DtmfSender callback interface. Application should implement this interface
-// to get notifications from the DtmfSender.
+// DtmfSender callback interface, used to implement RTCDtmfSender events.
+// Applications should implement this interface to get notifications from the
+// DtmfSender.
class DtmfSenderObserverInterface {
public:
// Triggered when DTMF |tone| is sent.
@@ -35,13 +34,18 @@
// The interface of native implementation of the RTCDTMFSender defined by the
// WebRTC W3C Editor's Draft.
+// See: https://www.w3.org/TR/webrtc/#peer-to-peer-dtmf
class DtmfSenderInterface : public rtc::RefCountInterface {
public:
+ // Used to receive events from the DTMF sender. Only one observer can be
+ // registered at a time. UnregisterObserver should be called before the
+ // observer object is destroyed.
virtual void RegisterObserver(DtmfSenderObserverInterface* observer) = 0;
virtual void UnregisterObserver() = 0;
- // Returns true if this DtmfSender is capable of sending DTMF.
- // Otherwise returns false.
+ // Returns true if this DtmfSender is capable of sending DTMF. Otherwise
+ // returns false. To be able to send DTMF, the associated RtpSender must be
+ // able to send packets, and a "telephone-event" codec must be negotiated.
virtual bool CanInsertDtmf() = 0;
// Queues a task that sends the DTMF |tones|. The |tones| parameter is treated
@@ -49,20 +53,26 @@
// * generate the associated DTMF tones. The characters a to d are equivalent
// to A to D. The character ',' indicates a delay of 2 seconds before
// processing the next character in the tones parameter.
+ //
// Unrecognized characters are ignored.
+ //
// The |duration| parameter indicates the duration in ms to use for each
- // character passed in the |tones| parameter.
- // The duration cannot be more than 6000 or less than 70.
- // The |inter_tone_gap| parameter indicates the gap between tones in ms.
- // The |inter_tone_gap| must be at least 50 ms but should be as short as
+ // character passed in the |tones| parameter. The duration cannot be more
+ // than 6000 or less than 70.
+ //
+ // The |inter_tone_gap| parameter indicates the gap between tones in ms. The
+ // |inter_tone_gap| must be at least 50 ms but should be as short as
// possible.
+ //
// If InsertDtmf is called on the same object while an existing task for this
// object to generate DTMF is still running, the previous task is canceled.
// Returns true on success and false on failure.
virtual bool InsertDtmf(const std::string& tones, int duration,
int inter_tone_gap) = 0;
- // Returns the track given as argument to the constructor.
+ // Returns the track given as argument to the constructor. Only exists for
+ // backwards compatibilty; now that DtmfSenders are tied to RtpSenders, it's
+ // no longer relevant.
virtual const AudioTrackInterface* track() const = 0;
// Returns the tones remaining to be played out.
diff --git a/webrtc/api/jsep.h b/webrtc/api/jsep.h
index 37aed46..d19ae3c 100644
--- a/webrtc/api/jsep.h
+++ b/webrtc/api/jsep.h
@@ -8,7 +8,14 @@
* be found in the AUTHORS file in the root of the source tree.
*/
-// Interfaces matching the draft-ietf-rtcweb-jsep-01.
+// This file contains declarations of interfaces that wrap SDP-related
+// constructs; session descriptions and ICE candidates. The inner "cricket::"
+// objects shouldn't be accessed directly; the intention is that an application
+// using the PeerConnection API only creates these objects from strings, and
+// them passes them into the PeerConnection.
+//
+// Though in the future, we're planning to provide an SDP parsing API, with a
+// structure more friendly than cricket::SessionDescription.
#ifndef WEBRTC_API_JSEP_H_
#define WEBRTC_API_JSEP_H_
@@ -36,18 +43,21 @@
};
// Class representation of an ICE candidate.
+//
// An instance of this interface is supposed to be owned by one class at
// a time and is therefore not expected to be thread safe.
+//
+// An instance can be created by CreateIceCandidate.
class IceCandidateInterface {
public:
virtual ~IceCandidateInterface() {}
- /// If present, this contains the identierfier of the "media stream
- // identification" as defined in [RFC 3388] for m-line this candidate is
- // assocated with.
+ // If present, this is the value of the "a=mid" attribute of the candidate's
+ // m= section in SDP, which identifies the m= section.
virtual std::string sdp_mid() const = 0;
- // This indeicates the index (starting at zero) of m-line in the SDP this
- // candidate is assocated with.
+ // This indicates the index (starting at zero) of m= section this candidate
+ // is assocated with. Needed when an endpoint doesn't support MIDs.
virtual int sdp_mline_index() const = 0;
+ // Only for use internally.
virtual const cricket::Candidate& candidate() const = 0;
// Creates a SDP-ized form of this candidate.
virtual bool ToString(std::string* out) const = 0;
@@ -55,15 +65,14 @@
// Creates a IceCandidateInterface based on SDP string.
// Returns NULL if the sdp string can't be parsed.
-// |error| can be NULL if doesn't care about the failure reason.
+// |error| may be NULL.
IceCandidateInterface* CreateIceCandidate(const std::string& sdp_mid,
int sdp_mline_index,
const std::string& sdp,
SdpParseError* error);
-// This class represents a collection of candidates for a specific m-line.
-// This class is used in SessionDescriptionInterface to represent all known
-// candidates for a certain m-line.
+// This class represents a collection of candidates for a specific m= section.
+// Used in SessionDescriptionInterface.
class IceCandidateCollection {
public:
virtual ~IceCandidateCollection() {}
@@ -73,9 +82,12 @@
virtual const IceCandidateInterface* at(size_t index) const = 0;
};
-// Class representation of a Session description.
-// An instance of this interface is supposed to be owned by one class at
-// a time and is therefore not expected to be thread safe.
+// Class representation of an SDP session description.
+//
+// An instance of this interface is supposed to be owned by one class at a time
+// and is therefore not expected to be thread safe.
+//
+// An instance can be created by CreateSessionDescription.
class SessionDescriptionInterface {
public:
// Supported types:
@@ -84,44 +96,59 @@
static const char kAnswer[];
virtual ~SessionDescriptionInterface() {}
+
+ // Only for use internally.
virtual cricket::SessionDescription* description() = 0;
virtual const cricket::SessionDescription* description() const = 0;
+
// Get the session id and session version, which are defined based on
// RFC 4566 for the SDP o= line.
virtual std::string session_id() const = 0;
virtual std::string session_version() const = 0;
+
+ // kOffer/kPrAnswer/kAnswer
virtual std::string type() const = 0;
+
// Adds the specified candidate to the description.
+ //
// Ownership is not transferred.
- // Returns false if the session description does not have a media section that
- // corresponds to the |candidate| label.
+ //
+ // Returns false if the session description does not have a media section
+ // that corresponds to |candidate.sdp_mid()| or
+ // |candidate.sdp_mline_index()|.
virtual bool AddCandidate(const IceCandidateInterface* candidate) = 0;
- // Removes the candidates from the description.
+
+ // Removes the candidates from the description, if found.
+ //
// Returns the number of candidates removed.
virtual size_t RemoveCandidates(
const std::vector<cricket::Candidate>& candidates) { return 0; }
- // Returns the number of m- lines in the session description.
+ // Returns the number of m= sections in the session description.
virtual size_t number_of_mediasections() const = 0;
- // Returns a collection of all candidates that belong to a certain m-line
+
+ // Returns a collection of all candidates that belong to a certain m=
+ // section.
virtual const IceCandidateCollection* candidates(
size_t mediasection_index) const = 0;
+
// Serializes the description to SDP.
virtual bool ToString(std::string* out) const = 0;
};
-// Creates a SessionDescriptionInterface based on SDP string and the type.
+// Creates a SessionDescriptionInterface based on the SDP string and the type.
// Returns NULL if the sdp string can't be parsed or the type is unsupported.
-// |error| can be NULL if doesn't care about the failure reason.
+// |error| may be NULL.
SessionDescriptionInterface* CreateSessionDescription(const std::string& type,
const std::string& sdp,
SdpParseError* error);
-// Jsep CreateOffer and CreateAnswer callback interface.
+// CreateOffer and CreateAnswer callback interface.
class CreateSessionDescriptionObserver : public rtc::RefCountInterface {
public:
- // The implementation of the CreateSessionDescriptionObserver takes
- // the ownership of the |desc|.
+ // This callback transfers the ownership of the |desc|.
+ // TODO(deadbeef): Make this take an std::unique_ptr<> to avoid confusion
+ // around ownership.
virtual void OnSuccess(SessionDescriptionInterface* desc) = 0;
virtual void OnFailure(const std::string& error) = 0;
@@ -129,7 +156,7 @@
~CreateSessionDescriptionObserver() {}
};
-// Jsep SetLocalDescription and SetRemoteDescription callback interface.
+// SetLocalDescription and SetRemoteDescription callback interface.
class SetSessionDescriptionObserver : public rtc::RefCountInterface {
public:
virtual void OnSuccess() = 0;
diff --git a/webrtc/api/jsepicecandidate.h b/webrtc/api/jsepicecandidate.h
index af06431..f068637 100644
--- a/webrtc/api/jsepicecandidate.h
+++ b/webrtc/api/jsepicecandidate.h
@@ -8,7 +8,8 @@
* be found in the AUTHORS file in the root of the source tree.
*/
-// Implements the IceCandidateInterface.
+// TODO(deadbeef): Move this out of api/; it's an implementation detail and
+// shouldn't be used externally.
#ifndef WEBRTC_API_JSEPICECANDIDATE_H_
#define WEBRTC_API_JSEPICECANDIDATE_H_
@@ -23,13 +24,14 @@
namespace webrtc {
+// Implementation of IceCandidateInterface.
class JsepIceCandidate : public IceCandidateInterface {
public:
JsepIceCandidate(const std::string& sdp_mid, int sdp_mline_index);
JsepIceCandidate(const std::string& sdp_mid, int sdp_mline_index,
const cricket::Candidate& candidate);
~JsepIceCandidate();
- // |error| can be NULL if don't care about the failure reason.
+ // |err| may be NULL.
bool Initialize(const std::string& sdp, SdpParseError* err);
void SetCandidate(const cricket::Candidate& candidate) {
candidate_ = candidate;
@@ -51,8 +53,7 @@
RTC_DISALLOW_COPY_AND_ASSIGN(JsepIceCandidate);
};
-// Implementation of IceCandidateCollection.
-// This implementation stores JsepIceCandidates.
+// Implementation of IceCandidateCollection which stores JsepIceCandidates.
class JsepCandidateCollection : public IceCandidateCollection {
public:
JsepCandidateCollection() {}
@@ -66,6 +67,8 @@
}
virtual bool HasCandidate(const IceCandidateInterface* candidate) const;
// Adds and takes ownership of the JsepIceCandidate.
+ // TODO(deadbeef): Make this use an std::unique_ptr<>, so ownership logic is
+ // more clear.
virtual void add(JsepIceCandidate* candidate) {
candidates_.push_back(candidate);
}
@@ -73,6 +76,7 @@
return candidates_[index];
}
// Removes the candidate that has a matching address and protocol.
+ //
// Returns the number of candidates that were removed.
size_t remove(const cricket::Candidate& candidate);
diff --git a/webrtc/api/jsepsessiondescription.h b/webrtc/api/jsepsessiondescription.h
index 8f2ab5f..b5e1b4f 100644
--- a/webrtc/api/jsepsessiondescription.h
+++ b/webrtc/api/jsepsessiondescription.h
@@ -8,7 +8,8 @@
* be found in the AUTHORS file in the root of the source tree.
*/
-// Implements the SessionDescriptionInterface.
+// TODO(deadbeef): Move this out of api/; it's an implementation detail and
+// shouldn't be used externally.
#ifndef WEBRTC_API_JSEPSESSIONDESCRIPTION_H_
#define WEBRTC_API_JSEPSESSIONDESCRIPTION_H_
@@ -28,15 +29,18 @@
namespace webrtc {
+// Implementation of SessionDescriptionInterface.
class JsepSessionDescription : public SessionDescriptionInterface {
public:
explicit JsepSessionDescription(const std::string& type);
virtual ~JsepSessionDescription();
- // |error| can be NULL if don't care about the failure reason.
+ // |error| may be NULL.
bool Initialize(const std::string& sdp, SdpParseError* error);
// Takes ownership of |description|.
+ // TODO(deadbeef): Make this use an std::unique_ptr<>, so ownership logic is
+ // more clear.
bool Initialize(cricket::SessionDescription* description,
const std::string& session_id,
const std::string& session_version);
@@ -56,7 +60,7 @@
virtual std::string type() const {
return type_;
}
- // Allow changing the type. Used for testing.
+ // Allows changing the type. Used for testing.
void set_type(const std::string& type) { type_ = type; }
virtual bool AddCandidate(const IceCandidateInterface* candidate);
virtual size_t RemoveCandidates(
diff --git a/webrtc/api/mediaconstraintsinterface.h b/webrtc/api/mediaconstraintsinterface.h
index 2017890..8dafea4 100644
--- a/webrtc/api/mediaconstraintsinterface.h
+++ b/webrtc/api/mediaconstraintsinterface.h
@@ -28,9 +28,12 @@
namespace webrtc {
-// MediaConstraintsInterface
// Interface used for passing arguments about media constraints
// to the MediaStream and PeerConnection implementation.
+//
+// Constraints may be either "mandatory", which means that unless satisfied,
+// the method taking the constraints should fail, or "optional", which means
+// they may not be satisfied..
class MediaConstraintsInterface {
public:
struct Constraint {
diff --git a/webrtc/api/mediastreaminterface.h b/webrtc/api/mediastreaminterface.h
index a52f0c7..59ca66c 100644
--- a/webrtc/api/mediastreaminterface.h
+++ b/webrtc/api/mediastreaminterface.h
@@ -53,8 +53,8 @@
virtual ~NotifierInterface() {}
};
-// Base class for sources. A MediaStreamTrack have an underlying source that
-// provide media. A source can be shared with multiple tracks.
+// Base class for sources. A MediaStreamTrack has an underlying source that
+// provides media. A source can be shared by multiple tracks.
class MediaSourceInterface : public rtc::RefCountInterface,
public NotifierInterface {
public:
@@ -73,7 +73,8 @@
virtual ~MediaSourceInterface() {}
};
-// Information about a track.
+// C++ version of MediaStreamTrack.
+// See: https://www.w3.org/TR/mediacapture-streams/#mediastreamtrack
class MediaStreamTrackInterface : public rtc::RefCountInterface,
public NotifierInterface {
public:
@@ -90,17 +91,24 @@
// object is a subclass of VideoTrackInterface. It is typically used
// to protect a static_cast<> to the corresponding subclass.
virtual std::string kind() const = 0;
+
+ // Track identifier.
virtual std::string id() const = 0;
+
+ // A disabled track will produce silence (if audio) or black frames (if
+ // video). Can be disabled and re-enabled.
virtual bool enabled() const = 0;
- virtual TrackState state() const = 0;
virtual bool set_enabled(bool enable) = 0;
+ // Live or ended. A track will never be live again after becoming ended.
+ virtual TrackState state() const = 0;
+
protected:
virtual ~MediaStreamTrackInterface() {}
};
-// VideoTrackSourceInterface is a reference counted source used for VideoTracks.
-// The same source can be used in multiple VideoTracks.
+// VideoTrackSourceInterface is a reference counted source used for
+// VideoTracks. The same source can be used by multiple VideoTracks.
class VideoTrackSourceInterface
: public MediaSourceInterface,
public rtc::VideoSourceInterface<VideoFrame> {
@@ -114,7 +122,7 @@
// Indicates that parameters suitable for screencasts should be automatically
// applied to RtpSenders.
// TODO(perkj): Remove these once all known applications have moved to
- // explicitly setting suitable parameters for screencasts and dont' need this
+ // explicitly setting suitable parameters for screencasts and don't need this
// implicit behavior.
virtual bool is_screencast() const = 0;
@@ -125,9 +133,10 @@
// the encoder.
virtual rtc::Optional<bool> needs_denoising() const = 0;
- // Returns false if no stats are available, e.g, for a remote
- // source, or a source which has not seen its first frame yet.
- // Should avoid blocking.
+ // Returns false if no stats are available, e.g, for a remote source, or a
+ // source which has not seen its first frame yet.
+ //
+ // Implementation should avoid blocking.
virtual bool GetStats(Stats* stats) = 0;
protected:
@@ -143,7 +152,8 @@
// See https://crbug.com/653531 and https://github.com/WICG/mst-content-hint.
enum class ContentHint { kNone, kFluid, kDetailed };
- // Register a video sink for this track.
+ // Register a video sink for this track. Used to connect the track to the
+ // underlying video engine.
void AddOrUpdateSink(rtc::VideoSinkInterface<VideoFrame>* sink,
const rtc::VideoSinkWants& wants) override {}
void RemoveSink(rtc::VideoSinkInterface<VideoFrame>* sink) override {}
@@ -171,7 +181,7 @@
};
// AudioSourceInterface is a reference counted source used for AudioTracks.
-// The same source can be used in multiple AudioTracks.
+// The same source can be used by multiple AudioTracks.
class AudioSourceInterface : public MediaSourceInterface {
public:
class AudioObserver {
@@ -182,14 +192,15 @@
virtual ~AudioObserver() {}
};
- // TODO(xians): Makes all the interface pure virtual after Chrome has their
- // implementations.
- // Sets the volume to the source. |volume| is in the range of [0, 10].
+ // TODO(deadbeef): Makes all the interfaces pure virtual after they're
+ // implemented in chromium.
+
+ // Sets the volume of the source. |volume| is in the range of [0, 10].
// TODO(tommi): This method should be on the track and ideally volume should
// be applied in the track in a way that does not affect clones of the track.
virtual void SetVolume(double volume) {}
- // Registers/unregisters observer to the audio source.
+ // Registers/unregisters observers to the audio source.
virtual void RegisterAudioObserver(AudioObserver* observer) {}
virtual void UnregisterAudioObserver(AudioObserver* observer) {}
@@ -235,7 +246,8 @@
class AudioTrackInterface : public MediaStreamTrackInterface {
public:
- // TODO(xians): Figure out if the following interface should be const or not.
+ // TODO(deadbeef): Figure out if the following interface should be const or
+ // not.
virtual AudioSourceInterface* GetSource() const = 0;
// Add/Remove a sink that will receive the audio data from the track.
@@ -244,15 +256,16 @@
// Get the signal level from the audio track.
// Return true on success, otherwise false.
- // TODO(xians): Change the interface to int GetSignalLevel() and pure virtual
- // after Chrome has the correct implementation of the interface.
+ // TODO(deadbeef): Change the interface to int GetSignalLevel() and pure
+ // virtual after it's implemented in chromium.
virtual bool GetSignalLevel(int* level) { return false; }
// Get the audio processor used by the audio track. Return NULL if the track
// does not have any processor.
- // TODO(xians): Make the interface pure virtual.
- virtual rtc::scoped_refptr<AudioProcessorInterface>
- GetAudioProcessor() { return NULL; }
+ // TODO(deadbeef): Make the interface pure virtual.
+ virtual rtc::scoped_refptr<AudioProcessorInterface> GetAudioProcessor() {
+ return nullptr;
+ }
protected:
virtual ~AudioTrackInterface() {}
@@ -263,6 +276,14 @@
typedef std::vector<rtc::scoped_refptr<VideoTrackInterface> >
VideoTrackVector;
+// C++ version of https://www.w3.org/TR/mediacapture-streams/#mediastream.
+//
+// A major difference is that remote audio/video tracks (received by a
+// PeerConnection/RtpReceiver) are not synchronized simply by adding them to
+// the same stream; a session description with the correct "a=msid" attributes
+// must be pushed down.
+//
+// Thus, this interface acts as simply a container for tracks.
class MediaStreamInterface : public rtc::RefCountInterface,
public NotifierInterface {
public:
diff --git a/webrtc/api/mediastreamproxy.h b/webrtc/api/mediastreamproxy.h
index fe11300..15b40ed 100644
--- a/webrtc/api/mediastreamproxy.h
+++ b/webrtc/api/mediastreamproxy.h
@@ -18,6 +18,8 @@
namespace webrtc {
+// TODO(deadbeef): Move this to .cc file and out of api/. What threads methods
+// are called on is an implementation detail.
BEGIN_SIGNALING_PROXY_MAP(MediaStream)
PROXY_SIGNALING_THREAD_DESTRUCTOR()
PROXY_CONSTMETHOD0(std::string, label)
diff --git a/webrtc/api/mediastreamtrackproxy.h b/webrtc/api/mediastreamtrackproxy.h
index 9a3cb42..605f3f2 100644
--- a/webrtc/api/mediastreamtrackproxy.h
+++ b/webrtc/api/mediastreamtrackproxy.h
@@ -21,6 +21,9 @@
namespace webrtc {
+// TODO(deadbeef): Move this to .cc file and out of api/. What threads methods
+// are called on is an implementation detail.
+
BEGIN_SIGNALING_PROXY_MAP(AudioTrack)
PROXY_SIGNALING_THREAD_DESTRUCTOR()
PROXY_CONSTMETHOD0(std::string, kind)
diff --git a/webrtc/api/notifier.h b/webrtc/api/notifier.h
index eabaa3c..878d01c 100644
--- a/webrtc/api/notifier.h
+++ b/webrtc/api/notifier.h
@@ -18,7 +18,8 @@
namespace webrtc {
-// Implement a template version of a notifier.
+// Implements a template version of a notifier.
+// TODO(deadbeef): This is an implementation detail; move out of api/.
template <class T>
class Notifier : public T {
public:
diff --git a/webrtc/api/peerconnectionfactoryproxy.h b/webrtc/api/peerconnectionfactoryproxy.h
index d41aad2..e829cca 100644
--- a/webrtc/api/peerconnectionfactoryproxy.h
+++ b/webrtc/api/peerconnectionfactoryproxy.h
@@ -21,6 +21,8 @@
namespace webrtc {
+// TODO(deadbeef): Move this to .cc file and out of api/. What threads methods
+// are called on is an implementation detail.
BEGIN_SIGNALING_PROXY_MAP(PeerConnectionFactory)
PROXY_SIGNALING_THREAD_DESTRUCTOR()
PROXY_METHOD1(void, SetOptions, const Options&)
diff --git a/webrtc/api/peerconnectioninterface.h b/webrtc/api/peerconnectioninterface.h
index 6cc8be7..ea94f50 100644
--- a/webrtc/api/peerconnectioninterface.h
+++ b/webrtc/api/peerconnectioninterface.h
@@ -10,43 +10,59 @@
// This file contains the PeerConnection interface as defined in
// http://dev.w3.org/2011/webrtc/editor/webrtc.html#peer-to-peer-connections.
-// Applications must use this interface to implement peerconnection.
-// PeerConnectionFactory class provides factory methods to create
-// peerconnection, mediastream and media tracks objects.
//
-// The Following steps are needed to setup a typical call using Jsep.
+// The PeerConnectionFactory class provides factory methods to create
+// PeerConnection, MediaStream and MediaStreamTrack objects.
+//
+// The following steps are needed to setup a typical call using WebRTC:
+//
// 1. Create a PeerConnectionFactoryInterface. Check constructors for more
// information about input parameters.
-// 2. Create a PeerConnection object. Provide a configuration string which
-// points either to stun or turn server to generate ICE candidates and provide
-// an object that implements the PeerConnectionObserver interface.
-// 3. Create local MediaStream and MediaTracks using the PeerConnectionFactory
-// and add it to PeerConnection by calling AddStream.
-// 4. Create an offer and serialize it and send it to the remote peer.
-// 5. Once an ice candidate have been found PeerConnection will call the
+//
+// 2. Create a PeerConnection object. Provide a configuration struct which
+// points to STUN and/or TURN servers used to generate ICE candidates, and
+// provide an object that implements the PeerConnectionObserver interface,
+// which is used to receive callbacks from the PeerConnection.
+//
+// 3. Create local MediaStreamTracks using the PeerConnectionFactory and add
+// them to PeerConnection by calling AddTrack (or legacy method, AddStream).
+//
+// 4. Create an offer, call SetLocalDescription with it, serialize it, and send
+// it to the remote peer
+//
+// 5. Once an ICE candidate has been gathered, the PeerConnection will call the
// observer function OnIceCandidate. The candidates must also be serialized and
// sent to the remote peer.
+//
// 6. Once an answer is received from the remote peer, call
-// SetLocalSessionDescription with the offer and SetRemoteSessionDescription
-// with the remote answer.
+// SetRemoteDescription with the remote answer.
+//
// 7. Once a remote candidate is received from the remote peer, provide it to
-// the peerconnection by calling AddIceCandidate.
-
-
-// The Receiver of a call can decide to accept or reject the call.
-// This decision will be taken by the application not peerconnection.
-// If application decides to accept the call
+// the PeerConnection by calling AddIceCandidate.
+//
+// The receiver of a call (assuming the application is "call"-based) can decide
+// to accept or reject the call; this decision will be taken by the application,
+// not the PeerConnection.
+//
+// If the application decides to accept the call, it should:
+//
// 1. Create PeerConnectionFactoryInterface if it doesn't exist.
+//
// 2. Create a new PeerConnection.
+//
// 3. Provide the remote offer to the new PeerConnection object by calling
-// SetRemoteSessionDescription.
+// SetRemoteDescription.
+//
// 4. Generate an answer to the remote offer by calling CreateAnswer and send it
// back to the remote peer.
+//
// 5. Provide the local answer to the new PeerConnection by calling
-// SetLocalSessionDescription with the answer.
-// 6. Provide the remote ice candidates by calling AddIceCandidate.
-// 7. Once a candidate have been found PeerConnection will call the observer
-// function OnIceCandidate. Send these candidates to the remote peer.
+// SetLocalDescription with the answer.
+//
+// 6. Provide the remote ICE candidates by calling AddIceCandidate.
+//
+// 7. Once a candidate has been gathered, the PeerConnection will call the
+// observer function OnIceCandidate. Send these candidates to the remote peer.
#ifndef WEBRTC_API_PEERCONNECTIONINTERFACE_H_
#define WEBRTC_API_PEERCONNECTIONINTERFACE_H_
@@ -341,53 +357,143 @@
static const int kAudioJitterBufferMaxPackets = 50;
// ICE connection receiving timeout for aggressive configuration.
static const int kAggressiveIceConnectionReceivingTimeout = 1000;
- // TODO(pthatcher): Rename this ice_transport_type, but update
- // Chromium at the same time.
- IceTransportsType type = kAll;
+
+ ////////////////////////////////////////////////////////////////////////
+ // The below few fields mirror the standard RTCConfiguration dictionary:
+ // https://www.w3.org/TR/webrtc/#rtcconfiguration-dictionary
+ ////////////////////////////////////////////////////////////////////////
+
// TODO(pthatcher): Rename this ice_servers, but update Chromium
// at the same time.
IceServers servers;
+ // TODO(pthatcher): Rename this ice_transport_type, but update
+ // Chromium at the same time.
+ IceTransportsType type = kAll;
BundlePolicy bundle_policy = kBundlePolicyBalanced;
RtcpMuxPolicy rtcp_mux_policy = kRtcpMuxPolicyRequire;
+ std::vector<rtc::scoped_refptr<rtc::RTCCertificate>> certificates;
+ int ice_candidate_pool_size = 0;
+
+ //////////////////////////////////////////////////////////////////////////
+ // The below fields correspond to constraints from the deprecated
+ // constraints interface for constructing a PeerConnection.
+ //
+ // rtc::Optional fields can be "missing", in which case the implementation
+ // default will be used.
+ //////////////////////////////////////////////////////////////////////////
+
+ // If set to true, don't gather IPv6 ICE candidates.
+ // TODO(deadbeef): Remove this? IPv6 support has long stopped being
+ // experimental
+ bool disable_ipv6 = false;
+
+ // If set to true, use RTP data channels instead of SCTP.
+ // TODO(deadbeef): Remove this. We no longer commit to supporting RTP data
+ // channels, though some applications are still working on moving off of
+ // them.
+ bool enable_rtp_data_channel = false;
+
+ // Minimum bitrate at which screencast video tracks will be encoded at.
+ // This means adding padding bits up to this bitrate, which can help
+ // when switching from a static scene to one with motion.
+ rtc::Optional<int> screencast_min_bitrate;
+
+ // Use new combined audio/video bandwidth estimation?
+ rtc::Optional<bool> combined_audio_video_bwe;
+
+ // Can be used to disable DTLS-SRTP. This should never be done, but can be
+ // useful for testing purposes, for example in setting up a loopback call
+ // with a single PeerConnection.
+ rtc::Optional<bool> enable_dtls_srtp;
+
+ /////////////////////////////////////////////////
+ // The below fields are not part of the standard.
+ /////////////////////////////////////////////////
+
+ // Can be used to disable TCP candidate generation.
TcpCandidatePolicy tcp_candidate_policy = kTcpCandidatePolicyEnabled;
+
+ // Can be used to avoid gathering candidates for a "higher cost" network,
+ // if a lower cost one exists. For example, if both Wi-Fi and cellular
+ // interfaces are available, this could be used to avoid using the cellular
+ // interface.
CandidateNetworkPolicy candidate_network_policy =
kCandidateNetworkPolicyAll;
+
+ // The maximum number of packets that can be stored in the NetEq audio
+ // jitter buffer. Can be reduced to lower tolerated audio latency.
int audio_jitter_buffer_max_packets = kAudioJitterBufferMaxPackets;
+
+ // Whether to use the NetEq "fast mode" which will accelerate audio quicker
+ // if it falls behind.
bool audio_jitter_buffer_fast_accelerate = false;
- int ice_connection_receiving_timeout = kUndefined; // ms
- int ice_backup_candidate_pair_ping_interval = kUndefined; // ms
+
+ // Timeout in milliseconds before an ICE candidate pair is considered to be
+ // "not receiving", after which a lower priority candidate pair may be
+ // selected.
+ int ice_connection_receiving_timeout = kUndefined;
+
+ // Interval in milliseconds at which an ICE "backup" candidate pair will be
+ // pinged. This is a candidate pair which is not actively in use, but may
+ // be switched to if the active candidate pair becomes unusable.
+ //
+ // This is relevant mainly to Wi-Fi/cell handoff; the application may not
+ // want this backup cellular candidate pair pinged frequently, since it
+ // consumes data/battery.
+ int ice_backup_candidate_pair_ping_interval = kUndefined;
+
+ // Can be used to enable continual gathering, which means new candidates
+ // will be gathered as network interfaces change. Note that if continual
+ // gathering is used, the candidate removal API should also be used, to
+ // avoid an ever-growing list of candidates.
ContinualGatheringPolicy continual_gathering_policy = GATHER_ONCE;
- std::vector<rtc::scoped_refptr<rtc::RTCCertificate>> certificates;
+
+ // If set to true, candidate pairs will be pinged in order of most likely
+ // to work (which means using a TURN server, generally), rather than in
+ // standard priority order.
bool prioritize_most_likely_ice_candidate_pairs = false;
+
struct cricket::MediaConfig media_config;
- // Flags corresponding to values set by constraint flags.
- // rtc::Optional flags can be "missing", in which case the webrtc
- // default applies.
- bool disable_ipv6 = false;
- bool enable_rtp_data_channel = false;
+
+ // This doesn't currently work. For a while we were working on adding QUIC
+ // data channel support to PeerConnection, but decided on a different
+ // approach, and that code hasn't been updated for a while.
bool enable_quic = false;
- rtc::Optional<int> screencast_min_bitrate;
- rtc::Optional<bool> combined_audio_video_bwe;
- rtc::Optional<bool> enable_dtls_srtp;
- int ice_candidate_pool_size = 0;
+
+ // If set to true, only one preferred TURN allocation will be used per
+ // network interface. UDP is preferred over TCP and IPv6 over IPv4. This
+ // can be used to cut down on the number of candidate pairings.
bool prune_turn_ports = false;
+
// If set to true, this means the ICE transport should presume TURN-to-TURN
// candidate pairs will succeed, even before a binding response is received.
+ // This can be used to optimize the initial connection time, since the DTLS
+ // handshake can begin immediately.
bool presume_writable_when_fully_relayed = false;
+
// If true, "renomination" will be added to the ice options in the transport
// description.
+ // See: https://tools.ietf.org/html/draft-thatcher-ice-renomination-00
bool enable_ice_renomination = false;
- // If true, ICE role is redetermined when peerconnection sets a local
- // transport description that indicates an ICE restart.
+
+ // If true, the ICE role is re-determined when the PeerConnection sets a
+ // local transport description that indicates an ICE restart.
+ //
+ // This is standard RFC5245 ICE behavior, but causes unnecessary role
+ // thrashing, so an application may wish to avoid it. This role
+ // re-determining was removed in ICEbis (ICE v2).
bool redetermine_role_on_ice_restart = true;
+
// If set, the min interval (max rate) at which we will send ICE checks
// (STUN pings), in milliseconds.
rtc::Optional<int> ice_check_min_interval;
+
//
// Don't forget to update operator== if adding something.
//
};
+ // See: https://www.w3.org/TR/webrtc/#idl-def-rtcofferansweroptions
struct RTCOfferAnswerOptions {
static const int kUndefined = -1;
static const int kMaxOfferToReceiveMedia = 1;
@@ -395,10 +501,23 @@
// 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.
+ //
+ // 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.
+ // Values greater than 1 are treated the same.
+ //
+ // If set to 0, the generated directional attribute will not include the
+ // "recv" direction (meaning it will be "sendonly" or "inactive".
int offer_to_receive_video = kUndefined;
int offer_to_receive_audio = kUndefined;
+
bool voice_activity_detection = true;
bool ice_restart = false;
+
+ // If true, will offer to BUNDLE audio/video/data together. Not to be
+ // confused with RTCP mux (multiplexing RTP and RTCP together).
bool use_rtp_mux = true;
RTCOfferAnswerOptions() = default;
@@ -435,16 +554,25 @@
// Add a new MediaStream to be sent on this PeerConnection.
// Note that a SessionDescription negotiation is needed before the
// remote peer can receive the stream.
+ //
+ // This has been removed from the standard in favor of a track-based API. So,
+ // this is equivalent to simply calling AddTrack for each track within the
+ // 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.
virtual bool AddStream(MediaStreamInterface* stream) = 0;
// Remove a MediaStream from this PeerConnection.
- // Note that a SessionDescription negotiation is need before the
+ // Note that a SessionDescription negotiation is needed before the
// remote peer is notified.
virtual void RemoveStream(MediaStreamInterface* stream) = 0;
// TODO(deadbeef): Make the following two methods pure virtual once
// implemented by all subclasses of PeerConnectionInterface.
- // Add a new MediaStreamTrack to be sent on this PeerConnection.
+
+ // Add a new MediaStreamTrack to be sent on this PeerConnection, and return
+ // the newly created RtpSender.
+ //
// |streams| indicates which stream labels the track should be associated
// with.
virtual rtc::scoped_refptr<RtpSenderInterface> AddTrack(
@@ -459,13 +587,25 @@
return false;
}
- // Returns pointer to the created DtmfSender on success.
- // Otherwise returns NULL.
+ // Returns pointer to a DtmfSender on success. Otherwise returns NULL.
+ //
+ // This API is no longer part of the standard; instead DtmfSenders are
+ // obtained from RtpSenders. Which is what the implementation does; it finds
+ // an RtpSender for |track| and just returns its DtmfSender.
virtual rtc::scoped_refptr<DtmfSenderInterface> CreateDtmfSender(
AudioTrackInterface* track) = 0;
// TODO(deadbeef): Make these pure virtual once all subclasses implement them.
+
+ // Creates a sender without a track. Can be used for "early media"/"warmup"
+ // use cases, where the application may want to negotiate video attributes
+ // before a track is available to send.
+ //
+ // The standard way to do this would be through "addTransceiver", but we
+ // don't support that API yet.
+ //
// |kind| must be "audio" or "video".
+ //
// |stream_id| is used to populate the msid attribute; if empty, one will
// be generated automatically.
virtual rtc::scoped_refptr<RtpSenderInterface> CreateSender(
@@ -474,11 +614,23 @@
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.
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.
+ //
+ // 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.
virtual std::vector<rtc::scoped_refptr<RtpReceiverInterface>> GetReceivers()
const {
return std::vector<rtc::scoped_refptr<RtpReceiverInterface>>();
@@ -494,12 +646,22 @@
// be changed to "= 0;".
virtual void GetStats(RTCStatsCollectorCallback* callback) {}
+ // Create a data channel with the provided config, or default config if none
+ // is provided. Note that an offer/answer negotiation is still necessary
+ // before the data channel can be used.
+ //
+ // Also, calling CreateDataChannel is the only way to get a data "m=" section
+ // in SDP, so it should be done before CreateOffer is called, if the
+ // application plans to use data channels.
virtual rtc::scoped_refptr<DataChannelInterface> CreateDataChannel(
const std::string& label,
const DataChannelInit* config) = 0;
+ // Returns the more recently applied description; "pending" if it exists, and
+ // otherwise "current". See below.
virtual const SessionDescriptionInterface* local_description() const = 0;
virtual const SessionDescriptionInterface* remote_description() const = 0;
+
// A "current" description the one currently negotiated from a complete
// offer/answer exchange.
virtual const SessionDescriptionInterface* current_local_description() const {
@@ -509,6 +671,7 @@
const {
return nullptr;
}
+
// A "pending" description is one that's part of an incomplete offer/answer
// exchange (thus, either an offer or a pranswer). Once the offer/answer
// exchange is finished, the "pending" description will become "current".
@@ -550,14 +713,14 @@
// The |observer| callback will be called when done.
virtual void SetRemoteDescription(SetSessionDescriptionObserver* observer,
SessionDescriptionInterface* desc) = 0;
- // Restarts or updates the ICE Agent process of gathering local candidates
- // and pinging remote candidates.
+ // Deprecated; Replaced by SetConfiguration.
// TODO(deadbeef): Remove once Chrome is moved over to SetConfiguration.
virtual bool UpdateIce(const IceServers& configuration,
const MediaConstraintsInterface* constraints) {
return false;
}
virtual bool UpdateIce(const IceServers& configuration) { return false; }
+
// TODO(deadbeef): Make this pure virtual once all Chrome subclasses of
// PeerConnectionInterface implement it.
virtual PeerConnectionInterface::RTCConfiguration GetConfiguration() {
@@ -598,20 +761,25 @@
const PeerConnectionInterface::RTCConfiguration& config) {
return false;
}
+
// Provides a remote candidate to the ICE Agent.
// A copy of the |candidate| will be created and added to the remote
// description. So the caller of this method still has the ownership of the
// |candidate|.
- // TODO(ronghuawu): Consider to change this so that the AddIceCandidate will
- // take the ownership of the |candidate|.
virtual bool AddIceCandidate(const IceCandidateInterface* candidate) = 0;
- // Removes a group of remote candidates from the ICE agent.
+ // Removes a group of remote candidates from the ICE agent. Needed mainly for
+ // continual gathering, to avoid an ever-growing list of candidates as
+ // networks come and go.
virtual bool RemoveIceCandidates(
const std::vector<cricket::Candidate>& candidates) {
return false;
}
+ // Register a metric observer (used by chromium).
+ //
+ // There can only be one observer at a time. Before the observer is
+ // destroyed, RegisterUMAOberver(nullptr) should be called.
virtual void RegisterUMAObserver(UMAObserver* observer) = 0;
// Returns the current SignalingState.
@@ -634,7 +802,8 @@
// TODO(ivoc): Make this pure virtual when Chrome is updated.
virtual void StopRtcEventLog() {}
- // Terminates all media and closes the transport.
+ // Terminates all media, closes the transports, and in general releases any
+ // resources used by the PeerConnection. This is an irreversible operation.
virtual void Close() = 0;
protected:
@@ -642,8 +811,8 @@
~PeerConnectionInterface() {}
};
-// PeerConnection callback interface. Application should implement these
-// methods.
+// PeerConnection callback interface, used for RTCPeerConnection events.
+// Application should implement these methods.
class PeerConnectionObserver {
public:
enum StateType {
@@ -681,6 +850,11 @@
virtual void OnRenegotiationNeeded() = 0;
// Called any time the IceConnectionState changes.
+ //
+ // Note that our ICE states lag behind the standard slightly. The most
+ // notable differences include the fact that "failed" occurs after 15
+ // seconds, not 30, and this actually represents a combination ICE + DTLS
+ // state, so it may be "failed" if DTLS fails while ICE succeeds.
virtual void OnIceConnectionChange(
PeerConnectionInterface::IceConnectionState new_state) = 0;
@@ -712,39 +886,50 @@
~PeerConnectionObserver() {}
};
-// PeerConnectionFactoryInterface is the factory interface use for creating
-// PeerConnection, MediaStream and media tracks.
-// PeerConnectionFactoryInterface will create required libjingle threads,
-// socket and network manager factory classes for networking.
-// If an application decides to provide its own threads and network
-// implementation of these classes it should use the alternate
-// CreatePeerConnectionFactory method which accepts threads as input and use the
-// CreatePeerConnection version that takes a PortAllocator as an
-// argument.
+// PeerConnectionFactoryInterface is the factory interface used for creating
+// PeerConnection, MediaStream and MediaStreamTrack objects.
+//
+// The simplest method for obtaiing one, CreatePeerConnectionFactory will
+// create the required libjingle threads, socket and network manager factory
+// classes for networking if none are provided, though it requires that the
+// application runs a message loop on the thread that called the method (see
+// explanation below)
+//
+// If an application decides to provide its own threads and/or implementation
+// of networking classes, it should use the alternate
+// CreatePeerConnectionFactory method which accepts threads as input, and use
+// the CreatePeerConnection version that takes a PortAllocator as an argument.
class PeerConnectionFactoryInterface : public rtc::RefCountInterface {
public:
class Options {
public:
- Options()
- : disable_encryption(false),
- disable_sctp_data_channels(false),
- disable_network_monitor(false),
- network_ignore_mask(rtc::kDefaultNetworkIgnoreMask),
- ssl_max_version(rtc::SSL_PROTOCOL_DTLS_12),
- crypto_options(rtc::CryptoOptions::NoGcm()) {}
- bool disable_encryption;
- bool disable_sctp_data_channels;
- bool disable_network_monitor;
+ Options() : crypto_options(rtc::CryptoOptions::NoGcm()) {}
+
+ // If set to true, created PeerConnections won't enforce any SRTP
+ // requirement, allowing unsecured media. Should only be used for
+ // testing/debugging.
+ bool disable_encryption = false;
+
+ // Deprecated. The only effect of setting this to true is that
+ // CreateDataChannel will fail, which is not that useful.
+ bool disable_sctp_data_channels = false;
+
+ // If set to true, any platform-supported network monitoring capability
+ // won't be used, and instead networks will only be updated via polling.
+ //
+ // This only has an effect if a PeerConnection is created with the default
+ // PortAllocator implementation.
+ bool disable_network_monitor = false;
// Sets the network types to ignore. For instance, calling this with
// ADAPTER_TYPE_ETHERNET | ADAPTER_TYPE_LOOPBACK will ignore Ethernet and
// loopback interfaces.
- int network_ignore_mask;
+ int network_ignore_mask = rtc::kDefaultNetworkIgnoreMask;
// Sets the maximum supported protocol version. The highest version
// supported by both ends will be used for the connection, i.e. if one
// party supports DTLS 1.0 and the other DTLS 1.2, DTLS 1.0 will be used.
- rtc::SSLProtocolVersion ssl_max_version;
+ rtc::SSLProtocolVersion ssl_max_version = rtc::SSL_PROTOCOL_DTLS_12;
// Sets crypto related options, e.g. enabled cipher suites.
rtc::CryptoOptions crypto_options;
@@ -754,13 +939,15 @@
virtual rtc::scoped_refptr<PeerConnectionInterface> CreatePeerConnection(
const PeerConnectionInterface::RTCConfiguration& configuration,
- const MediaConstraintsInterface* constraints,
std::unique_ptr<cricket::PortAllocator> allocator,
std::unique_ptr<rtc::RTCCertificateGeneratorInterface> cert_generator,
PeerConnectionObserver* observer) = 0;
+ // Deprecated; should use RTCConfiguration for everything that previously
+ // used constraints.
virtual rtc::scoped_refptr<PeerConnectionInterface> CreatePeerConnection(
const PeerConnectionInterface::RTCConfiguration& configuration,
+ const MediaConstraintsInterface* constraints,
std::unique_ptr<cricket::PortAllocator> allocator,
std::unique_ptr<rtc::RTCCertificateGeneratorInterface> cert_generator,
PeerConnectionObserver* observer) = 0;
@@ -769,7 +956,7 @@
CreateLocalMediaStream(const std::string& label) = 0;
// Creates a AudioSourceInterface.
- // |constraints| decides audio processing settings but can be NULL.
+ // |options| decides audio processing settings.
virtual rtc::scoped_refptr<AudioSourceInterface> CreateAudioSource(
const cricket::AudioOptions& options) = 0;
// Deprecated - use version above.
@@ -777,13 +964,14 @@
virtual rtc::scoped_refptr<AudioSourceInterface> CreateAudioSource(
const MediaConstraintsInterface* constraints) = 0;
- // Creates a VideoTrackSourceInterface. The new source take ownership of
+ // Creates a VideoTrackSourceInterface. The new source takes ownership of
// |capturer|.
+ // TODO(deadbeef): Switch to std::unique_ptr<>, to make this transfership of
+ // ownership more clear.
virtual rtc::scoped_refptr<VideoTrackSourceInterface> CreateVideoSource(
cricket::VideoCapturer* capturer) = 0;
// A video source creator that allows selection of resolution and frame rate.
- // |constraints| decides video resolution and frame rate but can
- // be NULL.
+ // |constraints| decides video resolution and frame rate but can be NULL.
// In the NULL case, use the version above.
virtual rtc::scoped_refptr<VideoTrackSourceInterface> CreateVideoSource(
cricket::VideoCapturer* capturer,
@@ -866,8 +1054,11 @@
// |network_thread|, |worker_thread| and |signaling_thread| are
// the only mandatory parameters.
//
-// If non-null, ownership of |default_adm|, |encoder_factory| and
-// |decoder_factory| are transferred to the returned factory.
+// If non-null, a reference is added to |default_adm|, and ownership of
+// |video_encoder_factory| and |video_decoder_factory| is transferred to the
+// returned factory.
+// TODO(deadbeef): Use rtc::scoped_refptr<> and std::unique_ptr<> to make this
+// ownership transfer and ref counting more obvious.
rtc::scoped_refptr<PeerConnectionFactoryInterface> CreatePeerConnectionFactory(
rtc::Thread* network_thread,
rtc::Thread* worker_thread,
diff --git a/webrtc/api/peerconnectionproxy.h b/webrtc/api/peerconnectionproxy.h
index 76b45d6..2375dd4 100644
--- a/webrtc/api/peerconnectionproxy.h
+++ b/webrtc/api/peerconnectionproxy.h
@@ -19,7 +19,8 @@
namespace webrtc {
-// Define proxy for PeerConnectionInterface.
+// TODO(deadbeef): Move this to .cc file and out of api/. What threads methods
+// are called on is an implementation detail.
BEGIN_SIGNALING_PROXY_MAP(PeerConnection)
PROXY_SIGNALING_THREAD_DESTRUCTOR()
PROXY_METHOD0(rtc::scoped_refptr<StreamCollectionInterface>, local_streams)
diff --git a/webrtc/api/proxy.h b/webrtc/api/proxy.h
index f834790..5634cfe 100644
--- a/webrtc/api/proxy.h
+++ b/webrtc/api/proxy.h
@@ -10,6 +10,7 @@
// This file contains Macros for creating proxies for webrtc MediaStream and
// PeerConnection classes.
+// TODO(deadbeef): Move this to pc/; this is part of the implementation.
//
// Example usage:
diff --git a/webrtc/api/rtpreceiverinterface.h b/webrtc/api/rtpreceiverinterface.h
index 4e47c9a..8607d93 100644
--- a/webrtc/api/rtpreceiverinterface.h
+++ b/webrtc/api/rtpreceiverinterface.h
@@ -54,6 +54,7 @@
// but this API also applies them to receivers, similar to ORTC:
// http://ortc.org/wp-content/uploads/2016/03/ortc.html#rtcrtpparameters*.
virtual RtpParameters GetParameters() const = 0;
+ // Currently, doesn't support changing any parameters, but may in the future.
virtual bool SetParameters(const RtpParameters& parameters) = 0;
// Does not take ownership of observer.
@@ -65,6 +66,8 @@
};
// Define proxy for RtpReceiverInterface.
+// TODO(deadbeef): Move this to .cc file and out of api/. What threads methods
+// are called on is an implementation detail.
BEGIN_SIGNALING_PROXY_MAP(RtpReceiver)
PROXY_SIGNALING_THREAD_DESTRUCTOR()
PROXY_CONSTMETHOD0(rtc::scoped_refptr<MediaStreamTrackInterface>, track)
diff --git a/webrtc/api/rtpsenderinterface.h b/webrtc/api/rtpsenderinterface.h
index 68547b0..f2b6766 100644
--- a/webrtc/api/rtpsenderinterface.h
+++ b/webrtc/api/rtpsenderinterface.h
@@ -47,9 +47,13 @@
// to uniquely identify a receiver until we implement Unified Plan SDP.
virtual std::string id() const = 0;
+ // Returns a list of streams associated with this sender's track. Although we
+ // only support one track per stream, in theory the API allows for multiple.
virtual std::vector<std::string> stream_ids() const = 0;
virtual RtpParameters GetParameters() const = 0;
+ // Note that only a subset of the parameters can currently be changed. See
+ // rtpparameters.h
virtual bool SetParameters(const RtpParameters& parameters) = 0;
// Returns null for a video sender.
@@ -60,6 +64,8 @@
};
// Define proxy for RtpSenderInterface.
+// TODO(deadbeef): Move this to .cc file and out of api/. What threads methods
+// are called on is an implementation detail.
BEGIN_SIGNALING_PROXY_MAP(RtpSender)
PROXY_SIGNALING_THREAD_DESTRUCTOR()
PROXY_METHOD1(bool, SetTrack, MediaStreamTrackInterface*)
diff --git a/webrtc/api/udptransportinterface.h b/webrtc/api/udptransportinterface.h
index 1a28531..30858e6 100644
--- a/webrtc/api/udptransportinterface.h
+++ b/webrtc/api/udptransportinterface.h
@@ -45,6 +45,8 @@
virtual rtc::SocketAddress GetRemoteAddress() const = 0;
};
+// TODO(deadbeef): Move this to .cc file and out of api/. What threads methods
+// are called on is an implementation detail.
BEGIN_OWNED_PROXY_MAP(UdpTransport)
PROXY_WORKER_THREAD_DESTRUCTOR()
PROXY_WORKER_CONSTMETHOD0(rtc::SocketAddress, GetLocalAddress)
diff --git a/webrtc/api/videosourceproxy.h b/webrtc/api/videosourceproxy.h
index b678acb..a00a21d 100644
--- a/webrtc/api/videosourceproxy.h
+++ b/webrtc/api/videosourceproxy.h
@@ -16,10 +16,10 @@
namespace webrtc {
-// VideoTrackSourceInterface makes sure the real VideoTrackSourceInterface
-// implementation is
-// destroyed on the signaling thread and marshals all method calls to the
-// signaling thread.
+// Makes sure the real VideoTrackSourceInterface implementation is destroyed on
+// the signaling thread and marshals all method calls to the signaling thread.
+// TODO(deadbeef): Move this to .cc file and out of api/. What threads methods
+// are called on is an implementation detail.
BEGIN_PROXY_MAP(VideoTrackSource)
PROXY_SIGNALING_THREAD_DESTRUCTOR()
PROXY_CONSTMETHOD0(SourceState, state)
