nertc::IRtcEngine类 参考

#include <nertc_engine.h>

类 nertc::IRtcEngine 继承关系图:

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	joinChannel (const char *token, const char *channel_name, uid_t uid, NERtcJoinChannelOptions channel_options)=0
virtual int	switchChannel (const char *token, const char *channel_name)=0
virtual int	switchChannel (const char *token, const char *channel_name, NERtcJoinChannelOptions channel_options)=0
virtual int	switchChannelEx (const char *token, const char *channel_name, NERtcJoinChannelOptionsEx channel_options_ex)=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
virtual int	subscribeRemoteVideoStream (uid_t uid, NERtcVideoStreamType stream_type, NERtcRemoteVideoStreamType subscribe_type, bool subscribe)=0

详细描述

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

成员函数说明

enableLocalAudio()

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

pure virtual

开启/关闭本地音频采集和发送。
通过本接口可以实现开启或关闭本地语音功能，进行本地音频采集及处理。

自从

V3.5.0

调用时机

请在引擎初始化之后调用此接口，且该方法在加入房间前后均可调用。

注解

• 加入房间后，语音功能默认为开启状态。
• 该方法设置内部引擎为启用状态，在 leaveChannel 后仍然有效。
• 该方法不影响接收或播放远端音频流，enableLocalAudio(false) 适用于只下行不上行音频流的场景。
• 该方法会操作音频硬件设备，建议避免频繁开关，否则可能导致设备异常。

参数说明

参数名称	类型	描述
enabled	boolean	是否启用本地音频的采集和发送： true：开启本地音频采集。 false：关闭本地音频采集。关闭后，远端用户会接收不到本地用户的音频流；但本地用户依然可以接收到远端用户的音频流。

示例代码

//打开音频采集
rtc_engine_->enableLocalAudio(true); 
//关闭音频采集
rtc_engine_->enableLocalAudio(false);

相关回调

• 开启音频采集后，远端会触发 onUserAudioStart 回调。
• 关闭音频采集后，远端会触发 onUserAudioStop 回调。

相关接口

muteLocalAudioStream：两者的差异在于，enableLocalAudio 用于开启本地语音采集及处理，而 muteLocalAudioStream 用于停止或继续发送本地音频流。

返回

• 0（kNERtcNoError）：方法调用成功。
• 其他：方法调用失败。
  • 30005（kNERtcErrInvalidState）：引擎尚未初始化，或者多房间场景下未在本房间操作。

enableLocalVideo() [1/2]

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

pure virtual

开启或关闭本地视频的采集与发送。
通过本接口可以实现开启或关闭本地视频，不影响接收远端视频。

自从

V3.5.0

调用时机

请在初始化后调用该方法，且该方法在加入房间前后均可调用。

注解

• 纯音频 SDK 禁用该接口，如需使用请前往云信官网下载并替换成视频 SDK。
• 该方法设置内部引擎为开启或关闭状态, 在 leaveChannel 后仍然有效。

参数说明

参数名称	类型	描述
enabled	bool	是否开启本地视频采集与发送： true：开启本地视频采集。 false：关闭本地视频采集，此时不需要本地有摄像头。关闭后，远端用户无法接收到本地用户的视频流；但本地用户仍然可以接收到远端用户的视频流。

示例代码

//打开视频
rtc_engine_->enableLocalVideo(true);
//关闭视频
rtc_engine_->enableLocalVideo(false);

相关回调

• 开启本地视频采集后，远端会收到 onUserVideoStart 回调。
• 关闭本地视频采集后，远端会收到 onUserVideoStop 回调。

相关接口

若您希望开启辅流通道的视频采集，请调用 enableLocalVideo 方法。

返回

• 0（kNERtcNoError）：方法调用成功。
• 其他：方法调用失败。
  • 30001（kNERtcErrFatal）：通用错误，一般表示引擎错误，尝试再次调用此接口即可。
  • 30005（kNERtcErrInvalidState）：当前状态不支持的操作，比如已开启外部视频采集。
  • 50000（kNERtcRuntimeErrVDMNoAuthorize）：应用未获取到操作系统的摄像头权限。

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：关闭本地视频采集，此时不需要本地有摄像头。关闭后，远端用户无法接收到本地用户的视频流；但本地用户仍然可以接收到远端用户的视频流。

