NERtc iOS SDK  V4.6.0
构造函数 | 所有成员列表
<INERtcEngine>协议 参考

NERtcEngine 的常用接口。 更多...

#import <INERtcEngine.h>

类 <INERtcEngine> 继承关系图:
<INERtcEngineEx> NERtcEngine

构造函数

(NERtcConnectionStateType) - connectionState
 获取当前房间连接状态。 更多...
 
(int) - setupEngineWithContext:
 创建 NERtcEngine 并初始化 NERTC SDK 服务。 更多...
 
(int) - joinChannelWithToken:channelName:myUid:completion:
 加入音视频房间。
加入音视频房间时，如果指定房间尚未创建，云信服务器内部会自动创建一个同名房间。 更多...
 
(int) - leaveChannel
 离开房间，即挂断或退出通话。
结束通话时，必须调用 leaveChannel 结束通话，否则无法开始下一次通话。
成功调用该方法离开房间后，本地会触发 onNERtcEngineDidLeaveChannelWithResult 回调，远端会触发 onNERtcEngineUserDidLeaveWithUserID 回调。 更多...
 
(int) - switchChannelWithToken:channelName:completion:
 快速切换音视频房间。
房间场景为直播场景时，房间中角色为观众的成员可以调用该方法从当前房间快速切换至另一个房间。
成功调用该方切换房间后，本端会收到离开房间的回调 onNERtcEngineDidLeaveChannelWithResult；远端用户会收到 onNERtcEngineUserDidLeaveWithUserID 和 onNERtcEngineUserDidJoinWithUserID 的回调。 更多...
 
(int) - enableLocalAudio:
 开启/关闭本地音频采集和发送。
当 App 加入房间时，语音功能默认为开启状态。
该方法不影响接收或播放远端音频流，enableLocalAudio(NO) 适用于只下行不上行音频流的场景。
成功调用该方法后，房间内其他用户触发 onNERtcEngineUserAudioDidStart 或 onNERtcEngineUserAudioDidStop 回调。 更多...
 
(int) - enableLocalVideo:
 是否开启本地视频采集。 更多...
 
(int) - setChannelProfile:
 设置房间场景。
房间场景可设置为通话或直播场景，不同的场景中 QoS 策略不同。 更多...
 
(int) - setLocalVideoConfig:
 设置视频编码属性。 更多...
 
(int) - setAudioProfile:scenario:
 设置音频编码属性。 更多...
 
(int) - setupLocalVideoCanvas:
 设置本地视图。
该方法设置本地视频显示信息。只影响本地用户看到的视频画面，不影响远端。 App 通过调用此接口绑定本地视频流的显示视窗（view）。 在 App 开发中，通常在初始化后调用该方法进行本地视频设置，然后再加入房间。 更多...
 
(int) - setupRemoteVideoCanvas:forUserID:
 设置远端用户视图。
该方法绑定远端用户和显示视图，并设置远端用户视图在本地显示时的渲染模式和镜像模式，只影响本地用户看到的视频画面。 更多...
 
(int) - switchCamera
 切换前置/后置摄像头。
该方法需要在相机启动后调用，例如调用 startPreview 或 joinChannel 后。 更多...
 
(int) - setClientRole:
 在直播场景中设置用户角色。
用户角色支持设置为主播或观众，主播和观众的权限不同。 更多...
 
(int) - setParameters:
 设置音视频通话的相关参数。 更多...
 

详细描述

NERtcEngine 的常用接口。

函数文档

◆ connectionState

- (NERtcConnectionStateType) connectionState

获取当前房间连接状态。

返回
当前房间连接状态。

◆ enableLocalAudio:

- (int) enableLocalAudio: (BOOL)  enabled

开启/关闭本地音频采集和发送。
当 App 加入房间时，语音功能默认为开启状态。
该方法不影响接收或播放远端音频流，enableLocalAudio(NO) 适用于只下行不上行音频流的场景。
成功调用该方法后，房间内其他用户触发 onNERtcEngineUserAudioDidStart 或 onNERtcEngineUserAudioDidStop 回调。

注解
  • 该方法与 muteLocalAudio 的区别在于，enableLocalAudio 用于开启本地语音采集及处理；muteLocalAudio 用于停止或继续发送本地音频流。
  • 该方法设置内部引擎为启用状态，在 leaveChannel 后仍然有效。
  • 从 V4.4.0 版本开始，开启或关闭本地音频采集的操作不再影响音乐文件播放，即 enableLocalAudio(NO) 后仍旧可以通过 startAudioMixingWithOption: 播放音乐文件。
参数
enabled是否开启本地音频采集。
返回
  • 0: 方法调用成功；
  • 其他: 方法调用失败。

◆ enableLocalVideo:

- (int) enableLocalVideo: (BOOL)  enabled

