io.agora.rtc

## Interface IRtcConnObserver

-     public interface IRtcConnObserver

  The observer interface for RTC connection events.

- - ### Method Summary

    All Methods Instance Methods Default Methods Deprecated Methods
    Modifier and Type | Method and Description
    --- | ---
    `default int` | `onAIQoSCapabilityMissing(AgoraRtcConn agoraRtcConn, int defaultFallbackSenario)` Occurs when the client-side version lacks AIQoS capability support.
    `default void` | `onApiCallExecuted(AgoraRtcConn agoraRtcConn, int err, java.lang.String api, java.lang.String result)` Reports the result of an API call execution.
    `default void` | `onChangeRoleFailure(AgoraRtcConn agoraRtcConn)` Occurs when the local user fails to change the user role.
    `default void` | `onChangeRoleSuccess(AgoraRtcConn agoraRtcConn, int oldRole, int newRole)` Occurs when the role of the local user changes successfully.
    `default void` | `onChannelMediaRelayStateChanged(AgoraRtcConn agoraRtcConn, int state, int code)` Occurs when the state of the channel media relay changes.
    `default void` | `onConnected(AgoraRtcConn agoraRtcConn, RtcConnInfo connInfo, int reason)` Occurs when the connection state between the SDK and the Agora channel changes to CONNECTION_STATE_CONNECTED(3).
    `default void` | `onConnecting(AgoraRtcConn agoraRtcConn, RtcConnInfo connInfo, int reason)` Occurs when the connection state between the SDK and the Agora channel changes to CONNECTION_STATE_CONNECTING(2).
    `default void` | `onConnectionFailure(AgoraRtcConn agoraRtcConn, RtcConnInfo connInfo, int reason)` Occurs when the connection state between the SDK and the Agora channel changes to CONNECTION_STATE_FAILED(5).
    `default void` | `onConnectionLicenseValidationFailure(AgoraRtcConn agoraRtcConn, RtcConnInfo connInfo, int reason)` Occurs when connection license verification fails.
    `default void` | `onConnectionLost(AgoraRtcConn agoraRtcConn, RtcConnInfo connInfo)` Occurs when the SDK loses connection with the Agora channel.
    `default void` | `onContentInspectResult(AgoraRtcConn agoraRtcConn, int result)` Reports the result of content inspection.
    `default void` | `onCustomUserInfoUpdated(AgoraRtcConn agoraRtcConn, java.lang.String userId, java.lang.String customUserInfo)` Occurs when a remote user updates custom user info.
    `default void` | `onDisconnected(AgoraRtcConn agoraRtcConn, RtcConnInfo connInfo, int reason)` Occurs when the connection state between the SDK and the Agora channel changes to CONNECTION_STATE_DISCONNECTED(1).
    `default void` | `onEncryptionError(AgoraRtcConn agoraRtcConn, int errorType)` Occurs when an encryption error happens during the transmission.
    `default void` | `onError(AgoraRtcConn agoraRtcConn, int error, java.lang.String msg)` Reports an error during SDK runtime.
    `default void` | `onLastmileProbeResult(AgoraRtcConn agoraRtcConn, LastmileProbeResult result)` Reports the result of the last-mile network probe test.
    `default void` | `onLastmileQuality(AgoraRtcConn agoraRtcConn, int quality)` Reports the quality of the last-mile network.
    `default void` | `onLocalUserRegistered(AgoraRtcConn agoraRtcConn, int uid, java.lang.String userAccount)` Occurs when the local user successfully registers a user account by calling the joinChannelWithUserAccount method.
    `default void` | `onNetworkTypeChanged(AgoraRtcConn agoraRtcConn, int type)` Occurs when the network type is changed.
    `default void` | `onReconnected(AgoraRtcConn agoraRtcConn, RtcConnInfo connInfo, int reason)` Deprecated.
    `default void` | `onReconnecting(AgoraRtcConn agoraRtcConn, RtcConnInfo connInfo, int reason)` Occurs when the connection state between the SDK and the Agora channel changes to CONNECTION_STATE_RECONNECTING(4).
    `default void` | `onSnapshotTaken(AgoraRtcConn agoraRtcConn, java.lang.String channel, int userId, java.lang.String filePath, int width, int height, int errCode)` Occurs when a snapshot is successfully taken.
    `default void` | `onStreamMessageError(AgoraRtcConn agoraRtcConn, java.lang.String userId, int streamId, int code, int missed, int cached)` Reports the error that occurs when receiving data stream messages.
    `default void` | `onTokenPrivilegeDidExpire(AgoraRtcConn agoraRtcConn)` Occurs when the token has expired.
    `default void` | `onTokenPrivilegeWillExpire(AgoraRtcConn agoraRtcConn, java.lang.String token)` Occurs when the token expires in 30 seconds.
    `default void` | `onTransportStats(AgoraRtcConn agoraRtcConn, RtcStats stats)` Reports the transport statistics of the connection.
    `default void` | `onUploadLogResult(AgoraRtcConn agoraRtcConn, java.lang.String requestId, int success, int reason)` Reports the user log upload result.
    `default void` | `onUserAccountUpdated(AgoraRtcConn agoraRtcConn, int uid, java.lang.String userAccount)` Occurs when the user account information is updated.
    `default void` | `onUserJoined(AgoraRtcConn agoraRtcConn, java.lang.String userId)` Occurs when a remote user joins the channel.
    `default void` | `onUserLeft(AgoraRtcConn agoraRtcConn, java.lang.String userId, int reason)` Occurs when a remote user leaves the channel.
    `default void` | `onUserNetworkQuality(AgoraRtcConn agoraRtcConn, java.lang.String userId, int txQuality, int rxQuality)` Reports the network quality of each user.
    `default void` | `onWarning(AgoraRtcConn agoraRtcConn, int warning, java.lang.String msg)` Reports a warning during SDK runtime.

