OMCS 开发手册之 Android SDK 说明

（OMCS android SDK 目前版本提供的功能有：语音、视频、远程桌面（手机屏幕分享）、电子白板。）

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

一. IMultimediaManager 接口

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

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

    /**
     * 与OMCS服务器的TCP连接状态监听
     * @param connectionEventListener 连接状态监听器
     */
    void  setConnectionEventListener(IConnectionEventListener connectionEventListener);

    /**
     * 设备的guest监听。
     * @param listener
     */
    void setDeviceGuestListener(IDeviceGuestListener listener);

    /**
     * 主动断开来访者guest到本地多媒体设备的连接。
     * @param guestID 来访者ID
     * @param deviceType  设备类型
     * @param notifyGuest 是否通知对方。如果通知对方，对方的连接器将触发Disconnected事件。
     */
    void disconnectGuest(String guestID, MultimediaDeviceType deviceType, boolean notifyGuest);

    /**
     * 查询本地的某设备是否正在工作？     *
     * @param deviceType 设备类型
     * @return 工作中？
     */
    boolean deviceIsWorking(MultimediaDeviceType deviceType);

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

    /**
     * 获取语音消息控制器。
     * @return
     */
    IAudioMessageController getAudioMessageController();

    /**
     * 在广播帧的时候，是否允许丢弃帧。必须在初始化前设置才有效。     *
     * @param isAllow
     */
    void setAllowDiscardFrameWhenBroadcast(boolean isAllow);

    /**
     * 注入自定义的摄像头采集器。将取代OMCS框架内部自带的摄像头采集器。
     * @param cameraCapturer
     */
    void setCameraCapturer(ICameraCapturer cameraCapturer);

 　　/**
     * 注入自定义的麦克风采集器。将取代OMCS框架内部自带的麦克风采集器。
     * @param microphoneCapturer
     */
    void setMicrophoneCapturer(IMicrophoneCapturer microphoneCapturer);

    /**
     * 注入自定义的桌面采集器。将取代OMCS框架内容自动的桌面采集器
     * @param desktopCapturer
     */
    void setDesktopCapturer(IDesktopCapturer desktopCapturer);

基础部分的方法很容易理解，但要注意：

（1）与服务器的连接状态

IConnectionEventListener接口用于监听与服务器TCP连接的状态监听，比如，连接断开、重连开始、重连完成等事件。（注意：OMCS框架内部采用了自动重连机制）

通过IMultimediaManager的setConnectionEventListener方法注入该监听器。

（2）Guest连接、断开事件

IDeviceGuestListener接口用于监听Guest连接到我的设备，或与我的设备断开连接的事件。

通过IMultimediaManager的setDeviceGuestListener方法注入该监听器。

1.摄像头

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

 /**
     * 使用的摄像头索引
     */
    int getCameraDeviceIndex();

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

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

    /**开始相机预览。
     * @param holder
     */
    void startCameraPreview( SurfaceHolder holder );

    /**
     * 设置打开相机的回调。
     * @param _callback
     */
    void setCameraOpenCallBack(ICamOpenOverCallback _callback);

    Camera getCamera();

    /**
     * 旋转摄像头预览图像
     * @param rotateAngle
     */
    void setCameraRotateAngle(RotateAngle rotateAngle);

    /**
     * 获取摄像头采集视频的分辨率。
     */
    Size getCameraVideoSize();

    /**摄像头采集视频的大小。默认为320x240。
     * @param width 宽
     * @param height 高
     */
    void setCameraVideoSize(int width,int height);

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

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

（1）CameraSurfaceView 类

OMCS 提供了 CameraSurfaceView 类，用于显示自己的摄像头的预览画面，OMCS框架会在其surfaceCreated回调中自动打开摄像头，并在其surfaceDestroyed回调中关闭摄像头。

当OMCS打开摄像头完成时，会回调ICamOpenOverCallback 接口。通过IMultimediaManager的setCameraOpenCallBack方法，可以注入自己的ICamOpenOverCallback实现。

（2）ICamOpenOverCallback 接口

可以让采集视频的activity实现ICamOpenOverCallback接口，当摄像头打开成功或失败时此回调方法会被调用。

在打开摄像头成功的回调方法cameraHasOpened里，调用CameraSurfaceView 的 getSurfaceHolder可以得到SurfaceHolder 引用，将其传给 startCameraPreview方法，便可开启摄像头预览。

（3）setCameraVideoSize 、setCameraEncodeQuality 、setCameraRotateAngle、setCameraDeviceIndex、switchCameraDeviceIndex、setOutputVideo 都很容易理解，不赘述。

2.麦克风

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

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

3.屏幕/桌面

