主要功能

频道管理

方法 描述
sharedEngineWithAppId 创建并初始化 RtcEngine。
destory 销毁 RtcEngine 对象。
joinChannelByToken 加入频道。
leaveChannel 离开频道。

sharedEngineWithAppId

创建并初始化 RtcEngine。

 +(instancetype _Nonnull)sharedEngineWithAppId:(NSString * _Nonnull)appId delegate:(id<TangRTCEngineDelegate> _Nullable)delegate;

TangRTCEngineKit 类的所有接口函数,如无特殊说明,都是异步调用,对接口的调用建议在同一个线程进行。

注意:

请确保在调用其他 API 前先调用该方法创建并初始化 TangRTCEngineKit。 SDK 只支持每个 app 创建一个 TangRTCEngineKit 实例。

参数 描述
appId 为 app 开发者签发的 App ID。 使用同一个 App ID 的 app 才能进入同一个频道进行拉流。一个 App ID 只能用于创建一个 TangRTCEngineManager。如需更换 App ID,必须先调用 destoryTangRTCEngine 销毁当前 TangRTCEngineManager 再重新创建。
delegate TangRTCEngineKit 的事件句柄,详见 TangRTCEngineDelegate。
返回值 描述
TangRTCEngineKit 对象 方法调用成功,返回一个 TangRTCEngineKit 对象。
errCode 方法调用失败,返回错误码。

destroy

销毁 TangRTCEngineKit 对象。

   +(void)destroy;

该方法释放 TangRTC SDK 使用的所有资源。有些 app 只在用户需要时才进行实时音视频通信,不需要时则将资源释放出来用于其他操作, 该方法适用于此类情况。

调用该方法后,你将无法再使用 SDK 的其它方法和回调。如需再次使用实时音视频通信功能,你必须依次重新调用 sharedEngineWithAppId 方法创建一个新的 TangRTCEngineKit 对象。

注意:如需在销毁后再次创建 TangRTCEngineKit 对象,需要等待 destroy 方法执行结束后再创建实例。

joinChannelByToken

加入频道

 -(int)joinChannelByToken:(NSString * _Nullable)token
            channelId:(NSString * _Nonnull)channelId
                      uid:(NSUInteger)uid
             mediaOptions:(ChannelMediaOptions * _Nonnull)mediaOptions
              joinSuccess:(void(^ _Nullable)(NSString * _Nonnull channel, NSUInteger uid, NSInteger elapsed))joinSuccessBlock;

该方法让用户加入通话频道,在同一个频道内的用户可以互相通话,多个用户加入同一个频道,可以群聊。 使用不同 App ID 的 app 不能互通。

成功调用该方法加入频道后会触发以下回调:

本地会触发 didJoinChannel 和 connectionChangedToState 回调。

在网络状况不理想的情况下,客户端可能会与全时服务器失去连接;SDK 会自动尝试重连,重连成功后,本地会触发 didRejoinChannel 回调。

该方法有一个 options 参数,用于配置用户加入频道时是否自动订阅频道内所有远端音视频流。默认情况下,用户订阅频道内所有其他用户的音频流和视频流,因此会产生用量并影响计费。如果想取消订阅,可以通过设置 options 参数或相应的 mute 方法实现。 注意:

该方法允许用户一次加入仅一个频道。

参数 描述
token 在服务端生成的用于鉴权的动态密钥。(预留)
channelId 频道名。该参数标识用户进行实时音视频互动的频道。
uid 用户ID。(预留)
options 频道媒体设置选项。详见 ChannelMediaOptions。(预留)
joinSuccessBlock 成功加入频道回调。joinSuccessBlock 优先级高于 didJoinChannel ,两个同时存在时,didJoinChannel 会被忽略。需要有 didJoinChannel 回调时,请将 joinSuccessBlock 设置为 nil。

 

返回值 描述
0 方法调用成功。
-1 传入的参数无效。例如,使用了不合法的 Token,uid 参数未设置为整型,ChannelMediaOptions 结构体成员值不合法。你需要填入有效的参数,重新加入频道。
-2 RtcEngine 对象初始化失败。你需要重新初始化 RtcEngine 对象。
-3 RtcEngine 对象尚未初始化。你需要在调用该方法前成功初始化 RtcEngine 对象。
-4 加入频道被拒绝。可能的原因是用户已经在频道中。我们推荐通过 onConnectionStateChanged 回调判断用户是否在频道中。除收到 CONNECTION_STATE_DISCONNECTED(1) 状态外,不要再次调用该方法加入频道。
-5 频道名无效。你需要在 channelId 中填入有效的频道名,重新加入频道。

