频道相关

getUserInfoByUid

通过传入用户 ID 获取用户信息。

C++

virtual int getUserInfoByUid(uid_t uid, rtc::UserInfo* userInfo) = 0;

当远端用户加入频道后，SDK 会获取该远端用户的用户 ID 和用户 User Account，并将其缓存在一个映射表中，并在本地客户端触发 onUserInfoUpdated 回调。收到该回调后，你可以调用 getUserInfoByUid 并传入用户 ID，从 UserInfo 对象中获取对应的用户 User Account。

调用时机

在收到 onUserInfoUpdated 回调后调用该方法。

参数

uid

uid，表示用户 ID。

userInfo

输入和输出参数，表示用户信息。输入值为一个 UserInfo 对象，输出值为一个包含用户 User Account 和用户 ID 的 UserInfo 对象。详见 UserInfo。

返回值

• 0：方法调用成功。
• < 0：方法调用失败。详见错误码了解详情和解决建议。

所属接口类

• IRtcEngine

getUserInfoByUidEx

通过传入用户 ID 获取用户信息。

C++

virtual int getUserInfoByUidEx(uid_t uid, rtc::UserInfo* userInfo, const RtcConnection& connection) = 0;

该方法通过传入用户 ID 获取用户信息。功能与 getUserInfoByUid 相同。

适用场景

适用于多频道场景。

参数

uid

远端用户的用户 ID。

userInfo

输入和输出参数，用于标识用户的 UserInfo 对象。调用该方法时传入的 UserInfo 对象，在方法调用成功后返回包含用户 User Account 和用户 ID 的 UserInfo 对象。详见 UserInfo。

connection

RtcConnection 对象。详见 RtcConnection。

返回值

• 0：方法调用成功。
• < 0：方法调用失败。详见错误码了解详情和解决建议。

所属接口类

• IRtcEngineEx

getUserInfoByUserAccount

通过传入用户 User Account 获取远端用户信息。

C++

virtual int getUserInfoByUserAccount(const char* userAccount, rtc::UserInfo* userInfo) = 0;

远端用户加入频道后，SDK 会获取该远端用户的用户 ID 和用户 User Account，并将其缓存在映射表中，同时在本地客户端触发 onUserInfoUpdated 回调。收到该回调后，你可以调用该方法并传入用户 User Account，从 UserInfo 对象中获取该远端用户的用户 ID。

调用时机

在收到 onUserInfoUpdated 回调后调用该方法。

参数

userAccount

用户 User Account。

userInfo

输出参数，表示用户信息。详见 UserInfo。

返回值

• 0：方法调用成功。
• < 0：方法调用失败。详见错误码了解详情和解决建议。

所属接口类

• IRtcEngine

getUserInfoByUserAccountEx

通过用户 User Account 获取用户信息。

C++

virtual int getUserInfoByUserAccountEx(const char* userAccount, rtc::UserInfo* userInfo, const RtcConnection& connection) = 0;

该方法通过传入用户 User Account 获取用户信息，功能与 getUserInfoByUserAccount 相同。

适用场景

该方法适用于多频道场景。

参数

userAccount

用户 User Account。请确保设置该参数。

userInfo

输入和输出参数，用于标识用户的 UserInfo 对象。调用该方法后，该对象将包含用户 User Account 和用户 ID。详见 UserInfo。

connection

RtcConnection 对象。详见 RtcConnection。

返回值

• 0：方法调用成功。
• < 0：方法调用失败。详见错误码了解详情和解决建议。

所属接口类

• IRtcEngineEx

joinChannel [1/2]

加入一个频道。

C++

virtual int joinChannel(const char* token, const char* channelId, const char* info, uid_t uid) = 0;

默认情况下，用户会订阅频道中其他所有用户的音视频流，从而产生使用量和计费。如需停止订阅指定流或所有远端流，请调用 muteRemoteAudio/VideoStream 或 muteAllRemoteAudio/VideoStreams。

信息

• 该方法仅支持用户同时加入一个频道。
• 不同 App ID 的用户无法互通。
• 加入频道前，请确保用于生成 Token 的 App ID 与调用 initialize 方法时传入的 App ID 一致，否则可能会导致加入频道失败。

调用时机

该方法需要在调用 initialize 方法之后调用。

相关回调

成功调用该方法后，SDK 会触发以下回调：

• 本地客户端：onJoinChannelSuccess 和 onConnectionStateChanged 回调。
• 远端客户端：如果用户在 COMMUNICATION 频道场景中加入频道，或主播在 LIVE_BROADCASTING 频道场景中加入频道，则触发 onUserJoined 回调。

当由于网络状况不佳导致本地客户端与声网服务器的连接中断时，SDK 会尝试重新连接服务器。当本地客户端成功重新加入频道时，SDK 会在本地客户端触发 onRejoinChannelSuccess 回调。

参数

token

用于鉴权的 Token，由你的服务器生成。

信息

• （推荐）如果你的项目启用了安全模式（使用 App ID 和 Token 进行鉴权），该参数为必填。
• 如果你只启用了测试模式（使用 App ID 进行鉴权），该参数为可选。成功加入频道后，你将在 24 小时后自动退出频道。
• 如果你需要同时加入多个频道或在频道间切换，声网建议使用通配符 Token，这样你每次加入频道时无需重新申请 Token。

channelId

频道名。在相同 App ID 的前提下，填写相同频道名的用户会进入同一个频道进行音视频互动。字符串长度必须小于 64 字节。支持的字符（共 89 个）：

• 所有小写英文字母：a 到 z。
• 所有大写英文字母：A 到 Z。
• 所有数字字符：0 到 9。
• "!", "#", "$", "%", "&", "(", ")", "+", "-", ":", ";", "<", "=", ".", ">", "?", "@", "[", "]", "^", "_", "{", "}", "|", "~", ","

info

（可选）预留参数。

uid

用户 ID。用于标识频道中的用户以进行实时音视频互动。你需要自行设置和管理用户 ID，并确保同一频道中的每个用户 ID 唯一。该参数为 32 位无符号整数，取值范围为 1 到 2^32 - 1。如果未指定用户 ID（或设置为 0），SDK 会自动分配一个随机用户 ID，并在 onJoinChannelSuccess 回调中返回。你的应用程序必须记录并维护返回的用户 ID，SDK 不会保存。

返回值

• 0：方法调用成功。
• < 0：方法调用失败。详见错误码了解详情和解决建议。
  • -2：参数无效。例如，Token 无效，uid 参数未设置为整数，或 ChannelMediaOptions 中的成员值无效。你需要传入有效参数并重新加入频道。
  • -3：IRtcEngine 对象初始化失败。你需要重新初始化 IRtcEngine 对象。
  • -7：IRtcEngine 对象尚未初始化。你需要先初始化 IRtcEngine 对象再调用该方法。
  • -8：IRtcEngine 对象的内部状态错误。典型原因是在调用 startEchoTest 开始通话回声测试后，未调用 stopEchoTest 停止测试就调用该方法加入频道。你需要先调用 stopEchoTest 再调用该方法。
  • -17：加入频道请求被拒绝。典型原因是用户已在频道中。声网建议你使用 onConnectionStateChanged 回调判断用户是否在频道中。只有在收到 CONNECTION_STATE_DISCONNECTED（1）状态时才调用该方法加入频道。
  • -102：频道名无效。你需要在 channelId 中传入有效的频道名重新加入频道。
  • -121：用户 ID 无效。你需要在 uid 中传入有效的用户 ID 重新加入频道。

所属接口类

• IRtcEngine

joinChannel [2/2]

加入频道并设置媒体选项。

C++

