blob: c82ad3dc3a6b19860c8ca0f08c5b460413ba7919 [file] [log] [blame]
niklase@google.com470e71d2011-07-07 08:21:25 +00001/*
tommi@webrtc.orga990e122012-04-26 15:28:22 +00002 * Copyright (c) 2012 The WebRTC project authors. All Rights Reserved.
niklase@google.com470e71d2011-07-07 08:21:25 +00003 *
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.).
niklase@google.com470e71d2011-07-07 08:21:25 +000017//
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
pbos@webrtc.org956aa7e2013-05-21 13:52:32 +000037#include "webrtc/common_types.h"
niklase@google.com470e71d2011-07-07 08:21:25 +000038
39namespace webrtc {
40
41class AudioDeviceModule;
andrew@webrtc.orgf0a90c32013-03-05 01:12:49 +000042class AudioProcessing;
xians@webrtc.orgc1e28032014-02-02 15:30:20 +000043class AudioTransport;
minyue@webrtc.orge509f942013-09-12 17:03:00 +000044class Config;
niklase@google.com470e71d2011-07-07 08:21:25 +000045
46const int kVoEDefault = -1;
47
48// VoiceEngineObserver
Jelena Marusic0d266052015-05-04 14:15:32 +020049class 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;
niklase@google.com470e71d2011-07-07 08:21:25 +000055
Jelena Marusic0d266052015-05-04 14:15:32 +020056 protected:
57 virtual ~VoiceEngineObserver() {}
niklase@google.com470e71d2011-07-07 08:21:25 +000058};
59
60// VoiceEngine
Jelena Marusic0d266052015-05-04 14:15:32 +020061class 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);
niklase@google.com470e71d2011-07-07 08:21:25 +000067
Jelena Marusic0d266052015-05-04 14:15:32 +020068 // 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);
niklase@google.com470e71d2011-07-07 08:21:25 +000073
Jelena Marusic0d266052015-05-04 14:15:32 +020074 // Specifies the amount and type of trace information which will be
75 // created by the VoiceEngine.
76 static int SetTraceFilter(unsigned int filter);
niklase@google.com470e71d2011-07-07 08:21:25 +000077
Jelena Marusic0d266052015-05-04 14:15:32 +020078 // Sets the name of the trace file and enables non-encrypted trace messages.
79 static int SetTraceFile(const char* fileNameUTF8,
80 bool addFileCounter = false);
niklase@google.com470e71d2011-07-07 08:21:25 +000081
Jelena Marusic0d266052015-05-04 14:15:32 +020082 // Installs the TraceCallback implementation to ensure that the user
83 // receives callbacks for generated trace messages.
84 static int SetTraceCallback(TraceCallback* callback);
niklase@google.com470e71d2011-07-07 08:21:25 +000085
henrika@webrtc.org8883a0f2014-04-09 13:04:12 +000086#if !defined(WEBRTC_CHROMIUM_BUILD)
Jelena Marusic0d266052015-05-04 14:15:32 +020087 static int SetAndroidObjects(void* javaVM, void* context);
henrika@webrtc.org8883a0f2014-04-09 13:04:12 +000088#endif
niklase@google.com470e71d2011-07-07 08:21:25 +000089
Jelena Marusic0d266052015-05-04 14:15:32 +020090 protected:
91 VoiceEngine() {}
92 ~VoiceEngine() {}
niklase@google.com470e71d2011-07-07 08:21:25 +000093};
94
95// VoEBase
Jelena Marusic0d266052015-05-04 14:15:32 +020096class WEBRTC_DLLEXPORT VoEBase {
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);
niklase@google.com470e71d2011-07-07 08:21:25 +0000102
Jelena Marusic0d266052015-05-04 14:15:32 +0200103 // 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;
niklase@google.com470e71d2011-07-07 08:21:25 +0000107
Jelena Marusic0d266052015-05-04 14:15:32 +0200108 // Installs the observer class to enable runtime error control and
109 // warning notifications. Returns -1 in case of an error, 0 otherwise.
110 virtual int RegisterVoiceEngineObserver(VoiceEngineObserver& observer) = 0;
niklase@google.com470e71d2011-07-07 08:21:25 +0000111
Jelena Marusic0d266052015-05-04 14:15:32 +0200112 // Removes and disables the observer class for runtime error control
113 // and warning notifications. Returns 0.
114 virtual int DeRegisterVoiceEngineObserver() = 0;
niklase@google.com470e71d2011-07-07 08:21:25 +0000115
Jelena Marusic0d266052015-05-04 14:15:32 +0200116 // 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 // Returns -1 in case of an error, 0 otherwise.
126 // TODO(ajm): Remove default NULLs.
127 virtual int Init(AudioDeviceModule* external_adm = NULL,
128 AudioProcessing* audioproc = NULL) = 0;
andrew@webrtc.orgf0a90c32013-03-05 01:12:49 +0000129
Jelena Marusic0d266052015-05-04 14:15:32 +0200130 // Returns NULL before Init() is called.
131 virtual AudioProcessing* audio_processing() = 0;
niklase@google.com470e71d2011-07-07 08:21:25 +0000132
Jelena Marusic0d266052015-05-04 14:15:32 +0200133 // Terminates all VoiceEngine functions and releases allocated resources.
134 // Returns 0.
135 virtual int Terminate() = 0;
niklase@google.com470e71d2011-07-07 08:21:25 +0000136
Jelena Marusic0d266052015-05-04 14:15:32 +0200137 // Creates a new channel and allocates the required resources for it.
138 // One can use |config| to configure the channel. Currently that is used for
139 // choosing between ACM1 and ACM2, when creating Audio Coding Module.
140 // Returns channel ID or -1 in case of an error.
141 virtual int CreateChannel() = 0;
142 virtual int CreateChannel(const Config& config) = 0;
niklase@google.com470e71d2011-07-07 08:21:25 +0000143
Jelena Marusic0d266052015-05-04 14:15:32 +0200144 // Deletes an existing channel and releases the utilized resources.
145 // Returns -1 in case of an error, 0 otherwise.
146 virtual int DeleteChannel(int channel) = 0;
niklase@google.com470e71d2011-07-07 08:21:25 +0000147
Jelena Marusic0d266052015-05-04 14:15:32 +0200148 // Prepares and initiates the VoiceEngine for reception of
149 // incoming RTP/RTCP packets on the specified |channel|.
150 virtual int StartReceive(int channel) = 0;
niklase@google.com470e71d2011-07-07 08:21:25 +0000151
Jelena Marusic0d266052015-05-04 14:15:32 +0200152 // Stops receiving incoming RTP/RTCP packets on the specified |channel|.
153 virtual int StopReceive(int channel) = 0;
niklase@google.com470e71d2011-07-07 08:21:25 +0000154
Jelena Marusic0d266052015-05-04 14:15:32 +0200155 // Starts forwarding the packets to the mixer/soundcard for a
156 // specified |channel|.
157 virtual int StartPlayout(int channel) = 0;
niklase@google.com470e71d2011-07-07 08:21:25 +0000158
Jelena Marusic0d266052015-05-04 14:15:32 +0200159 // Stops forwarding the packets to the mixer/soundcard for a
160 // specified |channel|.
161 virtual int StopPlayout(int channel) = 0;
niklase@google.com470e71d2011-07-07 08:21:25 +0000162
Jelena Marusic0d266052015-05-04 14:15:32 +0200163 // Starts sending packets to an already specified IP address and
164 // port number for a specified |channel|.
165 virtual int StartSend(int channel) = 0;
niklase@google.com470e71d2011-07-07 08:21:25 +0000166
Jelena Marusic0d266052015-05-04 14:15:32 +0200167 // Stops sending packets from a specified |channel|.
168 virtual int StopSend(int channel) = 0;
niklase@google.com470e71d2011-07-07 08:21:25 +0000169
Jelena Marusic0d266052015-05-04 14:15:32 +0200170 // Gets the version information for VoiceEngine and its components.
171 virtual int GetVersion(char version[1024]) = 0;
niklase@google.com470e71d2011-07-07 08:21:25 +0000172
Jelena Marusic0d266052015-05-04 14:15:32 +0200173 // Gets the last VoiceEngine error code.
174 virtual int LastError() = 0;
niklase@google.com470e71d2011-07-07 08:21:25 +0000175
Jelena Marusic0d266052015-05-04 14:15:32 +0200176 // TODO(xians): Make the interface pure virtual after libjingle
177 // implements the interface in its FakeWebRtcVoiceEngine.
178 virtual AudioTransport* audio_transport() { return NULL; }
xians@webrtc.orgc1e28032014-02-02 15:30:20 +0000179
Minyue2013aec2015-05-13 14:14:42 +0200180 // Associate a send channel to a receive channel.
181 // Used for obtaining RTT for a receive-only channel.
182 // One should be careful not to crate a circular association, e.g.,
183 // 1 <- 2 <- 1.
Jelena Marusicf09e09c2015-05-26 10:24:55 +0200184 virtual int AssociateSendChannel(int channel, int accociate_send_channel) = 0;
henrika@webrtc.org66803482014-04-17 10:45:01 +0000185
Jelena Marusic0d266052015-05-04 14:15:32 +0200186 protected:
187 VoEBase() {}
188 virtual ~VoEBase() {}
niklase@google.com470e71d2011-07-07 08:21:25 +0000189};
190
pbos@webrtc.orgd900e8b2013-07-03 15:12:26 +0000191} // namespace webrtc
niklase@google.com470e71d2011-07-07 08:21:25 +0000192
193#endif // WEBRTC_VOICE_ENGINE_VOE_BASE_H