NERtc Windows SDK  V4.6.20
Public 成员函数 | 所有成员列表
nertc::IRtcEngine类 参考abstract

#include <nertc_engine.h>

类 nertc::IRtcEngine 继承关系图:
nertc::IRtcEngineEx

Public 成员函数

virtual int initialize (const NERtcEngineContext &context)=0
 
virtual void release (bool sync=true)=0
 
virtual int setClientRole (NERtcClientRole role)=0
 
virtual int setChannelProfile (NERtcChannelProfileType profile)=0
 
virtual int joinChannel (const char *token, const char *channel_name, uid_t uid)=0
 
virtual int switchChannel (const char *token, const char *channel_name)=0
 
virtual int leaveChannel ()=0
 
virtual int queryInterface (NERtcInterfaceIdType iid, void **inter)=0
 
virtual int enableLocalAudio (bool enabled)=0
 
virtual int setupLocalVideoCanvas (NERtcVideoCanvas *canvas)=0
 
virtual int setupRemoteVideoCanvas (uid_t uid, NERtcVideoCanvas *canvas)=0
 
virtual int enableLocalVideo (bool enabled)=0
 
virtual int enableLocalVideo (NERtcVideoStreamType type, bool enabled)=0
 
virtual int subscribeRemoteVideoStream (uid_t uid, NERtcRemoteVideoStreamType type, bool subscribe)=0
 

详细描述

RtcEngine 类提供了供 App 调用的主要接口方法。
IRtcEngine 是 NERTC SDK 的基础接口类。创建一个 IRtcEngine 对象并调用这个对象的方法可以激活 NERTC SDK 的通信功能。

成员函数说明

◆ enableLocalAudio()

virtual int nertc::IRtcEngine::enableLocalAudio ( bool  enabled)
pure virtual

开启/关闭本地音频采集和发送。
该方法可以重新开启本地语音功能,重新开始本地音频采集及处理。
该方法不影响接收或播放远端音频流。
成功调用该方法后,房间内其他用户触发 onUserAudioStart 或 onUserAudioStop 回调。

注解
该方法与 muteLocalAudioStream 的区别在于:
该方法设置内部引擎为启用状态,在 leaveChannel 后仍然有效。
自从
V4.5.0
参数
[in]enabled
  • true: 重新开启本地语音功能,即开启本地语音采集或处理(默认)。
  • false: 关闭本地语音功能,即停止本地语音采集或处理。
返回
  • 0: 方法调用成功;
  • 其他: 方法调用失败。

◆ enableLocalVideo() [1/2]

virtual int nertc::IRtcEngine::enableLocalVideo ( bool  enabled)
pure virtual

开启或关闭本地视频采集和渲染。
该方法启用本地视频采集功能。

注解
  • 该方法仅适用于视频主流,若您希望开启辅流通道的视频采集,请调用 enableLocalVideo 方法。
  • 该方法在加入房间前和加入房间后均可调用。
  • 该方法设置内部引擎为启用状态,在 leaveChannel 后仍然有效。
  • 成功启用或禁用本地视频采集和渲染后,远端会触发 onUserVideoStartonUserVideoStop 回调。
参数
[in]enabled是否启用本地视频采集和渲染:
  • true: 开启本地视频采集和渲染 (默认);
  • false: 关闭使用本地摄像头设备。关闭后,远端用户会接收不到本地用户的视频流;但本地用户依然可以接收远端用户的视频流。设置为 false 时,该方法不需要本地有摄像头。
返回
  • 0: 方法调用成功;
  • 其他: 方法调用失败。

◆ enableLocalVideo() [2/2]

virtual int nertc::IRtcEngine::enableLocalVideo ( NERtcVideoStreamType  type,
bool  enabled 
)
pure virtual

开启或关闭本地视频的采集与发送。
通过主流或辅流视频通道进行本地视频流的采集与发送。

自从
V4.6.20
调用时机
请在初始化后调用该方法,且该方法在加入房间前后均可调用。
注解
  • 纯音频 SDK 禁用该接口,如需使用请前往云信官网下载并替换成视频 SDK。
  • 该方法设置内部引擎为开启或关闭状态, 在 leaveChannel 后仍然有效。
参数说明
参数名称 类型 描述
type NERtcVideoStreamType 视频通道类型:
  • kNERTCVideoStreamMain:主流。
  • kNERTCVideoStreamSub:辅流。