virtual int joinChannel(const char* token, const char* channelId, uid_t uid, const ChannelMediaOptions& options) = 0;

该方法相比 joinChannel [1/2] 增加了 options 参数，用于设置媒体选项，例如是否在频道内发布音视频流，或在加入频道时是否自动订阅所有远端用户的音视频流。默认情况下，用户会订阅频道中所有其他用户的音视频流，从而产生使用量和计费。如需停止订阅其他流，请设置 options 参数或调用 muteRemoteAudio/VideoStream 或 muteAllRemoteAudio/VideoStreams。

信息

• 该方法仅支持用户同时加入一个频道。
• 不同 App ID 的用户无法互通。
• 加入频道前，请确保用于生成 Token 的 App ID 与调用 initialize 方法时传入的 App ID 一致，否则可能会导致加入频道失败。

调用时机

请在调用 initialize 方法后调用该方法。

相关回调

成功调用该方法后，SDK 会触发以下回调：

• 本地客户端：onJoinChannelSuccess 和 onConnectionStateChanged 回调。
• 远端客户端：如果用户在 COMMUNICATION 频道场景中加入频道，或主播在 LIVE_BROADCASTING 频道场景中加入频道，则触发 onUserJoined 回调。

当由于网络状况不佳导致本地客户端与声网服务器的连接中断时，SDK 会尝试重新连接服务器。当本地客户端成功重新加入频道时，SDK 会在本地客户端触发 onRejoinChannelSuccess 回调。

参数

token

在你的服务器上生成的用于鉴权的 Token。

信息

• （推荐）如果你的项目启用了安全模式（使用 App ID 和 Token 进行鉴权），该参数为必填。
• 如果你只启用了测试模式（使用 App ID 进行鉴权），该参数为可选。成功加入频道后，24 小时后会自动退出频道。
• 如果你需要同时加入多个频道或在频道间切换，声网建议使用通配符 Token，这样你每次加入频道时无需重新申请 Token。

channelId

频道名。在相同 App ID 的前提下，填写相同频道名的用户会进入同一个频道进行音视频互动。字符串长度必须小于 64 字节。支持的字符（共 89 个）：

• 所有小写英文字母：a 到 z。
• 所有大写英文字母：A 到 Z。
• 所有数字字符：0 到 9。
• "!", "#", "$", "%", "&", "(", ")", "+", "-", ":", ";", "<", "=", ".", ">", "?", "@", "[", "]", "^", "_", "{", "}", "|", "~", ","

uid

用户 ID。用于标识频道中的用户以进行实时音视频互动。你需要自行设置和管理用户 ID，并确保同一频道内的每个用户 ID 唯一。该参数为 32 位无符号整数，取值范围为 1 到 2^32-1。如果未指定用户 ID（或设置为 0），SDK 会自动分配一个随机用户 ID，并在 onJoinChannelSuccess 回调中返回。你的应用程序必须记录并维护返回的用户 ID。

options

频道媒体选项。详见 ChannelMediaOptions。

返回值

• 0：方法调用成功。
• < 0：方法调用失败。详见错误码了解详情和解决建议。
  • -2：参数无效。例如，Token 无效，uid 参数未设置为整数，或 ChannelMediaOptions 中的成员值无效。你需要传入有效参数并重新加入频道。
  • -3：IRtcEngine 对象初始化失败。你需要重新初始化 IRtcEngine 对象。
  • -7：IRtcEngine 对象尚未初始化。你需要先初始化 IRtcEngine 对象再调用该方法。
  • -8：IRtcEngine 对象的内部状态错误。典型原因是在调用 startEchoTest 开始通话回路测试后，未调用 stopEchoTest 停止测试就调用该方法加入频道。你需要先调用 stopEchoTest 再调用该方法。
  • -17：加入频道请求被拒绝。典型原因是用户已在频道中。声网建议你通过 onConnectionStateChanged 回调判断用户是否在频道中。只有在收到 CONNECTION_STATE_DISCONNECTED（1）状态时才调用该方法加入频道。
  • -102：频道名无效。你需要在 channelId 中传入有效的频道名重新加入频道。
  • -121：用户 ID 无效。你需要在 uid 中传入有效的用户 ID 重新加入频道。

所属接口类

• IRtcEngine

joinChannelEx

加入一个频道。

C++

virtual int joinChannelEx(const char* token, const RtcConnection& connection, const ChannelMediaOptions& options, IRtcEngineEventHandler* eventHandler) = 0;

你可以多次调用该方法加入多个频道。 在多摄像头采集场景中，调用该方法后需要调用 startPreview 方法，并将 sourceType 设置为 VIDEO_SOURCE_CAMERA_SECONDARY，以确保第二路摄像头正常采集。

信息

如果你已经在一个频道中，不能使用相同的用户 ID 重新加入该频道。 在加入频道前，请确保用于生成 Token 的 App ID 与调用 initialize 方法时传入的 App ID 相同，否则可能会导致使用该 Token 加入频道失败。

适用场景

该方法适用于多频道场景。

调用时机

请在调用 initialize 方法后调用该方法。

相关回调

成功调用该方法后，SDK 会触发以下回调：

• 本地客户端：onJoinChannelSuccess 和 onConnectionStateChanged 回调。
• 远端客户端：如果是 COMMUNICATION 频道场景中有用户加入频道，或 LIVE_BROADCASTING 频道场景中有主播加入频道，则触发 onUserJoined 回调。

当由于网络状况不佳导致本地客户端与声网服务器的连接中断时，SDK 会尝试重连服务器。当本地客户端成功重加入频道时，SDK 会触发本地客户端的 onRejoinChannelSuccess 回调。

参数

token

用于鉴权的 Token，由你的服务器生成。

信息

• （推荐）如果你的项目启用了安全模式（使用 App ID 和 Token 鉴权），该参数为必填。
• 如果你只启用了测试模式（使用 App ID 鉴权），该参数为可选。成功加入频道后，你将在 24 小时后自动退出频道。
• 如果你需要同时加入不同频道或在频道间切换，声网建议使用通配符 Token，这样你每次加入频道时无需重新申请 Token。详见 Secure authentication with tokens。

connection

连接信息，详见 RtcConnection。

options

频道媒体选项，详见 ChannelMediaOptions。

eventHandler

回调类，详见 IRtcEngineEventHandler。你可以通过该参数传入的 eventHandler 对象获取多个频道的回调事件。

返回值

• 0：方法调用成功。
• < 0：方法调用失败。详见错误码了解详情和解决建议。
  • -2：参数无效。例如，Token 无效，uid 参数未设置为整数，或 ChannelMediaOptions 中的成员值无效。你需要传入有效参数并重新加入频道。
  • -3：IRtcEngine 对象初始化失败。你需要重新初始化 IRtcEngine 对象。
  • -7：IRtcEngine 对象尚未初始化。你需要先初始化 IRtcEngine 对象再调用该方法。
  • -8：IRtcEngine 对象的内部状态错误。典型原因是在调用 startEchoTest 开始通话回路测试后，未调用 stopEchoTest 停止测试就调用该方法加入频道。你需要先调用 stopEchoTest 再调用该方法。
  • -17：加入频道请求被拒绝。典型原因是用户已在频道中。声网建议你通过 onConnectionStateChanged 回调判断用户是否在频道中。只有在收到 CONNECTION_STATE_DISCONNECTED（1）状态时才调用该方法加入频道。
  • -102：频道名无效。你需要在 channelId 中传入有效的频道名以重新加入频道。
  • -121：用户 ID 无效。你需要在 uid 中传入有效的用户 ID 以重新加入频道。

所属接口类

• IRtcEngineEx

joinChannelWithUserAccount [1/2]

使用用户 User Account 和 Token 加入频道。

