频道相关

GetUserInfoByUid

通过 UID 获取用户信息。

C#

public abstract int GetUserInfoByUid(uint uid, ref UserInfo userInfo);

远端用户加入频道后，SDK 会获取到该远端用户的 UID 和 User Account，然后缓存一个包含了远端用户 UID 和 User Account 的映射表，并在本地触发 OnUserInfoUpdated 回调。收到回调后，调用该方法传入 UID 来获取包含了指定用户 User Account 的 UserInfo 对象。

调用时机

在收到 OnUserInfoUpdated 回调后调用。

调用限制

无。

相关回调

OnUserInfoUpdated

参数

uid

用户 ID。

userInfo

输入和输出参数。标识用户的 UserInfo 对象：

• 输入值：一个 UserInfo 对象。
• 输出值：一个包含了用户 User Account 和 UID 的 UserInfo 对象。

返回值

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

所属接口类

• IRtcEngine

GetUserInfoByUserAccount

通过 User Account 获取用户信息。

C#

public abstract int GetUserInfoByUserAccount(string userAccount, ref UserInfo userInfo);

远端用户加入频道后，SDK 会获取到该远端用户的 UID 和 User Account，然后缓存一个包含了远端用户 UID 和 User Account 的映射表，并在本地触发 OnUserInfoUpdated 回调。收到回调后，调用该方法传入 User Account 来获取包含了指定用户 UID 的 UserInfo 对象。

调用时机

在收到 OnUserInfoUpdated 回调后调用。

调用限制

无。

相关回调

OnUserInfoUpdated

参数

userAccount

用户 User Account。

userInfo

输入和输出参数。标识用户的 UserInfo 对象：

• 输入值：一个 UserInfo 对象。
• 输出值：一个包含了用户 User Account 和 UID 的 UserInfo 对象。

返回值

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

所属接口类

• IRtcEngine

JoinChannel [1/2]

加入频道。

C#

public abstract int JoinChannel(string token, string channelId, string info = "", uint uid = 0);

加入频道后，默认情况下用户订阅频道内所有其他用户的音频流和视频流，因此会产生用量并影响计费。如果想取消订阅，可以通过相应的 mute 方法实现。

调用时机

该方法需要在 Initialize 之后再调用。

调用限制

• 该方法仅支持用户一次加入一个频道。
• 使用不同 App ID 的 App 不能互通。
• 加入频道前，请确保用于生成 Token 的 App ID 和调用 Initialize 方法初始化引擎时使用的是同一个 App ID，否则使用 Token 加入频道会失败。

相关回调

成功调用该方法加入频道后会触发以下回调：

• 本地会触发 OnJoinChannelSuccess 和 OnConnectionStateChanged 回调。
• 通信场景下的用户和直播场景下的主播加入频道后，远端会触发 OnUserJoined 回调。

在网络状况不理想的情况下，客户端可能会与声网服务器失去连接，此时 SDK 会自动尝试重连，重连成功后，本地会触发 OnRejoinChannelSuccess 回调。

参数

token

在服务端生成的用于鉴权的动态密钥。详见使用 Token 鉴权。

信息

• （推荐）如果你的项目开启了安全模式，即选择 APP ID + Token 为鉴权机制，则该参数为必填。
• 如果你的项目仅开启调试模式，即选择 APP ID 为鉴权机制，则无需填入 Token 即可加入频道。成功加入频道 24 小时后会自动退出该频道。
• 如果你需要同时加入多个频道或在频道间频繁切换，声网推荐你使用通配 Token 以避免每加入一个新的频道都需向服务端申请一个新的 Token，详见 使用通配 Token。

channelId

频道名。该参数标识用户进行实时音视频互动的频道。App ID 一致的前提下，填入相同频道名的用户会进入同一个频道进行音视频互动。该参数为长度在 64 字节以内的字符串。以下为支持的字符集范围（共 89 个字符）:

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

info

(非必选项) 预留参数。

uid

用户 ID。该参数用于标识在实时音视频互动频道中的用户。你需要自行设置和管理用户 ID，并确保同一频道内的每个用户 ID 是唯一的。该参数为 32 位无符号整数。建议设置范围：1 到 2³²-1。如果不指定（即设为 0），SDK 会自动分配一个，并在 OnJoinChannelSuccess 回调中返回， 应用层必须记住该返回值并维护，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，重新加入频道。

JoinChannel [2/2]

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

C#

public abstract int JoinChannel(string token, string channelId, uint uid,
                                ChannelMediaOptions options);

相比 JoinChannel [1/2]，该方法增加了 options 参数，用于设置媒体选项，如是否在频道内发布音视频流等。用户加入频道时是否自动订阅频道内所有远端音视频流。默认情况下，用户订阅频道内所有其他用户的音频流和视频流，因此会产生用量并影响计费。如果想取消订阅，可以通过设置 options 参数或相应的 mute 方法实现。

调用时机

该方法需要在 Initialize 之后再调用。

调用限制

• 该方法仅支持用户一次加入一个频道。
• 使用不同 App ID 的 App 不能互通。
• 加入频道前，请确保用于生成 Token 的 App ID 和调用 Initialize 方法初始化引擎时使用的是同一个 App ID，否则使用 Token 加入频道会失败。

相关回调

成功调用该方法加入频道后会触发以下回调：

• 本地会触发 OnJoinChannelSuccess 和 OnConnectionStateChanged 回调。
• 通信场景下的用户和直播场景下的主播加入频道后，远端会触发 OnUserJoined 回调。

在网络状况不理想的情况下，客户端可能会与声网服务器失去连接，此时 SDK 会自动尝试重连，重连成功后，本地会触发 OnRejoinChannelSuccess 回调。

参数

token

在服务端生成的用于鉴权的动态密钥。详见使用 Token 鉴权。

信息

• （推荐）如果你的项目开启了安全模式，即选择 APP ID + Token 为鉴权机制，则该参数为必填。
• 如果你的项目仅开启调试模式，即选择 APP ID 为鉴权机制，则无需填入 Token 即可加入频道。成功加入频道 24 小时后会自动退出该频道。
• 如果你需要同时加入多个频道或在频道间频繁切换，声网推荐你使用通配 Token 以避免每加入一个新的频道都需向服务端申请一个新的 Token，详见 使用通配 Token。

channelId

频道名。该参数标识用户进行实时音视频互动的频道。App ID 一致的前提下，填入相同频道名的用户会进入同一个频道进行音视频互动。该参数为长度在 64 字节以内的字符串。以下为支持的字符集范围（共 89 个字符）:

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

uid

用户 ID。该参数用于标识在实时音视频互动频道中的用户。你需要自行设置和管理用户 ID，并确保同一频道内的每个用户 ID 是唯一的。该参数为 32 位无符号整数。建议设置范围：1 到 2³²-1。如果不指定（即设为 0），SDK 会自动分配一个，并在 OnJoinChannelSuccess 回调中返回， 应用层必须记住该返回值并维护，SDK 不对该返回值进行维护。

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#

public abstract int JoinChannelEx(string token, RtcConnection connection, ChannelMediaOptions options);

调用该方法，你可以同时加入多个频道。如果你想在不同的设备上加入相同的频道，请确保你在不同设备上使用的用户 ID 都不同。

适用场景

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

调用时机

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

在多摄像头采集场景下，你需要在调用该方法之后调用 StartPreview [2/2] 方法设置 sourceType 为 VIDEO_SOURCE_CAMERA_SECONDARY，以确保第二个摄像头采集正常。

调用限制

如果你已经在一个频道内，你不能用相同的用户 ID 再次加入该频道。

加入频道前，请确保用于生成 Token 的 App ID 和调用 Initialize 方法初始化引擎时使用的是同一个 App ID，否则使用 Token 加入频道会失败。

相关回调

成功调用该方法加入频道后会触发以下回调：

• 本地会触发 OnJoinChannelSuccess 和 OnConnectionStateChanged 回调。
• 通信场景下的用户和直播场景下的主播加入频道后，远端会触发 OnUserJoined 回调。

在网络状况不理想的情况下，客户端可能会与声网服务器失去连接，此时 SDK 会自动尝试重连，重连成功后，本地会触发 OnRejoinChannelSuccess 回调。

参数

token

在服务端生成的用于鉴权的动态密钥。详见使用 Token 鉴权。

信息

• （推荐）如果你的项目开启了安全模式，即选择 APP ID + Token 为鉴权机制，则该参数为必填。
• 如果你的项目仅开启调试模式，即选择 APP ID 为鉴权机制，则无需填入 Token 即可加入频道。成功加入频道 24 小时后会自动退出该频道。
• 如果你需要同时加入多个频道或在频道间频繁切换，声网推荐你使用通配 Token 以避免每加入一个新的频道都需向服务端申请一个新的 Token，详见 使用通配 Token。

connection

Connection 信息。详见 RtcConnection。

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，重新加入频道。

所属接口类

• IRtcEngineEx

JoinChannelWithUserAccount [1/2]

使用 User Account 和 Token 加入频道。

C#

public abstract int JoinChannelWithUserAccount(string token, string channelId, string userAccount);

调用该方法前，如果你未调用 RegisterLocalUserAccount 注册一个 User Account，调用该方法加入频道时，SDK 会自动为你创建一个 User Account。先调用 RegisterLocalUserAccount 方法注册 Account，再调用此方法加入频道，可以缩短进入频道的时间。

用户成功加入频道后，默认订阅频道内所有其他用户的音频流和视频流，因此产生用量并影响计费。如果想取消订阅，可以通过调用相应的 mute 方法实现。

注意

为保证通信质量，请确保频道内使用同一类型的数据标识用户身份。即同一频道内需要统一使用 UID 或 User Account。如果有用户通过 Web SDK 加入频道，请确保 Web 加入的用户也是同样类型。

调用时机

该方法需要在 Initialize 之后再调用。

调用限制

• 该方法仅支持用户一次加入一个频道。
• 使用不同 App ID 的 App 不能互通。
• 加入频道前，请确保用于生成 Token 的 App ID 和调用 Initialize 方法初始化引擎时使用的是同一个 App ID，否则使用 Token 加入频道会失败。

相关回调

成功加入频道后，会触发以下回调：

• 本地：OnLocalUserRegistered、OnJoinChannelSuccess 和 OnConnectionStateChanged 回调。
• 远端：通信场景下的用户和直播场景下的主播加入频道后，远端会分别触发 OnUserJoined 和 OnUserInfoUpdated 回调。

参数

token

在服务端生成的用于鉴权的动态密钥。详见使用 Token 鉴权。

信息

• （推荐）如果你的项目开启了安全模式，即选择 APP ID + Token 为鉴权机制，则该参数为必填。
• 如果你的项目仅开启调试模式，即选择 APP ID 为鉴权机制，则无需填入 Token 即可加入频道。成功加入频道 24 小时后会自动退出该频道。
• 如果你需要同时加入多个频道或在频道间频繁切换，声网推荐你使用通配 Token 以避免每加入一个新的频道都需向服务端申请一个新的 Token，详见 使用通配 Token。

channelId

频道名。该参数标识用户进行实时音视频互动的频道。App ID 一致的前提下，填入相同频道名的用户会进入同一个频道进行音视频互动。该参数为长度在 64 字节以内的字符串。以下为支持的字符集范围（共 89 个字符）:

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

userAccount

用户 User Account。该参数用于标识实时音视频互动频道中的用户。你需要自行设置和管理用户的 User Account，并确保同一频道中每个用户的 User Account 是唯一的。 该参数为必填，最大不超过 255 字节，不可填 NULL。以下为支持的字符集范围（共 89 个字符）：

• 26 个小写英文字母 a-z
• 26 个大写英文字母 A-Z
• 10 个数字 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，重新加入频道。

JoinChannelWithUserAccount [2/2]

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

C#

public abstract int JoinChannelWithUserAccount(string token, string channelId, string userAccount,
            ChannelMediaOptions options);

调用该方法前，如果你未调用 RegisterLocalUserAccount 注册一个 User Account，调用该方法加入频道时，SDK 会自动为你创建一个 User Account。先调用 RegisterLocalUserAccount 方法注册 Account，再调用此方法加入频道，可以缩短进入频道的时间。

相比 JoinChannelWithUserAccount [1/2]，该方法增加了 options 参数，用于在加入频道时设置媒体选项，如是否在频道内发布音视频流等。默认情况下，用户订阅频道内所有其他用户的音频流和视频流，因此会产生用量并影响计费。如果想取消订阅，可以通过设置 options 参数或相应的 mute 方法实现。

注意

为保证通信质量，请确保频道内使用同一类型的数据标识用户身份。即同一频道内需要统一使用 UID 或 User Account。如果有用户通过 Web SDK 加入频道，请确保 Web 加入的用户也是同样类型。

调用时机

该方法需要在 Initialize 之后再调用。

调用限制

• 该方法仅支持用户一次加入一个频道。
• 使用不同 App ID 的 App 不能互通。
• 加入频道前，请确保用于生成 Token 的 App ID 和调用 Initialize 方法初始化引擎时使用的是同一个 App ID，否则使用 Token 加入频道会失败。

相关回调

成功加入频道后，会触发以下回调：

• 本地：OnLocalUserRegistered、OnJoinChannelSuccess 和 OnConnectionStateChanged 回调。
• 远端：通信场景下的用户和直播场景下的主播加入频道后，远端会分别触发 OnUserJoined 和 OnUserInfoUpdated 回调。

参数

token

在服务端生成的用于鉴权的动态密钥。详见使用 Token 鉴权。

信息

• （推荐）如果你的项目开启了安全模式，即选择 APP ID + Token 为鉴权机制，则该参数为必填。
• 如果你的项目仅开启调试模式，即选择 APP ID 为鉴权机制，则无需填入 Token 即可加入频道。成功加入频道 24 小时后会自动退出该频道。
• 如果你需要同时加入多个频道或在频道间频繁切换，声网推荐你使用通配 Token 以避免每加入一个新的频道都需向服务端申请一个新的 Token，详见 使用通配 Token。

channelId

频道名。该参数标识用户进行实时音视频互动的频道。App ID 一致的前提下，填入相同频道名的用户会进入同一个频道进行音视频互动。该参数为长度在 64 字节以内的字符串。以下为支持的字符集范围（共 89 个字符）:

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

userAccount

用户 User Account。该参数用于标识实时音视频互动频道中的用户。你需要自行设置和管理用户的 User Account，并确保同一频道中每个用户的 User Account 是唯一的。 该参数为必填，最大不超过 255 字节，不可填 NULL。以下为支持的字符集范围（共 89 个字符）：

• 26 个小写英文字母 a-z
• 26 个大写英文字母 A-Z
• 10 个数字 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

LeaveChannel [1/2]

离开频道。

C#

public abstract int LeaveChannel();

调用该方法后，SDK 会终止音视频互动、离开当前频道，并会释放会话相关的所有资源。

成功加入频道后，必须调用本方法结束通话，否则无法开始下一次通话。

注意

• 该方法是异步操作，调用返回时并没有真正退出频道。
• 如果你已调用 JoinChannelEx 加入多个频道，调用本方法后会同时离开所有已加入的频道。

调用时机

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

调用限制

如果你调用了该方法后立即调用 Dispose 方法，SDK 将不会触发 OnLeaveChannel 回调。

相关回调

成功调用该方法离开频道后会触发以下回调：

• 本地：OnLeaveChannel 回调。
• 远端：主播离开频道后，远端会触发 OnUserOffline 回调。

返回值

• 0(ERR_OK): 方法调用成功。
• < 0: 方法调用失败。详见错误码了解详情和解决建议。
  • -1: 一般性的错误（未明确归类）。
  • -2: 参数无效。
  • -7: SDK 尚未初始化。

LeaveChannel [2/2]

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

C#

public abstract int LeaveChannel(LeaveChannelOptions options); 

调用该方法后，SDK 会终止音视频互动、离开当前频道，并会释放会话相关的所有资源。

成功加入频道后，必须调用本方法或者 LeaveChannel [1/2] 结束通话，否则无法开始下一次通话。如果你已调用 JoinChannelEx 加入多个频道，调用本方法后会同时离开所有已加入的频道。

