new RTCPeerConnectionIceEvent() — Methode · JavaScript-Referenz

Signatur

new RTCPeerConnectionIceEvent(type, options)

Beschreibung

Der Konstruktor RTCPeerConnectionIceEvent() erzeugt ein Event-Objekt vom Typ RTCPeerConnectionIceEvent. Solche Events löst der Browser normalerweise selbst auf einer RTCPeerConnection aus, und zwar als icecandidate-Event, sobald der ICE-Agent einen neuen Kandidaten gefunden hat. Den Kandidaten liest man dann über die Eigenschaft event.candidate aus und schickt ihn per Signalisierung an die Gegenstelle.

In normalem Anwendungscode ruft man den Konstruktor selten selbst auf. Nützlich ist er vor allem für Unit-Tests und Mocks: Man kann die eigene Signalisierungslogik testen, ohne eine echte Netzwerkverbindung aufzubauen. Außerdem eignet er sich für Polyfills und Adapter-Schichten, die WebRTC-Events nachbilden oder weiterreichen.

Ein Event mit candidate: null bedeutet, dass die Kandidatensuche abgeschlossen ist (Ende der Kandidaten). Deshalb sollte jeder icecandidate-Handler diesen Fall ausdrücklich behandeln.

Parameter

Name	Typ	Default	Beschreibung
$type Pflicht	string		Name des Events. In der Praxis fast immer `"icecandidate"`.
$options	object	{}	Optionales Konfigurationsobjekt. Es erbt die Felder von `EventInit` (`bubbles`, `cancelable`, `composed`, jeweils standardmäßig `false`).
$options.candidate	RTCIceCandidate \| null	null	Der ICE-Kandidat, den das Event transportiert. `null` signalisiert das Ende der Kandidatensuche.
$options.url	string \| null	null	URL des STUN-/TURN-Servers, über den der Kandidat ermittelt wurde. Veraltet und nicht in allen Browsern unterstützt. Stattdessen `RTCIceCandidate.url` verwenden, wo verfügbar.

Beispiele

Event mit einem ICE-Kandidaten erzeugen

const candidate = new RTCIceCandidate({
  candidate: 'candidate:1 1 udp 2122260223 192.168.1.20 54321 typ host',
  sdpMid: '0',
  sdpMLineIndex: 0
});

const event = new RTCPeerConnectionIceEvent('icecandidate', { candidate });

console.log(event.type);
console.log(event.candidate.address, event.candidate.port);
console.log(event.isTrusted);

icecandidate 192.168.1.20 54321 false

Signalisierungslogik ohne echte Verbindung testen

// Zu testende Logik: Kandidaten an den Signalisierungsserver senden
const sent = [];
const signaling = { send: (msg) => sent.push(msg) };

const onIceCandidate = ({ candidate }) => {
  if (candidate) {
    signaling.send({ type: 'candidate', candidate: candidate.toJSON() });
  } else {
    signaling.send({ type: 'end-of-candidates' });
  }
};

const target = new EventTarget();
target.addEventListener('icecandidate', onIceCandidate);

// Browser-Verhalten simulieren
target.dispatchEvent(new RTCPeerConnectionIceEvent('icecandidate', {
  candidate: new RTCIceCandidate({
    candidate: 'candidate:2 1 udp 1686052607 203.0.113.5 40000 typ srflx raddr 0.0.0.0 rport 0',
    sdpMid: '0',
    sdpMLineIndex: 0
  })
}));
target.dispatchEvent(new RTCPeerConnectionIceEvent('icecandidate', { candidate: null }));

console.log(sent.map((m) => m.type));

["candidate", "end-of-candidates"]

Ende der Kandidaten auf einer RTCPeerConnection simulieren

const pc = new RTCPeerConnection();

pc.onicecandidate = (event) => {
  console.log(event instanceof RTCPeerConnectionIceEvent, event.candidate);
};

// Löst nur die Handler aus, der ICE-Agent selbst bleibt unberührt
pc.dispatchEvent(new RTCPeerConnectionIceEvent('icecandidate'));

pc.close();

true null

// Wichtig · Fallstricke

Synthetische Events: Selbst erzeugte Events haben isTrusted === false. Wer sie per dispatchEvent() auf einer echten RTCPeerConnection auslöst, ruft nur die registrierten Handler auf. Der ICE-Agent erfährt davon nichts, und es entsteht kein echter Kandidat.
Gültiger Kandidat nötig: new RTCIceCandidate() wirft einen TypeError, wenn sowohl sdpMid als auch sdpMLineIndex null sind. In Tests daher immer mindestens eins davon angeben.
null-Kandidat: Ein fehlender candidate bedeutet „Ende der Kandidaten“. Handler, die ohne Prüfung auf event.candidate.candidate zugreifen, stürzen dabei ab.
Veraltetes url: Die Option bzw. Eigenschaft url ist veraltet und wird nicht überall unterstützt. Code sollte sich nicht darauf verlassen.
Kompatibilität: Der Konstruktor ist in allen aktuellen Browsern verfügbar. In Node.js gibt es ihn nicht von Haus aus. Dort braucht man eine WebRTC-Bibliothek (z. B. wrtc/node-datachannel) oder ein eigenes Mock-Objekt.

Siehe auch

RTCPeerConnectionIceEvent RTCPeerConnectionIceEvent.candidate RTCIceCandidate RTCPeerConnection.prototype.addIceCandidate() EventTarget.prototype.dispatchEvent() new FontFaceSetLoadEvent()