C++

virtual int joinChannelWithUserAccount(const char* token, const char* channelId, const char* userAccount) = 0;

在调用该方法之前，如果你尚未调用 registerLocalUserAccount 注册用户 User Account，SDK 会在你调用该方法加入频道时自动为你创建一个用户 User Account。建议你先调用 registerLocalUserAccount 注册用户 User Account，再调用该方法加入频道，以缩短加入频道所需的时间。 用户加入频道后，默认会订阅频道中所有其他用户的音视频流，从而产生用量和计费。如需停止订阅指定流或所有远端流，请调用 setRemoteAudio/VideoStream 或 setAllRemoteAudio/VideoStreams。

信息

• 该方法仅支持用户同时加入一个频道。
• 不同 App ID 的用户无法互通。
• 加入频道前，请确保用于生成 Token 的 App ID 与调用 initialize 方法时传入的 App ID 相同，否则可能导致加入频道失败。
• 为确保通信顺畅，请使用相同的参数类型标识用户。例如，如果某用户使用用户 ID 加入频道，则其他用户也应使用用户 ID；使用用户 User Account 加入频道的用户也应保持一致。如果用户使用声网 Web SDK 加入频道，请确保该用户的 ID 类型一致。

调用时机

在调用 initialize 之后调用该方法。

相关回调

成功调用该方法后，SDK 会触发以下回调：

• 本地客户端：onLocalUserRegistered、onJoinChannelSuccess 和 onConnectionStateChanged 回调。
• 远端客户端：如果用户在 COMMUNICATION 频道场景中加入频道，或主播在 LIVE_BROADCASTING 频道场景中加入频道，则会触发 onUserJoined 和 onUserInfoUpdated 回调。

参数

token

在你的服务器上生成的用于鉴权的 Token。

信息

• （推荐）如果你的项目启用了安全模式（使用 App ID 和 Token 进行鉴权），该参数为必填。
• 如果你仅启用了测试模式（使用 App ID 进行鉴权），该参数为可选。成功加入频道后，你将在 24 小时后自动退出频道。
• 如果你需要同时加入多个频道或在频道间切换，声网建议使用通配符 Token，这样你每次加入频道时无需重新申请 Token。

channelId

频道名。在相同 App ID 的前提下，填写相同频道名的用户会进入同一个频道进行音视频互动。字符串长度必须小于 64 字节。支持的字符（共 89 个）：

• 所有小写英文字母：a 到 z。
• 所有大写英文字母：A 到 Z。
• 所有数字字符：0 到 9。
• "!", "#", "$", "%", "&", "(", ")", "+", "-", ":", ";", "<", "=", ".", ">", "?", "@", "[", "]", "^", "_", "{", "}", "|", "~", ","

userAccount

用户 User Account。你需要自行设置和管理用户 User Account，并确保同一频道中的每个用户 User Account 唯一。该参数的最大长度为 255 字节，不能为空。支持的字符如下（共 89 个）：

• 26 个小写英文字母：a 到 z。
• 26 个大写英文字母：A 到 Z。
• 所有数字字符：0 到 9。
• 空格
• "!", "#", "$", "%", "&", "(", ")", "+", "-", ":", ";", "<", "=", ".", ">", "?", "@", "[", "]", "^", "_", "{", "}", "|", "~", ","

返回值

• 0：方法调用成功。
• < 0：方法调用失败。详见错误码了解详情和解决建议。
  • -2：参数无效。例如，Token 无效，uid 参数未设置为整数，或 ChannelMediaOptions 中某成员的值无效。请传入有效参数并重新加入频道。
  • -3：IRtcEngine 对象初始化失败。请重新初始化 IRtcEngine 对象。
  • -7：IRtcEngine 对象尚未初始化。请先初始化 IRtcEngine 对象再调用该方法。
  • -8：IRtcEngine 对象内部状态错误。典型原因是在调用 startEchoTest 开始通话回声测试后，未调用 stopEchoTest 停止测试就调用该方法加入频道。请先调用 stopEchoTest 再调用该方法。
  • -17：加入频道请求被拒绝。典型原因是用户已在频道中。声网建议你通过 onConnectionStateChanged 回调判断用户是否在频道中，仅在收到 CONNECTION_STATE_DISCONNECTED（1）状态时再调用该方法。
  • -102：频道名无效。请在 channelId 中传入有效的频道名重新加入频道。
  • -121：用户 ID 无效。请在 uid 中传入有效的用户 ID 重新加入频道。

所属接口类

• IRtcEngine

joinChannelWithUserAccount [2/2]

使用用户 User Account 和 Token 加入频道，并设置媒体选项。

C++

virtual int joinChannelWithUserAccount(const char* token, const char* channelId, const char* userAccount, const ChannelMediaOptions& options) = 0;

在调用该方法前，如果你尚未调用 registerLocalUserAccount 注册用户 User Account，SDK 会在你调用该方法加入频道时自动创建一个用户 User Account。提前调用 registerLocalUserAccount 可以缩短加入频道所需的时间。 与 joinChannelWithUserAccount 方法相比，该方法新增了 options 参数，用于设置频道内的媒体选项，例如是否发布音视频流。 默认情况下，用户会订阅频道内所有其他用户的音视频流，从而产生使用量和计费。若要停止订阅其他流，请设置 options 参数或调用 muteRemoteAudio/VideoStream 或 muteAllRemoteAudio/VideoStreams。

信息

该方法仅支持用户同时加入一个频道。 不同 App ID 的用户无法互通。 加入频道前，请确保用于生成 Token 的 App ID 与调用 initialize 方法时传入的 App ID 相同，否则可能导致加入频道失败。 为确保通信顺畅，请使用相同的参数类型标识用户。例如，如果某用户使用用户 ID 加入频道，则其他用户也应使用用户 ID；使用用户账号加入频道时同理。如果用户使用声网 Web SDK 加入频道，请确保用户 ID 的参数类型一致。

调用时机

请在调用 initialize 方法后调用该方法。

相关回调

成功调用该方法后，SDK 会触发以下回调：

• 本地客户端：onLocalUserRegistered、onJoinChannelSuccess 和 onConnectionStateChanged 回调。
• 远端客户端：如果用户在 COMMUNICATION 频道场景中加入频道，或主播在 LIVE_BROADCASTING 频道场景中加入频道，则会触发 onUserJoined 和 onUserInfoUpdated 回调。

参数

token

在你的服务器上生成的用于鉴权的 Token。

信息

• （推荐）如果你的项目启用了安全模式（使用 App ID 和 Token 进行鉴权），该参数为必填。
• 如果你只启用了测试模式（使用 App ID 进行鉴权），该参数为可选。成功加入频道后，你将在 24 小时后自动退出频道。
• 如果你需要同时加入多个频道或在频道间切换，声网建议使用通配符 Token，这样你每次加入频道时无需重新申请 Token。

channelId

频道名。该参数表示用户进行实时音视频互动的频道。在相同 App ID 的前提下，填写相同频道名的用户会进入同一个频道进行音视频互动。字符串长度必须小于 64 字节。支持的字符（共 89 个）：

• 所有小写英文字母：a 到 z。
• 所有大写英文字母：A 到 Z。
• 所有数字字符：0 到 9。
• "!", "#", "$", "%", "&", "(", ")", "+", "-", ":", ";", "<", "=", ".", ">", "?", "@", "[", "]", "^", "_", "{", "}", "|", "~", ","。

userAccount

用户 User Account。用于标识频道中的用户以进行实时音视频互动。你需要自行设置和管理用户 User Account，并确保同一频道中的每个用户 User Account 唯一。该参数的最大长度为 255 字节，不能为空。支持的字符如下（共 89 个）：

