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/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.