enabled bool 是否开启本地视频采集与发送:
  • true:开启本地视频采集。
  • false:关闭本地视频采集,此时不需要本地有摄像头。关闭后,远端用户无法接收到本地用户的视频流;但本地用户仍然可以接收到远端用户的视频流。
示例代码
//打开视频主流
bool enable = true;
rtc_engine_->enableLocalVideo(type, enable);
//关闭视频主流
bool enable = false;
rtc_engine_->enableLocalVideo(type, enable);
//打开视频辅流
bool enable = true;
rtc_engine_->enableLocalVideo(type, enable);
//关闭视频辅流
bool enable = false;
rtc_engine_->enableLocalVideo(type, enable);
NERtcVideoStreamType
Definition: nertc_engine_defines.h:5102
@ kNERTCVideoStreamSub
Definition: nertc_engine_defines.h:5120
@ kNERTCVideoStreamMain
Definition: nertc_engine_defines.h:5111
相关回调
  • type 为 kNERTCVideoStreamMain(主流)时:
  • streamType 为 kNERtcVideoStreamTypeSub(辅流)时:
返回
  • 0(kNERtcNoError):方法调用成功。
  • 其他:方法调用失败。
    • 30001(kNERtcErrFatal):通用错误,一般表示引擎错误,尝试再次调用此接口即可。
    • 30005(kNERtcErrInvalidState):当前状态不支持的操作,比如已开启外部视频采集。
    • 30027(kNERtcErrDeviceOccupied): 所选设备已被占用。比如已通过主流通道开启了摄像头,无法再通过辅流通道开启摄像头。
    • 30300(kNERtcRuntimeErrVDMNoAuthorize):应用未获取到操作系统的摄像头权限。
    • 30403(kNERtcErrMediaOpenBannedByServer): 已被服务器禁用视频。

◆ initialize()

virtual int nertc::IRtcEngine::initialize ( const NERtcEngineContext context)
pure virtual

初始化 NERTC SDK 服务。
在调用 createNERtcEngine() 方法创建 IRtcEngine 对象后,必须先调用该方法进行初始化,才能使用其他方法。初始化成功后,默认处于音视频通话模式。

警告
  • 必须使用同一个 App Key 才能进行通话。
  • 一个 IRtcEngine 实例对象只能使用一个 App Key。如需更换 App Key,必须先调用 release 方法销毁当前实例,再调用本方法重新创建实例。
参数
[in]context传入的RTC engine context对象: NERtcEngineContext.
返回
  • 0: 方法调用成功;
  • 其他: 方法调用失败。

◆ joinChannel()

virtual int nertc::IRtcEngine::joinChannel ( const char *  token,
const char *  channel_name,
uid_t  uid 
)
pure virtual

加入音视频房间。
加入音视频房间时,如果指定房间尚未创建,云信服务器内部会自动创建一个同名房间。

  • SDK 加入房间后,同一个房间内的用户可以互相通话,多个用户加入同一个房间,可以群聊。使用不同 App Key 的 App 之间不能互通。
  • 成功调用该方加入房间后,本地会触发onJoinChannel回调,远端会触发onUserJoined回调。

用户成功加入房间后,默认订阅房间内所有其他用户的音频流,可能会因此产生用量并影响计费。如果想取消自动订阅,可以在通话前通过调用setParameters方法实现。

  • 直播场景中的观众角色可以通过 switchChannel 快速切换房间。
    注解
    房间内每个用户的用户 ID 必须是唯一的。
    参数
    [in]token安全认证签名(NERTC Token)。可设置为:
    • null。调试模式下可设置为 null。安全性不高,建议在产品正式上线前在云信控制台中将鉴权方式恢复为默认的安全模式。
    • 已获取的NERTC Token。安全模式下必须设置为获取到的 Token 。若未传入正确的 Token 将无法进入房间。推荐使用安全模式。
    [in]channel_name房间名称,设置相同房间名称的用户会进入同一个通话房间。字符串格式,长度为 1 ~ 63 字节。支持以下 89 个字符:a-z, A-Z, 0-9, space, !#$%&()+-:;≤.,>? @[]^_{|}~”
    [in]uid用户的唯一标识 id,房间内每个用户的 uid 必须是唯一的。
    uid 可选,默认为 0。如果不指定(即设为 0),SDK 会自动分配一个随机 uid,并在 onJoinChannel 回调方法中返回,App 层必须记住该返回值并维护,SDK 不对该返回值进行维护。
    返回
  • 0: 方法调用成功;
  • 其他: 方法调用失败。