• 26 个小写英文字母：a 到 z。
• 26 个大写英文字母：A 到 Z。
• 所有数字字符：0 到 9。
• 空格
• "!", "#", "$", "%", "&", "(", ")", "+", "-", ":", ";", "<", "=", ".", ">", "?", "@", "[", "]", "^", "_", "{", "}", "|", "~", ","。

options

频道媒体选项。详见 ChannelMediaOptions。

返回值

• 0：方法调用成功。
• < 0：方法调用失败。详见错误码了解详情和解决建议。
  • -2：参数无效。例如，Token 无效，uid 参数未设置为整数，或 ChannelMediaOptions 中某成员的值无效。你需要传入有效参数并重新加入频道。
  • -3：IRtcEngine 对象初始化失败。你需要重新初始化 IRtcEngine 对象。
  • -7：IRtcEngine 对象尚未初始化。你需要先初始化 IRtcEngine 对象再调用该方法。
  • -8：IRtcEngine 对象的内部状态错误。典型原因是在调用 startEchoTest 开始通话回路测试后，未调用 stopEchoTest 停止测试就调用该方法加入频道。你需要先调用 stopEchoTest 再调用该方法。
  • -17：加入频道请求被拒绝。典型原因是用户已在频道中。声网建议你使用 onConnectionStateChanged 回调查看用户是否在频道中。只有在收到 CONNECTION_STATE_DISCONNECTED（1）状态时才调用该方法加入频道。
  • -102：频道名无效。你需要在 channelId 中传入有效的频道名以重新加入频道。
  • -121：用户 ID 无效。你需要在 uid 中传入有效的用户 ID 以重新加入频道。

所属接口类

• IRtcEngine

joinChannelWithUserAccountEx

使用用户 User Account 和 Token 加入频道，并设置媒体选项。

C++

virtual int joinChannelWithUserAccountEx(const char* token, const char* channelId, const char* userAccount, const ChannelMediaOptions& options, IRtcEngineEventHandler* eventHandler) = 0;

在调用该方法之前，如果你尚未调用 registerLocalUserAccount 注册用户 User Account，SDK 会在你调用该方法加入频道时自动为你创建一个用户 User Account。提前调用 registerLocalUserAccount 注册用户 User Account 再加入频道，可以缩短加入频道所需的时间。 用户加入频道后，默认会订阅频道中所有其他用户的音视频流，从而产生使用量和计费。如果你希望停止订阅其他用户的媒体流，可以设置 options 参数或调用 muteRemoteAudio/VideoStream 或 muteAllRemoteAudio/VideoStreams。

信息

• 该方法仅支持用户同时加入一个频道。
• 不同 App ID 的用户无法互通。
• 加入频道前，请确保用于生成 Token 的 App ID 与调用 initialize 方法时传入的 App ID 相同，否则可能会导致使用该 Token 加入频道失败。
• 为确保通信顺畅，请使用相同的参数类型标识用户。例如，如果某用户使用 UID 加入频道，则其他用户也应使用 UID；如果使用用户 User Account 加入频道，则其他用户也应使用用户 User Account。如果用户使用声网 Web SDK 加入频道，请确保用户 ID 的参数类型一致。

适用场景

该方法适用于多频道场景。

调用时机

请在调用 initialize 之后调用该方法。

相关回调

成功调用该方法后，SDK 会触发以下回调：

• 本地客户端：onLocalUserRegistered、onJoinChannelSuccess 和 onConnectionStateChanged 回调。
• 远端客户端：如果用户在 COMMUNICATION 频道场景中加入频道，或在 LIVE_BROADCASTING 频道场景中作为主播加入频道，则会触发 onUserJoined 和 onUserInfoUpdated 回调。

参数

token

在你的服务器上生成的用于鉴权的 Token。

信息

• （推荐）如果你的项目启用了安全模式（使用 App ID 和 Token 进行鉴权），该参数为必填。
• 如果你仅启用了测试模式（使用 App ID 进行鉴权），该参数为可选。成功加入频道后，你将在 24 小时后自动退出频道。
• 如果你需要同时加入多个频道或在频道间切换，声网建议使用通配符 Token，这样你每次加入频道时无需重新申请 Token。

channelId

频道名。在相同 App ID 下，填写相同频道名的用户会进入同一个频道。字符串长度必须小于 64 字节。支持的字符（共 89 个）：

• 所有小写英文字母：a 到 z。
• 所有大写英文字母：A 到 Z。
• 所有数字字符：0 到 9。
• "!", "#", "$", "%", "&", "(", ")", "+", "-", ":", ";", "<", "=", ".", ">", "?", "@", "[", "]", "^", "_", "{", "}", "|", "~", ","

userAccount

用户 User Account。用于标识频道中的用户。你需要自行设置并管理用户 User Account，确保同一频道中每个用户 User Account 唯一。最大长度为 255 字节，不能为空。支持的字符如下（共 89 个）：

• 26 个小写英文字母：a 到 z。
• 26 个大写英文字母：A 到 Z。
• 所有数字字符：0 到 9。
• 空格
• "!", "#", "$", "%", "&", "(", ")", "+", "-", ":", ";", "<", "=", ".", ">", "?", "@", "[", "]", "^", "_", "{", "}", "|", "~", ","

options

频道媒体选项。详见 ChannelMediaOptions。

eventHandler

回调类。详见 IRtcEngineEventHandler。你可以通过该参数传入的 eventHandler 对象获取多个频道的回调事件。

返回值

• 0：方法调用成功。
• < 0：方法调用失败。详见错误码了解详情和解决建议。
  • -2：参数无效。例如，Token 无效，uid 参数未设置为整数，或 ChannelMediaOptions 中的成员值无效。你需要传入有效参数并重新加入频道。
  • -3：IRtcEngine 对象初始化失败。你需要重新初始化 IRtcEngine 对象。
  • -7：IRtcEngine 对象尚未初始化。你需要先初始化 IRtcEngine 对象再调用该方法。
  • -8：IRtcEngine 对象内部状态错误。典型原因是在调用 startEchoTest 开始通话回路测试后，未调用 stopEchoTest 停止测试就调用该方法加入频道。你需要先调用 stopEchoTest 再调用该方法。
  • -17：加入频道请求被拒绝。典型原因是用户已在频道中。声网建议你通过 onConnectionStateChanged 回调判断用户是否在频道中。只有在收到 CONNECTION_STATE_DISCONNECTED（1）状态时才调用该方法加入频道。
  • -102：频道名无效。你需要在 channelId 中传入有效的频道名重新加入频道。
  • -121：用户 ID 无效。你需要在 uid 中传入有效的用户 ID 重新加入频道。

所属接口类

• IRtcEngine

leaveChannel [1/2]

离开频道。

C++

virtual int leaveChannel() = 0;

调用该方法后，SDK 会终止音视频互动，离开当前频道，并释放与会话相关的所有资源。加入频道后，必须调用该方法结束通话，否则无法开始下一次通话。

信息

• 如果在调用该方法后立即调用 release，SDK 不会触发 onLeaveChannel 回调。
• 此方法为异步调用。方法返回时，并不代表用户已完全离开频道。
• 如果你通过 joinChannelEx 加入了多个频道，调用该方法会离开你加入的所有频道。

调用时机

在加入频道后调用该方法。

相关回调

成功调用该方法后，SDK 会触发以下回调：

• 本地客户端：触发 onLeaveChannel 回调。
• 远端客户端：远端主播离开频道后触发 onUserOffline 回调。

返回值

• 0：方法调用成功。
• < 0：方法调用失败。详见错误码了解详情和解决建议。
  • -1：发生通用错误（无明确原因）。
  • -2：参数无效。
  • -7：SDK 未初始化。

