网络及其他

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

complain

投诉通话质量。

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

详情

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

参数

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

返回值

0: 方法调用成功。
< 0: 方法调用失败。详见错误码了解详情和解决建议。
- -1: 一般性的错误（未明确归类）。
- -2: 参数无效。
- -7: RtcEngine 尚未初始化就调用方法。

所属接口类

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

enableEncryptionEx

开启或关闭内置加密。

Java
public abstract int enableEncryptionEx(
      boolean enabled, EncryptionConfig config, RtcConnection connection);

自从

v4.3.1

用户离开频道后，SDK 会自动关闭加密。如需重新开启加密，你需要在用户再次加入频道前调用该方法。

适用场景

对安全要求较高的场景。

调用时机

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

调用限制

同一频道内的所有用户在调用该方法时，必须设置相同的加密模式和密钥。
如果开启了内置加密，则不能使用旁路推流功能。

参数

enabled

是否开启内置加密：

true: 开启内置加密。
false:（默认）关闭内置加密。

config

配置内置加密模式和密钥。详见 EncryptionConfig。

connection

Connection 信息。详见 RtcConnection。

返回值

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

所属接口类

RtcEngineEx

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，标识该客户端的此次通话。你可以调用该方法获取 callId 参数，然后在调用 rate、complain 等方法时填入。

调用时机

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

调用限制

无。

参数

callId: 输出参数，当前的通话 ID。

返回值

通话 ID。

所属接口类

RtcEngine

getCallIdEx

使用连接 ID 获取通话 ID。

Java
public abstract String getCallIdEx(RtcConnection connection);

自从

v4.3.1

调用时机

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

调用限制

无。

参数

connection: Connection 信息。详见 RtcConnection。

所属接口类

RtcEngineEx

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

isFeatureAvailableOnDevice

查询设备是否支持指定进阶功能。

Java
public abstract boolean isFeatureAvailableOnDevice(int type);

详情

自从

v4.2.3

查询当前设备能力是否满足虚拟背景、美颜等进阶功能的要求。

适用场景

在使用进阶音视频功能前，你可以根据查询结果判断当前设备是否支持这些功能，从而避免在低端设备上开启进阶功能导致性能下降或功能不可用的问题。你可以根据该方法的返回值，决定是否显示或启用相应的功能按钮，或者在设备能力不足时，为用户提示相应信息。

参数

type

进阶功能类型：

VIDEO_VIRTUAL_BACKGROUND (1)：虚拟背景功能。
VIDEO_BEAUTY_EFFECT (2)：美颜功能。

返回值

true: 设备支持指定进阶功能。
false: 设备不支持指定进阶功能。

所属接口类

RtcEngine

queryDeviceScore

查询设备评分等级。

Java
public abstract int queryDeviceScore();

详情

自从

v4.3.0

适用场景

在高清或超高清视频场景下，可以先调用该方法查询设备的等级评分。如果返回的评分较低（比如低于 60），则需要适当调低视频分辨率，以避免影响视频体验。不同业务场景要求的最低设备评分等级不同，具体评分推荐请联系技术支持。

返回值

>0: 方法调用成功，值为当前设备的评分等级，取值范围为[0,100]，数值越大表示设备能力越强。大部分设备的评分在 60 到 100 之间。
< 0: 方法调用失败。

所属接口类

RtcEngine

rate

给通话评分。

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

详情

注意

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

参数

callId: 通话 ID。你可以通过调用 getCallId 获取该参数。
rating: 给通话的评分，最低 1 分，最高 5 分。
description: （非必选项）给通话的描述。长度应小于 800 字节。

返回值

0: 方法调用成功。
< 0: 方法调用失败。详见错误码了解详情和解决建议。
- -1: 一般性的错误（未明确归类）。
- -2: 参数无效。

所属接口类

RtcEngine

sendCustomReportMessage

发送自定义上报消息。

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

详情

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

所属接口类

RtcEngine

sendCustomReportMessageEx

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

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

详情

所属接口类

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

setLocalAccessPoint

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

Java
public abstract int setLocalAccessPoint(LocalAccessPointConfiguration config);

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

调用时机

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

调用限制

该方法仅在部署声网混合云方案后生效。你可以联系销售了解和部署声网混合云。

参数

config: Local Access Point 配置。详见 LocalAccessPointConfiguration。

返回值

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

setLogFile

设置日志文件

Java
public abstract int setLogFile(String filePath);

废弃

该方法已废弃，请在调用 create [2/2] 时通过 config 参数设置日志文件路径。

设置 SDK 的输出 log 文件。SDK 运行时产生的所有 log 将写入该文件。

调用时机

该方法需要在 create [2/2] 后立即调用，否则输出日志可能不完整。

调用限制

App 必须保证指定的目录存在而且可写。