是否开启本地视频采集。

注解
  • 该方法在加入房间前和加入房间后均可调用。
  • 成功启用或禁用本地视频采集后，远端会触发 onNERtcEngineUserVideoDidStartWithUserID 或 onNERtcEngineUserVideoDidStop 回调。
参数
enabled是否开启本地视频采集。
返回
操作返回值，成功则返回 0

◆ joinChannelWithToken:channelName:myUid:completion:

- (int) joinChannelWithToken: (NSString *)  token
channelName: (NSString *)  channelName
myUid: (uint64_t)  uId
completion: (NERtcJoinChannelCompletion)  completion 

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

  • SDK 加入房间后，同一个房间内的用户可以互相通话，多个用户加入同一个房间，可以群聊。使用不同 App Key 的 App 之间不能互通。
  • 成功调用该方加入房间后，远端会触发 onNERtcEngineUserDidJoinWithUserID 回调。
  • 直播场景下的观众角色可以通过 switchChannelWithToken 快速切换房间。
    参数
    token安全认证签名（NERTC Token）。可设置为：
    • null。调试模式下可设置为 null。安全性不高，建议在产品正式上线前在云信控制台中将鉴权方式恢复为默认的安全模式。
    • 已获取的NERTC Token。安全模式下必须设置为获取到的 Token 。若未传入正确的 Token 将无法进入房间。推荐使用安全模式。
    channelName房间名称，设置相同房间名称的用户会进入同一个通话房间。
    字符串格式，长度为1~ 64 字节。支持以下89个字符：a-z, A-Z, 0-9, space, !#$%&()+-:;≤.,>? @[]^_{|}~”
    uId用户的唯一标识 id，房间内每个用户的 uId 必须是唯一的。
    uId 可选，默认为 0。如果不指定（即设为 0），SDK 会自动分配一个随机 uId，并在 NERtcJoinChannelCompletion 中返回，App 层必须记住该返回值并维护，SDK 不对该返回值进行维护。
    completion操作完成的 block 回调。
    返回
    操作返回值，被执行了则返回 0。

◆ leaveChannel

- (int) leaveChannel

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

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

◆ setAudioProfile:scenario:

- (int) setAudioProfile: (NERtcAudioProfileType)  profile
scenario: (NERtcAudioScenarioType)  scenario 

设置音频编码属性。

注解
该方法需要在 joinChannel 之前设置，joinChannel 后设置不生效。
参数
profile设置采样率、码率、编码模式和声道数。详细信息请参考 NERtcAudioProfileType。
scenario设置音频应用场景。详细信息请参考 NERtcAudioScenarioType。
返回
  • 0: 方法调用成功；
  • 其他: 方法调用失败。

◆ setChannelProfile:

- (int) setChannelProfile: (NERtcChannelProfileType)  channelProfile

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

注解
该方法必须在加入房间前调用，进入房间后无法再设置房间场景。
参数
channelProfile设置房间场景。详细信息请参考 NERtcEngineEnum.NERtcChannelProfileType。
返回
操作返回值，成功则返回 0

◆ setClientRole:

- (int) setClientRole: (NERtcClientRole)  role

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

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

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

  • 主播切观众，本端触发 onNERtcEngineDidClientRoleChanged 回调，远端触发 onNERtcEngineUserDidLeaveWithUserID 回调。
  • 观众切主播，本端触发 onNERtcEngineDidClientRoleChanged 回调，远端触发 onNERtcEngineUserDidJoinWithUserID 回调。
注解
  • 默认情况下用户以主播角色加入房间。在加入房间前，用户可以调用本接口切换本端模式为观众。在加入房间后，用户也可以通过本接口切换用户模式。
  • 用户切换为观众角色时，SDK 会自动关闭音视频设备。
自从
V4.5.0
参数
role用户角色。详细信息请参考 NERtcClientRole。
返回
  • 0(kNERtcNoError): 方法调用成功。
  • < 0: 方法调用失败。
    • 30001(kNERtcErrFatal): Engine 未创建。
    • 30101(kNERtcErrChannelNotJoined): 尚未加入房间。

◆ setLocalVideoConfig:

- (int) setLocalVideoConfig: (NERtcVideoEncodeConfiguration *)  config