leaveChannel

离开频道

  -(int)leaveChannel:(LeaveChannelOptions * _Nonnull)options
       leaveChannelBlock:(void (^ _Nullable)(ChannelStats * _Nonnull))leaveChannelBlock;

该方法会把会话相关的所有资源释放掉。

该方法是异步操作,调用返回时并没有真正退出频道。

成功加入频道后,必须调用本方法结束通话,否则无法开始下一次通话。

成功调用该方法、并且离开频道后会触发以下回调:

本地:didLeaveChannelWithStats 回调。

注意:如果你调用了本方法后立即调用 destory 方法,SDK 将无法触发 didLeaveChannelWithStats 回调。

参数 描述
options 离开频道的选项,详见 LeaveChannelOptions。(预留)
leaveChannelBlock 成功离开频道的回调,提供通话相关的统计信息,详见 ChannelStats 。(预留)

 

返回值 描述
0 方法调用成功。
-1 一般性的错误(未明确归类)
-2 TangRTCEngineKit 对象尚未初始化。

频道事件

方法 描述
didJoinChannel 成功加入频道回调。
didRejoinChannel 成功重新加入频道回调。
didJoinError 加入频道失败回调。
didLeaveChannelWithStats 离开频道回调。
connectionChangedToState 连接状态已改变回调。
notifiedFirstFrame 视频数据首帧回调。

didJoinChannel

成功加入频道回调。

 -(void)rtcEngine:(TangRtcEngineKit * _Nonnull)engine
    didJoinChannel:(NSString * _Nonnull)channel withUid:(NSUInteger)uid elapsed:(NSInteger) elapsed;

该回调方法表示该客户端成功加入了指定的频道。

参数 描述
engine TangRtcEngineKit 对象。
channel 频道名。
uid 加入频道的用户 ID。(预留)
elapsed 从本地调用 joinChannelByToken 开始到发生此事件过去的时间(毫秒)。(预留)

didRejoinChannel

成功重新加入频道回调。

 -(void)rtcEngine:(TangRtcEngineKit * _Nonnull)engine
        didRejoinChannel:(NSString * _Nonnull)channel withUid:(NSUInteger)uid elapsed:(NSInteger) elapsed;

有时候由于网络原因,客户端可能会和服务器失去连接,SDK 会进行自动重连,自动重连成功后触发此回调方法。

参数 描述
engine TangRtcEngineKit 对象。
channel 频道名。
uid 加入频道的用户 ID。(预留)
elapsed 从本地调用 joinChannelByToken 开始到发生此事件过去的时间(毫秒)。(预留)

didJoinError

加入频道失败回调。

    -(void)rtcEngine:(TangRTCEngineKit* _Nonnull)engine didJoinError:(NSInteger)errorCode {}

该回调方法表示该客户端加入指定的频道失败了。

参数 描述
engine TangRtcEngineKit 对象。
err 失败类型 ERROR_CODE_TYPE。
REMOTE_CANDIDATE_NOT_READY = -1,//!< 远端candidate没有准备好
PEER_CONNECTION_NOT_READY = -2, //!< PeerConnection初始化失败
RECONNECT_SAME_PEER = -3, //!< 重复连接同一个peer
PULLURL_NOT_READY = -4, //!< pull url没有准备好,应用端传进来的
REMOTE_SDP_NOT_READY = -5, //!< 远端sdp没有准备好
LOCAL_SDP_NOT_READY = -6, //!< 本地sdp没有准备好
ICE_CONNECTION_FAILED = -7, //!< ICE 连接失败
msg 失败消息。

didLeaveChannelWithStats

离开频道回调。

 -(void)rtcEngine:(TangRTCEngineKit * _Nonnull)engine
    didLeaveChannelWithStats:(TangRTCChannelStats * _Nonnull)stats;

App 调用 leaveChannel 方法时,SDK 提示 app 离开频道成功。在该回调方法中,app 可以得到此次通话的总通话时长、SDK 收发数据的流量等信息。

参数 描述
engine TangRtcEngineKit 对象。
stats 通话的统计数据: TangRTCChannelStats。(预留,暂未实现)

connectionChangedToState

网络连接状态已改变回调。

 -(void)rtcEngine:(TangRTCEngineKit * _Nonnull)engine
                connectionChangedToState:(ConnectionState)state
                reason:(ConnectionChangedReason)reason;