示例代码

//打开视频主流
nertc::NERtcVideoStreamType type = nertc::NERtcVideoStreamType::kNERTCVideoStreamMain;
bool enable = true;
rtc_engine_->enableLocalVideo(type, enable);
//关闭视频主流
nertc::NERtcVideoStreamType type = nertc::NERtcVideoStreamType::kNERTCVideoStreamMain;
bool enable = false;
rtc_engine_->enableLocalVideo(type, enable);
//打开视频辅流
nertc::NERtcVideoStreamType type = nertc::NERtcVideoStreamType::kNERTCVideoStreamSub;
bool enable = true;
rtc_engine_->enableLocalVideo(type, enable);
//关闭视频辅流
nertc::NERtcVideoStreamType type = nertc::NERtcVideoStreamType::kNERTCVideoStreamSub;
bool enable = false;
rtc_engine_->enableLocalVideo(type, enable);

相关回调

• type 为 kNERTCVideoStreamMain（主流）时：
  • 开启本地视频采集后，远端会收到 onUserVideoStart 回调。
  • 关闭本地视频采集后，远端会收到 onUserVideoStop 回调。
• streamType 为 kNERtcVideoStreamTypeSub（辅流）时：
  • 开启本地视频采集后，远端会收到 onUserSubStreamVideoStart 回调。
  • 关闭本地视频采集后，远端会收到 onUserSubStreamVideoStop 回调。

返回

• 0（kNERtcNoError）：方法调用成功。
• 其他：方法调用失败。
  • 30001（kNERtcErrFatal）：通用错误，一般表示引擎错误，尝试再次调用此接口即可。
  • 30005（kNERtcErrInvalidState）：当前状态不支持的操作，比如已开启外部视频采集。
  • 30027（kNERtcErrDeviceOccupied）: 所选设备已被占用。比如已通过主流通道开启了摄像头，无法再通过辅流通道开启摄像头。
  • 50000（kNERtcRuntimeErrVDMNoAuthorize）：应用未获取到操作系统的摄像头权限。

initialize()

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

pure virtual

创建 NERtc 实例。
通过本接口可以实现创建 NERtc 实例并初始化 NERTC SDK 服务。

自从

V3.5.0

调用时机

请确保在调用 createNERtcEngine() 方法创建 IRtcEngine 对象后，再调用其他 API 前先调用该方法创建并初始化 NERtc 实例。

注解

• 使用同一个 App Key 的 App 才能进入同一个房间进行通话或直播。
• 一个 App Key 只能用于创建一个 NERtc 实例；若您需要更换 App Key，必须先调用 release 方法销毁当前实例，再调用本方法重新创建实例。
• 初始化成功后，默认处于音视频通话模式。

参数说明

参数名称	类型	描述
context	NERtcEngineContext	传入的 RTC engine context 对象。

示例代码

nertc::NERtcEngineContext rtc_engine_context;
memset(&rtc_engine_context, 0, sizeof(nertc::NERtcEngineContext));
rtc_engine_context.app_key = app_key.c_str();
rtc_engine_context_.log_dir_path = log_dir_path_.c_str();
rtc_engine_context_.log_level = rtc_parameter_.log_level;
rtc_engine_context_.log_file_max_size_KBytes = log_file_max_size_KBytes;
rtc_engine_context_.event_handler = this;
rtc_engine_->initialize(rtc_engine_context);

相关接口

若您不再使用 NERtc 实例，需要调用 release 方法进行销毁。

返回

• 0（kNERtcNoError）：方法调用成功。
• 其他：方法调用失败。
  • 30001（kNERtcErrFatal）：通用错误，比如日志路径无法访问。
  • 30003（kNERtcErrInvalidParam）：参数错误，比如 app_key 为空或 log_dir_path 为空。
  • 30005（kNERtcErrInvalidState)：状态错误，比如重复初始化。

