RTCPeerConnection: icecandidate Ereignis
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.
Ein icecandidate
Ereignis wird an eine RTCPeerConnection
gesendet, wenn:
- Ein
RTCIceCandidate
erkannt und dem lokalen Teilnehmer hinzugefügt wurde durch einen Aufruf vonRTCPeerConnection.setLocalDescription()
, - Jeder
RTCIceCandidate
, der mit einem bestimmten Benutzernamen-Fragment und einer Passwortkombination (eine Generation) assoziiert ist, so identifiziert und hinzugefügt wurde, und - Das gesamte ICE-Sammeln auf allen Transporten abgeschlossen ist.
In den ersten beiden Fällen sollte der Ereignis-Handler den Kandidaten über den Signalisierungskanal an den entfernten Peer übermitteln, damit dieser ihn seinem Satz an entfernten Kandidaten hinzufügen kann.
Dieses Ereignis ist nicht abbrechbar und wird nicht gebubbelt.
Syntax
Verwenden Sie den Ereignisnamen in Methoden wie addEventListener()
oder setzen Sie eine Event-Handler-Eigenschaft.
addEventListener("icecandidate", (event) => {});
onicecandidate = (event) => {};
Ereignistyp
Ein RTCPeerConnectionIceEvent
. Erbt von Event
.
Ereigniseigenschaften
Ein RTCPeerConnectionIceEvent
, das ein Event
ist, implementiert auch die folgende Eigenschaft.
RTCPeerConnectionIceEvent.candidate
Nur lesbar-
Gibt den
RTCIceCandidate
an, der den mit dem Ereignis verbundenen Kandidaten enthält. Dies wird der leere String sein, wenn das Ereignis anzeigt, dass keine weiteren Kandidaten in dieser Generation erwartet werden, odernull
, wenn das gesamte ICE-Sammeln auf allen Transporten abgeschlossen ist.
Beschreibung
Es gibt drei Gründe, warum das icecandidate
Ereignis bei einer RTCPeerConnection
ausgelöst wird.
Teilen eines neuen Kandidaten
Die Mehrheit der icecandidate
Ereignisse wird ausgelöst, um anzuzeigen, dass ein neuer Kandidat gesammelt wurde. Dieser Kandidat muss über den Signalisierungskanal, den Ihr Code verwaltet, an den entfernten Peer übermittelt werden.
rtcPeerConnection.onicecandidate = (event) => {
if (event.candidate !== null) {
sendCandidateToRemotePeer(event.candidate);
} else {
/* there are no more candidates coming during this negotiation */
}
};
Der entfernte Peer wird, nachdem er den Kandidaten erhalten hat, den Kandidaten seinem Kandidatenpool hinzufügen, indem er addIceCandidate()
aufruft und den candidate
String übergibt, den Sie über den Signalisierungsserver weitergeleitet haben.
Anzeigen des Endes einer Kandidatengeneration
Wenn eine ICE-Verhandlungssitzung keine Kandidaten mehr vorschlagen kann für einen gegebenen RTCIceTransport
, hat sie das Sammeln für eine Generation von Kandidaten abgeschlossen. Dies wird durch ein icecandidate
Ereignis angezeigt, dessen candidate
String leer ist (""
).
Sie sollten dies an den entfernten Peer übermitteln, genauso wie jeden Standardkandidaten, wie oben unter Teilen eines neuen Kandidaten beschrieben. Dies stellt sicher, dass der entfernte Peer ebenfalls die End-of-Candidates-Benachrichtigung erhält. Wie Sie im Code im vorherigen Abschnitt sehen, wird jeder Kandidat an den anderen Peer gesendet, einschließlich solcher, die möglicherweise einen leeren Kandidatenstring haben. Nur Kandidaten, für die die Eigenschaft candidate
des Ereignisses null
ist, werden nicht über die Signalisierungsverbindung weitergeleitet.
Die End-of-Candidates-Anzeige wird in Abschnitt 9.3 des Trickle ICE Entwurfsspezifikations beschrieben (beachten Sie, dass sich die Abschnittsnummer ändern kann, da die Spezifikation durch wiederholte Entwürfe geht).
Anzeigen, dass das ICE-Sammeln abgeschlossen ist
Sobald alle ICE-Transporte das Sammeln von Kandidaten beendet haben und der Wert des RTCPeerConnection
Objekts iceGatheringState
den Übergang zu complete
gemacht hat, wird ein icecandidate
Ereignis mit dem Wert candidate
auf null
gesetzt gesendet.
Dieses Signal existiert aus Gründen der Abwärtskompatibilität und muss nicht an den entfernten Peer weitergeleitet werden (weshalb der oben gezeigte Code überprüft, ob event.candidate
null
ist, bevor der Kandidat weitergesendet wird).
Wenn Sie besondere Aktionen ausführen müssen, wenn keine weiteren Kandidaten erwartet werden, ist es viel besser, den Status des ICE-Sammelns zu beobachten, indem Sie auf icegatheringstatechange
Ereignisse achten:
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;
}
});
Wie Sie in diesem Beispiel sehen, lässt Sie das icegatheringstatechange
Ereignis wissen, wann der Wert der RTCPeerConnection
Eigenschaft iceGatheringState
aktualisiert wurde. Wenn dieser Wert jetzt complete
ist, wissen Sie, dass das ICE-Sammeln gerade beendet wurde.
Dies ist ein zuverlässigerer Ansatz, als die einzelnen ICE-Meldungen auf eine zu überprüfen, die anzeigt, dass die ICE-Sitzung beendet ist.
Beispiele
Dieses Beispiel erstellt einen einfachen Handler für das icecandidate
Ereignis, der eine Funktion namens sendMessage()
verwendet, um eine Antwort an den entfernten Peer über den Signalisierungsserver zu erstellen und zu senden.
Zuerst ein Beispiel mit addEventListener()
:
pc.addEventListener(
"icecandidate",
(ev) => {
if (ev.candidate !== null) {
sendMessage({
type: "new-ice-candidate",
candidate: ev.candidate,
});
}
},
false,
);
Sie können auch die onicecandidate
Event-Handler-Eigenschaft direkt setzen:
pc.onicecandidate = (ev) => {
if (ev.candidate !== null) {
sendMessage({
type: "new-ice-candidate",
candidate: ev.candidate,
});
}
};
Spezifikationen
Specification |
---|
WebRTC: Real-Time Communication in Browsers # dom-rtcpeerconnection-onicecandidate |
Browser-Kompatibilität
BCD tables only load in the browser