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(); }
实现 ICameraCapturer 接口，如果我们需要外接注入时，就new一个刚实现的视频采集类的实例注入到多媒体管理器；如果不需要外接数据注入null即可。
五. API使用流程
1. 设置多媒体管理器的摄像头，类似下面的示例代码：
（1）MultimediaManagerFactory.GetSingleton().setCameraVideoSize(640, 480);
（2）MultimediaManagerFactory.GetSingleton().setCameraEncodeQuality(15);
2. 调用多媒体管理器的initialize方法，初始化并登录到OMCS服务器。
3. 使用设备连接器Connector
（1）调用Connector的setConnectorEventListener设置回调，监听连接目标设备是否成功。
（2）调用Connector的beginConnect方法，连接到目标设备。
（3）使用完毕，调用Connector的disconnect方法断开到目标设备的连接。
六. Demo及下载
我们为 OMCS入门Demo 增加了一个简单的Android客户端，可与PC进行视频聊天，其运行效果如下所示：
登录：
连接对方：
视频对话：
下载：
（1）OMCS入门Demo源码（服务端 + PC端） （安卓端与PC端 公用同一个服务端）
（2）OMCS入门Demo之Android端 apk & Source code
上一篇：OMCS 开发手册（11） －－ 深入摄像头、麦克风、扬声器
--------------------------------------------------------------------------------------------------------------------
阅读 更多OMCS开发手册系列文章 。
Q Q：168757008
官网： www.oraycn.com
