RTCIceCandidateStats.deleted — Eigenschaft · JavaScript-Referenz

Signatur

RTCIceCandidateStats.deleted

Beschreibung

Die Eigenschaft deleted des Wörterbuchs RTCIceCandidateStats zeigt an, ob ein lokaler oder entfernter ICE-Kandidat nicht mehr genutzt werden kann. Diese Statistikobjekte bekommst du über RTCPeerConnection.getStats(). Sie haben den type "local-candidate" oder "remote-candidate".

Was true genau bedeutet, hängt vom Kandidatentyp ab:

Host-Kandidaten (candidateType: "host"): Die Netzwerkressourcen, meist der Socket, wurden freigegeben.
Relay-Kandidaten (candidateType: "relay"): Die TURN-Zuweisung ist nicht mehr aktiv.

Der Standardwert ist false. Solange der Wert false ist, gilt der Kandidat als noch verfügbar. Nützlich ist die Eigenschaft vor allem bei der Fehlersuche: Sie zeigt zum Beispiel, warum nach einem ICE-Restart oder einem Netzwerkwechsel bestimmte Kandidatenpaare nicht mehr funktionieren.

Die Eigenschaft wurde aus der aktuellen Spezifikation WebRTC Statistics entfernt und gilt als veraltet. Verlass dich in neuem Code nicht darauf. Prüfe immer, ob sie überhaupt vorhanden ist.

Rückgabewert

Typ

boolean | undefined

Beschreibung

true, wenn der Kandidat gelöscht bzw. freigegeben wurde, sonst false (Standardwert). In Browsern ohne Unterstützung ist die Eigenschaft undefined.

Beispiele

Gelöschte Kandidaten in den Statistiken finden

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

// Kurz warten, bis ICE-Kandidaten gesammelt wurden
await new Promise((r) => setTimeout(r, 2000));

const report = await pc.getStats();
report.forEach((stat) => {
  if (stat.type === 'local-candidate' || stat.type === 'remote-candidate') {
    const status = stat.deleted === undefined
      ? 'unbekannt (nicht unterstützt)'
      : stat.deleted ? 'gelöscht' : 'aktiv';
    console.log(`${stat.type} ${stat.candidateType} ${stat.address ?? '?'}:${stat.port} → ${status}`);
  }
});

local-candidate host 192.168.1.20:54321 → unbekannt (nicht unterstützt) local-candidate srflx 203.0.113.7:61000 → unbekannt (nicht unterstützt)

Nur verwendbare Kandidaten filtern (mit Rückfall)

const getUsableCandidates = async (pc) => {
  const report = await pc.getStats();
  return [...report.values()].filter(
    (s) => s.type === 'local-candidate' && s.deleted !== true // undefined gilt als aktiv
  );
};

const pc = new RTCPeerConnection();
pc.createDataChannel('x');
await pc.setLocalDescription(await pc.createOffer());
await new Promise((r) => setTimeout(r, 1000));

const usable = await getUsableCandidates(pc);
console.log(`${usable.length} verwendbare lokale Kandidaten`);

2 verwendbare lokale Kandidaten

Freigabe von TURN-Zuweisungen überwachen

const watchRelayCandidates = (pc, intervalMs = 5000) => setInterval(async () => {
  const report = await pc.getStats();
  for (const s of report.values()) {
    if (s.type === 'local-candidate' && s.candidateType === 'relay' && s.deleted) {
      console.warn(`TURN-Zuweisung ${s.id} (${s.url ?? 'unbekannt'}) ist nicht mehr aktiv`);
    }
  }
}, intervalMs);

const pc = new RTCPeerConnection({
  iceServers: [{ urls: 'turn:turn.example.com:3478', username: 'user', credential: 'pass' }]
});
const timer = watchRelayCandidates(pc);
// Später: clearInterval(timer); pc.close();

// Wichtig · Fallstricke

Veraltet: deleted wurde aus der Spezifikation WebRTC Statistics entfernt. Aktuelle Browser liefern die Eigenschaft meist gar nicht mehr. Dann ist sie undefined, nicht false.
Prüfe darum ausdrücklich mit stat.deleted === true bzw. 'deleted' in stat. Sonst hältst du einen fehlenden Wert womöglich fälschlich für „nicht gelöscht“.
Ob ein Kandidat wirklich genutzt wird, erfährst du zuverlässiger über die candidate-pair-Statistiken, etwa state und nominated, oder über RTCIceTransport.getSelectedCandidatePair().
Für getStats() brauchst du eine sichere Umgebung (HTTPS). Private IP-Adressen von Host-Kandidaten sind in vielen Browsern durch mDNS-Namen (*.local) verschleiert.
Rufe getStats() nicht zu oft auf. Das kostet Leistung, deshalb sind Intervalle von mindestens 1 Sekunde sinnvoll.

Siehe auch

RTCIceCandidateStats RTCIceCandidateStats.candidateType RTCPeerConnection.getStats() RTCIceCandidatePairStats RTCStatsReport MediaTrackSupportedConstraints.deviceId RTCIceCandidateStats.id