RTCDataChannelStats.protocol — Eigenschaft · JavaScript-Referenz

Signatur

RTCDataChannelStats.protocol

Beschreibung

Die Eigenschaft protocol gehört zu einem RTCDataChannelStats-Objekt. Solche Objekte liefert RTCPeerConnection.getStats() im zurückgegebenen RTCStatsReport für jeden Eintrag mit type === "data-channel". Der Wert entspricht der Eigenschaft RTCDataChannel.protocol, also dem Subprotokoll, das beim Aufruf von createDataChannel(label, { protocol }) angegeben wurde.

Das Subprotokoll ist ein frei wählbarer Bezeichner auf Anwendungsebene, zum Beispiel "json", "chat-v2" oder "binary-file". WebRTC wertet ihn nicht aus. Die Gegenstelle kann aber daran erkennen, wie die Nachrichten auf dem Kanal zu verarbeiten sind. Wurde kein Protokoll angegeben, ist der Wert ein leerer String.

In der Praxis nutzt man protocol vor allem beim Monitoring und Debugging: Zusammen mit label, messagesSent, bytesReceived und ähnlichen Werten lässt sich die Last pro Kanal auswerten und nach Protokoll gruppieren, ohne dass man die RTCDataChannel-Objekte selbst im Zugriff haben muss.

Rückgabewert

Typ

string

Beschreibung

Das Subprotokoll des Datenkanals, so wie es beim Erzeugen angegeben wurde. Ohne Angabe ein leerer String "".

Beispiele

Protokolle aller Datenkanäle auslesen

const pc = new RTCPeerConnection();
const chat = pc.createDataChannel('chat', { protocol: 'chat-v2' });
const files = pc.createDataChannel('dateien', { protocol: 'binary-file' });

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

chat: "chat-v2" dateien: "binary-file"

Übertragene Bytes nach Subprotokoll gruppieren

const bytesByProtocol = async (pc) => {
  const report = await pc.getStats();
  const result = {};
  for (const stats of report.values()) {
    if (stats.type !== 'data-channel') continue;
    const key = stats.protocol || '(ohne Protokoll)';
    result[key] = (result[key] ?? 0) + (stats.bytesSent ?? 0) + (stats.bytesReceived ?? 0);
  }
  return result;
};

// Alle 5 Sekunden protokollieren
setInterval(async () => console.table(await bytesByProtocol(pc)), 5000);

┌─────────────┬────────┐ │ chat-v2 │ 1834 │ │ binary-file │ 524288 │ └─────────────┴────────┘

Leerer String ohne protocol-Angabe

const pc = new RTCPeerConnection();
pc.createDataChannel('steuerung'); // kein protocol angegeben

const report = await pc.getStats();
const stats = [...report.values()].find((s) => s.type === 'data-channel');
console.log(JSON.stringify(stats?.protocol));

""

// Wichtig · Fallstricke

Leerer String statt undefined: Ohne angegebenes Subprotokoll ist der Wert "". Deshalb bei Vergleichen oder zur Gruppierung besser stats.protocol || 'Standard' verwenden.
Nur eine Kennzeichnung: Der Browser prüft weder Inhalt noch Format der Nachrichten anhand des Protokolls. Die Einhaltung ist Sache der Anwendung.
Maximale Länge: Laut Spezifikation ist das Protokoll auf 65535 Bytes begrenzt. Längere Werte führen schon bei createDataChannel() zu einem TypeError.
Kompatibilität: getStats() mit "data-channel"-Einträgen wird von Chromium, Firefox und Safari unterstützt, aber nicht jeder Browser liefert alle Felder. Vor dem Zugriff auf die Eigenschaft prüfen, ob sie vorhanden ist.
Die Statistik ist eine Momentaufnahme. Für den aktuellen Stand muss getStats() erneut aufgerufen werden.

Siehe auch

RTCDataChannelStats RTCDataChannelStats.label RTCDataChannel.protocol RTCPeerConnection.createDataChannel() RTCPeerConnection.getStats() RTCStatsReport RTCDataChannelStats.state