所属接口类

• IRtcEngine

leaveChannel [2/2]

设置频道选项并离开频道。

C++

virtual int leaveChannel(const LeaveChannelOptions& options) = 0;

调用该方法后，SDK 会终止音视频互动，离开当前频道，并释放与会话相关的所有资源。如果你调用了 joinChannelEx 加入了多个频道，调用该方法会离开你加入的所有频道。

信息

如果在调用该方法后立即调用 release，SDK 不会触发 onLeaveChannel 回调。该方法为异步调用。当该方法返回时，并不意味着用户已经离开频道。

调用时机

在加入频道后调用该方法。

相关回调

成功调用该方法后，SDK 会触发以下回调：

• 本地客户端：触发 onLeaveChannel 回调。
• 远端客户端：远端主播离开频道后触发 onUserOffline 回调。

参数

options

离开频道的选项。详见 LeaveChannelOptions。

返回值

• 0：方法调用成功。
• < 0：方法调用失败。详见错误码了解详情和解决建议。

所属接口类

• IRtcEngine

leaveChannelEx [1/2]

离开频道。

C++

virtual int leaveChannelEx(const RtcConnection& connection) = 0;

调用该方法后，SDK 会终止音视频互动，离开当前频道，并释放与会话相关的所有资源。调用 joinChannelEx 加入频道后，必须调用此方法或 leaveChannelEx 结束通话，否则无法开始下一次通话。

• 如果在调用该方法后立即调用 release，SDK 不会触发 onLeaveChannel 回调。
• 此方法为异步调用，方法返回时并不代表用户已完全离开频道。
• 如果调用 leaveChannel，你将离开通过 joinChannel 或 joinChannelEx 加入的所有频道。

适用场景

该方法适用于多频道场景。

调用时机

该方法需要在调用 joinChannelEx 之后调用。

相关回调

成功调用该方法后，SDK 会触发以下回调：

• 本地客户端：触发 onLeaveChannel 回调。
• 远端客户端：远端用户离开频道后触发 onUserOffline 回调。

参数

connection

连接信息。详见 RtcConnection。

返回值

• 0：方法调用成功。
• < 0：方法调用失败。详见错误码了解详情和解决建议。

所属接口类

• IRtcEngineEx

leaveChannelEx [2/2]

设置频道选项并离开频道。

C++

virtual int leaveChannelEx(const RtcConnection& connection, const LeaveChannelOptions& options) = 0;

自从

自 v4.1.0 版本新增。

调用该方法后，SDK 会终止音视频互动，离开当前频道，并释放与会话相关的所有资源。调用 joinChannelEx 加入频道后，必须调用该方法或 leaveChannelEx 结束通话，否则无法开始下一次通话。

信息

• 如果在调用该方法后立即调用 release，SDK 不会触发 onLeaveChannel 回调。
• 该方法为异步调用，方法返回时并不代表用户已离开频道。
• 如果调用 leaveChannel [1/2] 或 leaveChannel [2/2]，你将离开通过 joinChannel [1/2]、joinChannel [2/2] 或 joinChannelEx 加入的所有频道。

适用场景

该方法适用于多频道场景。

调用时机

该方法需要在调用 joinChannelEx 后调用。

相关回调

成功调用该方法后，SDK 会触发以下回调：

• 本地客户端：触发 onLeaveChannel 回调。
• 远端客户端：远端主播离开频道后触发 onUserOffline 回调。

参数

connection

连接信息。详见 RtcConnection。

options

离开频道的选项。详见 LeaveChannelOptions。

信息

该参数仅支持设置 LeaveChannelOptions 中的 stopMicrophoneRecording 成员，设置其他成员无效。

返回值

• 0：方法调用成功。
• < 0：方法调用失败。详见错误码了解详情和解决建议。

所属接口类

• IRtcEngineEx

preloadChannel

预加载指定频道以缩短观众加入频道的时间。

C++

virtual int preloadChannel(const char* token, const char* channelId, uid_t uid) = 0;

当观众需要频繁切换不同频道时，调用该方法可以缩短加入频道的时间，从而减少观众听到和看到主播的延迟时间。如果你加入了一个已预加载的频道，离开后又想重新加入该频道，除非用于预加载频道的 Token 过期，否则无需再次调用该方法。

信息

• 调用该方法时，请确保将用户角色设置为观众，且未将音频场景设置为 AUDIO_SCENARIO_CHORUS，否则该方法不生效。
• 请确保用于预加载的频道名、用户 ID 和 Token 与加入频道时传入的值一致，否则该方法不生效。
• 一个 IRtcEngine 实例最多支持预加载 20 个频道。超过该限制时，仅最新的 20 个预加载频道生效。
• 预加载频道失败不会影响加入频道的能力，也不会增加加入频道所需的时间。

调用时机

为提升预加载频道的用户体验，声网建议在确认频道名和用户信息后尽早调用该方法。

参数

token

用于鉴权的 Token，由你的服务器生成。Token 过期后，你可以根据预加载频道的数量更新 Token：

• 预加载一个频道时，调用该方法传入新的 Token。
• 预加载多个频道时：
  • 如果你为所有预加载频道使用通配符 Token，调用 updatePreloadChannelToken 更新 Token。生成通配符 Token 时，确保用户 ID 不为 0。
  • 如果你为不同频道使用不同的 Token，调用该方法传入你的用户 ID、频道名和新的 Token。

channelId

你想要预加载的频道名。该参数表示用户进行实时音视频互动的频道。在相同 App ID 下，填写相同频道名的用户会进入同一个频道。频道名长度必须小于 64 字节。支持的字符（共 89 个）：

• 所有小写英文字母：a 到 z。
• 所有大写英文字母：A 到 Z。
• 所有数字字符：0 到 9。
• "!", "#", "$", "%", "&", "(", ")", "+", "-", ":", ";", "<", "=", ".", ">", "?", "@", "[", "]", "^", "_", "{", "}", "|", "~", ","。

uid

用户 ID，用于标识频道中的用户以进行实时音视频互动。你需要自行设置和管理用户 ID，并确保同一频道中的每个用户 ID 唯一。该参数为 32 位无符号整数，取值范围为 1 到 2^32 - 1。如果未指定用户 ID（或设置为 0），SDK 会分配一个随机用户 ID，并在 onJoinChannelSuccess 回调中返回。你的应用必须记录并维护返回的用户 ID，SDK 不会保存。

返回值

• 0：方法调用成功。
• < 0：方法调用失败。详见错误码了解详情和解决建议。
  • -7：IRtcEngine 对象尚未初始化。请先初始化 IRtcEngine 对象后再调用该方法。
  • -102：频道名无效。请传入有效的频道名并重新加入频道。

所属接口类

• IRtcEngine

preloadChannelWithUserAccount

预加载指定的频道。

C++

virtual int preloadChannelWithUserAccount(const char* token, const char* channelId, const char* userAccount) = 0;

当观众用户需要频繁切换不同频道时，调用该方法可以缩短加入频道的时间，从而减少观众听到和看到主播的延迟时间。如果你加入了一个已预加载的频道，离开后想重新加入该频道，除非用于预加载频道的 Token 过期，否则无需再次调用该方法。

信息

• 调用该方法时，请确保将用户角色设置为观众，且未将音频场景设置为 AUDIO_SCENARIO_CHORUS，否则该方法不生效。
• 你还需要确保用于预加载的用户 User Account、频道名和 Token 与加入频道时传入的值一致，否则该方法不生效。
• 一个 IRtcEngine 实例最多支持预加载 20 个频道。超过该限制时，仅最新的 20 个预加载频道生效。
• 预加载频道失败不会影响加入频道的功能，也不会增加加入频道所需的时间。

