# 网络及其他 (/zh-CN/api-reference/rtc/harmonyos/network)
> For AI agents: see the complete documentation index at [llms.txt](/llms.txt).
## enableEncryption [#enableencryption]
开启或关闭内置加密。
```ts
public abstract enableEncryption(enabled: boolean, config: EncryptionConfig): number;
```
用户离开频道后,SDK 会自动关闭加密。如需重新开启加密,你需要在用户再次加入频道前调用该方法。
### 适用场景 [#适用场景]
对安全要求较高的场景。
### 调用时机 [#调用时机]
该方法需要在加入频道前调用。
### 调用限制 [#调用限制]
- 同一频道内的所有用户在调用该方法时,必须设置相同的加密模式和密钥。
- 如果开启了内置加密,则不能使用旁路推流功能。
### 参数 [#参数]
是否开启内置加密:
- true: 开启内置加密。
- false:(默认)关闭内置加密。
配置内置加密模式和密钥。详见 [EncryptionConfig](/zh-CN/api-reference/rtc/harmonyos/class-encryptionconfig)。
### 返回值 [#返回值]
- 0: 方法调用成功。
- < 0: 方法调用失败
- -2: 调用了无效的参数。需重新指定参数。
- -4: 设置的加密模式不正确或加载外部加密库失败。需检查枚举值是否正确或重新加载外部加密库。
- -7: SDK 尚未初始化。需在调用 API 之前已创建 [RtcEngine](/zh-CN/api-reference/rtc/harmonyos/rtc-interface-class#class_irtcengine) 对象并完成初始化。
### 所属接口类 [#所属接口类]
- [RtcEngine](/zh-CN/api-reference/rtc/harmonyos/rtc-interface-class#class_irtcengine)
## enableEncryptionEx [#enableencryptionex]
开启或关闭内置加密。
```ts
public abstract enableEncryptionEx(enabled:boolean,config:EncryptionConfig,connection:RtcConnection):number;
```
用户离开频道后,SDK 会自动关闭加密。如需重新开启加密,你需要在用户再次加入频道前调用该方法。
### 适用场景 [#适用场景-1]
对安全要求较高的场景。
### 调用时机 [#调用时机-1]
该方法需要在加入频道前调用。
### 调用限制 [#调用限制-1]
- 同一频道内的所有用户在调用该方法时,必须设置相同的加密模式和密钥。
- 如果开启了内置加密,则不能使用旁路推流功能。
### 参数 [#参数-1]
是否开启内置加密:
- true: 开启内置加密。
- false:(默认)关闭内置加密。
配置内置加密模式和密钥。详见 [EncryptionConfig](/zh-CN/api-reference/rtc/harmonyos/class-encryptionconfig)。
Connection 信息。详见 [RtcConnection](/zh-CN/api-reference/rtc/harmonyos/class-rtcconnection)。
### 返回值 [#返回值-1]
- 0: 方法调用成功。
- < 0: 方法调用失败。详见[错误码](/zh-CN/api-reference/rtc/error-code)了解详情和解决建议。
## getCallId [#getcallid]
获取通话 ID。
```ts
public abstract getCallId(): string;
```
客户端在每次加入频道后会生成一个对应的 callId,标识该客户端的此次通话。
### 调用时机 [#调用时机-2]
该方法需要在加入频道后调用。
### 调用限制 [#调用限制-2]
无。
### 参数 [#参数-2]
输出参数,当前的通话 ID。
### 返回值 [#返回值-2]
### 所属接口类 [#所属接口类-1]
- [RtcEngine](/zh-CN/api-reference/rtc/harmonyos/rtc-interface-class#class_irtcengine)
## getCallIdEx [#getcallidex]
使用连接 ID 获取通话 ID。
```ts
public abstract getCallIdEx(connection:RtcConnection):string;
```
客户端在每次加入频道后会生成一个对应的 callId,标识该客户端的此次通话。
### 调用时机 [#调用时机-3]
该方法需要在加入频道后调用。
### 调用限制 [#调用限制-3]
无。
### 参数 [#参数-3]
Connection 信息。详见 [RtcConnection](/zh-CN/api-reference/rtc/harmonyos/class-rtcconnection)。
### 返回值 [#返回值-3]
### 所属接口类 [#所属接口类-2]
- [RtcEngineEx](/zh-CN/api-reference/rtc/harmonyos/rtc-interface-class#class_irtcengineex)
## getCurrentMonotonicTimeInMs [#getcurrentmonotonictimeinms]
获取 SDK 当前的 Monotonic Time。
```ts
public abstract getCurrentMonotonicTimeInMs(): number;
```
Monotonic Time 是指一个单调递增的时间序列,它的值会随着时间的推移而增加。单位为毫秒。
在自定义视频采集、自定义音频采集场景中,为确保音视频同步,声网建议你调用该方法获取 SDK 当前的 Monotonic Time 后,将该值传入采集的视频帧([VideoFrame](/zh-CN/api-reference/rtc/harmonyos/class-videoframe))、音频帧([AudioFrame](/zh-CN/api-reference/rtc/harmonyos/class-audioframe))的时间戳参数。
### 调用时机 [#调用时机-4]
加入频道前后均可调用。
### 调用限制 [#调用限制-4]
无。
### 返回值 [#返回值-4]
- ≥ 0: 方法调用成功,返回 SDK 当前的 Monotonic Time(毫秒)。
- < 0: 方法调用失败。详见[错误码](/zh-CN/api-reference/rtc/error-code)了解详情和解决建议。
### 所属接口类 [#所属接口类-3]
- [RtcEngine](/zh-CN/api-reference/rtc/harmonyos/rtc-interface-class#class_irtcengine)
## getErrorDescription [#geterrordescription]
获取警告或错误描述。
```ts
public static getErrorDescription(error: number): string {
return RtcEngineImpl.getErrorDescriptionInternal(error);
}
```
### 参数 [#参数-4]
SDK 报告的错误码。
### 返回值 [#返回值-5]
具体的错误描述。
### 所属接口类 [#所属接口类-4]
- [RtcEngine](/zh-CN/api-reference/rtc/harmonyos/rtc-interface-class#class_irtcengine)
## getNativeHandle [#getnativehandle]
获取 Native SDK 的 C++ 句柄。
```ts
public abstract getNativeHandle():bigint;
```
### 详情 [#详情]
该方法获取 Native SDK 引擎 的 C++ 句柄,用于包括注册音视频回调在内的特殊场景。
### 返回值 [#返回值-6]
SDK 引擎的 Native 句柄。
### 所属接口类 [#所属接口类-5]
- [RtcEngine](/zh-CN/api-reference/rtc/harmonyos/rtc-interface-class#class_irtcengine)
## getNtpWallTimeInMs [#getntpwalltimeinms]
获取当前的 NTP (网络时间协议) 时间。
```ts
public abstract getNtpWallTimeInMs():bigint;
```
### 详情 [#详情-1]
在实时合唱的场景中,特别是在各个接收端由于网络原因导致下行链路不一致的情况下,你可以调用该方法来获取当前的 NTP 时间作为基准时间,以对齐多个接收端的歌词和音乐,实现合唱同步。
### 返回值 [#返回值-7]
当前 NTP 时间的 Unix 时间戳 (毫秒)。
## getSdkVersion [#getsdkversion]
获取 SDK 版本。
```ts
public static getSdkVersion(): string {
return RtcEngineImpl.getRtcSdkVersion();
}
```
### 参数 [#参数-5]
### 返回值 [#返回值-8]
当前的 SDK 版本号。格式为字符串。
### 所属接口类 [#所属接口类-6]
- [RtcEngine](/zh-CN/api-reference/rtc/harmonyos/rtc-interface-class#class_irtcengine)
## setParameters [#setparameters]
SDK 的 JSON 配置信息,用于提供技术预览或特别定制功能。
```ts
public abstract setParameters(parameters: string): number;
```
### 参数 [#参数-6]
JSON 字符串形式的参数。
### 返回值 [#返回值-9]
- 0: 方法调用成功。
- < 0: 方法调用失败。详见[错误码](/zh-CN/api-reference/rtc/error-code)了解详情和解决建议。
### 所属接口类 [#所属接口类-7]
- [RtcEngine](/zh-CN/api-reference/rtc/harmonyos/rtc-interface-class#class_irtcengine)
## setRemoteSubscribeFallbackOption [#setremotesubscribefallbackoption]
设置弱网环境下订阅的音视频流回退选项。
```ts
public abstract setRemoteSubscribeFallbackOption(option:Constants.StreamFallbackOptions):number;
```
### 详情 [#详情-2]
网络不理想的环境下,实时通信音视频的质量会下降。你可以调用该方法并将 option 设置为 STREAM_FALLBACK_OPTION_VIDEO_STREAM_LOW 或 STREAM_FALLBACK_OPTION_AUDIO_ONLY,SDK 会在下行弱网且音视频质量严重受影响时,将视频流切换为小流或关闭视频流,从而保证音频质量。同时,SDK 会持续监控网络质量,并在网络质量改善时恢复订阅音视频流。
当订阅流回退为音频流或由音频流恢复为音视频流时,SDK 会触发 onRemoteSubscribeFallbackToAudioOnly 回调。
### 参数 [#参数-7]
订阅流的回退选项。
- STREAM_FALLBACK_OPTION_DISABLED (0): 网络条件较差时,不对音视频流作回退处理,但不能保证音视频流的质量。
- STREAM_FALLBACK_OPTION_VIDEO_STREAM_LOW (1):(默认)网络条件较差时,只接收视频小流(低分辨率、低码率视频流)。
- STREAM_FALLBACK_OPTION_AUDIO_ONLY (2): 网络条件较差时,先尝试只接收视频小流;如果因网络环境太差无法显示视频,则再回退到只接收订阅的音频流。
### 返回值 [#返回值-10]
- 0: 方法调用成功。
- < 0: 方法调用失败。详见[错误码](/zh-CN/api-reference/rtc/error-code)了解详情和解决建议。
## startLastmileProbeTest [#startlastmileprobetest]
开始通话前网络质量探测。
```ts
public abstract startLastmileProbeTest(config: LastmileProbeConfig): number;
```
开始通话前网络质量探测,向用户反馈上下行网络的带宽、丢包、网络抖动和往返时延数据。
### 调用时机 [#调用时机-5]
该方法需要在加入频道前调用,且在收到 onLastmileQuality 和 onLastmileProbeResult 回调之前请不要调用其他方法,否则可能会由于 API 操作过于频繁导致此方法无法执行。
### 调用限制 [#调用限制-5]
无。
### 相关回调 [#相关回调]
成功调用该方法后,SDK 会依次触发如下 2 个回调:
- [onLastmileQuality](/zh-CN/api-reference/rtc/harmonyos/network#callback_irtcengineeventhandler_onlastmilequality),视网络情况约 2 秒内返回。该回调通过打分反馈上下行网络质量,更贴近用户的主观感受。
- [onLastmileProbeResult](/zh-CN/api-reference/rtc/harmonyos/network#callback_irtcengineeventhandler_onlastmileproberesult),视网络情况约 30 秒内返回。该回调通过具体数据反馈上下行网络质量,更加客观。
### 参数 [#参数-8]
Last mile 网络探测配置,详见 [LastmileProbeConfig](/zh-CN/api-reference/rtc/harmonyos/class-lastmileprobeconfig)。
### 返回值 [#返回值-11]
- 0: 方法调用成功。
- < 0: 方法调用失败。详见[错误码](/zh-CN/api-reference/rtc/error-code)了解详情和解决建议。
### 所属接口类 [#所属接口类-8]
- [RtcEngine](/zh-CN/api-reference/rtc/harmonyos/rtc-interface-class#class_irtcengine)
## stopLastmileProbeTest [#stoplastmileprobetest]
停止通话前网络质量探测。
```ts
public abstract stopLastmileProbeTest(): number;
```
### 返回值 [#返回值-12]
- 0: 方法调用成功。
- < 0: 方法调用失败。详见[错误码](/zh-CN/api-reference/rtc/error-code)了解详情和解决建议。
### 所属接口类 [#所属接口类-9]
- [RtcEngine](/zh-CN/api-reference/rtc/harmonyos/rtc-interface-class#class_irtcengine)
## onConnectionLost [#onconnectionlost]
网络连接中断,且 SDK 无法在 10 秒内连接服务器回调。
```ts
onConnectionLost?:() => void;
```
### 详情 [#详情-3]
SDK 在调用 joinChannelWithOptions 后,无论是否加入成功,只要 10 秒和服务器无法连接就会触发该回调。如果 SDK 在断开连接后,20 分钟内还是没能重新加入频道,SDK 会停止尝试重连。
### 所属接口类 [#所属接口类-10]
- [IRtcEngineEventHandler](/zh-CN/api-reference/rtc/harmonyos/rtc-interface-class#class_irtcengineeventhandler)
## onConnectionStateChanged [#onconnectionstatechanged]
网络连接状态已改变回调。
```ts
onConnectionStateChanged ? : ( state: Constants.ConnectionState, reason: Constants.ConnectionChangedReason ) => void
```
### 详情 [#详情-4]
该回调在网络连接状态发生改变的时候触发,并告知用户当前的网络连接状态和引起网络状态改变的原因。
### 参数 [#参数-9]
当前网络连接状态。详见 [ConnectionState](/zh-CN/api-reference/rtc/harmonyos/enum-connectionstatetype)。
引起当前网络连接状态改变的原因。详见 [ConnectionChangedReason](/zh-CN/api-reference/rtc/harmonyos/enum-connectionchangedreasontype)。
### 所属接口类 [#所属接口类-11]
- [IRtcEngineEventHandler](/zh-CN/api-reference/rtc/harmonyos/rtc-interface-class#class_irtcengineeventhandler)
## onEncryptionError [#onencryptionerror]
内置加密出错回调。
```ts
onEncryptionError?:(errorType:Constants.EncryptionError) => void;
```
### 详情 [#详情-5]
调用 [enableEncryption](/zh-CN/api-reference/rtc/harmonyos/network#api_irtcengine_enableencryption) 开启加密后, 如果发流端、收流端出现加解密出错,SDK 会触发该回调。
### 参数 [#参数-10]
错误类型,详见 [EncryptionError](/zh-CN/api-reference/rtc/harmonyos/enum-encryptionerrortype)。
### 所属接口类 [#所属接口类-12]
- [IRtcEngineEventHandler](/zh-CN/api-reference/rtc/harmonyos/rtc-interface-class#class_irtcengineeventhandler)
## onLastmileProbeResult [#onlastmileproberesult]
通话前网络上下行 Last mile 质量探测报告回调。
```ts
onLastmileProbeResult? : (result:LastmileProbeResult) => void;
```
### 详情 [#详情-6]
在调用 [startLastmileProbeTest](/zh-CN/api-reference/rtc/harmonyos/network#api_irtcengine_startlastmileprobetest) 之后,SDK 会在约 30 秒内返回该回调。
### 参数 [#参数-11]
上下行 Last mile 质量探测结果。详见 [LastmileProbeResult](/zh-CN/api-reference/rtc/harmonyos/class-lastmileproberesult)。
### 所属接口类 [#所属接口类-13]
- [IRtcEngineEventHandler](/zh-CN/api-reference/rtc/harmonyos/rtc-interface-class#class_irtcengineeventhandler)
## onLastmileQuality [#onlastmilequality]
网络上下行 last mile 质量报告回调。
```ts
onLastmileQuality? : (quality:Constants.QualityType) => void;
```
### 详情 [#详情-7]
该回调描述本地用户在加入频道前的 last mile 网络探测的结果,其中 last mile 是指设备到声网边缘服务器的网络状态。
加入频道前,调用 [startLastmileProbeTest](/zh-CN/api-reference/rtc/harmonyos/network#api_irtcengine_startlastmileprobetest) 之后,SDK 触发该回调报告本地用户在加入频道前的 last mile 网络探测的结果。
### 参数 [#参数-12]
Last mile 网络质量。详见 [NetworkQuality](/zh-CN/api-reference/rtc/harmonyos/enum-qualitytype)。
### 所属接口类 [#所属接口类-14]
- [IRtcEngineEventHandler](/zh-CN/api-reference/rtc/harmonyos/rtc-interface-class#class_irtcengineeventhandler)
## onNetworkQuality [#onnetworkquality]
通话中每个用户的网络上下行 last mile 质量报告回调。
```ts
onNetworkQuality? : (uid: number, txQuality: Constants.NetworkQuality, rxQuality: Constants.NetworkQuality) => void;
```
### 详情 [#详情-8]
该回调描述每个用户在通话中的 last mile 网络状态,其中 last mile 是指设备到声网边缘服务器的网络状态。
该回调每 2 秒触发一次。如果远端有多个用户,该回调每 2 秒会被触发多次。
该回调通过频道内的广播包反馈网络质量。过多的广播包可能引发广播风暴。为防止广播风暴导致频道内大量数据传输,该回调默认支持同时反馈最多 4 个远端主播的网络质量。
:::note
注: 用户不发流时,txQuality 为 `UNKNOWN`;用户不收流时,rxQuality 为 `UNKNOWN`。
:::
### 参数 [#参数-13]
用户 ID。表示该回调报告的是持有该 ID 的用户的网络质量。如果当 uid 为 0 时,返回的是本地用户的网络质量。
该用户的上行网络质量,基于发送码率、上行丢包率、平均往返时延和网络抖动计算。 该值代表当前的上行网络质量,帮助判断是否可以支持当前设置的视频编码属性。 假设上行码率是 1000 Kbps,那么支持直播场景下 640 × 480 的分辨率、15 fps 的帧率没有问题,但是支持 1280 × 720 的分辨率就会有困难。详见 [NetworkQuality](/zh-CN/api-reference/rtc/harmonyos/enum-qualitytype)。
该用户的下行网络质量,基于下行网络的丢包率、平均往返延时和网络抖动计算。详见 [NetworkQuality](/zh-CN/api-reference/rtc/harmonyos/enum-qualitytype)。
### 所属接口类 [#所属接口类-15]
- [IRtcEngineEventHandler](/zh-CN/api-reference/rtc/harmonyos/rtc-interface-class#class_irtcengineeventhandler)
## onPermissionError [#onpermissionerror]
获取设备权限出错回调。
```ts
onPermissionError?:(permission:Constants.PermissionType) => void;
```
### 详情 [#详情-9]
无法获取设备权限时,SDK 会触发该回调,报告哪个设备的权限无法获取。
### 参数 [#参数-14]
设备权限类型。详见 [PermissionType](/zh-CN/api-reference/rtc/harmonyos/enum-permissiontype)。
### 所属接口类 [#所属接口类-16]
- [IRtcEngineEventHandler](/zh-CN/api-reference/rtc/harmonyos/rtc-interface-class#class_irtcengineeventhandler)