需要访问旧版文档站？前往旧版文档官网首页。 (在新标签页打开)
声网文档中心

网络及其他

  • Unreal Blueprint

更新时间不可用

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

Complain

投诉通话质量。

C++
UFUNCTION(BlueprintCallable, Category = "Agora|IRtcEngine")
	int Complain(const FString& callId, const FString& description);

详情

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

参数

参数名描述
callId

通话 ID。你可以通过调用 GetCallId 获取该参数。

description

（非必选项）通话的描述。长度应小于 800 字节。

表格内容超出当前宽度，可横向滚动查看更多列。

返回值

  • 0: 方法调用成功。

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

    • -1: 一般性的错误（未明确归类）。
    • -2: 参数无效。
    • -7: IRtcEngine 尚未初始化就调用方法。

所属接口类

EnableEncryption

开启或关闭内置加密。

C++
UFUNCTION(BlueprintCallable, Category = "Agora|IRtcEngine")
	int EnableEncryption(bool enabled, const FEncryptionConfig& config);

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

适用场景

对安全要求较高的场景。

调用时机

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

调用限制

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

参数

参数名描述
enabled

是否开启内置加密：

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

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

表格内容超出当前宽度，可横向滚动查看更多列。

返回值

  • 0: 方法调用成功。

  • < 0: 方法调用失败

    • -2: 调用了无效的参数。需重新指定参数。
    • -4: 设置的加密模式不正确或加载外部加密库失败。需检查枚举值是否正确或重新加载外部加密库。
    • -7: SDK 尚未初始化。需在调用 API 之前已创建 IRtcEngine 对象并完成初始化。

所属接口类

EnableEncryptionEx

开启或关闭内置加密。

C++
UFUNCTION(BlueprintCallable, Category = "Agora|IRtcEngine")
	int EnableEncryptionEx(const FRtcConnection& connection, bool enabled, const FEncryptionConfig& config);

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

适用场景

对安全要求较高的场景。

调用时机

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

调用限制

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

参数

参数名描述
enabled

是否开启内置加密：

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

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

connection

Connection 信息。详见 FUABT_RtcConnection。

表格内容超出当前宽度，可横向滚动查看更多列。

返回值

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

所属接口类

EnableWebSdkInteroperability

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

C++
UFUNCTION(BlueprintCallable, Category = "Agora|IRtcEngine")
	int EnableWebSdkInteroperability(bool enabled);

详情

弃用:

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

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

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

参数

参数名描述
enabled

是否打开与 Web SDK 的互通：

  • true: 打开互通。
  • false: (默认) 关闭互通。
表格内容超出当前宽度，可横向滚动查看更多列。

返回值

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

所属接口类

GetCallId

获取通话 ID。

C++
UFUNCTION(BlueprintCallable, Category = "Agora|IRtcEngine")
	int GetCallId(FString& callId);

客户端在每次加入频道后会生成一个对应的 callId，标识该客户端的此次通话。你可以调用该方法获取 callId 参数，然后在调用 Rate、Complain 等方法时填入。

调用时机

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

调用限制

无。

参数

参数名描述
callId

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

表格内容超出当前宽度，可横向滚动查看更多列。

返回值

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

所属接口类

GetCallIdEx

使用连接 ID 获取通话 ID。

C++
UFUNCTION(BlueprintCallable, Category = "Agora|IRtcEngine")
	int GetCallIdEx( FString & callId, const FRtcConnection& connection);

客户端在每次加入频道后会生成一个对应的 callId，标识该客户端的此次通话。你可以调用该方法获取 callId 参数，然后在调用 Rate、Complain 等方法时填入。

调用时机

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

调用限制

无。

参数

参数名描述
callId

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

connection

Connection 信息。详见 FUABT_RtcConnection。

表格内容超出当前宽度，可横向滚动查看更多列。

返回值

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

所属接口类

GetConnectionState

获取当前网络连接状态。

