#include <nertc_engine.h>
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: 关闭本地语音功能，即停止本地语音采集或处理。
|
- 返回
-
◆ enableLocalVideo() [1/2]
| virtual int nertc::IRtcEngine::enableLocalVideo |
( |
bool |
enabled | ) |
|
|
pure virtual |
开启或关闭本地视频采集和渲染。
该方法启用本地视频采集功能。
- 注解
-
- 参数
-
| [in] | enabled | 是否启用本地视频采集和渲染:
- true: 开启本地视频采集和渲染 (默认)；
- false: 关闭使用本地摄像头设备。关闭后，远端用户会接收不到本地用户的视频流；但本地用户依然可以接收远端用户的视频流。设置为 false 时，该方法不需要本地有摄像头。
|
- 返回
-
◆ enableLocalVideo() [2/2]
开启或关闭本地视频的采集与发送。
通过主流或辅流视频通道进行本地视频流的采集与发送。
- 自从
- V4.6.20
- 调用时机
- 请在初始化后调用该方法，且该方法在加入房间前后均可调用。
- 注解
-
- 参数说明
| 参数名称 | 类型 | 描述 |
| 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()
◆ 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 释放会话相关所有资源。
- 返回
-
◆ queryInterface()
获取设备管理员对象的指针。
- 参数
-
| [in] | iid | 想要获取的接口的iid. |
| [in] | inter | 指向 DeviceManager 对象的指针。 |
- 返回
-
◆ 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()
设置房间场景。
房间场景可设置为通话或直播场景，不同的场景中 QoS 策略不同。
- 注解
- 必须在加入通话前设置，开始通话后设置无效，结束通话后保留之前的设置。
- 参数
-
| [in] | profile | 设置房间场景。详细信息请参考 NERtcChannelProfileType。 |
- 返回
-
◆ setClientRole()
在直播场景中设置用户角色。
用户角色支持设置为主播或观众，主播和观众的权限不同。
- 主播：可以开关摄像头等设备、可以发布流、可以操作互动直播推流相关接口、上下线对其他房间内用户可见。
- 观众：不可以开关摄像头等设备、不可以发布流、不可以操作互动直播推流相关接口、上下线对其他房间内用户不可见。
如果你在加入频道后调用该方法切换角色，调用成功后会收到以下回调：
- 主播切观众，本端触发 onClientRoleChanged 回调，远端触发 onUserLeft 回调。
- 观众切主播，本端触发 onClientRoleChanged 回调，远端触发 onUserJoined 回调。
- 注解
- 默认情况下用户以主播角色加入房间。
- 在加入房间前，用户可以调用本接口切换本端角色为观众。在加入房间后，用户也可以通过本接口切换用户角色。
- 用户切换为观众角色时，SDK 会自动关闭音视频设备。
- 自从
- V4.5.0
- 参数
-
- 返回
- 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 方法。
- 参数
-
- 返回
-
◆ setupRemoteVideoCanvas()
设置远端用户视图。
该方法绑定远端用户和显示视图，并设置远端用户视图在本地显示时的渲染模式和镜像模式，只影响本地用户看到的视频画面。
- 注解
- 调用该接口时需要指定远端视频的 uid，一般可以在用户加入后设置好。
- 如果 App 无法事先知道对方的用户 ID，可以在 APP 收到 onUserJoined 事件时设置。
- 解除某个用户的绑定视图可以把 canvas 设置为空。
- 退出房间后，SDK 会清除远程用户和视图的绑定关系。
- 如果您希望在通话中更新本地用户视图的渲染或镜像模式，请使用 setRemoteRenderMode 方法。
- 参数
-
- 返回
-
◆ subscribeRemoteVideoStream()
订阅或取消订阅指定远端用户的视频流。
- 注解
- 用户加入房间之后，默认不订阅远端用户的视频流，如果希望看到指定远端用户的视频，可以在监听到对方加入房间或发布视频流之后，通过此方法订阅该用户的视频流。
- 该方法需要在加入房间后调用。
- 参数
-
- 返回
-
◆ 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 | 期望切换到的目标房间名称。 |
- 返回
-
该类的文档由以下文件生成:
