# 频道相关 (/zh-CN/api-reference/rtc/cpp-all-platforms/channel)

> For AI agents: see the complete documentation index at [llms.txt](/llms.txt).

<a id="toc_channel"></a>

<a id="api_irtcengine_getuserinfobyuid"></a>

<a id="ariaid-title2"></a>

## getUserInfoByUid [#getuserinfobyuid]

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

<a id="api_irtcengine_getuserinfobyuid__prototype"></a>

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

<a id="api_irtcengine_getuserinfobyuid__detailed_desc"></a>

当远端用户加入频道后，SDK 会获取该远端用户的用户 ID 和用户 User Account，并将其缓存在一个映射表中，并在本地客户端触发 [onUserInfoUpdated](/zh-CN/api-reference/rtc/cpp-all-platforms/channel#callback_irtcengineeventhandler_onuserinfoupdated) 回调。收到该回调后，你可以调用 [getUserInfoByUid](/zh-CN/api-reference/rtc/cpp-all-platforms/channel#api_irtcengine_getuserinfobyuid) 并传入用户 ID，从 [UserInfo](/zh-CN/api-reference/rtc/cpp-all-platforms/class-userinfo) 对象中获取对应的用户 User Account。

<a id="api_irtcengine_getuserinfobyuid__timing"></a>

### 调用时机 [#调用时机]

在收到 [onUserInfoUpdated](/zh-CN/api-reference/rtc/cpp-all-platforms/channel#callback_irtcengineeventhandler_onuserinfoupdated) 回调后调用该方法。

<a id="api_irtcengine_getuserinfobyuid__parameters"></a>

### 参数 [#参数]

<ParameterList>
<a id="uid"></a>
<Parameter name="uid">

`uid`，表示用户 ID。

</Parameter>
<a id="userinfo"></a>
<Parameter name="userInfo">

输入和输出参数，表示用户信息。输入值为一个 [UserInfo](/zh-CN/api-reference/rtc/cpp-all-platforms/class-userinfo) 对象，输出值为一个包含用户 User Account 和用户 ID 的 [UserInfo](/zh-CN/api-reference/rtc/cpp-all-platforms/class-userinfo) 对象。详见 [UserInfo](/zh-CN/api-reference/rtc/cpp-all-platforms/class-userinfo)。

</Parameter>
</ParameterList>

<a id="api_irtcengine_getuserinfobyuid__return_values"></a>

### 返回值 [#返回值]

- 0：方法调用成功。
- &lt; 0：方法调用失败。详见[错误码](/zh-CN/api-reference/rtc/error-code)了解详情和解决建议。

### 所属接口类 [#所属接口类]

- [IRtcEngine](/zh-CN/api-reference/rtc/cpp-all-platforms/rtc-interface-class#class_irtcengine)

<a id="api_irtcengineex_getuserinfobyuidex"></a>

<a id="ariaid-title3"></a>

## getUserInfoByUidEx [#getuserinfobyuidex]

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

<a id="api_irtcengineex_getuserinfobyuidex__prototype"></a>

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

<a id="api_irtcengineex_getuserinfobyuidex__detailed_desc"></a>

该方法通过传入用户 ID 获取用户信息。功能与 [getUserInfoByUid](/zh-CN/api-reference/rtc/cpp-all-platforms/channel#api_irtcengine_getuserinfobyuid) 相同。

<a id="api_irtcengineex_getuserinfobyuidex__scenario"></a>

### 适用场景 [#适用场景]

适用于多频道场景。

<a id="api_irtcengineex_getuserinfobyuidex__parameters"></a>

### 参数 [#参数-1]

<ParameterList>
<a id="uid-1"></a>
<Parameter name="uid">

远端用户的用户 ID。

</Parameter>
<a id="userinfo-1"></a>
<Parameter name="userInfo">

输入和输出参数，用于标识用户的 [UserInfo](/zh-CN/api-reference/rtc/cpp-all-platforms/class-userinfo) 对象。调用该方法时传入的 [UserInfo](/zh-CN/api-reference/rtc/cpp-all-platforms/class-userinfo) 对象，在方法调用成功后返回包含用户 User Account 和用户 ID 的 [UserInfo](/zh-CN/api-reference/rtc/cpp-all-platforms/class-userinfo) 对象。详见 [UserInfo](/zh-CN/api-reference/rtc/cpp-all-platforms/class-userinfo)。

</Parameter>
<a id="connection"></a>
<Parameter name="connection">

[RtcConnection](/zh-CN/api-reference/rtc/cpp-all-platforms/class-rtcconnection) 对象。详见 [RtcConnection](/zh-CN/api-reference/rtc/cpp-all-platforms/class-rtcconnection)。

</Parameter>
</ParameterList>

<a id="api_irtcengineex_getuserinfobyuidex__return_values"></a>

### 返回值 [#返回值-1]

- 0：方法调用成功。
- &lt; 0：方法调用失败。详见[错误码](/zh-CN/api-reference/rtc/error-code)了解详情和解决建议。

### 所属接口类 [#所属接口类-1]

- [IRtcEngineEx](/zh-CN/api-reference/rtc/cpp-all-platforms/rtc-interface-class#class_irtcengineex)

<a id="api_irtcengine_getuserinfobyuseraccount"></a>

<a id="ariaid-title4"></a>

## getUserInfoByUserAccount [#getuserinfobyuseraccount]

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

<a id="api_irtcengine_getuserinfobyuseraccount__prototype"></a>

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

<a id="api_irtcengine_getuserinfobyuseraccount__detailed_desc"></a>

远端用户加入频道后，SDK 会获取该远端用户的用户 ID 和用户 User Account，并将其缓存在映射表中，同时在本地客户端触发 [onUserInfoUpdated](/zh-CN/api-reference/rtc/cpp-all-platforms/channel#callback_irtcengineeventhandler_onuserinfoupdated) 回调。收到该回调后，你可以调用该方法并传入用户 User Account，从 [UserInfo](/zh-CN/api-reference/rtc/cpp-all-platforms/class-userinfo) 对象中获取该远端用户的用户 ID。

<a id="api_irtcengine_getuserinfobyuseraccount__timing"></a>

### 调用时机 [#调用时机-1]

在收到 [onUserInfoUpdated](/zh-CN/api-reference/rtc/cpp-all-platforms/channel#callback_irtcengineeventhandler_onuserinfoupdated) 回调后调用该方法。

<a id="api_irtcengine_getuserinfobyuseraccount__parameters"></a>

### 参数 [#参数-2]

<ParameterList>
<a id="useraccount"></a>
<Parameter name="userAccount">

用户 User Account。

</Parameter>
<a id="userinfo-2"></a>
<Parameter name="userInfo">

输出参数，表示用户信息。详见 [UserInfo](/zh-CN/api-reference/rtc/cpp-all-platforms/class-userinfo)。

</Parameter>
</ParameterList>

<a id="api_irtcengine_getuserinfobyuseraccount__return_values"></a>

### 返回值 [#返回值-2]

- 0：方法调用成功。
- &lt; 0：方法调用失败。详见[错误码](/zh-CN/api-reference/rtc/error-code)了解详情和解决建议。

### 所属接口类 [#所属接口类-2]

- [IRtcEngine](/zh-CN/api-reference/rtc/cpp-all-platforms/rtc-interface-class#class_irtcengine)

<a id="api_irtcengineex_getuserinfobyuseraccountex"></a>

<a id="ariaid-title5"></a>

## getUserInfoByUserAccountEx [#getuserinfobyuseraccountex]

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

<a id="api_irtcengineex_getuserinfobyuseraccountex__prototype"></a>

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

<a id="api_irtcengineex_getuserinfobyuseraccountex__detailed_desc"></a>

该方法通过传入用户 User Account 获取用户信息，功能与 [getUserInfoByUserAccount](/zh-CN/api-reference/rtc/cpp-all-platforms/channel#api_irtcengine_getuserinfobyuseraccount) 相同。

<a id="api_irtcengineex_getuserinfobyuseraccountex__scenario"></a>

### 适用场景 [#适用场景-1]

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

<a id="api_irtcengineex_getuserinfobyuseraccountex__parameters"></a>

### 参数 [#参数-3]

<ParameterList>
<a id="useraccount-1"></a>
<Parameter name="userAccount">

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

</Parameter>
<a id="userinfo-3"></a>
<Parameter name="userInfo">

输入和输出参数，用于标识用户的 [UserInfo](/zh-CN/api-reference/rtc/cpp-all-platforms/class-userinfo) 对象。调用该方法后，该对象将包含用户 User Account 和用户 ID。详见 [UserInfo](/zh-CN/api-reference/rtc/cpp-all-platforms/class-userinfo)。

</Parameter>
<a id="connection-1"></a>
<Parameter name="connection">

[RtcConnection](/zh-CN/api-reference/rtc/cpp-all-platforms/class-rtcconnection) 对象。详见 [RtcConnection](/zh-CN/api-reference/rtc/cpp-all-platforms/class-rtcconnection)。

</Parameter>
</ParameterList>

<a id="api_irtcengineex_getuserinfobyuseraccountex__return_values"></a>

### 返回值 [#返回值-3]

- 0：方法调用成功。
- &lt; 0：方法调用失败。详见[错误码](/zh-CN/api-reference/rtc/error-code)了解详情和解决建议。

### 所属接口类 [#所属接口类-3]

- [IRtcEngineEx](/zh-CN/api-reference/rtc/cpp-all-platforms/rtc-interface-class#class_irtcengineex)

<a id="api_irtcengine_joinchannel"></a>

<a id="api_irtcengine_joinchannel1"></a>

<a id="ariaid-title6"></a>

## joinChannel [1/2] [#joinchannel-12]

加入一个频道。

<a id="api_irtcengine_joinchannel1__prototype"></a>

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

<a id="api_irtcengine_joinchannel1__detailed_desc"></a>

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

:::note
注：

- 该方法仅支持用户同时加入一个频道。
- 不同 App ID 的用户无法互通。
- 加入频道前，请确保用于生成 Token 的 App ID 与调用 [initialize](/zh-CN/api-reference/rtc/cpp-all-platforms/initialize#api_irtcengine_initialize) 方法时传入的 App ID 一致，否则可能会导致加入频道失败。
:::

<a id="api_irtcengine_joinchannel1__timing"></a>

### 调用时机 [#调用时机-2]

该方法需要在调用 [initialize](/zh-CN/api-reference/rtc/cpp-all-platforms/initialize#api_irtcengine_initialize) 方法之后调用。

<a id="api_irtcengine_joinchannel1__related"></a>

### 相关回调 [#相关回调]

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

- 本地客户端：[onJoinChannelSuccess](/zh-CN/api-reference/rtc/cpp-all-platforms/channel#callback_irtcengineeventhandler_onjoinchannelsuccess) 和 [onConnectionStateChanged](/zh-CN/api-reference/rtc/cpp-all-platforms/network#callback_irtcengineeventhandler_onconnectionstatechanged) 回调。
- 远端客户端：如果用户在 `COMMUNICATION` 频道场景中加入频道，或主播在 `LIVE_BROADCASTING` 频道场景中加入频道，则触发 [onUserJoined](/zh-CN/api-reference/rtc/cpp-all-platforms/channel#callback_irtcengineeventhandler_onuserjoined) 回调。

当由于网络状况不佳导致本地客户端与声网服务器的连接中断时，SDK 会尝试重新连接服务器。当本地客户端成功重新加入频道时，SDK 会在本地客户端触发 [onRejoinChannelSuccess](/zh-CN/api-reference/rtc/cpp-all-platforms/channel#callback_irtcengineeventhandler_onrejoinchannelsuccess) 回调。

<a id="api_irtcengine_joinchannel1__parameters"></a>

### 参数 [#参数-4]

<ParameterList>
<a id="token"></a>
<Parameter name="token">

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

:::note
注：

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

</Parameter>
<a id="channelid"></a>
<Parameter name="channelId">

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

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

</Parameter>
<a id="info"></a>
<Parameter name="info">

（可选）预留参数。

</Parameter>
<a id="uid-2"></a>
<Parameter name="uid">

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

</Parameter>
</ParameterList>

<a id="api_irtcengine_joinchannel1__return_values"></a>

### 返回值 [#返回值-4]

- 0：方法调用成功。
- &lt; 0：方法调用失败。详见[错误码](/zh-CN/api-reference/rtc/error-code)了解详情和解决建议。

  - -2：参数无效。例如，Token 无效，`uid` 参数未设置为整数，或 [ChannelMediaOptions](/zh-CN/api-reference/rtc/cpp-all-platforms/class-channelmediaoptions) 中的成员值无效。你需要传入有效参数并重新加入频道。
  - -3：[IRtcEngine](/zh-CN/api-reference/rtc/cpp-all-platforms/rtc-interface-class#class_irtcengine) 对象初始化失败。你需要重新初始化 [IRtcEngine](/zh-CN/api-reference/rtc/cpp-all-platforms/rtc-interface-class#class_irtcengine) 对象。
  - -7：[IRtcEngine](/zh-CN/api-reference/rtc/cpp-all-platforms/rtc-interface-class#class_irtcengine) 对象尚未初始化。你需要先初始化 [IRtcEngine](/zh-CN/api-reference/rtc/cpp-all-platforms/rtc-interface-class#class_irtcengine) 对象再调用该方法。
  - -8：[IRtcEngine](/zh-CN/api-reference/rtc/cpp-all-platforms/rtc-interface-class#class_irtcengine) 对象的内部状态错误。典型原因是在调用 [startEchoTest](/zh-CN/api-reference/rtc/cpp-all-platforms/network#api_irtcengine_startechotest3) 开始通话回声测试后，未调用 [stopEchoTest](/zh-CN/api-reference/rtc/cpp-all-platforms/network#api_irtcengine_stopechotest) 停止测试就调用该方法加入频道。你需要先调用 [stopEchoTest](/zh-CN/api-reference/rtc/cpp-all-platforms/network#api_irtcengine_stopechotest) 再调用该方法。
  - -17：加入频道请求被拒绝。典型原因是用户已在频道中。声网建议你使用 [onConnectionStateChanged](/zh-CN/api-reference/rtc/cpp-all-platforms/network#callback_irtcengineeventhandler_onconnectionstatechanged) 回调判断用户是否在频道中。只有在收到 `CONNECTION_STATE_DISCONNECTED`（1）状态时才调用该方法加入频道。
  - -102：频道名无效。你需要在 `channelId` 中传入有效的频道名重新加入频道。
  - -121：用户 ID 无效。你需要在 `uid` 中传入有效的用户 ID 重新加入频道。

### 所属接口类 [#所属接口类-4]

- [IRtcEngine](/zh-CN/api-reference/rtc/cpp-all-platforms/rtc-interface-class#class_irtcengine)

<a id="api_irtcengine_joinchannel2"></a>

<a id="ariaid-title7"></a>

## joinChannel [2/2] [#joinchannel-22]

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

<a id="api_irtcengine_joinchannel2__prototype"></a>

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

<a id="api_irtcengine_joinchannel2__detailed_desc"></a>

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

:::note
注：

- 该方法仅支持用户同时加入一个频道。
- 不同 App ID 的用户无法互通。
- 加入频道前，请确保用于生成 Token 的 App ID 与调用 [initialize](/zh-CN/api-reference/rtc/cpp-all-platforms/initialize#api_irtcengine_initialize) 方法时传入的 App ID 一致，否则可能会导致加入频道失败。
:::

<a id="api_irtcengine_joinchannel2__timing"></a>

### 调用时机 [#调用时机-3]

请在调用 [initialize](/zh-CN/api-reference/rtc/cpp-all-platforms/initialize#api_irtcengine_initialize) 方法后调用该方法。

<a id="api_irtcengine_joinchannel2__related"></a>

### 相关回调 [#相关回调-1]

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

- 本地客户端：[onJoinChannelSuccess](/zh-CN/api-reference/rtc/cpp-all-platforms/channel#callback_irtcengineeventhandler_onjoinchannelsuccess) 和 [onConnectionStateChanged](/zh-CN/api-reference/rtc/cpp-all-platforms/network#callback_irtcengineeventhandler_onconnectionstatechanged) 回调。
- 远端客户端：如果用户在 COMMUNICATION 频道场景中加入频道，或主播在 LIVE_BROADCASTING 频道场景中加入频道，则触发 [onUserJoined](/zh-CN/api-reference/rtc/cpp-all-platforms/channel#callback_irtcengineeventhandler_onuserjoined) 回调。

当由于网络状况不佳导致本地客户端与声网服务器的连接中断时，SDK 会尝试重新连接服务器。当本地客户端成功重新加入频道时，SDK 会在本地客户端触发 [onRejoinChannelSuccess](/zh-CN/api-reference/rtc/cpp-all-platforms/channel#callback_irtcengineeventhandler_onrejoinchannelsuccess) 回调。

<a id="api_irtcengine_joinchannel2__parameters"></a>

### 参数 [#参数-5]

<ParameterList>
<a id="token-1"></a>
<Parameter name="token">

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

:::note
注：

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

</Parameter>
<a id="channelid-1"></a>
<Parameter name="channelId">

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

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

</Parameter>
<a id="uid-3"></a>
<Parameter name="uid">

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

</Parameter>
<a id="options"></a>
<Parameter name="options">

频道媒体选项。详见 [ChannelMediaOptions](/zh-CN/api-reference/rtc/cpp-all-platforms/class-channelmediaoptions)。

</Parameter>
</ParameterList>

<a id="api_irtcengine_joinchannel2__return_values"></a>

### 返回值 [#返回值-5]

- 0：方法调用成功。
- &lt; 0：方法调用失败。详见[错误码](/zh-CN/api-reference/rtc/error-code)了解详情和解决建议。

  - -2：参数无效。例如，Token 无效，`uid` 参数未设置为整数，或 [ChannelMediaOptions](/zh-CN/api-reference/rtc/cpp-all-platforms/class-channelmediaoptions) 中的成员值无效。你需要传入有效参数并重新加入频道。
  - -3：[IRtcEngine](/zh-CN/api-reference/rtc/cpp-all-platforms/rtc-interface-class#class_irtcengine) 对象初始化失败。你需要重新初始化 [IRtcEngine](/zh-CN/api-reference/rtc/cpp-all-platforms/rtc-interface-class#class_irtcengine) 对象。
  - -7：[IRtcEngine](/zh-CN/api-reference/rtc/cpp-all-platforms/rtc-interface-class#class_irtcengine) 对象尚未初始化。你需要先初始化 [IRtcEngine](/zh-CN/api-reference/rtc/cpp-all-platforms/rtc-interface-class#class_irtcengine) 对象再调用该方法。
  - -8：[IRtcEngine](/zh-CN/api-reference/rtc/cpp-all-platforms/rtc-interface-class#class_irtcengine) 对象的内部状态错误。典型原因是在调用 [startEchoTest](/zh-CN/api-reference/rtc/cpp-all-platforms/network#api_irtcengine_startechotest3) 开始通话回路测试后，未调用 [stopEchoTest](/zh-CN/api-reference/rtc/cpp-all-platforms/network#api_irtcengine_stopechotest) 停止测试就调用该方法加入频道。你需要先调用 [stopEchoTest](/zh-CN/api-reference/rtc/cpp-all-platforms/network#api_irtcengine_stopechotest) 再调用该方法。
  - -17：加入频道请求被拒绝。典型原因是用户已在频道中。声网建议你通过 [onConnectionStateChanged](/zh-CN/api-reference/rtc/cpp-all-platforms/network#callback_irtcengineeventhandler_onconnectionstatechanged) 回调判断用户是否在频道中。只有在收到 `CONNECTION_STATE_DISCONNECTED`（1）状态时才调用该方法加入频道。
  - -102：频道名无效。你需要在 `channelId` 中传入有效的频道名重新加入频道。
  - -121：用户 ID 无效。你需要在 `uid` 中传入有效的用户 ID 重新加入频道。

### 所属接口类 [#所属接口类-5]

- [IRtcEngine](/zh-CN/api-reference/rtc/cpp-all-platforms/rtc-interface-class#class_irtcengine)

<a id="api_irtcengineex_joinchannelex"></a>

<a id="ariaid-title8"></a>

## joinChannelEx [#joinchannelex]

加入一个频道。

<a id="api_irtcengineex_joinchannelex__prototype"></a>

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

<a id="api_irtcengineex_joinchannelex__detailed_desc"></a>

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

:::note
注： 如果你已经在一个频道中，不能使用相同的用户 ID 重新加入该频道。
在加入频道前，请确保用于生成 Token 的 App ID 与调用 [initialize](/zh-CN/api-reference/rtc/cpp-all-platforms/initialize#api_irtcengine_initialize) 方法时传入的 App ID 相同，否则可能会导致使用该 Token 加入频道失败。
:::

<a id="api_irtcengineex_joinchannelex__scenario"></a>

### 适用场景 [#适用场景-2]

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

<a id="api_irtcengineex_joinchannelex__timing"></a>

### 调用时机 [#调用时机-4]

请在调用 [initialize](/zh-CN/api-reference/rtc/cpp-all-platforms/initialize#api_irtcengine_initialize) 方法后调用该方法。

<a id="api_irtcengineex_joinchannelex__related"></a>

### 相关回调 [#相关回调-2]

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

- 本地客户端：[onJoinChannelSuccess](/zh-CN/api-reference/rtc/cpp-all-platforms/channel#callback_irtcengineeventhandler_onjoinchannelsuccess) 和 [onConnectionStateChanged](/zh-CN/api-reference/rtc/cpp-all-platforms/network#callback_irtcengineeventhandler_onconnectionstatechanged) 回调。
- 远端客户端：如果是 `COMMUNICATION` 频道场景中有用户加入频道，或 `LIVE_BROADCASTING` 频道场景中有主播加入频道，则触发 [onUserJoined](/zh-CN/api-reference/rtc/cpp-all-platforms/channel#callback_irtcengineeventhandler_onuserjoined) 回调。

当由于网络状况不佳导致本地客户端与声网服务器的连接中断时，SDK 会尝试重连服务器。当本地客户端成功重加入频道时，SDK 会触发本地客户端的 [onRejoinChannelSuccess](/zh-CN/api-reference/rtc/cpp-all-platforms/channel#callback_irtcengineeventhandler_onrejoinchannelsuccess) 回调。

<a id="api_irtcengineex_joinchannelex__parameters"></a>

### 参数 [#参数-6]

<ParameterList>
<a id="token-2"></a>
<Parameter name="token">

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

:::note
注：

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

</Parameter>
<a id="connection-2"></a>
<Parameter name="connection">

连接信息，详见 [RtcConnection](/zh-CN/api-reference/rtc/cpp-all-platforms/class-rtcconnection)。

</Parameter>
<a id="options-1"></a>
<Parameter name="options">

频道媒体选项，详见 [ChannelMediaOptions](/zh-CN/api-reference/rtc/cpp-all-platforms/class-channelmediaoptions)。

</Parameter>
<a id="eventhandler"></a>
<Parameter name="eventHandler">

回调类，详见 [IRtcEngineEventHandler](/zh-CN/api-reference/rtc/cpp-all-platforms/rtc-interface-class#class_irtcengineeventhandler)。你可以通过该参数传入的 `eventHandler` 对象获取多个频道的回调事件。

</Parameter>
</ParameterList>

<a id="api_irtcengineex_joinchannelex__return_values"></a>

### 返回值 [#返回值-6]

- 0：方法调用成功。
- &lt; 0：方法调用失败。详见[错误码](/zh-CN/api-reference/rtc/error-code)了解详情和解决建议。

  - -2：参数无效。例如，Token 无效，`uid` 参数未设置为整数，或 [ChannelMediaOptions](/zh-CN/api-reference/rtc/cpp-all-platforms/class-channelmediaoptions) 中的成员值无效。你需要传入有效参数并重新加入频道。
  - -3：[IRtcEngine](/zh-CN/api-reference/rtc/cpp-all-platforms/rtc-interface-class#class_irtcengine) 对象初始化失败。你需要重新初始化 [IRtcEngine](/zh-CN/api-reference/rtc/cpp-all-platforms/rtc-interface-class#class_irtcengine) 对象。
  - -7：[IRtcEngine](/zh-CN/api-reference/rtc/cpp-all-platforms/rtc-interface-class#class_irtcengine) 对象尚未初始化。你需要先初始化 [IRtcEngine](/zh-CN/api-reference/rtc/cpp-all-platforms/rtc-interface-class#class_irtcengine) 对象再调用该方法。
  - -8：[IRtcEngine](/zh-CN/api-reference/rtc/cpp-all-platforms/rtc-interface-class#class_irtcengine) 对象的内部状态错误。典型原因是在调用 [startEchoTest](/zh-CN/api-reference/rtc/cpp-all-platforms/network#api_irtcengine_startechotest3) 开始通话回路测试后，未调用 [stopEchoTest](/zh-CN/api-reference/rtc/cpp-all-platforms/network#api_irtcengine_stopechotest) 停止测试就调用该方法加入频道。你需要先调用 [stopEchoTest](/zh-CN/api-reference/rtc/cpp-all-platforms/network#api_irtcengine_stopechotest) 再调用该方法。
  - -17：加入频道请求被拒绝。典型原因是用户已在频道中。声网建议你通过 [onConnectionStateChanged](/zh-CN/api-reference/rtc/cpp-all-platforms/network#callback_irtcengineeventhandler_onconnectionstatechanged) 回调判断用户是否在频道中。只有在收到 `CONNECTION_STATE_DISCONNECTED`（1）状态时才调用该方法加入频道。
  - -102：频道名无效。你需要在 `channelId` 中传入有效的频道名以重新加入频道。
  - -121：用户 ID 无效。你需要在 `uid` 中传入有效的用户 ID 以重新加入频道。

### 所属接口类 [#所属接口类-6]

- [IRtcEngineEx](/zh-CN/api-reference/rtc/cpp-all-platforms/rtc-interface-class#class_irtcengineex)

<a id="api_irtcengine_joinchannelwithuseraccount1"></a>

<a id="ariaid-title9"></a>

## joinChannelWithUserAccount [1/2] [#joinchannelwithuseraccount-12]

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

<a id="api_irtcengine_joinchannelwithuseraccount1__prototype"></a>

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

<a id="api_irtcengine_joinchannelwithuseraccount1__detailed_desc"></a>

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

:::note
注：

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

<a id="api_irtcengine_joinchannelwithuseraccount1__timing"></a>

### 调用时机 [#调用时机-5]

在调用 [initialize](/zh-CN/api-reference/rtc/cpp-all-platforms/initialize#api_irtcengine_initialize) 之后调用该方法。

<a id="api_irtcengine_joinchannelwithuseraccount1__related"></a>

### 相关回调 [#相关回调-3]

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

- 本地客户端：[onLocalUserRegistered](/zh-CN/api-reference/rtc/cpp-all-platforms/channel#callback_irtcengineeventhandler_onlocaluserregistered)、[onJoinChannelSuccess](/zh-CN/api-reference/rtc/cpp-all-platforms/channel#callback_irtcengineeventhandler_onjoinchannelsuccess) 和 [onConnectionStateChanged](/zh-CN/api-reference/rtc/cpp-all-platforms/network#callback_irtcengineeventhandler_onconnectionstatechanged) 回调。
- 远端客户端：如果用户在 `COMMUNICATION` 频道场景中加入频道，或主播在 `LIVE_BROADCASTING` 频道场景中加入频道，则会触发 [onUserJoined](/zh-CN/api-reference/rtc/cpp-all-platforms/channel#callback_irtcengineeventhandler_onuserjoined) 和 [onUserInfoUpdated](/zh-CN/api-reference/rtc/cpp-all-platforms/channel#callback_irtcengineeventhandler_onuserinfoupdated) 回调。

<a id="api_irtcengine_joinchannelwithuseraccount1__parameters"></a>

### 参数 [#参数-7]

<ParameterList>
<a id="token-3"></a>
<Parameter name="token">

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

:::note
注：

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

</Parameter>
<a id="channelid-2"></a>
<Parameter name="channelId">

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

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

</Parameter>
<a id="useraccount-2"></a>
<Parameter name="userAccount">

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

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

</Parameter>
</ParameterList>

<a id="api_irtcengine_joinchannelwithuseraccount1__return_values"></a>

### 返回值 [#返回值-7]

- 0：方法调用成功。
- &lt; 0：方法调用失败。详见[错误码](/zh-CN/api-reference/rtc/error-code)了解详情和解决建议。

  - -2：参数无效。例如，Token 无效，`uid` 参数未设置为整数，或 [ChannelMediaOptions](/zh-CN/api-reference/rtc/cpp-all-platforms/class-channelmediaoptions) 中某成员的值无效。请传入有效参数并重新加入频道。
  - -3：[IRtcEngine](/zh-CN/api-reference/rtc/cpp-all-platforms/rtc-interface-class#class_irtcengine) 对象初始化失败。请重新初始化 [IRtcEngine](/zh-CN/api-reference/rtc/cpp-all-platforms/rtc-interface-class#class_irtcengine) 对象。
  - -7：[IRtcEngine](/zh-CN/api-reference/rtc/cpp-all-platforms/rtc-interface-class#class_irtcengine) 对象尚未初始化。请先初始化 [IRtcEngine](/zh-CN/api-reference/rtc/cpp-all-platforms/rtc-interface-class#class_irtcengine) 对象再调用该方法。
  - -8：[IRtcEngine](/zh-CN/api-reference/rtc/cpp-all-platforms/rtc-interface-class#class_irtcengine) 对象内部状态错误。典型原因是在调用 [startEchoTest](/zh-CN/api-reference/rtc/cpp-all-platforms/network#api_irtcengine_startechotest3) 开始通话回声测试后，未调用 [stopEchoTest](/zh-CN/api-reference/rtc/cpp-all-platforms/network#api_irtcengine_stopechotest) 停止测试就调用该方法加入频道。请先调用 [stopEchoTest](/zh-CN/api-reference/rtc/cpp-all-platforms/network#api_irtcengine_stopechotest) 再调用该方法。
  - -17：加入频道请求被拒绝。典型原因是用户已在频道中。声网建议你通过 [onConnectionStateChanged](/zh-CN/api-reference/rtc/cpp-all-platforms/network#callback_irtcengineeventhandler_onconnectionstatechanged) 回调判断用户是否在频道中，仅在收到 `CONNECTION_STATE_DISCONNECTED`（1）状态时再调用该方法。
  - -102：频道名无效。请在 `channelId` 中传入有效的频道名重新加入频道。
  - -121：用户 ID 无效。请在 `uid` 中传入有效的用户 ID 重新加入频道。

### 所属接口类 [#所属接口类-7]

- [IRtcEngine](/zh-CN/api-reference/rtc/cpp-all-platforms/rtc-interface-class#class_irtcengine)

<a id="api_irtcengine_joinchannelwithuseraccount2"></a>

<a id="ariaid-title10"></a>

## joinChannelWithUserAccount [2/2] [#joinchannelwithuseraccount-22]

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

<a id="api_irtcengine_joinchannelwithuseraccount2__prototype"></a>

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

<a id="api_irtcengine_joinchannelwithuseraccount2__detailed_desc"></a>

在调用该方法前，如果你尚未调用 [registerLocalUserAccount](/zh-CN/api-reference/rtc/cpp-all-platforms/channel#api_irtcengine_registerlocaluseraccount) 注册用户 User Account，SDK 会在你调用该方法加入频道时自动创建一个用户 User Account。提前调用 [registerLocalUserAccount](/zh-CN/api-reference/rtc/cpp-all-platforms/channel#api_irtcengine_registerlocaluseraccount) 可以缩短加入频道所需的时间。

与 `joinChannelWithUserAccount` 方法相比，该方法新增了 `options` 参数，用于设置频道内的媒体选项，例如是否发布音视频流。

默认情况下，用户会订阅频道内所有其他用户的音视频流，从而产生使用量和计费。若要停止订阅其他流，请设置 `options` 参数或调用 `muteRemoteAudio/VideoStream` 或 `muteAllRemoteAudio/VideoStreams`。

:::note
注： 该方法仅支持用户同时加入一个频道。
不同 App ID 的用户无法互通。
加入频道前，请确保用于生成 Token 的 App ID 与调用 [initialize](/zh-CN/api-reference/rtc/cpp-all-platforms/initialize#api_irtcengine_initialize) 方法时传入的 App ID 相同，否则可能导致加入频道失败。
为确保通信顺畅，请使用相同的参数类型标识用户。例如，如果某用户使用用户 ID 加入频道，则其他用户也应使用用户 ID；使用用户账号加入频道时同理。如果用户使用声网 Web SDK 加入频道，请确保用户 ID 的参数类型一致。
:::

<a id="api_irtcengine_joinchannelwithuseraccount2__timing"></a>

### 调用时机 [#调用时机-6]

请在调用 [initialize](/zh-CN/api-reference/rtc/cpp-all-platforms/initialize#api_irtcengine_initialize) 方法后调用该方法。

<a id="api_irtcengine_joinchannelwithuseraccount2__related"></a>

### 相关回调 [#相关回调-4]

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

- 本地客户端：[onLocalUserRegistered](/zh-CN/api-reference/rtc/cpp-all-platforms/channel#callback_irtcengineeventhandler_onlocaluserregistered)、[onJoinChannelSuccess](/zh-CN/api-reference/rtc/cpp-all-platforms/channel#callback_irtcengineeventhandler_onjoinchannelsuccess) 和 [onConnectionStateChanged](/zh-CN/api-reference/rtc/cpp-all-platforms/network#callback_irtcengineeventhandler_onconnectionstatechanged) 回调。
- 远端客户端：如果用户在 COMMUNICATION 频道场景中加入频道，或主播在 LIVE_BROADCASTING 频道场景中加入频道，则会触发 [onUserJoined](/zh-CN/api-reference/rtc/cpp-all-platforms/channel#callback_irtcengineeventhandler_onuserjoined) 和 [onUserInfoUpdated](/zh-CN/api-reference/rtc/cpp-all-platforms/channel#callback_irtcengineeventhandler_onuserinfoupdated) 回调。

<a id="api_irtcengine_joinchannelwithuseraccount2__parameters"></a>

### 参数 [#参数-8]

<ParameterList>
<a id="token-4"></a>
<Parameter name="token">

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

:::note
注：

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

</Parameter>
<a id="channelid-3"></a>
<Parameter name="channelId">

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

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

</Parameter>
<a id="useraccount-3"></a>
<Parameter name="userAccount">

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

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

</Parameter>
<a id="options-2"></a>
<Parameter name="options">

频道媒体选项。详见 [ChannelMediaOptions](/zh-CN/api-reference/rtc/cpp-all-platforms/class-channelmediaoptions)。

</Parameter>
</ParameterList>

<a id="api_irtcengine_joinchannelwithuseraccount2__return_values"></a>

### 返回值 [#返回值-8]

- 0：方法调用成功。
- &lt; 0：方法调用失败。详见[错误码](/zh-CN/api-reference/rtc/error-code)了解详情和解决建议。

  - -2：参数无效。例如，Token 无效，`uid` 参数未设置为整数，或 [ChannelMediaOptions](/zh-CN/api-reference/rtc/cpp-all-platforms/class-channelmediaoptions) 中某成员的值无效。你需要传入有效参数并重新加入频道。
  - -3：[IRtcEngine](/zh-CN/api-reference/rtc/cpp-all-platforms/rtc-interface-class#class_irtcengine) 对象初始化失败。你需要重新初始化 [IRtcEngine](/zh-CN/api-reference/rtc/cpp-all-platforms/rtc-interface-class#class_irtcengine) 对象。
  - -7：[IRtcEngine](/zh-CN/api-reference/rtc/cpp-all-platforms/rtc-interface-class#class_irtcengine) 对象尚未初始化。你需要先初始化 [IRtcEngine](/zh-CN/api-reference/rtc/cpp-all-platforms/rtc-interface-class#class_irtcengine) 对象再调用该方法。
  - -8：[IRtcEngine](/zh-CN/api-reference/rtc/cpp-all-platforms/rtc-interface-class#class_irtcengine) 对象的内部状态错误。典型原因是在调用 [startEchoTest](/zh-CN/api-reference/rtc/cpp-all-platforms/network#api_irtcengine_startechotest3) 开始通话回路测试后，未调用 [stopEchoTest](/zh-CN/api-reference/rtc/cpp-all-platforms/network#api_irtcengine_stopechotest) 停止测试就调用该方法加入频道。你需要先调用 [stopEchoTest](/zh-CN/api-reference/rtc/cpp-all-platforms/network#api_irtcengine_stopechotest) 再调用该方法。
  - -17：加入频道请求被拒绝。典型原因是用户已在频道中。声网建议你使用 [onConnectionStateChanged](/zh-CN/api-reference/rtc/cpp-all-platforms/network#callback_irtcengineeventhandler_onconnectionstatechanged) 回调查看用户是否在频道中。只有在收到 `CONNECTION_STATE_DISCONNECTED`（1）状态时才调用该方法加入频道。
  - -102：频道名无效。你需要在 `channelId` 中传入有效的频道名以重新加入频道。
  - -121：用户 ID 无效。你需要在 `uid` 中传入有效的用户 ID 以重新加入频道。

### 所属接口类 [#所属接口类-8]

- [IRtcEngine](/zh-CN/api-reference/rtc/cpp-all-platforms/rtc-interface-class#class_irtcengine)

<a id="api_irtcengine_joinchannelwithuseraccountex_irtcengine"></a>

<a id="ariaid-title11"></a>

## joinChannelWithUserAccountEx [#joinchannelwithuseraccountex]

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

<a id="api_irtcengine_joinchannelwithuseraccountex_irtcengine__prototype"></a>

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

<a id="api_irtcengine_joinchannelwithuseraccountex_irtcengine__detailed_desc"></a>

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

:::note
注：

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

<a id="api_irtcengine_joinchannelwithuseraccountex_irtcengine__scenario"></a>

### 适用场景 [#适用场景-3]

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

<a id="api_irtcengine_joinchannelwithuseraccountex_irtcengine__timing"></a>

### 调用时机 [#调用时机-7]

请在调用 [initialize](/zh-CN/api-reference/rtc/cpp-all-platforms/initialize#api_irtcengine_initialize) 之后调用该方法。

<a id="api_irtcengine_joinchannelwithuseraccountex_irtcengine__related"></a>

### 相关回调 [#相关回调-5]

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

- 本地客户端：[onLocalUserRegistered](/zh-CN/api-reference/rtc/cpp-all-platforms/channel#callback_irtcengineeventhandler_onlocaluserregistered)、[onJoinChannelSuccess](/zh-CN/api-reference/rtc/cpp-all-platforms/channel#callback_irtcengineeventhandler_onjoinchannelsuccess) 和 [onConnectionStateChanged](/zh-CN/api-reference/rtc/cpp-all-platforms/network#callback_irtcengineeventhandler_onconnectionstatechanged) 回调。
- 远端客户端：如果用户在 `COMMUNICATION` 频道场景中加入频道，或在 `LIVE_BROADCASTING` 频道场景中作为主播加入频道，则会触发 [onUserJoined](/zh-CN/api-reference/rtc/cpp-all-platforms/channel#callback_irtcengineeventhandler_onuserjoined) 和 [onUserInfoUpdated](/zh-CN/api-reference/rtc/cpp-all-platforms/channel#callback_irtcengineeventhandler_onuserinfoupdated) 回调。

<a id="api_irtcengine_joinchannelwithuseraccountex_irtcengine__parameters"></a>

### 参数 [#参数-9]

<ParameterList>
<a id="token-5"></a>
<Parameter name="token">

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

:::note
注：

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

</Parameter>
<a id="channelid-4"></a>
<Parameter name="channelId">

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

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

</Parameter>
<a id="useraccount-4"></a>
<Parameter name="userAccount">

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

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

</Parameter>
<a id="options-3"></a>
<Parameter name="options">

频道媒体选项。详见 [ChannelMediaOptions](/zh-CN/api-reference/rtc/cpp-all-platforms/class-channelmediaoptions)。

</Parameter>
<a id="eventhandler-1"></a>
<Parameter name="eventHandler">

回调类。详见 [IRtcEngineEventHandler](/zh-CN/api-reference/rtc/cpp-all-platforms/rtc-interface-class#class_irtcengineeventhandler)。你可以通过该参数传入的 `eventHandler` 对象获取多个频道的回调事件。

</Parameter>
</ParameterList>

<a id="api_irtcengine_joinchannelwithuseraccountex_irtcengine__return_values"></a>

### 返回值 [#返回值-9]

- 0：方法调用成功。
- &lt; 0：方法调用失败。详见[错误码](/zh-CN/api-reference/rtc/error-code)了解详情和解决建议。

  - -2：参数无效。例如，Token 无效，`uid` 参数未设置为整数，或 [ChannelMediaOptions](/zh-CN/api-reference/rtc/cpp-all-platforms/class-channelmediaoptions) 中的成员值无效。你需要传入有效参数并重新加入频道。
  - -3：[IRtcEngine](/zh-CN/api-reference/rtc/cpp-all-platforms/rtc-interface-class#class_irtcengine) 对象初始化失败。你需要重新初始化 [IRtcEngine](/zh-CN/api-reference/rtc/cpp-all-platforms/rtc-interface-class#class_irtcengine) 对象。
  - -7：[IRtcEngine](/zh-CN/api-reference/rtc/cpp-all-platforms/rtc-interface-class#class_irtcengine) 对象尚未初始化。你需要先初始化 [IRtcEngine](/zh-CN/api-reference/rtc/cpp-all-platforms/rtc-interface-class#class_irtcengine) 对象再调用该方法。
  - -8：[IRtcEngine](/zh-CN/api-reference/rtc/cpp-all-platforms/rtc-interface-class#class_irtcengine) 对象内部状态错误。典型原因是在调用 [startEchoTest](/zh-CN/api-reference/rtc/cpp-all-platforms/network#api_irtcengine_startechotest3) 开始通话回路测试后，未调用 [stopEchoTest](/zh-CN/api-reference/rtc/cpp-all-platforms/network#api_irtcengine_stopechotest) 停止测试就调用该方法加入频道。你需要先调用 [stopEchoTest](/zh-CN/api-reference/rtc/cpp-all-platforms/network#api_irtcengine_stopechotest) 再调用该方法。
  - -17：加入频道请求被拒绝。典型原因是用户已在频道中。声网建议你通过 [onConnectionStateChanged](/zh-CN/api-reference/rtc/cpp-all-platforms/network#callback_irtcengineeventhandler_onconnectionstatechanged) 回调判断用户是否在频道中。只有在收到 `CONNECTION_STATE_DISCONNECTED`（1）状态时才调用该方法加入频道。
  - -102：频道名无效。你需要在 `channelId` 中传入有效的频道名重新加入频道。
  - -121：用户 ID 无效。你需要在 `uid` 中传入有效的用户 ID 重新加入频道。

### 所属接口类 [#所属接口类-9]

- [IRtcEngine](/zh-CN/api-reference/rtc/cpp-all-platforms/rtc-interface-class#class_irtcengine)

<a id="api_irtcengine_leavechannel"></a>

<a id="ariaid-title12"></a>

## leaveChannel [1/2] [#leavechannel-12]

离开频道。

<a id="api_irtcengine_leavechannel__prototype"></a>

```cpp
virtual int leaveChannel() = 0;
```

<a id="api_irtcengine_leavechannel__detailed_desc"></a>

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

:::note
注：

- 如果在调用该方法后立即调用 [release](/zh-CN/api-reference/rtc/cpp-all-platforms/initialize#api_irtcengine_release)，SDK 不会触发 [onLeaveChannel](/zh-CN/api-reference/rtc/cpp-all-platforms/channel#callback_irtcengineeventhandler_onleavechannel) 回调。
- 此方法为异步调用。方法返回时，并不代表用户已完全离开频道。
- 如果你通过 [joinChannelEx](/zh-CN/api-reference/rtc/cpp-all-platforms/channel#api_irtcengineex_joinchannelex) 加入了多个频道，调用该方法会离开你加入的所有频道。
:::

<a id="api_irtcengine_leavechannel__timing"></a>

### 调用时机 [#调用时机-8]

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

<a id="api_irtcengine_leavechannel__related"></a>

### 相关回调 [#相关回调-6]

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

- 本地客户端：触发 [onLeaveChannel](/zh-CN/api-reference/rtc/cpp-all-platforms/channel#callback_irtcengineeventhandler_onleavechannel) 回调。
- 远端客户端：远端主播离开频道后触发 [onUserOffline](/zh-CN/api-reference/rtc/cpp-all-platforms/channel#callback_irtcengineeventhandler_onuseroffline) 回调。

<a id="api_irtcengine_leavechannel__return_values"></a>

### 返回值 [#返回值-10]

- 0：方法调用成功。
- &lt; 0：方法调用失败。详见[错误码](/zh-CN/api-reference/rtc/error-code)了解详情和解决建议。

  - -1：发生通用错误（无明确原因）。
  - -2：参数无效。
  - -7：SDK 未初始化。

### 所属接口类 [#所属接口类-10]

- [IRtcEngine](/zh-CN/api-reference/rtc/cpp-all-platforms/rtc-interface-class#class_irtcengine)

<a id="api_irtcengine_leavechannel2"></a>

<a id="ariaid-title13"></a>

## leaveChannel [2/2] [#leavechannel-22]

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

<a id="api_irtcengine_leavechannel2__prototype"></a>

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

<a id="api_irtcengine_leavechannel2__detailed_desc"></a>

调用该方法后，SDK 会终止音视频互动，离开当前频道，并释放与会话相关的所有资源。如果你调用了 [joinChannelEx](/zh-CN/api-reference/rtc/cpp-all-platforms/channel#api_irtcengineex_joinchannelex) 加入了多个频道，调用该方法会离开你加入的所有频道。

:::note
注： 如果在调用该方法后立即调用 [release](/zh-CN/api-reference/rtc/cpp-all-platforms/initialize#api_irtcengine_release)，SDK 不会触发 [onLeaveChannel](/zh-CN/api-reference/rtc/cpp-all-platforms/channel#callback_irtcengineeventhandler_onleavechannel) 回调。该方法为异步调用。当该方法返回时，并不意味着用户已经离开频道。
:::

<a id="api_irtcengine_leavechannel2__timing"></a>

### 调用时机 [#调用时机-9]

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

<a id="api_irtcengine_leavechannel2__related"></a>

### 相关回调 [#相关回调-7]

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

- 本地客户端：触发 [onLeaveChannel](/zh-CN/api-reference/rtc/cpp-all-platforms/channel#callback_irtcengineeventhandler_onleavechannel) 回调。
- 远端客户端：远端主播离开频道后触发 [onUserOffline](/zh-CN/api-reference/rtc/cpp-all-platforms/channel#callback_irtcengineeventhandler_onuseroffline) 回调。

<a id="api_irtcengine_leavechannel2__parameters"></a>

### 参数 [#参数-10]

<ParameterList>
<a id="options-4"></a>
<Parameter name="options">

离开频道的选项。详见 [LeaveChannelOptions](/zh-CN/api-reference/rtc/cpp-all-platforms/class-leavechanneloptions)。

</Parameter>
</ParameterList>

<a id="api_irtcengine_leavechannel2__return_values"></a>

### 返回值 [#返回值-11]

- 0：方法调用成功。
- &lt; 0：方法调用失败。详见[错误码](/zh-CN/api-reference/rtc/error-code)了解详情和解决建议。

### 所属接口类 [#所属接口类-11]

- [IRtcEngine](/zh-CN/api-reference/rtc/cpp-all-platforms/rtc-interface-class#class_irtcengine)

<a id="api_irtcengineex_leavechannelex"></a>

<a id="ariaid-title14"></a>

## leaveChannelEx [1/2] [#leavechannelex-12]

离开频道。

<a id="api_irtcengineex_leavechannelex__prototype"></a>

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

<a id="api_irtcengineex_leavechannelex__detailed_desc"></a>

调用该方法后，SDK 会终止音视频互动，离开当前频道，并释放与会话相关的所有资源。调用 [joinChannelEx](/zh-CN/api-reference/rtc/cpp-all-platforms/channel#api_irtcengineex_joinchannelex) 加入频道后，必须调用此方法或 `leaveChannelEx` 结束通话，否则无法开始下一次通话。

- 如果在调用该方法后立即调用 [release](/zh-CN/api-reference/rtc/cpp-all-platforms/initialize#api_irtcengine_release)，SDK 不会触发 [onLeaveChannel](/zh-CN/api-reference/rtc/cpp-all-platforms/channel#callback_irtcengineeventhandler_onleavechannel) 回调。
- 此方法为异步调用，方法返回时并不代表用户已完全离开频道。
- 如果调用 `leaveChannel`，你将离开通过 `joinChannel` 或 [joinChannelEx](/zh-CN/api-reference/rtc/cpp-all-platforms/channel#api_irtcengineex_joinchannelex) 加入的所有频道。

<a id="api_irtcengineex_leavechannelex__scenario"></a>

### 适用场景 [#适用场景-4]

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

<a id="api_irtcengineex_leavechannelex__timing"></a>

### 调用时机 [#调用时机-10]

该方法需要在调用 [joinChannelEx](/zh-CN/api-reference/rtc/cpp-all-platforms/channel#api_irtcengineex_joinchannelex) 之后调用。

<a id="api_irtcengineex_leavechannelex__related"></a>

### 相关回调 [#相关回调-8]

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

- 本地客户端：触发 [onLeaveChannel](/zh-CN/api-reference/rtc/cpp-all-platforms/channel#callback_irtcengineeventhandler_onleavechannel) 回调。
- 远端客户端：远端用户离开频道后触发 [onUserOffline](/zh-CN/api-reference/rtc/cpp-all-platforms/channel#callback_irtcengineeventhandler_onuseroffline) 回调。

<a id="api_irtcengineex_leavechannelex__parameters"></a>

### 参数 [#参数-11]

<ParameterList>
<a id="connection-3"></a>
<Parameter name="connection">

连接信息。详见 [RtcConnection](/zh-CN/api-reference/rtc/cpp-all-platforms/class-rtcconnection)。

</Parameter>
</ParameterList>

<a id="api_irtcengineex_leavechannelex__return_values"></a>

### 返回值 [#返回值-12]

- 0：方法调用成功。
- &lt; 0：方法调用失败。详见[错误码](/zh-CN/api-reference/rtc/error-code)了解详情和解决建议。

### 所属接口类 [#所属接口类-12]

- [IRtcEngineEx](/zh-CN/api-reference/rtc/cpp-all-platforms/rtc-interface-class#class_irtcengineex)

<a id="api_irtcengineex_leavechannelex2"></a>

<a id="ariaid-title15"></a>

## leaveChannelEx [2/2] [#leavechannelex-22]

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

<a id="api_irtcengineex_leavechannelex2__prototype"></a>

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

<a id="api_irtcengineex_leavechannelex2__detailed_desc"></a>

:::info[自从]
自 v4.1.0 版本新增。
:::

调用该方法后，SDK 会终止音视频互动，离开当前频道，并释放与会话相关的所有资源。调用 [joinChannelEx](/zh-CN/api-reference/rtc/cpp-all-platforms/channel#api_irtcengineex_joinchannelex) 加入频道后，必须调用该方法或 `leaveChannelEx` 结束通话，否则无法开始下一次通话。

:::note
注：

- 如果在调用该方法后立即调用 [release](/zh-CN/api-reference/rtc/cpp-all-platforms/initialize#api_irtcengine_release)，SDK 不会触发 [onLeaveChannel](/zh-CN/api-reference/rtc/cpp-all-platforms/channel#callback_irtcengineeventhandler_onleavechannel) 回调。
- 该方法为异步调用，方法返回时并不代表用户已离开频道。
- 如果调用 [leaveChannel [1/2]](/zh-CN/api-reference/rtc/cpp-all-platforms/channel#api_irtcengine_leavechannel) 或 [leaveChannel [2/2]](/zh-CN/api-reference/rtc/cpp-all-platforms/channel#api_irtcengine_leavechannel2)，你将离开通过 [joinChannel [1/2]](/zh-CN/api-reference/rtc/cpp-all-platforms/channel#api_irtcengine_joinchannel1)、[joinChannel [2/2]](/zh-CN/api-reference/rtc/cpp-all-platforms/channel#api_irtcengine_joinchannel2) 或 [joinChannelEx](/zh-CN/api-reference/rtc/cpp-all-platforms/channel#api_irtcengineex_joinchannelex) 加入的所有频道。
:::

<a id="api_irtcengineex_leavechannelex2__scenario"></a>

### 适用场景 [#适用场景-5]

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

<a id="api_irtcengineex_leavechannelex2__timing"></a>

### 调用时机 [#调用时机-11]

该方法需要在调用 [joinChannelEx](/zh-CN/api-reference/rtc/cpp-all-platforms/channel#api_irtcengineex_joinchannelex) 后调用。

<a id="api_irtcengineex_leavechannelex2__related"></a>

### 相关回调 [#相关回调-9]

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

- 本地客户端：触发 [onLeaveChannel](/zh-CN/api-reference/rtc/cpp-all-platforms/channel#callback_irtcengineeventhandler_onleavechannel) 回调。
- 远端客户端：远端主播离开频道后触发 [onUserOffline](/zh-CN/api-reference/rtc/cpp-all-platforms/channel#callback_irtcengineeventhandler_onuseroffline) 回调。

<a id="api_irtcengineex_leavechannelex2__parameters"></a>

### 参数 [#参数-12]

<ParameterList>
<a id="connection-4"></a>
<Parameter name="connection">

连接信息。详见 [RtcConnection](/zh-CN/api-reference/rtc/cpp-all-platforms/class-rtcconnection)。

</Parameter>
<a id="options-5"></a>
<Parameter name="options">

离开频道的选项。详见 [LeaveChannelOptions](/zh-CN/api-reference/rtc/cpp-all-platforms/class-leavechanneloptions)。

:::note
注： 该参数仅支持设置 [LeaveChannelOptions](/zh-CN/api-reference/rtc/cpp-all-platforms/class-leavechanneloptions) 中的 `stopMicrophoneRecording` 成员，设置其他成员无效。
:::

</Parameter>
</ParameterList>

<a id="api_irtcengineex_leavechannelex2__return_values"></a>

### 返回值 [#返回值-13]

- 0：方法调用成功。
- &lt; 0：方法调用失败。详见[错误码](/zh-CN/api-reference/rtc/error-code)了解详情和解决建议。

### 所属接口类 [#所属接口类-13]

- [IRtcEngineEx](/zh-CN/api-reference/rtc/cpp-all-platforms/rtc-interface-class#class_irtcengineex)

<a id="api_irtcengine_preloadchannel"></a>

<a id="ariaid-title16"></a>

## preloadChannel [#preloadchannel]

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

<a id="api_irtcengine_preloadchannel__prototype"></a>

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

<a id="api_irtcengine_preloadchannel__detailed_desc"></a>

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

:::note
注：

- 调用该方法时，请确保将用户角色设置为观众，且未将音频场景设置为 `AUDIO_SCENARIO_CHORUS`，否则该方法不生效。
- 请确保用于预加载的频道名、用户 ID 和 Token 与加入频道时传入的值一致，否则该方法不生效。
- 一个 [IRtcEngine](/zh-CN/api-reference/rtc/cpp-all-platforms/rtc-interface-class#class_irtcengine) 实例最多支持预加载 20 个频道。超过该限制时，仅最新的 20 个预加载频道生效。
- 预加载频道失败不会影响加入频道的能力，也不会增加加入频道所需的时间。
:::

<a id="api_irtcengine_preloadchannel__timing"></a>

### 调用时机 [#调用时机-12]

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

<a id="api_irtcengine_preloadchannel__parameters"></a>

### 参数 [#参数-13]

<ParameterList>
<a id="token-6"></a>
<Parameter name="token">

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

- 预加载一个频道时，调用该方法传入新的 Token。
- 预加载多个频道时：

  - 如果你为所有预加载频道使用通配符 Token，调用 [updatePreloadChannelToken](/zh-CN/api-reference/rtc/cpp-all-platforms/channel#api_irtcengine_updatepreloadchanneltoken) 更新 Token。生成通配符 Token 时，确保用户 ID 不为 0。
  - 如果你为不同频道使用不同的 Token，调用该方法传入你的用户 ID、频道名和新的 Token。

</Parameter>
<a id="channelid-5"></a>
<Parameter name="channelId">

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

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

</Parameter>
<a id="uid-4"></a>
<Parameter name="uid">

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

</Parameter>
</ParameterList>

<a id="api_irtcengine_preloadchannel__return_values"></a>

### 返回值 [#返回值-14]

- 0：方法调用成功。
- &lt; 0：方法调用失败。详见[错误码](/zh-CN/api-reference/rtc/error-code)了解详情和解决建议。

  - -7：[IRtcEngine](/zh-CN/api-reference/rtc/cpp-all-platforms/rtc-interface-class#class_irtcengine) 对象尚未初始化。请先初始化 [IRtcEngine](/zh-CN/api-reference/rtc/cpp-all-platforms/rtc-interface-class#class_irtcengine) 对象后再调用该方法。
  - -102：频道名无效。请传入有效的频道名并重新加入频道。

### 所属接口类 [#所属接口类-14]

- [IRtcEngine](/zh-CN/api-reference/rtc/cpp-all-platforms/rtc-interface-class#class_irtcengine)

<a id="api_irtcengine_preloadchannelwithuseraccount"></a>

<a id="ariaid-title17"></a>

## preloadChannelWithUserAccount [#preloadchannelwithuseraccount]

预加载指定的频道。

<a id="api_irtcengine_preloadchannelwithuseraccount__prototype"></a>

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

<a id="api_irtcengine_preloadchannelwithuseraccount__detailed_desc"></a>

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

:::note
注：

- 调用该方法时，请确保将用户角色设置为观众，且未将音频场景设置为 `AUDIO_SCENARIO_CHORUS`，否则该方法不生效。
- 你还需要确保用于预加载的用户 User Account、频道名和 Token 与加入频道时传入的值一致，否则该方法不生效。
- 一个 [IRtcEngine](/zh-CN/api-reference/rtc/cpp-all-platforms/rtc-interface-class#class_irtcengine) 实例最多支持预加载 20 个频道。超过该限制时，仅最新的 20 个预加载频道生效。
- 预加载频道失败不会影响加入频道的功能，也不会增加加入频道所需的时间。
:::

<a id="api_irtcengine_preloadchannelwithuseraccount__timing"></a>

### 调用时机 [#调用时机-13]

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

<a id="api_irtcengine_preloadchannelwithuseraccount__parameters"></a>

### 参数 [#参数-14]

<ParameterList>
<a id="token-7"></a>
<Parameter name="token">

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

- 预加载一个频道时，调用该方法传入新的 Token。
- 预加载多个频道时：

  - 如果你为所有预加载频道使用通配符 Token，调用 [updatePreloadChannelToken](/zh-CN/api-reference/rtc/cpp-all-platforms/channel#api_irtcengine_updatepreloadchanneltoken) 更新 Token。注意：生成通配符 Token 时，确保用户 ID 不为 0。
  - 如果你为不同频道使用不同的 Token，调用该方法传入用户 ID、频道名和新的 Token。

</Parameter>
<a id="channelid-6"></a>
<Parameter name="channelId">

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

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

</Parameter>
<a id="useraccount-5"></a>
<Parameter name="userAccount">

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

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

</Parameter>
</ParameterList>

<a id="api_irtcengine_preloadchannelwithuseraccount__return_values"></a>

### 返回值 [#返回值-15]

- 0：方法调用成功。
- &lt; 0：方法调用失败。详见[错误码](/zh-CN/api-reference/rtc/error-code)了解详情和解决建议。

  - -2：参数无效，例如用户 User Account 为空。请传入有效参数后重新加入频道。
  - -7：[IRtcEngine](/zh-CN/api-reference/rtc/cpp-all-platforms/rtc-interface-class#class_irtcengine) 对象尚未初始化。请先初始化 [IRtcEngine](/zh-CN/api-reference/rtc/cpp-all-platforms/rtc-interface-class#class_irtcengine) 对象后再调用该方法。
  - -102：频道名无效。请传入有效的频道名后重新加入频道。

### 所属接口类 [#所属接口类-15]

- [IRtcEngine](/zh-CN/api-reference/rtc/cpp-all-platforms/rtc-interface-class#class_irtcengine)

<a id="api_irtcengine_registerlocaluseraccount"></a>

<a id="ariaid-title18"></a>

## registerLocalUserAccount [#registerlocaluseraccount]

注册用户 User Account。

<a id="api_irtcengine_registerlocaluseraccount__prototype"></a>

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

<a id="api_irtcengine_registerlocaluseraccount__detailed_desc"></a>

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

- 先调用 [registerLocalUserAccount](/zh-CN/api-reference/rtc/cpp-all-platforms/channel#api_irtcengine_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 设置为相同的参数类型。

<a id="api_irtcengine_registerlocaluseraccount__related"></a>

### 相关回调 [#相关回调-10]

成功调用该方法后，SDK 会触发 [onLocalUserRegistered](/zh-CN/api-reference/rtc/cpp-all-platforms/channel#callback_irtcengineeventhandler_onlocaluserregistered) 回调，报告本地用户的用户 ID 和用户 User Account。

<a id="api_irtcengine_registerlocaluseraccount__parameters"></a>

### 参数 [#参数-15]

<ParameterList>
<a id="appid"></a>
<Parameter name="appId">

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

</Parameter>
<a id="useraccount-6"></a>
<Parameter name="userAccount">

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

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

</Parameter>
</ParameterList>

<a id="api_irtcengine_registerlocaluseraccount__return_values"></a>

### 返回值 [#返回值-16]

- 0：方法调用成功。
- &lt; 0：方法调用失败。详见[错误码](/zh-CN/api-reference/rtc/error-code)了解详情和解决建议。

### 所属接口类 [#所属接口类-16]

- [IRtcEngine](/zh-CN/api-reference/rtc/cpp-all-platforms/rtc-interface-class#class_irtcengine)

<a id="api_irtcengine_renewtoken"></a>

<a id="ariaid-title19"></a>

## renewToken [#renewtoken]

更新 Token。

<a id="api_irtcengine_renewtoken__prototype"></a>

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

<a id="api_irtcengine_renewtoken__detailed_desc"></a>

成功调用该方法后，SDK 会触发 [onRenewTokenResult](/zh-CN/api-reference/rtc/cpp-all-platforms/channel#callback_irtcengineeventhandler_onrenewtokenresult) 回调。在单频道场景下，你可以在以下情况下调用该方法更新 Token：

- 收到 [onTokenPrivilegeWillExpire](/zh-CN/api-reference/rtc/cpp-all-platforms/channel#callback_irtcengineeventhandler_ontokenprivilegewillexpire) 回调，提示 Token 即将过期。
- Token 已过期时，SDK 会触发 [onRequestToken](/zh-CN/api-reference/rtc/cpp-all-platforms/channel#callback_irtcengineeventhandler_onrequesttoken) 回调，并在 [onConnectionStateChanged](/zh-CN/api-reference/rtc/cpp-all-platforms/network#callback_irtcengineeventhandler_onconnectionstatechanged) 回调中报告 `CONNECTION_CHANGED_TOKEN_EXPIRED`（9）。

<a id="api_irtcengine_renewtoken__parameters"></a>

### 参数 [#参数-16]

<ParameterList>
<a id="token-8"></a>
<Parameter name="token">

新的 Token。

</Parameter>
</ParameterList>

<a id="api_irtcengine_renewtoken__return_values"></a>

### 返回值 [#返回值-17]

- 0：方法调用成功。
- &lt; 0：方法调用失败。详见[错误码](/zh-CN/api-reference/rtc/error-code)了解详情和解决建议。

  - -2：参数无效，例如传入的 Token 为空。
  - -7：[IRtcEngine](/zh-CN/api-reference/rtc/cpp-all-platforms/rtc-interface-class#class_irtcengine) 对象尚未初始化。请先初始化 [IRtcEngine](/zh-CN/api-reference/rtc/cpp-all-platforms/rtc-interface-class#class_irtcengine) 对象再调用该方法。
  - 110：Token 无效。请确保以下两点：

    - 生成 Token 时指定的用户 ID 与加入频道时使用的用户 ID 一致。
    - 生成的 Token 与加入频道时传入的 Token 相同。

### 所属接口类 [#所属接口类-17]

- [IRtcEngine](/zh-CN/api-reference/rtc/cpp-all-platforms/rtc-interface-class#class_irtcengine)

<a id="api_irtcengine_setchannelprofile"></a>

<a id="ariaid-title20"></a>

## setChannelProfile [#setchannelprofile]

设置频道场景。

<a id="api_irtcengine_setchannelprofile__prototype"></a>

```cpp
virtual int setChannelProfile(CHANNEL_PROFILE_TYPE profile) = 0;
```

<a id="api_irtcengine_setchannelprofile__detailed_desc"></a>

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

:::note
注： 为保证实时通信质量，声网建议频道内所有用户使用相同的频道场景。在不同的频道场景中，SDK 的默认音频路由也不同。详见 [setDefaultAudioRouteToSpeakerphone](/zh-CN/api-reference/rtc/cpp-all-platforms/device-management/audio-route#api_irtcengine_setdefaultaudioroutetospeakerphone)。
:::

<a id="api_irtcengine_setchannelprofile__timing"></a>

### 调用时机 [#调用时机-14]

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

<a id="api_irtcengine_setchannelprofile__parameters"></a>

### 参数 [#参数-17]

<ParameterList>
<a id="profile"></a>
<Parameter name="profile">

频道场景。详见 [CHANNEL_PROFILE_TYPE](/zh-CN/api-reference/rtc/cpp-all-platforms/enum-channelprofiletype)。

</Parameter>
</ParameterList>

<a id="api_irtcengine_setchannelprofile__return_values"></a>

### 返回值 [#返回值-18]

- 0：方法调用成功。
- &lt; 0：方法调用失败。详见[错误码](/zh-CN/api-reference/rtc/error-code)了解详情和解决建议。

  - -2：参数无效。
  - -7：SDK 未初始化。

### 所属接口类 [#所属接口类-18]

- [IRtcEngine](/zh-CN/api-reference/rtc/cpp-all-platforms/rtc-interface-class#class_irtcengine)

<a id="setclientrole"></a>

<a id="api_irtcengine_setclientrole"></a>

<a id="api_irtcengine_setclientrole1"></a>

<a id="ariaid-title21"></a>

## setClientRole [1/2] [#setclientrole-12]

设置用户角色。

<a id="api_irtcengine_setclientrole1__prototype"></a>

```cpp
virtual int setClientRole(CLIENT_ROLE_TYPE role) = 0;
```

<a id="api_irtcengine_setclientrole1__detailed_desc"></a>

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

- 如果你在加入频道前调用该方法将用户角色设置为主播，并通过 [setupLocalVideo](/zh-CN/api-reference/rtc/cpp-all-platforms/video/video-rendering#api_irtcengine_setuplocalvideo) 设置本地视频属性，则用户加入频道时会自动开启本地视频预览。

- 如果你在加入频道后调用该方法设置用户角色，SDK 会自动调用 [muteLocalAudioStream](/zh-CN/api-reference/rtc/cpp-all-platforms/publishnsubscribe#api_irtcengine_mutelocalaudiostream) 和 [muteLocalVideoStream](/zh-CN/api-reference/rtc/cpp-all-platforms/publishnsubscribe#api_irtcengine_mutelocalvideostream) 方法来更新音视频流的发布状态。

:::note
注： 在加入频道前调用该方法并将用户角色设置为 `BROADCASTER` 时，本地客户端不会触发 [onClientRoleChanged](/zh-CN/api-reference/rtc/cpp-all-platforms/channel#callback_irtcengineeventhandler_onclientrolechanged) 回调；但如果将 `role` 设置为 `AUDIENCE`，则会触发该回调。
:::

<a id="api_irtcengine_setclientrole1__timing"></a>

### 调用时机 [#调用时机-15]

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

<a id="api_irtcengine_setclientrole1__related"></a>

### 相关回调 [#相关回调-11]

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

- 本地客户端触发 [onClientRoleChanged](/zh-CN/api-reference/rtc/cpp-all-platforms/channel#callback_irtcengineeventhandler_onclientrolechanged) 回调。注意：在加入频道前调用该方法并将 `role` 设置为 `AUDIENCE` 也会触发该回调。
- 远端客户端触发 [onUserJoined](/zh-CN/api-reference/rtc/cpp-all-platforms/channel#callback_irtcengineeventhandler_onuserjoined) 或 [onUserOffline](/zh-CN/api-reference/rtc/cpp-all-platforms/channel#callback_irtcengineeventhandler_onuseroffline) 回调。

如果你在加入频道后调用该方法设置用户角色失败，SDK 会触发 [onClientRoleChangeFailed](/zh-CN/api-reference/rtc/cpp-all-platforms/channel#callback_irtcengineeventhandler_onclientrolechangefailed) 回调，报告失败原因和当前用户角色。

<a id="api_irtcengine_setclientrole1__parameters"></a>

### 参数 [#参数-18]

<ParameterList>
<a id="role"></a>
<Parameter name="role">

用户角色，详见 [CLIENT_ROLE_TYPE](/zh-CN/api-reference/rtc/cpp-all-platforms/enum-clientroletype)。

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

</Parameter>
</ParameterList>

<a id="api_irtcengine_setclientrole1__return_values"></a>

### 返回值 [#返回值-19]

- 0：方法调用成功。
- &lt; 0：方法调用失败。详见[错误码](/zh-CN/api-reference/rtc/error-code)了解详情和解决建议。

  - -1：发生通用错误（无明确原因）。
  - -2：参数无效。
  - -7：SDK 未初始化。

### 所属接口类 [#所属接口类-19]

- [IRtcEngine](/zh-CN/api-reference/rtc/cpp-all-platforms/rtc-interface-class#class_irtcengine)

<a id="api_irtcengine_setclientrole2"></a>

<a id="ariaid-title22"></a>

## setClientRole [2/2] [#setclientrole-22]

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

<a id="api_irtcengine_setclientrole2__prototype"></a>

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

<a id="api_irtcengine_setclientrole2__detailed_desc"></a>

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

- 如果你在加入频道前调用该方法将用户角色设置为主播，并通过 [setupLocalVideo](/zh-CN/api-reference/rtc/cpp-all-platforms/video/video-rendering#api_irtcengine_setuplocalvideo) 设置本地视频属性，则用户加入频道时会自动开启本地视频预览。
- 如果你在加入频道后调用该方法设置用户角色，SDK 会自动调用 [muteLocalAudioStream](/zh-CN/api-reference/rtc/cpp-all-platforms/publishnsubscribe#api_irtcengine_mutelocalaudiostream) 和 [muteLocalVideoStream](/zh-CN/api-reference/rtc/cpp-all-platforms/publishnsubscribe#api_irtcengine_mutelocalvideostream) 方法来改变音视频流的发布状态。

:::note
注： 当用户角色设置为主播时，观众延迟等级只能设置为 `AUDIENCE_LATENCY_LEVEL_ULTRA_LOW_LATENCY`。
在加入频道前调用该方法并将 `role` 设置为 `BROADCASTER` 时，本地客户端不会触发 [onClientRoleChanged](/zh-CN/api-reference/rtc/cpp-all-platforms/channel#callback_irtcengineeventhandler_onclientrolechanged) 回调。
在加入频道前调用该方法并将 `role` 设置为 `AUDIENCE` 时，会触发该回调。
:::

<a id="api_irtcengine_setclientrole2__timing"></a>

### 调用时机 [#调用时机-16]

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

<a id="api_irtcengine_setclientrole2__related"></a>

### 相关回调 [#相关回调-12]

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

- 本地客户端触发 [onClientRoleChanged](/zh-CN/api-reference/rtc/cpp-all-platforms/channel#callback_irtcengineeventhandler_onclientrolechanged) 回调。注意：在加入频道前调用此方法并将 `role` 设置为 `AUDIENCE` 也会触发该回调。
- 远端客户端触发 [onUserJoined](/zh-CN/api-reference/rtc/cpp-all-platforms/channel#callback_irtcengineeventhandler_onuserjoined) 或 [onUserOffline](/zh-CN/api-reference/rtc/cpp-all-platforms/channel#callback_irtcengineeventhandler_onuseroffline) 回调。

如果你在加入频道后调用此方法设置用户角色但失败，SDK 会触发 [onClientRoleChangeFailed](/zh-CN/api-reference/rtc/cpp-all-platforms/channel#callback_irtcengineeventhandler_onclientrolechangefailed) 回调，报告失败原因和当前用户角色。

<a id="api_irtcengine_setclientrole2__parameters"></a>

### 参数 [#参数-19]

<ParameterList>
<a id="role-1"></a>
<Parameter name="role">

用户角色，详见 [CLIENT_ROLE_TYPE](/zh-CN/api-reference/rtc/cpp-all-platforms/enum-clientroletype)。

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

</Parameter>
<a id="options-6"></a>
<Parameter name="options">

用户的详细选项，详见 [ClientRoleOptions](/zh-CN/api-reference/rtc/cpp-all-platforms/class-clientroleoptions)。

</Parameter>
</ParameterList>

<a id="api_irtcengine_setclientrole2__return_values"></a>

### 返回值 [#返回值-20]

- 0：方法调用成功。
- &lt; 0：方法调用失败。详见[错误码](/zh-CN/api-reference/rtc/error-code)了解详情和解决建议。

  - -1：发生通用错误（无明确原因）。
  - -2：参数无效。
  - -5：请求被拒绝。
  - -7：SDK 未初始化。

### 所属接口类 [#所属接口类-20]

- [IRtcEngine](/zh-CN/api-reference/rtc/cpp-all-platforms/rtc-interface-class#class_irtcengine)

<a id="api_irtcengine_updatechannelmediaoptions"></a>

<a id="ariaid-title23"></a>

## updateChannelMediaOptions [#updatechannelmediaoptions]

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

<a id="api_irtcengine_updatechannelmediaoptions__prototype"></a>

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

<a id="api_irtcengine_updatechannelmediaoptions__detailed_desc"></a>

<a id="api_irtcengine_updatechannelmediaoptions__parameters"></a>

### 参数 [#参数-20]

<ParameterList>
<a id="options-7"></a>
<Parameter name="options">

频道媒体选项。详见 [ChannelMediaOptions](/zh-CN/api-reference/rtc/cpp-all-platforms/class-channelmediaoptions)。

</Parameter>
</ParameterList>

<a id="api_irtcengine_updatechannelmediaoptions__return_values"></a>

### 返回值 [#返回值-21]

- 0：方法调用成功。
- &lt; 0：方法调用失败。详见[错误码](/zh-CN/api-reference/rtc/error-code)了解详情和解决建议。

  - -2：[ChannelMediaOptions](/zh-CN/api-reference/rtc/cpp-all-platforms/class-channelmediaoptions) 中某个成员的值无效，例如 `token` 或用户 ID 无效。你需要填写有效的参数。
  - -7：[IRtcEngine](/zh-CN/api-reference/rtc/cpp-all-platforms/rtc-interface-class#class_irtcengine) 对象尚未初始化。你需要先初始化 [IRtcEngine](/zh-CN/api-reference/rtc/cpp-all-platforms/rtc-interface-class#class_irtcengine) 对象再调用该方法。
  - -8：[IRtcEngine](/zh-CN/api-reference/rtc/cpp-all-platforms/rtc-interface-class#class_irtcengine) 对象的内部状态错误，可能是用户尚未加入频道。建议你通过 [onConnectionStateChanged](/zh-CN/api-reference/rtc/cpp-all-platforms/network#callback_irtcengineeventhandler_onconnectionstatechanged) 回调判断用户是否在频道中。如果你收到 `CONNECTION_STATE_DISCONNECTED`（1）或 `CONNECTION_STATE_FAILED`（5）状态，说明用户不在频道中。你需要先调用 `joinChannel` 加入频道，再调用该方法。

### 所属接口类 [#所属接口类-21]

- [IRtcEngine](/zh-CN/api-reference/rtc/cpp-all-platforms/rtc-interface-class#class_irtcengine)

<a id="api_irtcengineex_updatechannelmediaoptionsex"></a>

<a id="ariaid-title24"></a>

## updateChannelMediaOptionsEx [#updatechannelmediaoptionsex]

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

<a id="api_irtcengineex_updatechannelmediaoptionsex__prototype"></a>

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

<a id="api_irtcengineex_updatechannelmediaoptionsex__detailed_desc"></a>

<a id="api_irtcengineex_updatechannelmediaoptionsex__scenario"></a>

### 适用场景 [#适用场景-6]

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

<a id="api_irtcengineex_updatechannelmediaoptionsex__parameters"></a>

### 参数 [#参数-21]

<ParameterList>
<a id="options-8"></a>
<Parameter name="options">

频道媒体选项。详见 [ChannelMediaOptions](/zh-CN/api-reference/rtc/cpp-all-platforms/class-channelmediaoptions)。

</Parameter>
<a id="connection-5"></a>
<Parameter name="connection">

连接信息。详见 [RtcConnection](/zh-CN/api-reference/rtc/cpp-all-platforms/class-rtcconnection)。

</Parameter>
</ParameterList>

<a id="api_irtcengineex_updatechannelmediaoptionsex__return_values"></a>

### 返回值 [#返回值-22]

- 0：方法调用成功。
- &lt; 0：方法调用失败。详见[错误码](/zh-CN/api-reference/rtc/error-code)了解详情和解决建议。

  - -2：[ChannelMediaOptions](/zh-CN/api-reference/rtc/cpp-all-platforms/class-channelmediaoptions) 中的成员值无效，例如 `token` 或用户 ID 无效。你需要填写有效的参数。
  - -7：[IRtcEngine](/zh-CN/api-reference/rtc/cpp-all-platforms/rtc-interface-class#class_irtcengine) 对象尚未初始化。你需要先初始化 [IRtcEngine](/zh-CN/api-reference/rtc/cpp-all-platforms/rtc-interface-class#class_irtcengine) 对象再调用该方法。
  - -8：[IRtcEngine](/zh-CN/api-reference/rtc/cpp-all-platforms/rtc-interface-class#class_irtcengine) 对象的内部状态错误，可能的原因是用户未加入频道。声网建议你通过 [onConnectionStateChanged](/zh-CN/api-reference/rtc/cpp-all-platforms/network#callback_irtcengineeventhandler_onconnectionstatechanged) 回调判断用户是否在频道中。如果你收到 `CONNECTION_STATE_DISCONNECTED`（1）或 `CONNECTION_STATE_FAILED`（5）状态，说明用户不在频道中。你需要先调用 `joinChannel` 加入频道，再调用该方法。

### 所属接口类 [#所属接口类-22]

- [IRtcEngineEx](/zh-CN/api-reference/rtc/cpp-all-platforms/rtc-interface-class#class_irtcengineex)

<a id="api_irtcengine_updatepreloadchanneltoken"></a>

<a id="ariaid-title25"></a>

## updatePreloadChannelToken [#updatepreloadchanneltoken]

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

<a id="api_irtcengine_updatepreloadchanneltoken__prototype"></a>

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

<a id="api_irtcengine_updatepreloadchanneltoken__detailed_desc"></a>

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

<a id="api_irtcengine_updatepreloadchanneltoken__scenario"></a>

### 适用场景 [#适用场景-7]

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

<a id="api_irtcengine_updatepreloadchanneltoken__parameters"></a>

### 参数 [#参数-22]

<ParameterList>
<a id="token-9"></a>
<Parameter name="token">

新的通配 Token。

</Parameter>
</ParameterList>

<a id="api_irtcengine_updatepreloadchanneltoken__return_values"></a>

### 返回值 [#返回值-23]

- 0：方法调用成功。
- &lt; 0：方法调用失败。详见[错误码](/zh-CN/api-reference/rtc/error-code)了解详情和解决建议。

  - -2：参数无效，例如传入的 Token 无效。请传入有效参数并重新加入频道。
  - -7：[IRtcEngine](/zh-CN/api-reference/rtc/cpp-all-platforms/rtc-interface-class#class_irtcengine) 对象尚未初始化。请先初始化 [IRtcEngine](/zh-CN/api-reference/rtc/cpp-all-platforms/rtc-interface-class#class_irtcengine) 对象后再调用该方法。

### 所属接口类 [#所属接口类-23]

- [IRtcEngine](/zh-CN/api-reference/rtc/cpp-all-platforms/rtc-interface-class#class_irtcengine)

<a id="callback_irtcengineeventhandler_onclientrolechanged"></a>

<a id="ariaid-title26"></a>

## onClientRoleChanged [#onclientrolechanged]

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

<a id="callback_irtcengineeventhandler_onclientrolechanged__prototype"></a>

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

<a id="callback_irtcengineeventhandler_onclientrolechanged__detailed_desc"></a>

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

<a id="callback_irtcengineeventhandler_onclientrolechanged__timing"></a>

### 触发时机 [#触发时机]

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

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

<a id="callback_irtcengineeventhandler_onclientrolechanged__parameters"></a>

### 参数 [#参数-23]

<ParameterList>
<a id="oldrole"></a>
<Parameter name="oldRole">

用户切换前的角色。详见 [CLIENT_ROLE_TYPE](/zh-CN/api-reference/rtc/cpp-all-platforms/enum-clientroletype)。

</Parameter>
<a id="newrole"></a>
<Parameter name="newRole">

用户切换后的角色。详见 [CLIENT_ROLE_TYPE](/zh-CN/api-reference/rtc/cpp-all-platforms/enum-clientroletype)。

</Parameter>
<a id="newroleoptions"></a>
<Parameter name="newRoleOptions">

用户切换后的角色属性。详见 [ClientRoleOptions](/zh-CN/api-reference/rtc/cpp-all-platforms/class-clientroleoptions)。

:::note
注： 自 v4.1.0 起引入。
:::

</Parameter>
</ParameterList>

### 所属接口类 [#所属接口类-24]

- [IRtcEngineEventHandler](/zh-CN/api-reference/rtc/cpp-all-platforms/rtc-interface-class#class_irtcengineeventhandler)

<a id="callback_irtcengineeventhandler_onclientrolechangefailed"></a>

<a id="ariaid-title27"></a>

## onClientRoleChangeFailed [#onclientrolechangefailed]

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

<a id="callback_irtcengineeventhandler_onclientrolechangefailed__prototype"></a>

```cpp
virtual void onClientRoleChangeFailed(CLIENT_ROLE_CHANGE_FAILED_REASON reason, CLIENT_ROLE_TYPE currentRole)
```

<a id="callback_irtcengineeventhandler_onclientrolechangefailed__detailed_desc"></a>

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

<a id="callback_irtcengineeventhandler_onclientrolechangefailed__timing"></a>

### 触发时机 [#触发时机-1]

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

<a id="callback_irtcengineeventhandler_onclientrolechangefailed__parameters"></a>

### 参数 [#参数-24]

<ParameterList>
<a id="reason"></a>
<Parameter name="reason">

用户角色切换失败的原因。详见 [CLIENT_ROLE_CHANGE_FAILED_REASON](/zh-CN/api-reference/rtc/cpp-all-platforms/enum-clientrolechangefailedreason)。

</Parameter>
<a id="currentrole"></a>
<Parameter name="currentRole">

当前的用户角色。详见 [CLIENT_ROLE_TYPE](/zh-CN/api-reference/rtc/cpp-all-platforms/enum-clientroletype)。

</Parameter>
</ParameterList>

### 所属接口类 [#所属接口类-25]

- [IRtcEngineEventHandler](/zh-CN/api-reference/rtc/cpp-all-platforms/rtc-interface-class#class_irtcengineeventhandler)

<a id="callback_irtcengineeventhandler_onerror"></a>

<a id="ariaid-title28"></a>

## onError [#onerror]

[onError](/zh-CN/api-reference/rtc/cpp-all-platforms/channel#callback_irtcengineeventhandler_onerror) 回调。报告 SDK 运行时发生的错误。

<a id="callback_irtcengineeventhandler_onerror__prototype"></a>

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

<a id="callback_irtcengineeventhandler_onerror__detailed_desc"></a>

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

<a id="callback_irtcengineeventhandler_onerror__parameters"></a>

### 参数 [#参数-25]

<ParameterList>
<a id="err"></a>
<Parameter name="err">

错误码。详见 [ERROR_CODE_TYPE](/zh-CN/api-reference/rtc/cpp-all-platforms/enum-errorcodetype)。

</Parameter>
<a id="msg"></a>
<Parameter name="msg">

错误信息。

</Parameter>
</ParameterList>

### 所属接口类 [#所属接口类-26]

- [IRtcEngineEventHandler](/zh-CN/api-reference/rtc/cpp-all-platforms/rtc-interface-class#class_irtcengineeventhandler)

<a id="callback_irtcengineeventhandler_onjoinchannelsuccess"></a>

<a id="ariaid-title29"></a>

## onJoinChannelSuccess [#onjoinchannelsuccess]

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

<a id="callback_irtcengineeventhandler_onjoinchannelsuccess__prototype"></a>

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

<a id="callback_irtcengineeventhandler_onjoinchannelsuccess__detailed_desc"></a>

<a id="callback_irtcengineeventhandler_onjoinchannelsuccess__timing"></a>

### 触发时机 [#触发时机-2]

当你调用 `joinChannel`、`joinChannelWithUserAccount`、[joinChannelEx](/zh-CN/api-reference/rtc/cpp-all-platforms/channel#api_irtcengineex_joinchannelex) 或 [joinChannelWithUserAccountEx](/zh-CN/api-reference/rtc/cpp-all-platforms/channel#api_irtcengine_joinchannelwithuseraccountex_irtcengine) 加入频道时，SDK 会触发该回调。

<a id="callback_irtcengineeventhandler_onjoinchannelsuccess__parameters"></a>

### 参数 [#参数-26]

<ParameterList>
<a id="channel"></a>
<Parameter name="channel">

频道名。

</Parameter>
<a id="uid-5"></a>
<Parameter name="uid">

本地用户的用户 ID。

</Parameter>
<a id="elapsed"></a>
<Parameter name="elapsed">

从本地用户调用 `joinChannel`、`joinChannelWithUserAccount`、[joinChannelEx](/zh-CN/api-reference/rtc/cpp-all-platforms/channel#api_irtcengineex_joinchannelex) 或 [joinChannelWithUserAccountEx](/zh-CN/api-reference/rtc/cpp-all-platforms/channel#api_irtcengine_joinchannelwithuseraccountex_irtcengine) 加入频道到触发该回调的时间间隔，单位为毫秒。

</Parameter>
</ParameterList>

### 所属接口类 [#所属接口类-27]

- [IRtcEngineEventHandler](/zh-CN/api-reference/rtc/cpp-all-platforms/rtc-interface-class#class_irtcengineeventhandler)

<a id="callback_irtcengineeventhandler_onleavechannel"></a>

<a id="ariaid-title30"></a>

## onLeaveChannel [#onleavechannel]

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

<a id="callback_irtcengineeventhandler_onleavechannel__prototype"></a>

```cpp
virtual void onLeaveChannel(const RtcStats& stats)
```

<a id="callback_irtcengineeventhandler_onleavechannel__detailed_desc"></a>

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

<a id="callback_irtcengineeventhandler_onleavechannel__timing"></a>

### 触发时机 [#触发时机-3]

在你调用 [leaveChannel [1/2]](/zh-CN/api-reference/rtc/cpp-all-platforms/channel#api_irtcengine_leavechannel)、[leaveChannel [2/2]](/zh-CN/api-reference/rtc/cpp-all-platforms/channel#api_irtcengine_leavechannel2)、[leaveChannelEx [1/2]](/zh-CN/api-reference/rtc/cpp-all-platforms/channel#api_irtcengineex_leavechannelex) 或 [leaveChannelEx [2/2]](/zh-CN/api-reference/rtc/cpp-all-platforms/channel#api_irtcengineex_leavechannelex2) 离开频道后，SDK 会触发该回调。

<a id="callback_irtcengineeventhandler_onleavechannel__parameters"></a>

### 参数 [#参数-27]

<ParameterList>
<a id="stats"></a>
<Parameter name="stats">

通话统计信息。详见 [RtcStats](/zh-CN/api-reference/rtc/cpp-all-platforms/class-rtcstats)。

</Parameter>
</ParameterList>

### 所属接口类 [#所属接口类-28]

- [IRtcEngineEventHandler](/zh-CN/api-reference/rtc/cpp-all-platforms/rtc-interface-class#class_irtcengineeventhandler)

<a id="callback_irtcengineeventhandler_onlocaluserregistered"></a>

<a id="ariaid-title31"></a>

## onLocalUserRegistered [#onlocaluserregistered]

[onLocalUserRegistered](/zh-CN/api-reference/rtc/cpp-all-platforms/channel#callback_irtcengineeventhandler_onlocaluserregistered) 回调。当本地用户注册用户 User Account 时触发。

<a id="callback_irtcengineeventhandler_onlocaluserregistered__prototype"></a>

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

<a id="callback_irtcengineeventhandler_onlocaluserregistered__detailed_desc"></a>

当本地用户成功调用 [registerLocalUserAccount](/zh-CN/api-reference/rtc/cpp-all-platforms/channel#api_irtcengine_registerlocaluseraccount) 注册用户 User Account，或调用 `joinChannelWithUserAccount` 加入频道后，SDK 会触发该回调，并返回本地用户的用户 ID 和用户 User Account。

<a id="callback_irtcengineeventhandler_onlocaluserregistered__parameters"></a>

### 参数 [#参数-28]

<ParameterList>
<a id="uid-6"></a>
<Parameter name="uid">

本地用户的用户 ID。

</Parameter>
<a id="useraccount-7"></a>
<Parameter name="userAccount">

本地用户的用户 User Account。

</Parameter>
</ParameterList>

### 所属接口类 [#所属接口类-29]

- [IRtcEngineEventHandler](/zh-CN/api-reference/rtc/cpp-all-platforms/rtc-interface-class#class_irtcengineeventhandler)

<a id="callback_irtcengineeventhandler_onrejoinchannelsuccess"></a>

<a id="ariaid-title32"></a>

## onRejoinChannelSuccess [#onrejoinchannelsuccess]

[onRejoinChannelSuccess](/zh-CN/api-reference/rtc/cpp-all-platforms/channel#callback_irtcengineeventhandler_onrejoinchannelsuccess) 回调。

<a id="callback_irtcengineeventhandler_onrejoinchannelsuccess__prototype"></a>

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

<a id="callback_irtcengineeventhandler_onrejoinchannelsuccess__detailed_desc"></a>

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

<a id="callback_irtcengineeventhandler_onrejoinchannelsuccess__timing"></a>

### 触发时机 [#触发时机-4]

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

<a id="callback_irtcengineeventhandler_onrejoinchannelsuccess__parameters"></a>

### 参数 [#参数-29]

<ParameterList>
<a id="channel-1"></a>
<Parameter name="channel">

频道名。

</Parameter>
<a id="uid-7"></a>
<Parameter name="uid">

重新加入频道的用户 ID。

</Parameter>
<a id="elapsed-1"></a>
<Parameter name="elapsed">

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

</Parameter>
</ParameterList>

### 所属接口类 [#所属接口类-30]

- [IRtcEngineEventHandler](/zh-CN/api-reference/rtc/cpp-all-platforms/rtc-interface-class#class_irtcengineeventhandler)

<a id="callback_irtcengineeventhandler_onrenewtokenresult"></a>

<a id="ariaid-title33"></a>

## onRenewTokenResult [#onrenewtokenresult]

[renewToken](/zh-CN/api-reference/rtc/cpp-all-platforms/channel#api_irtcengine_renewtoken) 方法调用结果回调。

<a id="callback_irtcengineeventhandler_onrenewtokenresult__prototype"></a>

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

<a id="callback_irtcengineeventhandler_onrenewtokenresult__detailed_desc"></a>

:::info[自从]
自 v4.6.0 版本新增。
:::

当你调用 [renewToken](/zh-CN/api-reference/rtc/cpp-all-platforms/channel#api_irtcengine_renewtoken) 方法更新 Token 后，该回调会被触发，用于通知更新结果。

<a id="callback_irtcengineeventhandler_onrenewtokenresult__parameters"></a>

### 参数 [#参数-30]

<ParameterList>
<a id="token-10"></a>
<Parameter name="token">

更新的 Token。

</Parameter>
<a id="code"></a>
<Parameter name="code">

错误码，详见 [RENEW_TOKEN_ERROR_CODE](/zh-CN/api-reference/rtc/cpp-all-platforms/enum-renewtokenerrorcode)。

</Parameter>
</ParameterList>

### 所属接口类 [#所属接口类-31]

- [IRtcEngineEventHandler](/zh-CN/api-reference/rtc/cpp-all-platforms/rtc-interface-class#class_irtcengineeventhandler)

<a id="callback_irtcengineeventhandler_onrequesttoken"></a>

<a id="ariaid-title34"></a>

## onRequestToken [#onrequesttoken]

Token 过期时触发的回调。

<a id="callback_irtcengineeventhandler_onrequesttoken__prototype"></a>

```cpp
virtual void onRequestToken() {}
```

<a id="callback_irtcengineeventhandler_onrequesttoken__detailed_desc"></a>



收到该回调后，你需要在你的 Token 服务器上生成新的 Token，并根据场景更新 Token：

- 单频道场景：

  - 调用 [renewToken](/zh-CN/api-reference/rtc/cpp-all-platforms/channel#api_irtcengine_renewtoken)传入新的 Token，无需先离开频道。SDK 会通过 [onRenewTokenResult](/zh-CN/api-reference/rtc/cpp-all-platforms/channel#callback_irtcengineeventhandler_onrenewtokenresult) 回调报告更新结果。
  - 如果你的 App 需要离开并重新加入频道，也可以调用 `leaveChannel` 离开频道，然后在调用 `joinChannel` 时传入新的 Token。
- 多频道场景：调用 [updateChannelMediaOptionsEx](/zh-CN/api-reference/rtc/cpp-all-platforms/channel#api_irtcengineex_updatechannelmediaoptionsex) 传入新 Token。

<a id="callback_irtcengineeventhandler_onrequesttoken__timing"></a>

### 触发时机 [#触发时机-5]

当 Token 过期时触发该回调。

### 所属接口类 [#所属接口类-32]

- [IRtcEngineEventHandler](/zh-CN/api-reference/rtc/cpp-all-platforms/rtc-interface-class#class_irtcengineeventhandler)

<a id="callback_irtcengineeventhandler_onrtcstats"></a>

<a id="ariaid-title35"></a>

## onRtcStats [#onrtcstats]

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

<a id="callback_irtcengineeventhandler_onrtcstats__prototype"></a>

```cpp
virtual void onRtcStats(const RtcStats& stats)
```

<a id="callback_irtcengineeventhandler_onrtcstats__detailed_desc"></a>

<a id="callback_irtcengineeventhandler_onrtcstats__timing"></a>

### 触发时机 [#触发时机-6]

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

<a id="callback_irtcengineeventhandler_onrtcstats__parameters"></a>

### 参数 [#参数-31]

<ParameterList>
<a id="stats-1"></a>
<Parameter name="stats">

RTC 引擎的统计信息。详见 [RtcStats](/zh-CN/api-reference/rtc/cpp-all-platforms/class-rtcstats)。

</Parameter>
</ParameterList>

### 所属接口类 [#所属接口类-33]

- [IRtcEngineEventHandler](/zh-CN/api-reference/rtc/cpp-all-platforms/rtc-interface-class#class_irtcengineeventhandler)

<a id="callback_irtcengineeventhandler_ontokenprivilegewillexpire"></a>

<a id="ariaid-title36"></a>

## onTokenPrivilegeWillExpire [#ontokenprivilegewillexpire]

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

<a id="callback_irtcengineeventhandler_ontokenprivilegewillexpire__prototype"></a>

```cpp
virtual void onTokenPrivilegeWillExpire(const char* token)
```

<a id="callback_irtcengineeventhandler_ontokenprivilegewillexpire__detailed_desc"></a>

收到该回调时，你需要在 Token 服务器上生成新的 Token，并根据场景更新 Token：

- 单频道场景：

  - 调用 [renewToken](/zh-CN/api-reference/rtc/cpp-all-platforms/channel#api_irtcengine_renewtoken) 传入新的 Token，无需先离开频道。SDK 会通过 [onRenewTokenResult](/zh-CN/api-reference/rtc/cpp-all-platforms/channel#callback_irtcengineeventhandler_onrenewtokenresult) 回调报告更新结果。
  - 如果你的 App 需要离开并重新加入频道，也可以调用 `leaveChannel` 离开频道，然后在调用 `joinChannel` 时传入新的 Token。
- 多频道场景：调用 [updateChannelMediaOptionsEx](/zh-CN/api-reference/rtc/cpp-all-platforms/channel#api_irtcengineex_updatechannelmediaoptionsex) 传入新的 Token。

<a id="callback_irtcengineeventhandler_ontokenprivilegewillexpire__timing"></a>

### 触发时机 [#触发时机-7]

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

<a id="callback_irtcengineeventhandler_ontokenprivilegewillexpire__parameters"></a>

### 参数 [#参数-32]

<ParameterList>
<a id="token-11"></a>
<Parameter name="token">

即将过期的 Token。

</Parameter>
</ParameterList>

### 所属接口类 [#所属接口类-34]

- [IRtcEngineEventHandler](/zh-CN/api-reference/rtc/cpp-all-platforms/rtc-interface-class#class_irtcengineeventhandler)

<a id="callback_irtcengineeventhandler_onuserinfoupdated"></a>

<a id="ariaid-title37"></a>

## onUserInfoUpdated [#onuserinfoupdated]

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

<a id="callback_irtcengineeventhandler_onuserinfoupdated__prototype"></a>

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

<a id="callback_irtcengineeventhandler_onuserinfoupdated__detailed_desc"></a>

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

<a id="callback_irtcengineeventhandler_onuserinfoupdated__parameters"></a>

### 参数 [#参数-33]

<ParameterList>
<a id="uid-8"></a>
<Parameter name="uid">

远端用户的用户 ID。

</Parameter>
<a id="info-1"></a>
<Parameter name="info">

包含远端用户的用户 ID 和用户 User Account 信息的对象。详见 [UserInfo](/zh-CN/api-reference/rtc/cpp-all-platforms/class-userinfo)。

</Parameter>
</ParameterList>

### 所属接口类 [#所属接口类-35]

- [IRtcEngineEventHandler](/zh-CN/api-reference/rtc/cpp-all-platforms/rtc-interface-class#class_irtcengineeventhandler)

<a id="callback_irtcengineeventhandler_onuserjoined"></a>

<a id="ariaid-title38"></a>

## onUserJoined [#onuserjoined]

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

<a id="callback_irtcengineeventhandler_onuserjoined__prototype"></a>

```cpp
virtual void onUserJoined(uid_t uid, int elapsed)
```

<a id="callback_irtcengineeventhandler_onuserjoined__detailed_desc"></a>

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

<a id="callback_irtcengineeventhandler_onuserjoined__timing"></a>

### 触发时机 [#触发时机-8]

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

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

<a id="callback_irtcengineeventhandler_onuserjoined__parameters"></a>

### 参数 [#参数-34]

<ParameterList>
<a id="uid-9"></a>
<Parameter name="uid">

加入频道的用户 ID。

</Parameter>
<a id="elapsed-2"></a>
<Parameter name="elapsed">

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

</Parameter>
</ParameterList>

### 所属接口类 [#所属接口类-36]

- [IRtcEngineEventHandler](/zh-CN/api-reference/rtc/cpp-all-platforms/rtc-interface-class#class_irtcengineeventhandler)

<a id="callback_irtcengineeventhandler_onuseroffline"></a>

<a id="ariaid-title39"></a>

## onUserOffline [#onuseroffline]

[onUserOffline](/zh-CN/api-reference/rtc/cpp-all-platforms/channel#callback_irtcengineeventhandler_onuseroffline) 回调：当远端用户（通信频道场景）或主播（直播频道场景）离开频道时触发。

<a id="callback_irtcengineeventhandler_onuseroffline__prototype"></a>

```cpp
virtual void onUserOffline(uid_t uid, USER_OFFLINE_REASON_TYPE reason)
```

<a id="callback_irtcengineeventhandler_onuseroffline__detailed_desc"></a>

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

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

<a id="callback_irtcengineeventhandler_onuseroffline__timing"></a>

### 触发时机 [#触发时机-9]

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

<a id="callback_irtcengineeventhandler_onuseroffline__parameters"></a>

### 参数 [#参数-35]

<ParameterList>
<a id="uid-10"></a>
<Parameter name="uid">

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

</Parameter>
<a id="reason-1"></a>
<Parameter name="reason">

用户离线的原因，详见 [USER_OFFLINE_REASON_TYPE](/zh-CN/api-reference/rtc/cpp-all-platforms/enum-userofflinereasontype)。

</Parameter>
</ParameterList>

### 所属接口类 [#所属接口类-37]

- [IRtcEngineEventHandler](/zh-CN/api-reference/rtc/cpp-all-platforms/rtc-interface-class#class_irtcengineeventhandler)