注意

该方法是异步操作，调用返回时并没有真正退出频道。

调用时机

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

调用限制

如果你调用了该方法后立即调用 Dispose 方法，SDK 将不会触发 OnLeaveChannel 回调。

相关回调

成功调用该方法离开频道后会触发以下回调：

• 本地：OnLeaveChannel 回调。
• 远端：主播离开频道后，远端会触发 OnUserOffline 回调。

参数

options

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

返回值

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

所属接口类

• IRtcEngine

LeaveChannelEx [1/2]

离开频道。

C#

public abstract int LeaveChannelEx(RtcConnection connection);

调用该方法后，SDK 会终止音视频互动、离开当前频道，并会释放会话相关的所有资源。

调用 JoinChannelEx 成功加入频道后，必须调用本方法或 LeaveChannelEx [2/2] 结束通话，否则无法开始下一次通话。

注意

• 该方法是异步操作，调用返回时并没有真正退出频道。
• 如果你调用了 LeaveChannel [1/2] 或 LeaveChannel [2/2] 后，会同时离开 JoinChannel [1/2] 或 JoinChannel [2/2] 及 JoinChannelEx 加入的频道。

适用场景

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

调用时机

该方法需要在 JoinChannelEx 后调用。

调用限制

如果你调用了该方法后立即调用 Dispose 方法，SDK 将不会触发 OnLeaveChannel 回调。

相关回调

成功调用该方法离开频道后会触发以下回调：

• 本地：OnLeaveChannel 回调。
• 远端：主播离开频道后，远端会触发 OnUserOffline 回调。

参数

connection

Connection 信息。详见 RtcConnection。

返回值

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

LeaveChannelEx [2/2]

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

C#

public abstract int LeaveChannelEx(RtcConnection connection, LeaveChannelOptions options);

调用该方法后，SDK 会终止音视频互动、离开当前频道，并会释放会话相关的所有资源。

调用 JoinChannelEx 成功加入频道后，必须调用本方法或 LeaveChannelEx [1/2] 结束通话，否则无法开始下一次通话。

注意

• 该方法是异步操作，调用返回时并没有真正退出频道。
• 如果你调用了 LeaveChannel [1/2] 或 LeaveChannel [2/2] 后，会同时离开 JoinChannel [1/2] 或 JoinChannel [2/2] 及 JoinChannelEx 加入的频道。

适用场景

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

调用时机

该方法需要在 JoinChannelEx 后调用。

调用限制

如果你调用了该方法后立即调用 Dispose 方法，SDK 将不会触发 OnLeaveChannel 回调。

相关回调

成功调用该方法离开频道后会触发以下回调：

• 本地：OnLeaveChannel 回调。
• 远端：主播离开频道后，远端会触发 OnUserOffline 回调。

参数

connection

Connection 信息。详见 RtcConnection。

options

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

信息

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

返回值

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

所属接口类

• IRtcEngineEx

PreloadChannel

使用 token、channelId、uid 预加载频道。

C#

public abstract int PreloadChannel(string token, string channelId, uint uid);

调用该方法可以减少观众频繁切换频道时加入频道的时间，从而缩短观众听到主播首帧音频以及看到首帧画面的耗时，提升观众端的视频体验。

如果当前频道已经成功预加载，观众加入、离开频道后如需再次加入该频道，只要预加载时传入的 Token 仍在有效期内，则无需重新预加载。

信息

预加载不生效不会影响后续正常加入频道，也不会增加加入频道的耗时。

调用时机

为了提升预加载频道的用户体验，声网推荐你在确认频道名、用户信息后、加入频道前，尽早调用该方法。

调用限制

• 调用该方法时，请确保用户角色设为观众、音频应用场景设为非合唱场景（AUDIO_SCENARIO_CHORUS），否则预加载不生效。
• 请确保预加载频道时传入的频道名、用户 ID、Token 和后续加入频道时传入的值相同，否则预加载不生效。
• 目前一个 IRtcEngine 实例最多支持预加载 20 个频道，如超出限制，仅最新预加载的 20 个频道生效。

参数

token

在服务端生成的用于鉴权的动态密钥。详见使用 Token 鉴权。

Token 过期后，根据预加载频道的数量，你可以通过不同方式来传入用于预加载频道的新 Token：

• 预加载一个频道时：调用此方法来传入新的 Token。
• 预加载多个频道时：
  • 如果你使用了通配的 Token，调用 UpdatePreloadChannelToken 来更新所有预加载频道的 Token。
    信息

    生成通配 Token 时，用户 ID 不得设为 0。详见 使用通配 Token。
  • 如果你使用了不同的 Token：调用此方法并传入你的用户 ID、对应的频道名和更新后的 Token。

channelId

待预加载的频道名。该参数标识用户进行实时音视频互动的频道。App ID 一致的前提下，填入相同频道名的用户会进入同一个频道进行音视频互动。 该参数为长度在 64 字节以内的字符串。以下为支持的字符集范围（共 89 个字符）:

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

uid

用户 ID。该参数用于标识在实时音视频互动频道中的用户。你需要自行设置和管理用户 ID，并确保同一频道内的每个用户 ID 是唯一的。该参数为 32 位无符号整数。建议设置范围：1 到 2³²-1。如果不指定（即设为 0），SDK 会自动分配一个，并在 OnJoinChannelSuccess 回调中返回， 应用层必须记住该返回值并维护，SDK 不对该返回值进行维护。

返回值