参数

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 日志文件的默认大小为 2,048 KB；API 调用日志文件的默认大小为 2,048 KB。日志文件均为 UTF-8 编码。
最新的日志永远写在 agorasdk.log 和 agoraapi.log 中。
当 agorasdk.log 写满后，SDK 会按照以下顺序对日志文件进行操作：
1. 删除 agorasdk.4.log 文件（如有）。
2. 将 agorasdk.3.log 重命名为 agorasdk.4.log。
3. 将 agorasdk.2.log 重命名为 agorasdk.3.log。
4. 将 agorasdk.1.log 重命名为 agorasdk.2.log。
5. 新建 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);

废弃

该方法已废弃，请在调用 create [2/2] 时通过 config 参数设置日志输出级别。

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

参数

level: 日志级别。详见 LogLevel。

返回值

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

所属接口类

RtcEngine

setParameters

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

Java
public abstract int setParameters(String parameters);

参数

parameters: JSON 字符串形式的参数。

返回值

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

所属接口类

RtcEngine

setRemoteSubscribeFallbackOption [1/2]

设置弱网环境下订阅的音视频流回退选项。

Java
public abstract int setRemoteSubscribeFallbackOption(int option);

详情

废弃

自 v4.4.0 起废弃，请改用 setRemoteSubscribeFallbackOption [2/2]。

网络不理想的环境下，实时通信音视频的质量会下降。你可以调用该方法并将 option 设置为 STREAM_FALLBACK_OPTION_VIDEO_STREAM_LOW 或 STREAM_FALLBACK_OPTION_AUDIO_ONLY，SDK 会在下行弱网且音视频质量严重受影响时，将视频流切换为小流或关闭视频流，从而保证音频质量。同时，SDK 会持续监控网络质量，并在网络质量改善时恢复订阅音视频流。

当订阅流回退为音频流或由音频流恢复为音视频流时，SDK 会触发 onRemoteSubscribeFallbackToAudioOnly 回调。

参数

option

订阅流的回退选项。

STREAM_FALLBACK_OPTION_DISABLED (0): 网络条件较差时，不对音视频流作回退处理，但不能保证音视频流的质量。
STREAM_FALLBACK_OPTION_VIDEO_STREAM_LOW (1):（默认）网络条件较差时，只接收视频小流（低分辨率、低码率视频流）。
STREAM_FALLBACK_OPTION_AUDIO_ONLY (2): 网络条件较差时，先尝试只接收视频小流；如果因网络环境太差无法显示视频，则再回退到只接收订阅的音频流。

返回值

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

所属接口类

RtcEngine

setRemoteSubscribeFallbackOption [2/2]

设置弱网环境下订阅的音视频流回退选项。

Java
public abstract int setRemoteSubscribeFallbackOption(Constants.StreamFallbackOptions option);

详情

自从

v4.4.0

当订阅流回退为音频流或由音频流恢复为音视频流时，SDK 会触发 onRemoteSubscribeFallbackToAudioOnly 回调。

参数

option: 订阅流的回退选项。详见 StreamFallbackOptions。

返回值

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

所属接口类

RtcEngine

startEchoTest

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

Java
public abstract int startEchoTest(EchoTestConfiguration config);

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

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

调用时机

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

调用限制

在频道内调用该方法时，需确保当前没有发布音视频流。
调用该方法后，必须调用 stopEchoTest 结束测试，否则该用户无法进行下一次音视频通话回路测试，也无法加入频道。
直播场景下，该方法仅能由主播调用。

参数

config: 音视频通话回路测试的配置。详见 EchoTestConfiguration。

返回值

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

所属接口类

RtcEngine

startLastmileProbeTest

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

Java
public abstract int startLastmileProbeTest(LastmileProbeConfig config);

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

调用时机

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

调用限制

无。

参数

config: Last mile 网络探测配置，详见 LastmileProbeConfig。

返回值

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

所属接口类

RtcEngine

stopEchoTest

停止语音通话回路测试。

Java
public abstract int stopEchoTest();

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

返回值

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)：加入频道失败。SDK 在尝试加入频道 20 分钟后仍未能加入频道，会返回该状态并不再尝试重连。请提示用户尝试切换网络后重新加入频道。
CONNECTION_CHANGED_LEAVE_CHANNEL (5)：离开频道。
CONNECTION_CHANGED_INVALID_APP_ID (6)：App ID 无效。请使用有效的 APP ID 重新加入频道，并确保你使用的 App ID 与在声网控制台生成的一致。
CONNECTION_CHANGED_INVALID_CHANNEL_NAME (7)：频道名无效。请更换有效的频道名重新加入频道。有效的频道名为长度在 64 字节以内的字符串。以下为支持的字符集范围（共 89 个字符）:
- 26 个小写英文字母 a~z
- 26 个大写英文字母 A~Z
- 10 个数字 0~9
- "!"、"#"、"$"、"%"、"&"、"("、")"、"+"、"-"、":"、";"、"<"、"="、"."、">"、"?"、"@"、"["、"]"、"^"、"_"、"{"、"}"、"|"、"~"、","
CONNECTION_CHANGED_INVALID_TOKEN (8)：Token 无效。一般有以下原因：
- 你的项目启用了 App Certificate，但加入频道未使用 Token。
- 在调用 joinChannel [2/2] 加入频道时指定的用户 ID 与生成 Token 时传入的用户 ID 不一致。
- 生成的 Token 和加入频道使用的 Token 不一致。
请确保：
- 当你的项目启用了 App Certificate 时，使用 Token 加入频道。
- 生成 Token 时指定的用户 ID 与加入频道时使用的用户 ID 一致，
- 生成的 Token 和加入频道使用的 Token 一致。
CONNECTION_CHANGED_TOKEN_EXPIRED (9)：当前使用的 Token 已过期。请重新在你的服务端生成 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 地址变更。如多次收到该状态码，请提示用户更换网络后尝试重新加入频道。
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): 媒体流加密错误。
ENCRYPTION_ERROR_DATASTREAM_DECRYPTION_FAILURE (3): 数据流解密错误。请确保接收端和发送端使用的加密模式或密钥一致。
ENCRYPTION_ERROR_DATASTREAM_ENCRYPTION_FAILURE (4): 数据流加密错误。

