RTCIceCandidate.relatedAddress — Eigenschaft · JavaScript-Referenz

Signatur

RTCIceCandidate.relatedAddress

Beschreibung

Die Eigenschaft relatedAddress eines RTCIceCandidate liefert die IP-Adresse, von der ein abgeleiteter Kandidat stammt. Sie wird aus dem Feld raddr der SDP-Zeile a=candidate: gelesen. Zusammen mit relatedPort zeigt sie, wie ein Kandidat mit dem lokalen Netz zusammenhängt.

Die Bedeutung hängt vom Kandidatentyp (RTCIceCandidate.type) ab:

host: Keine zugehörige Adresse, der Wert ist null.
srflx (serverreflexiv): Die lokale Basisadresse, deren öffentliche Abbildung der STUN-Server gemeldet hat.
prflx (peerreflexiv): Die Basisadresse, von der das Paket gesendet wurde, das diesen Kandidaten entdeckt hat.
relay: Die vom TURN-Server gemeldete reflexive Adresse, über die der Relay-Kandidat erreicht wird.

Für den ICE-Verbindungsaufbau selbst ist relatedAddress nicht nötig. Nützlich ist sie vor allem für Diagnose und Protokollierung, etwa um festzustellen, ob STUN/TURN funktioniert oder ob NAT im Spiel ist. Den Wert kann man nicht setzen. Er entsteht aus dem Kandidaten-String, der an den Konstruktor übergeben wird, oder aus dem Kandidaten, den der Browser selbst sammelt.

Rückgabewert

Typ

string | null

Beschreibung

Die zugehörige IP-Adresse (IPv4 oder IPv6) als String oder null, wenn der Kandidat keine hat (z. B. host) oder der Wert verborgen ist.

Beispiele

Zugehörige Adresse lokaler Kandidaten protokollieren

const pc = new RTCPeerConnection({
  iceServers: [{ urls: 'stun:stun.l.google.com:19302' }]
});

pc.addEventListener('icecandidate', ({ candidate }) => {
  if (!candidate) return; // Sammeln der Kandidaten beendet
  const { type, address, port, relatedAddress, relatedPort } = candidate;
  console.log(`${type}: ${address}:${port}`,
    relatedAddress ? `(von ${relatedAddress}:${relatedPort})` : '');
});

pc.createDataChannel('diag');
await pc.setLocalDescription(await pc.createOffer());

host: 3f1c9a2e-....local:54321 srflx: 203.0.113.7:54321 (von 0.0.0.0:0)

Kandidat aus einem SDP-String erzeugen

const candidate = new RTCIceCandidate({
  candidate: 'candidate:842163049 1 udp 1677729535 203.0.113.7 61001 typ srflx raddr 192.168.1.20 rport 61001 generation 0',
  sdpMid: '0',
  sdpMLineIndex: 0
});

console.log(candidate.type);           // Kandidatentyp
console.log(candidate.relatedAddress); // Wert aus raddr
console.log(candidate.relatedPort);    // Wert aus rport

srflx 192.168.1.20 61001

Prüfen, ob TURN-Relay funktioniert

const testTurn = (turnConfig) => new Promise((resolve) => {
  const pc = new RTCPeerConnection({ iceServers: [turnConfig] });
  const timer = setTimeout(() => { pc.close(); resolve(null); }, 5000);

  pc.onicecandidate = ({ candidate }) => {
    if (candidate?.type === 'relay') {
      clearTimeout(timer);
      pc.close();
      resolve({ relay: candidate.address, related: candidate.relatedAddress });
    }
  };
  pc.createDataChannel('t');
  pc.createOffer().then((o) => pc.setLocalDescription(o));
});

const result = await testTurn({
  urls: 'turn:turn.example.com:3478', username: 'user', credential: 'pass'
});
console.log(result ?? 'Kein Relay-Kandidat – TURN nicht erreichbar');

{ relay: '198.51.100.4', related: '203.0.113.7' }

// Wichtig · Fallstricke

Datenschutz: Moderne Browser verbergen lokale IP-Adressen mit mDNS-Hostnamen (*.local). Bei srflx- und relay-Kandidaten wird raddr oft durch 0.0.0.0 bzw. :: ersetzt und rport durch 0. Man kann sich also nicht darauf verlassen, hier die echte lokale IP zu bekommen.
Bei host-Kandidaten und bei Kandidaten ohne raddr im String ist der Wert null, kein Leerstring. Vor der Weiterverarbeitung also auf null prüfen.
Die Eigenschaft ist schreibgeschützt. Eine Zuweisung wird stillschweigend ignoriert, im Strict Mode wirft sie einen TypeError.
Kompatibilität: Chrome/Edge seit Version 74, Firefox seit 68, Safari seit 11. Ältere Browser liefern undefined. Als Ausweg lässt sich candidate.candidate selbst parsen (Felder raddr/rport).
Protokolliert man ICE-Kandidaten auf einem Server, können darin personenbezogene IP-Adressen stehen. Das ist datenschutzrechtlich relevant (DSGVO).

Siehe auch

RTCIceCandidate RTCIceCandidate.relatedPort RTCIceCandidate.address RTCIceCandidate.type RTCIceCandidate.candidate WorkerNavigator.mediaCapabilities