设置视频编码属性。

  • 可以在加入房间前或加入房间后调用此接口。
  • NERtcVideoConfig 中的 videoProfile 可以指定预设的 Profile 模式，但是预设模式往往无法满足实际场景需求，网易云信建议您通过 width 和 height 进行自定义设置。详细信息请参考设置视频属性。
    注解

  • 纯音频 SDK 禁用该接口，如需使用请前往云信官网下载并替换成视频 SDK。
  • V4.5.0 开始，setLocalVideoConfig 方法实时生效；此前的版本中，setLocalVideoConfig 方法设置成功后，下次开启本端视频时生效。
  • 每个属性对应一套视频参数，例如分辨率、帧率、码率等。所有设置的参数均为理想情况下的最大值。当视频引擎因网络环境等原因无法达到设置的分辨率、帧率或码率的最大值时，会取最接近最大值的那个值。
  • setLocalVideoConfig 为全量参数配置接口，重复调用此接口时，SDK 会刷新此前的所有参数配置，以最新的传参为准。所以每次修改配置时都需要设置所有参数，未设置的参数将取默认值。
    参数
    config视频编码属性配置，详细信息请参考 NERtcVideoEncodeConfiguration。
    返回
    操作返回值，成功则返回 0

◆ setParameters:

- (int) setParameters: (NSDictionary *)  parameters

设置音视频通话的相关参数。

注解

  • 此接口可在加入房间前后调用。使用参数 kNERtcKeyVideoPreferHWEncode、kNERtcKeyVideoPreferHWDecode 时，请在初始化前调用此接口。
  • 此方法提供技术预览或特别定制功能，若您需要使用此接口，请咨询技术支持获取帮助。
参数
parameters参数内容 参数 key，请参阅 NERtcEngineBase.h 中的定义
返回
操作返回值，成功则返回 0

◆ setupEngineWithContext:

- (int) setupEngineWithContext: (NERtcEngineContext *)  context

创建 NERtcEngine 并初始化 NERTC SDK 服务。

注解
  • 请确保在调用其他 API 前先调用该方法创建并初始化 NERtc 实例。
  • 使用同一个 App Key 的 App 才能进入同一个房间进行通话或直播。
  • 一个App Key 只能用于创建一个NERtc 实例。如需更换 App Key，必须先调用 destroyEngine 方法销毁当前实例，再调用本方法重新创建实例。
  • 若不再使用 NERtc 实例，需要调用 destroyEngine 进行销毁。
参数
context传入的RTC engine context对象。详细信息请参考 NERtcEngineContext。
返回
操作返回值，成功则返回 0

◆ setupLocalVideoCanvas:

- (int) setupLocalVideoCanvas: (NERtcVideoCanvas *_Nullable)  canvas

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

注解
参数
canvas视频画布。详细信息请参考 NERtcVideoCanvas。如果需要删除则传 nil。
返回
  • 0: 方法调用成功；
  • 其他: 方法调用失败。

◆ setupRemoteVideoCanvas:forUserID:

- (int) setupRemoteVideoCanvas: (NERtcVideoCanvas *_Nullable)  canvas
forUserID: (uint64_t)  userID 

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

注解
  • 如果 App 无法事先知道对方的用户 ID，可以在 APP 收到 onNERtcEngineUserDidJoinWithUserID 事件时设置。
  • 解除某个用户的绑定视图可以把 canvas 设置为空。
  • 退出房间后，SDK 会清除远程用户和视图的绑定关系。
  • 如果您希望在通话中更新本地用户视图的渲染或镜像模式，请使用 INERtcEngineEx#setRemoteRenderScaleMode:forUserID: 方法。
参数
userID远端用户 ID。
canvas视频窗口。详细信息请参考 NERtcVideoCanvas。如果需要删除则传 nil。
返回
  • 0: 方法调用成功；
  • 其他: 方法调用失败。

◆ switchCamera

- (int) switchCamera

切换前置/后置摄像头。
该方法需要在相机启动后调用，例如调用 startPreview 或 joinChannel 后。

注解
纯音频 SDK 禁用该接口，如需使用请前往云信官网下载并替换成视频 SDK。
返回
操作返回值，成功则返回 0

◆ switchChannelWithToken:channelName:completion:

- (int) switchChannelWithToken: (NSString *)  token
channelName: (NSString *)  channelName
completion: (NERtcJoinChannelCompletion)  completion 

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

注解
  • 房间成员成功切换房间后，默认订阅房间内所有其他成员的音频流，因此产生用量并影响计费。如果想取消订阅，可以通过调用相应的 subscribeRemoteAudio 方法实现。
  • 该方法仅适用于直播场景中，角色为观众的音视频房间成员。即已通过接口 setchannelprofile 设置房间场景为直播，通过 setClientRole 设置房间成员的角色为观众。
参数
token在服务器端生成的用于鉴权的安全认证签名（Token）。可设置为：
  • null。调试模式下可设置为 null。安全性不高，建议在产品正式上线前在云信控制台中将鉴权方式恢复为默认的安全模式。
  • 已获取的NERTC Token。安全模式下必须设置为获取到的 Token 。若未传入正确的 Token 将无法进入房间。推荐使用安全模式。
channelName期望切换到的目标房间名称
completion操作完成的 block 回调
返回
该协议的文档由以下文件生成:
制作者 doxygen 1.9.1