连接状态管理
SDK 端与服务器之间的连接状态会随着 SDK 初始化/反初始化、登录/登出、进出房间以及网络环境的变化而发生改变,也可能由于网络或鉴权问题导致连接中断。
本文将介绍连接相关的各个阶段、状态变化原因及处理方式。
1. 连接状态说明
为了便于理解 SDK 行为,本文将连接相关状态抽象为以下几类逻辑状态:
1. 未初始化
- 尚未调用 CRVideo_Init 完成 SDK 初始化。
2. 未登录
- 已完成 SDK 初始化,但尚未调用 CRVideo_Login / CRVideo_LoginByToken 或登录失败 / 已登出。
3. 已登录(房间外业务中)
- CRVideo_Login / CRVideo_LoginByToken 成功,收到 CRVideo_LoginSuccess 回调。
- SDK 与登录服务器之间保持心跳与长连接,可收发队列、呼叫、邀请等信令。
4. 已进入房间
- 成功调用 CRVideo_EnterMeeting3,收到 CRVideo_EnterMeetingRslt 成功回调。
- 与房间服务器建立媒体连接,可进行音视频、影音共享、屏幕共享等业务。
- 房间内其他人将收到 CRVideo_UserEnterMeeting 回调。
5. SDK内部断线重连
- 登录或房间连接由于网络原因中断,SDK会内部自动周期性尝试重连(总尝试时间为SDK的连接超时时间,默认为60秒),如果重连成功业务可以正常继续,如果重连不成功将回调 CRVideo_LineOff。
- SDK内部断线重连时,对应用层是无感知的,重连成功后,SDK会有序重传所有信令数据,确保业务逻辑完全正常;
- SDK内部断线重连时,音视频将是卡住状态,重连成功后,自动恢复正常;
6. 断线
- 当网络长时间中断,收到 CRVideo_LineOff 通知时,代表已经断线,SDK进入“未登录”状态。 此后 SDK 内部不再尝试重连,应用层可按业务需要决定是否重登、入会等操作。
- 如果断线之前在房间中,那么此时自动进入离开房间状态。 房间内其他人将收到 CRVideo_UserLeftMeeting 回调。
下图为 SDK 连接状态切换描述图:

2. 掉线与重连处理建议
在复杂的网络环境下,断线不可避免,SDK内部已实现一些短时间内、常见断线重连,如:切wifi,插拔网络,网络设备重启,网络路径闪断等;
但更长时间的断线,SDK 将回调 CRVideo_LineOff,建议在应用上实现「温和重连策略」。
掉线(CRVideo_LineOff)
- 当收到 CRVideo_LineOff 回调时,说明当前账号与登录服务器已断开连接。
- 建议处理方式:
- 在 UI 上提示用户「网络异常,连接已断开」或类似文案。
- 立即或延迟一段时间再次调用 CRVideo_Login / CRVideo_LoginByToken 重登,可设置重试次数上限与退避策略。
- 如重试多次失败,可引导用户检查网络。
- 如果之前在房间中,掉线重登之后,可以按需重新调用 CRVideo_EnterMeeting3 进入房间。
网络质量检测
在房间内,可通过 CRVideo_NetStateChanged 被动感知网络状况:当网络状态变化时 SDK 主动回调,并返回 0~10 的网络评分(10 为最佳)。