RTCDataChannel.maxRetransmits — Eigenschaft · JavaScript-Referenz

Signatur

RTCDataChannel.maxRetransmits

Beschreibung

Die schreibgeschützte Eigenschaft maxRetransmits eines RTCDataChannel gibt an, wie oft der Browser eine nicht bestätigte Nachricht höchstens erneut übertragen soll, bevor er sie verwirft. Der Wert wird beim Anlegen des Kanals über die Option maxRetransmits von RTCPeerConnection.createDataChannel() festgelegt. Danach lässt er sich nicht mehr ändern.

Wenn Sie einen Wert setzen, wird der Kanal teilweise zuverlässig (partial reliability nach SCTP, RFC 3758). Das ist z. B. bei Echtzeit-Spielen, Positionsdaten oder Telemetrie sinnvoll. Dort ist eine veraltete Nachricht wertlos, und eine blockierende Neuübertragung würde nur Verzögerung erzeugen. Mit 0 wird eine Nachricht genau einmal gesendet und nie wiederholt, ähnlich wie bei UDP.

Wurde die Option nicht gesetzt, ist der Wert null. Der Kanal ist dann entweder voll zuverlässig oder wird stattdessen über maxPacketLifeTime zeitlich begrenzt. Beide Optionen schließen sich gegenseitig aus. Für die Reihenfolge der Nachrichten ist unabhängig davon die Eigenschaft ordered zuständig.

Rückgabewert

Typ

number | null

Beschreibung

Die höchste Anzahl an Neuübertragungen als ganze Zahl ohne Vorzeichen (16 Bit, 0–65535). Der Wert ist null, wenn beim Anlegen kein maxRetransmits angegeben wurde.

Beispiele

Unzuverlässigen Kanal für Spielpositionen anlegen

const pc = new RTCPeerConnection();

// Positionsdaten: höchstens 2 Neuübertragungen, Reihenfolge egal
const positions = pc.createDataChannel('positions', {
  ordered: false,
  maxRetransmits: 2
});

console.log(positions.maxRetransmits);
console.log(positions.ordered);

2 false

Standardwert bei einem zuverlässigen Kanal

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

console.log(chat.maxRetransmits);      // keine Begrenzung gesetzt
console.log(chat.maxPacketLifeTime);

null null

Zuverlässigkeit eines eingehenden Kanals prüfen

const pc = new RTCPeerConnection();

pc.addEventListener('datachannel', ({ channel }) => {
  const reliable = channel.maxRetransmits === null &&
                   channel.maxPacketLifeTime === null;

  console.log(`${channel.label}: ${reliable
    ? 'voll zuverlässig'
    : `teilweise zuverlässig (maxRetransmits=${channel.maxRetransmits})`}`);
});

positions: teilweise zuverlässig (maxRetransmits=2)

Fehler bei gleichzeitiger Angabe beider Optionen

const pc = new RTCPeerConnection();

try {
  pc.createDataChannel('bad', { maxRetransmits: 3, maxPacketLifeTime: 500 });
} catch (err) {
  console.log(err.name);
}

TypeError

// Wichtig · Fallstricke

Nur lesbar: Eine Zuweisung wie channel.maxRetransmits = 5 hat keine Wirkung und wirft im Strict Mode einen TypeError. Ändern lässt sich der Wert nur über einen neuen Kanal.
Gegenseitiger Ausschluss: Wenn Sie maxRetransmits und maxPacketLifeTime gleichzeitig angeben, wirft createDataChannel() einen TypeError.
Datenverlust ist gewollt: Bei gesetztem Wert können Nachrichten verloren gehen, und zwar ohne Fehlermeldung. Für Dateiübertragungen, Chat oder Steuerbefehle eignet sich das nicht. Nutzen Sie dafür einen zuverlässigen Kanal.
Kombination mit ordered: Wird ordered auf true belassen, können verworfene Nachrichten trotzdem die Zustellung aufhalten (Head-of-Line-Blocking). Deshalb setzt man meist zusätzlich ordered: false.
Kompatibilität: Ältere Chrome-Versionen hatten stattdessen die Eigenschaft maxRetransmitTime, die inzwischen entfernt wurde. Frühere Implementierungen lieferten teils 65535 statt null. Prüfen Sie deshalb am besten auf null und auf diesen Sonderwert.
Werte über 65535 werden von der Implementierung auf das Maximum gekürzt.

Siehe auch

RTCDataChannel RTCDataChannel.maxPacketLifeTime RTCDataChannel.ordered RTCPeerConnection.createDataChannel() RTCDataChannel.reliable PreferenceManager.reducedTransparency WindowClient.ancestorOrigins