# 网络及其他 (/zh-CN/api-reference/rtc/flutter/network)

> For AI agents: see the complete documentation index at [llms.txt](/llms.txt).

<a id="toc_network"></a>

<a id="api_irtcengine_complain"></a>

<a id="ariaid-title2"></a>

## complain [#complain]

投诉通话质量。

<a id="api_irtcengine_complain__prototype"></a>

```dart
Future<void> complain({required String callId, required String description});
```

<a id="api_irtcengine_complain__detailed_desc"></a>

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

<a id="api_irtcengine_complain__parameters"></a>

### 参数 [#参数]

<ParameterList>
<a id="callid"></a>
<Parameter name="callId">

通话 ID。你可以通过调用 [getCallId](/zh-CN/api-reference/rtc/flutter/network#api_irtcengine_getcallid) 获取该参数。

</Parameter>
<a id="description"></a>
<Parameter name="description">

通话的描述。长度应小于 800 字节。

</Parameter>
</ParameterList>

<a id="api_irtcengine_complain__return_values"></a>

### 返回值 [#返回值]

方法成功调用时，无返回值；方法调用失败时，会抛出 [AgoraRtcException](/zh-CN/api-reference/rtc/flutter/class-agorartcexception) 异常，你需要捕获异常并进行处理。详见[错误码](/zh-CN/api-reference/rtc/error-code)了解详情和解决建议。

### 所属接口类 [#所属接口类]

- [RtcEngine](/zh-CN/api-reference/rtc/flutter/rtc-interface-class#class_irtcengine)

<a id="api_irtcengine_enableencryption"></a>

<a id="ariaid-title3"></a>

## enableEncryption [#enableencryption]

开启或关闭内置加密。

<a id="api_irtcengine_enableencryption__prototype"></a>

```dart
Future<void> enableEncryption(
    {required bool enabled, required EncryptionConfig config});
```

<a id="api_irtcengine_enableencryption__detailed_desc"></a>

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

:::note
注：

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

<a id="api_irtcengine_enableencryption__scenario"></a>

### 适用场景 [#适用场景]

对安全要求较高的场景。

<a id="api_irtcengine_enableencryption__timing"></a>

### 调用时机 [#调用时机]

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

<a id="api_irtcengine_enableencryption__parameters"></a>

### 参数 [#参数-1]

<ParameterList>
<a id="enabled"></a>
<Parameter name="enabled">

是否开启内置加密：

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

</Parameter>
<a id="config"></a>
<Parameter name="config">

配置内置加密模式和密钥。详见 [EncryptionConfig](/zh-CN/api-reference/rtc/flutter/class-encryptionconfig)。

</Parameter>
</ParameterList>

<a id="api_irtcengine_enableencryption__return_values"></a>

### 返回值 [#返回值-1]

方法成功调用时，无返回值；方法调用失败时，会抛出 [AgoraRtcException](/zh-CN/api-reference/rtc/flutter/class-agorartcexception) 异常，你需要捕获异常并进行处理。详见[错误码](/zh-CN/api-reference/rtc/error-code)了解详情和解决建议。

### 所属接口类 [#所属接口类-1]

- [RtcEngine](/zh-CN/api-reference/rtc/flutter/rtc-interface-class#class_irtcengine)

<a id="api_irtcengineex_enableencryptionex"></a>

<a id="ariaid-title4"></a>

## enableEncryptionEx [#enableencryptionex]

开启或关闭内置加密。

<a id="api_irtcengineex_enableencryptionex__prototype"></a>

```dart
Future<void> enableEncryptionEx(
    {required RtcConnection connection,
    required bool enabled,
    required EncryptionConfig config});
```

<a id="api_irtcengineex_enableencryptionex__detailed_desc"></a>

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

:::note
注：

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

<a id="api_irtcengineex_enableencryptionex__scenario"></a>

### 适用场景 [#适用场景-1]

对安全要求较高的场景。

<a id="api_irtcengineex_enableencryptionex__timing"></a>

### 调用时机 [#调用时机-1]

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

<a id="api_irtcengineex_enableencryptionex__parameters"></a>

### 参数 [#参数-2]

<ParameterList>
<a id="enabled-1"></a>
<Parameter name="enabled">

是否开启内置加密：

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

</Parameter>
<a id="config-1"></a>
<Parameter name="config">

配置内置加密模式和密钥。详见 [EncryptionConfig](/zh-CN/api-reference/rtc/flutter/class-encryptionconfig)。

</Parameter>
<a id="connection"></a>
<Parameter name="connection">

Connection 信息。详见 [RtcConnection](/zh-CN/api-reference/rtc/flutter/class-rtcconnection)。

</Parameter>
</ParameterList>

<a id="api_irtcengineex_enableencryptionex__return_values"></a>

### 返回值 [#返回值-2]

方法成功调用时，无返回值；方法调用失败时，会抛出 [AgoraRtcException](/zh-CN/api-reference/rtc/flutter/class-agorartcexception) 异常，你需要捕获异常并进行处理。

### 所属接口类 [#所属接口类-2]

- [RtcEngineEx](/zh-CN/api-reference/rtc/flutter/rtc-interface-class#class_irtcengineex)

<a id="api_irtcengine_enablewebsdkinteroperability"></a>

<a id="ariaid-title5"></a>

## enableWebSdkInteroperability [#enablewebsdkinteroperability]

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

<a id="api_irtcengine_enablewebsdkinteroperability__prototype"></a>

```dart
Future<void> enableWebSdkInteroperability(bool enabled);
```

<a id="api_irtcengine_enablewebsdkinteroperability__detailed_desc"></a>

<a id="废弃"></a>

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

该方法打开或关闭与 Web SDK 的互通。如果有用户通过 Web SDK 加入频道，请确保调用该方法，否则 Web 端用户看 Native 端的画面会是黑屏。
该方法仅在直播场景下适用，通信场景下默认互通是打开的。

<a id="api_irtcengine_enablewebsdkinteroperability__parameters"></a>

### 参数 [#参数-3]

<ParameterList>
<a id="enabled-2"></a>
<Parameter name="enabled">

是否打开与 Web SDK 的互通：

- true: 打开互通。
- false: (默认) 关闭互通。

</Parameter>
</ParameterList>

<a id="api_irtcengine_enablewebsdkinteroperability__return_values"></a>

### 返回值 [#返回值-3]

方法成功调用时，无返回值；方法调用失败时，会抛出 [AgoraRtcException](/zh-CN/api-reference/rtc/flutter/class-agorartcexception) 异常，你需要捕获异常并进行处理。详见[错误码](/zh-CN/api-reference/rtc/error-code)了解详情和解决建议。

### 所属接口类 [#所属接口类-3]

- [RtcEngine](/zh-CN/api-reference/rtc/flutter/rtc-interface-class#class_irtcengine)

<a id="api_rtcengineext_getassetabsolutepath"></a>

<a id="ariaid-title6"></a>

## getAssetAbsolutePath [#getassetabsolutepath]

通过 Asset 的相对规路径获取该 Asset 的实际绝对路径。

<a id="api_rtcengineext_getassetabsolutepath__prototype"></a>

```dart
Future<String?> getAssetAbsolutePath(String assetPath)
```

<a id="api_rtcengineext_getassetabsolutepath__detailed_desc"></a>

<a id="api_rtcengineext_getassetabsolutepath__parameters"></a>

### 参数 [#参数-4]

<ParameterList>
<a id="assetpath"></a>
<Parameter name="assetPath">

pubspec.yaml 文件中配置的 `flutter -> assets` 字段。

</Parameter>
</ParameterList>

<a id="api_rtcengineext_getassetabsolutepath__return_values"></a>

### 返回值 [#返回值-4]

Asset 的实际路径。

### 所属接口类 [#所属接口类-4]

- [RtcEngineExt](/zh-CN/api-reference/rtc/flutter/rtc-interface-class#class_rtcengineext)

<a id="api_irtcengine_getcallid"></a>

<a id="ariaid-title7"></a>

## getCallId [#getcallid]

获取通话 ID。

<a id="api_irtcengine_getcallid__prototype"></a>

```dart
Future<String> getCallId();
```

<a id="api_irtcengine_getcallid__detailed_desc"></a>

客户端在每次加入频道后会生成一个对应的 `callId`，标识该客户端的此次通话。你可以调用该方法获取 `callId` 参数，然后在调用 [rate](/zh-CN/api-reference/rtc/flutter/network#api_irtcengine_rate)、[complain](/zh-CN/api-reference/rtc/flutter/network#api_irtcengine_complain) 等方法时填入。

<a id="api_irtcengine_getcallid__timing"></a>

### 调用时机 [#调用时机-2]

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

<a id="api_irtcengine_getcallid__return_values"></a>

### 返回值 [#返回值-5]

通话 ID。

### 所属接口类 [#所属接口类-5]

- [RtcEngine](/zh-CN/api-reference/rtc/flutter/rtc-interface-class#class_irtcengine)

<a id="api_irtcengineex_getcallidex"></a>

<a id="ariaid-title8"></a>

## getCallIdEx [#getcallidex]

使用连接 ID 获取通话 ID。

<a id="api_irtcengineex_getcallidex__prototype"></a>

```dart
Future<String> getCallIdEx(RtcConnection connection);
```

<a id="api_irtcengineex_getcallidex__detailed_desc"></a>

客户端在每次加入频道后会生成一个对应的 `callId`，标识该客户端的此次通话。你可以调用该方法获取 `callId` 参数，然后在调用 [rate](/zh-CN/api-reference/rtc/flutter/network#api_irtcengine_rate)、[complain](/zh-CN/api-reference/rtc/flutter/network#api_irtcengine_complain) 等方法时填入。

<a id="api_irtcengineex_getcallidex__timing"></a>

### 调用时机 [#调用时机-3]

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

<a id="api_irtcengineex_getcallidex__parameters"></a>

### 参数 [#参数-5]

<ParameterList>
<a id="connection-1"></a>
<Parameter name="connection">

Connection 信息。详见 [RtcConnection](/zh-CN/api-reference/rtc/flutter/class-rtcconnection)。

</Parameter>
</ParameterList>

### 所属接口类 [#所属接口类-6]

- [RtcEngineEx](/zh-CN/api-reference/rtc/flutter/rtc-interface-class#class_irtcengineex)

<a id="api_irtcengine_getconnectionstate"></a>

<a id="ariaid-title9"></a>

## getConnectionState [#getconnectionstate]

获取当前网络连接状态。

<a id="api_irtcengine_getconnectionstate__prototype"></a>

```dart
Future<ConnectionStateType> getConnectionState();
```

<a id="api_irtcengine_getconnectionstate__detailed_desc"></a>

<a id="api_irtcengine_getconnectionstate__timing"></a>

### 调用时机 [#调用时机-4]

加入频道前后均可调用。

<a id="api_irtcengine_getconnectionstate__return_values"></a>

### 返回值 [#返回值-6]

当前网络连接状态。详见 [ConnectionStateType](/zh-CN/api-reference/rtc/flutter/enum-connectionstatetype)。

### 所属接口类 [#所属接口类-7]

- [RtcEngine](/zh-CN/api-reference/rtc/flutter/rtc-interface-class#class_irtcengine)

<a id="api_irtcengineex_getconnectionstateex"></a>

<a id="ariaid-title10"></a>

## getConnectionStateEx [#getconnectionstateex]

获取当前网络连接状态。

<a id="api_irtcengineex_getconnectionstateex__prototype"></a>

```dart
Future<ConnectionStateType> getConnectionStateEx(RtcConnection connection);
```

<a id="api_irtcengineex_getconnectionstateex__detailed_desc"></a>

<a id="api_irtcengineex_getconnectionstateex__timing"></a>

### 调用时机 [#调用时机-5]

加入频道前后均可调用。

<a id="api_irtcengineex_getconnectionstateex__parameters"></a>

### 参数 [#参数-6]

<ParameterList>
<a id="connection-2"></a>
<Parameter name="connection">

Connection 信息。详见 [RtcConnection](/zh-CN/api-reference/rtc/flutter/class-rtcconnection)。

</Parameter>
</ParameterList>

<a id="api_irtcengineex_getconnectionstateex__return_values"></a>

### 返回值 [#返回值-7]

当前网络连接状态。详见 [ConnectionStateType](/zh-CN/api-reference/rtc/flutter/enum-connectionstatetype)。

### 所属接口类 [#所属接口类-8]

- [RtcEngineEx](/zh-CN/api-reference/rtc/flutter/rtc-interface-class#class_irtcengineex)

<a id="api_irtcengine_getcurrentmonotonictimeinms"></a>

<a id="ariaid-title11"></a>

## getCurrentMonotonicTimeInMs [#getcurrentmonotonictimeinms]

获取 SDK 当前的 Monotonic Time。

<a id="api_irtcengine_getcurrentmonotonictimeinms__prototype"></a>

```dart
Future<int> getCurrentMonotonicTimeInMs();
```

<a id="api_irtcengine_getcurrentmonotonictimeinms__detailed_desc"></a>

Monotonic Time 是指一个单调递增的时间序列，它的值会随着时间的推移而增加。单位为毫秒。
在自定义视频采集、自定义音频采集场景中，为确保音视频同步，声网建议你调用该方法获取 SDK 当前的 Monotonic Time 后，将该值传入采集的视频帧（[VideoFrame](/zh-CN/api-reference/rtc/flutter/class-videoframe)）、音频帧（[AudioFrame](/zh-CN/api-reference/rtc/flutter/class-audioframe)）的时间戳参数。

<a id="api_irtcengine_getcurrentmonotonictimeinms__timing"></a>

### 调用时机 [#调用时机-6]

加入频道前后均可调用。

<a id="api_irtcengine_getcurrentmonotonictimeinms__return_values"></a>

### 返回值 [#返回值-8]

- ≥ 0: 方法调用成功，返回 SDK 当前的 Monotonic Time（毫秒）。
- &lt; 0: 方法调用失败。详见[错误码](/zh-CN/api-reference/rtc/error-code)了解详情和解决建议。

### 所属接口类 [#所属接口类-9]

- [RtcEngine](/zh-CN/api-reference/rtc/flutter/rtc-interface-class#class_irtcengine)

<a id="api_irtcengine_geterrordescription"></a>

<a id="ariaid-title12"></a>

## getErrorDescription [#geterrordescription]

获取警告或错误描述。

<a id="api_irtcengine_geterrordescription__prototype"></a>

```dart
Future<String> getErrorDescription(int code);
```

<a id="api_irtcengine_geterrordescription__detailed_desc"></a>

<a id="api_irtcengine_geterrordescription__parameters"></a>

### 参数 [#参数-7]

<ParameterList>
<a id="code"></a>
<Parameter name="code">

SDK 报告的错误码。

</Parameter>
</ParameterList>

<a id="api_irtcengine_geterrordescription__return_values"></a>

### 返回值 [#返回值-9]

具体的错误描述。

### 所属接口类 [#所属接口类-10]

- [RtcEngine](/zh-CN/api-reference/rtc/flutter/rtc-interface-class#class_irtcengine)

<a id="api_irtcengine_getnativehandle"></a>

<a id="ariaid-title13"></a>

## getNativeHandle [#getnativehandle]

获取 Native SDK 的 C++ 句柄。

<a id="api_irtcengine_getnativehandle__prototype"></a>

```dart
Future<int> getNativeHandle();
```

<a id="api_irtcengine_getnativehandle__detailed_desc"></a>

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

<a id="api_irtcengine_getnativehandle__return_values"></a>

### 返回值 [#返回值-10]

SDK 引擎的 Native 句柄。

### 所属接口类 [#所属接口类-11]

- [RtcEngine](/zh-CN/api-reference/rtc/flutter/rtc-interface-class#class_irtcengine)

<a id="api_irtcengine_getnetworktype"></a>

<a id="ariaid-title14"></a>

## getNetworkType [#getnetworktype]

获取本地网络连接类型。

<a id="api_irtcengine_getnetworktype__prototype"></a>

```dart
Future<int> getNetworkType();
```

<a id="api_irtcengine_getnetworktype__detailed_desc"></a>

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

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

<a id="api_irtcengine_getnetworktype__return_values"></a>

### 返回值 [#返回值-11]

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

  - 0：网络连接已断开。
  - 1：网络类型为 LAN。
  - 2：网络类型为 Wi-Fi（包含热点）。
  - 3：网络类型为 2G 移动网络。
  - 4：网络类型为 3G 移动网络。
  - 5：网络类型为 4G 移动网络。
  - 6：网络类型为 5G 移动网络。
- &lt; 0: 方法调用失败，返回错误码。

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

### 所属接口类 [#所属接口类-12]

- [RtcEngine](/zh-CN/api-reference/rtc/flutter/rtc-interface-class#class_irtcengine)

<a id="api_irtcengine_getntpwalltimeinms"></a>

<a id="ariaid-title15"></a>

## getNtpWallTimeInMs [#getntpwalltimeinms]

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

<a id="api_irtcengine_getntpwalltimeinms__prototype"></a>

```dart
Future<int> getNtpWallTimeInMs();
```

<a id="api_irtcengine_getntpwalltimeinms__detailed_desc"></a>

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

<a id="api_irtcengine_getntpwalltimeinms__return_values"></a>

### 返回值 [#返回值-12]

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

### 所属接口类 [#所属接口类-13]

- [RtcEngine](/zh-CN/api-reference/rtc/flutter/rtc-interface-class#class_irtcengine)

<a id="api_irtcengine_getversion"></a>

<a id="ariaid-title16"></a>

## getVersion [#getversion]

获取 SDK 版本。

<a id="api_irtcengine_getversion__prototype"></a>

```dart
Future<SDKBuildInfo> getVersion();
```

<a id="api_irtcengine_getversion__detailed_desc"></a>

<a id="api_irtcengine_getversion__return_values"></a>

### 返回值 [#返回值-13]

[SDKBuildInfo](/zh-CN/api-reference/rtc/flutter/class-sdkbuildinfo) 对象。

### 所属接口类 [#所属接口类-14]

- [RtcEngine](/zh-CN/api-reference/rtc/flutter/rtc-interface-class#class_irtcengine)

<a id="api_irtcengine_isfeatureavailableondevice"></a>

<a id="ariaid-title17"></a>

## isFeatureAvailableOnDevice [#isfeatureavailableondevice]

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

<a id="api_irtcengine_isfeatureavailableondevice__prototype"></a>

```dart
Future<bool> isFeatureAvailableOnDevice(FeatureType type);
```

<a id="api_irtcengine_isfeatureavailableondevice__detailed_desc"></a>

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

<a id="api_irtcengine_isfeatureavailableondevice__scenario"></a>

### 适用场景 [#适用场景-2]

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

<a id="api_irtcengine_isfeatureavailableondevice__parameters"></a>

### 参数 [#参数-8]

<ParameterList>
<a id="type"></a>
<Parameter name="type">

进阶功能类型，详见 [FeatureType](/zh-CN/api-reference/rtc/flutter/enum-featuretype)。

</Parameter>
</ParameterList>

<a id="api_irtcengine_isfeatureavailableondevice__return_values"></a>

### 返回值 [#返回值-14]

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

### 所属接口类 [#所属接口类-15]

- [RtcEngine](/zh-CN/api-reference/rtc/flutter/rtc-interface-class#class_irtcengine)

<a id="api_irtcengine_querydevicescore"></a>

<a id="ariaid-title18"></a>

## queryDeviceScore [#querydevicescore]

查询设备评分等级。

<a id="api_irtcengine_querydevicescore__prototype"></a>

```dart
Future<int> queryDeviceScore();
```

<a id="api_irtcengine_querydevicescore__detailed_desc"></a>

<a id="api_irtcengine_querydevicescore__scenario"></a>

### 适用场景 [#适用场景-3]

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

<a id="api_irtcengine_querydevicescore__return_values"></a>

### 返回值 [#返回值-15]

方法调用成功时，返回一个取值范围为 [0,100] 的值，表示当前设备的评分等级，数值越大表示设备能力越强，大部分设备的评分在 60 到 100 之间；方法调用失败时，会抛出 [AgoraRtcException](/zh-CN/api-reference/rtc/flutter/class-agorartcexception) 异常，你需要捕获异常并进行处理。

- &lt; 0: 方法调用失败。

### 所属接口类 [#所属接口类-16]

- [RtcEngine](/zh-CN/api-reference/rtc/flutter/rtc-interface-class#class_irtcengine)

<a id="api_irtcengine_rate"></a>

<a id="ariaid-title19"></a>

## rate [#rate]

给通话评分。

<a id="api_irtcengine_rate__prototype"></a>

```dart
Future<void> rate(
    {required String callId,
    required int rating,
    required String description});
```

<a id="api_irtcengine_rate__detailed_desc"></a>

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

<a id="api_irtcengine_rate__parameters"></a>

### 参数 [#参数-9]

<ParameterList>
<a id="callid-1"></a>
<Parameter name="callId">

通话 ID。你可以通过调用 [getCallId](/zh-CN/api-reference/rtc/flutter/network#api_irtcengine_getcallid) 获取该参数。

</Parameter>
<a id="rating"></a>
<Parameter name="rating">

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

</Parameter>
<a id="description-1"></a>
<Parameter name="description">

给通话的描述。长度应小于 800 字节。

</Parameter>
</ParameterList>

<a id="api_irtcengine_rate__return_values"></a>

### 返回值 [#返回值-16]

方法成功调用时，无返回值；方法调用失败时，会抛出 [AgoraRtcException](/zh-CN/api-reference/rtc/flutter/class-agorartcexception) 异常，你需要捕获异常并进行处理。详见[错误码](/zh-CN/api-reference/rtc/error-code)了解详情和解决建议。

### 所属接口类 [#所属接口类-17]

- [RtcEngine](/zh-CN/api-reference/rtc/flutter/rtc-interface-class#class_irtcengine)

<a id="api_irtcengine_sendcustomreportmessage"></a>

<a id="ariaid-title20"></a>

## sendCustomReportMessage [#sendcustomreportmessage]

发送自定义上报消息。

<a id="api_irtcengine_sendcustomreportmessage__prototype"></a>

```dart
Future<void> sendCustomReportMessage(
    {required String id,
    required String category,
    required String event,
    required String label,
    required int value});
```

<a id="api_irtcengine_sendcustomreportmessage__detailed_desc"></a>

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

### 所属接口类 [#所属接口类-18]

- [RtcEngine](/zh-CN/api-reference/rtc/flutter/rtc-interface-class#class_irtcengine)

<a id="api_irtcengineex_sendcustomreportmessageex"></a>

<a id="ariaid-title21"></a>

## sendCustomReportMessageEx [#sendcustomreportmessageex]

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

<a id="api_irtcengineex_sendcustomreportmessageex__prototype"></a>

```dart
Future<void> sendCustomReportMessageEx(
      {required String id,
      required String category,
      required String event,
      required String label,
      required int value,
      required RtcConnection connection});
```

<a id="api_irtcengineex_sendcustomreportmessageex__detailed_desc"></a>

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

### 所属接口类 [#所属接口类-19]

- [RtcEngineEx](/zh-CN/api-reference/rtc/flutter/rtc-interface-class#class_irtcengineex)

<a id="api_irtcengine_setavsyncsource"></a>

<a id="ariaid-title22"></a>

## setAVSyncSource [#setavsyncsource]

设置发流端音画同步。

<a id="api_irtcengine_setavsyncsource__prototype"></a>

```dart
Future<void> setAVSyncSource({required String channelId, required int uid});
```

<a id="api_irtcengine_setavsyncsource__detailed_desc"></a>

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

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

<a id="api_irtcengine_setavsyncsource__parameters"></a>

### 参数 [#参数-10]

<ParameterList>
<a id="channelid"></a>
<Parameter name="channelId">

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

</Parameter>
<a id="uid"></a>
<Parameter name="uid">

音频发送端的用户 ID。

</Parameter>
</ParameterList>

<a id="api_irtcengine_setavsyncsource__return_values"></a>

### 返回值 [#返回值-17]

方法成功调用时，无返回值；方法调用失败时，会抛出 [AgoraRtcException](/zh-CN/api-reference/rtc/flutter/class-agorartcexception) 异常，你需要捕获异常并进行处理。详见[错误码](/zh-CN/api-reference/rtc/error-code)了解详情和解决建议。

### 所属接口类 [#所属接口类-20]

- [RtcEngine](/zh-CN/api-reference/rtc/flutter/rtc-interface-class#class_irtcengine)

<a id="api_irtcengine_setcloudproxy"></a>

<a id="ariaid-title23"></a>

## setCloudProxy [#setcloudproxy]

设置云代理服务。

<a id="api_irtcengine_setcloudproxy__prototype"></a>

```dart
Future<void> setCloudProxy(CloudProxyType proxyType);
```

<a id="api_irtcengine_setcloudproxy__detailed_desc"></a>

当用户的网络访问受到防火墙限制时，你需要将声网提供的 IP 和端口号添加到防火墙白名单，然后调用该方法开启云代理，并通过 `proxyType` 参数设置云代理类型。
成功连接云代理后，SDK 会触发 [onConnectionStateChanged](/zh-CN/api-reference/rtc/flutter/network#callback_irtcengineeventhandler_onconnectionstatechanged) (connectionStateConnecting, connectionChangedSettingProxyServer) 回调。
如果你想关闭已设置的 Force UDP 或 Force TCP 云代理，请调用 `setCloudProxy(noneProxy)`。
如果你想更改已设置的云代理类型，请先调用 `setCloudProxy(noneProxy)`，再调用 [setCloudProxy](/zh-CN/api-reference/rtc/flutter/network#api_irtcengine_setcloudproxy) 并传入你期望的 `proxyType` 值。

:::note
注：

- 建议你在频道外调用该方法。
- 如果用户处于内网防火墙环境下，使用 Force UDP 云代理时，旁路推流和跨频道媒体流转发功能不可用。
- 使用 Force UDP 云代理时，调用 [startAudioMixing](/zh-CN/api-reference/rtc/flutter/play/audio-mixing#api_irtcengine_startaudiomixing2) 方法时无法播放 HTTP 协议的在线音频文件。旁路推流和跨频道媒体流转发功能会使用 TCP 协议的云代理。
:::

<a id="api_irtcengine_setcloudproxy__parameters"></a>

### 参数 [#参数-11]

<ParameterList>
<a id="proxytype"></a>
<Parameter name="proxyType">

云代理类型，详见 [CloudProxyType](/zh-CN/api-reference/rtc/flutter/enum-cloudproxytype)。
该参数为必填参数，如果你不赋值，SDK 会报错。

</Parameter>
</ParameterList>

<a id="api_irtcengine_setcloudproxy__return_values"></a>

### 返回值 [#返回值-18]

方法成功调用时，无返回值；方法调用失败时，会抛出 [AgoraRtcException](/zh-CN/api-reference/rtc/flutter/class-agorartcexception) 异常，你需要捕获异常并进行处理。详见[错误码](/zh-CN/api-reference/rtc/error-code)了解详情和解决建议。

### 所属接口类 [#所属接口类-21]

- [RtcEngine](/zh-CN/api-reference/rtc/flutter/rtc-interface-class#class_irtcengine)

<a id="api_irtcengine_setlocalaccesspoint"></a>

<a id="ariaid-title24"></a>

## setLocalAccessPoint [#setlocalaccesspoint]

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

<a id="api_irtcengine_setlocalaccesspoint__prototype"></a>

```dart
Future<void> setLocalAccessPoint(LocalAccessPointConfiguration config);
```

<a id="api_irtcengine_setlocalaccesspoint__detailed_desc"></a>

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

:::note
注： 该方法仅在部署声网混合云方案后生效。你可以[联系销售](https://www.shengwang.cn/contact-sales/)了解和部署声网混合云。
:::

<a id="api_irtcengine_setlocalaccesspoint__timing"></a>

### 调用时机 [#调用时机-7]

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

<a id="api_irtcengine_setlocalaccesspoint__parameters"></a>

### 参数 [#参数-12]

<ParameterList>
<a id="config-2"></a>
<Parameter name="config">

Local Access Point 配置。详见 LocalAccessPointConfiguration。

</Parameter>
</ParameterList>

<a id="api_irtcengine_setlocalaccesspoint__return_values"></a>

### 返回值 [#返回值-19]

方法成功调用时，无返回值；方法调用失败时，会抛出 [AgoraRtcException](/zh-CN/api-reference/rtc/flutter/class-agorartcexception) 异常，你需要捕获异常并进行处理。详见[错误码](/zh-CN/api-reference/rtc/error-code)了解详情和解决建议。

### 所属接口类 [#所属接口类-22]

- [RtcEngine](/zh-CN/api-reference/rtc/flutter/rtc-interface-class#class_irtcengine)

<a id="api_irtcengine_setlogfile"></a>

<a id="ariaid-title25"></a>

## setLogFile [#setlogfile]

设置日志文件

<a id="api_irtcengine_setlogfile__prototype"></a>

```dart
Future<void> setLogFile(String filePath);
```

<a id="api_irtcengine_setlogfile__detailed_desc"></a>

<a id="废弃-1"></a>

:::error[废弃]
弃用： 该方法已废弃，请在调用 [initialize](/zh-CN/api-reference/rtc/flutter/initialize#api_irtcengine_initialize) 时通过 `context` 参数设置日志文件路径。
:::

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

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

<a id="api_irtcengine_setlogfile__timing"></a>

### 调用时机 [#调用时机-8]

该方法需要在 [initialize](/zh-CN/api-reference/rtc/flutter/initialize#api_irtcengine_initialize) 后立即调用，否则输出日志可能不完整。

<a id="api_irtcengine_setlogfile__parameters"></a>

### 参数 [#参数-13]

<ParameterList>
<a id="filepath"></a>
<Parameter name="filePath">

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

</Parameter>
</ParameterList>

<a id="api_irtcengine_setlogfile__return_values"></a>

### 返回值 [#返回值-20]

方法成功调用时，无返回值；方法调用失败时，会抛出 [AgoraRtcException](/zh-CN/api-reference/rtc/flutter/class-agorartcexception) 异常，你需要捕获异常并进行处理。详见[错误码](/zh-CN/api-reference/rtc/error-code)了解详情和解决建议。

### 所属接口类 [#所属接口类-23]

- [RtcEngine](/zh-CN/api-reference/rtc/flutter/rtc-interface-class#class_irtcengine)

<a id="api_irtcengine_setlogfilesize"></a>

<a id="ariaid-title26"></a>

## setLogFileSize [#setlogfilesize]

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

<a id="api_irtcengine_setlogfilesize__prototype"></a>

```dart
Future<void> setLogFileSize(int fileSizeInKBytes);
```

<a id="api_irtcengine_setlogfilesize__detailed_desc"></a>

<a id="废弃-2"></a>

:::error[废弃]
弃用： 该方法已废弃，请改用 [initialize](/zh-CN/api-reference/rtc/flutter/initialize#api_irtcengine_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` 相同。

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

<a id="api_irtcengine_setlogfilesize__parameters"></a>

### 参数 [#参数-14]

<ParameterList>
<a id="filesizeinkbytes"></a>
<Parameter name="fileSizeInKBytes">

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

</Parameter>
</ParameterList>

<a id="api_irtcengine_setlogfilesize__return_values"></a>

### 返回值 [#返回值-21]

方法成功调用时，无返回值；方法调用失败时，会抛出 [AgoraRtcException](/zh-CN/api-reference/rtc/flutter/class-agorartcexception) 异常，你需要捕获异常并进行处理。详见[错误码](/zh-CN/api-reference/rtc/error-code)了解详情和解决建议。

### 所属接口类 [#所属接口类-24]

- [RtcEngine](/zh-CN/api-reference/rtc/flutter/rtc-interface-class#class_irtcengine)

<a id="api_irtcengine_setlogfilter"></a>

<a id="ariaid-title27"></a>

## setLogFilter [#setlogfilter]

设置日志输出等级。

<a id="api_irtcengine_setlogfilter__prototype"></a>

```dart
Future<void> setLogFilter(LogFilterType filter);
```

<a id="api_irtcengine_setlogfilter__detailed_desc"></a>

<a id="废弃-3"></a>

:::error[废弃]
弃用： 请改用 [initialize](/zh-CN/api-reference/rtc/flutter/initialize#api_irtcengine_initialize) 中的 `logConfig`。
:::

该方法设置 SDK 的输出日志输出等级。不同的输出等级可以单独或组合使用。日志级别顺序依次为 `logFilterOff`、`logFilterCritical`、`logFilterError`、`logFilterWarn`、`logFilterInfo` 和 `logFilterDebug`。
选择一个级别，你就可以看到在该级别之前所有级别的日志信息。
例如，你选择 `logFilterWarn` 级别，就可以看到在 `logFilterCritical`、`logFilterError` 和 `logFilterWarn` 级别的日志信息。

<a id="api_irtcengine_setlogfilter__parameters"></a>

### 参数 [#参数-15]

<ParameterList>
<a id="filter"></a>
<Parameter name="filter">

日志过滤等级。详见 [LogFilterType](/zh-CN/api-reference/rtc/flutter/enum-logfiltertype)。

</Parameter>
</ParameterList>

<a id="api_irtcengine_setlogfilter__return_values"></a>

### 返回值 [#返回值-22]

方法成功调用时，无返回值；方法调用失败时，会抛出 [AgoraRtcException](/zh-CN/api-reference/rtc/flutter/class-agorartcexception) 异常，你需要捕获异常并进行处理。详见[错误码](/zh-CN/api-reference/rtc/error-code)了解详情和解决建议。

### 所属接口类 [#所属接口类-25]

- [RtcEngine](/zh-CN/api-reference/rtc/flutter/rtc-interface-class#class_irtcengine)

<a id="api_irtcengine_setloglevel"></a>

<a id="ariaid-title28"></a>

## setLogLevel [#setloglevel]

设置 SDK 的日志输出级别。

<a id="api_irtcengine_setloglevel__prototype"></a>

```dart
Future<void> setLogLevel(LogLevel level);
```

<a id="api_irtcengine_setloglevel__detailed_desc"></a>

<a id="废弃-4"></a>

:::error[废弃]
弃用： 该方法已废弃，请在调用 [initialize](/zh-CN/api-reference/rtc/flutter/initialize#api_irtcengine_initialize) 时通过 `context` 参数设置日志输出级别。
:::

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

<a id="api_irtcengine_setloglevel__parameters"></a>

### 参数 [#参数-16]

<ParameterList>
<a id="level"></a>
<Parameter name="level">

日志级别。详见 [LogLevel](/zh-CN/api-reference/rtc/flutter/enum-loglevel)。

</Parameter>
</ParameterList>

<a id="api_irtcengine_setloglevel__return_values"></a>

### 返回值 [#返回值-23]

方法成功调用时，无返回值；方法调用失败时，会抛出 [AgoraRtcException](/zh-CN/api-reference/rtc/flutter/class-agorartcexception) 异常，你需要捕获异常并进行处理。详见[错误码](/zh-CN/api-reference/rtc/error-code)了解详情和解决建议。

### 所属接口类 [#所属接口类-26]

- [RtcEngine](/zh-CN/api-reference/rtc/flutter/rtc-interface-class#class_irtcengine)

<a id="api_irtcengine_setparameters"></a>

<a id="ariaid-title29"></a>

## setParameters [#setparameters]

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

<a id="api_irtcengine_setparameters__prototype"></a>

```dart
Future<void> setParameters(String parameters);
```

<a id="api_irtcengine_setparameters__detailed_desc"></a>

<a id="api_irtcengine_setparameters__parameters"></a>

### 参数 [#参数-17]

<ParameterList>
<a id="parameters"></a>
<Parameter name="parameters">

JSON 字符串形式的参数。

</Parameter>
</ParameterList>

<a id="api_irtcengine_setparameters__return_values"></a>

### 返回值 [#返回值-24]

方法成功调用时，无返回值；方法调用失败时，会抛出 [AgoraRtcException](/zh-CN/api-reference/rtc/flutter/class-agorartcexception) 异常，你需要捕获异常并进行处理。详见[错误码](/zh-CN/api-reference/rtc/error-code)了解详情和解决建议。

### 所属接口类 [#所属接口类-27]

- [RtcEngine](/zh-CN/api-reference/rtc/flutter/rtc-interface-class#class_irtcengine)

<a id="api_irtcengine_setremotesubscribefallbackoption"></a>

<a id="ariaid-title30"></a>

## setRemoteSubscribeFallbackOption [#setremotesubscribefallbackoption]

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

<a id="api_irtcengine_setremotesubscribefallbackoption__prototype"></a>

```dart
Future<void> setRemoteSubscribeFallbackOption(StreamFallbackOptions option);
```

<a id="api_irtcengine_setremotesubscribefallbackoption__detailed_desc"></a>

网络不理想的环境下，实时通信音视频的质量会下降。你可以调用该方法并将 `option` 设置为 `streamFallbackOptionVideoStreamLow` 或 `streamFallbackOptionAudioOnly`，SDK 会在下行弱网且音视频质量严重受影响时，将视频流切换为小流或关闭视频流，从而保证音频质量。同时，SDK 会持续监控网络质量，并在网络质量改善时恢复订阅音视频流。
当订阅流回退为音频流或由音频流恢复为音视频流时，SDK 会触发 [onRemoteSubscribeFallbackToAudioOnly](/zh-CN/api-reference/rtc/flutter/network#callback_irtcengineeventhandler_onremotesubscribefallbacktoaudioonly) 回调。

<a id="api_irtcengine_setremotesubscribefallbackoption__parameters"></a>

### 参数 [#参数-18]

<ParameterList>
<a id="option"></a>
<Parameter name="option">

订阅流的回退选项。详见 [StreamFallbackOptions](/zh-CN/api-reference/rtc/flutter/enum-streamfallbackoptions)。

</Parameter>
</ParameterList>

<a id="api_irtcengine_setremotesubscribefallbackoption__return_values"></a>

### 返回值 [#返回值-25]

方法成功调用时，无返回值；方法调用失败时，会抛出 [AgoraRtcException](/zh-CN/api-reference/rtc/flutter/class-agorartcexception) 异常，你需要捕获异常并进行处理。详见[错误码](/zh-CN/api-reference/rtc/error-code)了解详情和解决建议。

### 所属接口类 [#所属接口类-28]

- [RtcEngine](/zh-CN/api-reference/rtc/flutter/rtc-interface-class#class_irtcengine)

<a id="api_irtcengine_startechotest2"></a>

<a id="api_irtcengine_startechotest3"></a>

<a id="ariaid-title31"></a>

## startEchoTest [#startechotest]

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

<a id="api_irtcengine_startechotest3__prototype"></a>

```dart
Future<void> startEchoTest(EchoTestConfiguration config);
```

<a id="api_irtcengine_startechotest3__detailed_desc"></a>

为测试用户本地发流、收流是否正常，你可以调用该方法进行音视频通话回路测试，即测试系统的音视频设备和用户的上下行网络是否正常。
开始测试后，用户需发出声音或面对摄像头，音频或视频会在约 2 秒后播放出来。如果音频播放正常，则表示系统音频设备和用户上下行网络均正常； 如果视频播放正常，则表示系统视频设备和用户上下行网络均正常。

:::note
注：

- 在频道内调用该方法时，需确保当前没有发布音视频流。
- 调用该方法后，必须调用 [stopEchoTest](/zh-CN/api-reference/rtc/flutter/network#api_irtcengine_stopechotest) 结束测试，否则该用户无法进行下一次音视频通话回路测试，也无法加入频道。
- 直播场景下，该方法仅能由主播调用。
:::

<a id="api_irtcengine_startechotest3__timing"></a>

### 调用时机 [#调用时机-9]

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

<a id="api_irtcengine_startechotest3__parameters"></a>

### 参数 [#参数-19]

<ParameterList>
<a id="config-3"></a>
<Parameter name="config">

音视频通话回路测试的配置。详见 [EchoTestConfiguration](/zh-CN/api-reference/rtc/flutter/class-echotestconfiguration)。

</Parameter>
</ParameterList>

<a id="api_irtcengine_startechotest3__return_values"></a>

### 返回值 [#返回值-26]

- 0: 方法调用成功。
- &lt; 0: 方法调用失败。详见[错误码](/zh-CN/api-reference/rtc/error-code)了解详情和解决建议。

### 所属接口类 [#所属接口类-29]

- [RtcEngine](/zh-CN/api-reference/rtc/flutter/rtc-interface-class#class_irtcengine)

<a id="api_irtcengine_startlastmileprobetest"></a>

<a id="ariaid-title32"></a>

## startLastmileProbeTest [#startlastmileprobetest]

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

<a id="api_irtcengine_startlastmileprobetest__prototype"></a>

```dart
Future<void> startLastmileProbeTest(LastmileProbeConfig config);
```

<a id="api_irtcengine_startlastmileprobetest__detailed_desc"></a>

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

<a id="api_irtcengine_startlastmileprobetest__timing"></a>

### 调用时机 [#调用时机-10]

该方法需要在加入频道前调用，且在收到 [onLastmileQuality](/zh-CN/api-reference/rtc/flutter/network#callback_irtcengineeventhandler_onlastmilequality) 和 [onLastmileProbeResult](/zh-CN/api-reference/rtc/flutter/network#callback_irtcengineeventhandler_onlastmileproberesult) 回调之前请不要调用其他方法，否则可能会由于 API 操作过于频繁导致此方法无法执行。

<a id="api_irtcengine_startlastmileprobetest__related"></a>

### 相关回调 [#相关回调]

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

- [onLastmileQuality](/zh-CN/api-reference/rtc/flutter/network#callback_irtcengineeventhandler_onlastmilequality)，视网络情况约 2 秒内返回。该回调通过打分反馈上下行网络质量，更贴近用户的主观感受。
- [onLastmileProbeResult](/zh-CN/api-reference/rtc/flutter/network#callback_irtcengineeventhandler_onlastmileproberesult)，视网络情况约 30 秒内返回。该回调通过具体数据反馈上下行网络质量，更加客观。

<a id="api_irtcengine_startlastmileprobetest__parameters"></a>

### 参数 [#参数-20]

<ParameterList>
<a id="config-4"></a>
<Parameter name="config">

Last mile 网络探测配置，详见 [LastmileProbeConfig](/zh-CN/api-reference/rtc/flutter/class-lastmileprobeconfig)。

</Parameter>
</ParameterList>

<a id="api_irtcengine_startlastmileprobetest__return_values"></a>

### 返回值 [#返回值-27]

方法成功调用时，无返回值；方法调用失败时，会抛出 [AgoraRtcException](/zh-CN/api-reference/rtc/flutter/class-agorartcexception) 异常，你需要捕获异常并进行处理。详见[错误码](/zh-CN/api-reference/rtc/error-code)了解详情和解决建议。

### 所属接口类 [#所属接口类-30]

- [RtcEngine](/zh-CN/api-reference/rtc/flutter/rtc-interface-class#class_irtcengine)

<a id="api_irtcengine_stopechotest"></a>

<a id="ariaid-title33"></a>

## stopEchoTest [#stopechotest]

停止语音通话回路测试。

<a id="api_irtcengine_stopechotest__prototype"></a>

```dart
Future<void> stopEchoTest();
```

<a id="api_irtcengine_stopechotest__detailed_desc"></a>

调用 [startEchoTest](/zh-CN/api-reference/rtc/flutter/network#api_irtcengine_startechotest3) 后，必须调用该方法结束测试，否则该用户无法进行下一次音视频通话回路测试，也无法加入频道。

<a id="api_irtcengine_stopechotest__return_values"></a>

### 返回值 [#返回值-28]

方法成功调用时，无返回值；方法调用失败时，会抛出 [AgoraRtcException](/zh-CN/api-reference/rtc/flutter/class-agorartcexception) 异常，你需要捕获异常并进行处理。详见[错误码](/zh-CN/api-reference/rtc/error-code)了解详情和解决建议。

### 所属接口类 [#所属接口类-31]

- [RtcEngine](/zh-CN/api-reference/rtc/flutter/rtc-interface-class#class_irtcengine)

<a id="api_irtcengine_stoplastmileprobetest"></a>

<a id="ariaid-title34"></a>

## stopLastmileProbeTest [#stoplastmileprobetest]

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

<a id="api_irtcengine_stoplastmileprobetest__prototype"></a>

```dart
Future<void> stopLastmileProbeTest();
```

<a id="api_irtcengine_stoplastmileprobetest__detailed_desc"></a>

<a id="api_irtcengine_stoplastmileprobetest__return_values"></a>

### 返回值 [#返回值-29]

方法成功调用时，无返回值；方法调用失败时，会抛出 [AgoraRtcException](/zh-CN/api-reference/rtc/flutter/class-agorartcexception) 异常，你需要捕获异常并进行处理。详见[错误码](/zh-CN/api-reference/rtc/error-code)了解详情和解决建议。

### 所属接口类 [#所属接口类-32]

- [RtcEngine](/zh-CN/api-reference/rtc/flutter/rtc-interface-class#class_irtcengine)

<a id="callback_irtcengineeventhandler_onconnectionbanned"></a>

<a id="ariaid-title35"></a>

## onConnectionBanned [#onconnectionbanned]

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

<a id="callback_irtcengineeventhandler_onconnectionbanned__prototype"></a>

```dart
final void Function(RtcConnection connection)? onConnectionBanned;
```

<a id="callback_irtcengineeventhandler_onconnectionbanned__detailed_desc"></a>

<a id="废弃-5"></a>

:::error[废弃]
弃用: 请改用 [onConnectionStateChanged](/zh-CN/api-reference/rtc/flutter/network#callback_irtcengineeventhandler_onconnectionstatechanged)。
:::

<a id="callback_irtcengineeventhandler_onconnectionbanned__parameters"></a>

### 参数 [#参数-21]

<ParameterList>
<a id="connection-3"></a>
<Parameter name="connection">

Connection 信息。详见 [RtcConnection](/zh-CN/api-reference/rtc/flutter/class-rtcconnection)。

</Parameter>
</ParameterList>

### 所属接口类 [#所属接口类-33]

- [RtcEngineEventHandler](/zh-CN/api-reference/rtc/flutter/rtc-interface-class#class_irtcengineeventhandler)

<a id="callback_irtcengineeventhandler_onconnectioninterrupted"></a>

<a id="ariaid-title36"></a>

## onConnectionInterrupted [#onconnectioninterrupted]

网络连接中断回调。

<a id="callback_irtcengineeventhandler_onconnectioninterrupted__prototype"></a>

```dart
final void Function(RtcConnection connection)? onConnectionInterrupted;
```

<a id="callback_irtcengineeventhandler_onconnectioninterrupted__detailed_desc"></a>

<a id="废弃-6"></a>

:::error[废弃]
弃用: 请改用 [onConnectionStateChanged](/zh-CN/api-reference/rtc/flutter/network#callback_irtcengineeventhandler_onconnectionstatechanged) 回调。
:::

SDK 在和服务器建立连接后，失去了网络连接超过 4 秒，会触发该回调。在触发事件后，SDK 会主动重连服务器，所以该事件可以用于 UI 提示。该回调与 [onConnectionLost](/zh-CN/api-reference/rtc/flutter/network#callback_irtcengineeventhandler_onconnectionlost) 的区别是：

- [onConnectionInterrupted](/zh-CN/api-reference/rtc/flutter/network#callback_irtcengineeventhandler_onconnectioninterrupted) 回调一定是发生在成功加入频道后，且 SDK 刚失去和服务器连接超过 4 秒时触发。
- [onConnectionLost](/zh-CN/api-reference/rtc/flutter/network#callback_irtcengineeventhandler_onconnectionlost) 回调是无论是否成功加入频道，只要 10 秒内和服务器无法建立连接都会触发。

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

<a id="callback_irtcengineeventhandler_onconnectioninterrupted__parameters"></a>

### 参数 [#参数-22]

<ParameterList>
<a id="connection-4"></a>
<Parameter name="connection">

Connection 信息。详见 [RtcConnection](/zh-CN/api-reference/rtc/flutter/class-rtcconnection)。

</Parameter>
</ParameterList>

### 所属接口类 [#所属接口类-34]

- [RtcEngineEventHandler](/zh-CN/api-reference/rtc/flutter/rtc-interface-class#class_irtcengineeventhandler)

<a id="callback_irtcengineeventhandler_onconnectionlost"></a>

<a id="ariaid-title37"></a>

## onConnectionLost [#onconnectionlost]

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

<a id="callback_irtcengineeventhandler_onconnectionlost__prototype"></a>

```dart
final void Function(RtcConnection connection)? onConnectionLost;
```

<a id="callback_irtcengineeventhandler_onconnectionlost__detailed_desc"></a>

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

<a id="callback_irtcengineeventhandler_onconnectionlost__parameters"></a>

### 参数 [#参数-23]

<ParameterList>
<a id="connection-5"></a>
<Parameter name="connection">

Connection 信息。详见 [RtcConnection](/zh-CN/api-reference/rtc/flutter/class-rtcconnection)。

</Parameter>
</ParameterList>

### 所属接口类 [#所属接口类-35]

- [RtcEngineEventHandler](/zh-CN/api-reference/rtc/flutter/rtc-interface-class#class_irtcengineeventhandler)

<a id="callback_irtcengineeventhandler_onconnectionstatechanged"></a>

<a id="ariaid-title38"></a>

## onConnectionStateChanged [#onconnectionstatechanged]

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

<a id="callback_irtcengineeventhandler_onconnectionstatechanged__prototype"></a>

```dart
final void Function(RtcConnection connection, ConnectionStateType state,
      ConnectionChangedReasonType reason)? onConnectionStateChanged;
```

<a id="callback_irtcengineeventhandler_onconnectionstatechanged__detailed_desc"></a>

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

<a id="callback_irtcengineeventhandler_onconnectionstatechanged__parameters"></a>

### 参数 [#参数-24]

<ParameterList>
<a id="connection-6"></a>
<Parameter name="connection">

Connection 信息。详见 [RtcConnection](/zh-CN/api-reference/rtc/flutter/class-rtcconnection)。

</Parameter>
<a id="state"></a>
<Parameter name="state">

当前网络连接状态。详见 [ConnectionStateType](/zh-CN/api-reference/rtc/flutter/enum-connectionstatetype)。

</Parameter>
<a id="reason"></a>
<Parameter name="reason">

引起当前网络连接状态改变的原因。详见 [ConnectionChangedReasonType](/zh-CN/api-reference/rtc/flutter/enum-connectionchangedreasontype)。

</Parameter>
</ParameterList>

### 所属接口类 [#所属接口类-36]

- [RtcEngineEventHandler](/zh-CN/api-reference/rtc/flutter/rtc-interface-class#class_irtcengineeventhandler)

<a id="callback_irtcengineeventhandler_onencryptionerror"></a>

<a id="ariaid-title39"></a>

## onEncryptionError [#onencryptionerror]

内置加密出错回调。

<a id="callback_irtcengineeventhandler_onencryptionerror__prototype"></a>

```dart
final void Function(RtcConnection connection, EncryptionErrorType errorType)?
      onEncryptionError;
```

<a id="callback_irtcengineeventhandler_onencryptionerror__detailed_desc"></a>

调用 [enableEncryption](/zh-CN/api-reference/rtc/flutter/network#api_irtcengine_enableencryption) 开启加密后， 如果发流端、收流端出现加解密出错，SDK 会触发该回调。

<a id="callback_irtcengineeventhandler_onencryptionerror__parameters"></a>

### 参数 [#参数-25]

<ParameterList>
<a id="connection-7"></a>
<Parameter name="connection">

Connection 信息。详见 [RtcConnection](/zh-CN/api-reference/rtc/flutter/class-rtcconnection)。

</Parameter>
<a id="errortype"></a>
<Parameter name="errorType">

错误类型，详见 [EncryptionErrorType](/zh-CN/api-reference/rtc/flutter/enum-encryptionerrortype)。

</Parameter>
</ParameterList>

### 所属接口类 [#所属接口类-37]

- [RtcEngineEventHandler](/zh-CN/api-reference/rtc/flutter/rtc-interface-class#class_irtcengineeventhandler)

<a id="callback_irtcengineeventhandler_onlastmileproberesult"></a>

<a id="ariaid-title40"></a>

## onLastmileProbeResult [#onlastmileproberesult]

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

<a id="callback_irtcengineeventhandler_onlastmileproberesult__prototype"></a>

```dart
final void Function(LastmileProbeResult result)? onLastmileProbeResult;
```

<a id="callback_irtcengineeventhandler_onlastmileproberesult__detailed_desc"></a>

在调用 [startLastmileProbeTest](/zh-CN/api-reference/rtc/flutter/network#api_irtcengine_startlastmileprobetest) 之后，SDK 会在约 30 秒内返回该回调。

<a id="callback_irtcengineeventhandler_onlastmileproberesult__parameters"></a>

### 参数 [#参数-26]

<ParameterList>
<a id="result"></a>
<Parameter name="result">

上下行 Last mile 质量探测结果。详见 [LastmileProbeResult](/zh-CN/api-reference/rtc/flutter/class-lastmileproberesult)。

</Parameter>
</ParameterList>

### 所属接口类 [#所属接口类-38]

- [RtcEngineEventHandler](/zh-CN/api-reference/rtc/flutter/rtc-interface-class#class_irtcengineeventhandler)

<a id="callback_irtcengineeventhandler_onlastmilequality"></a>

<a id="ariaid-title41"></a>

## onLastmileQuality [#onlastmilequality]

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

<a id="callback_irtcengineeventhandler_onlastmilequality__prototype"></a>

```dart
final void Function(QualityType quality)? onLastmileQuality;
```

<a id="callback_irtcengineeventhandler_onlastmilequality__detailed_desc"></a>

该回调描述本地用户在加入频道前的 last mile 网络探测的结果，其中 last mile 是指设备到声网边缘服务器的网络状态。
加入频道前，调用 [startLastmileProbeTest](/zh-CN/api-reference/rtc/flutter/network#api_irtcengine_startlastmileprobetest) 之后，SDK 触发该回调报告本地用户在加入频道前的 last mile 网络探测的结果。

<a id="callback_irtcengineeventhandler_onlastmilequality__parameters"></a>

### 参数 [#参数-27]

<ParameterList>
<a id="quality"></a>
<Parameter name="quality">

Last mile 网络质量。详见 [QualityType](/zh-CN/api-reference/rtc/flutter/enum-qualitytype)。

</Parameter>
</ParameterList>

### 所属接口类 [#所属接口类-39]

- [RtcEngineEventHandler](/zh-CN/api-reference/rtc/flutter/rtc-interface-class#class_irtcengineeventhandler)

<a id="callback_irtcengineeventhandler_onmultipathstats"></a>

<a id="ariaid-title42"></a>

## onMultipathStats [#onmultipathstats]

多路径传输统计信息的回调。

<a id="callback_irtcengineeventhandler_onmultipathstats__prototype"></a>

```dart
  final void Function(RtcConnection connection, MultipathStats stats)?
      onMultipathStats;
```

<a id="callback_irtcengineeventhandler_onmultipathstats__detailed_desc"></a>

:::info[自从]
自 v6.6.2 版本新增。
:::

<a id="callback_irtcengineeventhandler_onmultipathstats__timing"></a>

### 触发时机 [#触发时机]

该回调在你将 `enableMultipath` 设置为 true 以启用多路径传输后触发。

<a id="callback_irtcengineeventhandler_onmultipathstats__parameters"></a>

### 参数 [#参数-28]

<ParameterList>
<a id="stats"></a>
<Parameter name="stats">

多路径传输统计信息。详见 [MultipathStats](/zh-CN/api-reference/rtc/flutter/class-multipathstats)。

</Parameter>
</ParameterList>

### 所属接口类 [#所属接口类-40]

- [RtcEngineEventHandler](/zh-CN/api-reference/rtc/flutter/rtc-interface-class#class_irtcengineeventhandler)

<a id="callback_irtcengineeventhandler_onnetworkquality"></a>

<a id="ariaid-title43"></a>

## onNetworkQuality [#onnetworkquality]

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

<a id="callback_irtcengineeventhandler_onnetworkquality__prototype"></a>

```dart
final void Function(RtcConnection connection, int remoteUid,
      QualityType txQuality, QualityType rxQuality)? onNetworkQuality;
```

<a id="callback_irtcengineeventhandler_onnetworkquality__detailed_desc"></a>

该回调描述每个用户在通话中的 last mile 网络状态，其中 last mile 是指设备到声网边缘服务器的网络状态。
该回调每 2 秒触发一次。如果远端有多个用户，该回调每 2 秒会被触发多次。
该回调通过频道内的广播包反馈网络质量。过多的广播包可能引发广播风暴。为防止广播风暴导致频道内大量数据传输，该回调默认支持同时反馈最多 4 个远端主播的网络质量。

:::note
注： 用户不发流时，`txQuality` 为 `Unknown`；用户不收流时，`rxQuality` 为 `Unknown`。
:::

<a id="callback_irtcengineeventhandler_onnetworkquality__parameters"></a>

### 参数 [#参数-29]

<ParameterList>
<a id="connection-8"></a>
<Parameter name="connection">

Connection 信息。详见 [RtcConnection](/zh-CN/api-reference/rtc/flutter/class-rtcconnection)。

</Parameter>
<a id="remoteuid"></a>
<Parameter name="remoteUid">

用户 ID。表示该回调报告的是持有该 ID 的用户的网络质量。如果当 uid 为 0 时，返回的是本地用户的网络质量。

</Parameter>
<a id="txquality"></a>
<Parameter name="txQuality">

该用户的上行网络质量，基于发送码率、上行丢包率、平均往返时延和网络抖动计算。 该值代表当前的上行网络质量，帮助判断是否可以支持当前设置的视频编码属性。 假设上行码率是 1000 Kbps，那么支持直播场景下 640 × 480 的分辨率、15 fps 的帧率没有问题，但是支持 1280 × 720 的分辨率就会有困难。详见 [QualityType](/zh-CN/api-reference/rtc/flutter/enum-qualitytype)。

</Parameter>
<a id="rxquality"></a>
<Parameter name="rxQuality">

该用户的下行网络质量，基于下行网络的丢包率、平均往返延时和网络抖动计算。详见 [QualityType](/zh-CN/api-reference/rtc/flutter/enum-qualitytype)。

</Parameter>
</ParameterList>

### 所属接口类 [#所属接口类-41]

- [RtcEngineEventHandler](/zh-CN/api-reference/rtc/flutter/rtc-interface-class#class_irtcengineeventhandler)

<a id="callback_irtcengineeventhandler_onnetworktypechanged"></a>

<a id="ariaid-title44"></a>

## onNetworkTypeChanged [#onnetworktypechanged]

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

<a id="callback_irtcengineeventhandler_onnetworktypechanged__prototype"></a>

```dart
final void Function(RtcConnection connection, NetworkType type)?
      onNetworkTypeChanged;
```

<a id="callback_irtcengineeventhandler_onnetworktypechanged__detailed_desc"></a>

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

<a id="callback_irtcengineeventhandler_onnetworktypechanged__parameters"></a>

### 参数 [#参数-30]

<ParameterList>
<a id="connection-9"></a>
<Parameter name="connection">

Connection 信息。详见 [RtcConnection](/zh-CN/api-reference/rtc/flutter/class-rtcconnection)。

</Parameter>
<a id="type-1"></a>
<Parameter name="type">

本地网络连接类型。详见 [NetworkType](/zh-CN/api-reference/rtc/flutter/enum-networktype)。

</Parameter>
</ParameterList>

### 所属接口类 [#所属接口类-42]

- [RtcEngineEventHandler](/zh-CN/api-reference/rtc/flutter/rtc-interface-class#class_irtcengineeventhandler)

<a id="callback_irtcengineeventhandler_onpermissionerror"></a>

<a id="ariaid-title45"></a>

## onPermissionError [#onpermissionerror]

获取设备权限出错回调。

<a id="callback_irtcengineeventhandler_onpermissionerror__prototype"></a>

```dart
final void Function(PermissionType permissionType)? onPermissionError;
```

<a id="callback_irtcengineeventhandler_onpermissionerror__detailed_desc"></a>

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

<a id="callback_irtcengineeventhandler_onpermissionerror__parameters"></a>

### 参数 [#参数-31]

<ParameterList>
<a id="permissiontype"></a>
<Parameter name="permissionType">

设备权限类型。详见 [PermissionType](/zh-CN/api-reference/rtc/flutter/enum-permissiontype)。

</Parameter>
</ParameterList>

### 所属接口类 [#所属接口类-43]

- [RtcEngineEventHandler](/zh-CN/api-reference/rtc/flutter/rtc-interface-class#class_irtcengineeventhandler)

<a id="callback_irtcengineeventhandler_onpermissiongranted"></a>

<a id="ariaid-title46"></a>

## onPermissionGranted [#onpermissiongranted]

权限被授予时的回调。

<a id="callback_irtcengineeventhandler_onpermissiongranted__prototype"></a>

```dart
  final void Function(PermissionType permissionType)?
      onPermissionGranted;
```

<a id="callback_irtcengineeventhandler_onpermissiongranted__detailed_desc"></a>

<a id="callback_irtcengineeventhandler_onpermissiongranted__parameters"></a>

### 参数 [#参数-32]

<ParameterList>
<a id="permissiontype-1"></a>
<Parameter name="permissionType">

权限类型，详见 [PermissionType](/zh-CN/api-reference/rtc/flutter/enum-permissiontype)。

</Parameter>
</ParameterList>

### 所属接口类 [#所属接口类-44]

- [RtcEngineEventHandler](/zh-CN/api-reference/rtc/flutter/rtc-interface-class#class_irtcengineeventhandler)

<a id="callback_irtcengineeventhandler_onproxyconnected"></a>

<a id="ariaid-title47"></a>

## onProxyConnected [#onproxyconnected]

代理连接状态回调。

<a id="callback_irtcengineeventhandler_onproxyconnected__prototype"></a>

```dart
final void Function(String channel, int uid, ProxyType proxyType,
      String localProxyIp, int elapsed)? onProxyConnected;
```

<a id="callback_irtcengineeventhandler_onproxyconnected__detailed_desc"></a>

通过该回调你可以监听 SDK 连接代理的状态。例如，当用户调用 [setCloudProxy](/zh-CN/api-reference/rtc/flutter/network#api_irtcengine_setcloudproxy) 设置代理并成功加入频道后，SDK 会触发该回调报告用户 ID、连接的代理类型和从调用 [joinChannel](/zh-CN/api-reference/rtc/flutter/channel#api_irtcengine_joinchannel2) 到触发该回调经过的时间等。

<a id="callback_irtcengineeventhandler_onproxyconnected__parameters"></a>

### 参数 [#参数-33]

<ParameterList>
<a id="channel"></a>
<Parameter name="channel">

频道名称。

</Parameter>
<a id="uid-1"></a>
<Parameter name="uid">

用户 ID

</Parameter>
<a id="localproxyip"></a>
<Parameter name="localProxyIp">

预留参数，暂不支持。

</Parameter>
<a id="elapsed"></a>
<Parameter name="elapsed">

从调用 [joinChannel](/zh-CN/api-reference/rtc/flutter/channel#api_irtcengine_joinchannel2) 到 SDK 触发该回调的经过的时间（毫秒）。

</Parameter>
</ParameterList>

### 所属接口类 [#所属接口类-45]

- [RtcEngineEventHandler](/zh-CN/api-reference/rtc/flutter/rtc-interface-class#class_irtcengineeventhandler)

<a id="callback_irtcengineeventhandler_onremotesubscribefallbacktoaudioonly"></a>

<a id="ariaid-title48"></a>

## onRemoteSubscribeFallbackToAudioOnly [#onremotesubscribefallbacktoaudioonly]

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

<a id="callback_irtcengineeventhandler_onremotesubscribefallbacktoaudioonly__prototype"></a>

```dart
final void Function(int uid, bool isFallbackOrRecover)?
      onRemoteSubscribeFallbackToAudioOnly;
```

<a id="callback_irtcengineeventhandler_onremotesubscribefallbacktoaudioonly__detailed_desc"></a>

当你调用了 [setRemoteSubscribeFallbackOption](/zh-CN/api-reference/rtc/flutter/network#api_irtcengine_setremotesubscribefallbackoption) 并将 `option` 设置为 `streamFallbackOptionAudioOnly` 后，该回调会在下列情况时被触发：

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

:::note
注： 订阅流因弱网环境而回退为视频小流时，你可以通过 [onRemoteVideoStats](/zh-CN/api-reference/rtc/flutter/video/video-basic#callback_irtcengineeventhandler_onremotevideostats) 回调来监控远端视频大小流的切换。
:::

<a id="callback_irtcengineeventhandler_onremotesubscribefallbacktoaudioonly__parameters"></a>

### 参数 [#参数-34]

<ParameterList>
<a id="uid-2"></a>
<Parameter name="uid">

远端用户的用户 ID。

</Parameter>
<a id="isfallbackorrecover"></a>
<Parameter name="isFallbackOrRecover">

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

</Parameter>
</ParameterList>

### 所属接口类 [#所属接口类-46]

- [RtcEngineEventHandler](/zh-CN/api-reference/rtc/flutter/rtc-interface-class#class_irtcengineeventhandler)

<a id="callback_irtcengineeventhandler_onuplinknetworkinfoupdated"></a>

<a id="ariaid-title49"></a>

## onUplinkNetworkInfoUpdated [#onuplinknetworkinfoupdated]

上行网络信息变化回调。

<a id="callback_irtcengineeventhandler_onuplinknetworkinfoupdated__prototype"></a>

```dart
final void Function(UplinkNetworkInfo info)? onUplinkNetworkInfoUpdated;
```

<a id="callback_irtcengineeventhandler_onuplinknetworkinfoupdated__detailed_desc"></a>

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

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

<a id="callback_irtcengineeventhandler_onuplinknetworkinfoupdated__parameters"></a>

### 参数 [#参数-35]

<ParameterList>
<a id="info"></a>
<Parameter name="info">

上行网络信息，详见 [UplinkNetworkInfo](/zh-CN/api-reference/rtc/flutter/class-uplinknetworkinfo)。

</Parameter>
</ParameterList>

### 所属接口类 [#所属接口类-47]

- [RtcEngineEventHandler](/zh-CN/api-reference/rtc/flutter/rtc-interface-class#class_irtcengineeventhandler)