◆ leaveChannel()

virtual int nertc::IRtcEngine::leaveChannel ( )
pure virtual

离开房间,即挂断或退出通话。
结束通话时,必须调用 leaveChannel 结束通话,否则无法开始下一次通话。
成功调用该方法离开房间后,本地会触发 onLeaveChannel 回调,远端会触发 onUserLeft 回调。

注解
  • 该方法是异步操作,调用返回时并没有真正退出频道。在真正退出房间后,SDK 会触发 onLeaveChannel 回调。
  • 如果在调用 leaveChannel 后立即调用 release,可能会无法正常离开房间。因此建议用户在收到 onLeaveChannel 回调之后再调用 release 释放会话相关所有资源。
返回
  • 0: 方法调用成功;
  • 其他: 方法调用失败。

◆ queryInterface()

virtual int nertc::IRtcEngine::queryInterface ( NERtcInterfaceIdType  iid,
void **  inter 
)
pure virtual

获取设备管理员对象的指针。

参数
[in]iid想要获取的接口的iid.
[in]inter指向 DeviceManager 对象的指针。
返回
  • 0: 方法调用成功;
  • 其他: 方法调用失败。

◆ release()

virtual void nertc::IRtcEngine::release ( bool  sync = true)
pure virtual

销毁 NERtc 实例,并释放资源。
该方法释放 NERTC SDK 使用的所有资源。有些 App 只在用户需要时才进行实时音视频通信,完成音视频通话后,则将资源释放出来用于其他操作,该方法适用于此类情况。

  • 该接口需要在调用 leaveChannel 方法并收到本端离开房间的回调后调用。或收到 onDisconnect 回调、重连失败时调用此方法销毁实例,并释放资源。
  • 调用该释放实例后,您将无法再使用 SDK 的其它方法和回调。如需再次使用实时音视频通话功能,您必须重新创建一个新的 NERtc 实例。
    注解
  • 该方法为同步调用,需要等待 NERtcEngine 实例资源释放后才能执行其他操作,建议在子线程中调用该方法,避免主线程阻塞。此外,请勿在 SDK 的回调中调用该方法,否则由于 SDK 要等待回调返回才能回收相关的对象资源,会造成死锁。SDK 会自动检测这种死锁并转为异步调用,但是检测本身会消耗额外的时间。
  • 如果需要重新使用 IRtcEngine,调用该方法后需要调用 destroyNERtcEngine 方法销毁引擎,等待执行结束后才能再次调用 createNERtcEngine
    参数
    [in]sync默认为 true 且只能设置为 true,表示同步调用,等待 IRtcEngine 对象资源释放后再返回。

◆ setChannelProfile()

virtual int nertc::IRtcEngine::setChannelProfile ( NERtcChannelProfileType  profile)
pure virtual

设置房间场景。
房间场景可设置为通话或直播场景,不同的场景中 QoS 策略不同。

注解
必须在加入通话前设置,开始通话后设置无效,结束通话后保留之前的设置。
参数
[in]profile设置房间场景。详细信息请参考 NERtcChannelProfileType。
返回
  • 0: 方法调用成功;
  • 其他: 方法调用失败。

◆ setClientRole()

virtual int nertc::IRtcEngine::setClientRole ( NERtcClientRole  role)
pure virtual

在直播场景中设置用户角色。
用户角色支持设置为主播或观众,主播和观众的权限不同。

  • 主播:可以开关摄像头等设备、可以发布流、可以操作互动直播推流相关接口、上下线对其他房间内用户可见。
  • 观众:不可以开关摄像头等设备、不可以发布流、不可以操作互动直播推流相关接口、上下线对其他房间内用户不可见。

如果你在加入频道后调用该方法切换角色,调用成功后会收到以下回调:

  • 主播切观众,本端触发 onClientRoleChanged 回调,远端触发 onUserLeft 回调。
  • 观众切主播,本端触发 onClientRoleChanged 回调,远端触发 onUserJoined 回调。
注解
  • 默认情况下用户以主播角色加入房间。
  • 在加入房间前,用户可以调用本接口切换本端角色为观众。在加入房间后,用户也可以通过本接口切换用户角色。
  • 用户切换为观众角色时,SDK 会自动关闭音视频设备。
