OMCS 开发手册 －－ HarmonyOS 版（支持鸿蒙电脑、手机、Pad）

   （OMCS Harmony SDK 目前版本提供的功能有：语音、视频、桌面/屏幕分享、电子白板） 

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

一. 多媒体管理器：IMultimediaManager

　　多媒体管理器用于管理本地的多媒体设备，包括：摄像头、麦克风、桌面、电子白板。

　　在客户端中以单例模式提供，可以通过MultimediaManagerFactory类的静态方法GetSingleton()获取该单例的引用。

　　IMultimediaManager接口定义中基础的部分如下：

 /**
   * 与多媒体服务器建立连接，并初始化本地多媒体管理器。
   * 如果与服务器连接失败，将抛出网络异常。
   *
   * @param userID     当前登录的用户ID。
   * @param password   当前登录的用户的密码。
   * @param serverIP   OMCS服务器IP
   * @param serverPort OMCS服务器端口
   * @param context
   */
   initialize(userID:string, password:string, serverIP:string,serverPort:number,context:Context,callBack:Function):void;

 /**
    * 注入回调后，当客户端与服务器的TCP连接断开时，将触发此事件
    */
   setConnectionInterrupted(fun:Function):void
   /**
    * 注入回调后,当自动重连开始时，触发此事件。如果重连成功则将重新登录，并触发RelogonCompleted事件。
    */
   setConnectionRebuildStart(fun:Function):void
   /**
    * 注入回调后,当断线重连成功时，会自动登录服务器验证用户账号密码，并触发此事件。
    * 如果验证失败，则与服务器的连接将会断开，且后续不会再自动重连。事件参数表明了登录验证的结果
    * @param logonResp
    */
   setRelogonCompleted(fun:(logonResp:LogonResponse)=>void):void

 /**
   * 当前登录用户的ID。
   *
   * @return
   */
  getCurrentUserID():string;

  /**
   * 当前多媒体管理器是否可用？（与OMCS服务器成功连接？并且设备管理器已经初始化完成？）
   * @return
   */
  isAvailable():boolean;


 /**
   * 退出登录，并关闭多媒体管理器。一般在进程退出前调用。
   */
  close():void;

（1） 其中最重要的方法是initialize(userID:string, password:string, serverIP:string,serverPort:number,context:Context,callBack:Function):void;用于与多媒体服务器建立连接并初始化本地多媒体管理器.

（2）与服务器的连接状态通过setConnectionInterrupted、setConnectionRebuildStart、setRelogonCompleted设置回调后，可以监听与服务器TCP连接的状态.

1.摄像头

　　IMultimediaManager接口中与摄像头设置相关的接口如下：

  /**
   * 设置使用的摄像头的索引。
   * @param index 0-后 1-前
   */
  setCameraDeviceIndex(index:number):void;

   /**
    *  摄像头的最大帧频。默认值：30。（必须在调用Initialize方法之前设置才有效。）
    * @param  rate
    */
    MaxCameraFrameRate(rate:number):void

  /**
   * 切换摄像头并重新打开指定摄像头（必须设置配置参数，否则报错）
   * @param index 0-后 1-前
   */
  switchCameraDeviceIndex(index:number):void;

  /**
   * 本地摄像头视频的编码质量。取值0~31，默认值10。取值越小，越清晰。
   *
   * @param quality
   */
  setCameraEncodeQuality(quality:number):void;


  /**
   * 是否将摄像头集到的视频输出给Guest。（必须在初始化完成之后设置才有效）
   * 如果为true，表示输出；否则，表示将采集到的视频数据丢弃，不发送给guest。默认值为true。
   *
   * @param isOutput
   */
  setOutputVideo(isOutput:boolean):void;

2.麦克风

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

   /**
    * 声音数据编码方式。默认为speex（必须在调用Initialize方法之前设置才有效。）
    * @param  index 0-speex 1-AAC
    */
   SetMicrophoneEncoding(index:AudioCodecType):void

  /**
   * 控制是否输出麦克风的声音给guest。默认值为true。（必须在初始化完成之后设置才有效）
   * @param isOutput 是否输出？
   */
  setOutputAudio(isOutput:boolean):void;

  /**
   * 控制扬声器是否不播放来自所有Owner的声音。默认值为false。
   * @param mute 是否静音？
   */
  setMute(mute:boolean):void;

3.桌面

　　 鸿蒙端可以将自己的屏幕分享给guest观看（guest端可以是HarmonyOS、Windows、Android、iOS、Linux）。IMultimediaManager类中与桌面/屏幕设置相关的方法如下：

   /**
    * 控制是否输出桌面图像给guest。默认值为true。（必须在初始化完成之后设置才有效）
    * @param isOutput 是否输出？
    */

  setOutputDesktop(isOutput:boolean):void

  /**
   * 本地屏幕的编码质量。取值0~31，默认值10。取值越小，越清晰。
   *
   * @param quality
   */
  setDesktopEncodeQuality(quality:number):void;

  /**
   * 本地屏幕最大帧频。取值8~30，默认值16。
   *
   * @param maxFPS
   */
  setDesktopMaxFPS(maxFPS:number):void;

二.多媒体连接器 MultimediaConnector

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

/**
   * 尝试连接目标多媒体设备。
   *
   * @param destUserID 目标用户的UserID
   */
　beginConnect(destUserID:string):Promise<void>;

  /**
   * 注入回调后,当连接目标多媒体设备的尝试（由BeginConnect发起）结束时，回调该函数。
   *  result 连接结果
   */
  connectEnded:((result:ConnectResult) => void)

  /**
   * 注入回调后,当与目标多媒体设备的连接断开时，回调该函数。
   *
   * @param type 设备类型
   */
  disconnected:((type:DisConnectResult)=>void)

