src/third_party/webrtc/voice_engine/include/voe_base.h

   1 /*
   2  *  Copyright (c) 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 // This sub-API supports the following functionalities:
  12 //
  13 //  - Enables full duplex VoIP sessions via RTP using G.711 (mu-Law or A-Law).
  14 //  - Initialization and termination.
  15 //  - Trace information on text files or via callbacks.
  16 //  - Multi-channel support (mixing, sending to multiple destinations etc.).
  17 //
  18 // To support other codecs than G.711, the VoECodec sub-API must be utilized.
  19 //
  20 // Usage example, omitting error checking:
  21 //
  22 //  using namespace webrtc;
  23 //  VoiceEngine* voe = VoiceEngine::Create();
  24 //  VoEBase* base = VoEBase::GetInterface(voe);
  25 //  base->Init();
  26 //  int ch = base->CreateChannel();
  27 //  base->StartPlayout(ch);
  28 //  ...
  29 //  base->DeleteChannel(ch);
  30 //  base->Terminate();
  31 //  base->Release();
  32 //  VoiceEngine::Delete(voe);
  33 //
  34 #ifndef WEBRTC_VOICE_ENGINE_VOE_BASE_H
  35 #define WEBRTC_VOICE_ENGINE_VOE_BASE_H
  36
  37 #include "webrtc/common_types.h"
  38
  39 namespace webrtc {
  40
  41 class AudioDeviceModule;
  42 class AudioProcessing;
  43 class AudioTransport;
  44 class Config;
  45
  46 const int kVoEDefault = -1;
  47
  48 // VoiceEngineObserver
  49 class WEBRTC_DLLEXPORT VoiceEngineObserver
  50 {
  51 public:
  52     // This method will be called after the occurrence of any runtime error
  53     // code, or warning notification, when the observer interface has been
  54     // installed using VoEBase::RegisterVoiceEngineObserver().
  55     virtual void CallbackOnError(int channel, int errCode) = 0;
  56
  57 protected:
  58     virtual ~VoiceEngineObserver() {}
  59 };
  60
  61 // VoiceEngine
  62 class WEBRTC_DLLEXPORT VoiceEngine
  63 {
  64 public:
  65     // Creates a VoiceEngine object, which can then be used to acquire
  66     // sub-APIs. Returns NULL on failure.
  67     static VoiceEngine* Create();
  68     static VoiceEngine* Create(const Config& config);
  69
  70     // Deletes a created VoiceEngine object and releases the utilized resources.
  71     // Note that if there are outstanding references held via other interfaces,
  72     // the voice engine instance will not actually be deleted until those
  73     // references have been released.
  74     static bool Delete(VoiceEngine*& voiceEngine);
  75
  76     // Specifies the amount and type of trace information which will be
  77     // created by the VoiceEngine.
  78     static int SetTraceFilter(unsigned int filter);
  79
  80     // Sets the name of the trace file and enables non-encrypted trace messages.
  81     static int SetTraceFile(const char* fileNameUTF8,
  82                             bool addFileCounter = false);
  83
  84     // Installs the TraceCallback implementation to ensure that the user
  85     // receives callbacks for generated trace messages.
  86     static int SetTraceCallback(TraceCallback* callback);
  87
  88 #if !defined(WEBRTC_CHROMIUM_BUILD)
  89     static int SetAndroidObjects(void* javaVM, void* env, void* context);
  90 #endif
  91
  92 protected:
  93     VoiceEngine() {}
  94     ~VoiceEngine() {}
  95 };
  96
  97 // VoEBase
  98 class WEBRTC_DLLEXPORT VoEBase
  99 {
 100 public:
 101     // Factory for the VoEBase sub-API. Increases an internal reference
 102     // counter if successful. Returns NULL if the API is not supported or if
 103     // construction fails.
 104     static VoEBase* GetInterface(VoiceEngine* voiceEngine);
 105
 106     // Releases the VoEBase sub-API and decreases an internal reference
 107     // counter. Returns the new reference count. This value should be zero
 108     // for all sub-APIs before the VoiceEngine object can be safely deleted.
 109     virtual int Release() = 0;
 110
 111     // Installs the observer class to enable runtime error control and
 112     // warning notifications.
 113     virtual int RegisterVoiceEngineObserver(VoiceEngineObserver& observer) = 0;
 114
 115     // Removes and disables the observer class for runtime error control
 116     // and warning notifications.
 117     virtual int DeRegisterVoiceEngineObserver() = 0;
 118
 119     // Initializes all common parts of the VoiceEngine; e.g. all
 120     // encoders/decoders, the sound card and core receiving components.
 121     // This method also makes it possible to install some user-defined external
 122     // modules:
 123     // - The Audio Device Module (ADM) which implements all the audio layer
 124     // functionality in a separate (reference counted) module.
 125     // - The AudioProcessing module handles capture-side processing. VoiceEngine
 126     // takes ownership of this object.
 127     // If NULL is passed for any of these, VoiceEngine will create its own.
 128     // TODO(ajm): Remove default NULLs.
 129     virtual int Init(AudioDeviceModule* external_adm = NULL,
 130                      AudioProcessing* audioproc = NULL) = 0;
 131
 132     // Returns NULL before Init() is called.
 133     virtual AudioProcessing* audio_processing() = 0;
 134
 135     // Terminates all VoiceEngine functions and releses allocated resources.
 136     virtual int Terminate() = 0;
 137
 138     // Creates a new channel and allocates the required resources for it.
 139     // One can use |config| to configure the channel. Currently that is used for
 140     // choosing between ACM1 and ACM2, when creating Audio Coding Module.
 141     virtual int CreateChannel() = 0;
 142     virtual int CreateChannel(const Config& config) = 0;
 143
 144     // Deletes an existing channel and releases the utilized resources.
 145     virtual int DeleteChannel(int channel) = 0;
 146
 147     // Prepares and initiates the VoiceEngine for reception of
 148     // incoming RTP/RTCP packets on the specified |channel|.
 149     virtual int StartReceive(int channel) = 0;
 150
 151     // Stops receiving incoming RTP/RTCP packets on the specified |channel|.
 152     virtual int StopReceive(int channel) = 0;
 153
 154     // Starts forwarding the packets to the mixer/soundcard for a
 155     // specified |channel|.
 156     virtual int StartPlayout(int channel) = 0;
 157
 158     // Stops forwarding the packets to the mixer/soundcard for a
 159     // specified |channel|.
 160     virtual int StopPlayout(int channel) = 0;
 161
 162     // Starts sending packets to an already specified IP address and
 163     // port number for a specified |channel|.
 164     virtual int StartSend(int channel) = 0;
 165
 166     // Stops sending packets from a specified |channel|.
 167     virtual int StopSend(int channel) = 0;
 168
 169     // Gets the version information for VoiceEngine and its components.
 170     virtual int GetVersion(char version[1024]) = 0;
 171
 172     // Gets the last VoiceEngine error code.
 173     virtual int LastError() = 0;
 174
 175     // TODO(xians): Make the interface pure virtual after libjingle
 176     // implements the interface in its FakeWebRtcVoiceEngine.
 177     virtual AudioTransport* audio_transport() { return NULL; }
 178
 179     // To be removed. Don't use.
 180     virtual int SetOnHoldStatus(int channel, bool enable,
 181         OnHoldModes mode = kHoldSendAndPlay) { return -1; }
 182     virtual int GetOnHoldStatus(int channel, bool& enabled,
 183         OnHoldModes& mode) { return -1; }
 184     virtual int SetNetEQPlayoutMode(int channel, NetEqModes mode) { return -1; }
 185     virtual int GetNetEQPlayoutMode(int channel,
 186         NetEqModes& mode) { return -1; }
 187
 188 protected:
 189     VoEBase() {}
 190     virtual ~VoEBase() {}
 191 };
 192
 193 }  // namespace webrtc
 194
 195 #endif  //  WEBRTC_VOICE_ENGINE_VOE_BASE_H