joinChannel() [1/2]

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

pure virtual

加入音视频房间。
通过本接口可以实现加入音视频房间，加入房间后可以与房间内的其他用户进行音视频通话。

自从

V3.5.0

调用时机

请在初始化后调用该方法。

注解

• 加入房间后，同一个房间内的用户可以互相通话，多个用户加入同一个房间，可以群聊。使用不同 App Key 的 App 之间不能互通。
• 加入音视频房间时，如果指定房间尚未创建，云信 服务器内部会自动创建一个同名房间。
• 传参中 uid 可选，若不指定则默认为 0，SDK 会自动分配一个随机 uid，并在 onJoinChannel 回调方法中返回；App 层必须记住该返回值并维护，SDK 不对该返回值进行维护。
• 用户成功加入房间后，默认订阅房间内所有其他用户的音频流，可能会因此产生用量并影响计费；若您想取消自动订阅，可以在通话前通过调用 setParameters 方法实现。
• 网络测速过程中无法加入房间。
• 若使用了云代理功能，uid 不允许传 0，请用真实的 uid。

参数说明

参数名称	类型	描述
token	const char	安全认证签名（NERTC Token），可以设置为： null。调试模式下可设置为 null。安全性不高，建议在产品正式上线前在网易云信控制台中将鉴权方式恢复为默认的安全模式。 已获取的 NERTC Token。安全模式下必须设置为获取到的 Token。若未传入正确的 Token 将无法进入房间。推荐使用安全模式。
channelName	const char	房间名称，设置相同房间名称的用户会进入同一个通话房间。 字符串格式，长度为 1 ~ 64 字节。 支持以下 89 个字符：a-z, A-Z, 0-9, space, !#$%&()+-:;≤.,>? @[]^_{|}~”
uid	uid_t	用户的唯一标识 ID。

示例代码

rtc_engine_->joinChannel(token, "124514", 1);

相关接口

• 您可以调用 leaveChannel 方法离开房间。
• 直播场景中，观众角色可以通过 switchChannel 接口切换房间。

相关回调

• 成功调用该方法加入房间后，本地会触发 onJoinChannel 回调，远端会触发 onUserJoined 回调。
• 在弱网环境下，若客户端和服务器失去连接，SDK 会自动重连，并在自动重连成功后触发 onRejoinChannel 回调。

返回

• 0（kNERtcNoError）：方法调用成功。
• 其他：方法调用失败。
  • 30001（kNERtcErrFatal）：重复入会或获取房间信息失败。
  • 30005（kNERtcErrInvalidState)：状态错误，比如引擎尚未初始化或正在进行网络探测。

joinChannel() [2/2]

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

pure virtual

加入音视频房间。
通过本接口可以实现加入音视频房间，加入房间后可以与房间内的其他用户进行音视频通话。

自从

V3.5.0

调用时机

请在初始化后调用该方法。

注解

• 加入房间后，同一个房间内的用户可以互相通话，多个用户加入同一个房间，可以群聊。使用不同 App Key 的 App 之间不能互通。
• 加入音视频房间时，如果指定房间尚未创建，云信 服务器内部会自动创建一个同名房间。
• 传参中 uid 可选，若不指定则默认为 0，SDK 会自动分配一个随机 uid，并在 onJoinChannel 回调方法中返回；App 层必须记住该返回值并维护，SDK 不对该返回值进行维护。
• 用户成功加入房间后，默认订阅房间内所有其他用户的音频流，可能会因此产生用量并影响计费；若您想取消自动订阅，可以在通话前通过调用 setParameters 方法实现。
• 网络测速过程中无法加入房间。
• 若使用了云代理功能，uid 不允许传 0，请用真实的 uid。

参数说明

