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 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: ~VoiceEngineObserver()57 virtual ~VoiceEngineObserver() {} 58 }; 59 60 // VoiceEngine 61 class WEBRTC_DLLEXPORT VoiceEngine { 62 public: 63 // Creates a VoiceEngine object, which can then be used to acquire 64 // sub-APIs. Returns NULL on failure. 65 static VoiceEngine* Create(); 66 static VoiceEngine* Create(const Config& config); 67 68 // Deletes a created VoiceEngine object and releases the utilized resources. 69 // Note that if there are outstanding references held via other interfaces, 70 // the voice engine instance will not actually be deleted until those 71 // references have been released. 72 static bool Delete(VoiceEngine*& voiceEngine); 73 74 // Specifies the amount and type of trace information which will be 75 // created by the VoiceEngine. 76 static int SetTraceFilter(unsigned int filter); 77 78 // Sets the name of the trace file and enables non-encrypted trace messages. 79 static int SetTraceFile(const char* fileNameUTF8, 80 bool addFileCounter = false); 81 82 // Installs the TraceCallback implementation to ensure that the user 83 // receives callbacks for generated trace messages. 84 static int SetTraceCallback(TraceCallback* callback); 85 86 #if !defined(WEBRTC_CHROMIUM_BUILD) 87 static int SetAndroidObjects(void* javaVM, void* context); 88 #endif 89 90 static std::string GetVersionString(); 91 92 protected: VoiceEngine()93 VoiceEngine() {} ~VoiceEngine()94 ~VoiceEngine() {} 95 }; 96 97 // VoEBase 98 class WEBRTC_DLLEXPORT VoEBase { 99 public: 100 // Factory for the VoEBase sub-API. Increases an internal reference 101 // counter if successful. Returns NULL if the API is not supported or if 102 // construction fails. 103 static VoEBase* GetInterface(VoiceEngine* voiceEngine); 104 105 // Releases the VoEBase sub-API and decreases an internal reference 106 // counter. Returns the new reference count. This value should be zero 107 // for all sub-APIs before the VoiceEngine object can be safely deleted. 108 virtual int Release() = 0; 109 110 // Installs the observer class to enable runtime error control and 111 // warning notifications. Returns -1 in case of an error, 0 otherwise. 112 virtual int RegisterVoiceEngineObserver(VoiceEngineObserver& observer) = 0; 113 114 // Removes and disables the observer class for runtime error control 115 // and warning notifications. Returns 0. 116 virtual int DeRegisterVoiceEngineObserver() = 0; 117 118 // Initializes all common parts of the VoiceEngine; e.g. all 119 // encoders/decoders, the sound card and core receiving components. 120 // This method also makes it possible to install some user-defined external 121 // modules: 122 // - The Audio Device Module (ADM) which implements all the audio layer 123 // functionality in a separate (reference counted) module. 124 // - The AudioProcessing module handles capture-side processing. VoiceEngine 125 // takes ownership of this object. 126 // If NULL is passed for any of these, VoiceEngine will create its own. 127 // Returns -1 in case of an error, 0 otherwise. 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 releases allocated resources. 136 // Returns 0. 137 virtual int Terminate() = 0; 138 139 // Creates a new channel and allocates the required resources for it. 140 // One can use |config| to configure the channel. Currently that is used for 141 // choosing between ACM1 and ACM2, when creating Audio Coding Module. 142 // Returns channel ID or -1 in case of an error. 143 virtual int CreateChannel() = 0; 144 virtual int CreateChannel(const Config& config) = 0; 145 146 // Deletes an existing channel and releases the utilized resources. 147 // Returns -1 in case of an error, 0 otherwise. 148 virtual int DeleteChannel(int channel) = 0; 149 150 // Prepares and initiates the VoiceEngine for reception of 151 // incoming RTP/RTCP packets on the specified |channel|. 152 virtual int StartReceive(int channel) = 0; 153 154 // Stops receiving incoming RTP/RTCP packets on the specified |channel|. 155 virtual int StopReceive(int channel) = 0; 156 157 // Starts forwarding the packets to the mixer/soundcard for a 158 // specified |channel|. 159 virtual int StartPlayout(int channel) = 0; 160 161 // Stops forwarding the packets to the mixer/soundcard for a 162 // specified |channel|. 163 virtual int StopPlayout(int channel) = 0; 164 165 // Starts sending packets to an already specified IP address and 166 // port number for a specified |channel|. 167 virtual int StartSend(int channel) = 0; 168 169 // Stops sending packets from a specified |channel|. 170 virtual int StopSend(int channel) = 0; 171 172 // Gets the version information for VoiceEngine and its components. 173 virtual int GetVersion(char version[1024]) = 0; 174 175 // Gets the last VoiceEngine error code. 176 virtual int LastError() = 0; 177 178 // TODO(xians): Make the interface pure virtual after libjingle 179 // implements the interface in its FakeWebRtcVoiceEngine. audio_transport()180 virtual AudioTransport* audio_transport() { return NULL; } 181 182 // Associate a send channel to a receive channel. 183 // Used for obtaining RTT for a receive-only channel. 184 // One should be careful not to crate a circular association, e.g., 185 // 1 <- 2 <- 1. 186 virtual int AssociateSendChannel(int channel, int accociate_send_channel) = 0; 187 188 protected: VoEBase()189 VoEBase() {} ~VoEBase()190 virtual ~VoEBase() {} 191 }; 192 193 } // namespace webrtc 194 195 #endif // WEBRTC_VOICE_ENGINE_VOE_BASE_H 196