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: ~VoiceEngineObserver()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: VoiceEngine()93 VoiceEngine() {} ~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. audio_transport()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; } GetOnHoldStatus(int channel,bool & enabled,OnHoldModes & mode)182 virtual int GetOnHoldStatus(int channel, bool& enabled, 183 OnHoldModes& mode) { return -1; } 184 185 protected: VoEBase()186 VoEBase() {} ~VoEBase()187 virtual ~VoEBase() {} 188 }; 189 190 } // namespace webrtc 191 192 #endif // WEBRTC_VOICE_ENGINE_VOE_BASE_H 193