RTCDataChannelStats.state — Eigenschaft · JavaScript-Referenz

Signatur

RTCDataChannelStats.state

Beschreibung

Die Eigenschaft state gehört zum Dictionary RTCDataChannelStats, das man über RTCPeerConnection.getStats() erhält. Einträge dieses Typs haben type === "data-channel". state enthält einen der Werte "connecting", "open", "closing" oder "closed". Diese Werte entsprechen genau dem, was RTCDataChannel.readyState zum Zeitpunkt der Erfassung liefert.

Nützlich ist die Eigenschaft vor allem beim Überwachen und Diagnostizieren: Aus einem einzigen Statistik-Bericht lässt sich ablesen, welche Datenkanäle einer Verbindung gerade offen sind, und man kann das mit Kennzahlen wie messagesSent, bytesReceived oder label verknüpfen. Einen Verweis auf das eigentliche RTCDataChannel-Objekt braucht man dafür nicht.

Wichtig: Der Wert ist eine Momentaufnahme. Um auf Zustandsänderungen sofort zu reagieren, sind die Ereignisse open, closing und close am RTCDataChannel besser geeignet als regelmäßiges Abfragen von getStats().

Rückgabewert

Typ

"connecting" | "open" | "closing" | "closed"

Beschreibung

Ein String mit dem Zustand des Datenkanals:

"connecting" – die Verbindung wird noch aufgebaut
"open" – Nachrichten können gesendet und empfangen werden
"closing" – der Kanal wird gerade geschlossen
"closed" – der Kanal ist geschlossen oder konnte nicht aufgebaut werden

Beispiele

Zustand aller Datenkanäle auslesen

const pc = new RTCPeerConnection();
const channel = pc.createDataChannel('chat');

const logChannelStates = async () => {
  const report = await pc.getStats();
  report.forEach((stats) => {
    if (stats.type === 'data-channel') {
      console.log(`Kanal "${stats.label}" (ID ${stats.dataChannelIdentifier}): ${stats.state}`);
    }
  });
};

await logChannelStates();

Kanal "chat" (ID 0): connecting

Offene Kanäle mit Durchsatz auswerten

const getOpenChannelSummary = async (pc) => {
  const report = await pc.getStats();
  return [...report.values()]
    .filter((s) => s.type === 'data-channel' && s.state === 'open')
    .map(({ label, messagesSent, messagesReceived, bytesSent }) => ({
      label,
      messagesSent,
      messagesReceived,
      bytesSent
    }));
};

// Nach erfolgreichem Verbindungsaufbau:
console.table(await getOpenChannelSummary(pc));

Tabelle mit Label, Nachrichten- und Byte-Zählern aller offenen Kanäle

Statistik mit readyState vergleichen (Monitoring)

const monitor = (pc, channel, intervalMs = 5000) => {
  const timer = setInterval(async () => {
    const report = await pc.getStats();
    const stats = [...report.values()].find(
      (s) => s.type === 'data-channel' && s.dataChannelIdentifier === channel.id
    );
    console.log('Stats:', stats?.state, '| live:', channel.readyState);
    if (stats?.state === 'closed') clearInterval(timer);
  }, intervalMs);
  return () => clearInterval(timer);
};

const stopMonitor = monitor(pc, channel);

Stats: open | live: open

// Wichtig · Fallstricke

Nur eine Momentaufnahme: Der Wert gilt für den Zeitpunkt, zu dem getStats() die Daten erfasst hat. Wer schnell auf Änderungen reagieren muss, sollte die Ereignisse open/close am RTCDataChannel nutzen oder readyState direkt lesen.
Nicht jeder Browser führt geschlossene Kanäle weiter im Statistik-Bericht. Es kann also sein, dass ein Eintrag mit "closed" nie erscheint.
dataChannelIdentifier ist erst dann gesetzt (und nicht null), wenn der Kanal über SCTP ausgehandelt wurde. Vorher lassen sich Statistik-Einträge und Kanal nur über label zuordnen.
Browser-Unterstützung: Chromium unterstützt die Eigenschaft seit Langem, Firefox erst in neueren Versionen, Safari nur teilweise. Deshalb vor dem Zugriff auf undefined prüfen, z. B. mit optionaler Verkettung (stats?.state).
Die Eigenschaft ist schreibgeschützt. Das Ändern des Werts im zurückgegebenen Objekt hat keine Wirkung auf den Kanal.

Siehe auch

RTCDataChannelStats RTCDataChannel.readyState RTCPeerConnection.getStats() RTCDataChannel RTCStatsReport MediaTrackSupportedConstraints.sampleRate