自从
V4.5.0
参数
[in]role用户角色。 NERtcClientRole
返回
  • 0(kNERtcNoError): 方法调用成功。
  • < 0: 方法调用失败。
    • 30001(kNERtcErrFatal): Engine 未创建。
    • 30101(kNERtcErrChannelNotJoined): 尚未加入房间。
    • 30005(kNERtcErrInvalidState): 不支持切换角色(主播/观众)。

◆ setupLocalVideoCanvas()

virtual int nertc::IRtcEngine::setupLocalVideoCanvas ( NERtcVideoCanvas canvas)
pure virtual

设置本地视图。
该方法设置本地视频显示信息。只影响本地用户看到的视频画面,不影响远端。
App 通过调用此接口绑定本地视频流的显示视窗(view)。 在 App 开发中,通常在初始化后调用该方法进行本地视频设置,然后再加入房间。

注解
  • Mac 端若使用外部渲染,必须在 SDK 初始化时设置本地视图。
  • 该方法在加入频道前后都能调用。
  • 如果您希望在通话中更新本地用户视图的渲染或镜像模式,请使用 setLocalRenderMode 方法。
参数
[in]canvas视频画布信息。详细信息请参考 NERtcVideoCanvas
返回
  • 0: 方法调用成功;
  • 其他: 方法调用失败。

◆ setupRemoteVideoCanvas()

virtual int nertc::IRtcEngine::setupRemoteVideoCanvas ( uid_t  uid,
NERtcVideoCanvas canvas 
)
pure virtual

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

注解
  • 调用该接口时需要指定远端视频的 uid,一般可以在用户加入后设置好。
  • 如果 App 无法事先知道对方的用户 ID,可以在 APP 收到 onUserJoined 事件时设置。
  • 解除某个用户的绑定视图可以把 canvas 设置为空。
  • 退出房间后,SDK 会清除远程用户和视图的绑定关系。
  • 如果您希望在通话中更新本地用户视图的渲染或镜像模式,请使用 setRemoteRenderMode 方法。
参数
[in]uid远端用户 ID。
[in]canvas视频画布信息。详细信息请参考 NERtcVideoCanvas
返回
  • 0: 方法调用成功;
  • 其他: 方法调用失败。

◆ subscribeRemoteVideoStream()

virtual int nertc::IRtcEngine::subscribeRemoteVideoStream ( uid_t  uid,
NERtcRemoteVideoStreamType  type,
bool  subscribe 
)
pure virtual

订阅或取消订阅指定远端用户的视频流。

注解
  • 用户加入房间之后,默认不订阅远端用户的视频流,如果希望看到指定远端用户的视频,可以在监听到对方加入房间或发布视频流之后,通过此方法订阅该用户的视频流。
  • 该方法需要在加入房间后调用。
参数
[in]uid指定用户的用户 ID。
[in]type订阅的视频流类型。 NERtcRemoteVideoStreamType
[in]subscribe是否订阅远端用户的视频流。
  • true:订阅指定视频流。
  • false(默认):不订阅指定视频流。
返回
  • 0: 方法调用成功;
  • 其他: 方法调用失败。

◆ switchChannel()

virtual int nertc::IRtcEngine::switchChannel ( const char *  token,
const char *  channel_name 
)
pure virtual

快速切换音视频房间。
房间场景为直播场景时,房间中角色为观众的成员可以调用该方法从当前房间快速切换至另一个房间。
成功调用该方切换房间后,本端会先收到离开房间的回调 onLeaveChannel,再收到成功加入新房间的回调 onJoinChannel。远端用户会收到 onUserLeave 和 onUserJoined 的回调。

注解
  • 该方法仅适用于直播场景中,角色为观众的音视频房间成员。即已通过接口 setchannelprofile 设置房间场景为直播,通过 setClientRole 设置房间成员的角色为观众。
  • 房间成员成功切换房间后,默认订阅房间内所有其他成员的音频流,因此产生用量并影响计费。如果想取消订阅,可以通过调用相应的 subscribeRemoteAudio 方法传入 false 实现。
    参数
    [in]token安全认证签名(NERTC Token)。可设置为:
    • null。调试模式下可设置为 null。建议在产品正式上线前在云信控制台中将鉴权方式恢复为默认的安全模式。
    • 已获取的NERTC Token。安全模式下必须设置为获取到的 Token 。若未传入正确的 Token 将无法进入房间。推荐使用安全模式。
    [in]channel_name期望切换到的目标房间名称。
    返回

该类的文档由以下文件生成: