RTCPeerConnection: icecandidate-Event
Baseline
Weitgehend verfügbar
Diese Funktion ist gut etabliert und funktioniert auf vielen Geräten und in vielen Browserversionen. Sie ist seit September 2017 browserübergreifend verfügbar.
Ein icecandidate-Ereignis wird an eine RTCPeerConnection gesendet, wenn:
- Ein
RTCIceCandidateidentifiziert und dem lokalen Peer durch einen Aufruf vonRTCPeerConnection.setLocalDescription()hinzugefügt wurde, - Jeder
RTCIceCandidate, der mit einer bestimmten Benutzernamen-Fragment- und Passwortkombination (eine Generation) korreliert ist, so identifiziert und hinzugefügt wurde, und - Alle ICE-Sammlungen auf allen Transportwegen abgeschlossen sind.
In den ersten beiden Fällen sollte der Event-Handler den Kandidaten über den Signalisierungskanal an den entfernten Peer übertragen, damit der entfernte Peer ihn zu seinem Satz von entfernten Kandidaten hinzufügen kann.
Dieses Ereignis kann nicht abgebrochen werden und bildet keine Blaseneffekte.
Syntax
Verwenden Sie den Ereignisnamen in Methoden wie addEventListener() oder setzen Sie eine Ereignishandler-Eigenschaft.
addEventListener("icecandidate", (event) => { })
onicecandidate = (event) => { }
Ereignistyp
Ein RTCPeerConnectionIceEvent. Erbt von Event.
Beschreibung
Es gibt drei Gründe, warum das icecandidate-Ereignis auf einer RTCPeerConnection ausgelöst wird.
Weitergabe eines neuen Kandidaten
Die Mehrheit der icecandidate-Ereignisse wird ausgelöst, um anzuzeigen, dass ein neuer Kandidat gesammelt wurde. Dieser Kandidat muss über den von Ihrem Code verwalteten Signalisierungskanal 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 nach Empfang des Kandidaten diesen durch Aufruf von addIceCandidate() seiner Kandidatenmenge hinzufügen, indem er den über den Signalisierungsserver übermittelten candidate-String übergibt.
Anzeige des Endes einer Generation von Kandidaten
Wenn eine ICE-Verhandlungssitzung keine weiteren Kandidaten für einen bestimmten RTCIceTransport vorschlagen kann, wurde 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 wie jeden Standardkandidaten weiterleiten, wie oben unter Weitergabe eines neuen Kandidaten beschrieben. Dies stellt sicher, dass der entfernte Peer ebenfalls die Benachrichtigung über das Ende der Kandidaten erhält. Wie Sie im Code im vorherigen Abschnitt sehen, wird jeder Kandidat an den anderen Peer gesendet, einschließlich aller, die möglicherweise einen leeren Kandidaten-String haben. Nur Kandidaten, für die die candidate-Eigenschaft des Ereignisses null ist, werden nicht über die Signalisierungsverbindung weitergeleitet.
Die Anzeige des Endes von Kandidaten wird in Abschnitt 9.3 des Trickle ICE-Entwurfs beschrieben (beachten Sie, dass sich die Abschnittsnummer ändern kann, während der Entwurf wiederholt durchläuft).
Anzeige, dass die ICE-Sammlung abgeschlossen ist
Sobald alle ICE-Transporte das Sammeln von Kandidaten abgeschlossen haben und der Wert des RTCPeerConnection-Objekts iceGatheringState auf complete übergegangen ist, wird ein icecandidate-Ereignis mit dem Wert von candidate auf null gesendet.
Dieses Signal existiert aus Gründen der Abwärtskompatibilität und muss nicht an den entfernten Peer weitergegeben werden (weshalb der obige Code-Schnipsel prüft, ob event.candidate null ist, bevor der Kandidat weitergeleitet wird).
Wenn Sie besondere Aktionen ausführen müssen, wenn keine weiteren Kandidaten zu erwarten sind, sollten Sie besser den ICE-Sammlungsstatus überwachen, 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 sich der Wert der [iceGatheringState]-Eigenschaft der RTCPeerConnection aktualisiert hat. Wenn dieser nun complete ist, wissen Sie, dass die ICE-Sammlung gerade beendet wurde.
Dies ist ein zuverlässigerer Ansatz, als auf die einzelnen ICE-Nachrichten zu schauen, die anzeigen, dass die ICE-Sitzung beendet ist.
Beispiele
Dieses Beispiel erstellt einen einfachen Handlers 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 unter Verwendung von addEventListener():
pc.addEventListener("icecandidate", (ev) => {
if (ev.candidate !== null) {
sendMessage({
type: "new-ice-candidate",
candidate: ev.candidate,
});
}
});
Sie können auch die onicecandidate-Ereignishandler-Eigenschaft direkt setzen:
pc.onicecandidate = (ev) => {
if (ev.candidate !== null) {
sendMessage({
type: "new-ice-candidate",
candidate: ev.candidate,
});
}
};
Spezifikationen
| Spezifikation |
|---|
| WebRTC: Real-Time Communication in Browsers # dom-rtcpeerconnection-onicecandidate |