参数名称	类型	描述
token	const char	安全认证签名（NERTC Token），可以设置为： null。调试模式下可设置为 null。安全性不高，建议在产品正式上线前在网易云信控制台中将鉴权方式恢复为默认的安全模式。 已获取的 NERTC Token。安全模式下必须设置为获取到的 Token。若未传入正确的 Token 将无法进入房间。推荐使用安全模式。
channelName	const char	房间名称，设置相同房间名称的用户会进入同一个通话房间。 字符串格式，长度为 1 ~ 64 字节。 支持以下 89 个字符：a-z, A-Z, 0-9, space, !#$%&()+-:;≤.,>? @[]^_{|}~”
uid	uid_t	用户的唯一标识 ID。
channel_options	NERtcJoinChannelOptions	加入房间时设置一些特定的房间参数。默认值为 nil。

示例代码

rtc_engine_->joinChannel(token, "124514", 1);

相关接口

• 您可以调用 leaveChannel 方法离开房间。
• 直播场景中，观众角色可以通过 switchChannel 接口切换房间。

相关回调

• 成功调用该方法加入房间后，本地会触发 onJoinChannel 回调，远端会触发 onUserJoined 回调。
• 在弱网环境下，若客户端和服务器失去连接，SDK 会自动重连，并在自动重连成功后触发 onRejoinChannel 回调。

返回

• 0（kNERtcNoError）：方法调用成功。
• 其他：方法调用失败。
  • 30001（kNERtcErrFatal）：重复入会或获取房间信息失败。
  • 30005（kNERtcErrInvalidState)：状态错误，比如引擎尚未初始化或正在进行网络探测。

leaveChannel()

virtual int nertc::IRtcEngine::leaveChannel ( )

pure virtual

离开音视频房间。
通过本接口可以实现挂断或退出通话，并释放本房间内的相关资源。

自从

V3.5.0

调用时机

请在初始化并成功加入房间后调用该方法。

注解

• 结束通话时必须调用此方法离开房间，否则无法开始下一次通话。
• 该方法是异步操作，调用返回时并没有真正退出频道。在真正退出房间后，SDK 会触发 onLeaveChannel 回调。
• 如果在调用 leaveChannel 后立即调用 release 方法，可能会无法正常离开房间；建议您在收到 onLeaveChannel 回调之后再调用 release 方法释放会话相关所有资源。

示例代码

rtc_engine_->leaveChannel();

相关回调

成功调用该方法离开房间后，本地会触发 onLeaveChannel 回调，远端会触发 onUserLeft 回调。

返回

• 0（kNERtcNoError）：方法调用成功。
• 其他：方法调用失败。
  • 30001（kNERtcErrFatal）：正在进行网络探测。
  • 30005（kNERtcErrInvalidState)：状态错误，比如引擎尚未初始化。
  • 30101（kNERtcErrChannelNotJoined）：尚未加入房间。
  • 30102（kNERtcErrChannelRepleatedlyLeave）：重复离开房间。
  • 30104（kNERtcErrSessionNotFound）：会话未找到。

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

设置房间场景。
通过此接口可以实现设置房间场景为通话（默认）、直播场景、视频 1 对 1 呼叫场景、语聊房场景等。针对不同场景采取的优化策略不同，如通话场景侧重语音流畅度，直播场景侧重视频清晰度。

自从

V3.6.0

注解

• 同一个房间内的用户建议使用同一种房间场景以获得最佳效果。
• 设置场景会影响音视频码率、帧率、视频分辨率、视频大小流模式、自动打开视频、自动订阅视频、传输策略。
• 调用此函数将覆盖上一次调用此函数设置的场景。
• 调用此函数场景类型为视频 1 对 1 呼叫场景、清晰度较高的 1 对 1 呼叫场景等 v5.5.40 新增的房间场景将覆盖您通过 setVideoConfig, setAudioProfile 等 API 设置的音视频相关配置，因此建议先第一时间设置场景再通过其他 API 调整音视频配置。
• V5.5.40 之前就存在通信场景和直播场景，设置通信场景和直播场景，不会覆盖 setVideoConfig, setAudioProfile 等 API 设置的音视频相关配置

调用时机

请在初始化后调用该方法，且该方法仅可在加入房间前调用。建议在初始化之后先调此方法，再调别的 API 设置的音视频相关配置。

参数说明

参数名称	类型	描述
profile	NERtcChannelProfileType	设置房间场景： kNERtcChannelProfileCommunication（0）：通话场景。 kNERtcChannelProfileLiveBroadcasting（1）：直播场景。 kNERtcChannelProfileVideoCall (3)：视频 1 对 1 呼叫场景。 kNERtcChannelProfileHighQualityVideoCall (4)：清晰度较高的 1 对 1 呼叫场景。 kNERtcChannelProfileChatroom (5)：语聊房场景。 kNERtcChannelProfileHighQualityChatroom (6)：高品质语聊房场景。 kNERtcChannelProfileMeeting (7)：会议场景。

示例代码

//设置房间场景为直播场景
rtc_engine->setChannelProfile(nertc::kNERtcChannelProfileLiveBroadcasting);

返回

• 0（kNERtcNoError）：方法调用成功。
• 其他：方法调用失败。
  • 30003（kNERtcErrInvalidParam）：参数错误。
  • 30004（kNERtcErrNotSupported）：不支持的操作，比如不是对主房间的设置。
  • 30005（kNERtcErrInvalidState)：当前状态不支持的操作，比如引擎尚未初始化。

setClientRole()

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

pure virtual

设置直播场景下的用户角色。
通过本接口可以实现将用户角色在“主播”（kNERtcClientRoleBroadcaster）和“观众“（kNERtcClientRoleAudience）之间的切换，用户加入房间后默认为“主播”。

自从

V3.9.0

使用前提

该方法仅在通过 setChannelProfile 方法设置房间场景为直播场景（kNERtcChannelProfileLiveBroadcasting）时调用有效。

调用时机

请在初始化后调用该方法，且该方法在加入房间前后均可调用。

业务场景

适用于观众上下麦与主播互动的互动直播场景。

注解

用户切换为观众角色时，SDK 会自动关闭音视频设备。

参数说明

参数名称	类型	描述
role	NERtcClientRole	用户角色： kNERtcClientRoleBroadcaster（0）：设置用户角色为主播。主播可以开关摄像头等设备、可以发布流、可以操作互动直播推流相关接口、加入或退出房间状态对其他房间内用户可见。 kNERtcClientRoleAudience（1）：设置用户角色为观众。观众只能收流不能发流加入或退出房间状态对其他房间内用户不可见。

示例代码

//切换用户角色为主播
rtc_engine_->setClientRole(nertc::kNERtcClientRoleBroadcaster);
//切换用户角色为观众
rtc_engine_->setClientRole(nertc::kNERtcClientRoleAudience);

相关回调

• 加入房间前调用该方法设置用户角色，不会触发任何回调，在加入房间成功后角色自动生效：
  • 设置用户角色为主播：加入房间后，远端用户触发 onUserJoined 回调。
  • 设置用户角色为观众：加入房间后，远端用户不触发任何回调。
• 加入房间后调用该方法切换用户角色：
  • 从观众角色切为主播：本端用户触发 onClientRoleChanged 回调，远端用户触发 onUserJoined 回调。
  • 从主播角色切为观众：本端用户触发 onClientRoleChanged 回调，远端用户触发 onUserleft 回调。

返回

• 0（kNERtcNoError）：方法调用成功。
• 其他：方法调用失败。
  • 30001（kNERtcErrFatal)：引擎未创建成功。
  • 30005（kNERtcErrInvalidState)：当前状态不支持的操作，不支持切换角色（主播/观众）。
  • 30101（kNERtcErrChannelNotJoined): 尚未加入房间。

setupLocalVideoCanvas()

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

pure virtual

设置本地用户视图。
通过本接口可以实现绑定本地用户和显示视图，并设置本地用户视图在本地显示时的镜像模式和裁减比例，只影响本地用户看到的视频画面。

自从

V3.5.0

调用时机

请在初始化后调用该方法，且该方法在加入房间前后均可调用。

注解