C++
UFUNCTION(BlueprintCallable, Category = "Agora|IRtcEngine")
	ECONNECTION_STATE_TYPE GetConnectionState();

调用时机

加入频道前后均可调用。

调用限制

无。

返回值

当前网络连接状态。详见 ECONNECTION_STATE_TYPE。

所属接口类

GetConnectionStateEx

获取当前网络连接状态。

C++
UFUNCTION(BlueprintCallable, Category = "Agora|IRtcEngine")
	ECONNECTION_STATE_TYPE GetConnectionStateEx(const FRtcConnection& connection);

调用时机

加入频道前后均可调用。

调用限制

无。

参数

参数名描述
connection

Connection 信息。详见 FUABT_RtcConnection。

表格内容超出当前宽度，可横向滚动查看更多列。

返回值

当前网络连接状态。详见 ECONNECTION_STATE_TYPE。

所属接口类

GetErrorDescription

获取警告或错误描述。

C++
UFUNCTION(BlueprintCallable, Category = "Agora|IRtcEngine")
	FString GetErrorDescription(int code);

参数

参数名描述
code

SDK 报告的错误码。

表格内容超出当前宽度，可横向滚动查看更多列。

返回值

具体的错误描述。

所属接口类

GetNetworkType

获取本地网络连接类型。

C++
UFUNCTION(BlueprintCallable, Category = "Agora|IRtcEngine")
	int GetNetworkType();

详情

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

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

返回值

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

    • 0：网络连接已断开。
    • 1：网络类型为 LAN。
    • 2：网络类型为 Wi-Fi（包含热点）。
    • 3：网络类型为 2G 移动网络。
    • 4：网络类型为 3G 移动网络。
    • 5：网络类型为 4G 移动网络。
    • 6：网络类型为 5G 移动网络。

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

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

所属接口类

GetNtpWallTimeInMs

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

C++
UFUNCTION(BlueprintCallable, Category = "Agora|IRtcEngine")
	FString GetNtpWallTimeInMs();

详情

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

返回值

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

所属接口类

GetVersion

获取 SDK 版本。

C++
UFUNCTION(BlueprintCallable, Category = "Agora|IRtcEngine")
	FString GetVersion();

参数

参数名描述
build

编译号。

表格内容超出当前宽度，可横向滚动查看更多列。

返回值

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

所属接口类

IsFeatureAvailableOnDevice

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

C++
UFUNCTION(BlueprintCallable, Category = "Agora|IRtcEngine")
	bool IsFeatureAvailableOnDevice(EFeatureType type);

详情

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

适用场景

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

参数

参数名描述
type

进阶功能类型，详见 EFeatureType。

表格内容超出当前宽度，可横向滚动查看更多列。

返回值

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

所属接口类

OnRemoteSubscribeFallbackToAudioOnly

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

C++
UFUNCTION(BlueprintNativeEvent, Category = "Agora|Event")
	void OnRemoteSubscribeFallbackToAudioOnly(int64 uid, bool isFallbackOrRecover);

详情

当你调用了 SetRemoteSubscribeFallbackOption 并将 option 设置为 STREAM_FALLBACK_OPTION_AUDIO_ONLY 后，该回调会在下列情况时被触发：

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

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

参数

参数名描述
uid

远端用户的用户 ID。

isFallbackOrRecover
  • true: 由于网络环境不理想，订阅流已回退为音频流。
  • false: 由于网络环境改善，订阅流已恢复为音视频流。
表格内容超出当前宽度，可横向滚动查看更多列。

所属接口类

QueryDeviceScore

查询设备评分等级。

C++
UFUNCTION(BlueprintCallable, Category = "Agora|IRtcEngine")
	int QueryDeviceScore();

详情

适用场景

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

返回值

  • < 0: 方法调用失败。

所属接口类

Rate

给通话评分。

C++
UFUNCTION(BlueprintCallable, Category = "Agora|IRtcEngine")
	int Rate(const FString& callId, int rating, const FString& description);

详情

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

参数

参数名描述
callId