所属接口类

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)：网络连接断开，完全无法沟通。
QUALITY_DETECTING (8)：网络质量检测进行中。

所属接口类

IRtcEngineEventHandler

onNetworkQuality

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

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

详情

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

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

该回调通过频道内的广播包反馈网络质量。过多的广播包可能引发广播风暴。为防止广播风暴导致频道内大量数据传输，该回调默认支持同时反馈最多 4 个远端主播的网络质量。

信息

用户不发流时，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)：网络连接断开，完全无法沟通。
QUALITY_DETECTING (8)：网络质量检测进行中。

rxQuality

该用户的下行网络质量，基于下行网络的丢包率、平均往返延时和网络抖动计算。

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

所属接口类

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

onRemoteSubscribeFallbackToAudioOnly

订阅流已回退为音频流或恢复为音视频流回调。

Java
public void onRemoteSubscribeFallbackToAudioOnly(int uid, boolean isFallbackOrRecover) {}

详情

当你调用了 setRemoteSubscribeFallbackOption [1/2] 并将 option 设置为 STREAM_FALLBACK_OPTION_AUDIO_ONLY 后，该回调会在下列情况时被触发：

下行网络环境较差，订阅的音视频流回退为音频流
下行网络环境改善，订阅音频流恢复为音视频流

注意

订阅流因弱网环境而回退为视频小流时，你可以通过 onRemoteVideoStats 回调来监控远端视频大小流的切换。

参数

uid

远端用户的用户 ID。

isFallbackOrRecover

true: 由于网络环境不理想，订阅流已回退为音频流。
false: 由于网络环境改善，订阅流已恢复为音视频流。

所属接口类

IRtcEngineEventHandler

onUplinkNetworkInfoUpdated

上行网络信息变化回调。

Java
public void onUplinkNetworkInfoUpdated(UplinkNetworkInfo info) {}

详情

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

注意

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

参数

info: 上行网络信息，详见 UplinkNetworkInfo。

所属接口类

IRtcEngineEventHandler

complain

详情​

参数​

返回值​

enableEncryption

适用场景

调用时机

调用限制

参数​

返回值​

enableEncryptionEx

适用场景

调用时机

调用限制

参数​

返回值​

enableWebSdkInteroperability

详情​

参数​

返回值​

getCallId

调用时机

调用限制

参数​

返回值​

getCallIdEx

调用时机

调用限制

参数​

getConnectionState

调用时机

调用限制

返回值​

getConnectionStateEx

调用时机

调用限制

参数​

返回值​

getCurrentMonotonicTimeInMs

调用时机

调用限制

返回值​

getErrorDescription

参数​

返回值​

getNativeHandle

详情​

返回值​

getNetworkType

详情​

返回值​

getNtpWallTimeInMs

详情​

返回值​

getSdkVersion

返回值​

isFeatureAvailableOnDevice

详情​

适用场景

参数​

返回值​

queryDeviceScore

详情​

适用场景

返回值​

rate

详情​

参数​

返回值​

sendCustomReportMessage

详情​

sendCustomReportMessageEx

详情​

setAVSyncSource

详情​

参数​

返回值​

setCloudProxy

详情​

参数​

详情

参数

返回值

参数

返回值

参数

返回值

详情

参数

返回值

参数

返回值

参数

返回值

参数

返回值

返回值

参数

返回值

详情

返回值

详情

返回值

详情

返回值

返回值

详情

参数

返回值

详情

返回值

详情

参数

返回值

详情

详情

详情

参数

返回值

详情

参数

返回值

参数

返回值

参数

返回值

详情

参数

返回值

详情

参数

返回值

参数

返回值

参数

返回值

详情

参数

返回值

详情

参数

返回值

参数

返回值

参数

返回值

返回值

返回值

详情

详情

详情

详情

参数

详情

参数

详情

参数

详情

参数

详情