# 频道连接状态管理 (/zh-CN/realtime-media/rtc/build/initialize-and-channel/channel-connection/blueprint)
> For AI agents: see the complete documentation index at [llms.txt](/llms.txt).
在实时音视频场景下,App 端与声网 SD-RTN™ 之间的连接状态会随着客户端加入或离开频道而发生变化,也可能由于网络或鉴权问题而导致连接中断。
本文介绍各种频道连接状态,状态改变原因和处理方式,帮助你更好地管理用户和排除网络故障。
## 技术原理 [#技术原理-10]
### 连接状态 [#连接状态-20]
当连接状态发生变化时,声网会发送 `FOnConnectionStateChanged` 回调。下图展示各种连接状态,以及用户从加入到离开频道的过程中连接状态如何改变:
### 断线重连 [#断线重连-10]
通信过程中,如果因网络问题导致连接断开,SDK 会自动开启断线重连机制。下图展示本地用户(UID1)和远程用户(UID2)在以下过程中收到的回调:本地用户加入频道、发生网络异常、连接中断、重新加入频道。

图解如下:
- T0:SDK 接收到 UID1 的 `JoinChannel` 请求。
- T1:调用 `JoinChannel` 200 ms 后,UID1 加入频道。同时,UID1 收到 `FOnConnectionStateChanged(CONNECTING, CONNECTING)` 回调。成功加入频道后,UID1 收到 `FOnConnectionStateChanged(CONNECTED, JOIN_SUCCESS)` 和 `FOnJoinChannelSuccess` 回调。
- T2:因网间传输延迟,UID 2 感知 UID 1 加入频道约有 100 毫秒的延迟,此时 UID 2 收到 `FOnUserJoined` 回调。
- T3:某个时间点 UID 1 客户端因断网等原因导致上行网络变差。SDK 自动尝试重新加入频道。
- T4:如果 UID1 连续 4 秒没有收到服务器发送的任何数据,UID1 收到 `FOnConnectionStateChanged(RECONNECTING, INTERRUPTED)` 回调;同时 SDK 继续尝试重新加入频道。
- T5:如果 UID 1 收到 `FOnConnectionStateChanged(RECONNECTING, INTERRUPTED)` 后连续 10 秒没有收到服务器发送的任何数据,UID 1 会收到 `FOnConnectionLost` 回调;同时 SDK 继续尝试重新加入频道。
- T6:如果 UID2 连续 20 秒没有收到来自 UID1 的任何数据,则 SDK 判断 UID1 离线。UID2 收到 `FOnUserOffline` 回调。
- T7:如果 UID 1 收到 `FOnConnectionStateChanged(RECONNECTING, INTERRUPTED)` 后连续 20 分钟无法重新加入频道,SDK 不再继续尝试。UID 1 收到 `FOnConnectionStateChanged(FAILED, JOIN_FAILED)` 回调;用户需要退出当前频道,然后重新加入频道。
## 前提条件 [#前提条件-10]
在进行操作之前,请确保你已经在项目中实现了基本的实时音视频功能。详见[实现音视频互动](/zh-CN/realtime-media/rtc/get-started/quick-start)。
## 实现方法 [#实现方法]
本节介绍如何使用 `FOnConnectionStateChanged` 回调来监控频道连接状态的变化。
1. 创建 **OnConnectionStateChanged** 回调函数,配置以下参数:
| 输入参数 | 数据类型 | 参数描述 |
|:-------|:--------|:---------|
| `state` | Enum | 当前网络连接状态。详见 [`ECONNECTION_STATE_TYPE`](/zh-CN/api-reference/rtc/unreal-blueprint/enum-connectionstatetype)。|
| `reason` | Enum | 引起当前网络连接状态改变的原因。详见 [`ECONNECTION_CHANGED_REASON_TYPE`](/zh-CN/api-reference/rtc/unreal-blueprint/enum-connectionchangedreasontype)。|
2. 添加对 **OnConnectionStateChanged** 回调的监听,如下图所示:

