网络及其他

介绍跟网络相关的方法以及其他方法和回调。

complain

投诉通话质量。

Java

public abstract int complain(String callId, String description);

该方法允许用户就通话质量进行投诉。需要在离开频道后调用。

参数

参数名	描述
callId	通话 ID。你可以通过调用 getCallId 获取该参数。
description	（非必选项）通话的描述。长度应小于 800 字节。

返回值

• 0: 方法调用成功。

• < 0: 方法调用失败。详见错误码了解详情和解决建议。

  • -2: 参数无效。

  • -3：SDK 尚未准备好。可能的原因有：

    • RtcEngine 初始化失败。请重新初始化 RtcEngine。

    • 调用方法时用户尚未加入频道。请检查方法的调用逻辑。

    • 调用 rate 或 complain 方法时用户尚未离开频道。请检查方法的调用逻辑。

    • 请检查是否已开启音频模块。请检查程序集完整性。

所属接口类

• RtcEngine

enableEncryption

开启或关闭内置加密。

Java

public abstract int enableEncryption(boolean enabled, EncryptionConfig config);

在安全要求较高的场景下，建议你在加入频道前，调用本方法开启内置加密。

同一频道内所有用户必须使用相同的加密模式和密钥。用户离开频道后，SDK 会自动关闭加密。如需重新开启加密，你需要在用户再次加入频道前调用该方法。

注意： 如果开启了内置加密，则不能使用旁路推流功能。

参数

参数名	描述
enabled	是否开启内置加密： true: 开启内置加密。 false: 关闭内置加密。
config	配置内置加密模式和密钥。详见 EncryptionConfig。

返回值

• 0: 方法调用成功。

• < 0: 方法调用失败

  • -2: 调用了无效的参数。需重新指定参数。

  • -4: 设置的加密模式不正确或加载外部加密库失败。需检查枚举值是否正确或重新加载外部加密库。

  • -7: SDK 尚未初始化。需在调用 API 之前已创建 RtcEngine 对象并完成初始化。

所属接口类

• RtcEngine

enableWebSdkInteroperability

打开与 Web SDK 的互通（仅在直播场景适用）。

Java

public abstract int enableWebSdkInteroperability(boolean enabled);

弃用:

该方法已废弃，SDK 自动开启与 Web SDK 的互通，无需调用该方法开启。

该方法打开或关闭与 Web SDK 的互通。如果有用户通过 Web SDK 加入频道，请确保调用该方法，否则 Web 端用户看 Native 端的画面会是黑屏。

该方法仅在直播场景下适用，通信场景下默认互通是打开的。

参数

参数名	描述
enabled	是否打开与 Web SDK 的互通： true: 打开互通。 false: (默认) 关闭互通。

返回值

• 0: 方法调用成功。

• < 0: 方法调用失败。详见错误码了解详情和解决建议。

所属接口类

• RtcEngine

getCallId

获取通话 ID。

Java

public abstract String getCallId();

客户端在每次加入频道后会生成一个对应的 callId，标识该客户端的此次通话。有些方法，如 rate、complain 等，需要在通话结束后调用，向 SDK 提交反馈。这些方法中需要填入指定的 callId 参数。

注意： 该方法需要在加入频道后调用。

返回值

通话 ID。

所属接口类

• RtcEngine

getConnectionState

获取当前网络连接状态。

Java

public abstract RtcConnection.CONNECTION_STATE_TYPE getConnectionState();

该方法在加入频道前后都能调用。

返回值

当前网络连接状态。

所属接口类

• RtcEngine

getConnectionStateEx

获取当前网络连接状态。

Java

public abstract RtcConnection.CONNECTION_STATE_TYPE getConnectionStateEx(
      RtcConnection connection);

该方法在加入频道前后都能调用。

参数

参数名	描述
connection	Connection 信息。详见 RtcConnection。

返回值

当前网络连接状态。

所属接口类

• RtcEngineEx

getCurrentMonotonicTimeInMs

获取 SDK 当前的 Monotonic Time。

Java

public abstract long getCurrentMonotonicTimeInMs();

自从

v4.2.0

Monotonic Time 是指一个单调递增的时间序列，它的值会随着时间的推移而增加。单位为毫秒。

在自定义视频采集、自定义音频采集场景中，为确保音视频同步，声网建议你调用该方法获取 SDK 当前的 Monotonic Time 后，将该值传入采集的视频帧（VideoFrame）、音频帧（AudioFrame）的时间戳参数。

返回值

• ≥0: 方法调用成功，返回 SDK 当前的 Monotonic Time（毫秒）。

• < 0: 方法调用失败。详见错误码了解详情和解决建议。

所属接口类

• RtcEngine

getErrorDescription

获取警告或错误描述。

Java

public static String getErrorDescription(int error)

