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  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
     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:
     93   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.
    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