安卓端可以将自己的屏幕分享给guest观看或监视（guest端可以是PC、安卓、iOS）。

   /**
     * 如果其它guset会连接到当前手机的屏幕（远程桌面、屏幕分享），那么必须先设置Activity。
     * @param activity
     */
    void setDesktopRecordActivity(Activity activity);

    /**
     * 如果其它guset会连接到当前手机的屏幕（远程桌面、屏幕分享），那么必须在setDesktopRecordActivity方法所设置的目标Activity的onActivityResult方法中调用该方法。
     * @param requestCode
     * @param resultCode
     * @param data
     */
    void setDesktopRecordActivityResult(int requestCode, int resultCode, Intent data);
		
    /**
     * 设置允许对方控制自己的桌面 (注 ：activity 为null时 ，表示不允许控制）
     * @param activity
     */
    void setDesktopControlActivity(Activity activity) ;
        
    /**
     * 本地屏幕的编码质量。取值0~31，默认值10。取值越小，越清晰。
     *
     * @param quality
     */
    void setDesktopEncodeQuality(int quality);
	
    /**
     * 输出屏幕的分辨率的缩小系数。默认值：0.5。取值范围：大于等于0.1且小于等于1。
     *
     * @param coef 缩小的比例系数。取值范围：大于等于0.1且小于等于1。
     */
    void setDesktopZoomCoef(float coef);

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

    /**
     * 设置当前桌面设备的运行模式。默认值：DesktopDeviceRunMode.RunWhenNeed。
     * 如果手机持有者拒绝了屏幕采集的权限请求，则将恢复为默认值：DesktopDeviceRunMode.RunWhenNeed。
     * @param mode
     */
    void setDesktopDeviceRunMode(DesktopDeviceRunMode mode)  throws Exception;

    /**
     * 获取当前桌面设备的运行模式。
     * @return
     */
    DesktopDeviceRunMode getDesktopDeviceRunMode();

（1）setDesktopRecordActivity：安卓系统要求在后台采集屏幕图像，必须和一个Activity绑定。

（2）setDesktopRecordActivityResult：当采集屏幕图像时，APP会向安卓系统申请权限，此时界面会弹出权限请求的提示给用户操作同意/拒绝，用户操作之后，APP拿到用户的操作结果（同意或拒绝），则调用setDesktopRecordActivityResult通知OMCS框架。

二.多媒体连接器 Connector

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

    /**
     * 设置连接器事件监听器。    
     */
    void setConnectorEventListener(IConnectorEventListener listener);

    /**
     * 获取当前连接器的设备类型    
     */
    MultimediaDeviceType getDeviceType() ;

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

    /**
     * Owner方的UserID。
     */
    String getOwnerID();

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

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

（1）调用beginConnect方法，以尝试连接目标用户Owner的设备，框架将通过回调IConnectorEventListener接口通知连接的结果。

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

1.CameraConnector

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

    /**
     * 设置摄像头连接器状态回调。     
     */
    void setCameraConnectorCallback(ICameraConnectorCallback callback);

    /**
     * 设置要绘制视频的View。    
     */
    void setOtherVideoPlayerSurfaceView(OMCSSurfaceView view);

    /**
     * Owner端是否输出了视频？（对应Owner端可以调用setOutputVideo方法）     
     */
    boolean getOwnerOutput();

    /**
     * 修改Owner端的视频采集分辨率。     
     */
    void changeOwnerCameraVideoSize(int width,int height);

    /**
     * 设置视频图像缩放。
     * @param videoScale 是否等比缩放？如果否，则表示填满画布
     * @param videoScale4BigSide false 表示小的那边留黑边，true表示裁剪大的那一边
     */
    void setVideoUniformScale(boolean videoScale,boolean videoScale4BigSide) 

   /**
     * 设置视频图像旋转的角度（0，90，180，270）。
     * @param angle
     */
    public void setRotateAngle(RotateAngle angle)

通过ICameraConnectorCallback回调，我们可以得知Owner端的摄像头采集分辨率发生了变化、outputVideo状态发生了变化。

CameraConnector通过OMCSSurfaceView来绘制视频图像：

（1）如果需要旋转视频图像，可以调用CameraConnector的setRotateAngle方法来设置旋转的角度：0，90，180，270。

（2）如果要设置视频图像是等比缩放还是拉伸以填满画布，可以调用CameraConnector的setVideoUniformScale方法，默认值为false（填满画布）。

2.MicrophoneConnector

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

3.DesktopConnector

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

DesktopConnector与CameraConnector相似，不再赘述。

4.WhiteBoardConnector

