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