1 /* 2 * Copyright 2012 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_DTMF_SENDER_INTERFACE_H_ 12 #define API_DTMF_SENDER_INTERFACE_H_ 13 14 #include <string> 15 16 #include "api/media_stream_interface.h" 17 #include "rtc_base/ref_count.h" 18 19 namespace webrtc { 20 21 // DtmfSender callback interface, used to implement RTCDtmfSender events. 22 // Applications should implement this interface to get notifications from the 23 // DtmfSender. 24 class DtmfSenderObserverInterface { 25 public: 26 // Triggered when DTMF |tone| is sent. 27 // If |tone| is empty that means the DtmfSender has sent out all the given 28 // tones. 29 // The callback includes the state of the tone buffer at the time when 30 // the tone finished playing. OnToneChange(const std::string & tone,const std::string & tone_buffer)31 virtual void OnToneChange(const std::string& tone, 32 const std::string& tone_buffer) {} 33 // DEPRECATED: Older API without tone buffer. 34 // TODO(bugs.webrtc.org/9725): Remove old API and default implementation 35 // when old callers are gone. OnToneChange(const std::string & tone)36 virtual void OnToneChange(const std::string& tone) {} 37 38 protected: 39 virtual ~DtmfSenderObserverInterface() = default; 40 }; 41 42 // The interface of native implementation of the RTCDTMFSender defined by the 43 // WebRTC W3C Editor's Draft. 44 // See: https://www.w3.org/TR/webrtc/#peer-to-peer-dtmf 45 class DtmfSenderInterface : public rtc::RefCountInterface { 46 public: 47 // Provides the spec compliant default 2 second delay for the ',' character. 48 static const int kDtmfDefaultCommaDelayMs = 2000; 49 50 // Used to receive events from the DTMF sender. Only one observer can be 51 // registered at a time. UnregisterObserver should be called before the 52 // observer object is destroyed. 53 virtual void RegisterObserver(DtmfSenderObserverInterface* observer) = 0; 54 virtual void UnregisterObserver() = 0; 55 56 // Returns true if this DtmfSender is capable of sending DTMF. Otherwise 57 // returns false. To be able to send DTMF, the associated RtpSender must be 58 // able to send packets, and a "telephone-event" codec must be negotiated. 59 virtual bool CanInsertDtmf() = 0; 60 61 // Queues a task that sends the DTMF |tones|. The |tones| parameter is treated 62 // as a series of characters. The characters 0 through 9, A through D, #, and 63 // * generate the associated DTMF tones. The characters a to d are equivalent 64 // to A to D. The character ',' indicates a delay of 2 seconds before 65 // processing the next character in the tones parameter. 66 // 67 // Unrecognized characters are ignored. 68 // 69 // The |duration| parameter indicates the duration in ms to use for each 70 // character passed in the |tones| parameter. The duration cannot be more 71 // than 6000 or less than 70. 72 // 73 // The |inter_tone_gap| parameter indicates the gap between tones in ms. The 74 // |inter_tone_gap| must be at least 50 ms but should be as short as 75 // possible. 76 // 77 // The |comma_delay| parameter indicates the delay after the ',' 78 // character. InsertDtmf specifies |comma_delay| as an argument 79 // with a default value of 2 seconds as per the WebRTC spec. This parameter 80 // allows users to comply with legacy WebRTC clients. The |comma_delay| 81 // must be at least 50 ms. 82 // 83 // If InsertDtmf is called on the same object while an existing task for this 84 // object to generate DTMF is still running, the previous task is canceled. 85 // Returns true on success and false on failure. InsertDtmf(const std::string & tones,int duration,int inter_tone_gap)86 virtual bool InsertDtmf(const std::string& tones, 87 int duration, 88 int inter_tone_gap) { 89 return InsertDtmf(tones, duration, inter_tone_gap, 90 kDtmfDefaultCommaDelayMs); 91 } InsertDtmf(const std::string & tones,int duration,int inter_tone_gap,int comma_delay)92 virtual bool InsertDtmf(const std::string& tones, 93 int duration, 94 int inter_tone_gap, 95 int comma_delay) { 96 // TODO(bugs.webrtc.org/165700): Remove once downstream implementations 97 // override this signature rather than the 3-parameter one. 98 return InsertDtmf(tones, duration, inter_tone_gap); 99 } 100 101 // Returns the tones remaining to be played out. 102 virtual std::string tones() const = 0; 103 104 // Returns the current tone duration value in ms. 105 // This value will be the value last set via the InsertDtmf() method, or the 106 // default value of 100 ms if InsertDtmf() was never called. 107 virtual int duration() const = 0; 108 109 // Returns the current value of the between-tone gap in ms. 110 // This value will be the value last set via the InsertDtmf() method, or the 111 // default value of 50 ms if InsertDtmf() was never called. 112 virtual int inter_tone_gap() const = 0; 113 114 // Returns the current value of the "," character delay in ms. 115 // This value will be the value last set via the InsertDtmf() method, or the 116 // default value of 2000 ms if InsertDtmf() was never called. comma_delay()117 virtual int comma_delay() const { return kDtmfDefaultCommaDelayMs; } 118 119 protected: 120 ~DtmfSenderInterface() override = default; 121 }; 122 123 } // namespace webrtc 124 125 #endif // API_DTMF_SENDER_INTERFACE_H_ 126