RTCPeerConnection: icecandidate 事件

在 addEventListener() 等方法中使用事件名称，或设置事件处理程序属性。

addEventListener("icecandidate", (event) => {});

onicecandidate = (event) => {};

一个 RTCPeerConnectionIceEvent。继承自 Event。

RTCPeerConnectionIceEvent 是一个 Event，因此此事件还实现以下属性.

RTCPeerConnectionIceEvent.candidate 只读

指示包含与事件关联的候选者的 RTCIceCandidate。如果事件指示此生成中没有更多候选者，则此值为空字符串 ("")，如果所有传输上的所有 ICE 收集都已完成，则此值为 null。

在 RTCPeerConnection 上触发 icecandidate 事件有三个原因。

大多数 icecandidate 事件都会触发，以指示已收集到一个新候选者。此候选者需要通过您管理的信令通道传递给远程对等体。

rtcPeerConnection.onicecandidate = (event) => {
  if (event.candidate !== null) {
    sendCandidateToRemotePeer(event.candidate);
  } else {
    /* there are no more candidates coming during this negotiation */
  }
};

远程对等体在收到候选者后，会通过调用 addIceCandidate() 将候选者添加到其候选者池中，并将您使用信令服务器传递的 candidate 字符串作为参数传入。

当 ICE 协商会话为给定 RTCIceTransport 用尽要提出的候选者时，它会完成对一生成候选者的收集。发生这种情况的标志是一个 icecandidate 事件，其 candidate 字符串为空 ("")。

您应该像任何标准候选者一样将此传递给远程对等体，如上文 共享新候选者 中所述。这样可以确保远程对等体也能收到候选者结束通知。正如您在上一节代码中看到的，每个候选者都会发送给另一个对等体，包括任何可能具有空候选者字符串的候选者。仅当事件的 candidate 属性为 null 时，候选者才不会通过信令连接转发。

候选者结束指示在 Trickle ICE 草案规范的第 9.3 节 中进行了描述（请注意，该节号可能会随着规范经过反复草案而发生变化）。

一旦所有 ICE 传输完成候选者的收集，并且 RTCPeerConnection 对象的 iceGatheringState 属性值已过渡到 complete，则会发送一个 icecandidate 事件，其 candidate 值设置为 null。

此信号是为了向后兼容而存在的，不需要继续传递给远程对等体（这就是上面的代码片段在将候选者转发之前检查 event.candidate 是否为 null 的原因）。

如果您需要在不再预期有更多候选者时执行任何特殊操作，最好通过监视 icegatheringstatechange 事件来监视 ICE 收集状态

pc.addEventListener("icegatheringstatechange", (ev) => {
  switch (pc.iceGatheringState) {
    case "new":
      /* gathering is either just starting or has been reset */
      break;
    case "gathering":
      /* gathering has begun or is ongoing */
      break;
    case "complete":
      /* gathering has ended */
      break;
  }
});

如您在此示例中看到的那样，icegatheringstatechange 事件可以让您知道何时 RTCPeerConnection 属性 iceGatheringState 的值已更新。如果该值现在是 complete，则表示 ICE 收集刚刚结束。

这比查看指示 ICE 会话已结束的单个 ICE 消息更可靠。

此示例创建了一个简单的 icecandidate 事件处理程序，它使用名为 sendMessage() 的函数通过信令服务器创建并发送对远程对等体的回复。

首先，使用 addEventListener() 的示例

pc.addEventListener(
  "icecandidate",
  (ev) => {
    if (ev.candidate !== null) {
      sendMessage({
        type: "new-ice-candidate",
        candidate: ev.candidate,
      });
    }
  },
  false,
);

您也可以直接设置 onicecandidate 事件处理程序属性

pc.onicecandidate = (ev) => {
  if (ev.candidate !== null) {
    sendMessage({
      type: "new-ice-candidate",
      candidate: ev.candidate,
    });
  }
};

• WebRTC API
• 信令和视频通话