• 0：方法调用成功。
• < 0：方法调用失败。详见错误码了解详情和解决建议。
  • -7：IRtcEngine 对象尚未初始化。你需要在调用该方法前成功初始化 IRtcEngine 对象。
  • -102：频道名无效。你需要填入有效的频道名，重新加入频道。

所属接口类

• IRtcEngine

PreloadChannelWithUserAccount

使用 token、channelId、userAccount 预加载频道。

C#

public abstract int PreloadChannel(string token, string channelId, string userAccount);

调用该方法可以减少观众频繁切换频道时加入频道的时间，从而缩短观众听到主播首帧音频以及看到首帧画面的耗时，提升观众端的视频体验。

如果当前频道已经成功预加载，观众加入、离开频道后如需再次加入该频道，只要预加载时传入的 Token 仍在有效期内，则无需重新预加载。

信息

预加载不生效不会影响后续正常加入频道，也不会增加加入频道的耗时。

调用时机

为了提升预加载频道的用户体验，声网推荐你在确认频道名、用户信息后、加入频道前，尽早调用该方法。

调用限制

• 调用该方法时，请确保用户角色设为观众、音频应用场景设为非合唱场景（AUDIO_SCENARIO_CHORUS），否则预加载不生效。
• 请确保预加载频道时传入的频道名、用户 User Account、Token 和后续加入频道时传入的值相同，否则预加载不生效。
• 目前一个 IRtcEngine 实例最多支持预加载 20 个频道，如超出限制，仅最新预加载的 20 个频道生效。

参数

token

在服务端生成的用于鉴权的动态密钥。详见使用 Token 鉴权。

Token 过期后，根据预加载频道的数量，你可以通过不同方式来传入用于预加载频道的新 Token：

• 预加载一个频道时：调用此方法来传入新的 Token。
• 预加载多个频道时：
  • 如果你使用了通配的 Token，调用 UpdatePreloadChannelToken 来更新所有预加载频道的 Token。
    信息

    生成通配 Token 时，用户 ID 不得设为 0。详见 使用通配 Token。
  • 如果你使用了不同的 Token：调用此方法并传入你的用户 ID、对应的频道名和更新后的 Token。

channelId

待预加载的频道名。该参数标识用户进行实时音视频互动的频道。App ID 一致的前提下，填入相同频道名的用户会进入同一个频道进行音视频互动。 该参数为长度在 64 字节以内的字符串。以下为支持的字符集范围（共 89 个字符）:

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

userAccount

用户 User Account。该参数用于标识实时音视频互动频道中的用户。你需要自行设置和管理用户的 User Account，并确保同一频道中每个用户的 User Account 是唯一的。 该参数为必填，最大不超过 255 字节，不可填 NULL。以下为支持的字符集范围（共 89 个字符）：

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

返回值

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

所属接口类

• IRtcEngine

RegisterLocalUserAccount

注册本地用户 User Account。

C#

public abstract int RegisterLocalUserAccount(string appId, string userAccount);

该方法为本地用户注册一个 User Account。注册成功后，该 User Account 即可标识该本地用户的身份，用户可以使用它加入频道。

该方法为可选。如果你希望用户使用 User Account 加入频道，可参考下列任意一种方式实现：

• 先调用 RegisterLocalUserAccount 方法注册 Account，再调用 JoinChannelWithUserAccount [1/2] 或 JoinChannelWithUserAccount [2/2] 方法加入频道，可以缩短进入频道的时间。
• 直接调用 JoinChannelWithUserAccount [1/2] 或 JoinChannelWithUserAccount [2/2] 方法加入频道。

注意

• 请确保在该方法中设置的 userAccount 在频道中的唯一性。
• 为保证通信质量，请确保频道内使用同一类型的数据标识用户身份。即同一频道内需要统一使用 UID 或 User Account。如果有用户通过 Web SDK 加入频道，请确保 Web 加入的用户也是同样类型。

调用限制

无。

相关回调

成功调用该方法后，本地会触发 OnLocalUserRegistered 回调，告知本地用户的 UID 和 User Account。

参数

appId

你的项目在控制台注册的 App ID。

userAccount

用户 User Account。该参数用于标识实时音视频互动频道中的用户。你需要自行设置和管理用户的 User Account，并确保同一频道中每个用户的 User Account 是唯一的。该参数为必填，最大不超过 255 字节，不可填 NULL。以下为支持的字符集范围（共 89 个字符）：

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

返回值

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

所属接口类

• IRtcEngine

RenewToken

更新 Token。

C#

public abstract int RenewToken(string token);

该方法用于更新 Token。Token 会在一定时间后失效，此时 SDK 将无法和服务器建立连接。

调用时机

在以下任意一种情况下，声网推荐你在你的服务端重新生成 Token，然后调用该方法传入新的 Token：

• 收到 OnTokenPrivilegeWillExpire 回调报告 Token 即将过期时；
• 收到 OnRequestToken 回调报告 Token 已过期；
• 收到 OnConnectionStateChanged 回调报告 CONNECTION_CHANGED_TOKEN_EXPIRED(9) 时；

调用限制

无。

相关回调

• OnTokenPrivilegeWillExpire
• OnRequestToken
• OnConnectionStateChanged

参数

token

新生成的 Token。

返回值

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

所属接口类

• IRtcEngine

SetChannelProfile

设置频道场景。

C#

public abstract int SetChannelProfile(CHANNEL_PROFILE_TYPE profile);