/**
   * 与目标设备是否已连接？
   */
  isConnected():boolean;

 /**
   * Owner方的UserID。
   */
  getOwnerID():string

 /**
   * 与目标用户的多媒体设备断开连接。
   */
disconnect():void

（1）调用beginConnect方法，以尝试连接目标用户Owner的设备，只要设置了connectEnded回调，框架就会通过回调通知连接结果。

（2）当已经连接成功正在正常工作的连接器断开连接时（如因为自己掉线，对方掉线、或主动断开），只要设置了disconnected回调，框架就会通过回调通知断开的原因。

（3）我们要使用的CameraConnector、MicrophoneConnector、DesktopConnector都是从MultimediaConnector继承的。

1.CameraConnector

摄像头连接器还包含了如下功能：

  /**
   * 注入回调后,Owner端的 OutputVideo发生变化时，回调该函数。
   * @param ownerOutput 是否输出。
   */
     OnOwnerOutputChanged:(ownerOutput:boolean)=>void

/**
   * 注入回调后,Owner端的摄像头视频分辨率发生变化时，回调该函数。
   * @param size 新的分辨率。
   */
  public OnOwnerCameraVideoSizeChanged:(size:Size)=>void

/**　　
   * 获取对方的屏幕分辨率。
   * @param ScreenSize屏幕的分辨率。
   */
 getScreenSize():ScreenSize

（1）调用BeginConnect 方法，以尝试连接目标用户Owner的设置，框架会将回调connectEnded来通知连接的结果。（MicrophoneConnector、DesktopConnector、WhiteBoardConnector 都同理）.

（2）CameraConnector通过模板层的OMCSSurfaceView来绘制图像，创建OMCSSurfaceView时需要传递连接的userID以及对应的CameraConnector实例。

2.MicrophoneConnector

 　　与CameraConnector相似，甚至更简单，不再赘述。 

3.DesktopConnector

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

/**
   * Owner端的 OutputVideo发生变化时，回调该函数。
   * @param ownerOutput 是否输出。
   */
  public OnOwnerOutputChanged:(ownerOutput:boolean)=>void

  /**
   * Owner端的屏幕分辨率发生变化时，回调该函数。
   * @param size 新的分辨率。
   */
  public OnOwnerScreenResolutionChanged:(size:Size)=>void

/**
   * 设置要绘制桌面的surfaceView
   * @param desktopRef 桌面surfaceView的实例
   */
  setDesktopSurfaceView(desktopRef:DesktopSurfaceView):void

　　 注意：远程桌面需要通过模板层的DesktopSurfaceView来绘制桌面图像，DesktopSurfaceView需要传递四个参数：

/**
 * 桌面连接器的控件
 * param onComponentReady 回调函数
 * @param Desktop DesktopConnector的实例。
 * @param userId 连接用户的ID。
 * @param xcomponentWidth 控件的宽度
 * @param  xcomponentHeight 控件的高度
 */
DesktopSurfaceView({
        onComponentReady:(desktopRef)=>{},
        Desktop,
        userId,
        xcomponentWidth,
        xcomponentHeight
      })

　　 其中，onComponentReady需要传递一个回调函数，当控件准备完毕时会回调出控件的实例，此时便可以将实例设置到DesktopConnector，当设置完成之后，才能调用beginConnect连接到对应的用户的桌面。

 

4.WhiteBoardConnector

　　通过WhiteBoardConnector可以连接到电子白板，并可在电子白板上绘制图形。

 /**
   * 开始连接到电子白板
   * @param whiteboardGroupID 连接的白板的ID
   */
  beginConnect(whiteboardGroupID:string):void;

　　注意：WhiteBoardConnector需要通过模板层的whiteboard控件来绘制图像。

/**
 * 电子白板的控件
 * @param CloseWhiteBoardCallback 电子白板关闭时触发的回调
 * @param onComponentReady 控件创建完成后，返回控件的实例
 */

whiteboard({
  CloseWhiteBoardCallback:()=>{},
  onComponentReady:(whiteboard)=>{}
})

  　其中，onComponentReady需要传递一个回调函数，当控件准备完毕时会回调出控件的实例。因为new出WhiteBoardConnector需要传入控件的实例，所以只有当onComponentReady回调出实例后，才可以new出WhiteBoardConnector并开始连接到电子白板。

　　

三. API使用流程

1. 设置多媒体管理器的相关参数，类似下面的示例代码：     

（1）MultimediaManagerFactory.GetSingleton().setCameraVideoSize(1280, 720);

（2）MultimediaManagerFactory.GetSingleton().setCameraEncodeQuality(15); 

2. 调用多媒体管理器的initialize方法，初始化并登录到OMCS服务器。

3. 使用设备连接器 Connector，来访问目标对象的设备。

（1）调用Connector的beginConnect方法，连接到目标设备。

（2）使用完毕，调用Connector的disconnect方法断开到目标设备的连接。　　

 

四. Demo及下载

1. OMCS 入门 Demo HarmonyOS 版源码：OmcsHarmonyDemo.rar

（1）压缩包中包含了两份源码：OmcsHarmonyDemoMobile 对应的是鸿蒙手机端，OmcsHarmonyDemoPC 对应的是鸿蒙PC端。

（2）Demo 服务端可执行程序：OMCS.ServerExe.rar

（3）该Demo详细介绍请 参见这里

 

2. OMCS Demo 实现视频聊天、远程桌面（简化版）： VideoChatMini_HarmonyOS.rar （该Demo详细介绍请 参见这里）