网络及其他
介绍跟网络相关的方法以及其他方法和回调。
enableEncryption
开启或关闭内置加密。
public abstract enableEncryption(enabled: boolean, config: EncryptionConfig): number;
详情
在安全要求较高的场景下,建议你在加入频道前,调用本方法开启内置加密。
同一频道内所有用户必须使用相同的加密模式和密钥。用户离开频道后,SDK 会自动关闭加密。如需重新开启加密,你需要在用户再次加入频道前调用该方法。
参数
- enabled
- 是否开启内置加密:
- true: 开启内置加密。
- false:(默认)关闭内置加密。
- config
- 配置内置加密模式和密钥。详见 EncryptionConfig。
返回值
- 0: 方法调用成功。
- < 0: 方法调用失败
- -2: 调用了无效的参数。需重新指定参数。
- -4: 设置的加密模式不正确或加载外部加密库失败。需检查枚举值是否正确或重新加载外部加密库。
- -7: SDK 尚未初始化。需在调用 API 之前已创建 RtcEngine 对象并完成初始化。
getCallId
getCallIdEx
使用连接 ID 获取通话 ID。
public abstract getCallIdEx(connection:RtcConnection):string;
详情
客户端在每次加入频道后会生成一个对应的 callId,标识该客户端的此次通话。你可以调用该方法获取 callId 参数,然后在调用 、 等方法时填入。
参数
- connection
- Connection 信息。详见 RtcConnection。
getCurrentMonotonicTimeInMs
获取 SDK 当前的 Monotonic Time。
public abstract getCurrentMonotonicTimeInMs(): number;
详情
Monotonic Time 是指一个单调递增的时间序列,它的值会随着时间的推移而增加。单位为毫秒。
在自定义视频采集、自定义音频采集场景中,为确保音视频同步,声网建议你调用该方法获取 SDK 当前的 Monotonic Time 后,将该值传入采集的视频帧(VideoFrame)、音频帧(AudioFrame)的时间戳参数。
返回值
- ≥0: 方法调用成功,返回 SDK 当前的 Monotonic Time(毫秒)。
- < 0: 方法调用失败。详见错误码了解详情和解决建议。
getNativeHandle
setEncryptionMode
启用内置的加密方案。
public abstract setEncryptionMode(encryptionMode:string):number;
详情
SDK 支持内置加密方案,默认支持 AES-128-GCM。如需采用其他加密方案,可以调用本方法。同一频道内的所有用户必须设置相同的加密方式和 secret 才能进行通话。关于这几种加密方式的区别,请参考 AES 加密算法的相关资料。
参数
- encryptionMode
- 加密模式:
- "
aes-128-xts
": 128 位 AES 加密,XTS 模式; - "
aes-128-ecb
": 128 位 AES 加密,ECB 模式; - "
aes-256-xts
": 256 位 AES 加密,XTS 模式; - "
sm4-128-ecb
": 128 位 SM4 加密,ECB 模式; - "
aes-128-gcm
": 128 位 AES 加密,GCM 模式; - "
aes-256-gcm
": 256 位 AES 加密,GCM 模式; - "": 设置为空字符串时,默认使用加密方式 "
aes-128-gcm
"。
- "
返回值
- 0: 方法调用成功。
- < 0: 方法调用失败。详见错误码了解详情和解决建议。
setEncryptionSecret
启用内置加密,并设置数据加密密码。
public abstract setEncryptionSecret(secret:string):number;
详情
在加入频道之前, App 需调用该方法指定 secret 来启用内置的加密功能,同一频道内的所有用户应设置相同的 secret。 当用户离开频道时,该频道的 secret 会自动清除。如果未指定 secret 或将 secret 设置为空,则无法激活加密功能。
- 请不要在旁路推流时调用此方法。
- 为保证最佳传输效果,请确保加密后的数据大小不超过原始数据大小 + 16 字节。16 字节是 AES 通用加密模式下最大填充块大小。
参数
- secret
- 加密密码。
返回值
- 0: 方法调用成功。
- < 0: 方法调用失败。详见错误码了解详情和解决建议。
setLogFile
设置日志文件
public abstract setLogFile(filePath: string): number;
详情
logConfig
参数设置日志文件路径 。设置 SDK 的输出 log 文件。SDK 运行时产生的所有 log 将写入该文件。App 必须保证指定的目录存在而且可写。
如需调用本方法,请在调用 方法初始化 RtcEngine 对象后立即调用,否则输出日志可能不完整。
参数
- filePath
- 日志文件的完整路径。该日志文件为 UTF-8 编码。
返回值
- 0: 方法调用成功。
- < 0: 方法调用失败。详见错误码了解详情和解决建议。
setLogFileSize
设置 SDK 输出的日志文件的大小。
public abstract setLogFileSize(fileSizeInKBytes: number): number;
详情
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 会按照以下顺序对日志文件进行操作:- 删除
agorasdk.4.log
文件(如有)。 - 将
agorasdk.3.log
重命名为agorasdk.4.log
。 - 将
agorasdk.2.log
重命名为agorasdk.3.log
。 - 将
agorasdk.1.log
重命名为agorasdk.2.log
。 - 新建
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
设置日志输出等级。
public abstract setLogFilter(filter: Constants.LogFilter): number;
详情
该方法设置 SDK 的输出日志输出等级。不同的输出等级可以单独或组合使用。日志级别顺序依次为 OFF、CRITICAL、ERROR、WARN、INFO 和 DEBUG。 选择一个级别,你就可以看到在该级别之前所有级别的日志信息。
例如,你选择 WARN 级别,就可以看到在 CRITICAL、ERROR 和 WARN 级别的日志信息。
参数
- filter
日志过滤等级。
返回值
- 0: 方法调用成功。
- < 0: 方法调用失败。详见错误码了解详情和解决建议。
setParameters
startLastmileProbeTest
开始通话前网络质量探测。
public abstract startLastmileProbeTest(config: LastmileProbeConfig): number;
详情
开始通话前网络质量探测,向用户反馈上下行网络的带宽、丢包、网络抖动和往返时延数据。
- onLastmileQuality,视网络情况约 2 秒内返回。该回调通过打分反馈上下行网络质量,更贴近用户的主观感受。
- onLastmileProbeResult,视网络情况约 30 秒内返回。该回调通过具体数据反馈上下行网络质量,更加客观。
该方法需要在加入频道前调用,用于判断和预测目前的上行网络质量是否足够好。
- 调用该方法后,在收到 onLastmileQuality 和 onLastmileProbeResult 回调之前请不要调用其他方法,否则可能会由于 API 操作过于频繁导致此方法无法执行。
- 在直播场景中,如果本地用户为主播,请勿加入频道后调用该方法。
参数
- config
- Last mile 网络探测配置,详见 LastmileProbeConfig。
返回值
- 0: 方法调用成功。
- < 0: 方法调用失败。详见错误码了解详情和解决建议。
stopLastmileProbeTest
onConnectionLost
网络连接中断,且 SDK 无法在 10 秒内连接服务器回调。
onConnectionLost?:() => void;
详情
SDK 在调用 joinChannelWithOptions 后,无论是否加入成功,只要 10 秒和服务器无法连接就会触发该回调。如果 SDK 在断开连接后,20 分钟内还是没能重新加入频道,SDK 会停止尝试重连。
所属接口类onConnectionStateChanged
网络连接状态已改变回调。
onConnectionStateChanged ? : ( state: Constants.ConnectionState, reason: Constants.ConnectionChangedReason ) => void
详情
该回调在网络连接状态发生改变的时候触发,并告知用户当前的网络连接状态和引起网络状态改变的原因。
参数
- state
当前网络连接状态。
- DISCONNECTED (1):网络连接断开。
- CONNECTING (2):建立网络连接中。
- CONNECTED (3):网络已连接。
- RECONNECTING (4):重新建立网络连接中 。
- FAILED (5):网络连接失败 。
- reason
- CONNECTING (0):建立网络连接中。
- JOIN_SUCCESS (1):成功加入频道。
- INTERRUPTED (2):网络连接中断。
- BANNED_BY_SERVER (3):网络连接被服务器禁止,例如,当用户被踢出频道时,会返回该状态。
- JOIN_FAILED (4):加入频道失败。SDK 在尝试加入频道 20 分钟后仍未能加入频道,会返回该状态并不再尝试重连。请提示用户尝试切换网络后重新加入频道。
- LEAVE_CHANNEL (5):离开频道。
- INVALID_APP_ID (6):App ID 无效。请使用有效的 APP ID 重新加入频道,并确保你使用的 App ID 与在声网控制台生成的一致。
- INVALID_CHANNEL_NAME (7):频道名无效。请更换有效的频道名重新加入频道。有效的频道名为长度在 64 字节以内的字符串。以下为支持的字符集范围(共 89 个字符):
- 26 个小写英文字母 a~z
- 26 个大写英文字母 A~Z
- 10 个数字 0~9
- "!"、"#"、"$"、"%"、"&"、"("、")"、"+"、"-"、":"、";"、"<"、"="、"."、">"、"?"、"@"、"["、"]"、"^"、"_"、"{"、"}"、"|"、"~"、","
- INVALID_TOKEN (8):Token 无效。一般有以下原因:
- 你的项目启用了 App Certificate,但加入频道未使用 Token。
- 在调用 joinChannelWithOptions 加入频道时指定的用户 ID 与生成 Token 时传入的用户 ID 不一致。
- 生成的 Token 和加入频道使用的 Token 不一致。
- 当你的项目启用了 App Certificate 时,使用 Token 加入频道。
- 生成 Token 时指定的用户 ID 与加入频道时使用的用户 ID 一致,
- 生成的 Token 和加入频道使用的 Token 一致。
- TOKEN_EXPIRED (9):当前使用的 Token 已过期。请重新在你的服务端生成 Token,然后用新的 Token 重新加入频道。
- REJECTED_BY_SERVER (10):此用户被服务器禁止 。
- SETTING_PROXY_SERVER (11):由于设置了代理服务器,SDK 尝试重连 。
- RENEW_TOKEN (12):更新 Token 引起网络连接状态改变 。
- CLIENT_IP_ADDRESS_CHANGED (13):客户端 IP 地址变更。如多次收到该状态码,请提示用户更换网络后尝试重新加入频道。
- KEEP_ALIVE_TIMEOUT (14):SDK 和服务器连接保活超时,进入自动重连状态。
- REJOIN_SUCCESS (15):重新加入频道成功。
- LOST (16):SDK 和服务器失去连接。
- ECHO_TEST (17):连接状态变化由回声测试引起。
- CLIENT_IP_ADDRESS_CHANGED_BY_USER (18):本地 IP 地址被用户更改。
- SAME_UID_LOGIN (19):使用相同的 UID 从不同的设备加入同一频道。
- TOO_MANY_BROADCASTERS (20):频道内主播人数已达上限。
onEncryptionError
内置加密出错回调。
onEncryptionError?:(errorType:Constants.EncryptionError) => void;
详情
调用 enableEncryption 开启加密后, 如果发流端、收流端出现加解密出错,SDK 会触发该回调。
参数
- errorType
- 错误类型。
- INTERNAL_FAILURE (0): 内部原因。
- DECRYPTION_FAILURE (1): 媒体流解密错误。请确保接收端和发送端使用的加密模式或密钥一致。
- ENCRYPTION_FAILURE (2): 媒体流加密错误。
- DATASTREAM_DECRYPTION_FAILURE (3): 数据流解密错误。请确保接收端和发送端使用的加密模式或密钥一致。
- DATASTREAM_ENCRYPTION_FAILURE (4): 数据流加密错误。
onLastmileProbeResult
通话前网络上下行 Last mile 质量探测报告回调。
onLastmileProbeResult? : (result:LastmileProbeResult) => void;
详情
在调用 startLastmileProbeTest 之后,SDK 会在约 30 秒内返回该回调。
参数
- result
- 上下行 Last mile 质量探测结果。 详见: LastmileProbeResult。
onLastmileQuality
网络上下行 last mile 质量报告回调。
onLastmileQuality? : (quality:Constants.QualityType) => void;
详情
该回调描述本地用户在加入频道前的 last mile 网络探测的结果,其中 last mile 是指设备到声网边缘服务器的网络状态。
加入频道前,调用 startLastmileProbeTest 之后,SDK 触发该回调报告本地用户在加入频道前的 last mile 网络探测的结果。
参数
- quality
- Last mile 网络质量。
onNetworkQuality
通话中每个用户的网络上下行 last mile 质量报告回调。
onNetworkQuality? : (uid: number, txQuality: Constants.NetworkQuality, rxQuality: Constants.NetworkQuality) => void;
详情
该回调描述每个用户在通话中的 last mile 网络状态,其中 last mile 是指设备到声网边缘服务器的网络状态。
该回调每 2 秒触发一次。如果远端有多个用户,该回调每 2 秒会被触发多次。
该回调通过频道内的广播包反馈网络质量。过多的广播包可能引发广播风暴。为防止广播风暴导致频道内大量数据传输,该回调默认支持同时反馈最多 4 个远端主播的网络质量。
参数
- uid
用户 ID。表示该回调报告的是持有该 ID 的用户的网络质量。如果当 uid 为 0 时,返回的是本地用户的网络质量。
- txQuality
- 该用户的上行网络质量,基于发送码率、上行丢包率、平均往返时延和网络抖动计算。 该值代表当前的上行网络质量,帮助判断是否可以支持当前设置的视频编码属性。 假设上行码率是 1000 Kbps,那么支持直播场景下 640 × 480 的分辨率、15 fps 的帧率没有问题,但是支持 1280 × 720 的分辨率就会有困难。
- rxQuality
- 该用户的下行网络质量,基于下行网络的丢包率、平均往返延时和网络抖动计算。