====== iOS SDK接口介绍 ====== 本页介绍iOS SDK集成至应用内所需的功能接口函数，当你计划接入SDK提供的语音、视频、IM等相关服务时，都必须先初始化，初始化完成以后才能接入其他函数的功能。如果计划使用语音和视频功能服务，则需要集成TCP SDK和Video SDK。如果计划使用IM功能服务，则需要集成TCP SDK和IM SDK。如果计划使用语音、视频、IM等相关服务，则需要集成TCP SDK、Video SDK和IM SDK。 SDK初始化流程

初始化UCSTcpClient实例对象----->初始化UCSService实例对象----->使用UCSTcpClient对象接入云平台----->音视频能力、IM能力

我们为集成SDK提供了更加详细的：[[iossdkguide|开发指南]]，此外我们针对SDK开发一个用于功能演示的Demo（[[http://www.ucpaas.com/product_service/download|下载地址]]） ===== 1、TCP SDK初始化配置连接 ===== ====1.1 初始化实例==== 原型：+ (instancetype)sharedTcpClientManager; 功能：实例化UCSTcpClient的一个单例对象，启动连接云平台能力，所有功能实现都要基于与云平台的连接。返回：UCSTcpClient实例对象备注：必须在调用其他能力接口前调用，这个方法是生成UCSTcpClient的唯一方法，请不要使用init()等其他初始化方法，否知会出现未知的错误参数：无 ====1.2 设置事件代理==== 原型：- (void)setTcpDelegate:(id ) delegate; 功能：设置TCP SDK代理。返回：无备注：如果需要通过回调监控tcp连接状态之类的，就必须设置这个代理。一般在初始化实例后，连接云平台前调用。参数： ^参数名 ^类型 ^约束 ^说明 | |delegate |UCSTCPDelegateBase |必选 |tcp事件回调代理 | ====1.3 连接云平台(明文)==== 原型：- (void)login_connect_old:(NSString *)accountSid withAccountToken:(NSString *)accountToken withClientNumber:(NSString *)clientNumber withClientPwd:(NSString *)clientPwd success:(void (^)(NSString *userId))success failure:(void (^)(UCSError *error))failure; 功能：连接到云之讯平台返回：无备注：一般在初始化实例后，连接云平台时调用(注意：这个登陆方式是为了兼容旧的SDK,后面可能会废弃)。使用这个接口的唯一场景是: 用户已经在现有的app中集成了我们旧的SDK,并且不希望更改成新的登陆方式(云之讯建议你更改成新的登陆方式)。其他场景下，请使用新的登陆方式。参数： ^参数名 ^类型 ^约束 ^说明 | |accountSid |NSString |必选 |开发者账号Id | |accountToken |NSString |必选 |开发者账户token(官网注册开发者账号时，由云平台自动分配) | |clientNumber |NSString |必选 |Client账号 | |clientPwd |NSString |必选 |Client账号密码 | |success |block |必选 |登陆成功回调Block，返回值userid | |failure | block |必选 |登陆失败回调block，返回值UCSError的实例对象 | ====1.4 连接云平台(密文)==== 原型：- (void)login_connect:(NSString *)token success:(void (^)(NSString *userId))success failure:(void (^)(UCSError *error))failure; 功能：连接到云之讯平台。返回：无备注：一般在初始化实例后，连接云平台时调用。(注意: 除非是为了兼容旧的SDK,否则请使用这个登陆方式)。 参数： ^参数名 ^类型 ^约束 ^说明 | |token |NSString |必选 |加密的token | |success |block |必选 |登陆成功回调Block，返回值userid | |failure | block |必选 |登陆失败回调block，返回值UCSError的实例对象 | ====1.5 获取连接云平台状态==== 原型：- (BOOL)login_isConnected; 功能：判断当前帐号与云平台的连接状态返回：YES：已连接；NO：未连接备注：开发者在使用能力接口前，可以通过该接口，判断是否已经正常连接云平台参数：无 ====1.6 断开云平台==== 原型：- (void)login_uninitWithFlag:(BOOL)flag; 功能：断开客户端和云平台的连接，并且根据flag标识的bool值选择是否关闭离线推送（推送功能暂时只有IM使用）。返回：无备注：在客户端不需要继续与云平台保持连接的时候，调用这个方法断开连接。断开连接后，客户端将不会再收到与云平台的消息推送，也无法发送消息到云平台。断开连接，不会影响APNS离线推送功能参数： ^参数名 ^类型 ^约束 ^说明 | |flag |BOOL |必选 |是否关闭推送的bool值。YES，关闭。NO，不关闭。(暂时只有IM使用推送功能) | ====1.7 查询当前网络状态==== 原型：- (UCSNetworkStatus)getCurrentNetWorkStatus; 功能：查询当前网络状态返回：当前网络状态UCSNetworkStatus枚举备注：无参数：无 =====2、 TCP SDK连接事件代理接口 ===== 目的是提供TCP的网络链接状态的监听。 ====2.1 TCP SDK连接状态事件代理==== 原型：- (void)didConnectionStatusChanged:(UCSConnectionStatus)connectionStatus error:(UCSError *) error; 功能：监听连接状态返回：无备注：连接状态变化时，会通过此方法回调开发者。参数： ^参数名 ^类型 ^约束 ^说明 | |connectionStatus |UCSConnectionStatus |必选 |连接状态的枚举值，具体参考UCSTcpDefine.h文件 | |error |UCSError |必选 |错误码实例对象 | =====3、音视频引擎初始化配置接口 ===== ====3.1 初始化实例==== 原型：- (UCSService *) initWithDelegate:(id)delegate; 功能：初始化SDK，启动能力服务，以便用户使用语音、视频等相关能力接口。返回：UCSService实例对象备注：必须在调用其他能力接口前调用，在tcp sdk初始化之后，tcp sdk登陆之前调用。只需要初始化一次，初始化完成后保存返回的对象。参数： ^参数名 ^类型 ^约束 ^说明 | |delegate |UCSEventDelegate |必选 |为事件回调代理（提供互联网音视频能力回调等实例对象）， \\ 详细参见UCSEvent.h | ====3.2 设置事件代理==== 原型：-(void)setDelegate:(id< UCSEventDelegate>)delegate; 功能：设置事件代理方法返回：无备注：一般在初始化实例后，调用其他能力接口前调用，在tcp sdk初始化之后，tcp sdk登陆之前调用。参数： ^参数名 ^类型 ^约束 ^说明 | |delegate |UCSEventDelegate |必选 |为事件回调代理（提供互联网音视频能力回调等实例对象）， \\ 详细参见UCSEvent.h | ====3.3 获取SDK版本号==== 原型：- (NSString*) getUCSSDKVersion; 功能：获取SDK版本号返回：SDK版本信息字符串备注：用于知道当前SDK版本信息，便于功能细节追溯参数：无 ====3.4 设置Ipv6==== 原型：- (void)setIpv6:(BOOL)isIpv6; 功能：设置当前网络是否是IPV6 返回：无备注：默认IPV4，建议在初始化完成后设置，也可在拨打电话之前设置。参数： ^参数名 ^类型 ^约束 ^说明 | |isIpv6 |BOOL |必选 |NO:不是IPv6 YES:是IPv6 | =====4、音视频引擎初始化配置代理接口===== ====4.1 引擎初始化成功代理==== 原型：- (void)onInitEngineSuccessful:(NSInteger)result; 功能：引擎初始化成功回调返回：无备注：建议登陆接口在引擎初始化成功后调用。参数： ^参数名 ^类型 ^约束 ^说明 | |result |NSInteger |必选 |0表示成功 | =====5、互联网音频通话能力接口 ===== ====5.1 发起呼叫==== 原型：- (void)dial:(NSInteger)callType andCalled:(NSString *)calledNumber andUserdata:(NSString *)callerData; 功能：发起免费通话和视频通话返回：无备注： * 语音免费呼叫：SDK与SDK之间语音通话场景； * 视频呼叫：SDK与SDK之间视频通话场景；参数： ^参数名 ^类型 ^约束 ^说明 | |callType |NSInteger |必选 |拨打电话方式：0 语音免费通话；2 视频通话； | |calledNumber |NSString |必选 |被叫userid账号 | |callerData |NSString |必选 |开发者透传数据字段，方便开发者透传自定义应用信息，该字段信息会通过云平台回调函数透传返回给开发者服务器 | ====5.2 释放通话==== 原型：- (void) hangUp: (NSString*)callid; 功能：挂断通话返回：无备注：主叫方：外呼过程中或通话中，调用这个接口结束一路呼叫；被叫方：来电过程中或通话中，调用这个接口结束一路通话；参数： ^参数名 ^类型 ^约束 ^说明 | |callid |NSString |无 |释放的会话id (目前版本可以为空)，该参数可由<接收来电>、<呼叫振铃>事件回调中得到 | ====5.3 接听来电==== 原型：- (void) answer: (NSString*)callid； 功能：接听来电电话返回：无备注：用于被叫来电时，用户触发接听电话场景，被叫收到onIncomingCall事件后，可调用answer接口接听或调用reject接口拒绝接听。参数： ^参数名 ^类型 ^约束 ^说明 | |callid |NSString |无 |来电通话id (目前版本可以为空) | ====5.4 拒绝来电==== 原型：- (void) reject: (NSString*)callid； 功能：拒接来电电话返回：无备注：用于被叫来电时，用户触发拒接电话场景，被叫收到onIncomingCall事件后，可调用answer接口接听或调用reject接口拒绝接听。参数： ^参数名 ^类型 ^约束 ^说明 | |callid |NSString |无 |来电通话id (目前版本可以为空) | ====5.5 发送DTMF==== 原型：- (BOOL)sendDTMF: (char )dtmf; 功能：发送DTMF信息返回：YES：成功；NO：失败备注：用于通话过程中发送DTMF场景，取值为0-9、*、#。参数： ^参数名 ^类型 ^约束 ^说明 | |dtmf |NSString |必选 |DTMF值 | ====5.6 设置扬声器状态==== 原型：- (void) setSpeakerphone:(BOOL)enable; 功能：设置扬声器状态，开启或关闭返回：无备注：用于通话过程中开启或关闭免提场景。参数： ^参数名 ^类型 ^约束 ^说明 | |enable |BOOL |必选 |打开：YES，关闭：NO | ====5.7 获取扬声器状态==== 原型：- (BOOL) isSpeakerphoneOn; 功能：获取当前扬声器是否开启状态返回：YSE：扬声器开启； NO：扬声器关闭备注：用于通话过程中判断扬声器是否开启场景。参数：无 ====5.8 设置静音状态==== 原型：- (void)setMicMute:(BOOL)on; 功能：设置静音状态，开启或关闭返回：无备注：用于通话过程中开启或关闭静音场景(开启后，自己能听到对方的声音，对方听不到自己的声音)。参数： ^参数名 ^类型 ^约束 ^说明 | |on |BOOL |必选 |打开：YES，关闭：NO | ====5.9 获取静音状态==== 原型：- (BOOL)isMicMute; 功能：获取当前静音是否开启状态返回：YES：静音开启； NO：静音关闭备注：用于通话过程中判断静音是否开启场景。参数：无 ====5.10 Push续活通知==== 原型：- (void) callIncomingPushRsp:(NSString*)callid withVps:(NSInteger)vpsid withReason:(UCSReason*)reason; 功能：iOS离线来电续活返回：无备注：当云平台接收要来电时，被叫方如不在线，则云平台会给开发者应用服务器回调<离线来电Push续活通知>，开发者应用服务器可以通过APNS苹果推送机制，将来电信息推送到应用客户端，并在应用客户端激活SDK时，使用该接口通知云平台SDK已激活，正在等待云平台下发来电呼叫。应用可以根据当前网络环境或业务逻辑判断是否接听来电，结果可以通过reason字段发给云平台，云平台根据reason判断是否继续下发来电或释放会话。参数： ^参数名 ^类型 ^约束 ^说明 | |callid |NSString |无 |当前来电会话id (目前版本可以为空) | |vpsid |NSInteger |必选 |云平台会话控制服务器标识id | |reason |UCSReason |必选 |原因UCSReason { \\ NSInteger reason；/*错误码*/ \\ NSString *msg；/*描述*/ \\ } \\ 详细请参见[[video_sdk:iosv3returncode|IOS 返回码]] | =====6、互联网音频通话能力事件代理接口====== ====6.1 呼叫失败事件代理==== 原型：- (void)onDialFailed:(NSString*)callid withReason:( UCSReason*) reason; 功能：音视频通话呼叫失败事件代理返回：无备注：用于音视频通话，主叫侧接收到云平台下发的呼叫失败应答场景。外呼时，如呼叫失败，就返回该事件。外呼失败的原因有很多，可以根据reason来判断。参数： ^参数名 ^类型 ^约束 ^说明 | |callid |NSString |无 |当前通话id (目前版本可以为空) | |reason |UCSReason |必选 |呼叫失败的原因详细请参见[[video_sdk:iosv3returncode|IOS 返回码]] | ====6.2 呼叫释放事件代理===== 原型：- (void) onHangUp:(NSString*)callid withReason:( UCSReason*) reason; 功能：释放通话事件回调代理返回：无备注：用于音视频通话，通话过程中主动释放通话场景。通话过程中，呼叫释放，就返回该事件。外呼过程中，呼叫释放，只调用onDialFailed事件代理。参数： ^参数名 ^类型 ^约束 ^说明 | |callid |NSString |无 |当前通话id (目前版本可以为空) | |reason |UCSReason |必选 |呼叫失败的原因详细请参见[[video_sdk:iosv3returncode|IOS 返回码]] | ====6.3 振铃事件代理===== 原型：- (void) onAlerting:(NSString*)callid; 功能：音视频通话被叫应答回铃事件代理返回：无备注：用于音视频通话，主叫侧接收到云平台下发的呼叫回铃应答场景。外呼时，被叫如有回应，就返回该事件。当收到该事件时，对方会响起振铃音，本地会响起回铃音。参数： ^参数名 ^类型 ^约束 ^说明 | |callid |NSString |无 |当前通话id (目前版本可以为空)| ====6.4 接听事件代理==== 原型：- (void) onAnswer:(NSString*)callid; 功能：音视频通话被叫应答接听事件代理返回：无备注：用于音视频通话，主叫侧接收到云平台下发的呼叫接听应答场景。外呼时，被叫如有回应接听，就返回该事件。当收到该事件时，表明对方已经应答接听，进入通话状态，应用需要提醒用户已经进入通话状态。参数： ^参数名 ^类型 ^约束 ^说明 | |callid |NSString |无 |当前通话id (目前版本可以为空)| ====6.5 来电事件代理==== 原型：- (void)onIncomingCall:(NSString*)callid withcalltype:(UCSCallTypeEnum) callType withcallerinfo:(NSDictionary *)callinfo; 功能：互联网音视频来电事件代理返回：无备注：用于互联网音视频通话，被叫侧接收到云平台下发呼叫的场景。应用接收到该事件后，需要提醒用户来电或者根据自己业务逻辑拒绝来电。参数： ^参数名 ^类型 ^约束 ^说明 | |callid |NSString |无 |当前通话id (目前版本可以为空) | |callType |NSString |必选 |通话类型: 0 语音免费电话；2 视频电话； | |callinfo |NSDictionary |必选 |来电会话信息(主被叫号码、会话id等) 待补充。。。 | ====6.6 DTMF事件代理==== 原型：- (void)onDTMF:(NSString *)value; 功能：DTMF事件回调代理返回：无备注：通话过程中，接收对方DTMF，应用根据DTMF信息进行业务逻辑处理，一般适用于门禁系统，智能解锁场景。参数： ^参数名 ^类型 ^约束 ^说明 | |value |NSString|必选 |DTMF值[[https://tools.ietf.org/html/rfc2833|rfc 2833]]协议标准 | ====6.7 OTT通话网络状态回调==== 原型：- (void)onNetWorkState:(UCSNetworkState)networkState; 功能：OTT网络状态回调代理返回：无备注：通话过程中，应用根据OTT网络状态回调进行界面显示。参数： ^参数名 ^类型 ^约束 ^说明 | |networkState |UCSNetworkState |必选 |UCSNetworkState:枚举网络状态为优秀、一般、良好、很差 | =====7、互联网视频通话能力接口===== ====7.1 设置视频显示窗口==== 原型：-(UIView *)allocCameraViewWithFrame:(CGRect)frame; 功能：实例化视频的显示窗口返回：UIView 视图窗口备注：用于实例化视频图像显示窗口。参数： ^参数名 ^类型 ^约束 ^说明 | |frame |CGRect |必选 |设置显示本地视频视图控件的大小 | ====7.2 设置视频显示参数==== 原型：-(BOOL)initCameraConfig:(UIView*)localVideoView withRemoteVideoView:(UIView*)remoteView; 功能：设置视频的显示参数返回：YES成功；NO失败备注：用于设置视频图像显示大小。参数： ^参数名 ^类型 ^约束 ^说明 | |localVideoView |UIView |必选 |设置显示本地视频视图控件 | |remoteView |UIView |必选 |设置显示对方视频视图控件 | ====7.3 获取摄像头个数==== 原型：- (int) getCameraNum; 功能：获取到当前手机的摄像头个数返回：摄像头个数备注：无参数：无 ====7.4 前后摄像头切换==== 原型：- (BOOL) switchCameraDevice:(int)CameraIndex; 功能：后置摄像头和前置摄像头的切换返回：YES成功；NO失败备注：前置摄像头与后置摄像头的切换参数： ^参数名 ^类型 ^约束 ^说明 | |CameraIndex |int |必选 |后置摄像头:0 前置摄像头:1 | ====7.5 切换视频模式===== 原型：- (BOOL) switchVideoMode:(UCSCameraType)type; 功能：切换视频模式返回：YES成功；NO失败备注：三种视频模式：本地模式、远程模式、正常模式。 * 远程模式：处于视频流接收状态。可以看到对方的视频，对方不能看本端的视频。 * 本地模式：处于视频流发送状态，不可以看到对方的视频，对方能看本端的视频。 * 正常模式：处于视频流发送以及接收状态，双方视频正常状态。参数： ^参数名 ^类型 ^约束 ^说明 | |type |UCSCameraType |必选 |UCSCameraType: 枚举远程模式、本地模式、正常模式 | ====7.6 自定义视频编解码参数==== 原型：-(void)setVideoAttr:(UCSVideoEncAttr*)ucsVideoEncAttr andVideoDecAttr:(UCSVideoDecAttr*)ucsVideoDecAttr; 功能：设置视频编码和解码参数返回：无备注：通过UCSVideoEncAttr设置视频编码分辨率、开始码率、帧率参数, 通过UCSVideoDecAttr设置视频解码分辨率参数（在设置视频显示参数前调用）参数： ^参数名 ^类型 ^约束 ^说明 | |ucsVideoEncAttr |UCSVideoEncAttr |必选 |参考ucsVideoEncAttr参数实体 | |ucsVideoDecAttr |UCSVideoDecAttr |必选 |参考ucsVideoDecAttr参数实体 | ====7.7 开启/关闭视频来电预览==== 原型：- (BOOL)setCameraPreViewStatu:(BOOL)isPreView; 功能：来电时是否支持预览返回：YES 成功 NO失败备注：视频来电时，未接听，是否支持对方预览摄像头显示图像，在登录前设置参数： ^参数名 ^类型 ^约束 ^说明 | |isPreView |BOOL |必选 |支持预览：YES 不支持预览：NO | ====7.8 获取来电时是否支持预览==== 原型：- (BOOL)isCameraPreviewStatu; 功能：获取来电时是否支持预览接口返回：YES 成功 NO失败备注：无参数：无 ====7.9 旋转视频==== 原型：- (BOOL) setRotationVideo:( unsigned int ) sendRotation withReciviedRotation:( unsigned int )reciviedRotation; 功能：设置视频显示的角度返回：YES成功；NO失败备注：旋转对端视频图像的显示角度参数值为4个方向 0 90 180 270 参数： ^参数名 ^类型 ^约束 ^说明 | |sendRotation |unsigned int |必选 |本端视频图像的角度 | |reciviedRotation |unsigned int |必选 |对端视频图像的角度 | ====7.10 视频截图==== 原型：- (void)cameraCapture:(int)islocal withFileName:(NSString*)filename withSavePath:(NSString*)savePath; 功能：截取摄像头显示的视频图像返回：无备注：截取本地的摄像头显示图像或者对方的显示图像，然后保存到本地路径地址。参数： ^参数名 ^类型 ^约束 ^说明 | |islocal |int |必选 |远端截图：0 本地截图：1 | |filename |NSString |必选 |截取的图片名称 | |savePath |NSString |必选 |存放的本地路径 | ===== 8、互联网视频通话能力代理接口 ===== ====8.1 视频截图回调通知==== 原型：- (void)onCameraCapture:(NSString*)cameraCapFilePath; 功能：视频截图回调返回：无备注：视频截图回调函数参数： ^参数名 ^类型 ^约束 ^说明 | |cameraCapFilePath |NSString |必选 |存放的本地路径 | ====8.2 对端视频模式回调通知==== 原型：- (void)onRemoteCameraMode:(UCSCameraType)type; 功能：对方模式切换的回调返回：无备注：当对端视频模式切换的时候，通过该回调，可以知道对方所处的视频模式状态。本地视频模式：对方处于视频流发送状态，本端视频可以看到对方的视频，对方看不到本端的视频。远程视频模式：对方处于视频流接收状态，本端视频不可以看到对方的视频，对方能看本端的视频。正常视频模式：对方处于视频流发送以及接收状态，双方视频正常状态。（注：当本地视频模式为本地视频模式，或者对方视频模式为远程视频模式，此时的网络状态是不准确的。）参数： ^参数名 ^类型 ^约束 ^说明 | |type |UCSCameraType |必选 |对端视频模式枚举值,具体参考UCSCameraeType定义。 | ===== 9、注意事项 ===== ====9.1 摄像头操作接口==== 关于摄像头的操作接口，如前后摄像头切换、摄像头旋转角度等操作，需要在通话建立后，才可以操作。通话结束后的复位操作需要开发者自己完成。 ====9.2 静音、扬声器、闪光灯等设备操作接口==== 静音、扬声器、闪光灯等设备操作接口，需要在主叫收到onAlerting回调时或者被叫收到onIncomming回调时进行操作。通话结束后的复位操作需要开发者自己完成。 ====9.3 视频来电预览操作接口==== 视频来电预览接口，在进行通话业务前进行配置。配置一次即可，不需要每通电话都配置。