- - ### Method Detail

    - #### onConnected

          default void onConnected(AgoraRtcConn agoraRtcConn,
                                   RtcConnInfo connInfo,
                                   int reason)

      Occurs when the connection state between the SDK and the Agora channel changes to CONNECTION_STATE_CONNECTED(3).
      Parameters:
        `agoraRtcConn` - The connection object.
        `connInfo` - The information of the connection. See `RtcConnInfo`.
        `reason` - The reason of the connection state change. See `Constants.ConnectionChangedReasonType`.

    - #### onDisconnected

          default void onDisconnected(AgoraRtcConn agoraRtcConn,
                                      RtcConnInfo connInfo,
                                      int reason)

      Occurs when the connection state between the SDK and the Agora channel changes to CONNECTION_STATE_DISCONNECTED(1).
      Parameters:
        `agoraRtcConn` - The connection object.
        `connInfo` - The information of the connection. See `RtcConnInfo`.
        `reason` - The reason of the connection state change. See `Constants.ConnectionChangedReasonType`.

    - #### onConnecting

          default void onConnecting(AgoraRtcConn agoraRtcConn,
                                    RtcConnInfo connInfo,
                                    int reason)

      Occurs when the connection state between the SDK and the Agora channel changes to CONNECTION_STATE_CONNECTING(2).
      Parameters:
        `agoraRtcConn` - The connection object.
        `connInfo` - The information of the connection. See `RtcConnInfo`.
        `reason` - The reason of the connection state change. See `Constants.ConnectionChangedReasonType`.

    - #### onReconnecting

          default void onReconnecting(AgoraRtcConn agoraRtcConn,
                                      RtcConnInfo connInfo,
                                      int reason)

      Occurs when the connection state between the SDK and the Agora channel changes to CONNECTION_STATE_RECONNECTING(4).
      Parameters:
        `agoraRtcConn` - The connection object.
        `connInfo` - The information of the connection. See `RtcConnInfo`.
        `reason` - The reason of the connection state change. See `Constants.ConnectionChangedReasonType`.

    - #### onReconnected

          @Deprecated
          default void onReconnected(AgoraRtcConn agoraRtcConn,
                                                 RtcConnInfo connInfo,
                                                 int reason)

      Deprecated.
      Occurs when the connection is reestablished after a disconnection. Deprecated: Use `onConnected(AgoraRtcConn, RtcConnInfo, int)` with reason `Constants.ConnectionChangedReasonType.CONNECTION_CHANGED_REJOIN_SUCCESS` instead.
      Parameters:
        `agoraRtcConn` - The connection object.
        `connInfo` - The information of the connection. See `RtcConnInfo`.
        `reason` - The reason of the connection state change. See `Constants.ConnectionChangedReasonType`.

    - #### onConnectionLost

          default void onConnectionLost(AgoraRtcConn agoraRtcConn,
                                        RtcConnInfo connInfo)

      Occurs when the SDK loses connection with the Agora channel.
      Parameters:
        `agoraRtcConn` - The connection object.
        `connInfo` - The information of the connection. See `RtcConnInfo`.

    - #### onLastmileQuality

          default void onLastmileQuality(AgoraRtcConn agoraRtcConn,
                                         int quality)

      Reports the quality of the last-mile network. The SDK triggers this callback within two seconds after the app calls startLastmileProbeTest.
      Parameters:
        `agoraRtcConn` - The connection object.
        `quality` - Quality of the last-mile network. See `Constants.QualityType`.

    - #### onLastmileProbeResult

          default void onLastmileProbeResult(AgoraRtcConn agoraRtcConn,
                                             LastmileProbeResult result)

      Reports the result of the last-mile network probe test. The SDK triggers this callback within 30 seconds after the app calls startLastmileProbeTest.
      Parameters:
        `agoraRtcConn` - The connection object.
        `result` - The result of the last-mile network probe test. See `LastmileProbeResult`.

    - #### onTokenPrivilegeWillExpire

          default void onTokenPrivilegeWillExpire(AgoraRtcConn agoraRtcConn,
                                                  java.lang.String token)

      Occurs when the token expires in 30 seconds. The SDK triggers this callback to remind the app to get a new token before the token privilege expires. Upon receiving this callback, you must generate a new token on your server and call renewToken to pass the new token to the SDK.
      Parameters:
        `agoraRtcConn` - The connection object.
        `token` - The token that expires in 30 seconds.

    - #### onTokenPrivilegeDidExpire

          default void onTokenPrivilegeDidExpire(AgoraRtcConn agoraRtcConn)

      Occurs when the token has expired. Upon receiving this callback, you must generate a new token on your server and call renewToken to pass the new token to the SDK.
      Parameters:
        `agoraRtcConn` - The connection object.

    - #### onConnectionFailure

          default void onConnectionFailure(AgoraRtcConn agoraRtcConn,
                                           RtcConnInfo connInfo,
                                           int reason)

      Occurs when the connection state between the SDK and the Agora channel changes to CONNECTION_STATE_FAILED(5).
      Parameters:
        `agoraRtcConn` - The connection object.
        `connInfo` - The connection information. See `RtcConnInfo`.
        `reason` - The reason of the connection state change. See `Constants.ConnectionChangedReasonType`.

    - #### onConnectionLicenseValidationFailure

          default void onConnectionLicenseValidationFailure(AgoraRtcConn agoraRtcConn,
                                                            RtcConnInfo connInfo,
                                                            int reason)

      Occurs when connection license verification fails.
      Parameters:
        `agoraRtcConn` - The connection object.
        `connInfo` - The connection information. See `RtcConnInfo`.
        `reason` - The reason for the license validation failure.

    - #### onUserJoined

          default void onUserJoined(AgoraRtcConn agoraRtcConn,
                                    java.lang.String userId)

      Occurs when a remote user joins the channel. You can get the ID of the remote user in this callback.
      Parameters:
        `agoraRtcConn` - The connection object.
        `userId` - The ID of the remote user who joins the channel.

    - #### onUserLeft

          default void onUserLeft(AgoraRtcConn agoraRtcConn,
                                  java.lang.String userId,
                                  int reason)

      Occurs when a remote user leaves the channel. You can know why the user leaves the channel through the `reason` parameter.
      Parameters:
        `agoraRtcConn` - The connection object.
        `userId` - The ID of the user who leaves the channel.
        `reason` - The reason why the remote user leaves the channel. See `Constants.UserOfflineReasonType`.

    - #### onTransportStats

          default void onTransportStats(AgoraRtcConn agoraRtcConn,
                                        RtcStats stats)

      Reports the transport statistics of the connection. The SDK triggers this callback once every two seconds when the connection state is CONNECTION_STATE_CONNECTED.
      Parameters:
        `agoraRtcConn` - The connection object.
        `stats` - The transport statistics. See `RtcStats`.

    - #### onChangeRoleSuccess

          default void onChangeRoleSuccess(AgoraRtcConn agoraRtcConn,
                                           int oldRole,
                                           int newRole)

      Occurs when the role of the local user changes successfully.
      Parameters:
        `agoraRtcConn` - The connection object.
        `oldRole` - The previous role of the local user. See `Constants.ClientRoleType`.
        `newRole` - The current role of the local user. See `Constants.ClientRoleType`.

    - #### onChangeRoleFailure

          default void onChangeRoleFailure(AgoraRtcConn agoraRtcConn)

      Occurs when the local user fails to change the user role.
      Parameters:
        `agoraRtcConn` - The connection object.

    - #### onUserNetworkQuality

          default void onUserNetworkQuality(AgoraRtcConn agoraRtcConn,
                                            java.lang.String userId,
                                            int txQuality,
                                            int rxQuality)

      Reports the network quality of each user. The SDK triggers this callback once every two seconds to report the uplink and downlink network conditions of each user in the channel, including the local user.
      Parameters:
        `agoraRtcConn` - The connection object.
        `userId` - The ID of the user. If `userId` is empty, this callback reports the network quality of the local user.
        `txQuality` - The uplink network quality. See `Constants.QualityType`.
        `rxQuality` - The downlink network quality. See `Constants.QualityType`.

    - #### onNetworkTypeChanged

          default void onNetworkTypeChanged(AgoraRtcConn agoraRtcConn,
                                            int type)

      Occurs when the network type is changed.
      Parameters:
        `agoraRtcConn` - The connection object.
        `type` - The current network type. See `Constants.NetworkType`.

    - #### onApiCallExecuted

          default void onApiCallExecuted(AgoraRtcConn agoraRtcConn,
                                         int err,
                                         java.lang.String api,
                                         java.lang.String result)

      Reports the result of an API call execution. This is usually used for asynchronous operations.
      Parameters:
        `agoraRtcConn` - The connection object.
        `err` - The error code returned by the API call. See
        `api` - The API name that was called.
        `result` - The result string of the API call.

    - #### onContentInspectResult

          default void onContentInspectResult(AgoraRtcConn agoraRtcConn,
                                              int result)

      Reports the result of content inspection.
      Parameters:
        `agoraRtcConn` - The connection object.
        `result` - The content inspection result. See `Constants.ContentInspectResult`.

    - #### onSnapshotTaken

          default void onSnapshotTaken(AgoraRtcConn agoraRtcConn,
                                       java.lang.String channel,
                                       int userId,
                                       java.lang.String filePath,
                                       int width,
                                       int height,
                                       int errCode)

      Occurs when a snapshot is successfully taken.
      Parameters:
        `agoraRtcConn` - The connection object.
        `channel` - The channel name.
        `userId` - The user ID. If the user ID is 0, the snapshot is for the local user.
        `filePath` - The local path of the snapshot file.
        `width` - The width (pixels) of the snapshot.
        `height` - The height (pixels) of the snapshot.
        `errCode` - The error code. 0 means success.

    - #### onError

          default void onError(AgoraRtcConn agoraRtcConn,
                               int error,
                               java.lang.String msg)

      Reports an error during SDK runtime.
      Parameters:
        `agoraRtcConn` - The connection object.
        `error` - The error code. See `Constants.ErrorCodeType`.
        `msg` - The error message.

    - #### onWarning

          default void onWarning(AgoraRtcConn agoraRtcConn,
                                 int warning,
                                 java.lang.String msg)

      Reports a warning during SDK runtime.
      Parameters:
        `agoraRtcConn` - The connection object.
        `warning` - The warning code.
        `msg` - The warning message.

    - #### onChannelMediaRelayStateChanged

          default void onChannelMediaRelayStateChanged(AgoraRtcConn agoraRtcConn,
                                                       int state,
                                                       int code)

      Occurs when the state of the channel media relay changes.
      Parameters:
        `agoraRtcConn` - The connection object.
        `state` - The state code.
        `code` - The error code.

    - #### onLocalUserRegistered

          default void onLocalUserRegistered(AgoraRtcConn agoraRtcConn,
                                             int uid,
                                             java.lang.String userAccount)

      Occurs when the local user successfully registers a user account by calling the joinChannelWithUserAccount method. This callback reports the user ID and user account of the local user.
      Parameters:
        `agoraRtcConn` - The connection object.
        `uid` - The ID of the local user.
        `userAccount` - The user account of the local user.

    - #### onUserAccountUpdated

          default void onUserAccountUpdated(AgoraRtcConn agoraRtcConn,
                                            int uid,
                                            java.lang.String userAccount)

      Occurs when the user account information is updated. Technical Preview, please do not depend on this event.
      Parameters:
        `agoraRtcConn` - The connection object.
        `uid` - The ID of the local user.
        `userAccount` - The user account of the local user.

    - #### onStreamMessageError

          default void onStreamMessageError(AgoraRtcConn agoraRtcConn,
                                            java.lang.String userId,
                                            int streamId,
                                            int code,
                                            int missed,
                                            int cached)

      Reports the error that occurs when receiving data stream messages.
      Parameters:
        `agoraRtcConn` - The connection object.
        `userId` - The ID of the user sending the data stream.
        `streamId` - The ID of the data stream.
        `code` - The error code.
        `missed` - The number of lost messages.
        `cached` - The number of incoming cached messages when the data stream is interrupted.

    - #### onEncryptionError

          default void onEncryptionError(AgoraRtcConn agoraRtcConn,
                                         int errorType)

      Occurs when an encryption error happens during the transmission.
      Parameters:
        `agoraRtcConn` - The connection object.
        `errorType` - The type of the encryption error. See `Constants.EncryptionErrorType`.

    - #### onUploadLogResult

          default void onUploadLogResult(AgoraRtcConn agoraRtcConn,
                                         java.lang.String requestId,
                                         int success,
                                         int reason)

      Reports the user log upload result.
      Parameters:
        `agoraRtcConn` - The connection object.
        `requestId` - Request ID of the upload.
        `success` - Whether the upload was successful.
        `reason` - Reason for the upload result. 0: OK, 1: Network Error, 2: Server Error. See `Constants.UploadErrorReason`.

    - #### onCustomUserInfoUpdated

          default void onCustomUserInfoUpdated(AgoraRtcConn agoraRtcConn,
                                               java.lang.String userId,
                                               java.lang.String customUserInfo)

      Occurs when a remote user updates custom user info.
      Parameters:
        `agoraRtcConn` - The connection object.
        `userId` - The remote user id.
        `customUserInfo` - The updated custom user info.

    - #### onAIQoSCapabilityMissing

          default int onAIQoSCapabilityMissing(AgoraRtcConn agoraRtcConn,
                                               int defaultFallbackSenario)

      Occurs when the client-side version lacks AIQoS capability support. This callback is triggered when the client's SDK version doesn't support AIQoS functionality (determined by version compatibility, not the specific scenario chosen by the client). When this happens, the server receives an OnAIQoSCapabilityMissing notification. In this callback, developers can return the desired audio scenario for the SDK to automatically switch to. If automatic switching is not desired, return -1 and manually call localUser.updateAudioTrack(scenario) to perform the switch.
      Parameters:
        `agoraRtcConn` - The connection object.
        `defaultFallbackSenario` - The default fallback scenario. See `Constants`.
      Returns:
        The desired audio scenario to switch to, or -1 to disable automatic switching.