通话 ID。你可以通过调用 GetCallId 获取该参数。

rating

给通话的评分，最低 1 分，最高 5 分。

description

（非必选项）给通话的描述。长度应小于 800 字节。

表格内容超出当前宽度，可横向滚动查看更多列。

返回值

  • 0: 方法调用成功。

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

    • -1: 一般性的错误（未明确归类）。
    • -2: 参数无效。

所属接口类

SendCustomReportMessage

发送自定义上报消息。

C++
UFUNCTION(BlueprintCallable, Category = "Agora|IRtcEngine")
	int SendCustomReportMessage(const FString& id, const FString& category, const FString& event, const FString& label, int value);

详情

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

所属接口类

SendCustomReportMessageEx

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

C++
UFUNCTION(BlueprintCallable, Category = "Agora|IRtcEngine")
	int SendCustomReportMessageEx(const FString& id, const FString& category, const FString& event, const FString& label, int value, const FRtcConnection& connection);

详情

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

所属接口类

SetAVSyncSource

设置发流端音画同步。

C++
UFUNCTION(BlueprintCallable, Category = "Agora|IRtcEngine")
	int SetAVSyncSource(const FString& channelId, int64 uid);

详情

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

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

参数

参数名描述
channelId

标识音频发送端所在频道的频道名。

uid

音频发送端的用户 ID。

表格内容超出当前宽度，可横向滚动查看更多列。

返回值

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

所属接口类

SetCloudProxy

设置云代理服务。

C++
UFUNCTION(BlueprintCallable, Category = "Agora|IRtcEngine")
	int SetCloudProxy(ECLOUD_PROXY_TYPE proxyType);

详情

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

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

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

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

注意：

  • 建议你在频道外调用该方法。
  • 如果用户处于内网防火墙环境下，使用 Force UDP 云代理时，旁路推流和跨频道媒体流转发功能不可用。
  • 使用 Force UDP 云代理时，调用 StartAudioMixing 方法时无法播放 HTTP 协议的在线音频文件。旁路推流和跨频道媒体流转发功能会使用 TCP 协议的云代理。

参数

参数名描述
proxyType

云代理类型，详见 ECLOUD_PROXY_TYPE。

该参数为必填参数，如果你不赋值，SDK 会报错。

表格内容超出当前宽度，可横向滚动查看更多列。

返回值

  • 0: 方法调用成功。

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

    • -2: 传入的参数无效。
    • -7: SDK 尚未初始化。

所属接口类

SetLocalAccessPoint

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

C++
UFUNCTION(BlueprintCallable, Category = "Agora|IRtcEngine")
	int SetLocalAccessPoint(const FLocalAccessPointConfiguration& config);

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

调用时机

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

调用限制

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

参数

参数名描述
config

Local Access Point 配置。详见 FLocalAccessPointConfiguration。

表格内容超出当前宽度，可横向滚动查看更多列。

返回值

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

SetLogFile

设置日志文件

C++
UFUNCTION(BlueprintCallable, Category = "Agora|IRtcEngine")
	int SetLogFile(const FString& filePath);

弃用：

该方法已废弃，请在调用 Initialize 时通过 context 参数设置日志文件路径。

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

调用时机

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

调用限制

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

参数

参数名描述
filePath

日志文件的完整路径。该日志文件为 UTF-8 编码。

表格内容超出当前宽度，可横向滚动查看更多列。

返回值

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

所属接口类

SetLogFileSize

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

C++
UFUNCTION(BlueprintCallable, Category = "Agora|IRtcEngine")
	int SetLogFileSize(int fileSizeInKBytes);

详情

弃用：

该方法已废弃，请改用 Initialize 中的 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: 方法调用失败。详见错误码了解详情和解决建议。

所属接口类

SetLogFilter

设置日志输出等级。

C++
UFUNCTION(BlueprintCallable, Category = "Agora|IRtcEngine")
	int SetLogFilter(int filter);

详情

弃用：

请改用 Initialize 中的 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: 方法调用失败。详见错误码了解详情和解决建议。

