RTCPeerConnection: icecandidate event
Baseline Widely available
This feature is well established and works across many devices and browser versions. It’s been available across browsers since January 2020.
Событие icecandidate
отправляется RTCPeerConnection
когда RTCIceCandidate
был идентифицирован и добавлен к локальному клиенту (local peer) через вызов RTCPeerConnection.setLocalDescription()
. Обработчик события должен передать кандидата удалённому клиенту (remote peer) по каналу сигнализации (signaling channel), чтобы удалённый клиент (remote peer) смог добавить его в свой набор удалённых кандидатов (remote candidates).
Всплывает | Нет |
---|---|
Отменяемое | Нет |
Интерфейс | RTCPeerConnectionIceEvent |
Название обработчика событий | RTCPeerConnection.onicecandidate |
Описание
Существует три причины, по которым событие icecandidate
происходит (fired) у RTCPeerConnection
.
Делимся (Sharing) новым кандидатом
В основном события icecandidate
происходят, чтобы указать, что новый кандидат был построен (gathered). Этого кандидата нужно доставить удалённому клиенту (remote peer) через канал сигнализации (signaling channel), которым управляет ваш код.
rtcPeerConnection.onicecandidate = (event) => {
if (event.candidate) {
sendCandidateToRemotePeer(event.candidate);
} else {
/* there are no more candidates coming during this negotiation */
}
};
Удалённый клиент (peer), получив кандидата, добавит этого кандидата в свой пул кандидатов, используя вызов addIceCandidate()
, передавая в candidate
строку, которую вы передали с помощью сервера сигнализации (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
property is 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
object's iceGatheringState
has made the transition to complete
, an icecandidate
event is sent with the value of complete
set to 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
events:
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.
Examples
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,
});
}
};
Спецификации
Specification |
---|
WebRTC: Real-Time Communication in Browsers # dom-rtcpeerconnection-onicecandidate |
Совместимость с браузерами
BCD tables only load in the browser