RTCIceParameters — Schnittstelle · JavaScript-Referenz

Signatur

dictionary RTCIceParameters { usernameFragment, password }

Beschreibung

RTCIceParameters ist ein WebRTC-Wörterbuch, also ein einfaches Objekt ohne eigenen Konstruktor. Es enthält die beiden Zugangsdaten, mit denen sich zwei ICE-Agenten bei den STUN-Verbindungsprüfungen gegenseitig ausweisen: das Benutzername-Fragment (ice-ufrag) und das Passwort (ice-pwd). Beide Werte stehen auch im SDP als Zeilen a=ice-ufrag: und a=ice-pwd:.

Solche Objekte bekommst du von den Methoden RTCIceTransport.getLocalParameters() und RTCIceTransport.getRemoteParameters(). An den RTCIceTransport kommst du über RTCRtpSender.transport.iceTransport oder RTCSctpTransport.transport.iceTransport. Damit kannst du die Werte auslesen, ohne das SDP selbst zu zerlegen.

Nützlich ist das vor allem bei der Fehlersuche und Überwachung: Nach einem ICE-Neustart (RTCPeerConnection.restartIce() oder createOffer({ iceRestart: true })) werden Benutzername-Fragment und Passwort neu erzeugt. Ändert sich usernameFragment, hat also ein Neustart stattgefunden. Außerdem lässt sich damit prüfen, welcher Kandidat zu welcher ICE-Generation gehört (siehe RTCIceCandidate.usernameFragment).

Parameter

Name	Typ	Default	Beschreibung
$usernameFragment	string		Benutzername-Fragment der ICE-Sitzung (`ice-ufrag`). Laut RFC 8839 mindestens 4 Zeichen lang. Zusammen mit dem Fragment der Gegenseite ergibt es den STUN-Benutzernamen.
$password	string		ICE-Passwort (`ice-pwd`), mindestens 22 Zeichen lang. Damit werden die STUN-Verbindungsprüfungen abgesichert (MESSAGE-INTEGRITY).

Rückgabewert

Typ

RTCIceParameters

Beschreibung

Einfaches Objekt der Form { usernameFragment, password }. Du bekommst es von getLocalParameters() bzw. getRemoteParameters(). Solange noch keine Parameter bekannt sind, liefern diese Methoden null.

Beispiele

Lokale und entfernte ICE-Parameter auslesen

const pc = new RTCPeerConnection();
// ... Signalisierung und Verbindungsaufbau wie gewohnt ...

pc.addEventListener('connectionstatechange', () => {
  if (pc.connectionState !== 'connected') return;

  const [sender] = pc.getSenders();
  const iceTransport = sender?.transport?.iceTransport;
  if (!iceTransport) {
    console.warn('RTCIceTransport wird nicht unterstützt');
    return;
  }

  const local = iceTransport.getLocalParameters();
  const remote = iceTransport.getRemoteParameters();
  console.log('Lokal:', local?.usernameFragment);
  console.log('Remote:', remote?.usernameFragment);
});

Lokal: 8hhY Remote: aB3x

ICE-Neustart am geänderten Benutzername-Fragment erkennen

const watchIceRestarts = (pc) => {
  let lastUfrag = null;

  pc.addEventListener('iceconnectionstatechange', () => {
    const iceTransport = pc.getSenders()[0]?.transport?.iceTransport;
    const params = iceTransport?.getLocalParameters();
    if (!params) return;

    if (lastUfrag && lastUfrag !== params.usernameFragment) {
      console.log(`ICE-Neustart: ${lastUfrag} -> ${params.usernameFragment}`);
    }
    lastUfrag = params.usernameFragment;
  });
};

// später: pc.restartIce();

ICE-Neustart: 8hhY -> Qz7m

Parameter mit dem SDP abgleichen

const parseIceFromSdp = (sdp) => ({
  usernameFragment: sdp.match(/^a=ice-ufrag:(.+)$/m)?.[1]?.trim() ?? null,
  password: sdp.match(/^a=ice-pwd:(.+)$/m)?.[1]?.trim() ?? null,
});

const pc = new RTCPeerConnection();
pc.createDataChannel('chat');
const offer = await pc.createOffer();
await pc.setLocalDescription(offer);

const fromSdp = parseIceFromSdp(pc.localDescription.sdp);
console.log(fromSdp.usernameFragment.length >= 4, fromSdp.password.length >= 22);

true true

// Wichtig · Fallstricke

Kein Konstruktor: RTCIceParameters ist ein Wörterbuch, kein Interface. Ein new RTCIceParameters() gibt es nicht und instanceof-Prüfungen funktionieren nicht.
Browser-Unterstützung: RTCIceTransport mit getLocalParameters()/getRemoteParameters() gibt es in Chromium-Browsern und Safari. In Firefox ist sender.transport.iceTransport teils nicht verfügbar. Prüfe deshalb vorher, ob die Funktion vorhanden ist, und lies die Werte notfalls aus dem SDP (a=ice-ufrag/a=ice-pwd).
null möglich: Vor der Signalisierung bzw. vor setRemoteDescription() liefert getRemoteParameters() null. Verwende optionale Verkettung (?.).
Sicherheit: Das ICE-Passwort ist ein Sitzungsgeheimnis. Schreib es nicht in Logs, Analysedaten oder Fehlerberichte. Ein Benutzername-Fragment zur Fehlersuche ist unkritisch, das Passwort nicht.
Bei BUNDLE teilen sich alle Medien einen ICE-Transport und damit dieselben Parameter.

Siehe auch

VREyeParameters VRStageParameters Accelerometer RTCIceTransport RTCIceCandidate