所属接口类

SetLogLevel

设置 SDK 的日志输出级别。

C++
UFUNCTION(BlueprintCallable, Category = "Agora|IRtcEngine")
	int SetLogLevel(ELOG_LEVEL level);

弃用：

该方法已废弃，请在调用 Initialize 时通过 context 参数设置日志输出级别。

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

参数

参数名描述
level

日志级别。详见 ELOG_LEVEL。

表格内容超出当前宽度，可横向滚动查看更多列。

返回值

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

所属接口类

SetParameters

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

C++
UFUNCTION(BlueprintCallable, Category = "Agora|IRtcEngine")
	int SetParameters(const FString& parameters);

详情

请联系技术支持获取 JSON 配置方式。

参数

参数名描述
parameters

JSON 字符串形式的参数。

表格内容超出当前宽度，可横向滚动查看更多列。

返回值

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

所属接口类

SetRemoteSubscribeFallbackOption

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

C++
UFUNCTION(BlueprintCallable, Category = "Agora|IRtcEngine")
	int SetRemoteSubscribeFallbackOption(ESTREAM_FALLBACK_OPTIONS option);

详情

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

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

参数

参数名描述
option

订阅流的回退选项。详见 ESTREAM_FALLBACK_OPTIONS。

表格内容超出当前宽度，可横向滚动查看更多列。

返回值

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

所属接口类

StartEchoTest

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

C++
UFUNCTION(BlueprintCallable, Category = "Agora|IRtcEngine")
	int StartEchoTest(const FEchoTestConfiguration& config);

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

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

调用时机

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

调用限制

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

参数

参数名描述
config

音视频通话回路测试的配置。详见 FEchoTestConfiguration。

表格内容超出当前宽度，可横向滚动查看更多列。

返回值

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

所属接口类

StartLastmileProbeTest

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

C++
UFUNCTION(BlueprintCallable, Category = "Agora|IRtcEngine")
	int StartLastmileProbeTest(const FLastmileProbeConfig& config);

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

调用时机

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

调用限制

无。

相关回调

成功调用该方法后，SDK 会依次触发如下 2 个回调：

  • OnLastmileQuality，视网络情况约 2 秒内返回。该回调通过打分反馈上下行网络质量，更贴近用户的主观感受。
  • OnLastmileProbeResult，视网络情况约 30 秒内返回。该回调通过具体数据反馈上下行网络质量，更加客观。

参数

参数名描述
config

Last mile 网络探测配置，详见 FLastmileProbeConfig。

表格内容超出当前宽度，可横向滚动查看更多列。

返回值

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

所属接口类

StopEchoTest

停止语音通话回路测试。

C++
UFUNCTION(BlueprintCallable, Category = "Agora|IRtcEngine")
	int StopEchoTest();

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

返回值

  • 0: 方法调用成功。

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

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

所属接口类

StopLastmileProbeTest

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

C++
UFUNCTION(BlueprintCallable, Category = "Agora|IRtcEngine")
	int StopLastmileProbeTest();

返回值

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

所属接口类

OnConnectionBanned

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

C++
UFUNCTION(BlueprintNativeEvent, Category = "Agora|Event")
	void OnConnectionBanned();

详情

弃用:

请改用 OnConnectionStateChanged。

所属接口类

OnConnectionInterrupted

网络连接中断回调。

C++
UFUNCTION(BlueprintNativeEvent, Category = "Agora|Event")
	void OnConnectionInterrupted();

详情

弃用:

请改用 OnConnectionStateChanged 回调。

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

  • OnConnectionInterrupted 回调一定是发生在成功加入频道后，且 SDK 刚失去和服务器连接超过 4 秒时触发。
  • OnConnectionLost 回调是无论是否成功加入频道，只要 10 秒内和服务器无法建立连接都会触发。

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

所属接口类

OnConnectionLost

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

C++
UFUNCTION(BlueprintNativeEvent, Category = "Agora|Event")
	void OnConnectionLost();

