RTCDtlsTransport: statechange — Ereignis · JavaScript-Referenz

Signatur

dtlsTransport.addEventListener("statechange", handler)

Beschreibung

Das Ereignis statechange wird an einem RTCDtlsTransport ausgelöst, wenn sich der Zustand der DTLS-Verbindung ändert. Über DTLS (Datagram Transport Layer Security) wird bei WebRTC der Schlüsselaustausch für SRTP-Medienströme und die Verschlüsselung von Datenkanälen (SCTP) abgewickelt. Den Transport erreicht man z. B. über RTCRtpSender.transport, RTCRtpReceiver.transport oder RTCSctpTransport.transport.

Das Ereignis ist ein einfaches Event ohne zusätzliche Eigenschaften und steigt nicht auf (kein Bubbling). Den neuen Zustand liest man im Handler aus event.target.state bzw. direkt aus transport.state. Mögliche Werte sind "new", "connecting", "connected", "closed" und "failed".

Registrieren lässt sich der Handler per addEventListener("statechange", handler) oder über die Eigenschaft onstatechange. Das Ereignis eignet sich, um gezielt Probleme auf der Verschlüsselungsebene zu erkennen, etwa fehlgeschlagene Handshakes wegen ungültiger Zertifikate. Das ist feiner als RTCPeerConnection.connectionState, das ICE- und DTLS-Zustände zusammenfasst.

Parameter

Name	Typ	Default	Beschreibung
$type Pflicht	string		Der Ereignistyp, hier immer `"statechange"`.
$handler Pflicht	(event: Event) => void		Callback, der bei jeder Zustandsänderung aufgerufen wird. `event.target` ist der betroffene `RTCDtlsTransport`.
$options	boolean \| AddEventListenerOptions	false	Optionale Listener-Optionen wie `once` oder `signal` (für die Abmeldung über `AbortController`).

Rückgabewert

Typ

void

Beschreibung

addEventListener gibt nichts zurück. Der Handler bekommt ein einfaches Event-Objekt übergeben.

Beispiele

DTLS-Zustand eines Senders überwachen (addEventListener)

const pc = new RTCPeerConnection();
const stream = await navigator.mediaDevices.getUserMedia({ audio: true });
const sender = pc.addTrack(stream.getAudioTracks()[0], stream);

// transport ist erst verfügbar, nachdem die Beschreibung gesetzt wurde
await pc.setLocalDescription(await pc.createOffer());

const dtls = sender.transport;
dtls?.addEventListener('statechange', (event) => {
  console.log('DTLS-Zustand:', event.target.state);
});

DTLS-Zustand: connecting DTLS-Zustand: connected

Fehlgeschlagenen Handshake behandeln (onstatechange)

const watchDtls = (transport, onFail) => {
  transport.onstatechange = () => {
    switch (transport.state) {
      case 'connected':
        console.log('Verschlüsselte Verbindung steht.');
        break;
      case 'failed':
        console.error('DTLS-Handshake fehlgeschlagen');
        onFail();
        break;
      case 'closed':
        transport.onstatechange = null; // Handler entfernen
        break;
    }
  };
};

// Aufruf, sobald der Transport existiert:
// watchDtls(sender.transport, () => pc.restartIce());

Verschlüsselte Verbindung steht.

Listener mit AbortController wieder abmelden

const controller = new AbortController();

const logState = (event) => {
  console.log(`DTLS: ${event.target.state}`);
};

const dtls = pc.sctp?.transport; // Transport des Datenkanals
dtls?.addEventListener('statechange', logState, { signal: controller.signal });

// Später, z. B. beim Beenden des Anrufs:
controller.abort();
// Alternativ: dtls.removeEventListener('statechange', logState);

DTLS: connected

// Wichtig · Fallstricke

Transport erst spät verfügbar: sender.transport, receiver.transport und pc.sctp sind null, bis eine lokale bzw. entfernte Beschreibung gesetzt wurde. Den Listener daher erst danach registrieren, z. B. nach setLocalDescription() oder im track-Ereignis.
Gemeinsamer Transport: Bei bundlePolicy: "max-bundle" (Standard in modernen Browsern) teilen sich meist alle Sender und Empfänger denselben RTCDtlsTransport. Wer an jedem Sender einen Listener registriert, bekommt dasselbe Ereignis mehrfach.
Endzustände: "failed" und "closed" sind endgültig. Ein fehlgeschlagener Transport erholt sich nicht von selbst, dafür muss neu verhandelt werden.
Das Ereignis enthält keine Fehlerdetails. Mehr Informationen liefert das error-Ereignis des Transports (in Chromium-Browsern), oder man wertet getStats() aus.
Kompatibilität: Firefox unterstützt RTCDtlsTransport erst ab Version 122. In älteren Browsern auf RTCPeerConnection: connectionstatechange ausweichen und vorher prüfen, ob sender.transport existiert.

Siehe auch

RTCDtlsTransport RTCDtlsTransport.state RTCDtlsTransport: error RTCPeerConnection: connectionstatechange RTCIceTransport: statechange RTCRtpSender.transport HTMLMediaElement: ratechange