RTCPeerConnection: iceconnectionstatechange 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 iceconnectionstatechange Ereignis wird an ein RTCPeerConnection-Objekt gesendet, jedes Mal, wenn sich der ICE-Verbindungszustand während des Verhandlungsprozesses ändert. Der neue ICE-Verbindungszustand ist in der iceConnectionState-Eigenschaft des Objekts verfügbar.

Eine häufig durchgeführte Aufgabe des iceconnectionstatechange Event-Listeners ist das Auslösen eines ICE-Restarts, wenn sich der Zustand auf failed ändert.

Dieses Ereignis ist nicht abbrechbar und wird nicht gebubbelt.

Syntax

Verwenden Sie den Ereignisnamen in Methoden wie addEventListener() oder setzen Sie eine Ereignishandler-Eigenschaft.

js
addEventListener("iceconnectionstatechange", (event) => {});

oniceconnectionstatechange = (event) => {};

Ereignistyp

Ein generisches Event.

Nutzungshinweise

Ein erfolgreicher Verbindungsversuch beginnt typischerweise im Zustand new, wechselt dann zu checking, dann connected und schließlich zu completed. Unter bestimmten Umständen kann der Zustand connected übersprungen werden, wodurch die Verbindung direkt vom Zustand checking zu completed wechselt. Dies kann geschehen, wenn nur der zuletzt geprüfte Kandidat erfolgreich ist und sowohl die Signalsammlung als auch das Ende der Kandidaten stattfinden, bevor die erfolgreiche Verhandlung abgeschlossen ist.

ICE-Verbindungszustand während ICE-Restarts

Wenn ein ICE-Restart verarbeitet wird, wird der Sammlung- und Konnektivitätsprüfprozess von vorne begonnen, was dazu führt, dass der iceConnectionState zu connected wechselt, wenn der ICE-Restart im completed-Zustand ausgelöst wurde. Wenn der ICE-Restart im temporären disconnected-Zustand eingeleitet wird, wechselt der Zustand stattdessen zu checking, was im Wesentlichen anzeigt, dass die Verhandlung ignoriert, dass die Verbindung vorübergehend verloren gegangen war.

Zustandsübergänge, wenn die Verhandlung endet

Wenn im Verhandlungsprozess keine weiteren Kandidaten mehr zu prüfen sind, wechselt die ICE-Verbindung in einen von zwei Zuständen. Wenn keine geeigneten Kandidaten gefunden wurden, wechselt der Zustand zu failed. Wenn mindestens ein geeigneter Kandidat erfolgreich identifiziert wurde, wechselt der Zustand zu completed. Die ICE-Schicht trifft diese Entscheidung beim Empfang des Endes der Kandidaten-Signals, das durch Aufrufen von addIceCandidate() mit einem Kandidaten bereitgestellt wird, dessen candidate-Eigenschaft ein leerer String ("") ist, oder durch Setzen der RTCPeerConnection-Eigenschaft canTrickleIceCandidates auf false.

Beispiele

Ein Event-Handler für dieses Ereignis kann durch die oniceconnectionstatechange-Eigenschaft oder durch Verwendung von addEventListener() auf der RTCPeerConnection hinzugefügt werden.

In diesem Beispiel wird ein Handler für iceconnectionstatechange eingerichtet, um einen Anrufstatus-Anzeiger zu aktualisieren, indem der Wert von iceConnectionState verwendet wird, um eine Zeichenfolge zu erstellen, die dem Namen einer CSS-Klasse entspricht, die wir dem Statusanzeiger zuweisen können, um ihn den aktuellen Zustand der Verbindung widerspiegeln zu lassen.

js
pc.addEventListener(
  "iceconnectionstatechange",
  (ev) => {
    let stateElem = document.querySelector("#call-state");
    stateElem.className = `${pc.iceConnectionState}-state`;
  },
  false,
);

Dies kann auch so geschrieben werden:

js
pc.oniceconnectionstatechange = (ev) => {
  let stateElem = document.querySelector("#call-state");
  stateElem.className = `${pc.iceConnectionState}-state`;
};

Spezifikationen

Specification
WebRTC: Real-Time Communication in Browsers
# dom-rtcpeerconnection-oniceconnectionstatechange

Browser-Kompatibilität

BCD tables only load in the browser

Siehe auch