RTCPeerConnection.iceGatheringState — Eigenschaft · JavaScript-Referenz

Signatur

RTCPeerConnection.iceGatheringState

Beschreibung

Die Eigenschaft iceGatheringState zeigt, wie weit der ICE-Agent einer RTCPeerConnection beim Sammeln von ICE-Kandidaten ist. ICE-Kandidaten sind mögliche Netzwerkpfade, also lokale Host-Adressen, über STUN ermittelte öffentliche Adressen (server-reflexive) und TURN-Relay-Adressen. Über diese Pfade versuchen die beiden Seiten, eine Verbindung aufzubauen.

Mögliche Werte:

"new": Die Verbindung wurde gerade erstellt, und es hat noch kein Sammeln stattgefunden. Das gilt auch, wenn es noch keine Transporte gibt.
"gathering": Der ICE-Agent sammelt gerade Kandidaten.
"complete": Das Sammeln ist abgeschlossen. Es kann wieder auf "gathering" wechseln, wenn z. B. ein ICE-Neustart oder eine neue Schnittstelle neues Sammeln auslöst.

Jede Änderung löst das Ereignis icegatheringstatechange aus. Nützlich ist das vor allem ohne Trickle ICE: Man wartet auf "complete" und schickt erst dann die vollständige SDP-Beschreibung aus localDescription mit allen Kandidaten über den Signalisierungskanal. Mit Trickle ICE wertet man stattdessen meist das Ereignis icecandidate aus.

Wichtig: Diese Eigenschaft sagt nur etwas über das Sammeln der Kandidaten aus, nicht über die Verbindung selbst. Den Verbindungsstatus liefern iceConnectionState bzw. connectionState.

Rückgabewert

Typ

"new" | "gathering" | "complete"

Beschreibung

Ein String aus der Aufzählung RTCIceGatheringState, der den aktuellen Sammelstatus beschreibt.

Beispiele

Status abfragen und Änderungen verfolgen

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

console.log('Start:', pc.iceGatheringState);

pc.addEventListener('icegatheringstatechange', () => {
  console.log('Sammelstatus:', pc.iceGatheringState);
});

// Ein Datenkanal sorgt dafür, dass beim Erstellen des Angebots ein Transport entsteht
pc.createDataChannel('chat');
const offer = await pc.createOffer();
await pc.setLocalDescription(offer); // startet das Sammeln

Start: new Sammelstatus: gathering Sammelstatus: complete

Ohne Trickle ICE: auf vollständiges Sammeln warten

const waitForGatheringComplete = (pc, timeoutMs = 5000) =>
  new Promise((resolve) => {
    if (pc.iceGatheringState === 'complete') return resolve();
    const timer = setTimeout(done, timeoutMs); // Sicherheitsnetz
    function done() {
      clearTimeout(timer);
      pc.removeEventListener('icegatheringstatechange', check);
      resolve();
    }
    function check() {
      if (pc.iceGatheringState === 'complete') done();
    }
    pc.addEventListener('icegatheringstatechange', check);
  });

const pc = new RTCPeerConnection();
pc.createDataChannel('daten');
await pc.setLocalDescription(await pc.createOffer());
await waitForGatheringComplete(pc);

// localDescription enthält jetzt alle gesammelten Kandidaten
const sdp = pc.localDescription.sdp;
console.log(sdp.includes('a=candidate'));

true

Mit der on-Property und dem Ende-Signal von icecandidate

const pc = new RTCPeerConnection();

pc.onicegatheringstatechange = () => {
  document.querySelector('#ice-status').textContent = pc.iceGatheringState;
};

pc.onicecandidate = ({ candidate }) => {
  if (candidate === null) {
    // Ende-Signal: danach ist der Status "complete"
    console.log('Alle Kandidaten gesammelt:', pc.iceGatheringState);
  }
};

pc.createDataChannel('x');
pc.createOffer().then((o) => pc.setLocalDescription(o));

Alle Kandidaten gesammelt: complete

// Wichtig · Fallstricke

Nicht mit dem Verbindungsstatus verwechseln: Auch bei "complete" kann die Verbindung noch fehlschlagen. Ob eine Verbindung steht, zeigen iceConnectionState und connectionState.
Das Sammeln beginnt erst mit setLocalDescription() und nur, wenn es Transceiver oder Datenkanäle gibt. Eine leere Verbindung bleibt auf "new".
Zurück auf "gathering": Bei restartIce(), bei createOffer({ iceRestart: true }) oder bei neuen Medienabschnitten kann der Status von "complete" wieder zu "gathering" wechseln. Man sollte also nicht davon ausgehen, dass er sich nur in eine Richtung ändert.
Wartezeiten: Wenn STUN- oder TURN-Server nicht erreichbar sind, kann es mehrere Sekunden bis zu "complete" dauern. Ein Zeitlimit (Timeout) und Trickle ICE verkürzen den Verbindungsaufbau deutlich.
Nach close() ändert sich der Status nicht mehr, und es werden keine Ereignisse mehr ausgelöst.
Kompatibilität: Unterstützt in allen modernen Browsern. Ältere Safari-Versionen und frühe Edge-Versionen (EdgeHTML) haben Übergänge teils unvollständig gemeldet. Mit icecandidate und candidate === null als zusätzlichem Ende-Signal ist man auf der sicheren Seite.
Datenschutz: Gesammelte Host-Kandidaten können lokale IP-Adressen offenlegen. Moderne Browser verschleiern diese deshalb über mDNS-Namen (*.local).

Siehe auch

RTCPeerConnection RTCPeerConnection.iceConnectionState RTCPeerConnection.connectionState RTCPeerConnection.setLocalDescription() RTCPeerConnection.restartIce()