• 纯音频 SDK 禁用该接口，如需使用请前往云信官网下载并替换成视频 SDK。
• 在实际业务中，通常建议在初始化后即调用该方法进行本地视图设置，然后再加入房间或开启预览；若您开发的是 macOS 平台的 App，若使用的是外部渲染，必须在初始化 SDK 时设置本地视图。

参数说明

参数名称	类型	描述
canvas	NERtcVideoCanvas	本地用户视频的画布。设置为 NULL 表示取消并释放已设置的画布，详细信息请参考 NERtcVideoCanvas。

示例代码

nertc::NERtcVideoCanvas canvas;
canvas.cb = nullptr;
canvas.user_data = nullptr;
canvas.window = window;
canvas.scaling_mode = nertc::kNERtcVideoScaleFit;
canvas.mirror_mode = nertc::kNERtcVideoMirrorModeAuto;
rtc_engine_->setupLocalVideoCanvas(canvas)

相关接口

若您希望在通话中更新本地用户视图的渲染或镜像模式，请使用 setLocalRenderMode 方法。

返回

• 0（kNERtcNoError）：方法调用成功。
• 其他：方法调用失败。
  • 30001（kNERtcErrFatal）：画布创建失败。

setupRemoteVideoCanvas()

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

pure virtual

设置远端用户视图。
通过本接口可以实现绑定远端用户和显示视图，并设置远端用户视图在本地显示时的镜像模式和裁减比例，只影响本地用户看到的视频画面。

自从

V3.5.0

调用时机

请在初始化后调用该方法，且该方法在加入房间前后均可调用。

注解

您可以通过设置 canvas 参数为空以解除远端用户视图绑定；退出房间后，SDK 也会主动清除远端用户和视图的绑定关系。

参数说明

参数名称	类型	描述
canvas	NERtcVideoCanvas	远端用户视频的画布。
uid	uid_t	远端用户的 ID。可以在 onUserJoined 回调中获取。

示例代码

nertc::NERtcVideoCanvas canvas;
canvas.cb = nullptr;
canvas.user_data = nullptr;
canvas.window = window;
canvas.scaling_mode = nertc::kNERtcVideoScaleFit; 
canvas.mirror_mode  = nertc::kNERtcVideoMirrorModeAuto;
rtc_engine_->setupRemoteVideoCanvas(uid, canvas);

相关接口

若您希望在通话中更新远端用户视图的渲染模式，请调用 setRemoteRenderMode 方法。

返回

• 0（kNERtcNoError）：方法调用成功。
• 其他：方法调用失败。
  • 30001（kNERtcErrFatal）：画布创建失败。
  • 30005（kNERtcErrInvalidState）：当前状态不支持的操作，比如引擎尚未初始化。

subscribeRemoteVideoStream() [1/2]

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

pure virtual

订阅或取消订阅指定远端用户的视频主流。
加入房间后，默认不订阅所有远端用户的视频主流；若您希望看到指定远端用户的视频，可以在监听到对方加入房间或发布视频流之后，通过此方法订阅该用户的视频主流。

自从

V3.5.0

调用时机

请在初始化后调用该方法，且该方法仅可在加入房间后调用。

参数说明

参数名称	类型	描述
uid	uid_t	指定用户的 ID。
type	NERtcRemoteVideoStreamType	订阅的视频流类型： kNERtcRemoteVideoStreamTypeHigh：高清画质的大流。 kNERtcRemoteVideoStreamTypeLow：低清画质的小流。 kNERtcRemoteVideoStreamTypeNone：不订阅。
subscribe	bool	是否订阅远端用户的视频流： true：订阅指定视频流。 false：不订阅指定视频流。

示例代码

//订阅对方 uid 为 12345 的大流
rtc_engine_->subscribeRemoteVideoStream(12345, nertc::kNERtcRemoteVideoStreamTypeHigh,true);

相关接口

若您希望订阅指定远端用户的视频辅流，请调用 subscribeRemoteVideoSubStream} 方法。

返回

