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
39namespace webrtc {
40
41class AudioDeviceModule;
42class AudioProcessing;
43class AudioTransport;
44class Config;
45
46const int kVoEDefault = -1;
47
48// VoiceEngineObserver
49class 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:
57  virtual ~VoiceEngineObserver() {}
58};
59
60// VoiceEngine
61class 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:
93  VoiceEngine() {}
94  ~VoiceEngine() {}
95};
96
97// VoEBase
98class 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.
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:
189  VoEBase() {}
190  virtual ~VoEBase() {}
191};
192
193}  // namespace webrtc
194
195#endif  //  WEBRTC_VOICE_ENGINE_VOE_BASE_H
196