RTCIceCandidatePairStats

WebRTC API 的 **RTCIceCandidatePairStats** 字典用于报告统计信息,这些信息可以深入了解连接的 RTCPeerConnection 的质量和性能,以及根据指定的 ICE 候选对进行配置的情况。

可以通过迭代 RTCPeerConnection.getStats() 返回的 RTCStatsReport,直到找到 type"candidate-pair" 的条目,从而获取统计信息。

实例属性

availableIncomingBitrate 可选

提供一个表示网络可用入站容量的值,方法是报告候选对的所有入站 RTP 流可用的总比特率。这不会考虑 IP 开销的大小,也不会考虑任何其他传输层,例如 TCPUDP

availableOutgoingBitrate 可选

提供一个信息性值,表示网络可用的出站容量,方法是报告候选对的所有出站 RTP 流可用的总比特率。这不会考虑 IP 开销的大小,也不会考虑任何其他传输层,例如 TCPUDP

bytesReceived 可选

迄今为止在此候选对上接收到的有效负载字节总数(即,接收到的总字节数减去任何标头、填充或其他管理开销)。

bytesSent 可选

迄今为止在此候选对上发送的有效负载字节总数(即,发送的总字节数减去任何标头、填充或其他管理开销)。

currentRoundTripTime 可选

一个浮点值,指示最近发送的 STUN 请求与收到响应之间经过的总时间(以秒为单位)。这可能是基于确认打开连接权限的请求。

lastPacketReceivedTimestamp 可选

一个 DOMHighResTimeStamp 值,指示本地对等体从此候选对的远程对等体接收最后一个数据包的时间。不会为 STUN 数据包记录时间戳。

lastPacketSentTimestamp 可选

一个 DOMHighResTimeStamp 值,指示本地对等体向此候选对的远程对等体发送最后一个数据包的时间。不会为 STUN 数据包记录时间戳。

localCandidateId 可选

RTCIceCandidateStats 对象中包含的数据(提供候选对本地候选的统计信息)中的 RTCIceCandidate 对应的唯一 ID 字符串。

nominated 可选

一个布尔值,如果为 true,则表示此对象描述的候选对是已提议用于的候选对,并且如果其优先级在已提名的候选对中最高,则将使用(或已使用)该候选对。有关详细信息,请参阅 RFC 5245,第 7.1.3.2.4 节

remoteCandidateId 可选

与远程候选对应的唯一 ID 字符串,从中提取数据以构建描述连接远程端的 RTCIceCandidateStats 对象。

requestsReceived 可选

已接收的连接检查请求总数,包括重传。此值包括连接检查和 STUN 同意检查。

requestsSent 可选

已发送的连接检查请求总数,包括重传。

responsesReceived 可选

已接收的连接检查响应总数。

responsesSent 可选

已发送的连接检查响应总数。这包括连接检查请求和 STUN 同意请求。

state 可选

一个字符串,指示两个候选之间连接的状态。

totalRoundTripTime 可选

一个浮点值,指示迄今为止在此候选对上发送 STUN 请求并接收其响应之间经过的总时间(以秒为单位)。这包括连接检查和同意检查请求。您可以通过将此值除以 responsesReceived 来计算平均往返时间 (RTT)。

transportId 可选

一个字符串,唯一标识用于检查以获取传输相关统计信息(如 RTCTransportStats 中所示)的 RTCIceTransport,这些统计信息用于生成此对象。

常用实例属性

以下属性对所有 WebRTC 统计信息对象都是通用的。

id

一个唯一标识正在监视以生成此统计信息集的对象的字符串。

timestamp

一个 DOMHighResTimeStamp 对象,指示为此统计信息对象获取样本的时间。

type

一个值为 "candidate-pair" 的字符串,指示对象包含的统计信息类型。

已弃用的属性

以下属性已从规范中移除,不再应该使用。您应尽快更新任何现有代码以避免使用它们。查看兼容性表格以了解哪些浏览器支持它们以及在哪些版本中支持。

priority 已弃用 可选 非标准

一个整数,表示候选对的优先级。

readable 已弃用 可选 非标准

一个布尔值,指示是否可以通过候选对描述的连接发送数据。

writable 已弃用 可选 非标准

一个布尔值,指示是否可以通过候选对描述的连接接收数据。

非标准属性

selected 非标准 可选

一个 Firefox 特定的布尔值,如果此对象描述的候选对是当前正在使用的候选对,则为 true。确定所选候选对的符合规范的方法是查找类型为 transport 的统计信息对象,它是一个RTCTransportStats 对象。该对象的selectedCandidatePairId 属性指示指定的传输是否正在使用。

使用说明

当前活动的 ICE 候选对(如果有)可以通过调用RTCIceTransport 方法getSelectedCandidatePair() 来获取,该方法返回一个RTCIceCandidatePair 对象,如果未选择任何对,则返回 null。活动候选对描述了RTCPeerConnection的两端的当前配置。

如果RTCIceTransport 执行 ICE 重启,则任何不是传输的活动候选对的候选对都将被删除,此时 ICE 传输的state 返回到 new,并且协商再次开始。有关更多信息,请参阅ICE 重启

示例

此示例计算连接检查之间经过的平均时间。

js
if (rtcStats && rtcStats.type === "candidate-pair") {
  let elapsed =
    (rtcStats.lastRequestTimestamp - rtcStats.firstRequestTimestamp) /
    rtcStats.requestsSent;

  console.log(`Average time between ICE connectivity checks: ${elapsed} ms.`);
}

代码首先查看 rtcStats 以查看其type 是否为 candidate-pair。如果是,则我们知道 rtcStats 实际上是一个 RTCIceCandidatePairStats 对象。然后,我们可以计算 STUN 连接检查之间经过的平均时间并记录该信息。

规范

规范
WebRTC 统计信息 API 的标识符
# dom-rtcstatstype-candidate-pair

浏览器兼容性

BCD 表格仅在浏览器中加载