RTCPeerConnection: icecandidate event

在此页

描述
范例
规范
浏览器兼容性
另请参阅
相关话题

An icecandidate event is sent to an RTCPeerConnection when an RTCIceCandidate has been identified and added to the local peer by a call to RTCPeerConnection.setLocalDescription() . The event handler should transmit the candidate to the remote peer over the signaling channel so the remote peer can add it to its set of remote candidates.

冒泡	No
可取消	No
接口	`RTCPeerConnectionIceEvent`
事件处理程序特性	`RTCPeerConnection.onicecandidate`

描述

There are three reasons why the icecandidate event is fired on an RTCPeerConnection .

Sharing a new candidate

The majority of icecandidate events are fired to indicate that a new candidate has been gathered. This candidate needs to be delivered to the remote peer over the signaling channel your code manages.

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

The remote peer, upon receiving the candidate, will add the candidate to its candidate pool by calling addIceCandidate() , passing in the candidate string you have passed along using the signaling server.

Indicating the end of a generation of candidates

When an ICE negotiation session runs out of candidates to propose for a given RTCIceTransport , it has completed gathering for a generation of candidates. That this has occurred is indicated by an icecandidate event whose candidate string is empty ( "" ).

You should deliver this to the remote peer just like any standard candidate, as described under Sharing a new candidate above. This ensures that the remote peer is given the end-of-candidates notification as well. As you see in the code in the previous section, every candidate is sent to the other peer, including any that might have an empty candidate string. Only candidates for which the event's candidate 特性为 null are not forwarded across the signaling connection.

The end-of-candidates indication is described in section 9.3 of the Trickle ICE draft specification (note that the section number is subject to change as the specification goes through repeated drafts).

Indicating that ICE gathering is complete

Once all ICE transports have finished gathering candidates and the value of the RTCPeerConnection 对象的 iceGatheringState has made the transition to complete ， icecandidate event is sent with the value of complete 设为 null .

This signal exists for backward compatibility purposes and does not need to be delivered onward to the remote peer (which is why the code snippet above checks to see if event.candidate is null prior to sending the candidate along.

If you need to perform any special actions when there are no further candidates expected, you're much better off watching the ICE gathering state by watching for icegatheringstatechange 事件：

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;
  }
});

As you can see in this example, the icegatheringstatechange event lets you know when the value of the RTCPeerConnection property iceGatheringState has been updated. If that value is now complete , you know that ICE gathering has just ended.

This is a more reliable approach than looking at the individual ICE messages for one indicating that the ICE session is finished.

范例

This example creates a simple handler for the icecandidate event that uses a function called sendMessage() to create and send a reply to the remote peer through the signaling server.

First, an example using addEventListener() :

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

You can also set the onicecandidate event handler property directly:

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

规范

规范	状态	注释
WebRTC 1.0: Real-time Communication Between Browsers The definition of 'icecandidate' in that specification.	候选推荐

浏览器兼容性

The compatibility table on this page is generated from structured data. If you'd like to contribute to the data, please check out https://github.com/mdn/browser-compat-data and send us a pull request. 更新 GitHub 上的兼容性数据

	桌面						移动
	Chrome	Edge	Firefox	Internet Explorer	Opera	Safari	Android webview	Chrome for Android	Firefox for Android	Opera for Android	Safari on iOS	Samsung Internet
`icecandidate` event	Chrome 24	Edge 15	Firefox 22	IE No	Opera 43	Safari 11	WebView Android Yes	Chrome Android 25	Firefox Android 44	Opera Android 43	Safari iOS ?	Samsung Internet Android 6.0

在此页

描述

Sharing a new candidate

Indicating the end of a generation of candidates

Indicating that ICE gathering is complete

范例

规范

浏览器兼容性

图例

另请参阅

元数据

相关话题