3. 当频道连接状态发生变化,触发 **OnConnectionStateChanged** 回调时,打印监听到的网络连接状态信息。你可以从日志中读取当前连接状态以及状态更改的触发原因,进而帮助网络故障排查,详见[状态说明及排障指导](#状态说明及排障指导-10)。如下图所示:

## 参考信息 [#参考信息-10]
### 连接状态 [#连接状态-21]
如前文图中所示,App 在加入和离开频道前后可能出现以下 5 种连接状态:
| 连接状态 | 描述 |
| --- | --- |
| Disconnected | [channel-connection-unreal-blueprint-markdown-1-1-1 details](#table-slot-channel-connection-unreal-blueprint-markdown-1-1-1) |
| Connecting | 调用 `JoinChannel` 方法后的瞬时状态。 |
| Connected | 发生在 App 成功加入频道后。SDK 还会触发 `FOnJoinChannelSuccess` 回调,上报本地客户端已经加入频道。此时用户可以发布或订阅频道中的音频和视频。 |
| Reconnecting | [channel-connection-unreal-blueprint-markdown-1-4-1 details](#table-slot-channel-connection-unreal-blueprint-markdown-1-4-1) |
| Failed | 连接失败。发生在 SDK 在 20 分钟内无法加入频道、并且 SDK 停止重新连接频道时。此时需调用 `LeaveChannel` 离开当前频道,再调用 `JoinChannel` 再次加入频道。 |
**channel-connection-unreal-blueprint-markdown-1-1-1 details**
初始连接状态。它通常发生在:
- 调用 `JoinChannel` 之前。
- 调用 `LeaveChannel` 之后。
**channel-connection-unreal-blueprint-markdown-1-4-1 details**
发生在连接中断时。SDK 会在中断后自动尝试重新连接。
- 如果重新加入频道成功,SDK 会触发 `FOnRejoinChannelSuccess` 回调。
- 如果 10 秒内没有加入频道,SDK 会触发 `FOnConnectionStateChanged(RECONNECTING, LOST)`,同时继续尝试重新加入频道。
### 状态说明及排障指导 [#状态说明及排障指导-10]
`FOnConnectionStateChanged` 中的 `reason` 参数描述了连接状态更改原因。
下表列出了不同连接状态和状态变化原因之间的映射关系,以及发生网络中断时故障时的处理方法。
| 连接状态 | 状态说明和排障指导 |
| --- | --- |
| Disconnected | [channel-connection-unreal-blueprint-markdown-2-1-1 details](#table-slot-channel-connection-unreal-blueprint-markdown-2-1-1) |
| Connecting | [channel-connection-unreal-blueprint-markdown-2-2-1 details](#table-slot-channel-connection-unreal-blueprint-markdown-2-2-1) |
| Connected | [channel-connection-unreal-blueprint-markdown-2-3-1 details](#table-slot-channel-connection-unreal-blueprint-markdown-2-3-1) |
| Reconnecting | [channel-connection-unreal-blueprint-markdown-2-4-1 details](#table-slot-channel-connection-unreal-blueprint-markdown-2-4-1) |
| Failed | [channel-connection-unreal-blueprint-markdown-2-5-1 details](#table-slot-channel-connection-unreal-blueprint-markdown-2-5-1) |
**channel-connection-unreal-blueprint-markdown-2-1-1 details**
- `LEAVE_CHANNEL`(5):用户离开频道。
- `INVALID_TOKEN`(8):Token 无效,请使用有效的 Token 加入频道。
**channel-connection-unreal-blueprint-markdown-2-2-1 details**
- `CONNECTING`(0): App 正在尝试加入声网频道。
**channel-connection-unreal-blueprint-markdown-2-3-1 details**
- `JOIN_SUCCESS`(1):App 已成功加入频道。
**channel-connection-unreal-blueprint-markdown-2-4-1 details**
- `INTERRUPTED`(2):当网络连接中断时,SDK 自动重新连接频道,连接状态持续变化。关于自动重连时连接状态如何改变, 详见[断线重连](#断线重连-10)。
- `LOST`(16):SDK 和服务器失去连接。
- `SETTING_PROXY_SERVER`(11):由于设置了代理服务器,SDK 尝试重连。
- `CLIENT_IP_ADDRESS_CHANGED`(13):客户端 IP 地址变更。如多次收到该状态码,请提示用户更换网络后尝试重新加入频道。
- `KEEP_ALIVE_TIMEOUT`(14):SDK 和服务器连接保活超时,进入自动重连状态。
- `RENEW_TOKEN`(12):更新 Token 引起网络连接状态改变。
**channel-connection-unreal-blueprint-markdown-2-5-1 details**
- `BANNED_BY_SERVER`(3):用户被服务器禁止。
- `JOIN_FAILED`(4):SDK 在 20 分钟内持续尝试加入频道失败,停止尝试重连。你需要调用 `LeaveChannel` 离开当前频道,然后调用 `JoinChannel` 重新加入频道。
- `INVALID_APP_ID`(6):App ID 无效,请使用有效的 App ID 加入频道。
- `INVALID_CHANNEL_NAME`(7):频道名无效,请检查频道名中是否包含非法字符,并使用有效的频道名加入频道。
- `TOKEN_EXPIRED`(9):Token 已过期。请从 App 服务器获取新的 Token,然后调用 `joinChannel` 重新加入频道。
- `REJECTED_BY_SERVER`(10):此用户被服务器禁止。一般有以下原因:
- 本地用户已加入频道后,App 再次调用加入频道的 API,如 `joinChannel`。
- App 调用了 `StartEchoTest`,但没有调用 `StopEchoTest` 结束回声测试。
### 示例项目 [#示例项目-1]
声网提供了开源的示例项目供你参考,你可以前往下载或查看其中的源代码。
### API 参考 [#api-参考-11]
- [`GetConnectionState`](/zh-CN/api-reference/rtc/unreal-blueprint/network#api_irtcengine_getconnectionstate)
- [`FOnConnectionStateChanged`](/zh-CN/api-reference/rtc/unreal-blueprint/network#callback_irtcengineeventhandler_onconnectionstatechanged)