RTCIceTransport.state — Eigenschaft · JavaScript-Referenz

Signatur

RTCIceTransport.state

Beschreibung

Die schreibgeschützte Eigenschaft state von RTCIceTransport zeigt an, in welcher Phase der ICE-Agent (Interactive Connectivity Establishment) für genau diesen Transport gerade steckt. Sie liefert einen Wert aus der Aufzählung RTCIceTransportState:

"new": Der Agent sammelt Kandidaten oder wartet auf entfernte Kandidaten. Es wurde noch nichts geprüft.
"checking": Mindestens ein entfernter Kandidat ist bekannt, und Kandidatenpaare werden geprüft. Eine passende Verbindung wurde noch nicht gefunden.
"connected": Ein funktionierendes Kandidatenpaar ist gefunden. Die Prüfung weiterer Paare kann noch laufen.
"completed": Die Sammlung ist abgeschlossen, alle Paare sind geprüft, und eine Verbindung besteht.
"disconnected": Die Verbindung ist vorübergehend unterbrochen, etwa durch fehlende Konnektivitätsprüfungen. Oft erholt sie sich von selbst.
"failed": Alle Kandidatenpaare sind gescheitert. Ohne einen ICE-Neustart ist keine Verbindung möglich.
"closed": Der Transport ist geschlossen und reagiert nicht mehr auf STUN-Anfragen.

Den Transport erreichen Sie über RTCRtpSender.transport.iceTransport, RTCRtpReceiver.transport.iceTransport oder RTCSctpTransport.transport.iceTransport (für Datenkanäle). Wenn sich der Wert ändert, löst der Transport das Ereignis statechange aus. Sie können es mit addEventListener("statechange", …) oder über die Eigenschaft onstatechange abfangen.

Im Gegensatz zu RTCPeerConnection.iceConnectionState, das den Status aller Transporte zusammenfasst, liefert state den Status eines einzelnen Transports. Bei gebündelten Verbindungen (bundlePolicy: "max-bundle") gibt es meist nur einen Transport. Ohne Bündelung kann jeder Medienstrom einen eigenen Transport mit eigenem Status haben.

Rückgabewert

Typ

Beschreibung

Ein String aus der Aufzählung RTCIceTransportState, der den aktuellen ICE-Status dieses Transports beschreibt.

Beispiele

Status des ICE-Transports eines Senders auslesen

const pc = new RTCPeerConnection({ iceServers: [{ urls: 'stun:stun.l.google.com:19302' }] });
const stream = await navigator.mediaDevices.getUserMedia({ audio: true });
const sender = pc.addTrack(stream.getAudioTracks()[0], stream);

const offer = await pc.createOffer();
await pc.setLocalDescription(offer);

// transport ist erst nach setLocalDescription verfügbar
const iceTransport = sender.transport?.iceTransport;
console.log('ICE-Status:', iceTransport?.state);

ICE-Status: new

Statuswechsel mit addEventListener überwachen

const watchIce = (iceTransport, label) => {
  const onChange = () => {
    console.log(`[${label}] ICE-Status: ${iceTransport.state}`);
    if (iceTransport.state === 'closed') {
      iceTransport.removeEventListener('statechange', onChange);
    }
  };
  iceTransport.addEventListener('statechange', onChange);
};

// nach setLocalDescription/setRemoteDescription:
const [sender] = pc.getSenders();
if (sender?.transport) watchIce(sender.transport.iceTransport, 'audio');

[audio] ICE-Status: checking [audio] ICE-Status: connected [audio] ICE-Status: completed

Automatischer ICE-Neustart bei "failed" (onstatechange)

const iceTransport = pc.sctp?.transport.iceTransport; // Transport des Datenkanals

let disconnectTimer;
iceTransport.onstatechange = () => {
  switch (iceTransport.state) {
    case 'disconnected':
      // kurz warten, oft erholt sich die Verbindung selbst
      disconnectTimer = setTimeout(() => {
        if (iceTransport.state === 'disconnected') pc.restartIce();
      }, 5000);
      break;
    case 'failed':
      console.warn('ICE fehlgeschlagen – starte Neustart');
      pc.restartIce(); // löst negotiationneeded aus
      break;
    case 'connected':
    case 'completed':
      clearTimeout(disconnectTimer);
      break;
  }
};

ICE fehlgeschlagen – starte Neustart

// Wichtig · Fallstricke

Browser-Kompatibilität: Chromium-Browser und Safari unterstützen RTCIceTransport. Firefox unterstützt es bisher nicht; dort ist sender.transport bzw. transport.iceTransport nicht verfügbar. Als Ausweichlösung dienen RTCPeerConnection.iceConnectionState und das Ereignis iceconnectionstatechange.
sender.transport ist null, solange noch keine lokale oder entfernte Beschreibung gesetzt ist. Prüfen Sie den Wert daher vor dem Zugriff, z. B. mit optionaler Verkettung (?.).
"disconnected" ist oft nur vorübergehend, etwa beim Wechsel des WLANs. Starten Sie ICE nicht sofort neu, sondern warten Sie eine kurze Frist ab. Bei "failed" hilft nur restartIce() oder ein neues Angebot mit iceRestart: true.
Der Status ist nicht dasselbe wie gatheringState: Dieser beschreibt nur das Sammeln lokaler Kandidaten, nicht die Konnektivität.
Ohne Bündelung kann es mehrere Transporte mit unterschiedlichem Status geben. Überwachen Sie dann jeden einzeln oder nutzen Sie den zusammengefassten Status der RTCPeerConnection.

Siehe auch

RTCIceTransport RTCIceTransport.gatheringState RTCPeerConnection.iceConnectionState RTCPeerConnection.restartIce() RTCDtlsTransport.iceTransport CSPViolationReport.statusCode