RTCPeerConnection.connectionState — Eigenschaft · JavaScript-Referenz

Signatur

RTCPeerConnection.connectionState

Beschreibung

Die Eigenschaft connectionState einer RTCPeerConnection fasst den Zustand aller Transportwege der Verbindung in einem einzigen Wert zusammen. Dazu gehören die ICE-Transporte und die DTLS-Transporte. Für Anwendungen ist das meist der wichtigste Wert, um festzustellen, ob Medien oder Datenkanäle tatsächlich übertragen werden können.

Mögliche Werte:

"new": Mindestens ein Transport ist im Zustand new, und keiner hat bisher angefangen, eine Verbindung aufzubauen. Außerdem sind alle anderen Transporte new oder closed, oder es gibt noch gar keine Transporte.
"connecting": Mindestens ein Transport baut gerade eine Verbindung auf oder führt die Prüfungen dafür durch.
"connected": Alle Transporte, die in Gebrauch sind, sind verbunden (connected bzw. completed) oder geschlossen.
"disconnected": Mindestens ein Transport hat die Verbindung verloren. Das ist oft nur vorübergehend, zum Beispiel beim Wechsel des Netzwerks.
"failed": Mindestens ein Transport ist endgültig gescheitert. Ohne einen ICE-Neustart erholt sich die Verbindung nicht mehr.
"closed": Die Verbindung wurde mit close() geschlossen.

Änderungen am Zustand werden über das Ereignis connectionstatechange gemeldet. Du kannst es mit pc.addEventListener("connectionstatechange", handler) oder über die Eigenschaft pc.onconnectionstatechange abonnieren. Typische Einsatzfälle sind Statusanzeigen in der Oberfläche („Verbinde…“, „Verbunden“), das automatische Wiederverbinden und das Aufräumen von Ressourcen, wenn ein Anruf endet.

Rückgabewert

Typ

Beschreibung

Ein String aus der Aufzählung RTCPeerConnectionState, der den aktuellen Gesamtzustand der Verbindung angibt.

Beispiele

Aktuellen Zustand auslesen

const pc = new RTCPeerConnection();
console.log(pc.connectionState);

pc.close();
console.log(pc.connectionState);

new closed

Statusanzeige über connectionstatechange

const pc = new RTCPeerConnection({
  iceServers: [{ urls: "stun:stun.l.google.com:19302" }]
});

const labels = {
  new: "Bereit",
  connecting: "Verbinde …",
  connected: "Verbunden",
  disconnected: "Verbindung unterbrochen",
  failed: "Verbindung fehlgeschlagen",
  closed: "Beendet"
};

const onStateChange = () => {
  console.log(`Status: ${labels[pc.connectionState]}`);
};

pc.addEventListener("connectionstatechange", onStateChange);

// Später, z. B. beim Verlassen der Seite:
// pc.removeEventListener("connectionstatechange", onStateChange);

Status: Verbinde … Status: Verbunden

Automatischer ICE-Neustart bei Fehler

// signaling ist ein eigenes Objekt, z. B. ein WebSocket-Wrapper
const watchConnection = (pc, signaling) => {
  let timer = null;

  pc.onconnectionstatechange = async () => {
    switch (pc.connectionState) {
      case "disconnected":
        // Kurz abwarten, oft erholt sich die Verbindung von selbst
        timer = setTimeout(() => pc.restartIce(), 5000);
        break;
      case "failed": {
        clearTimeout(timer);
        const offer = await pc.createOffer({ iceRestart: true });
        await pc.setLocalDescription(offer);
        signaling.send({ type: "offer", sdp: pc.localDescription });
        break;
      }
      case "connected":
        clearTimeout(timer);
        break;
      case "closed":
        clearTimeout(timer);
        pc.onconnectionstatechange = null;
        break;
    }
  };
};

// Wichtig · Fallstricke

Schreibgeschützt: Wenn du der Eigenschaft einen Wert zuweist, passiert nichts (im Strict Mode wird ein TypeError ausgelöst). Den Zustand änderst du nur indirekt, zum Beispiel über close() oder restartIce().
disconnected ist nicht endgültig: Die Verbindung kann von selbst wieder zu connected zurückkehren. Beende einen Anruf deshalb nicht sofort, sondern warte eine Karenzzeit ab. Erst failed braucht einen ICE-Neustart.
Kein Ereignis bei close(): Wenn du selbst pc.close() aufrufst, wird connectionstatechange in der Regel nicht ausgelöst. Räume in diesem Fall direkt nach dem Aufruf auf.
Unterschied zu iceConnectionState: connectionState berücksichtigt zusätzlich den DTLS-Transport. Damit ist es aussagekräftiger dafür, ob wirklich verschlüsselte Daten fließen können.
Kompatibilität: Firefox unterstützt die Eigenschaft erst ab Version 113. In sehr alten Browsern ist sie nicht vorhanden. Als Rückfalllösung dient iceConnectionState, zum Beispiel so: pc.connectionState ?? pc.iceConnectionState.

Siehe auch

RTCPeerConnection RTCPeerConnection.iceConnectionState RTCPeerConnection.signalingState RTCPeerConnection.prototype.restartIce() RTCPeerConnection.prototype.close() PerformanceScriptTiming.sourceFunctionName