# agora::rtc::IRtcConnectionObserver类 参考 (/zh-CN/api-reference/rtc-server-sdk/cpp/classagora-1-1rtc-1-1-i-rtc-connection-observer)
> For AI agents: see the complete documentation index at [llms.txt](/llms.txt).
## 详细描述 [#详细描述]
[IRtcConnectionObserver](/zh-CN/api-reference/rtc-server-sdk/cpp/classagora-1-1rtc-1-1-i-rtc-connection-observer) 类,用于监听 SDK 的连接状态。
## 构造及析构函数说明 [#构造及析构函数说明]
### ~IRtcConnectionObserver() [#irtcconnectionobserver]
virtual agora::rtc::IRtcConnectionObserver::~IRtcConnectionObserver()
## 成员函数说明 [#成员函数说明]
### onConnected() [#onconnected]
virtual void agora::rtc::IRtcConnectionObserver::onConnected(const [TConnectionInfo](/zh-CN/api-reference/rtc-server-sdk/cpp/structagora-1-1rtc-1-1-t-connection-info) & *connectionInfo*, [CONNECTION_CHANGED_REASON_TYPE](/zh-CN/api-reference/rtc-server-sdk/cpp/namespaceagora-1-1rtc#a329573b5363b2065b4069e5bf6013144) *reason*)
SDK 与频道的连接状态变更为 `CONNECTION_STATE_CONNECTED(3)` 时触发。
连接信息: [TConnectionInfo](/zh-CN/api-reference/rtc-server-sdk/cpp/structagora-1-1rtc-1-1-t-connection-info)。
连接状态变更原因: [CONNECTION_CHANGED_REASON_TYPE](/zh-CN/api-reference/rtc-server-sdk/cpp/namespaceagora-1-1rtc#a329573b5363b2065b4069e5bf6013144) 。
### onDisconnected() [#ondisconnected]
virtual void agora::rtc::IRtcConnectionObserver::onDisconnected(const [TConnectionInfo](/zh-CN/api-reference/rtc-server-sdk/cpp/structagora-1-1rtc-1-1-t-connection-info) & *connectionInfo*, [CONNECTION_CHANGED_REASON_TYPE](/zh-CN/api-reference/rtc-server-sdk/cpp/namespaceagora-1-1rtc#a329573b5363b2065b4069e5bf6013144) *reason*)
SDK 与频道的连接状态变更为 `CONNECTION_STATE_DISCONNECTED(1)` 时触发。
连接信息: [TConnectionInfo](/zh-CN/api-reference/rtc-server-sdk/cpp/structagora-1-1rtc-1-1-t-connection-info)。
连接状态变更原因: [CONNECTION_CHANGED_REASON_TYPE](/zh-CN/api-reference/rtc-server-sdk/cpp/namespaceagora-1-1rtc#a329573b5363b2065b4069e5bf6013144) 。
### onConnecting() [#onconnecting]
virtual void agora::rtc::IRtcConnectionObserver::onConnecting(const [TConnectionInfo](/zh-CN/api-reference/rtc-server-sdk/cpp/structagora-1-1rtc-1-1-t-connection-info) & *connectionInfo*, [CONNECTION_CHANGED_REASON_TYPE](/zh-CN/api-reference/rtc-server-sdk/cpp/namespaceagora-1-1rtc#a329573b5363b2065b4069e5bf6013144) *reason*)
SDK 与频道的连接状态变更为 `CONNECTION_STATE_CONNECTING(2)` 时触发。
连接信息: [TConnectionInfo](/zh-CN/api-reference/rtc-server-sdk/cpp/structagora-1-1rtc-1-1-t-connection-info)。
连接状态变更原因: [CONNECTION_CHANGED_REASON_TYPE](/zh-CN/api-reference/rtc-server-sdk/cpp/namespaceagora-1-1rtc#a329573b5363b2065b4069e5bf6013144) 。
### onReconnecting() [#onreconnecting]
virtual void agora::rtc::IRtcConnectionObserver::onReconnecting(const [TConnectionInfo](/zh-CN/api-reference/rtc-server-sdk/cpp/structagora-1-1rtc-1-1-t-connection-info) & *connectionInfo*, [CONNECTION_CHANGED_REASON_TYPE](/zh-CN/api-reference/rtc-server-sdk/cpp/namespaceagora-1-1rtc#a329573b5363b2065b4069e5bf6013144) *reason*)
SDK 与频道的连接状态变更为 `CONNECTION_STATE_RECONNECTING(4)` 时触发。
连接信息: [TConnectionInfo](/zh-CN/api-reference/rtc-server-sdk/cpp/structagora-1-1rtc-1-1-t-connection-info)。
连接状态变更原因: [CONNECTION_CHANGED_REASON_TYPE](/zh-CN/api-reference/rtc-server-sdk/cpp/namespaceagora-1-1rtc#a329573b5363b2065b4069e5bf6013144) 。
### onConnectionLost() [#onconnectionlost]
virtual void agora::rtc::IRtcConnectionObserver::onConnectionLost(const [TConnectionInfo](/zh-CN/api-reference/rtc-server-sdk/cpp/structagora-1-1rtc-1-1-t-connection-info) & *connectionInfo*)
SDK 与频道断开连接时触发。
连接信息: [TConnectionInfo](/zh-CN/api-reference/rtc-server-sdk/cpp/structagora-1-1rtc-1-1-t-connection-info)。
### onLastmileQuality() [#onlastmilequality]
virtual void agora::rtc::IRtcConnectionObserver::onLastmileQuality(const [QUALITY_TYPE](/zh-CN/api-reference/rtc-server-sdk/cpp/namespaceagora-1-1rtc#aeaf419fcafaa4d58da8b6d8718e31891) *quality*)
报告 last-mile 网络质量。
SDK 在调用 [startLastmileProbeTest](/zh-CN/api-reference/rtc-server-sdk/cpp/classagora-1-1rtc-1-1-i-rtc-connection#aca1f51af680b303f4ddbca3bff23baff) 两秒后触发该回调。
last-mile 网络质量: [QUALITY_TYPE](/zh-CN/api-reference/rtc-server-sdk/cpp/namespaceagora-1-1rtc#aeaf419fcafaa4d58da8b6d8718e31891) 。
### onLastmileProbeResult() [#onlastmileproberesult]
virtual void agora::rtc::IRtcConnectionObserver::onLastmileProbeResult(const [LastmileProbeResult](/zh-CN/api-reference/rtc-server-sdk/cpp/structagora-1-1rtc-1-1-lastmile-probe-result) & *result*)
通话前网络上下行 Last mile 质量探测报告回调。
调用 [startLastmileProbeTest](/zh-CN/api-reference/rtc-server-sdk/cpp/classagora-1-1rtc-1-1-i-rtc-connection#aca1f51af680b303f4ddbca3bff23baff) 方法 30 秒之后触发该回调。
上下行 Last mile 质量探测结果: [LastmileProbeResult](/zh-CN/api-reference/rtc-server-sdk/cpp/structagora-1-1rtc-1-1-lastmile-probe-result)。
### onTokenPrivilegeWillExpire() [#ontokenprivilegewillexpire]
virtual void agora::rtc::IRtcConnectionObserver::onTokenPrivilegeWillExpire(const char * *token*)
Token 服务将在 30s 内过期回调。
在通话过程中如果 Token 即将失效,SDK 会提前 30 秒触发该回调,提醒 app 更新 Token。
当收到该回调时,你需要重新在服务端生成新的 Token,然后调用 [renewToken](/zh-CN/api-reference/rtc-server-sdk/cpp/classagora-1-1rtc-1-1-i-rtc-connection#a718d33addd2e49f1932b666ab3551087) 将新生成的 Token 传给 SDK。
即将过期的 Token。
### onTokenPrivilegeDidExpire() [#ontokenprivilegedidexpire]
virtual void agora::rtc::IRtcConnectionObserver::onTokenPrivilegeDidExpire()
Token 已过期回调。
在通话过程中如果 Token 已失效,SDK 会触发该回调,提醒 app 更新 Token。
当收到该回调时,你需要重新在服务端生成新的 Token,然后调用 `connect` 重新连接频道。
### onConnectionFailure() [#onconnectionfailure]
virtual void agora::rtc::IRtcConnectionObserver::onConnectionFailure(const [TConnectionInfo](/zh-CN/api-reference/rtc-server-sdk/cpp/structagora-1-1rtc-1-1-t-connection-info) & *connectionInfo*, [CONNECTION_CHANGED_REASON_TYPE](/zh-CN/api-reference/rtc-server-sdk/cpp/namespaceagora-1-1rtc#a329573b5363b2065b4069e5bf6013144) *reason*)
SDK 与频道的连接状态变更为 `CONNECTION_STATE_FAILED(5)` 时触发。
连接信息: [TConnectionInfo](/zh-CN/api-reference/rtc-server-sdk/cpp/structagora-1-1rtc-1-1-t-connection-info)。
连接状态变更原因: [CONNECTION_CHANGED_REASON_TYPE](/zh-CN/api-reference/rtc-server-sdk/cpp/namespaceagora-1-1rtc#a329573b5363b2065b4069e5bf6013144) 。
### onUserJoined() [#onuserjoined]
virtual void agora::rtc::IRtcConnectionObserver::onUserJoined([user_id_t](/zh-CN/api-reference/rtc-server-sdk/cpp/namespaceagora#a67aa7eac4d2b30c5c02951f1303bcc48) *userId*)
远端用户加入频道时触发。
你可以通过该回调获取远端用户的 ID。
用户 ID。
### onUserLeft() [#onuserleft]
virtual void agora::rtc::IRtcConnectionObserver::onUserLeft([user_id_t](/zh-CN/api-reference/rtc-server-sdk/cpp/namespaceagora#a67aa7eac4d2b30c5c02951f1303bcc48) *userId*, [USER_OFFLINE_REASON_TYPE](/zh-CN/api-reference/rtc-server-sdk/cpp/namespaceagora-1-1rtc#a56ebc30a718928cb6998ba1424900fef) *reason*)
远端用户离开频道时触发。
你可以通过 `reason` 参数获取用户离开频道的原因。
用户 ID。
离开频道原因: [USER_OFFLINE_REASON_TYPE](/zh-CN/api-reference/rtc-server-sdk/cpp/namespaceagora-1-1rtc#a56ebc30a718928cb6998ba1424900fef) 。
### onTransportStats() [#ontransportstats]
virtual void agora::rtc::IRtcConnectionObserver::onTransportStats(const [RtcStats](/zh-CN/api-reference/rtc-server-sdk/cpp/structagora-1-1rtc-1-1-rtc-stats) & *stats*)
报告连接的传输统计信息。
当连接状态为 `CONNECTION_STATE_CONNECTED` 时,SDK 每两秒触发一次回调。
连接统计信息: [RtcStats](/zh-CN/api-reference/rtc-server-sdk/cpp/structagora-1-1rtc-1-1-rtc-stats)。
### onChangeRoleSuccess() [#onchangerolesuccess]
virtual void agora::rtc::IRtcConnectionObserver::onChangeRoleSuccess([CLIENT_ROLE_TYPE](/zh-CN/api-reference/rtc-server-sdk/cpp/namespaceagora-1-1rtc#a42f167813e36b5c11a8a1c659b877080) *oldRole*, [CLIENT_ROLE_TYPE](/zh-CN/api-reference/rtc-server-sdk/cpp/namespaceagora-1-1rtc#a42f167813e36b5c11a8a1c659b877080) *newRole*)
本地用户角色变更时触发。
本地用户变更前的角色:[CLIENT_ROLE_TYPE](/zh-CN/api-reference/rtc-server-sdk/cpp/namespaceagora-1-1rtc#a42f167813e36b5c11a8a1c659b877080)。
本地用户变更前的角色:[CLIENT_ROLE_TYPE](/zh-CN/api-reference/rtc-server-sdk/cpp/namespaceagora-1-1rtc#a42f167813e36b5c11a8a1c659b877080)。
### onChangeRoleFailure() [#onchangerolefailure]
virtual void agora::rtc::IRtcConnectionObserver::onChangeRoleFailure()
本地用户角色切换失败时触发。
### onUserNetworkQuality() [#onusernetworkquality]
virtual void agora::rtc::IRtcConnectionObserver::onUserNetworkQuality([user_id_t](/zh-CN/api-reference/rtc-server-sdk/cpp/namespaceagora#a67aa7eac4d2b30c5c02951f1303bcc48) *userId*, [QUALITY_TYPE](/zh-CN/api-reference/rtc-server-sdk/cpp/namespaceagora-1-1rtc#aeaf419fcafaa4d58da8b6d8718e31891) *txQuality*, [QUALITY_TYPE](/zh-CN/api-reference/rtc-server-sdk/cpp/namespaceagora-1-1rtc#aeaf419fcafaa4d58da8b6d8718e31891) *rxQuality*)
通话中每个用户的网络上下行 last mile 质量报告回调。
该回调描述每个用户在通话中的 last mile 网络状态,其中 last mile 是指设备到声网边缘服务器的网络状态。
该回调每 2 秒触发一次。如果远端有多个用户,该回调每 2 秒会被触发多次。
用户 ID。表示该回调报告的是持有该 ID 的用户的网络质量。
该用户的上行网络质量,基于发送码率、上行丢包率、平均往返时延和网络抖动计算。该值代表当前的上行网络质量,帮助判断是否可以支持当前设置的视频编码属性。 假设上行码率是 1000 Kbps,那么支持直播场景下 640 × 480 的分辨率、15 fps 的帧率没有问题,但是支持 1280 × 720 的分辨率就会有困难。详见 [QUALITY_TYPE](/zh-CN/api-reference/rtc-server-sdk/cpp/namespaceagora-1-1rtc#aeaf419fcafaa4d58da8b6d8718e31891) 。
该用户的下行网络质量,基于下行网络的丢包率、平均往返延时和网络抖动计算。详见 [QUALITY_TYPE](/zh-CN/api-reference/rtc-server-sdk/cpp/namespaceagora-1-1rtc#aeaf419fcafaa4d58da8b6d8718e31891) 。
### onNetworkTypeChanged() [#onnetworktypechanged]
virtual void agora::rtc::IRtcConnectionObserver::onNetworkTypeChanged([NETWORK_TYPE](/zh-CN/api-reference/rtc-server-sdk/cpp/namespaceagora-1-1rtc#ab5e06b511f978f1a997008401da46505) *type*)
本地网络类型发生改变回调。
本地网络连接类型发生改变时,SDK 会触发该回调,并在回调中明确当前的网络连接类型。 你可以通过该回调获取正在使用的网络类型;当连接中断时,该回调能辨别引起中断的原因是网络切换还是网络条件不好。
网络连接类型: [NETWORK_TYPE](/zh-CN/api-reference/rtc-server-sdk/cpp/namespaceagora-1-1rtc#ab5e06b511f978f1a997008401da46505) 。
### onApiCallExecuted() [#onapicallexecuted]
virtual void agora::rtc::IRtcConnectionObserver::onApiCallExecuted(int *err*, const char * *api*, const char * *result*)
API 方法已执行回调。
当方法调用失败时 SDK 返回的错误码。如果该方法调用成功,SDK 会返回 0。
SDK 执行的 API 方法。
SDK 调用 API 的结果。
### onError() [#onerror]
virtual void agora::rtc::IRtcConnectionObserver::onError(ERROR_CODE_TYPE *error*, const char * *msg*)
发生错误回调。
该回调方法表示 SDK 运行时出现了网络或媒体相关的错误。通常情况下,SDK 上报的错误意味着 SDK 无法自动恢复,需要 App 干预或提示用户。
错误码。
错误描述。
### onChannelMediaRelayStateChanged() [#onchannelmediarelaystatechanged]
virtual void agora::rtc::IRtcConnectionObserver::onChannelMediaRelayStateChanged(int *state*, int *code*)
跨频道媒体流转发状态发生改变回调。
当跨频道媒体流转发状态发生改变时,SDK 会触发该回调,并报告当前的转发状态以及相关的错误信息。
跨频道媒体流转发状态:
- `RELAY_STATE_IDLE(0)`: SDK 正在初始化。
- `RELAY_STATE_CONNECTING(1)`: SDK 尝试跨频道。
- `RELAY_STATE_RUNNING(2)`: 源频道主播成功加入目标频道。
- `RELAY_STATE_FAILURE(3)`: 发生异常,详见 code 中提示的错误信息。
跨频道媒体流转发出错的错误码:
- `RELAY_OK(0)`: 一切正常。
- `RELAY_ERROR_SERVER_ERROR_RESPONSE(1)`: 服务器回应出错。
- `RELAY_ERROR_SERVER_NO_RESPONSE(2)`: 服务器无回应。你可以调用 `disconnect` 方法离开频道。
- `RELAY_ERROR_NO_RESOURCE_AVAILABLE(3)`: SDK 无法获取服务,可能是因为服务器资源有限导致。
- `RELAY_ERROR_FAILED_JOIN_SRC(4)`: 服务器加入源频道失败。
- `RELAY_ERROR_FAILED_JOIN_DEST(5)`: 服务器加入目标频道失败。
- `RELAY_ERROR_FAILED_PACKET_RECEIVED_FROM_SRC(6)`: 服务器未收到源频道发送的数据。
- `RELAY_ERROR_FAILED_PACKET_SENT_TO_DEST(7)`: 源频道发送数据失败。
- `RELAY_ERROR_SERVER_CONNECTION_LOST(8)`: SDK 因网络质量不佳与服务器断开。你可以调用 `disconnect` 方法离开当前频道。
- `RELAY_ERROR_INTERNAL_ERROR(9)`: 服务器内部出错。
- `RELAY_ERROR_SRC_TOKEN_EXPIRED(10)`: 源频道的 Token 已过期。
- `RELAY_ERROR_DEST_TOKEN_EXPIRED(11)`: 目标频道的 Token 已过期。
### onEncryptionError() [#onencryptionerror]
virtual void agora::rtc::IRtcConnectionObserver::onEncryptionError([ENCRYPTION_ERROR_TYPE](/zh-CN/api-reference/rtc-server-sdk/cpp/namespaceagora-1-1rtc#a32a0270f2e3dab57953457ac1871b521) *errorType*)
内置加密出错回调。
调用 [enableEncryption](/zh-CN/api-reference/rtc-server-sdk/cpp/classagora-1-1rtc-1-1-i-rtc-connection#af34378df5af2c9e95518d1c8c0167d85) 开启加密后,如果发流端、收流端出现加解密出错,SDK 会触发该回调。
加密错误类型。