• 0（kNERtcNoError）：方法调用成功。
• 其他：方法调用失败。
  • 30001（kNERtcErrFatal）：画布为空对象，创建远端 peerconnection 失败。
  • 30005（kNERtcErrInvalidState)：状态错误，比如引擎尚未初始化。
  • 30009（kNERtcErrInvalidDeviceSourceID）：设备 ID 非法。
  • 30105（kNERtcErrUserNotFound）：未找到指定用户。
  • 30106（kNERtcErrInvalidUserID）：非法指定用户，比如订阅了本端。
  • 30107（kNERtcErrMediaNotStarted）：媒体会话未建立，比如对端未开启视频主流。
  • 30108（kNERtcErrSourceNotFound）：媒体源未找到，比如对端未开启视频主流。

subscribeRemoteVideoStream() [2/2]

virtual int nertc::IRtcEngine::subscribeRemoteVideoStream ( uid_t uid, NERtcVideoStreamType stream_type, NERtcRemoteVideoStreamType subscribe_type, bool subscribe )

pure virtual

订阅或取消订阅指定远端用户的视频主流。
加入房间后，默认不订阅所有远端用户的视频主流；若您希望看到指定远端用户的视频，可以在监听到对方加入房间或发布视频流之后，通过此方法订阅该用户的视频主流。

自从

V5.6.40

调用时机

请在初始化后调用该方法，且该方法仅可在加入房间后调用。

参数说明

参数名称	类型	描述
uid	uid_t	指定用户的 ID。
stream_type	NERtcVideoStreamType	视频通道类型： kNERTCVideoStreamMain：主流。 kNERTCVideoStreamSub：辅流。
subscribe_type	NERtcRemoteVideoStreamType	订阅的视频流类型： kNERtcRemoteVideoStreamTypeHigh：高清画质的大流。 kNERtcRemoteVideoStreamTypeLow：低清画质的小流。 kNERtcRemoteVideoStreamTypeNone：不订阅。
subscribe	bool	是否订阅远端用户的视频流： true：订阅指定视频流。 false：不订阅指定视频流。

示例代码

//订阅对方 uid 为 12345 的大流
rtc_engine_->subscribeRemoteVideoStream(12345, nertc::kNERTCVideoStreamMain, nertc::kNERtcRemoteVideoStreamTypeHigh,true);

相关接口

若您希望订阅指定远端用户的视频辅流，请调用 subscribeRemoteVideoSubStream} 方法。

返回

• 0（kNERtcNoError）：方法调用成功。
• 其他：方法调用失败。
  • 30001（kNERtcErrFatal）：画布为空对象，创建远端 peerconnection 失败。
  • 30005（kNERtcErrInvalidState)：状态错误，比如引擎尚未初始化。
  • 30009（kNERtcErrInvalidDeviceSourceID）：设备 ID 非法。
  • 30105（kNERtcErrUserNotFound）：未找到指定用户。
  • 30106（kNERtcErrInvalidUserID）：非法指定用户，比如订阅了本端。
  • 30107（kNERtcErrMediaNotStarted）：媒体会话未建立，比如对端未开启视频主流。
  • 30108（kNERtcErrSourceNotFound）：媒体源未找到，比如对端未开启视频主流。

switchChannel() [1/2]

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

pure virtual

快速切换音视频房间。 通过此接口可以实现当房间场景为直播场景时，从当前房间快速切换至另一个房间。

使用前提

请先通过 setChannelProfile 接口设置房间模式为直播模式。

调用时机

请在引擎初始化之后调用此接口，且该方法仅可在加入房间后调用。

注解

• 房间成员成功切换房间后，将会保持切换前的音视频的状态。
• v5.5.10 及之后版本，主播和观众都支持调用本接口快速切换至另一个房间。
• v5.5.10 之前版本，只支持观众调用本接口快速切换至另一个房间。

参数说明

参数名称	类型	描述
token	const char*	在服务器端生成的用于鉴权的安全认证签名（Token），可设置为： 已获取的 NERTC Token。安全模式下必须设置为获取到的 Token，默认 Token 有效期为 10min，也可以定期通过应用服务器向云信服务器申请 Token 或者申请长期且可复用的 Token。 null。调试模式下可设置为 null。安全性不高，建议在产品正式上线前在网易云信控制台中将鉴权方式恢复为默认的安全模式。
channel_name	const char*	期望切换到的目标房间名称。