你可以调用该方法设置频道的使用场景。SDK 会针对不同的使用场景采用不同的优化策略，如直播场景优先保证画质。SDK 初始化后默认的频道场景为直播场景。

调用时机

该方法需要在加入频道前调用。

调用限制

为保证实时音视频质量，相同频道内的用户必须使用同一种频道场景。

参数

profile

频道使用场景。详见 CHANNEL_PROFILE_TYPE。

返回值

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

所属接口类

• IRtcEngine

SetClientRole [1/2]

设置用户角色。

C#

public abstract int SetClientRole(CLIENT_ROLE_TYPE role);

SDK 默认设置用户角色为观众，你可以调用该方法设置用户角色为主播。用户角色（role）确定用户在 SDK 层的权限，包含是否可以发送流等。

调用时机

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

如果你在加入频道后调用该方法切换用户角色，调用成功后，SDK 会自动调用 MuteLocalAudioStream 和 MuteLocalVideoStream 修改发布音视频流的状态。

调用限制

在频道外调用本方法并将用户角色设为 BROADCASTER（主播）时，本地不会触发 OnClientRoleChanged 回调。

相关回调

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

• 本地触发 OnClientRoleChanged 回调。
  信息

  在加入频道前调用该方法并将 role 设为 AUDIENCE（观众）时，也会触发该回调。
• 远端触发 OnUserJoined 或 OnUserOffline 回调。

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

参数

role

用户角色。详见 CLIENT_ROLE_TYPE。

信息

角色为观众的用户无法在频道内发布音视频流。在直播场景下发流时，请确保你的用户角色已切换为主播。

返回值

• 0: 方法调用成功。
• < 0: 方法调用失败。详见错误码了解详情和解决建议。
  • -1: 一般性的错误（未明确归类）。
  • -2: 参数无效。
  • -7: SDK 尚未初始化。

SetClientRole [2/2]

设置直播场景下的用户角色和观众端延时级别。

C#

public abstract int SetClientRole(CLIENT_ROLE_TYPE role, ClientRoleOptions options);

SDK 默认设置用户角色为观众，你可以调用该方法设置用户角色为主播。用户角色（role）确定用户在 SDK 层的权限，包含是否有发流权限等。

该方法与 SetClientRole [1/2] 的区别在于，该方法还支持设置观众端延时级别（audienceLatencyLevel）。audienceLatencyLevel 需与 role 结合使用，确定用户在其权限范围内可以享受到的服务。例如对于观众，选择接收低延时还是超低延时的视频流。不同的延时级别会影响计费，详见 计费策略。

调用时机

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

如果你在加入频道后调用该方法切换用户角色，调用成功后，SDK 会自动调用 MuteLocalAudioStream 和 MuteLocalVideoStream 修改发布音视频流的状态。

调用限制

当用户角色设为主播时，观众端延时级别仅支持设置为 AUDIENCE_LATENCY_LEVEL_ULTRA_LOW_LATENCY（超低延时）。

在加入频道前调用该方法并将 role 设为 BROADCASTER（主播）时，本地不会触发 OnClientRoleChanged 回调。

相关回调

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

• 本地触发 OnClientRoleChanged 回调。
  信息

  在加入频道前调用该方法并将 role 设为 AUDIENCE（观众）时，也会触发该回调。
• 远端触发 OnUserJoined 或 OnUserOffline 回调。

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

参数

role

用户角色。详见 CLIENT_ROLE_TYPE。

信息

角色为观众的用户无法在频道内发布音视频流。在直播场景下发流时，请确保你的用户角色已切换为主播。

options

用户具体设置，包含用户级别。详见 ClientRoleOptions。

返回值

• 0: 方法调用成功。
• < 0: 方法调用失败。详见错误码了解详情和解决建议。
  • -1: 一般性的错误（未明确归类）。
  • -2: 参数无效。
  • -5: 调用被拒绝。
  • -7: SDK 尚未初始化。

所属接口类

• IRtcEngine

UpdateChannelMediaOptions

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

C#

public abstract int UpdateChannelMediaOptions(ChannelMediaOptions options);

参数

options

频道媒体选项，详见 ChannelMediaOptions。

返回值

• 0: 方法调用成功。
• < 0: 方法调用失败。详见错误码了解详情和解决建议。
  • -2：ChannelMediaOptions 成员值设置无效。例如，使用了不合法的 Token，设置了无效的用户角色。你需要填入有效的参数。
  • -7：IRtcEngine 对象尚未初始化。你需要在调用该方法前成功初始化 IRtcEngine 对象。
  • -8：IRtcEngine 对象内部状态错误。可能的原因是用户不在频道中。建议通过 OnConnectionStateChanged 回调判断用户是否在频道中。如果收到 CONNECTION_STATE_DISCONNECTED(1) 或 CONNECTION_STATE_FAILED(5)，则表示用户不在频道中。你需要在调用该方法前调用 JoinChannel [2/2] 加入频道。

所属接口类

• IRtcEngine

UpdateChannelMediaOptionsEx

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

C#

public abstract int UpdateChannelMediaOptionsEx(ChannelMediaOptions options, RtcConnection connection);

参数

options

频道媒体选项，详见 ChannelMediaOptions。

connection

Connection 信息。详见 RtcConnection。

返回值

