====== Android SDK 函数说明 ====== ===== 一. Android SDK 介绍 ===== UCPaaS融合通讯平台Android SDK以Java libs的方式提供给Android开发人员，该SDK提供了互联网语音通话、视频通话、实时语音群聊等能力。可以快速便捷帮您的Android应用APP实现语音通话、视频通话，语音会议等功能。在使用AndroidSDK之前，您可以先体验一下DEMO的功能演示，可以帮助您快速了解SDK提供的相关功能以及相关功能的实现方式。请点击[[http://www.ucpaas.com/freetrial/VoiceVerificationCode_demo#demo|Demo]]体验。 ==== 1. SDK 通讯类介绍 ==== ^名称 ^说明 | |UCSService | 核心通讯类，用于连接云服务平台 | |UCSCall | VoIP电话管理类,用于呼叫请求,挂断,静音等一系统操作 | ==== 2. SDK 工具类介绍 ==== ^名称 ^说明 | |DevicesAddressTools | 获取设备信息工具类 | |FileTools | 文件工具类 | |PhoneNumberTools| 电话号码验证工具类 | ===== 二. SDK 接口介绍 ===== ===== 1. 初始化及配置 ===== ====1.1. 初始化SDK==== 原型：- UCSService.init(Context mContext, boolean isSwitch) 功能：初始化SDK ，启动语音，视频等功能返回：无备注：必须在调用其他能力接口前调用参数： ^参数名 ^类型 ^约束 ^说明 | |mContext |Context |无 |当前程序上下文 | |isSwitch |Boolean |无 |日志开关 | ====1.2. 添加监听器==== 原型：- UCSService.addConnectionListener(ConnectionListener connectionListener) 功能：添加TCP连接监听器返回：无备注：连接服务成功的监听器参数： ^参数名 ^类型 ^约束 ^说明 | |connectionListener |ConnectionListener |无 |监听接口 | ====1.3. 移除监听器==== 原型：- UCSService.removeConnectionListener(ConnectionListener cl) 功能：移除监听器接口返回：无备注：移除之前添加的监听器参数： ^参数名 ^类型 ^约束 ^说明 | |cl |ConnectionListener |无 |监听接口 | ====1.4. 连接云平台(sid)==== 原型：- UCSService.connect(String accountSid, String accountToken, String ClientNumber, String ClientPwd) 功能：连接云平台返回：无备注：初始化后连接云平台参数： ^参数名 ^类型 ^约束 ^说明 | |accountSid |String |无 |开发者账户 | |accountToken |String |无 |开发者账户密码 | |ClientNumber |String |无 |子账号 | |ClientPwd |String |无 |子账号密码 | ====1.5. 连接云平台(token)==== 原型：- UCSService.connect(String token) 功能：连接云平台返回：无备注：初始化后连接云平台参数： ^参数名 ^类型 ^约束 ^说明 | |token |String |无 |开发者账户密码 | ====1.6. 获取连接云平台状态==== 原型：- UCSService.isConnected() 功能：判断TCP连接是否成功返回：true:连接成功；false:连接失败备注：TCP连接成功后判断是否TCP连接成功参数：无 ====1.7. 连接云平台回调==== ===1.7.0. 连接云平台成功回调=== 原型：- onConnectionSuccessful() 功能：连接云平台成功回调返回：无备注：连接云平台成功后回调此方法参数：无 ===1.7.1. 连接云平台失败回调=== 原型：- onConnectionFailed(UcsReason reason) 功能：连接云平台失败回调返回：无备注：连接云平台失败后回调此方法参数： ^参数名 ^类型 ^约束 ^说明 | |Reason |UcsReason |无 |失败返回信息 | ====1.8. 断开云平台连接==== 原型：- UCSService.uninit() 功能：断开与云平台的连接返回：无备注：断开与云平台的连接参数：无 ====1.9. 获取SDK版本号==== 原型：- UCSService.getSDKVersion() 功能：获取SDK 的版本返回：SDK 版本号备注：开发者通过此方法获得版本号参数：无 ====1.10. 打开/关闭SDK日志==== 原型：- UCSService.openSdkLog(Context mContext,boolean isOpenSdkLog) 功能：打开或者关闭SDK日志返回：无备注：无参数： ^参数名 ^类型 ^约束 ^说明 | |mContext |Context |无 |应用上下文 | |isOpenSdkLog |Boolean |无 |是否开启SDK日志 | ====1.11. 初始化SDK里面广播的action==== 原型：- UCSService.initAction(Context mContext) 功能：初始化SDK里面广播的action，保证广播的action是唯一的返回：无备注：无参数： ^参数名 ^类型 ^约束 ^说明 | |mContext |Context |无 |应用上下文 | =====2. 互联网音频通话能力接口===== voip是基于互联网网络进行语音传输的服务，无论客户处于互联网网络还是通讯网络，都可以无缝连接互联网语音的能力接口，支持多个平台（Android 、iOS、 Windows）。 ====2.1 注册VoIP电话监听器==== 原型：- UCSCall.addCallStateListener(CallStateListener csl) 功能：注册VoIP电话监听器，监听VoIP电话的各种状态返回：无备注：监听用户拨打电话的状态回调参数： ^参数名 ^类型 ^约束 ^说明 | |csl |CallStateListneer |无 |监听器实例 | ====2.2 移除VOIP电话监听器==== 原型：- UCSCall. removeCallStateListener (CallStateListener csl) 功能：移除VoIP电话监听器，监听VoIP电话的各种状态返回：无备注：移除VOIP的电话监听器参数： ^参数名 ^类型 ^约束 ^说明 | |csl |CallStateListneer |无 |监听器实例 | ====2.3 发起呼叫==== 原型：- UCSCall.dial(Context mContext,CallType callType,String calledNumner,String userdata) 功能：发起呼叫返回：无备注：无参数： ^参数名 ^类型 ^约束 ^说明 | |mContext |Context |无 |程序上下文 | |callType |CallType |无 |拨打电话方式VOIP:音频, VIDEO:视频 | |calledNumber |String |无 |被叫手机号码或Client账号 | |userData |String |无 |自定义透传数据(用于需要借助PaaS平台透传数据给AS服务器或者被叫方，最大长度128字节) | ====2.4 释放通话==== 原型：- UCSCall.hangUp(Context mContext, String callid) 功能：挂断电话返回：无备注：挂断电话,callId一般传空字符串参数： ^参数名 ^类型 ^约束 ^说明 | |mContext |Context |无 |程序上下文 | |callid |String |无 |当前通话id (目前版本为空) | ====2.5 接听来电==== 原型：- UCSCall.answer(Context mContext, String callid) 功能：接听电话返回：无备注：被叫接听,callid一般传空字符串参数： ^参数名 ^类型 ^约束 ^说明 | |mContext |Context |无 |程序上下文 | |callid |String |无 |当前通话id (目前版本为空) | ====2.6 发送DTMF==== 原型：- UCSCall.sendDTMF(Context mContext, int keyCode, EditText call_dtmf) 功能：发送DTMF 返回：无备注：发送拨打电话数字参数： ^参数名 ^类型 ^约束 ^说明 | |mContext |Context |无 |程序上下文 | |keyCode |int |无 |KeyEnvent CODE | |call_dtmf |EditText |无 |用于显示输入的keyCode值 | ====2.7 设置扬声器状态==== 原型：- UCSCall.setSpeakerphone(Context mContext，boolean isSpeakerphoneOn) 功能：设置扬声器状态返回：无备注：控制扬声器的开关参数： ^参数名 ^类型 ^约束 ^说明 | |mContext |Context |无 |程序上下文 | |isSpeakerphoneOn |Boolean|无 |false:关闭 true:开启 | ====2.8 获取扬声器状态==== 原型：- UCSCall.isSpeakerphoneOn(Context mContext) 功能：获取扬声器状态返回：true：开启；false：关闭备注：获取扬声器状态参数： ^参数名 ^类型 ^约束 ^说明 | |mContext |Context |无 |程序上下文 | ====2.9 设置静音状态==== 原型：- UCSCall.setMicMute( boolean isMicMute) 功能：设置静音状态返回：无备注：设置静音参数： ^参数名 ^类型 ^约束 ^说明 | |isMicMute |boolean |无 |true：静音；false：正常 | ====2.10 获取静音状态==== 原型：- UCSCall.isMicMute() 功能：获取静音状态返回：boolean true：静音；false：正常备注：获取设备的静音状态参数：无 ====2.11 播放来电铃声==== 原型：- UCSCall.startRinging(Context mContext, boolean isVibrator) 功能：播放来电铃声返回：无备注：播放来电铃声,这个铃声是系统铃声参数： ^参数名 ^类型 ^约束 ^说明 | |mContext |Context |无 |程序上下文 | |isVibrator |boolean |无 |是否振动 | ====2.12 停止播放来电铃声==== 原型：- UCSCall.stopRinging(Context mContext) 功能：停止播放来电铃声返回：无备注：停止播放来电铃声参数： ^参数名 ^类型 ^约束 ^说明 | |mContext |Context |无 |程序上下文 | ====2.13 播放去电铃声==== 原型：- UCSCall.startCallRinging(Context mContext,String fileName) 功能：播放去电铃声返回：无备注：自己定义铃声文件，这个铃声文件一般放在assets目录下参数： ^参数名 ^类型 ^约束 ^说明 | |mContext |Context |无 |程序上下文 | |fileName |String |无 |音频裸数据文件名称,为PCM格式，放在assets目录下 | ====2.14 停止播放去电铃声==== 原型：- UCSCall.stopCallRinging(Context mContext) 功能：停止播放去电铃声返回：无备注：无参数： ^参数名 ^类型 ^约束 ^说明 | |mContext |Context |无 |程序上下文 | ====2.15 开启录音==== 原型：- UCSCall.StartRecord(String filePath) 功能：开启录音返回： 0:成功；-1:失败备注：此方法在电话接通时设置参数： ^参数名 ^类型 ^约束 ^说明 | |filePath |String |无 |保存录音文件路径 | ====2.16 停止录音==== 原型：- UCSCall.StopRecord () 功能：停止录音返回： 0:成功；-1:失败备注：此方法在电话挂断时设置参数：无 =====3. 互联网音频通话状态回调接口===== ====3.1 呼叫失败回调通知==== 原型：- onDialFailed (String callid，UcsReason reason) 功能：呼叫失败回调返回：无备注：无参数： ^参数名 ^类型 ^约束 ^说明 | |callid |String |无 |当前通话id (目前版本可以为空)| |reason |UcsReason |无 |呼叫失败的原因 | ====3.2 呼叫被释放回调通知==== 原型：- onHangUp(String callid，UcsReason reason) 功能：呼叫释放返回：无备注：无参数： ^参数名 ^类型 ^约束 ^说明 | |callid |String |无 |当前通话id (目前版本可以为空)| |reason |UcsReason |无 |呼叫被释放的原因 | ====3.3 被叫振铃回调通知==== 原型：- onAlerting (String callid) 功能：呼叫振铃返回：无备注：无参数： ^参数名 ^类型 ^约束 ^说明 | |callid |String |无 |当前通话id (目前版本可以为空)| ====3.4 被叫接听回调通知==== 原型：- onAnswer(String callid) 功能：被叫接听返回：无备注：无参数： ^参数名 ^类型 ^约束 ^说明 | |callid |String |无 |当前通话id (目前版本可以为空)| ====3.5 来电回调通知==== 原型：- onIncomingCall(String callId, String callType, String callerNumber ,String nickName,String userdata) 功能：来电话时候回调此方法返回：无备注：无参数： ^参数名 ^类型 ^约束 ^说明 | |callid |String |无 |返回当前电话id号 | |callType |String |无 |来电类型：0：Voip来电 1：视频来电 | |callerNumber |String |无 |主叫号码 | |nickName |String |无 |显示主叫昵称(未使用时，可不关心) | |userdata |String |无 |用户透传数据(未使用时，可不关心) | ====3.6 DTMF回调通知==== 原型：- public void onDTMF(int dtmfCode) 功能：DTMF回调返回：无备注：DTMF回调(*号为10 #号为11) 参数： ^参数名 ^类型 ^约束 ^说明 | |dtmfCode |int |无 |DTMF回调(*号为10 #号为11) | ====3.7 单通回调==== 原型：- public void singlePass(int reason) 功能：单通出现后回调此方法返回：无备注：无参数： ^参数名 ^类型 ^约束 ^说明 | |reason |int |无 |单通回调的错误码 | ====3.8 网络状态上报回调==== 原型：- public void onNetworkState(int reason，String message) 功能：网络状态上报回调此方法返回：无备注：无参数： ^参数名 ^类型 ^约束 ^说明 | |reason |int |无 |0无法获取网络状态, 1网络状态极好, 2网络状态良好, 3网络状态一般, 4网络状态极差 | |message |String |无 |描述 | =====4. 互联网视频通话能力接口===== ====4.1 设置视频显示参数==== 原型：- UCSCall.initCameraConfig(Activity mActivity, LinearLayout remoteLinearLayout, LinearLayout localLinearLayout) 功能：初始化视频设置返回：无备注：无参数： ^参数名 ^类型 ^约束 ^说明 | |mActivity |Activity |无 |显示视频界面的activity | |remoteLinearLayout |LinearLayout |无 |显示对方视频的布局 | |localLinearLayout |LinearLayout |无 |显示本地视频的布局 | ====4.2 用户自定义编解码参数==== 原型：- UCSCall. setVideoAttr(VideoDecParam videoDecparam,VideoEncParam videoEncParam) 功能：设置用户定义的编解码返回：无备注：无参数： ^参数名 ^类型 ^约束 ^说明 | |videoDecparam |VideoDecParam |无 |编码参数 | |videoEncParam |VideoEncParam |无 |解码参数 | ====4.3 刷新摄像头==== 原型：- UCSCall. refreshCamera(UCSCameraType cameraType, UCSFrameType frameType) 功能：刷新视频显示返回：无备注：无参数： ^参数名 ^类型 ^约束 ^说明 | |cameraType |UCSCameraType |无 |刷新摄像头的枚举 | |frameType |UCSFrameType |无 |是否显示边框的枚举 | ====4.4 获取摄像头个数==== 原型：- UCSCall. getCameraNum() 功能：获取摄像头个数返回：摄像头个数备注：无参数：无 ====4.5 获取当前摄像头索引==== 原型：- UCSCall. getCurrentCameraIndex() 功能：获取当前摄像头索引返回：摄像头索引备注：无参数：无 ====4.6 切换摄像头==== 原型：- UCSCall. switchCameraDevice(int cameraIndex,RotateType rotateType) 功能：切换摄像头旋转角度返回：无备注：无参数： ^参数名 ^类型 ^约束 ^说明 | |cameraIndex |int |无 |摄像头索引 | |rotateType |RotateType |无 |旋转角度 | ====4.7 打开本地/远程摄像头==== 原型：- UCSCall. openCamera(UCSCameraType camera) 功能：打开本地/远程摄像头返回：无备注：无参数： ^参数名 ^类型 ^约束 ^说明 | |camera |UCSCameraType |无 |摄像头类型枚举 | ====4.8 关闭本地/远程摄像头==== 原型：- UCSCall. closeCamera(UCSCameraType camera) 功能：关闭摄像头返回：无备注：停止本地摄像头，把本地界面隐藏但是可以接收数据和发送数据参数： ^参数名 ^类型 ^约束 ^说明 | |cameraType |UCSCameraType |无 |摄像头类型枚举 | ====4.9 视频模式切换==== 原型：- UCSCall. switchVideoMode(UCSCameraType cameraType) 功能：视频模式切换返回：无备注：四种视频模式：本地模式、远程模式、后台模式、正常模式。 * 远程模式：处于视频流接收状态。可以看到对方的视频，对方不能看本端的视频。 * 本地模式：处于视频流发送状态，不可以看到对方的视频，对方能看本端的视频。 * 后台模式：关闭了接收数据，但是可以发送数据，这个状态一般在刷新摄像头和关闭摄像头方法中使用 * 正常模式：处于视频流发送以及接收状态，双方视频正常状态。参数： ^参数名 ^类型 ^约束 ^说明 | |cameraType |UCSCameraType |无 |UCSCameraType: 枚举远程模式、本地模式、后台模式、正常模式 | ====4.10 开启/关闭视频来电预览==== 原型：- UCSCall. setCameraPreViewStatu(Context mContext,boolean isPreView) 功能：开启/关闭视频来电返回：无备注：无参数： ^参数名 ^类型 ^约束 ^说明 | |mContext |Context |无 |上下文 | |isPreView |boolean |无 |true:支持 false:不支持 | ====4.11 获取来电时是否支持预览==== 原型：- UCSCall. isCameraPreviewStatu(Context mContext) 功能：查询是否开启视频来电预览返回：true:已开启 false:未开启备注：无参数： ^参数名 ^类型 ^约束 ^说明 | |mContext |Context |无 |上下文 | ====4.12 视频截图==== 原型：- UCSCall. videoCapture(UCSCameraType isLocal,String filenName,String savePath) 功能：视频截图返回：无备注：无参数： ^参数名 ^类型 ^约束 ^说明 | |isLocal |UCSCameraType |无 |摄像头类型枚举 | |filenName |String |无 |预保存的文件名 | |savePath |String |无 |视频文件保存的路径 | ====4.13 视频旋转==== 原型：- UCSCall. videoSetSendReciveRotation(int send_rotation, int recived_rotation) 功能：视频旋转返回：无备注：无参数： ^参数名 ^类型 ^约束 ^说明 | |send_rotation |int |无 |发送的视频旋转角度 | |recived_rotation |int |无 |接收的视频旋转角度 | ====4.14 打开/关闭闪光灯==== 原型：- UCSCall. setFlashCode(boolean mode) 功能：打开/关闭闪光灯返回：无备注：无参数： ^参数名 ^类型 ^约束 ^说明 | |mode |boolean |无 |打开：true关闭:false | ====4.15 获取闪关灯状态==== 原型：- UCSCall. getFlashCode() 功能：获取闪关灯状态返回：ture:已开启 false:已关闭备注：无参数：无 =====5. 互联网视频通话状态回调接口===== ====5.1 远程视频模式回调通知==== 原型：- public void onRemoteCameraMode (UCSCameraType cameraType) 功能：回调远端视频模式返回：无备注：无参数： ^参数名 ^类型 ^约束 ^说明 | |cameraType |UCSCameraType |LOCALCAMERA,只开了本地视频；REMOTECAMERA, 只开了远端视频；ALL 双向视频都开启了 |无 | ====5.2 视频截屏回调通知==== 原型：- public void onCameraCapture (String videoCapFilePath) 功能：视频截屏成功调用返回：无备注：无参数： ^参数名 ^类型 ^约束 ^说明 | |videoCapFilePath |String |无 |截屏图片保存的路径 | =====6. 枚举类说明===== ====6.1 CallType 呼叫类型==== 枚举类，呼叫类型：VOIP(音频)，VIEDO(视频) ====6.2 ClientType 账户类型==== 枚举类，两种账户类型：PHONE，CLIENT。 ====6.3 RotateType 视频旋转类型==== 枚举类，五种旋转类型： DEFAULT：顺时针旋转90度 RETATE_0：横的90度，头朝x轴负方向 RETATE_90: 顺时针旋转90度 RETATE_180: 顺时针旋转180度 RETATE_270: 顺时针旋转270度 ====6.4 UCSCameraType 视频类型==== 枚举类，四种视频类型： LOCALCAMERA：本地视频，处于发送状态时候，只发送本地视频流。 REMOTECAMERA：远程视频，处于接收状态时候，只接收对方的视频流。 BACKGROUNDCAMERA：后台模式，关闭了接收但是可以发送，一般在刷新摄像头和关闭摄像头方法中使用。 ALL：全部，既发送也接收视频流。 ====6.5 UCSFrameType视频边框类型==== 枚举类，两种边框类型：ORIGINAL，FRAME。 ====6.6 VideoExternFormat外部视频采集格式类型==== 枚举类，两种采集格式类型：i420，h264。 =====7. 注意事项===== ====7.1 视频电话使用流程（代码调用流程）==== {{:video_sdk:android_sdk_notice01.png|}} {{:video_sdk:android_sdk_notice02.png|}} ====7.2 SDK所需权限====

====7.3 配置SDK核心控制器==== 在AndroidManifest中配置如下核心控制器:

====7.4 AndroidManifest注意事项:==== 请勿在AndroidManifest中配置如下属性,否则会导致视频功能不可用: android:targetSdkVersion ====7.5 摄像头操作接口==== 关于摄像头的操作接口，如前后摄像头切换、摄像头旋转角度等操作，需要在通话建立后，才可以操作。通话结束后的复位操作需要开发者自己完成。 ====7.6 静音、扬声器、闪光灯等设备操作接口==== 静音、扬声器、闪光灯等设备操作接口，需要在主叫收到onAlerting回调时或者被叫收到onIncomming回调时进行操作。通话结束后的复位操作需要开发者自己完成。 ====7.7 视频来电预览操作接口==== 视频来电预览接口，在进行通话业务前进行配置。配置一次即可，不需要每通电话都配置。 =====8. 相关对象说明===== ^所属类 ^函数 ^说明 | |UcsReason |getReason() |获取当前错误码 | |UcsReason |getMsg() |获取错误码描述 | ^枚举类 ^枚举值 ^说明 | |VideoExternFormat |i420 |i420文件 | |VideoExternFormat |h264 |h264文件 |