示例代码

if (rtc_engine_) {
    ret = rtc_engine_->switchChannel(token_.c_str(), room_name.c_str());
}

相关回调

成功调用此接口切换房间后：

• 本端用户会先收到 onLeaveChannel 回调，其中 result 参数为 kNERtcErrChannelLeaveBySwitchAction，再收到成功加入新房间的回调 onJoinChannel。
• 远端用户会收到 onUserLeft 和 onUserJoined 的回调。

返回

• 0（kNERtcNoError）： 方法调用成功。
• 其他：方法调用失败。
  • 403（kNERtcErrChannelReservePermissionDenied）：没有权限，比如主播无法切换房间。
  • 30001（kNERtcErrFatal）：通用错误。
  • 30003（kNERtcErrInvalidParam）：参数错误，比如房间名称为空字符串。
  • 30100（kNERtcErrChannelAlreadyJoined）：重复加入房间。
  • 30109（kNERtcErrSwitchChannelInvalidState）：尚未加入房间。

switchChannel() [2/2]

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

pure virtual

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

注解

• 房间成员成功切换房间后，默认订阅房间内所有其他成员的音频流，因此产生用量并影响计费。如果想取消订阅，可以通过调用相应的 subscribeRemoteAudio 方法传入 false 实现。

参数

[in]	token	安全认证签名（NERTC Token）。可设置为： null。调试模式下可设置为 null。建议在产品正式上线前在网易云信控制台中将鉴权方式恢复为默认的安全模式。 已获取的 NERTC Token。安全模式下必须设置为获取到的 Token。若未传入正确的 Token 将无法进入房间。推荐使用安全模式。
[in]	channel_name	期望切换到的目标房间名称。
[in]	channel_options	加入房间时设置一些特定的房间参数，详情参考 NERtcJoinChannelOptions。

返回

• 0(kNERtcNoError)：方法调用成功。
• 30001(kNERtcErrFatal)：通用错误。
• 30003(kNERtcErrInvalidParam)：参数错误。
• 30109(kNERtcErrSwitchChannelInvalidState): 切换房间状态无效。
• 403(kNERtcErrChannelReservePermissionDenied): 用户角色不是观众。
• 30100(kNERtcErrChannelAlreadyJoined): 房间名无效，已在此房间中。

switchChannelEx()

virtual int nertc::IRtcEngine::switchChannelEx ( const char * token, const char * channel_name, NERtcJoinChannelOptionsEx channel_options_ex )

pure virtual

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

注解

• 该方法仅适用于直播场景中，角色为观众的音视频房间成员。即已通过接口 setchannelprofile 设置房间场景为直播，通过 setClientRole 设置房间成员的角色为观众。
• 房间成员成功切换房间后，默认订阅房间内所有其他成员的音频流，因此产生用量并影响计费。如果想取消订阅，可以通过调用相应的 subscribeRemoteAudio 方法传入 false 实现。

参数

[in]	token	安全认证签名（NERTC Token）。可设置为： null。调试模式下可设置为 null。建议在产品正式上线前在网易云信控制台中将鉴权方式恢复为默认的安全模式。 已获取的 NERTC Token。安全模式下必须设置为获取到的 Token。若未传入正确的 Token 将无法进入房间。推荐使用安全模式。
[in]	channel_name	期望切换到的目标房间名称。
[in]	channel_options	加入房间时设置一些特定的房间参数，详情参考 NERtcJoinChannelOptions。

返回

• 0(kNERtcNoError)：方法调用成功。
• 30001(kNERtcErrFatal)：通用错误。
• 30003(kNERtcErrInvalidParam)：参数错误。
• 30109(kNERtcErrSwitchChannelInvalidState): 切换房间状态无效。
• 403(kNERtcErrChannelReservePermissionDenied): 用户角色不是观众。
• 30100(kNERtcErrChannelAlreadyJoined): 房间名无效，已在此房间中。

---

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

• nertc_engine.h