该回调在网络连接状态发生改变的时候触发,并告知用户当前的网络连接状态和引起网络状态改变的原因。

参数 描述
engine TangRtcEngineKit 对象。
state 当前网络连接状态。(ConnectionState )
ConnectionStateDisconnected (1):网络连接断开。
ConnectionStateConnecting (2):建立网络连接中。
ConnectionStateConnected (3):网络已连接。
ConnectionStateReconnecting (4):重新建立网络连接中 。
ConnectionStateFailed (5):网络连接失败 。
reason 引起网络状态改变的原因。(ConnectionChangedReason )
ConnectionChangedReasonConnecting (0):建立网络连接中 。
ConnectionChangedReasonJoinSuccess (1):成功加入频道 。
ConnectionChangedReasonInterrupted (2):网络连接中断 。
ConnectionChangedReasonJoinFailed (3):加入频道失败 。
ConnectionChangedReasonLeaveChannel (4):离开频道 。
ConnectionChangedReasonInvalidChannelName (5):不是有效的频道名。请更换有效的频道名重新加入频道。
ConnectionChangedReasonRejoinSuccess (6):重新加入频道成功。
ConnectionChangedReasonLost (7):SDK 和服务器失去连接 。

notifiedFirstFrame

视频首帧通知

 -(void)rtcEngine:(TangRTCEngineKit* _Nonnull)engine notifiedFirstFrame:(NSString* _Nonnull)channel;

收到远端视频数据的时候,首帧通过回调的方式通知给上层

参数 描述
engine TangRtcEngineKit 对象。
channel 频道名。

音频管理

方法 描述
muteAllRemoteAudioStreams 取消或恢复订阅所有远端用户的音频流。

muteAllRemoteAudioStreams

取消或恢复订阅所有远端用户的音频流。

 -(int)muteAllRemoteAudioStreams:(BOOL)mute;

成功调用该方法后,本地用户会取消或恢复订阅所有远端用户的音频流,包括在调用该方法后加入频道的用户的音频流。

注意:

该方法需要在加入频道后调用。 如果需要在加入频道前设置默认不订阅远端用户音频流,可以在调用 joinChannelByToken 加入频道时设置 autoSubscribeAudio 为 NO。

参数 描述
muted 是否取消订阅所有远端用户的音频流:YES: 取消订阅所有远端用户的音频流。NO:(默认)订阅所有远端用户的音频流。
返回值 描述
0 方法调用成功。
<0 方法调用失败

视频管理

方法 描述
setupRemoteVideo 初始化远端用户视图。
muteAllRemoteVideoStreams 取消或恢复订阅所有远端用户的视频流。

setupRemoteVideo

初始化远端用户视图。

 -(int)setupRemoteVideo:(VideoCanvas * _Nonnull)remote;

该方法绑定远端用户和显示视图,并设置远端用户视图在本地显示时的渲染模式和镜像模式,只影响本地用户看到的视频画面。

如需解除某个远端用户的绑定视图,可以调用该方法并将 view 设置为空。

离开频道后,SDK 会清除远端用户视图的绑定关系。

参数 描述
remote 远端视频显示属性。详见 VideoCanvas。
#pragma mark -- TangRTCVideoCanvas
@interface TangRTCVideoCanvas : NSObject

@property(strong, nonatomic) VIEW_CLASS* _Nullable view;//窗口的view

@property(assign, nonatomic) TangRTCVideoRenderMode renderMode;//渲染模式(预留)

@property(copy, nonatomic) NSString* _Nullable channelId;//频道ID

@property(assign, nonatomic) NSUInteger uid;//用户ID(预留)

@property(assign, nonatomic) TangRTCVideoMirrorMode mirrorMode;//镜像模式(预留)

@end
返回值 描述
0 方法调用成功。
<0 方法调用失败

muteAllRemoteVideoStreams

取消或恢复订阅所有远端用户的视频流。

 -(int)muteAllRemoteVideoStreams:(BOOL)mute;

成功调用该方法后,本地用户会取消或恢复订阅所有远端用户的视频流,包括在调用该方法后加入频道的用户的视频流。

注意:

该方法需要在加入频道后调用。 如果需要在加入频道前设置默认不订阅远端用户视频流,可以在调用 joinChannelByToken 加入频道时设置 autoSubscribeVideo 为 NO。

参数 描述
muted 是否取消订阅所有远端用户的视频流。YES: 取消订阅所有用户的视频流。NO:(默认)订阅所有用户的视频流。
返回值 描述
0 方法调用成功。
<0 方法调用失败