调用时机

为提升预加载频道的用户体验，声网建议在确认频道名和用户信息后尽早调用该方法。

参数

token

你在服务器上生成的用于鉴权的 Token。Token 过期后，你可以根据预加载的频道数量更新 Token：

• 预加载一个频道时，调用该方法传入新的 Token。
• 预加载多个频道时：
  • 如果你为所有预加载频道使用通配符 Token，调用 updatePreloadChannelToken 更新 Token。注意：生成通配符 Token 时，确保用户 ID 不为 0。
  • 如果你为不同频道使用不同的 Token，调用该方法传入用户 ID、频道名和新的 Token。

channelId

你想要预加载的频道名。在相同 App ID 下，填写相同频道名的用户会进入同一个频道。频道名长度必须小于 64 字节，支持的字符（共 89 个）：

• 所有小写英文字母：a 到 z。
• 所有大写英文字母：A 到 Z。
• 所有数字字符：0 到 9。
• "!", "#", "$", "%", "&", "(", ")", "+", "-", ":", ";", "<", "=", ".", ">", "?", "@", "[", "]", "^", "_", "{", "}", "|", "~", ","。

userAccount

用户 User Account。你需要自行设置和管理用户 User Account，并确保同一频道中的每个用户 User Account 唯一。该参数最大长度为 255 字节，不能为空。支持的字符如下（共 89 个）：

• 26 个小写英文字母：a 到 z。
• 26 个大写英文字母：A 到 Z。
• 所有数字字符：0 到 9。
• 空格
• "!", "#", "$", "%", "&", "(", ")", "+", "-", ":", ";", "<", "=", ".", ">", "?", "@", "[", "]", "^", "_", "{", "}", "|", "~", ","。

返回值

• 0：方法调用成功。
• < 0：方法调用失败。详见错误码了解详情和解决建议。
  • -2：参数无效，例如用户 User Account 为空。请传入有效参数后重新加入频道。
  • -7：IRtcEngine 对象尚未初始化。请先初始化 IRtcEngine 对象后再调用该方法。
  • -102：频道名无效。请传入有效的频道名后重新加入频道。

所属接口类

• IRtcEngine

registerLocalUserAccount

注册用户 User Account。

C++

virtual int registerLocalUserAccount(const char* appId, const char* userAccount) = 0;

该方法用于注册用户 User Account。注册成功后，用户 User Account 可用于在加入频道时标识本地用户身份。你可以选择以下任一方式使用用户 User Account 加入频道：

• 先调用 registerLocalUserAccount 注册用户 User Account，再调用 joinChannelWithUserAccount 加入频道，可缩短进入频道的时间。
• 直接调用 joinChannelWithUserAccount 加入频道。

从 v4.6.0 版本开始，SDK 不再自动将 int 类型的用户 ID 映射为注册用户 User Account 时使用的 string 类型 userAccount。如果你希望使用注册时的原始 string 类型 userAccount 加入频道，请调用 joinChannelWithUserAccount，而不是调用 joinChannel 并传入通过该方法获取的 int 类型用户 ID。确保 userAccount 在频道内唯一。为确保通信顺畅，建议使用相同的参数类型标识用户。例如，如果某用户使用用户 ID 加入频道，则其他用户也应使用用户 ID；同理，如果使用用户 User Account 加入频道，则其他用户也应使用用户 User Account。如果用户使用声网 Web SDK 加入频道，确保用户 ID 设置为相同的参数类型。

相关回调

成功调用该方法后，SDK 会触发 onLocalUserRegistered 回调，报告本地用户的用户 ID 和用户 User Account。

参数

appId

声网控制台中项目的 App ID。

userAccount

用户 User Account。用于在频道中标识用户身份以实现实时音视频互动。你需要自行设置并管理用户 User Account，并确保同一频道内的每个用户 User Account 唯一。该参数的最大长度为 255 字节，不能为空。支持的字符共 89 个，包括：

• 26 个小写英文字母：a 到 z。
• 26 个大写英文字母：A 到 Z。
• 所有数字字符：0 到 9。
• 空格
• "!", "#", "$", "%", "&", "(", ")", "+", "-", ":", ";", "<", "=", ".", ">", "?", "@", "[", "]", "^", "_", "{", "}", "|", "~", ","

返回值

• 0：方法调用成功。
• < 0：方法调用失败。详见错误码了解详情和解决建议。

所属接口类

• IRtcEngine

renewToken

更新 Token。

C++

virtual int renewToken(const char* token) = 0;

成功调用该方法后，SDK 会触发 onRenewTokenResult 回调。Token 在一段时间后会过期，届时 SDK 将无法与服务器建立连接。声网建议你在以下任一情况下，在你的服务器上生成新的 Token，并调用该方法进行更新：

• 收到 onTokenPrivilegeWillExpire 回调，提示 Token 即将过期。
• 收到 onRequestToken 回调，提示 Token 已过期。
• 收到 onConnectionStateChanged 回调，报告 CONNECTION_CHANGED_TOKEN_EXPIRED（9）。

参数

token

新的 Token。

返回值

• 0：方法调用成功。
• < 0：方法调用失败。详见错误码了解详情和解决建议。
  • -2：参数无效，例如传入的 Token 为空。
  • -7：IRtcEngine 对象尚未初始化。请先初始化 IRtcEngine 对象再调用该方法。
  • 110：Token 无效。请确保以下两点：
    • 生成 Token 时指定的用户 ID 与加入频道时使用的用户 ID 一致。
    • 生成的 Token 与加入频道时传入的 Token 相同。

所属接口类

• IRtcEngine

setChannelProfile

设置频道场景。

C++

virtual int setChannelProfile(CHANNEL_PROFILE_TYPE profile) = 0;

SDK 会根据不同的频道场景采用不同的优化策略。例如，在极速直播场景中，SDK 会优先保证视频质量。初始化 SDK 后，默认频道场景为极速直播。

信息

为保证实时通信质量，声网建议频道内所有用户使用相同的频道场景。在不同的频道场景中，SDK 的默认音频路由也不同。详见 setDefaultAudioRouteToSpeakerphone。

调用时机

请在加入频道前调用此方法。

参数

profile

频道场景。详见 CHANNEL_PROFILE_TYPE。

返回值

• 0：方法调用成功。
• < 0：方法调用失败。详见错误码了解详情和解决建议。
  • -2：参数无效。
  • -7：SDK 未初始化。

所属接口类

• IRtcEngine

setClientRole [1/2]

设置用户角色。

C++

virtual int setClientRole(CLIENT_ROLE_TYPE role) = 0;

• 默认情况下，SDK 会将用户角色设置为观众。你可以调用该方法将用户角色设置为主播。用户角色（role）决定了用户在 SDK 层的权限，包括是否可以在频道中发布音视频流。

• 如果你在加入频道前调用该方法将用户角色设置为主播，并通过 setupLocalVideo 设置本地视频属性，则用户加入频道时会自动开启本地视频预览。

• 如果你在加入频道后调用该方法设置用户角色，SDK 会自动调用 muteLocalAudioStream 和 muteLocalVideoStream 方法来更新音视频流的发布状态。

信息

在加入频道前调用该方法并将用户角色设置为 BROADCASTER 时，本地客户端不会触发 onClientRoleChanged 回调；但如果将 role 设置为 AUDIENCE，则会触发该回调。

调用时机

你可以在加入频道前或加入频道后调用该方法。

相关回调

如果你在加入频道后调用该方法切换用户角色，SDK 会触发以下回调：

