RTCIceTransport.getLocalParameters() — Methode · JavaScript-Referenz

Signatur

RTCIceTransport.prototype.getLocalParameters()

Beschreibung

getLocalParameters() liefert die ICE-Zugangsdaten, die der lokale Endpunkt für die laufende ICE-Sitzung benutzt: das Username-Fragment (ice-ufrag) und das Passwort (ice-pwd). Mit diesen Werten werden die STUN-Verbindungsprüfungen (Connectivity Checks) zwischen den Peers authentifiziert. Es sind dieselben Werte, die als a=ice-ufrag und a=ice-pwd in der lokalen SDP-Beschreibung stehen.

Auf ein RTCIceTransport greift man nicht direkt über die RTCPeerConnection zu. Der Weg führt über den DTLS-Transport: sender.transport.iceTransport, receiver.transport.iceTransport oder bei Datenkanälen über pc.sctp.transport.iceTransport. Die Transporte gibt es erst, nachdem setLocalDescription() bzw. setRemoteDescription() aufgerufen wurde.

Nützlich ist die Methode vor allem zur Diagnose und Protokollierung, etwa um zu prüfen, welche ICE-Sitzung gerade aktiv ist, oder um einen ICE-Neustart (restartIce()) zu erkennen: Bei einem Neustart werden neue Werte für usernameFragment und password erzeugt. Für die Gegenstelle gibt es die entsprechende Methode getRemoteParameters().

Rückgabewert

Typ

RTCIceParameters | null

Beschreibung

Ein Objekt mit den Eigenschaften usernameFragment (string) und password (string). Sind noch keine lokalen Parameter festgelegt, gibt die Methode null zurück.

Beispiele

Lokale ICE-Parameter nach dem Verbindungsaufbau auslesen

const pc = new RTCPeerConnection();
const stream = await navigator.mediaDevices.getUserMedia({ audio: true });
stream.getTracks().forEach((track) => pc.addTrack(track, stream));

const offer = await pc.createOffer();
await pc.setLocalDescription(offer);

// Zugriff auf den ICE-Transport über den DTLS-Transport des Senders
const iceTransport = pc.getSenders()[0].transport?.iceTransport;
const params = iceTransport?.getLocalParameters();

if (params) {
  console.log('ufrag:', params.usernameFragment);
  console.log('pwd-Länge:', params.password.length);
} else {
  console.log('Noch keine lokalen ICE-Parameter vorhanden');
}

ufrag: 4ZcD pwd-Länge: 24

Parameter mit der lokalen SDP abgleichen

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

const iceTransport = pc.sctp?.transport.iceTransport;
const { usernameFragment } = iceTransport?.getLocalParameters() ?? {};

// ice-ufrag aus der SDP herausziehen
const sdpUfrag = pc.localDescription.sdp.match(/a=ice-ufrag:(\S+)/)?.[1];
console.log('Stimmen überein:', usernameFragment === sdpUfrag);

Stimmen überein: true

ICE-Neustart anhand neuer Parameter erkennen

const getUfrag = (pc) =>
  pc.getSenders()[0]?.transport?.iceTransport
    ?.getLocalParameters()?.usernameFragment;

const before = getUfrag(pc);
pc.restartIce();

pc.addEventListener('negotiationneeded', async () => {
  await pc.setLocalDescription();
  const after = getUfrag(pc);
  console.log('ICE-Neustart erkannt:', before !== after);
  // ... neue Offer per Signalisierung an die Gegenstelle schicken
});

ICE-Neustart erkannt: true

// Wichtig · Fallstricke

Browser-Unterstützung: Chromium-basierte Browser und Safari unterstützen RTCIceTransport. Firefox hat die Schnittstelle bzw. RTCDtlsTransport.iceTransport lange nicht oder nur teilweise angeboten. Deshalb am besten mit optionaler Verkettung (?.) arbeiten und prüfen, ob die Methode existiert.
Vor setLocalDescription() ist sender.transport gleich null, und getLocalParameters() kann null zurückgeben. Den Rückgabewert deshalb immer prüfen.
Nach einem ICE-Neustart gelten neue Werte. Einmal zwischengespeicherte Parameter können also veraltet sein.
Sicherheit: password ist ein Geheimnis für die STUN-Authentifizierung. Es sollte nicht protokolliert oder an Dritte übertragen werden, sondern nur über den vorgesehenen Signalisierungskanal (in der SDP) zur Gegenstelle gelangen.
Bei bundlePolicy: 'max-bundle' teilen sich alle Sender und Empfänger meist denselben ICE-Transport und damit dieselben Parameter.

Siehe auch

RTCIceTransport RTCIceTransport.getRemoteParameters() RTCIceTransport.getSelectedCandidatePair() RTCDtlsTransport.iceTransport RTCPeerConnection.restartIce() RTCPeerConnection