# 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 会触发该回调。 加密错误类型。