• 本地客户端触发 onClientRoleChanged 回调。注意：在加入频道前调用该方法并将 role 设置为 AUDIENCE 也会触发该回调。
• 远端客户端触发 onUserJoined 或 onUserOffline 回调。

如果你在加入频道后调用该方法设置用户角色失败，SDK 会触发 onClientRoleChangeFailed 回调，报告失败原因和当前用户角色。

参数

role

用户角色，详见 CLIENT_ROLE_TYPE。

信息

如果你将用户角色设置为观众，则无法在频道中发布音视频流。若希望在直播过程中发布媒体流，请确保将用户角色设置为主播。

返回值

• 0：方法调用成功。
• < 0：方法调用失败。详见错误码了解详情和解决建议。
  • -1：发生通用错误（无明确原因）。
  • -2：参数无效。
  • -7：SDK 未初始化。

所属接口类

• IRtcEngine

setClientRole [2/2]

设置用户角色和观众延迟等级。

C++

virtual int setClientRole(CLIENT_ROLE_TYPE role, const ClientRoleOptions& options) = 0;

该方法用于设置用户角色以及观众延迟等级。你可以调用该方法将用户角色设置为主播。用户角色 role 决定了用户在 SDK 层的权限，例如是否可以在频道中发布音视频流。 该方法与 setClientRole 的区别在于，它支持设置 audienceLatencyLevel。你需要将 audienceLatencyLevel 与 role 搭配使用，以决定用户在其权限范围内可享受的服务等级。例如，观众可以选择接收低延迟或超低延迟的远端流。

• 如果你在加入频道前调用该方法将用户角色设置为主播，并通过 setupLocalVideo 设置本地视频属性，则用户加入频道时会自动开启本地视频预览。
• 如果你在加入频道后调用该方法设置用户角色，SDK 会自动调用 muteLocalAudioStream 和 muteLocalVideoStream 方法来改变音视频流的发布状态。

信息

当用户角色设置为主播时，观众延迟等级只能设置为 AUDIENCE_LATENCY_LEVEL_ULTRA_LOW_LATENCY。 在加入频道前调用该方法并将 role 设置为 BROADCASTER 时，本地客户端不会触发 onClientRoleChanged 回调。 在加入频道前调用该方法并将 role 设置为 AUDIENCE 时，会触发该回调。

调用时机

你可以在加入频道前或加入频道后调用此方法。

相关回调

如果你在加入频道后调用此方法切换用户角色，SDK 会触发以下回调：

• 本地客户端触发 onClientRoleChanged 回调。注意：在加入频道前调用此方法并将 role 设置为 AUDIENCE 也会触发该回调。
• 远端客户端触发 onUserJoined 或 onUserOffline 回调。

如果你在加入频道后调用此方法设置用户角色但失败，SDK 会触发 onClientRoleChangeFailed 回调，报告失败原因和当前用户角色。

参数

role

用户角色，详见 CLIENT_ROLE_TYPE。

信息

如果你将用户角色设置为观众，则无法在频道中发布音视频流。如果你希望在直播中发布媒体流，请确保将用户角色设置为主播。

options

用户的详细选项，详见 ClientRoleOptions。

返回值

• 0：方法调用成功。
• < 0：方法调用失败。详见错误码了解详情和解决建议。
  • -1：发生通用错误（无明确原因）。
  • -2：参数无效。
  • -5：请求被拒绝。
  • -7：SDK 未初始化。

所属接口类

• IRtcEngine

updateChannelMediaOptions

在加入频道后更新频道的媒体选项。

C++

virtual int updateChannelMediaOptions(const ChannelMediaOptions& options) = 0;

参数

options

频道媒体选项。详见 ChannelMediaOptions。

返回值

• 0：方法调用成功。
• < 0：方法调用失败。详见错误码了解详情和解决建议。
  • -2：ChannelMediaOptions 中某个成员的值无效，例如 token 或用户 ID 无效。你需要填写有效的参数。
  • -7：IRtcEngine 对象尚未初始化。你需要先初始化 IRtcEngine 对象再调用该方法。
  • -8：IRtcEngine 对象的内部状态错误，可能是用户尚未加入频道。建议你通过 onConnectionStateChanged 回调判断用户是否在频道中。如果你收到 CONNECTION_STATE_DISCONNECTED（1）或 CONNECTION_STATE_FAILED（5）状态，说明用户不在频道中。你需要先调用 joinChannel 加入频道，再调用该方法。

所属接口类

• IRtcEngine

updateChannelMediaOptionsEx

在加入频道后更新频道媒体选项。

C++

virtual int updateChannelMediaOptionsEx(const ChannelMediaOptions& options, const RtcConnection& connection) = 0;

适用场景

该方法适用于多频道场景。

参数

options

频道媒体选项。详见 ChannelMediaOptions。

connection

连接信息。详见 RtcConnection。

返回值

• 0：方法调用成功。
• < 0：方法调用失败。详见错误码了解详情和解决建议。
  • -2：ChannelMediaOptions 中的成员值无效，例如 token 或用户 ID 无效。你需要填写有效的参数。
  • -7：IRtcEngine 对象尚未初始化。你需要先初始化 IRtcEngine 对象再调用该方法。
  • -8：IRtcEngine 对象的内部状态错误，可能的原因是用户未加入频道。声网建议你通过 onConnectionStateChanged 回调判断用户是否在频道中。如果你收到 CONNECTION_STATE_DISCONNECTED（1）或 CONNECTION_STATE_FAILED（5）状态，说明用户不在频道中。你需要先调用 joinChannel 加入频道，再调用该方法。

所属接口类

• IRtcEngineEx

updatePreloadChannelToken

更新预加载频道使用的通配 Token。

C++

virtual int updatePreloadChannelToken(const char* token) = 0;

你需要自行维护通配 Token 的生命周期。当该 Token 过期时，需要生成新的通配 Token，并调用该方法传入新 Token。

适用场景

适用于涉及多个频道的场景，例如在不同频道之间切换时，使用通配 Token 可以避免用户每次加入新频道时都申请新的 Token，从而节省切换频道的时间，并减轻你的 Token 服务器的压力。

参数

token

新的通配 Token。

返回值

• 0：方法调用成功。
• < 0：方法调用失败。详见错误码了解详情和解决建议。
  • -2：参数无效，例如传入的 Token 无效。请传入有效参数并重新加入频道。
  • -7：IRtcEngine 对象尚未初始化。请先初始化 IRtcEngine 对象后再调用该方法。

所属接口类

• IRtcEngine

onClientRoleChanged

用户角色或观众延迟等级发生变化时触发的回调。

C++

virtual void onClientRoleChanged(CLIENT_ROLE_TYPE oldRole, CLIENT_ROLE_TYPE newRole, const ClientRoleOptions& newRoleOptions)

信息

当你在加入频道前调用 setClientRole 并将用户角色设置为 BROADCASTER 时，该回调不会被触发。

触发时机

在以下任一情况下会触发该回调：

• 在加入频道后调用 setClientRole 设置用户角色或观众延迟等级；
• 在加入频道前调用 setClientRole 并将用户角色设置为 AUDIENCE。

参数

oldRole

用户切换前的角色。详见 CLIENT_ROLE_TYPE。

newRole

用户切换后的角色。详见 CLIENT_ROLE_TYPE。

newRoleOptions

用户切换后的角色属性。详见 ClientRoleOptions。

信息

自 v4.1.0 起引入。

所属接口类

• IRtcEngineEventHandler

onClientRoleChangeFailed

切换用户角色失败时触发的回调。

C++

virtual void onClientRoleChangeFailed(CLIENT_ROLE_CHANGE_FAILED_REASON reason, CLIENT_ROLE_TYPE currentRole)