• 0: 方法调用成功。
• < 0: 方法调用失败。详见错误码了解详情和解决建议。
  • -2：ChannelMediaOptions 成员值设置无效。例如，使用了不合法的 Token，设置了无效的用户角色。你需要填入有效的参数。
  • -7：IRtcEngine 对象尚未初始化。你需要在调用该方法前成功初始化 IRtcEngine 对象。
  • -8：IRtcEngine 对象内部状态错误。可能的原因是用户不在频道中。建议通过 OnConnectionStateChanged 回调判断用户是否在频道中。如果收到 CONNECTION_STATE_DISCONNECTED(1) 或 CONNECTION_STATE_FAILED(5)，则表示用户不在频道中。你需要在调用该方法前调用 JoinChannel [2/2] 加入频道。

所属接口类

• IRtcEngineEx

UpdatePreloadChannelToken

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

C#

public abstract int UpdatePreloadChannelToken(string token);

详情

你需要自行维护通配 Token 的生命周期。当通配 Token 过期后，你需要在你的服务端生成新的通配 Token，然后通过此方法来传入新的 Token。

适用场景

在需要频繁切换频道及多频道场景下，使用通配 Token 可以避免观众在切换不同频道时需多次申请 Token 从而导致切换频道时间增长，可以进一步加快切换频道的速度，同时减少你的 Token 服务端的压力。

参数

token

新的 Token。

返回值

• 0: 方法调用成功。
• < 0: 方法调用失败。详见错误码了解详情和解决建议。
  • -2：传入的参数无效。例如，使用了不合法的 Token。你需要填入有效的参数，重新加入频道。
  • -7：IRtcEngine 对象尚未初始化。你需要在调用该方法前成功初始化 IRtcEngine 对象。

所属接口类

• IRtcEngine

OnClientRoleChanged

用户角色、观众端延时级别已切换回调。

C#

 public virtual void OnClientRoleChanged(RtcConnection connection, CLIENT_ROLE_TYPE oldRole, CLIENT_ROLE_TYPE newRole, ClientRoleOptions newRoleOptions) { }

详情

触发时机

在以下任意一种情况时，会触发此回调：

• 在加入频道后调用 SetClientRole [1/2] 或 SetClientRole [2/2] 设置用户角色或观众端延时级别。
• 在加入频道前调用 SetClientRole [1/2] 或 SetClientRole [2/2] 并将用户角色设为 AUDIENCE。

使用限制

当你在加入频道前调用 SetClientRole [1/2] 或 SetClientRole [2/2] 并将用户角色设为 BROADCASTER 时，不会触发此回调。

参数

connection

Connection 信息。详见 RtcConnection。

oldRole

切换前的角色：CLIENT_ROLE_TYPE。

newRole

切换后的角色：CLIENT_ROLE_TYPE。

newRoleOptions

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

所属接口类

• IRtcEngineEventHandler

OnClientRoleChangeFailed

用户角色切换失败回调。

C#

public virtual void OnClientRoleChangeFailed(RtcConnection connection, CLIENT_ROLE_CHANGE_FAILED_REASON reason, CLIENT_ROLE_TYPE currentRole) { }

当用户角色切换失败时，你可以通过此回调得知切换失败的原因和当前的用户角色。

触发时机

本地用户加入频道后调用 SetClientRole [1/2] 或 SetClientRole [2/2] 设置用户角色失败时，SDK 会触发该回调。

使用限制

无。

参数

reason

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

currentRole

当前用户角色。详见 CLIENT_ROLE_TYPE。

connection

Connection 信息。详见 RtcConnection。

所属接口类

• IRtcEngineEventHandler

OnError

发生错误回调。

C#

 public virtual void OnError(int err, string msg) { }

详情

该回调方法表示 SDK 运行时出现了网络或媒体相关的错误。通常情况下，SDK 上报的错误意味着 SDK 无法自动恢复，需要 App 干预或提示用户。

参数

err

错误码。详见 ERROR_CODE_TYPE。

msg

错误描述。

所属接口类

• IRtcEngineEventHandler

OnJoinChannelSuccess

成功加入频道回调。

C#

public virtual void OnJoinChannelSuccess(RtcConnection connection, int elapsed) {}

详情

该回调方法表示该客户端成功加入了指定的频道。

触发时机

当你调用 JoinChannel [1/2]、JoinChannel [2/2]、JoinChannelWithUserAccount [1/2]、JoinChannelWithUserAccount [2/2]、 JoinChannelEx 或 方法成功加入频道后，SDK 会触发该回调。

使用限制

无。

参数

connection

Connection 信息。详见 RtcConnection。

elapsed

从本地调用 JoinChannel [2/2] 开始到发生此事件过去的时间（毫秒）。

所属接口类

• IRtcEngineEventHandler

OnLeaveChannel

离开频道回调。

C#

public virtual void OnLeaveChannel(RtcConnection connection, RtcStats stats) {}

你可以通过该回调获取此次通话的总通话时长、SDK 收发数据的流量等信息。

触发时机

当你成功调用 LeaveChannel [1/2]、LeaveChannel [2/2]、LeaveChannelEx [1/2] 或 LeaveChannelEx [2/2] 离开频道后，SDK 会触发该回调。

使用限制

无。

参数

connection

Connection 信息。详见 RtcConnection。

stats

通话的统计数据，详见 RtcStats。

所属接口类

• IRtcEngineEventHandler

OnLocalUserRegistered

本地用户成功注册 User Account 回调。

C#

public virtual void OnLocalUserRegistered(uint uid, string userAccount) {}

详情

本地用户成功调用 RegisterLocalUserAccount 方法注册用户 User Account，或调用 JoinChannelWithUserAccount [2/2] 加入频道后，SDK 会触发该回调，并告知本地用户的 UID 和 User Account。

