1/*
2 *  Copyright (c) 2011 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// This sub-API supports the following functionalities:
12//
13//  - Telephone event transmission.
14//  - DTMF tone generation.
15//
16// Usage example, omitting error checking:
17//
18//  using namespace webrtc;
19//  VoiceEngine* voe = VoiceEngine::Create();
20//  VoEBase* base = VoEBase::GetInterface(voe);
21//  VoEDtmf* dtmf  = VoEDtmf::GetInterface(voe);
22//  base->Init();
23//  int ch = base->CreateChannel();
24//  ...
25//  dtmf->SendTelephoneEvent(ch, 7);
26//  ...
27//  base->DeleteChannel(ch);
28//  base->Terminate();
29//  base->Release();
30//  dtmf->Release();
31//  VoiceEngine::Delete(voe);
32//
33#ifndef WEBRTC_VOICE_ENGINE_VOE_DTMF_H
34#define WEBRTC_VOICE_ENGINE_VOE_DTMF_H
35
36#include "webrtc/common_types.h"
37
38namespace webrtc {
39
40class VoiceEngine;
41
42// VoEDtmf
43class WEBRTC_DLLEXPORT VoEDtmf
44{
45public:
46
47    // Factory for the VoEDtmf sub-API. Increases an internal
48    // reference counter if successful. Returns NULL if the API is not
49    // supported or if construction fails.
50    static VoEDtmf* GetInterface(VoiceEngine* voiceEngine);
51
52    // Releases the VoEDtmf sub-API and decreases an internal
53    // reference counter. Returns the new reference count. This value should
54    // be zero for all sub-API:s before the VoiceEngine object can be safely
55    // deleted.
56    virtual int Release() = 0;
57
58    // Sends telephone events either in-band or out-of-band.
59    virtual int SendTelephoneEvent(int channel, int eventCode,
60                                   bool outOfBand = true, int lengthMs = 160,
61                                   int attenuationDb = 10) = 0;
62
63
64    // Sets the dynamic payload |type| that should be used for telephone
65    // events.
66    virtual int SetSendTelephoneEventPayloadType(int channel,
67                                                 unsigned char type) = 0;
68
69
70    // Gets the currently set dynamic payload |type| for telephone events.
71    virtual int GetSendTelephoneEventPayloadType(int channel,
72                                                 unsigned char& type) = 0;
73
74    // Enables or disables local tone playout for received DTMF events
75    // out-of-band.
76    virtual int SetDtmfPlayoutStatus(int channel, bool enable) = 0;
77
78    // Gets the DTMF playout status.
79    virtual int GetDtmfPlayoutStatus(int channel, bool& enabled) = 0;
80
81    // Toogles DTMF feedback state: when a DTMF tone is sent, the same tone
82    // is played out on the speaker.
83    virtual int SetDtmfFeedbackStatus(bool enable,
84                                      bool directFeedback = false) = 0;
85
86    // Gets the DTMF feedback status.
87    virtual int GetDtmfFeedbackStatus(bool& enabled, bool& directFeedback) = 0;
88
89    // Plays a DTMF feedback tone (only locally).
90    virtual int PlayDtmfTone(int eventCode, int lengthMs = 200,
91                             int attenuationDb = 10) = 0;
92
93    // To be removed. Don't use.
94    virtual int StartPlayingDtmfTone(int eventCode,
95        int attenuationDb = 10) { return -1; }
96    virtual int StopPlayingDtmfTone() { return -1; }
97
98protected:
99    VoEDtmf() {}
100    virtual ~VoEDtmf() {}
101};
102
103}  // namespace webrtc
104
105#endif  // WEBRTC_VOICE_ENGINE_VOE_DTMF_H
106