通过WhiteBoardConnector可以连接到电子白板，并可在电子白板上绘制图形。白板绘制功能接口如下：

 　　/**
     * 设置白板课件监听器
     * */
    void setCoursewareListener(ICoursewareListener listener);

    /**
     * 设置Page显示的尺寸(绘图只能在该范围内绘制)  默认尺寸1200，900
     * @param width
     * @param height
     */
    void setPageSize(int width, int height);

    /**
     * 重置界面到最初状态
     * */
    void resetScale();

    /**
     * 设置界面为画曲线状态
     * */
    void setDrawCurveEnable(boolean enabled);

    /**
     * 设置选择View 的状态  （目前仅支持选中PictureView）
     * @param enabled
     */
    void setHitViewEnabled(boolean enabled);

    /**
     * 获取当前选中的View 的状态  （目前仅支持选中PictureView）
     */
    boolean getHitViewEnabled();

    /**
     * 插入图片
     * @param bitmap
     */
    void insertPictureView(Bitmap bitmap);

    /**
     * 设置已选中的PictureView视图为背景
     */
    void setSelectedPictureViewAsBackImage();

    /**
     * 移除背景
     */
    void removeWhiteBoardBackImage();

    /**
     * 移除当前页面自己最后一次新增的view
     * */
    void removeMyLastView();

    /**
     * 设置控制点图像
     * */
    void setPointer(Bitmap bitmap);

    /**
     * 获取Page显示的尺寸
     * @return
     */
    Size getPageSize();

    /**
     * 是否显示Page的边框，默认不显示
     * @param isDisplay
     */
    void setDisplayPageBorder(boolean isDisplay);

    /**
     * 清空当前页
     */
    void clearCurrentPage();

    /**
     * 创建新的一页
     */
    void createPage();

    /**
     * 移除当前页
     * @throws Exception
     */
    void removeCurrentPage() throws Exception;

    /**
     * 获取当前显示页的索引
     * @return
     */
    int getCurrentPageIndex();

    /**
     * 设置当前显示页的索引 （0开始）
     * @param pageIndex
     */
    void setCurrentPageIndex(int pageIndex);

    /**
     * 获取总页数
     * @return
     */
    int getTotalPageCount();

    /**
     * 设置页面事件变动监听器
     * @param listener
     */
    void setPageEventListener(IPageEventListener listener);

其中 IPageEventListener接口定义如下：

     /**
     * 当前页面索引变动 （索引0开始）
     * @param pageIndex
     * @return
     */
    void curPageIndexChanged(int pageIndex);

    /**
     * 当前总页数变动
     * @param totalPageCount
     * @return
     */
    void totalPageCountChanged(int totalPageCount);

关于课件，安卓端白板目前只支持RAR、ZIP的图片压缩包。当PC客户端打开课件时，安卓端白板会自动下载、解压、并在白板中显示课件。

ICoursewareListener 接口用于监听课件下载与解压的进度，其定义如下：

　　/**
     * 开始下载课件
     * @param courseware
     * @return
     */
    void downloadStarted(String courseware);

    /**
     * 下载课件的进度
     * @param courseware
     * @param progressNum
     * @param totalProgressNum
     * @return
     */
    void downloadProgress(String courseware,long progressNum,long totalProgressNum);

    /**
     * 下载课件失败
     * @param courseware
     * @param failReason
     * @return
     */
    void downloadFail(String courseware,String failReason);

    /**
     * 下载课件完成
     * @param courseware
     * @return
     */
    void downloadCompleted(String courseware);

    /**
     * 开始解压 压缩包课件
     * @param courseware
     * @return
     */
    void decompressStarted(String courseware);

    /**
     * 解压 压缩包课件失败
     * @param courseware
     * @param failReason
     * @return
     */
    void decompressFail(String courseware, String failReason);

    /**
     * 解压 压缩包课件完成
     * @param courseware
     * @return
     */
    void decompressCompleted(String courseware);

三. 语音消息控制器

类似微信的语音消息功能，通过通过IMultimediaManager的getAudioMessageController方法可以获取语音消息控制器的引用。

关于IAudioMessageController接口的使用，请参见《OMCS 开发手册（10）－－语音消息》。

四. 注入自定义视频流

通过IMultimediaManager提供的 setCameraCapturer方法来向OMCS 注入自定义的外部视频流，以取代手机摄像头采集到的图像。

    /**
     * 注入自定义的摄像头采集器。将取代OMCS框架内部自带的摄像头采集器。
     * @param cameraCapturer
     */
    void setCameraCapturer(ICameraCapturer cameraCapturer);

其中ICameraCapturer 接口包含了如下方法：

/**
 * 摄像头采集器接口。
 */
public interface ICameraCapturer {

    /**
     * 采集的视频数据类型 （NV21、H264）
     * @return
     */
    VideoDataType getVideoDataType();

    /**
     * 采集的视频的分辨率。
     * @return
     */
    Size getVideoSize() ;

    /**
     * 开始采集
     * @param callback
     */
    void start(ICameraCapturerCallback callback);

    /**
     * 停止采集
     */
    void stop();
}