RTCSctpTransport: statechange — Ereignis · JavaScript-Referenz

Signatur

sctpTransport.addEventListener("statechange", handler)

Beschreibung

Das Ereignis statechange wird an ein RTCSctpTransport ausgelöst, sobald sich der Wert seiner Eigenschaft state ändert. Das SCTP-Transportobjekt überträgt in einer RTCPeerConnection alle Daten der RTCDataChannel-Kanäle. Du erreichst es über peerConnection.sctp.

Mögliche Zustände sind "connecting" (die SCTP-Aushandlung läuft), "connected" (die Aushandlung ist abgeschlossen, Datenkanäle können Daten senden) und "closed" (die SCTP-Verbindung wurde beendet, z. B. durch ein SCTP-ABORT, das Schließen des zugrunde liegenden DTLS-Transports oder durch pc.close()). Das Ereignis ist ein einfaches Event ohne zusätzliche Eigenschaften. Den neuen Zustand liest du über event.target.state bzw. pc.sctp.state.

Du registrierst den Handler entweder mit addEventListener("statechange", handler) oder über die Eigenschaft onstatechange. Das Ereignis eignet sich, um die Datenverbindung als Ganzes zu überwachen, etwa für Verbindungsanzeigen, Diagnose oder Aufräumlogik, unabhängig von den open- und close-Ereignissen einzelner Datenkanäle.

Parameter

Name	Typ	Default	Beschreibung
$type Pflicht	string		Der Ereignistyp, hier immer `"statechange"`.
$handler Pflicht	(event: Event) => void		Callback, der beim Zustandswechsel aufgerufen wird. `event.target` ist das `RTCSctpTransport`.
$options	boolean \| AddEventListenerOptions	false	Optionale Listener-Optionen wie `once` oder `signal` (zum Entfernen per `AbortController`).

Rückgabewert

Typ

void

Beschreibung

addEventListener gibt nichts zurück. Der Handler erhält ein Event-Objekt, der neue Zustand steht in event.target.state.

Beispiele

Zustand per addEventListener überwachen

const pc = new RTCPeerConnection();
// Datenkanal anlegen, damit SCTP ausgehandelt wird
const channel = pc.createDataChannel('chat');

const watchSctp = () => {
  const sctp = pc.sctp;
  if (!sctp) return;
  sctp.addEventListener('statechange', (event) => {
    console.log('SCTP-Zustand:', event.target.state);
  });
};

// pc.sctp existiert erst nach der Aushandlung der Remote-Beschreibung
pc.addEventListener('signalingstatechange', () => {
  if (pc.signalingState === 'stable') watchSctp();
}, { once: true });

SCTP-Zustand: connected

Handler über onstatechange setzen und wieder entfernen

const attachSctpHandler = (pc) => {
  const sctp = pc.sctp;
  if (!sctp) return;

  sctp.onstatechange = () => {
    switch (sctp.state) {
      case 'connecting':
        console.log('Datenverbindung wird aufgebaut …');
        break;
      case 'connected':
        console.log('Datenverbindung steht, maxMessageSize =', sctp.maxMessageSize);
        break;
      case 'closed':
        console.log('Datenverbindung geschlossen');
        sctp.onstatechange = null; // Handler entfernen
        break;
    }
  };
};

Datenverbindung steht, maxMessageSize = 262144

Listener mit AbortController entfernen

const controller = new AbortController();

const onSctpState = (event) => {
  const state = event.target.state;
  document.querySelector('#status').textContent = `Daten: ${state}`;
  if (state === 'closed') controller.abort(); // Listener abmelden
};

const observe = (pc) => {
  pc.sctp?.addEventListener('statechange', onSctpState, {
    signal: controller.signal,
  });
};

// Alternativ manuell:
// pc.sctp.removeEventListener('statechange', onSctpState);

// Wichtig · Fallstricke

pc.sctp ist anfangs null: Das Transportobjekt existiert erst, nachdem eine Session-Beschreibung mit Datenkanal-Anteil (m=application) gesetzt wurde. Registriere den Listener also erst nach setLocalDescription/setRemoteDescription. Sonst wirft der Aufruf einen TypeError.
Das Ereignis wird nur bei einem echten Zustandswechsel ausgelöst. Wenn der Transport beim Registrieren schon connected ist, kommt kein weiteres Ereignis. Prüfe daher zusätzlich den aktuellen Wert von sctp.state.
Ruft deine Seite selbst pc.close() auf, wird der Zustand closed gesetzt, laut Spezifikation aber kein statechange-Ereignis ausgelöst. Aufräumlogik gehört deshalb zusätzlich an die Stelle, an der du close() aufrufst.
Für ICE- oder DTLS-Probleme sind RTCIceTransport/RTCDtlsTransport (erreichbar über sctp.transport) bzw. connectionstatechange an der RTCPeerConnection aussagekräftiger.
Browser-Kompatibilität: Chromium ab Version 76, Safari ab 15, Firefox erst ab 113. In älteren Firefox-Versionen fehlt pc.sctp. Prüfe das mit 'sctp' in RTCPeerConnection.prototype.

Siehe auch

RTCSctpTransport RTCSctpTransport.state RTCPeerConnection.sctp RTCSctpTransport.transport RTCDtlsTransport: statechange RTCPeerConnection: connectionstatechange RTCDataChannel