Home | History | Annotate | Download | only in include 
      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 
     38 namespace webrtc {
     39 
     40 class VoiceEngine;
     41 
     42 // VoEDtmf
     43 class WEBRTC_DLLEXPORT VoEDtmf
     44 {
     45 public:
     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 
     98 protected:
     99     VoEDtmf() {}
    100     virtual ~VoEDtmf() {}
    101 };
    102 
    103 }  // namespace webrtc
    104 
    105 #endif  // WEBRTC_VOICE_ENGINE_VOE_DTMF_H
    106