该回调用于报告切换用户角色失败的原因和当前的用户角色。

触发时机

当本地用户加入频道后调用 setClientRole 切换用户角色失败时，SDK 会触发该回调。

参数

reason

用户角色切换失败的原因。详见 CLIENT_ROLE_CHANGE_FAILED_REASON。

currentRole

当前的用户角色。详见 CLIENT_ROLE_TYPE。

所属接口类

• IRtcEngineEventHandler

onError

onError 回调。报告 SDK 运行时发生的错误。

C++

virtual void onError(int err, const char* msg)

该回调表示 SDK 运行过程中发生了网络或媒体相关的错误。在大多数情况下，SDK 无法自动修复该问题并继续运行，需要你在应用层进行处理或提示用户。

参数

err

错误码。详见 ERROR_CODE_TYPE。

msg

错误信息。

所属接口类

• IRtcEngineEventHandler

onJoinChannelSuccess

本地用户成功加入频道回调。

C++

virtual void onJoinChannelSuccess(const char* channel, uid_t uid, int elapsed)

触发时机

当你调用 joinChannel、joinChannelWithUserAccount、joinChannelEx 或 joinChannelWithUserAccountEx 加入频道时，SDK 会触发该回调。

参数

channel

频道名。

uid

本地用户的用户 ID。

elapsed

从本地用户调用 joinChannel、joinChannelWithUserAccount、joinChannelEx 或 joinChannelWithUserAccountEx 加入频道到触发该回调的时间间隔，单位为毫秒。

所属接口类

• IRtcEngineEventHandler

onLeaveChannel

用户离开频道时触发的回调。

C++

virtual void onLeaveChannel(const RtcStats& stats)

你可以获取通话的总时长以及 SDK 的收发数据量。

触发时机

在你调用 leaveChannel [1/2]、leaveChannel [2/2]、leaveChannelEx [1/2] 或 leaveChannelEx [2/2] 离开频道后，SDK 会触发该回调。

参数

stats

通话统计信息。详见 RtcStats。

所属接口类

• IRtcEngineEventHandler

onLocalUserRegistered

onLocalUserRegistered 回调。当本地用户注册用户 User Account 时触发。

C++

virtual void onLocalUserRegistered(uid_t uid, const char* userAccount)

当本地用户成功调用 registerLocalUserAccount 注册用户 User Account，或调用 joinChannelWithUserAccount 加入频道后，SDK 会触发该回调，并返回本地用户的用户 ID 和用户 User Account。

参数

uid

本地用户的用户 ID。

userAccount

本地用户的用户 User Account。

所属接口类

• IRtcEngineEventHandler

onRejoinChannelSuccess

onRejoinChannelSuccess 回调。

C++

virtual void onRejoinChannelSuccess(const char* channel, uid_t uid, int elapsed)

当用户因网络问题与服务器断开连接时，SDK 会自动尝试重连，并在重连成功后触发该回调。

触发时机

当用户因网络问题与服务器断开连接后，SDK 自动尝试重连并成功后触发该回调。

参数

channel

频道名。

uid

重新加入频道的用户 ID。

elapsed

从本地用户调用 joinChannel 到 SDK 触发该回调的时间间隔（单位为毫秒）。

所属接口类

• IRtcEngineEventHandler

onRenewTokenResult

renewToken 方法调用结果回调。

C++

virtual void onRenewTokenResult(const char* token, RENEW_TOKEN_ERROR_CODE code)

自从

自 v4.6.0 版本新增。

当你调用 renewToken 方法更新 Token 后，该回调会被触发，用于通知更新结果。

参数

token

更新的 Token。

code

错误码，详见 RENEW_TOKEN_ERROR_CODE。

所属接口类

• IRtcEngineEventHandler

onRequestToken

Token 过期时触发的回调。

C++

virtual void onRequestToken() {}

收到该回调后，你需要在你的 Token 服务器上生成新的 Token，并通过以下方式之一进行更新：

• 单频道场景：
  • 调用 renewToken 传入新 Token。
  • 调用 leaveChannel 离开当前频道后，再调用 joinChannel 加入频道时传入新 Token。
• 多频道场景：调用 updateChannelMediaOptionsEx 传入新 Token。

触发时机

当 Token 过期时触发该回调。

所属接口类

• IRtcEngineEventHandler

onRtcStats

报告当前通话的统计信息。

C++

virtual void onRtcStats(const RtcStats& stats)

触发时机

用户加入频道后，SDK 每两秒触发一次该回调。

参数

stats

RTC 引擎的统计信息。详见 RtcStats。

所属接口类

• IRtcEngineEventHandler

onTokenPrivilegeWillExpire

Token 即将在 30 秒后过期时触发的回调。

C++

virtual void onTokenPrivilegeWillExpire(const char* token)

当收到该回调时，你需要在 Token 服务器上生成一个新的 Token，并通过以下方式之一更新 Token：

• 单频道场景：
  • 调用 renewToken 传入新的 Token。
  • 调用 leaveChannel 离开当前频道，然后在调用 joinChannel 加入频道时传入新的 Token。
• 多频道场景：调用 updateChannelMediaOptionsEx 传入新的 Token。

触发时机

SDK 会在 Token 过期前 30 秒触发该回调，提醒你更新 Token。

参数

token

即将过期的 Token。

所属接口类

• IRtcEngineEventHandler

onUserInfoUpdated

远端用户的用户 ID 和用户 User Account 信息更新时触发的回调。

C++

virtual void onUserInfoUpdated(uid_t uid, const UserInfo& info)

远端用户加入频道后，SDK 会获取该用户的用户 ID 和用户 User Account，并将其缓存在映射表中，然后在本地客户端触发该回调。

参数

uid

远端用户的用户 ID。

info

包含远端用户的用户 ID 和用户 User Account 信息的对象。详见 UserInfo。

所属接口类

• IRtcEngineEventHandler

onUserJoined

远端用户或主播加入频道时触发的回调。

C++

virtual void onUserJoined(uid_t uid, int elapsed)

在通信频道中，该回调表示有远端用户加入频道。当本地用户加入频道时，SDK 也会触发该回调报告频道中已有的用户。 在极速直播频道中，该回调表示有主播加入频道。当主播加入频道时，SDK 也会触发该回调报告频道中已有的主播。声网建议将连麦主播数量限制为 32 人，最多支持 17 路视频主播。

触发时机

SDK 在以下任一情况下触发该回调：

• 有远端用户或主播加入频道。
• 远端用户加入频道后切换为主播角色。
• 远端用户或主播在网络中断后重新加入频道。

参数

uid

加入频道的用户 ID。

elapsed

从本地用户调用 joinChannel 到该回调被触发的延迟时间（毫秒）。

所属接口类

• IRtcEngineEventHandler

onUserOffline

onUserOffline 回调：当远端用户（通信频道场景）或主播（极速直播频道场景）离开频道时触发。

C++

virtual void onUserOffline(uid_t uid, USER_OFFLINE_REASON_TYPE reason)

用户离线通常有以下两种情况：

• 离开频道：当用户或主播主动离开频道时，会发送离开消息。
• 掉线：在一段时间内未收到用户或主播的数据包时，SDK 会认为其掉线。通信频道场景为 20 秒，极速直播频道场景时间更长。网络不佳可能导致误判，建议使用声网 RTM SDK 进行更可靠的离线检测。

触发时机

当远端用户（通信频道场景）或主播（极速直播频道场景）离开频道时触发该回调。

参数

uid

离开频道或掉线的用户 ID。

reason

用户离线的原因，详见 USER_OFFLINE_REASON_TYPE。

所属接口类

• IRtcEngineEventHandler