频道相关
getUserInfoByUid
通过 UID 获取用户信息。
public abstract int getUserInfoByUid(int uid, UserInfo userInfo);
远端用户加入频道后，SDK 会获取到该远端用户的 UID 和 User Account，然后缓存一个包含了远端用户 UID 和 User Account 的 Mapping 表，并在本地触发 onUserInfoUpdated 回调。收到这个回调后，你可以调用该方法，通过传入 UID 获取包含了指定用户 User Account 的 UserInfo 对象。
参数
| 参数名 | 描述 |
|---|---|
uid | 用户 ID。 |
userInfo | 输入和输出参数。标识用户的
|
返回值
-
0: 方法调用成功。
-
< 0: 方法调用失败。详见
错误码了解详情和解决建议。
getUserInfoByUid
通过 UID 获取用户信息。
public abstract UserInfo getUserInfoByUid(int uid, String channelId, String localUserAccount);
远端用户加入频道后，SDK 会获取到该远端用户的 UID 和 User Account，然后缓存一个包含了远端用户 UID 和 User Account 的 Mapping 表，并在本地触发 onUserInfoUpdated 回调。收到这个回调后，你可以调用该方法，通过传入 UID 获取包含了指定用户 User Account 的 UserInfo 对象。
参数
| 参数名 | 描述 |
|---|---|
uid | 用户 ID。 |
channelId | 频道名。该参数标识用户进行实时音视频互动的频道。App ID 一致的前提下，填入相同频道名的用户会进入同一个频道进行音视频互动。该参数为长度在 64 字节以内的字符串。以下为支持的字符集范围（共 89 个字符）:
|
localUserAccount | 本地用户的 User Account。 |
返回值
-
方法调用成功，返回
UserInfo对象。 -
方法调用失败，则返回 NULL。
getUserInfoByUserAccount
通过 User Account 获取用户信息。
public abstract int getUserInfoByUserAccount(String userAccount, UserInfo userInfo);
远端用户加入频道后，SDK 会获取到该远端用户的 UID 和 User Account，然后缓存一个包含了远端用户 UID 和 User Account 的 Mapping 表，并在本地触发 onUserInfoUpdated 回调。收到这个回调后，你可以调用该方法，通过传入 UID 获取包含了指定用户 User Account 的 UserInfo 对象。
参数
| 参数名 | 描述 |
|---|---|
userAccount | 用户 User Account。 |
userInfo | 输入和输出参数。标识用户的
|
getUserInfoByUserAccount
通过 User Account 获取用户信息。
public abstract UserInfo getUserInfoByUserAccount(String userAccount, String channelId, String localUserAccount);
远端用户加入频道后，SDK 会获取到该远端用户的 UID 和 User Account，然后缓存一个包含了远端用户 UID 和 User Account 的 Mapping 表，并在本地触发 onUserInfoUpdated 回调。收到这个回调后，你可以调用该方法，通过传入 UID 获取包含了指定用户 User Account 的 UserInfo 对象。
参数
| 参数名 | 描述 |
|---|---|
userAccount | 用户 User Account。 |
channelId | 频道名。该参数标识用户进行实时音视频互动的频道。App ID 一致的前提下，填入相同频道名的用户会进入同一个频道进行音视频互动。该参数为长度在 64 字节以内的字符串。以下为支持的字符集范围（共 89 个字符）:
|
localUserAccount | 本地用户的 User Account。 |
joinChannel [1/2]
加入频道。
public abstract int joinChannel(
String token, String channelName, String optionalInfo, int optionalUid);
该方法让用户加入通话频道，在同一个频道内的用户可以互相通话，多个用户加入同一个频道，可以群聊。 使用不同 App ID 的 app 不能互通。
成功调用该方法加入频道后会触发以下回调：
-
本地会触发
onJoinChannelSuccess和onConnectionStateChanged回调。 -
通信场景下的用户和直播场景下的主播加入频道后，远端会触发
onUserJoined回调。
在网络状况不理想的情况下，客户端可能会与声网服务器失去连接；SDK 会自动尝试重连，重连成功后，本地会触发 onRejoinChannelSuccess 回调。
注意： 用户成功加入频道后，默认订阅频道内所有其他用户的音频流和视频流，因此产生用量并影响计费。如果想取消订阅，可以通过调用相应的 mute 方法实现。
参数
| 参数名 | 描述 |
|---|---|
token | 在服务端生成的用于鉴权的动态密钥。详见 |
channelId | 频道名。该参数标识用户进行实时音视频互动的频道。App ID 一致的前提下，填入相同频道名的用户会进入同一个频道进行音视频互动。该参数为长度在 64 字节以内的字符串。以下为支持的字符集范围（共 89 个字符）:
|
optionalInfo | (非必选项) 预留参数。 |
optionalUid | 用户 ID。该参数用于标识在实时音视频互动频道中的用户。你需要自行设置和管理用户 ID，并确保同一频道内的每个用户 ID 是唯一的。该参数为 32 位无符号整数。建议设置范围：1 到 232-1。如果不指定（即设为 0），SDK 会自动分配一个，并在 |
返回值
-
0：方法调用成功。
-
< 0：方法调用失败。
-
-2：传入的参数无效。例如，使用了不合法的 Token，
uid参数未设置为整型，ChannelMediaOptions结构体成员值不合法。你需要填入有效的参数，重新加入频道。 -
-3：
RtcEngine对象初始化失败。你需要重新初始化RtcEngine对象。 -
-7：
RtcEngine对象尚未初始化。你需要在调用该方法前成功初始化RtcEngine对象。 -
-8：
RtcEngine对象内部状态错误。可能的原因是：调用startEchoTest [3/3]开始通话回路测试后，未调用stopEchoTest停止测试就调用该方法加入频道。你需要在该方法前调用stopEchoTest。 -
-17：加入频道被拒绝。可能的原因是用户已经在频道中。建议通过
onConnectionStateChanged回调判断用户是否在频道中。除收到CONNECTION_STATE_DISCONNECTED(1) 状态外，不要再次调用该方法加入频道。 -
-102：频道名无效。你需要在
channelId中填入有效的频道名，重新加入频道。 -
-121：用户 ID 无效。你需要在
uid中填入有效的用户 ID，重新加入频道。
-
joinChannel [2/2]
设置媒体选项并加入频道。
public abstract int joinChannel(
String token, String channelId, int uid, ChannelMediaOptions options);
该方法让用户加入通话频道，在同一个频道内的用户可以互相通话，多个用户加入同一个频道，可以群聊。 使用不同 App ID 的 app 不能互通。
成功调用该方法加入频道后会触发以下回调：
-
本地会触发
onJoinChannelSuccess和onConnectionStateChanged回调。 -
通信场景下的用户和直播场景下的主播加入频道后，远端会触发
onUserJoined回调。
在网络状况不理想的情况下，客户端可能会与声网服务器失去连接；SDK 会自动尝试重连，重连成功后，本地会触发 onRejoinChannelSuccess 回调。
相比 joinChannel [1/2]，该方法增加了 options 参数，用于配置用户加入频道时是否自动订阅频道内所有远端音视频流。默认情况下，用户订阅频道内所有其他用户的音频流和视频流，因此会产生用量并影响计费。如果想取消订阅，可以通过设置 options 参数或相应的 mute 方法实现。
注意：
-
该方法允许用户一次加入仅一个频道。
-
请务必确保用于生成 Token 的 App ID 和
create [2/2]方法初始化引擎时用的是同一个 App ID，否则使用 Token 加入频道失败。
参数
| 参数名 | 描述 |
|---|---|
token | 在服务端生成的用于鉴权的动态密钥。详见 |
channelId | 频道名。该参数标识用户进行实时音视频互动的频道。App ID 一致的前提下，填入相同频道名的用户会进入同一个频道进行音视频互动。该参数为长度在 64 字节以内的字符串。以下为支持的字符集范围（共 89 个字符）:
|
uid | 用户 ID。该参数用于标识在实时音视频互动频道中的用户。你需要自行设置和管理用户 ID，并确保同一频道内的每个用户 ID 是唯一的。该参数为 32 位无符号整数。建议设置范围：1 到 232-1。如果不指定（即设为 0），SDK 会自动分配一个，并在 |
options | 频道媒体设置选项。详见 |
返回值
-
0：方法调用成功。
-
< 0：方法调用失败。
-
-2：传入的参数无效。例如，使用了不合法的 Token，
uid参数未设置为整型，ChannelMediaOptions结构体成员值不合法。你需要填入有效的参数，重新加入频道。 -
-3：
RtcEngine对象初始化失败。你需要重新初始化RtcEngine对象。 -
-7：
RtcEngine对象尚未初始化。你需要在调用该方法前成功初始化RtcEngine对象。 -
-8：
RtcEngine对象内部状态错误。可能的原因是：调用startEchoTest [3/3]开始通话回路测试后，未调用stopEchoTest停止测试就调用该方法加入频道。你需要在该方法前调用stopEchoTest。 -
-17：加入频道被拒绝。可能的原因是用户已经在频道中。建议通过
onConnectionStateChanged回调判断用户是否在频道中。除收到CONNECTION_STATE_DISCONNECTED(1) 状态外，不要再次调用该方法加入频道。 -
-102：频道名无效。你需要在
channelId中填入有效的频道名，重新加入频道。 -
-121：用户 ID 无效。你需要在
uid中填入有效的用户 ID，重新加入频道。
-
joinChannelEx
使用连接 ID 加入频道。
public abstract int joinChannelEx(String token, RtcConnection connection,
ChannelMediaOptions options, IRtcEngineEventHandler eventHandler);
调用该方法，你可以同时加入多个频道。
注意：
-
如果你已经在一个频道内，你不能用相同的用户 UID 再次加入该频道。
-
如果你想在不同的设备上加入相同的频道，请确保你在不同设备上使用的用户 UID 都不同。
-
请确保生成 Token 时传入的 app ID 和创建
RtcEngine实例时传入的 app ID 一致。
参数
| 参数名 | 描述 |
|---|---|
token | 在服务端生成的用于鉴权的动态密钥。详见 |
connection | Connection 信息。详见 |
options | 频道媒体设置选项。详见 |
eventHandler |
|
返回值
-
0：方法调用成功。
-
< 0：方法调用失败。
-
-2：传入的参数无效。例如，使用了不合法的 Token，
uid参数未设置为整型，ChannelMediaOptions结构体成员值不合法。你需要填入有效的参数，重新加入频道。 -
-3：
RtcEngine对象初始化失败。你需要重新初始化RtcEngine对象。 -
-7：
RtcEngine对象尚未初始化。你需要在调用该方法前成功初始化RtcEngine对象。 -
-8：
RtcEngine对象内部状态错误。可能的原因是：调用startEchoTest [3/3]开始通话回路测试后，未调用stopEchoTest停止测试就调用该方法加入频道。你需要在该方法前调用stopEchoTest。 -
-17：加入频道被拒绝。可能的原因是用户已经在频道中。建议通过
onConnectionStateChanged回调判断用户是否在频道中。除收到CONNECTION_STATE_DISCONNECTED(1) 状态外，不要再次调用该方法加入频道。 -
-102：频道名无效。你需要在
channelId中填入有效的频道名，重新加入频道。 -
-121：用户 ID 无效。你需要在
uid中填入有效的用户 ID，重新加入频道。
-
joinChannelWithUserAccount [1/2]
使用 User Account 和 Token 加入频道。
public abstract int joinChannelWithUserAccount(
String token, String channelName, String userAccount);
该方法允许本地用户使用 User Account 和 Token 加入频道。成功加入频道后，会触发以下回调：
-
本地：
onLocalUserRegistered、onJoinChannelSuccess和onConnectionStateChanged回调。 -
通信场景下的用户和直播场景下的主播加入频道后，远端会依次触发
onUserJoined和onUserInfoUpdated回调。
用户成功加入频道后，默认订阅频道内所有其他用户的音频流和视频流，因此产生用量并影响计费。如果想取消订阅，可以通过调用相应的 mute 方法实现。
注意： 为保证通信质量，请确保频道内使用同一类型的数据标识用户身份。即同一频道内需要统一使用 UID 或 User Account。如果有用户通过 Web SDK 加入频道，请确保 Web 加入的用户也是同样类型。
参数
| 参数名 | 描述 |
|---|---|
token | 在服务端生成的用于鉴权的动态密钥。详见 |
channelName | 频道名。该参数标识用户进行实时音视频互动的频道。App ID 一致的前提下，填入相同频道名的用户会进入同一个频道进行音视频互动。该参数为长度在 64 字节以内的字符串。以下为支持的字符集范围（共 89 个字符）:
|
userAccount | 用户 User Account。该参数用于标识实时音视频互动频道中的用户。你需要自行设置和管理用户的 User Account，并确保同一频道中每个用户的 User Account 是唯一的。 该参数为必填，最大不超过 255 字节，不可填 NULL。以下为支持的字符集范围（共 89 个字符）：
|
返回值
-
0: 方法调用成功。
-
< 0: 方法调用失败。详见
错误码了解详情和解决建议。
joinChannelWithUserAccount [2/2]
使用 User Account 和 Token 加入频道，并设置是否自动订阅音频或视频流。
public abstract int joinChannelWithUserAccount(
String token, String channelName, String userAccount, ChannelMediaOptions options);
该方法允许本地用户使用 User Account 加入频道。成功加入频道后，会触发以下回调：
-
本地：
onLocalUserRegistered、onJoinChannelSuccess和onConnectionStateChanged回调。 -
远端：通信场景下的用户和直播场景下的主播加入频道后，远端会分别触发
onUserJoined和onUserInfoUpdated回调。
用户成功加入频道后，默认订阅频道内所有其他用户的音频流和视频流，因此产生用量并影响计费。如果想取消订阅，可以通过调用相应的 mute 方法实现。
相比 joinChannelWithUserAccount [1/2]，该方法加了 options 参数，用于配置用户加入频道时是否自动订阅频道内所有远端音视频流。默认情况下，用户订阅频道内所有其他用户的音频流和视频流，因此会产生用量并影响计费。如果想取消订阅，可以通过设置 options 参数或相应的 mute 方法实现。
注意： 为保证通信质量，请确保频道内使用同一类型的数据标识用户身份。即同一频道内需要统一使用 UID 或 User Account。如果有用户通过 Web SDK 加入频道，请确保 Web 加入的用户也是同样类型。
参数
| 参数名 | 描述 |
|---|---|
token | 在服务端生成的用于鉴权的动态密钥。详见 |
channelName | 频道名。该参数标识用户进行实时音视频互动的频道。App ID 一致的前提下，填入相同频道名的用户会进入同一个频道进行音视频互动。该参数为长度在 64 字节以内的字符串。以下为支持的字符集范围（共 89 个字符）:
|
userAccount | 用户 User Account。该参数用于标识实时音视频互动频道中的用户。你需要自行设置和管理用户的 User Account，并确保同一频道中每个用户的 User Account 是唯一的。 该参数为必填，最大不超过 255 字节，不可填 NULL。以下为支持的字符集范围（共 89 个字符）：
|
options | 频道媒体设置选项。详见 |
joinChannelWithUserAccountEx
使用 User Account 加入频道，并设置是否自动订阅音频或视频流。
public abstract int joinChannelWithUserAccountEx(String token, String channelId,
String userAccount, ChannelMediaOptions options, IRtcEngineEventHandler eventHandler);
该方法允许本地用户使用 User Account 加入频道。成功加入频道后，会触发以下回调：
-
本地：
onLocalUserRegistered、onJoinChannelSuccess和onConnectionStateChanged回调。 -
远端：通信场景下的用户和直播场景下的主播加入频道后，远端会分别触发
onUserJoined和onUserInfoUpdated回调。
用户成功加入频道后，默认订阅频道内所有其他用户的音频流和视频流，因此产生用量并影响计费。如果想取消订阅，可以通过调用相应的 mute 方法实现。
注意： 为保证通信质量，请确保频道内使用同一类型的数据标识用户身份。即同一频道内需要统一使用 UID 或 User Account。如果有用户通过 Web SDK 加入频道，请确保 Web 加入的用户也是同样类型。
参数
| 参数名 | 描述 |
|---|---|
token | 在服务端生成的用于鉴权的动态密钥。详见 |
channelId | 频道名。该参数标识用户进行实时音视频互动的频道。App ID 一致的前提下，填入相同频道名的用户会进入同一个频道进行音视频互动。该参数为长度在 64 字节以内的字符串。以下为支持的字符集范围（共 89 个字符）:
|
userAccount | 用户 User Account。该参数用于标识实时音视频互动频道中的用户。你需要自行设置和管理用户的 User Account，并确保同一频道中每个用户的 User Account 是唯一的。 该参数为必填，最大不超过 255 字节，不可填 NULL。以下为支持的字符集范围（共 89 个字符）：
|
options | 频道媒体设置选项。详见 |
eventHandler |
|
返回值
-
0: 方法调用成功。
-
< 0: 方法调用失败。详见
错误码了解详情和解决建议。
leaveChannel [1/2]
离开频道。
public abstract int leaveChannel();
该方法会把会话相关的所有资源释放掉。
该方法是异步操作，调用返回时并没有真正退出频道。
成功加入频道后，必须调用本方法或者 leaveChannel [2/2] 结束通话，否则无法开始下一次通话。
成功调用该方法、并且离开频道后会触发以下回调：
-
本地：
onLeaveChannel回调。 -
远端：通信场景下的用户和直播场景下的主播离开频道后，远端会触发
onUserOffline回调。
注意：
-
如果你调用了本方法后立即调用
destroy方法，SDK 将无法触发onLeaveChannel回调。 -
如果你已调用
joinChannelEx加入多频道，调用本方法后会同时离开joinChannel [2/2]和joinChannelEx加入的频道。
返回值
-
0(ERR_OK): 方法调用成功。
-
< 0: 方法调用失败。详见
错误码了解详情和解决建议。-
-1: 一般性的错误（未明确归类）。
-
-2: 参数无效。
-
-7: SDK 尚未初始化。
-
leaveChannel [2/2]
设置频道选项并离开频道。
public abstract int leaveChannel(LeaveChannelOptions options);
该方法会把会话相关的所有资源释放掉，离开频道，即挂断或退出通话。不管当前是否在通话中均可以调用该方法。
加入频道后，必须调用本方法结束通话，才能开始下一次通话。
该方法是异步操作，调用返回时并没有真正退出频道。在真正退出频道后，本地会触发 onLeaveChannel 回调；通信场景下的用户和直播场景下的主播离开频道后，远端会触发 onUserOffline 回调。
注意：
-
如果你调用了本方法后立即调用
destroy方法，SDK 将无法触发onLeaveChannel回调。 -
如果你已调用
joinChannelEx加入多频道，调用本方法后会同时离开joinChannel [2/2]和joinChannelEx加入的频道。
参数
| 参数名 | 描述 |
|---|---|
options | 离开频道的选项，详见 |
返回值
-
0: 方法调用成功。
-
< 0: 方法调用失败。详见
错误码了解详情和解决建议。
leaveChannelEx [1/2]
离开频道。
public abstract int leaveChannelEx(RtcConnection connection);
离开频道，即挂断或退出通话。
调用 joinChannelEx 加入频道后，必须调用本方法结束通话，才能开始下一次通话。
不管当前是否在通话中，都可以调用该方法。该方法会把会话相关的所有资源释放掉。
该方法是异步操作，调用返回时并没有真正退出频道。在真正退出频道后，SDK 会触发 onLeaveChannel 回调。
成功调用该方法离开频道后，本地会触发 onLeaveChannel 回调；通信场景下的用户和直播场景下的主播离开频道后，远端会触发 onUserOffline 回调。
注意：
-
如果你调用了本方法后立即调用
destroy方法，SDK 将无法触发onLeaveChannel回调。 -
调用
leaveChannel [1/2]后会同时离开joinChannel [2/2]和joinChannelEx加入的频道。
参数
| 参数名 | 描述 |
|---|---|
connection | Connection 信息。详见 |
返回值
-
0: 方法调用成功。
-
< 0: 方法调用失败。详见
错误码了解详情和解决建议。
leaveChannelEx [2/2]
设置频道选项并离开频道。
public abstract int leaveChannelEx(RtcConnection connection, LeaveChannelOptions options);
离开频道，即挂断或退出通话。
调用 joinChannelEx 加入频道后，必须调用本方法结束通话，才能开始下一次通话。
不管当前是否在通话中，都可以调用该方法。该方法会把会话相关的所有资源释放掉。
该方法是异步操作，调用返回时并没有真正退出频道。在真正退出频道后，SDK 会触发 onLeaveChannel 回调。
成功调用该方法离开频道后，本地会触发 onLeaveChannel 回调；通信场景下的用户和直播场景下的主播离开频道后，远端会触发 onUserOffline 回调。
注意：
-
如果你调用了本方法后立即调用
destroy方法，SDK 将无法触发onLeaveChannel回调。 -
调用
leaveChannel [2/2]后会同时离开joinChannel [2/2]和joinChannelEx加入的频道。
参数
| 参数名 | 描述 |
|---|---|
connection | Connection 信息。详见 |
options | 自从 v4.1.0离开频道的选项，详见 LeaveChannelOptions。注： 该参数仅支持设置 LeaveChannelOptions 中的 stopMicrophoneRecording 成员，设置其他成员均不生效。 |
返回值
-
0: 方法调用成功。
-
< 0: 方法调用失败。详见
错误码了解详情和解决建议。
preloadChannel[1/2]
使用 token、channelName、optionalUid 预加载频道。
public abstract int preloadChannel(String token, String channelName, int optionalUid);
v4.2.2
调用该方法可以减少观众频繁切换频道时加入频道的时间，从而缩短观众听到主播首帧音频以及看到首帧画面的耗时，提升观众端的视频体验。由于 SDK 预加载频道需要一定的时间，因此声网推荐你在确认频道信息和用户信息后、加入频道前，尽早调用该方法。
注：
-
调用该方法时，请确保用户角色设为观众、音频应用场景设为非合唱场景（
AUDIO_SCENARIO_CHORUS），否则预加载不生效。 -
请确保预加载频道时传入的频道名、用户 ID、Token 和后续加入频道时传入的值相同，否则预加载不生效。
-
目前一个
RtcEngine实例最多支持预加载 20 个频道，如超出限制，仅最新预加载的 20 频道个生效。 -
预加载不生效不会影响后续正常加入频道，也不会增加加入频道的耗时。
如果当前频道已经成功预加载，观众加入、离开频道后如需再次加入该频道，只要预加载时传入的 Token 仍在有效期内，则无需重新预加载。
参数
| 参数名 | 描述 |
|---|---|
token | 在服务端生成的用于鉴权的动态密钥。详见
|
channelName | 待预加载的频道名。该参数标识用户进行实时音视频互动的频道。App ID 一致的前提下，填入相同频道名的用户会进入同一个频道进行音视频互动。
|
optionalUid | 用户 ID。该参数用于标识在实时音视频互动频道中的用户。你需要自行设置和管理用户 ID，并确保同一频道内的每个用户 ID 是唯一的。该参数为 32 位无符号整数。建议设置范围：1 到 232-1。如果不指定（即设为 0），SDK 会自动分配一个，并在 |
返回值
-
0：方法调用成功。
-
< 0：方法调用失败。
-
-7：
RtcEngine对象尚未初始化。你需要在调用该方法前成功初始化RtcEngine对象。 -
-102：频道名无效。你需要填入有效的频道名，重新加入频道。
-
preloadChannel[2/2]
使用 token、channelName、userAccount 预加载频道。
public abstract int preloadChannel(String token, String channelName, String userAccount);
v4.2.2
调用该方法可以减少观众频繁切换频道时加入频道的时间，从而缩短观众听到主播首帧音频以及看到首帧画面的耗时，提升观众端的视频体验。由于 SDK 预加载频道需要一定的时间，因此声网推荐你在确认频道信息和用户信息后、加入频道前，尽早调用该方法。
注：
-
调用该方法时，请确保用户角色设为观众、音频应用场景设为非合唱场景（
AUDIO_SCENARIO_CHORUS），否则预加载不生效。 -
请确保预加载频道时传入的频道名、用户 User Account、Token 和后续加入频道时传入的值相同，否则预加载不生效。
-
目前一个
RtcEngine实例最多支持预加载 20 个频道，如超出限制，仅最新预加载的 20 频道个生效。 -
预加载不生效不会影响后续正常加入频道，也不会增加加入频道的耗时。
如果当前频道已经成功预加载，观众加入、离开频道后如需再次加入该频道，只要预加载时传入的 Token 仍在有效期内，则无需重新预加载。
参数
| 参数名 | 描述 |
|---|---|
token | 在服务端生成的用于鉴权的动态密钥。详见
|
channelName | 待预加载的频道名。该参数标识用户进行实时音视频互动的频道。App ID 一致的前提下，填入相同频道名的用户会进入同一个频道进行音视频互动。
|
userAccount | 用户 User Account。该参数用于标识实时音视频互动频道中的用户。你需要自行设置和管理用户的 User Account，并确保同一频道中每个用户的 User Account 是唯一的。 该参数为必填，最大不超过 255 字节，不可填 NULL。以下为支持的字符集范围（共 89 个字符）：
|
返回值
-
0：方法调用成功。
-
< 0：方法调用失败。
-
-2：传入的参数无效。例如，User Account 为空。你需要填入有效的参数，重新加入频道。
-
-7：
RtcEngine对象尚未初始化。你需要在调用该方法前成功初始化RtcEngine对象。 -
-102：频道名无效。你需要填入有效的频道名，重新加入频道。
-
registerLocalUserAccount
注册本地用户 User Account。
public abstract int registerLocalUserAccount(String appId, String userAccount);
该方法为本地用户注册一个 User Account。注册成功后，该 User Account 即可标识该本地用户的身份，用户可以使用它加入频道。
成功注册 User Account 后，本地会触发 onLocalUserRegistered 回调，告知本地用户的 UID 和 User Account。
该方法为可选。如果你希望用户使用 User Account 加入频道，可以选用以下两种方式：
-
先调用
registerLocalUserAccount方法注册 Account，再调用joinChannelWithUserAccount [2/2]方法加入频道。 -
直接调用
joinChannelWithUserAccount [2/2]方法加入频道。
两种方式的区别在于，提前调用 registerLocalUserAccount，可以缩短使用 joinChannelWithUserAccount [2/2] 进入频道的时间。
注意：
-
userAccount不能为空，否则该方法不生效。 -
请确保在该方法中设置的
userAccount在频道中的唯一性。 -
为保证通信质量，请确保频道内使用同一类型的数据标识用户身份。即同一频道内需要统一使用 UID 或 User Account。 如果有用户通过 Web SDK 加入频道，请确保 Web 加入的用户也是同样类型。
参数
| 参数名 | 描述 |
|---|---|
appId | 你的项目在控制台注册的 App ID。 |
userAccount | 用户 User Account。该参数用于标识实时音视频互动频道中的用户。你需要自行设置和管理用户的 User Account，并确保同一频道中每个用户的 User Account 是唯一的。该参数为必填，最大不超过 255 字节，不可填 NULL。以下为支持的字符集范围（共 89 个字符）：
|
返回值
-
0: 方法调用成功。
-
< 0: 方法调用失败。详见
错误码了解详情和解决建议。
renewToken
更新 Token。
public abstract int renewToken(String token);
-
发生
onTokenPrivilegeWillExpire回调时。 -
onConnectionStateChanged回调报告CONNECTION_CHANGED_TOKEN_EXPIRED(9) 时。
参数
| 参数名 | 描述 |
|---|---|
token | 新的 Token。 |
返回值
-
0: 方法调用成功。
-
< 0: 方法调用失败。
-
-2：传入的参数无效。例如，使用了不合法的 Token。你需要填入有效的参数。
-
-7：
RtcEngine对象尚未初始化。你需要在调用该方法前成功初始化RtcEngine对象。
-
setChannelProfile
设置频道场景。
public abstract int setChannelProfile(int profile);
SDK 初始化后默认的频道场景为直播场景。你可以调用该方法设置频道的使用场景。SDK 会针对不同的使用场景采用不同的优化策略，如通信场景偏好流畅，直播场景偏好画质。
注意：
-
为保证实时音视频质量，相同频道内的用户必须使用同一种频道场景。
-
该方法必须在
joinChannel [2/2]前调用和进行设置，进入频道后无法再设置。 -
不同的频道场景下，SDK 的默认音频路由和默认视频编码码率是不同的，详见
setDefaultAudioRouteToSpeakerphone和setVideoEncoderConfiguration中的说明。
参数
| 参数名 | 描述 |
|---|---|
profile | 频道使用场景。
|
返回值
-
0(ERR_OK) 方法调用成功。
-
< 0 方法调用失败。
-
-2: 参数无效。
-
-7: SDK 尚未初始化。
-
setClientRole [1/2]
设置用户角色。
public abstract int setClientRole(int role);
在加入频道前和加入频道后均可调用该方法设置用户角色。
如果你在加入频道前调用该方法设置用户角色为主播、并且通过 setupLocalVideo 方法设置了本地视频属性，则用户加入频道时会自动开启本地视频预览。
如果你在加入频道后调用该方法切换用户角色，调用成功后：
-
本地会触发
onClientRoleChanged回调。 -
远端会触发
onUserJoined或onUserOffline(USER_OFFLINE_BECOME_AUDIENCE)回调。
参数
| 参数名 | 描述 |
|---|---|
role | 用户的角色：
|
返回值
-
0: 方法调用成功。
-
< 0: 方法调用失败。
-
-1: 一般性的错误（未明确归类）。
-
-2: 参数无效。
-
-7: SDK 尚未初始化。
-
setClientRole [2/2]
设置直播场景下的用户角色和级别。
public abstract int setClientRole(int role, ClientRoleOptions options);
直播场景下，SDK 会默认设置用户角色为观众，你可以调用该方法设置用户角色为主播。
该方法在加入频道前后均可调用。
如果你在加入频道前调用该方法设置用户角色为主播、并且通过 setupLocalVideo 方法设置了本地视频属性，则用户加入频道时会自动开启本地视频预览。
如果你在加入频道后调用该方法切换用户角色，调用成功后，SDK 会自动进行如下操作：
-
调用
muteLocalAudioStream和muteLocalVideoStream修改发布状态。 -
本地触发
onClientRoleChanged回调。 -
远端触发
onUserJoined或onUserOffline回调。
该方法与 setClientRole [1/2] 的区别在于，该方法还支持设置用户级别。
-
用户角色（
role）确定用户在 SDK 层的权限，包含是否可以发送流、是否可以接收流、是否可以旁路推流等。 -
用户级别（
level）需要与角色结合使用，确定用户在其权限范围内可以享受到的服务。例如对于观众，选择接收低延时还是超低延时的视频流。不同的级别会影响计费。
注意： 该方法仅适用于直播场景（setChannelProfile 中 profile 设为 CHANNEL_PROFILE_LIVE_BROADCASTING）。
参数
| 参数名 | 描述 |
|---|---|
role | 直播场景中的用户角色。
|
options | 用户具体设置，包含用户级别。详见 |
返回值
-
0: 方法调用成功。
-
< 0: 方法调用失败。详见
错误码了解详情和解决建议。-
-1: 一般性的错误（未明确归类）。
-
-2: 参数无效。
-
-5: 调用被拒绝。
-
-7: SDK 尚未初始化。
-
updateChannelMediaOptions
加入频道后更新频道媒体选项。
public abstract int updateChannelMediaOptions(ChannelMediaOptions options);
参数
| 参数名 | 描述 |
|---|---|
options | 频道媒体选项，详见 |
返回值
-
0: 方法调用成功。
-
< 0: 方法调用失败。
-
-2：
ChannelMediaOptions结构体成员值设置无效。例如，使用了不合法的 Token，设置了无效的用户角色。你需要填入有效的参数。 -
-7：
RtcEngine对象尚未初始化。你需要在调用该方法前成功初始化RtcEngine对象。 -
-8：
RtcEngine对象内部状态错误。可能的原因是用户不在频道中。建议通过onConnectionStateChanged回调判断用户是否在频道中。如果收到CONNECTION_STATE_DISCONNECTED(1) 或CONNECTION_STATE_FAILED(5)，则表示用户不在频道中。你需要在调用该方法前调用joinChannel [2/2]加入频道。
-
updateChannelMediaOptionsEx
加入频道后更新频道媒体选项 。
public abstract int updateChannelMediaOptionsEx(
ChannelMediaOptions options, RtcConnection connection);
参数
| 参数名 | 描述 |
|---|---|
options | 频道媒体选项，详见 |
connection | Connection 信息。详见 |
返回值
-
0: 方法调用成功。
-
< 0: 方法调用失败。
-
-2：
ChannelMediaOptions结构体成员值设置无效。例如，使用了不合法的 Token，设置了无效的用户角色。你需要填入有效的参数。 -
-7：
RtcEngine对象尚未初始化。你需要在调用该方法前成功初始化RtcEngine对象。 -
-8：
RtcEngine对象内部状态错误。可能的原因是用户不在频道中。建议通过onConnectionStateChanged回调判断用户是否在频道中。如果收到CONNECTION_STATE_DISCONNECTED(1) 或CONNECTION_STATE_FAILED(5)，则表示用户不在频道中。你需要在调用该方法前调用joinChannel [2/2]加入频道。
-
updatePreloadChannelToken
更新预加载频道的通配 Token。
public abstract int updatePreloadChannelToken(String token);
v4.2.2
你需要自行维护通配 Token 的生命周期。当通配 Token 过期后，你需要在你的服务端生成新的通配 Token，然后通过此方法来传入新的 Token。
参数
| 参数名 | 描述 |
|---|---|
token | 新的 Token。 |
返回值
-
0: 方法调用成功。
-
< 0: 方法调用失败。详见
错误码了解详情和解决建议。 -
-2：传入的参数无效。例如，使用了不合法的 Token。你需要填入有效的参数，重新加入频道。
-
-7：
RtcEngine对象尚未初始化。你需要在调用该方法前成功初始化RtcEngine对象。
onClientRoleChanged
直播场景下用户角色已切换回调。
public void onClientRoleChanged(int oldRole, int newRole, ClientRoleOptions newRoleOptions) {}
该回调是由本地用户在加入频道后调用 setClientRole [2/2] 改变用户角色触发的。
参数
| 参数名 | 描述 |
|---|---|
oldRole | 切换前的角色：
|
newRole | 切换后的角色：
|
newRoleOptions | 自从 v4.1.0切换后的角色属性。详见 ClientRoleOptions。 |
onClientRoleChangeFailed
直播场景下切换用户角色失败回调。
public void onClientRoleChangeFailed(int reason, int currentRole) {}
直播场景下，本地用户加入频道后调用 setClientRole [2/2] 切换用户角色失败时，SDK 会触发该回调，报告切换失败的原因和当前的用户角色。
参数
| 参数名 | 描述 |
|---|---|
reason | 切换用户角色失败的原因。
|
currentRole | 当前用户角色。
|
onError
发生错误回调。
public void onError(int err) {}
该回调方法表示 SDK 运行时出现了网络或媒体相关的错误。通常情况下，SDK 上报的错误意味着 SDK 无法自动恢复，需要 app 干预或提示用户。
参数
| 参数名 | 描述 |
|---|---|
err | 错误码。 |
onJoinChannelSuccess
成功加入频道回调。
public void onJoinChannelSuccess(String channel, int uid, int elapsed) {}
该回调方法表示该客户端成功加入了指定的频道。
参数
| 参数名 | 描述 |
|---|---|
channel | 频道名。 |
uid | 加入频道的用户 ID。 |
elapsed | 从本地调用 |
onLeaveChannel
离开频道回调。
public void onLeaveChannel(RtcStats stats) {}
App 调用 leaveChannel [2/2] 方法时，SDK 提示 app 离开频道成功。在该回调方法中，app 可以得到此次通话的总通话时长、SDK 收发数据的流量等信息。
参数
| 参数名 | 描述 |
|---|---|
stats | 通话的统计数据: |
onLocalUserRegistered
本地用户成功注册 User Account 回调。
public void onLocalUserRegistered(int uid, String userAccount) {}
本地用户成功调用 registerLocalUserAccount 方法注册用户 User Account，或调用 joinChannelWithUserAccount [2/2] 加入频道后，SDK 会触发该回调，并告知本地用户的 UID 和 User Account。
参数
| 参数名 | 描述 |
|---|---|
uid | 本地用户的 ID。 |
userAccount | 本地用户的 User Account。 |
onRejoinChannelSuccess
成功重新加入频道回调。
public void onRejoinChannelSuccess(String channel, int uid, int elapsed) {}
有时候由于网络原因，客户端可能会和服务器失去连接，SDK 会进行自动重连，自动重连成功后触发此回调方法。
参数
| 参数名 | 描述 |
|---|---|
channel | 频道名。 |
uid | 重新加入频道的用户 ID。 |
elapsed | 从调用 |
onRequestToken
Token 已过期回调。
public void onRequestToken() {}
在通话过程中如果 Token 已失效，SDK 会触发该回调，提醒 app 更新 Token。
当收到该回调时，你需要重新在服务端生成新的 Token，然后通过下列任意一种方式来更新 Token：
-
调用
renewToken来传入新的 Token。 -
调用
leaveChannel [2/2]离开当前频道，然后在调用joinChannel [2/2]时传入新的 Token 重新加入频道。
onRtcStats
onTokenPrivilegeWillExpire
Token 服务将在30s内过期回调。
public void onTokenPrivilegeWillExpire(String token) {}
在通话过程中如果 Token 即将失效，SDK 会提前 30 秒触发该回调，提醒 app 更新 Token。
当收到该回调时，你需要重新在服务端生成新的 Token，然后调用 renewToken 将新生成的 Token 传给 SDK。在多频道场景下，你需要调用 updateChannelMediaOptionsEx 来传入新的 Token。
参数
| 参数名 | 描述 |
|---|---|
token | 即将服务失效的 Token。 |
onUserInfoUpdated
onUserJoined
远端用户（通信场景）/主播（直播场景）加入当前频道回调。
public void onUserJoined(int uid, int elapsed) {}
-
通信场景下，该回调提示有远端用户加入了频道。如果加入之前，已经有其他用户在频道中了，新加入的用户也会收到这些已有用户加入频道的回调。
-
直播场景下，该回调提示有主播加入了频道。如果加入之前，已经有主播在频道中了，新加入的用户也会收到已有主播加入频道的回调。建议连麦主播不超过 17 人。
该回调在如下情况下会被触发：
-
远端用户/主播加入频道。
-
远端用户加入频道后将用户角色改变为主播。
-
远端用户/主播网络中断后重新加入频道。
参数
| 参数名 | 描述 |
|---|---|
uid | 新加入频道的远端用户/主播 ID。 |
elapsed | 从本地用户调用 |
onUserOffline
远端用户（通信场景）/主播（直播场景）离开当前频道回调。
public void onUserOffline(int uid, int reason) {}
用户离开频道有两个原因：
-
正常离开：远端用户/主播会发送类似“再见”的消息。接收此消息后，判断用户离开频道。
-
超时掉线：在一定时间内（通信场景为 20 秒，直播场景稍有延时），用户没有收到对方的任何数据包，则判定为对方掉线。在网络较差的情况下，有可能会误报。建议使用云信令 SDK 来做可靠的掉线检测。
参数
| 参数名 | 描述 |
|---|---|
uid | 离线用户或主播的用户 ID。 |
reason | 远端用户（通信场景）或主播（直播场景）下线的原因：
|