参数

参数名	描述
error	SDK 报告的错误码或警告码。

返回值

具体的错误或警告描述。

所属接口类

• RtcEngine

getNativeHandle

获取 Native SDK 的 C++ 句柄。

Java

public abstract long getNativeHandle();

该方法获取 Native SDK 引擎 的 C++ 句柄，用于包括注册音视频回调在内的特殊场景。

返回值

SDK 引擎的 Native 句柄。

所属接口类

• RtcEngine

getNetworkType

获取本地网络连接类型。

Java

public abstract int getNetworkType();

自从

v4.0.1

你可以在任何阶段通过该方法获取正在使用的网络类型。

注： 该方法在加入频道前后均可调用。

返回值

• ≥ 0: 方法调用成功，返回本地网络连接类型。

  • 0：网络连接已断开。

  • 1：网络类型为 LAN。

  • 2：网络类型为 Wi-Fi(包含热点）。

  • 3：网络类型为 2G 移动网络。

  • 4：网络类型为 3G 移动网络。

  • 5：网络类型为 4G 移动网络。

  • 6：网络类型为 5G 移动网络。

• < 0: 方法调用失败，返回错误码。

  • -1：网络连接类型未知。

所属接口类

• RtcEngine

getNtpWallTimeInMs

获取当前的 NTP (网络时间协议) 时间。

Java

public abstract long getNtpWallTimeInMs();

自从

v4.2.0

在实时合唱的场景中，特别是在各个接收端由于网络原因导致下行链路不一致的情况下，你可以调用该方法来获取当前的 NTP 时间作为基准时间，以对齐多个接收端的歌词和音乐，实现合唱同步。

返回值

当前 NTP 时间的 Unix 时间戳 (毫秒)。

所属接口类

• RtcEngine

getSdkVersion

获取 SDK 版本。

Java

public static String getSdkVersion()

返回值

当前的 SDK 版本号。格式为字符串。

所属接口类

• RtcEngine

rate

给通话评分。

Java

public abstract int rate(String callId, int rating, String description);

注意： 该方法需要在用户离开频道后调用。

参数

参数名	描述
callId	通话 ID。你可以通过调用 getCallId 获取该参数。
rating	给通话的评分，最低 1 分，最高 5 分，如超过这个范围，SDK 会返回 -2(ERR_INVALID_ARGUMENT) 错误。
description	（非必选项）给通话的描述。长度应小于 800 字节。

返回值

• 0: 方法调用成功。

• < 0: 方法调用失败。详见错误码了解详情和解决建议。

  • -2(ERR_INVALID_ARGUMENT)。

  • -3(ERR_NOT_READY)。

所属接口类

• RtcEngine

sendCustomReportMessage

发送自定义上报消息。

Java

public abstract int sendCustomReportMessage(
      String id, String category, String event, String label, int value);

声网提供自定义数据上报和分析服务。该服务当前处于免费内测期。内测期提供的能力为 6 秒内最多上报 10 条数据，每条自定义数据不能超过 256 字节，每个字符串不能超过 100 字节。如需试用该服务，请联系 sales@agora.io 开通并商定自定义数据格式。

所属接口类

• RtcEngine

sendCustomReportMessageEx

自定义数据上报和分析服务。

Java

public abstract int sendCustomReportMessageEx(
      String id, String category, String event, String label, int value, RtcConnection connection);

声网提供自定义数据上报和分析服务。该服务当前处于免费内测期。内测期提供的能力为 6 秒内最多上报 10 条数据，每条自定义数据不能超过 256 字节，每个字符串不能超过 100 字节。如需试用该服务，请联系 sales@agora.io 开通并商定自定义数据格式。

所属接口类

• RtcEngineEx

setAVSyncSource

设置发流端音画同步。

Java

public abstract int setAVSyncSource(String channelId, int uid);

同一用户可能使用两个设备分别发送音频流和视频流，为保证接收端听到和看到的音频和视频的时间同步性，你可以在视频发送端调用该方法，并传入音频发送端的频道名、用户 ID。 SDK 会以发送的音频流的时间戳为基准进行自动调节发送的视频流，以保证即使在两个发送端的上行网络情况不一致（如分别使用 Wi-Fi 和 4G 网络）的情况下，也能让接收到的音视频具有时间同步性。

注意： 建议你在加入频道前调用该方法。

参数

参数名	描述
channelId	标识音频发送端所在频道的频道名。
uid	音频发送端的用户 ID。

返回值

• 0: 方法调用成功。

• < 0: 方法调用失败。详见错误码了解详情和解决建议。

所属接口类

• RtcEngine

setCloudProxy

设置云代理服务。

Java

public abstract int setCloudProxy(int proxyType);

当用户的网络访问受到防火墙限制时，你需要将声网提供的 IP 和端口号添加到防火墙白名单，然后调用该方法开启云代理，并通过 proxyType 参数设置云代理类型。

成功连接云代理后，SDK 会触发 onConnectionStateChanged (CONNECTION_STATE_CONNECTING, CONNECTION_CHANGED_SETTING_PROXY_SERVER) 回调。

如果你想关闭已设置的 Force UDP 或 Force TCP 云代理，请调用 setCloudProxy(TRANSPORT_TYPE_NONE_PROXY)。

如果你想更改已设置的云代理类型，请先调用 setCloudProxy(TRANSPORT_TYPE_NONE_PROXY)，再调用 setCloudProxy 并传入你期望的 proxyType 值。

注意：

• 建议你在频道外调用该方法。

• 如果用户处于内网防火墙环境下，使用 Force UDP 云代理时，旁路推流和跨频道媒体流转发功能不可用。

• 使用 Force UDP 云代理时，调用 startAudioMixing [2/2] 方法时无法播放 HTTP 协议的在线音频文件。旁路推流和跨频道媒体流转发功能会使用 TCP 协议的云代理。

参数

参数名	描述
proxyType	云代理类型。 TRANSPORT_TYPE_NONE_PROXY（0）：自动模式。SDK 默认开启该模式。在该模式下，SDK 优先连接 SD-RTN™，如果连接失败，自动切换到 TLS 443。 TRANSPORT_TYPE_UDP_PROXY（1）：UDP 协议的云代理，即 Force UDP 云代理模式。在该模式下，SDK 始终通过 UDP 协议传输数据。 TRANSPORT_TYPE_TCP_PROXY（2）：TCP（加密）协议的云代理，即 Force TCP 云代理模式。在该模式下，SDK 始终通过 TLS 443 传输数据。 该参数为必填参数，如果你不赋值，SDK 会报错。

返回值

• 0: 方法调用成功。

• < 0: 方法调用失败。

  • -2: 传入的参数无效。

  • -7: SDK 尚未初始化。

所属接口类

• RtcEngine

setEncryptionMode

启用内置的加密方案。

Java

public abstract int setEncryptionMode(String encryptionMode);

弃用

请改用 enableEncryption 方法。

SDK 支持内置加密方案，默认支持 AES-128-GCM。如需采用其他加密方案，可以调用本方法。同一频道内的所有用户必须设置相同的加密方式和 secret 才能进行通话。关于这几种加密方式的区别，请参考 AES 加密算法的相关资料。

注意： 在调用本方法前，请先调用 setEncryptionSecret 启用内置加密功能。

参数

参数名	描述
encryptionMode	加密模式： "aes-128-xts": 128 位 AES 加密，XTS 模式； "aes-128-ecb": 128 位 AES 加密，ECB 模式； "aes-256-xts": 256 位 AES 加密，XTS 模式； "sm4-128-ecb": 128 位 SM4 加密，ECB 模式； "aes-128-gcm": 128 位 AES 加密，GCM 模式； "aes-256-gcm": 256 位 AES 加密，GCM 模式； "": 设置为空字符串时，默认使用加密方式 "aes-128-gcm"。

返回值

• 0: 方法调用成功。

• < 0: 方法调用失败。详见错误码了解详情和解决建议。

所属接口类

• RtcEngine

setEncryptionSecret

启用内置加密，并设置数据加密密码。

Java

public abstract int setEncryptionSecret(String secret);

弃用

请改用 enableEncryption 方法。

在加入频道之前， app 需调用该方法指定 secret 来启用内置的加密功能，同一频道内的所有用户应设置相同的 secret。 当用户离开频道时，该频道的 secret 会自动清除。如果未指定 secret 或将 secret 设置为空，则无法激活加密功能。

注意：

• 请不要在旁路推流时调用此方法。

• 为保证最佳传输效果，请确保加密后的数据大小不超过原始数据大小 + 16 字节。16 字节是 AES 通用加密模式下最大填充块大小。

参数

参数名	描述
secret	加密密码。

返回值

• 0: 方法调用成功。

• < 0: 方法调用失败。详见错误码了解详情和解决建议。

所属接口类

• RtcEngine

setLocalAccessPoint

配置与声网私有媒体服务器 Native 接入模块的连接。

Java

public abstract int setLocalAccessPoint(LocalAccessPointConfiguration config);

成功部署声网私有媒体服务器并在内网终端集成 RTC SDK v4.x 后，你可以调用该方法指定 Local Access Point，给 SDK 分配 Native 接入模块。

注意：

• 该方法仅在部署声网混合云方案后生效。你可以联系 sales@agora.io 了解和部署声网混合云。

• 该方法需要在加入频道前调用。

参数

参数名	描述
config	Local Access Point 配置。详见 LocalAccessPointConfiguration。

返回值

• 0: 方法调用成功。

• < 0: 方法调用失败。详见错误码了解详情和解决建议。

所属接口类

• RtcEngine

setLogFile

设置日志文件

Java

public abstract int setLogFile(String filePath);

弃用

此方法已废弃，请改用 create [2/2] 中的 logConfig 参数设置日志文件路径 。

设置 SDK 的输出 log 文件。SDK 运行时产生的所有 log 将写入该文件。App 必须保证指定的目录存在而且可写。

注：
如需调用本方法，请在调用 create [2/2] 方法初始化 RtcEngine 对象后立即调用，否则输出日志可能不完整。

参数

参数名	描述
filePath	日志文件的完整路径。该日志文件为 UTF-8 编码。

返回值

• 0: 方法调用成功。

• < 0: 方法调用失败。详见错误码了解详情和解决建议。

所属接口类

• RtcEngine

setLogFileSize

设置 SDK 输出的日志文件的大小。

Java

public abstract int setLogFileSize(long fileSizeInKBytes);

弃用

该方法已废弃，请改用 create [2/2] 中的 logConfig 参数设置日志文件大小。

默认情况下，SDK 会生成 5 个 SDK 日志文件和 5 个 API 调用日志文件，规则如下：

• SDK 日志文件的名称分别为：agorasdk.log、agorasdk.1.log、agorasdk.2.log、agorasdk.3.log、agorasdk.4.log。

• API 调用日志文件的名称分别为：agoraapi.log、agoraapi.1.log、agoraapi.2.log、agoraapi.3.log、agoraapi.4.log。

• 每个 SDK 日志文件的默认大小为 1,024 KB；API 调用日志文件的默认大小为 2,048 KB。日志文件均为 UTF-8 编码。

• 最新的日志永远写在 agorasdk.log 和 agoraapi.log 中。

• 当 agorasdk.log 写满后，SDK 会按照以下顺序对日志文件进行操作：

  • 删除 agorasdk.4.log 文件（如有）。

  • 将agorasdk.3.log 重命名为 agorasdk.4.log。

  • 将agorasdk.2.log 重命名为 agorasdk.3.log。

  • 将agorasdk.1.log 重命名为 agorasdk.2.log。

  • 新建 agorasdk.log 文件。

• agoraapi.log 文件的覆盖规则与 agorasdk.log 相同。

注：
该方法仅用于设置 agorasdk.log 文件的大小，对agoraapi.log不生效。

参数

参数名	描述
fileSizeInKBytes	单个 agorasdk.log 日志文件的大小，单位为 KB，取值范围为 [128,20480]，默认值为 2,048 KB。如果你将 fileSizeInKByte 设为小于 128 KB，SDK 会自动调整到 128 KB；如果你将 fileSizeInKByte 设为大于 20,480 KB，SDK 会自动调整到 20,480 KB。

返回值

• 0: 方法调用成功。

• < 0: 方法调用失败。详见错误码了解详情和解决建议。

所属接口类

• RtcEngine

setLogFilter

设置日志输出等级。

Java

public abstract int setLogFilter(int filter);

弃用

请改用 create [2/2] 中的 logConfig。

该方法设置 SDK 的输出日志输出等级。不同的输出等级可以单独或组合使用。日志级别顺序依次为 LOG_FILTER_OFF、LOG_FILTER_CRITICAL、LOG_FILTER_ERROR、LOG_FILTER_WARN、LOG_FILTER_INFO 和 LOG_FILTER_DEBUG。 选择一个级别，你就可以看到在该级别之前所有级别的日志信息。

例如，你选择 LOG_FILTER_WARN 级别，就可以看到在 LOG_FILTER_CRITICAL、LOG_FILTER_ERROR 和 LOG_FILTER_WARN 级别的日志信息。

参数

参数名

描述

filter

日志过滤等级。 LOG_FILTER_OFF (0)：不输出日志信息。 LOG_FILTER_DEBUG (0x80f)：输出所有 API 日志信息。如果你想获取最完整的日志，可以将日志级别设为该等级。 LOG_FILTER_INFO (0x0f)：输出 LOG_FILTER_CRITICAL、LOG_FILTER_ERROR、LOG_FILTER_WARN 和 LOG_FILTER_INFO 级别的日志信息。建议你将日志级别设为该等级。 LOG_FILTER_WARN (0x0e)：输出 LOG_FILTER_CRITICAL、LOG_FILTER_ERROR 和 LOG_FILTER_WARN 级别的日志信息。 LOG_FILTER_ERROR (0x0c)：输出 LOG_FILTER_CRITICAL 和 LOG_FILTER_ERROR 级别的日志信息。 LOG_FILTER_CRITICAL (0x08)：输出 LOG_FILTER_CRITICAL 级别的日志信息。

返回值

• 0: 方法调用成功。

• < 0: 方法调用失败。详见错误码了解详情和解决建议。

所属接口类

• RtcEngine

setLogLevel

设置 SDK 的日志输出级别。

Java

public abstract int setLogLevel(int level);

弃用

该方法已经废弃。请改用 RtcEngineConfig 设置日志输出级别。

选择一个级别，你就可以看到该级别的日志信息。

参数

参数名	描述
level	日志级别: LogLevel。

返回值

• 0: 方法调用成功。

• < 0: 方法调用失败。详见错误码了解详情和解决建议。

所属接口类

• RtcEngine

setParameters

SDK 的 JSON 配置信息，用于提供技术预览或特别定制功能。

Java

public abstract int setParameters(String parameters);

参数

参数名	描述
parameters	JSON 字符串形式的参数。

返回值

• 0: 方法调用成功。

• < 0: 方法调用失败。详见错误码了解详情和解决建议。

所属接口类

• RtcEngine

startEchoTest [1/3]

开始语音通话回路测试。

Java

public abstract int startEchoTest();

弃用

该方法已废弃，请改用 startEchoTest [3/3]。

该方法启动语音通话测试，目的是测试系统的音频设备（耳麦、扬声器等）和网络连接是否正常。在测试过程中，用户先说一段话，声音会在 10 秒后回放出来。如果 10 秒后用户能正常听到自己刚才说的话，就表示系统音频设备和网络连接都是正常的。

注意：

• 请在加入频道前调用该方法。

• 调用 startEchoTest [1/3] 后必须调用 stopEchoTest 以结束测试，否则不能进行下一次回声测试，也无法加入频道。

• 直播场景下，该方法仅能由用户角色为主播的用户调用。

返回值

• 0: 方法调用成功。

• < 0: 方法调用失败。详见错误码了解详情和解决建议。

所属接口类

• RtcEngine

startEchoTest [2/3]

开始语音通话回路测试。

Java

public abstract int startEchoTest(int intervalInSeconds);

弃用

该方法自 v4.0.1 废弃，请改用 startEchoTest [3/3]。

该方法启动语音通话测试，目的是测试系统的音频设备（耳麦、扬声器等）和网络连接是否正常。在测试过程中，用户先说一段话，声音会在设置的时间间隔（单位为秒）后回放出来。如果用户能正常听到自己刚才说的话，就表示系统音频设备和网络连接都是正常的。

注意：

• 请在加入频道前调用该方法。

• 调用 startEchoTest [2/3] 后必须调用 stopEchoTest 以结束测试，否则不能进行下一次回声测试，也无法加入频道。

• 直播场景下，该方法仅能由用户角色为主播的用户调用。

参数

参数名	描述
intervalInSeconds	设置返回语音通话回路测试结果的时间间隔，取值范围为 [2,10]，单位为秒。

返回值

• 0: 方法调用成功。

• < 0: 方法调用失败。详见错误码了解详情和解决建议。

所属接口类

• RtcEngine

startEchoTest [3/3]

开始音视频通话回路测试。

Java

public abstract int startEchoTest(EchoTestConfiguration config);

为测试用户本地发流、收流是否正常，你可以调用该方法进行音视频通话回路测试，即测试系统的音视频设备和用户的上下行网络是否正常。

开始测试后，用户需发出声音或面对摄像头，音频或视频会在约 2 秒后播放出来。如果音频播放正常，则表示系统音频设备和用户上下行网络均正常； 如果视频播放正常，则表示系统视频设备和用户上下行网络均正常。 注意：

• 该方法在加入频道前后均可调用。在频道内调用时，需确保当前没有发布音视频流。

• 调用该方法后，必须调用 stopEchoTest 结束测试，否则该用户无法进行下一次音视频通话回路测试， 也无法加入频道。

• 直播场景下，该方法仅能由主播调用。

参数

参数名	描述
config	音视频通话回路测试的配置。详见 EchoTestConfiguration。

返回值

• 0: 方法调用成功。

• < 0: 方法调用失败。详见错误码了解详情和解决建议。

所属接口类

• RtcEngine

startLastmileProbeTest

开始通话前网络质量探测。

Java

public abstract int startLastmileProbeTest(LastmileProbeConfig config);

开始通话前网络质量探测，向用户反馈上下行网络的带宽、丢包、网络抖动和往返时延数据。

启用该方法后，SDK 会依次返回如下 2 个回调：

• onLastmileQuality，视网络情况约 2 秒内返回。该回调通过打分反馈上下行网络质量，更贴近用户的主观感受。

• onLastmileProbeResult，视网络情况约 30 秒内返回。该回调通过具体数据反馈上下行网络质量，更加客观。

  该方法主要用于以下两种场景：

• 用户加入频道前，可以调用该方法判断和预测目前的上行网络质量是否足够好。

• 直播场景下，当用户角色想由观众切换为主播时，可以调用该方法判断和预测目前的上行网络质量是否足够好。

注意：

• 调用该方法后，在收到 onLastmileQuality 和 onLastmileProbeResult 回调之前请不要调用其他方法，否则可能会由于 API 操作过于频繁导致此方法无法执行。

• 在直播场景中，如果本地用户为主播，请勿加入频道后调用该方法。

参数

参数名	描述
config	Last mile 网络探测配置，详见 LastmileProbeConfig。

返回值

• 0: 方法调用成功。

• < 0: 方法调用失败。详见错误码了解详情和解决建议。

所属接口类

• RtcEngine

stopEchoTest

停止语音通话回路测试。

Java

public abstract int stopEchoTest();

返回值

• 0: 方法调用成功。

• < 0: 方法调用失败。

• -5(ERR_REFUSED): 停止测试失败，可能是测试不在运行中。

所属接口类

• RtcEngine

stopLastmileProbeTest

停止通话前网络质量探测。

Java

public abstract int stopLastmileProbeTest();

返回值

• 0: 方法调用成功。

• < 0: 方法调用失败。详见错误码了解详情和解决建议。

所属接口类

• RtcEngine

onConnectionBanned

网络连接已被服务器禁止回调。

Java

public void onConnectionBanned() {}

弃用:

请改用 onConnectionStateChanged。

所属接口类

• IRtcEngineEventHandler

onConnectionInterrupted

网络连接中断回调。

Java

public void onConnectionInterrupted() {}

弃用:

请改用 onConnectionStateChanged 回调。

SDK 在和服务器建立连接后，失去了网络连接超过 4 秒，会触发该回调。在触发事件后，SDK 会主动重连服务器，所以该事件可以用于 UI 提示。该回调与 onConnectionLost 的区别是：

• onConnectionInterrupted 回调一定是发生在成功加入频道后，且 SDK 刚失去和服务器连接超过 4 秒时触发。

• onConnectionLost 回调是无论是否成功加入频道，只要 10 秒内和服务器无法建立连接都会触发。

如果 SDK 在断开连接后，20 分钟内还是没能重新加入频道，SDK 会停止尝试重连。

所属接口类

• IRtcEngineEventHandler

onConnectionLost

网络连接中断，且 SDK 无法在 10 秒内连接服务器回调。

Java

public void onConnectionLost() {}

SDK 在调用 joinChannel [2/2] 后，无论是否加入成功，只要 10 秒和服务器无法连接就会触发该回调。如果 SDK 在断开连接后，20 分钟内还是没能重新加入频道，SDK 会停止尝试重连。

所属接口类

• IRtcEngineEventHandler

onConnectionStateChanged

网络连接状态已改变回调。

Java

public void onConnectionStateChanged(int state, int reason) {}

该回调在网络连接状态发生改变的时候触发，并告知用户当前的网络连接状态和引起网络状态改变的原因。

参数

参数名	描述
state	当前网络连接状态。 CONNECTION_STATE_DISCONNECTED (1)：网络连接断开。 CONNECTION_STATE_CONNECTING (2)：建立网络连接中。 CONNECTION_STATE_CONNECTED (3)：网络已连接。 CONNECTION_STATE_RECONNECTING (4)：重新建立网络连接中 。 CONNECTION_STATE_FAILED (5)：网络连接失败 。
reason	CONNECTION_CHANGED_CONNECTING (0)：建立网络连接中 。 CONNECTION_CHANGED_JOIN_SUCCESS (1)：成功加入频道 。 CONNECTION_CHANGED_INTERRUPTED (2)：网络连接中断 。 CONNECTION_CHANGED_BANNED_BY_SERVER (3)：网络连接被服务器禁止 。 CONNECTION_CHANGED_JOIN_FAILED (4)：加入频道失败 。 CONNECTION_CHANGED_LEAVE_CHANNEL (5)：离开频道 。 CONNECTION_CHANGED_INVALID_APP_ID (6)：不是有效的 APP ID。请更换有效的 APP ID 重新加入频道 。 CONNECTION_CHANGED_INVALID_CHANNEL_NAME (7)：不是有效的频道名。请更换有效的频道名重新加入频道。 CONNECTION_CHANGED_INVALID_TOKEN (8)：生成的 Token 无效。一般有以下原因： 在控制台上启用了 App Certificate，但加入频道未使用 Token。当启用了 App Certificate，必须使用 Token。 在调用 joinChannel [2/2] 加入频道时指定的 uid 与生成 Token 时传入的 uid 不一致。 CONNECTION_CHANGED_TOKEN_EXPIRED (9)：当前使用的 Token 过期，不再有效，需要重新在你的服务端申请生成 Token 。 CONNECTION_CHANGED_REJECTED_BY_SERVER (10)：此用户被服务器禁止 。 CONNECTION_CHANGED_SETTING_PROXY_SERVER (11)：由于设置了代理服务器，SDK 尝试重连 。 CONNECTION_CHANGED_RENEW_TOKEN (12)：更新 Token 引起网络连接状态改变 。 CONNECTION_CHANGED_CLIENT_IP_ADDRESS_CHANGED (13)：客户端 IP 地址变更，可能是由于网络类型，或网络运营商的 IP 或端口发生改变引起 。 CONNECTION_CHANGED_KEEP_ALIVE_TIMEOUT (14)：SDK 和服务器连接保活超时，进入自动重连状态 。 CONNECTION_CHANGED_REJOIN_SUCCESS (15)：重新加入频道成功。 CONNECTION_CHANGED_LOST (16)：SDK 和服务器失去连接 。 CONNECTION_CHANGED_ECHO_TEST (17)：连接状态变化由回声测试引起。 CONNECTION_CHANGED_CLIENT_IP_ADDRESS_CHANGED_BY_USER (18)：本地 IP 地址被用户更改。 CONNECTION_CHANGED_SAME_UID_LOGIN (19)：使用相同的 UID 从不同的设备加入同一频道。 CONNECTION_CHANGED_TOO_MANY_BROADCASTERS (20)：频道内主播人数已达上限。

所属接口类

• IRtcEngineEventHandler

onEncryptionError

内置加密出错回调。

Java

public void onEncryptionError(int errorType) {}

调用 enableEncryption 开启加密后， 如果发流端、收流端出现加解密出错，SDK 会触发该回调。

参数

参数名	描述
errorType	错误类型。 ENCRYPTION_ERROR_INTERNAL_FAILURE (0): 内部原因。 ENCRYPTION_ERROR_DECRYPTION_FAILURE (1): 解密错误。请确保接收端和发送端使用的加密模式或密钥一致。 ENCRYPTION_ERROR_ENCRYPTION_FAILURE (2): 加密错误。

所属接口类

• IRtcEngineEventHandler

onLastmileProbeResult

通话前网络上下行 Last mile 质量探测报告回调。

Java

public void onLastmileProbeResult(LastmileProbeResult result) {}

在调用 startLastmileProbeTest 之后，SDK 会在约 30 秒内返回该回调。

参数

参数名	描述
result	上下行 Last mile 质量探测结果。 详见: LastmileProbeResult。

所属接口类

• IRtcEngineEventHandler

onLastmileQuality

网络上下行 last mile 质量报告回调。

Java

public void onLastmileQuality(int quality) {}

该回调描述本地用户在加入频道前的 last mile 网络探测的结果，其中 last mile 是指设备到声网边缘服务器的网络状态。

加入频道前，调用 startLastmileProbeTest 之后，SDK 触发该回调报告本地用户在加入频道前的 last mile 网络探测的结果。

参数

参数名	描述
quality	Last mile 网络质量。 QUALITY_UNKNOWN (0)：质量未知。 QUALITY_EXCELLENT (1)：质量极好。 QUALITY_GOOD (2)：用户主观感觉和极好差不多，但码率可能略低于极好。 QUALITY_POOR (3)：用户主观感受有瑕疵但不影响沟通。 QUALITY_BAD (4)：勉强能沟通但不顺畅。 QUALITY_VBAD (5)：网络质量非常差，基本不能沟通。 QUALITY_DOWN (6)：网络连接断开，完全无法沟通。

所属接口类

• IRtcEngineEventHandler

onNetworkQuality

通话中每个用户的网络上下行 last mile 质量报告回调。

Java

public void onNetworkQuality(int uid, int txQuality, int rxQuality) {}

该回调描述每个用户在通话中的 last mile 网络状态，其中 last mile 是指设备到声网边缘服务器的网络状态。

该回调每 2 秒触发一次。如果远端有多个用户，该回调每 2 秒会被触发多次。

注：用户不发流时，txQuality 为 UNKNOWN；用户不收流时，rxQuality 为 UNKNOWN。

参数

参数名	描述
uid	用户 ID。表示该回调报告的是持有该 ID 的用户的网络质量。如果当 uid 为 0 时，返回的是本地用户的网络质量。
txQuality	该用户的上行网络质量，基于发送码率、上行丢包率、平均往返时延和网络抖动计算。 该值代表当前的上行网络质量，帮助判断是否可以支持当前设置的视频编码属性。 假设上行码率是 1000 Kbps，那么支持直播场景下 640 × 480 的分辨率、15 fps 的帧率没有问题，但是支持 1280 × 720 的分辨率就会有困难。 QUALITY_UNKNOWN (0)：质量未知。 QUALITY_EXCELLENT (1)：质量极好。 QUALITY_GOOD (2)：用户主观感觉和极好差不多，但码率可能略低于极好。 QUALITY_POOR (3)：用户主观感受有瑕疵但不影响沟通。 QUALITY_BAD (4)：勉强能沟通但不顺畅。 QUALITY_VBAD (5)：网络质量非常差，基本不能沟通。 QUALITY_DOWN (6)：网络连接断开，完全无法沟通。
rxQuality	该用户的下行网络质量，基于下行网络的丢包率、平均往返延时和网络抖动计算。 QUALITY_UNKNOWN (0)：质量未知。 QUALITY_EXCELLENT (1)：质量极好。 QUALITY_GOOD (2)：用户主观感觉和极好差不多，但码率可能略低于极好。 QUALITY_POOR (3)：用户主观感受有瑕疵但不影响沟通。 QUALITY_BAD (4)：勉强能沟通但不顺畅。 QUALITY_VBAD (5)：网络质量非常差，基本不能沟通。 QUALITY_DOWN (6)：网络连接断开，完全无法沟通。

所属接口类

• IRtcEngineEventHandler

onNetworkTypeChanged

本地网络类型发生改变回调。

Java

public void onNetworkTypeChanged(int type) {}

本地网络连接类型发生改变时，SDK 会触发该回调，并在回调中明确当前的网络连接类型。你可以通过该回调获取正在使用的网络类型；当连接中断时，该回调能辨别引起中断的原因是网络切换还是网络条件不好。

参数

参数名	描述
type	网络连接类型： NETWORK_TYPE_UNKNOWN (-1)：网络连接类型未知。 NETWORK_TYPE_DISCONNECTED (0)：网络连接已断开。 NETWORK_TYPE_LAN (1)：网络类型为 LAN。 NETWORK_TYPE_WIFI (2)：网络类型为 Wi-Fi(包含热点）。 NETWORK_TYPE_MOBILE_2G (3)：网络类型为 2G 移动网络。 NETWORK_TYPE_MOBILE_3G (4)：网络类型为 3G 移动网络。 NETWORK_TYPE_MOBILE_4G (5)：网络类型为 4G 移动网络。 NETWORK_TYPE_MOBILE_5G (6)：网络类型为 5G 移动网络。

所属接口类

• IRtcEngineEventHandler

onPermissionError

获取设备权限出错回调。

Java

public void onPermissionError(int permission) {}

无法获取设备权限时，SDK 会触发该回调，报告哪个设备的权限无法获取。

参数

参数名	描述
permission	设备权限类型。 RECORD_AUDIO (0): 音频采集设备的权限。 CAMERA (1): 摄像头权限。 SCREEN_CAPTURE (2): 屏幕共享权限。

所属接口类

• IRtcEngineEventHandler

onProxyConnected

代理连接状态回调。

Java

public void onProxyConnected(
    String channel, int uid, int proxyType, String localProxyIp, int elapsed) {}

通过该回调你可以监听 SDK 连接代理的状态。例如，当用户调用 setCloudProxy 设置代理并成功加入频道后，SDK 会触发该回调报告用户 ID、连接的代理类型和从调用 joinChannel [2/2] 到触发该回调经过的时间等。

参数

参数名	描述
channel	频道名称。
uid	用户 ID
proxyType	连接上的代理类型。 PROXY_TYPE_NONE_PROXY (0): 预留参数，暂不支持。 PROXY_TYPE_UDP_CLOUD_PROXY (1): UDP 协议的云代理，即 Force UDP 云代理模式。在该模式下，SDK 始终通过 UDP 协议传输数据。 PROXY_TYPE_TCP_CLOUD_PROXY (2): TCP（加密）协议的云代理，即 Force TCP 云代理模式。在该模式下，SDK 始终通过 TLS 443 传输数据。 PROXY_TYPE_LOCAL_PROXY (3): 预留参数，暂不支持。 PROXY_TYPE_TCP_AUTO_FALLBACK (4): 自动模式。在该模式下，SDK 优先连接 SD-RTN™，如果连接失败，自动切换为 TLS 443。
localProxyIp	预留参数，暂不支持。
elapsed	从调用 joinChannel [2/2] 到 SDK 触发该回调的经过的时间（毫秒）。

所属接口类

• IRtcEngineEventHandler

onUplinkNetworkInfoUpdated

上行网络信息变化回调。

Java

public void onUplinkNetworkInfoUpdated(UplinkNetworkInfo info) {}

只有当上行网络信息发生变化时，SDK 才会触发该回调。

注意： 该回调仅适用于向 SDK 推送 H.264 格式的外部编码视频数据的场景。

参数

参数名	描述
info	上行网络信息，详见 UplinkNetworkInfo。

所属接口类

• IRtcEngineEventHandler