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