详情

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

所属接口类

OnConnectionStateChanged

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

C++
UFUNCTION(BlueprintNativeEvent, Category = "Agora|Event")
	void OnConnectionStateChanged(ECONNECTION_STATE_TYPE state, ECONNECTION_CHANGED_REASON_TYPE reason);

详情

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

参数

参数名描述
state

当前网络连接状态。详见 ECONNECTION_STATE_TYPE。

reason

引起当前网络连接状态改变的原因。详见 ECONNECTION_CHANGED_REASON_TYPE。

表格内容超出当前宽度，可横向滚动查看更多列。

所属接口类

OnEncryptionError

内置加密出错回调。

C++
UFUNCTION(BlueprintNativeEvent, Category = "Agora|Event")
	void OnEncryptionError(EENCRYPTION_ERROR_TYPE errorType);

详情

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

参数

参数名描述
errorType

错误类型，详见 EENCRYPTION_ERROR_TYPE。

表格内容超出当前宽度，可横向滚动查看更多列。

所属接口类

OnLastmileProbeResult

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

C++
UFUNCTION(BlueprintNativeEvent, Category = "Agora|Event")
	void OnLastmileProbeResult(const FLastmileProbeResult& result);

详情

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

参数

参数名描述
result

上下行 Last mile 质量探测结果。详见 FLastmileProbeResult。

表格内容超出当前宽度，可横向滚动查看更多列。

所属接口类

OnLastmileQuality

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

C++
UFUNCTION(BlueprintNativeEvent, Category = "Agora|Event")
	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)：网络质量检测进行中。
表格内容超出当前宽度，可横向滚动查看更多列。

所属接口类

OnNetworkQuality

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

C++
UFUNCTION(BlueprintNativeEvent, Category = "Agora|Event")
	void OnNetworkQuality(int64 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)：网络质量检测进行中。
表格内容超出当前宽度，可横向滚动查看更多列。

所属接口类

OnNetworkTypeChanged

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

C++
UFUNCTION(BlueprintNativeEvent, Category = "Agora|Event")
	void OnNetworkTypeChanged(FENUMWRAP_NETWORK_TYPE type);

详情

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

参数

参数名描述
type

本地网络连接类型。详见 FENUMWRAP_NETWORK_TYPE。

表格内容超出当前宽度，可横向滚动查看更多列。

所属接口类

OnPermissionError

获取设备权限出错回调。

C++
UFUNCTION(BlueprintNativeEvent, Category = "Agora|Event")
	void OnPermissionError(EPERMISSION_TYPE permissionType);

详情

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

参数

参数名描述
permissionType

设备权限类型。详见 EPERMISSION_TYPE。

表格内容超出当前宽度，可横向滚动查看更多列。

所属接口类

OnProxyConnected

代理连接状态回调。

C++
UFUNCTION(BlueprintNativeEvent, Category = "Agora|Event")
	void OnProxyConnected(const FString& channel, int64 uid, EPROXY_TYPE proxyType, const FString& localProxyIp, int elapsed);

详情

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

参数

参数名描述
channel

频道名称。

uid

用户 ID

proxyType

连接上的代理类型。详见 EPROXY_TYPE。

localProxyIp

预留参数，暂不支持。

elapsed

从调用 JoinChannelWithOptions 到 SDK 触发该回调的经过的时间（毫秒）。

表格内容超出当前宽度，可横向滚动查看更多列。

所属接口类

OnUplinkNetworkInfoUpdated

上行网络信息变化回调。

C++
UFUNCTION(BlueprintNativeEvent, Category = "Agora|Event")
	void OnUplinkNetworkInfoUpdated(const FUplinkNetworkInfo& info);

详情

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

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

参数

参数名描述
info

上行网络信息，详见 FUplinkNetworkInfo。

表格内容超出当前宽度，可横向滚动查看更多列。

所属接口类

咨询电话

400 632 6626

上海声网科技有限公司

Copyright © 2026 声网保留所有权利