OMCS 开发手册之 C++ SDK 说明

（OMCS C++ SDK 目前版本提供的功能有：语音、视频和远程桌面）

　　如果您已经了解了OMCS语音视频框架其它任一版本的使用方法，那么上手C++版本的SDK是非常简单的。在本文中，我们将OMCS C++ SDK中重要的API列出来加以说明，很多重复性的内容就不再一一赘述了。在文末我们将提供一个Qt版的demo，作为C++版SDK的使用示例。

一. IMultimediaManager接口

OMCS框架客户端的核心类是IMultimediaManager（多媒体管理器接口），在客户端中以单例模式提供，可以通过MultimediaManagerFactory类的静态方法GetSingleton()获取该单例的引用。IMultimediaManager类定义中基础的部分如下：

    /// <summary>多媒体管理器初始化（连接Omcs服务器并登录）</summary> 
    /// <param name="userID">登陆用户ID</param>
    /// <param name="pwd">密码</param>
    /// <param name="serverIP">服务器IP</param>
    /// <param name="serverPort">服务器端口</param>
    /// <param name="onDisconnect">与服务器连接断开时回调此函数</param>
    /// <param name="onResucceed">重连服务器成功时回调此函数</param>
    /// <returns>登陆结果</returns>
    virtual Omcs_LoginResult Initialize(const char* userID, const char* pwd, const char* serverIP,
        int serverPort, Omcs_Callback onDisconnect, Omcs_Callback onResucceed) = 0;

    /// <summary>
    /// 关闭并释放多媒体管理器
    ///</summary> 
    virtual void  Dispose() = 0;

    /// <summary>主动断开来访者guest到本地多媒体设备的连接 </summary>
    /// <param name="guestID">来访者ID</param>
    /// <param name="deviceType">来访者ID</param>
    /// <param name="notifyGuest">来访者ID</param>
    virtual void DisconnectGuest(const char* guestID, Omcs_DeviceType deviceType, bool notifyGuest) = 0;

    /// <summary>查询本地的某设备是否正在工作？</summary>
    /// <param name="deviceType">设备类型</param>
    /// <returns>工作中？</returns>
    virtual bool DeviceIsWorking(Omcs_DeviceType deviceType) = 0;

    /// <summary>当前登录用户的ID</summary> 
    virtual const char* GetCurrentUserID() = 0;

1.摄像头

IMultimediaManager类中与摄像头设置相关的方法如下：

    /// <summary>设置要使用的摄像头索引</summary>

    virtual void CameraDevice_SetIndex(int index) = 0; 

    /// <summary>设置摄像头采用的分辨率</summary> 
    virtual void SetCameraVideoSize(Omcs_VideoSize videoSize) = 0; 

    /// <summary>设置摄像头最大帧频</summary> 
    virtual void SetMaxCameraFrameRate(int frameRate) = 0; 

    /// <summary>设置摄像头视频的编码质量</summary> 
    virtual void SetCameraEncodeQuality(int quality) = 0; 

    /// <summary>是否将摄像头集到的视频输出给Guest</summary> 
    virtual void SetOutputVideo(bool output) = 0;

2.麦克风

IMultimediaManager类中与麦克风设置相关的方法如下：

    /// <summary>设置要使用的麦克风索引</summary> 
    virtual void MicrophoneDevice_SetIndex(int index) = 0; 

    /// <summary>设置要使用的扬声器索引</summary> 
    virtual void SetSpeakerIndex(int index) = 0; 

    /// <summary>是否将话筒采集到的音频输出给Guest</summary>  
    virtual void SetOutputAudio(bool output) = 0; 

    /// <summary>设置静音</summary> 
    virtual void SetMute(bool isMute) = 0; 

    /// <summary>设置音频输入模式</summary> 
    virtual void SetAudioInputMode(Omcs_AudioInputMode mode) = 0;

SetOutputAudio方法用于控制是否将声音发送给guest。在抢麦场景中经常使用，默认将setOutputVideo设置为false，抢到麦的就将其设置为true。

3.桌面

C++端可以将自己的屏幕分享给guest观看和控制（guest端可以是PC、安卓、iOS）。IMultimediaManager类中与桌面/屏幕设置相关的方法如下：

    /// <summary>设置本地桌面采集的最大帧频 </summary> 
    virtual void SetMaxDesktopFrameRate(int frameRate) = 0; 

    /// <summary>设置本地桌面的编码质量</summary> 
    virtual void SetDesktopEncodeQuality(int quality) = 0; 

    /// <summary>是否将桌面图像输出给Guest</summary> 
    virtual void SetOutputDesktop(bool output) = 0;

二.多媒体连接器 IMultimediaConnector

当自己作为Guest，需要访问Owner的摄像头等设备时，就需要使用连接器。所有的连接器都从IMultimediaConnector基类继承，IMultimediaConnector包含的功能如下：

     /// <summary>开始连接对方设备</summary>
    virtual void BeginConnect() = 0;

    /// <summary>断开并释放连接器</summary> 
    virtual void Disconnect() = 0;

    /// <summary>连接器是否与目标设备建立了连接？</summary> 
    virtual bool IsConnected() = 0;

    /// <summary>Owner是否将采集到的数据输出给Guest？</summary> 
    virtual bool GetOwnerOutput() = 0;

我们要使用的CameraConnector、MicrophoneConnector、DesktopConnector都是从IMultimediaConnector继承的。

所有的多媒体连接器的构造函数都包括两个参数：

（1）ownerID ：即要连接的目标用户的ID。

（2）Omcs_IConnectorCallback ：注入的回调，用于接收连接器的状态通知。Omcs_IConnectorCallback 接口定义如下：

class Omcs_IConnectorCallback
{
    public:
    //当连接目标用户的设备结束时，回调此函数。result参数如果为NULL，表示连接成功；否则，其值指出了连接失败的原因。
    virtual void Omcs_Connector_ConnectEnded(const char* ownerID, Omcs_DeviceType deviceType, const char* result) {}
    //当连接器与目标设备断开连接时，回调此函数。result参数说明了连接断开的原因。
    virtual void Omcs_Connector_Disconnected(const char* ownerID, Omcs_DeviceType deviceType, const char* result) {}
    //当目标用户修改了是否输出设备数据的控制时，回调此函数。
    virtual void Omcs_Connector_OwnerOutputChanged(const char* ownerID, Omcs_DeviceType deviceType, bool output) {}
    //当连接器接收到来自目标设备的数据帧时，回调此函数。如果是视频帧（摄像头或桌面），size参数指明了视频图像的宽高。
    virtual void Omcs_Connector_FrameReceived(const char* ownerID, Omcs_DeviceType deviceType, unsigned char* frameData, Omcs_VideoSize size) {}
};

下面我们来逐个介绍具体的多媒体设备连接器。

1.MicrophoneConnector

麦克风连接器还包含了如下功能：

   /// <summary>设置静音</summary> 
    void SetMute(bool isMute);

    /// <summary>是否静音</summary> 
    bool GetMute();

2.CameraConnector

摄像头连接器除了IMultimediaConnector接口内的函数外，目前不包含其它函数了。

3.DesktopConnector

通过DesktopConnector可以观看Owner端的屏幕，并进行操作（即远程桌面和远程协助）。

    /// <summary>Owner是否允许操作桌面</summary>  
    bool GetOwnerAllowControl();

    /// <summary>设置是否仅仅允许查看远程桌面，但是不能进行操作</summary>  
    void SetWatchingOnly(bool watchingOnly);

    /// <summary>是否仅仅允许查看远程桌面，但是不能进行操作</summary>  
    bool GetWatchingOnly();