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