参数

uid

本地用户的 ID。

userAccount

本地用户的 User Account。

所属接口类

• IRtcEngineEventHandler

OnRejoinChannelSuccess

成功重新加入频道回调。

C#

public virtual void OnRejoinChannelSuccess(RtcConnection connection, int elapsed) {}

详情

触发时机

有时候由于网络原因，客户端可能会和服务器失去连接，SDK 会进行自动重连，自动重连成功后触发此回调方法。

使用限制

无。

参数

connection

Connection 信息。详见 RtcConnection。

elapsed

从调用 JoinChannel [2/2] 方法到触发该回调的时间间隔（毫秒）。

所属接口类

• IRtcEngineEventHandler

OnRequestToken

Token 已过期回调。

C#

public virtual void OnRequestToken(RtcConnection connection) {}

在音视频互动过程中，如果 Token 失效，SDK 会触发该回调报告 Token 已过期。

当收到该回调时，你需要重新在服务端生成新的 Token，然后通过下列任意一种方式来更新 Token：

• 单频道场景：
  • 调用 RenewToken 来传入新的 Token。
  • 调用 LeaveChannel [2/2] 离开当前频道，然后在调用 JoinChannel [2/2] 时传入新的 Token 重新加入频道。
• 多频道场景：调用 UpdateChannelMediaOptionsEx 传入新的 Token。

使用限制

无。

参数

connection

Connection 信息。详见 RtcConnection。

所属接口类

• IRtcEngineEventHandler

OnRtcStats

当前通话相关的统计信息回调。

C#

public virtual void OnRtcStats(RtcConnection connection, RtcStats stats) {}

触发时机

SDK 定期向 App 报告当前通话的统计信息，每两秒触发一次。

使用限制

无。

参数

connection

Connection 信息。详见 RtcConnection。

stats

RTC 引擎统计数据，详见 RtcStats。

所属接口类

• IRtcEngineEventHandler

OnTokenPrivilegeWillExpire

Token 即将在 30s 内过期回调。

C#

public virtual void OnTokenPrivilegeWillExpire(RtcConnection connection, string token) {}

当收到该回调时，你需要重新在服务端生成新的 Token，然后通过下列任意一种方式来更新 Token：

• 单频道场景：
  • 调用 RenewToken 来传入新的 Token。
  • 调用 LeaveChannel [2/2] 离开当前频道，然后在调用 JoinChannel [2/2] 时传入新的 Token 重新加入频道。
• 多频道场景：调用 UpdateChannelMediaOptionsEx 传入新的 Token。

触发时机

在音视频互动过程中，SDK 会在 Token 过期前 30 秒触发该回调，提醒 App 更新 Token。

使用限制

无。

参数

connection

Connection 信息。详见 RtcConnection。

token

即将过期的 Token。

所属接口类

• IRtcEngineEventHandler

OnUserInfoUpdated

远端用户信息已更新回调。

C#

public virtual void OnUserInfoUpdated(uint uid, UserInfo info)

详情

远端用户加入频道后，SDK 会获取到该远端用户的 UID 和 User Account，然后缓存一个包含了远端用户 UID 和 User Account 的 Mapping 表，并在本地触发该回调。

参数

uid

远端用户 ID。

info

标识用户信息的 UserInfo 对象，包含用户 UID 和 User Account。详见 UserInfo 类。

所属接口类

• IRtcEngineEventHandler

OnUserJoined

远端用户（通信场景）/主播（直播场景）加入当前频道回调。

C#

public virtual void OnUserJoined(RtcConnection connection, uint remoteUid, int elapsed) {}

• 通信场景下，该回调提示有远端用户加入了频道。如果加入之前已经有其他用户在频道中，新加入的用户也会收到这些已有用户加入频道的回调。
• 直播场景下，该回调提示有主播加入了频道。如果加入之前，已经有主播在频道中了，新加入的用户也会收到已有主播加入频道的回调。建议连麦主播不超过 17 人。

触发时机

该回调在如下情况下会被触发：

• 远端用户/主播加入频道。
• 远端用户加入频道后将用户角色改变为主播。
• 远端用户/主播网络中断后重新加入频道。

使用限制

无。

参数

connection

Connection 信息。详见 RtcConnection。

remoteUid

新加入频道的远端用户/主播 ID。

elapsed

从本地用户调用 JoinChannel [2/2] 到该回调触发的延迟（毫秒）。

所属接口类

• IRtcEngineEventHandler

OnUserOffline

远端用户（通信场景）/主播（直播场景）离开当前频道回调。

C#

public virtual void OnUserOffline(RtcConnection connection, uint remoteUid, USER_OFFLINE_REASON_TYPE reason) {}

用户离开频道一般有以下两个原因：

• 正常离开：远端用户或主播会发送类似“再见”的消息然后主动离开频道。
• 超时掉线：在一定时间内（通信场景为 20 秒，直播场景稍有延时），用户没有收到对方的任何数据包，则判定为对方掉线。在网络较差的情况下，有可能会误报。建议使用 RTM SDK 来做可靠的掉线检测。

触发时机

在音视频互动过程中，当远端用户或主播离开当前频道时会触发该回调。

使用限制

无。

参数

connection

Connection 信息。详见 RtcConnection。

remoteUid

离线的远端用户或主播的 ID。

reason

远端用户（通信场景）或主播（直播场景）离线的原因，详见 USER_OFFLINE_REASON_TYPE。

所属接口类

• IRtcEngineEventHandler