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 Config;
  44
  45 const int kVoEDefault = -1;
  46
  47 // VoiceEngineObserver
  48 class WEBRTC_DLLEXPORT VoiceEngineObserver
  49 {
  50 public:
  51     // This method will be called after the occurrence of any runtime error
  52     // code, or warning notification, when the observer interface has been
  53     // installed using VoEBase::RegisterVoiceEngineObserver().
  54     virtual void CallbackOnError(int channel, int errCode) = 0;
  55
  56 protected:
  57     virtual ~VoiceEngineObserver() {}
  58 };
  59
  60 // VoiceEngine
  61 class WEBRTC_DLLEXPORT VoiceEngine
  62 {
  63 public:
  64     // Creates a VoiceEngine object, which can then be used to acquire
  65     // sub-APIs. Returns NULL on failure.
  66     static VoiceEngine* Create();
  67     static VoiceEngine* Create(const Config& config);
  68
  69     // Deletes a created VoiceEngine object and releases the utilized resources.
  70     // Note that if there are outstanding references held via other interfaces,
  71     // the voice engine instance will not actually be deleted until those
  72     // references have been released.
  73     static bool Delete(VoiceEngine*& voiceEngine);
  74
  75     // Specifies the amount and type of trace information which will be
  76     // created by the VoiceEngine.
  77     static int SetTraceFilter(unsigned int filter);
  78
  79     // Sets the name of the trace file and enables non-encrypted trace messages.
  80     static int SetTraceFile(const char* fileNameUTF8,
  81                             bool addFileCounter = false);
  82
  83     // Installs the TraceCallback implementation to ensure that the user
  84     // receives callbacks for generated trace messages.
  85     static int SetTraceCallback(TraceCallback* callback);
  86
  87     static int SetAndroidObjects(void* javaVM, void* env, void* context);
  88
  89 protected:
  90     VoiceEngine() {}
  91     ~VoiceEngine() {}
  92 };
  93
  94 // VoEBase
  95 class WEBRTC_DLLEXPORT VoEBase
  96 {
  97 public:
  98     // Factory for the VoEBase sub-API. Increases an internal reference
  99     // counter if successful. Returns NULL if the API is not supported or if
 100     // construction fails.
 101     static VoEBase* GetInterface(VoiceEngine* voiceEngine);
 102
 103     // Releases the VoEBase sub-API and decreases an internal reference
 104     // counter. Returns the new reference count. This value should be zero
 105     // for all sub-APIs before the VoiceEngine object can be safely deleted.
 106     virtual int Release() = 0;
 107
 108     // Installs the observer class to enable runtime error control and
 109     // warning notifications.
 110     virtual int RegisterVoiceEngineObserver(VoiceEngineObserver& observer) = 0;
 111
 112     // Removes and disables the observer class for runtime error control
 113     // and warning notifications.
 114     virtual int DeRegisterVoiceEngineObserver() = 0;
 115
 116     // Initializes all common parts of the VoiceEngine; e.g. all
 117     // encoders/decoders, the sound card and core receiving components.
 118     // This method also makes it possible to install some user-defined external
 119     // modules:
 120     // - The Audio Device Module (ADM) which implements all the audio layer
 121     // functionality in a separate (reference counted) module.
 122     // - The AudioProcessing module handles capture-side processing. VoiceEngine
 123     // takes ownership of this object.
 124     // If NULL is passed for any of these, VoiceEngine will create its own.
 125     // TODO(ajm): Remove default NULLs.
 126     virtual int Init(AudioDeviceModule* external_adm = NULL,
 127                      AudioProcessing* audioproc = NULL) = 0;
 128
 129     // Returns NULL before Init() is called.
 130     virtual AudioProcessing* audio_processing() = 0;
 131
 132     // Terminates all VoiceEngine functions and releses allocated resources.
 133     virtual int Terminate() = 0;
 134
 135     // Creates a new channel and allocates the required resources for it.
 136     virtual int CreateChannel() = 0;
 137
 138     // Deletes an existing channel and releases the utilized resources.
 139     virtual int DeleteChannel(int channel) = 0;
 140
 141     // Prepares and initiates the VoiceEngine for reception of
 142     // incoming RTP/RTCP packets on the specified |channel|.
 143     virtual int StartReceive(int channel) = 0;
 144
 145     // Stops receiving incoming RTP/RTCP packets on the specified |channel|.
 146     virtual int StopReceive(int channel) = 0;
 147
 148     // Starts forwarding the packets to the mixer/soundcard for a
 149     // specified |channel|.
 150     virtual int StartPlayout(int channel) = 0;
 151
 152     // Stops forwarding the packets to the mixer/soundcard for a
 153     // specified |channel|.
 154     virtual int StopPlayout(int channel) = 0;
 155
 156     // Starts sending packets to an already specified IP address and
 157     // port number for a specified |channel|.
 158     virtual int StartSend(int channel) = 0;
 159
 160     // Stops sending packets from a specified |channel|.
 161     virtual int StopSend(int channel) = 0;
 162
 163     // Gets the version information for VoiceEngine and its components.
 164     virtual int GetVersion(char version[1024]) = 0;
 165
 166     // Gets the last VoiceEngine error code.
 167     virtual int LastError() = 0;
 168
 169     // Stops or resumes playout and transmission on a temporary basis.
 170     virtual int SetOnHoldStatus(int channel, bool enable,
 171                                 OnHoldModes mode = kHoldSendAndPlay) = 0;
 172
 173     // Gets the current playout and transmission status.
 174     virtual int GetOnHoldStatus(int channel, bool& enabled,
 175                                 OnHoldModes& mode) = 0;
 176
 177     // Sets the NetEQ playout mode for a specified |channel| number.
 178     virtual int SetNetEQPlayoutMode(int channel, NetEqModes mode) = 0;
 179
 180     // Gets the NetEQ playout mode for a specified |channel| number.
 181     virtual int GetNetEQPlayoutMode(int channel, NetEqModes& mode) = 0;
 182
 183 protected:
 184     VoEBase() {}
 185     virtual ~VoEBase() {}
 186 };
 187
 188 }  // namespace webrtc
 189
 190 #endif  //  WEBRTC_VOICE_ENGINE_VOE_BASE_H