# 网络及其他 (/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)