Signatur
Beschreibung
Der Konstruktor RTCIceCandidate() erzeugt ein Objekt, das einen einzelnen ICE-Kandidaten beschreibt. Ein solcher Kandidat ist eine mögliche Kombination aus IP-Adresse, Port und Transportprotokoll, über die zwei Teilnehmer einer RTCPeerConnection Daten austauschen können. Mögliche Typen sind lokale Adressen (host), per STUN ermittelte öffentliche Adressen (srflx/prflx) und TURN-Relay-Adressen (relay).
In der Praxis braucht man den Konstruktor vor allem auf der Empfängerseite des Signalisierungskanals: Der entfernte Teilnehmer sendet seinen Kandidaten (meist als JSON aus candidate.toJSON()) z. B. per WebSocket. Man baut daraus mit new RTCIceCandidate(daten) wieder ein Objekt und übergibt es an RTCPeerConnection.addIceCandidate().
Die schreibgeschützten Eigenschaften wie address, port, protocol, type oder foundation werden aus dem SDP-String im Feld candidate geparst. Mindestens sdpMid oder sdpMLineIndex muss angegeben werden, damit der Kandidat einer Medienzeile zugeordnet werden kann.
Parameter
| Name | Typ | Default | Beschreibung |
|---|---|---|---|
| $candidateInfo | RTCIceCandidateInit | {} | Initialisierungsobjekt mit den Feldern candidate (SDP-Attributzeile, z. B. "candidate:842163049 1 udp 1677729535 203.0.113.5 52301 typ srflx ..."; leerer String = Ende der Kandidaten), sdpMid (string|null, ID der Medienbeschreibung), sdpMLineIndex (number|null, Index der m-Zeile im SDP) und usernameFragment (string|null, ICE-ufrag). |
Rückgabewert
RTCIceCandidate-Objekt, dessen Eigenschaften (address, port, type, protocol usw.) aus dem übergebenen candidate-String abgeleitet sind.Beispiele
Kandidat aus Signalisierungsnachricht hinzufügen
const pc = new RTCPeerConnection({ iceServers: [{ urls: 'stun:stun.l.google.com:19302' }] });
const socket = new WebSocket('wss://signal.example.com');
socket.addEventListener('message', async (event) => {
const msg = JSON.parse(event.data);
if (msg.type === 'ice-candidate') {
try {
const candidate = new RTCIceCandidate(msg.candidate);
await pc.addIceCandidate(candidate);
console.log('Kandidat hinzugefügt:', candidate.type, candidate.address);
} catch (err) {
console.error('Kandidat ungültig:', err);
}
}
});Lokale Kandidaten serialisieren und senden
const pc = new RTCPeerConnection();
const socket = new WebSocket('wss://signal.example.com');
pc.addEventListener('icecandidate', ({ candidate }) => {
// candidate === null signalisiert das Ende der Sammlung
socket.send(JSON.stringify({
type: 'ice-candidate',
candidate: candidate ? candidate.toJSON() : null
}));
});Kandidat manuell erzeugen und untersuchen
const cand = new RTCIceCandidate({
candidate: 'candidate:842163049 1 udp 1677729535 203.0.113.5 52301 typ srflx raddr 192.168.1.10 rport 52301 generation 0 ufrag abcd',
sdpMid: '0',
sdpMLineIndex: 0
});
console.log(cand.protocol, cand.port, cand.type, cand.component);
console.log(JSON.stringify(cand.toJSON()));// Wichtig · Fallstricke
- Sind sowohl
sdpMidals auchsdpMLineIndexnullbzw. nicht angegeben, wirft der Konstruktor einenTypeError. - Seit WebRTC 1.0 akzeptiert
addIceCandidate()auch direkt ein einfachesRTCIceCandidateInit-Objekt – der explizite Konstruktoraufruf ist daher oft optional, macht den Code aber lesbarer. - Kandidaten, die vor
setRemoteDescription()ankommen, führen zu einem Fehler beiaddIceCandidate(); puffern Sie diese bis zum Setzen der Remote-Beschreibung. - Ein leerer
candidate-String steht für „End of Candidates“. Ältere Implementierungen verhalten sich dabei unterschiedlich. - Datenschutz:
host-Kandidaten können lokale IP-Adressen verraten. Moderne Browser verschleiern sie daher mit mDNS-Namen (*.local). Ältere Browser (alter Edge, Safari < 11) haben den Konstruktor nur teilweise oder mit Präfix unterstützt. - Signalisierungsdaten sollten Sie vor dem Parsen prüfen und nur über verschlüsselte Kanäle (
wss://) übertragen.