RTCIceTransport — Schnittstelle · JavaScript-Referenz

Signatur

interface RTCIceTransport extends EventTarget

Beschreibung

RTCIceTransport beschreibt die unterste Transportschicht einer WebRTC-Verbindung. Über sie laufen die Pakete, nachdem ICE (Interactive Connectivity Establishment) einen funktionierenden Netzwerkpfad zwischen den Gegenstellen gefunden hat. Man erstellt die Schnittstelle nicht selbst. Man erreicht sie über RTCDtlsTransport.iceTransport, also zum Beispiel über sender.transport.iceTransport, receiver.transport.iceTransport oder pc.sctp.transport.iceTransport.

Wichtige Eigenschaften (alle schreibgeschützt):

state: aktueller ICE-Zustand dieses Transports: "new", "checking", "connected", "completed", "disconnected", "failed" oder "closed".
gatheringState: Stand der Kandidatensammlung: "new", "gathering" oder "complete".
role: ICE-Rolle, entweder "controlling" oder "controlled".
component: "rtp" oder "rtcp". Bei gebündelten Verbindungen mit RTCP-Mux ist das praktisch immer "rtp".

Methoden: getSelectedCandidatePair() gibt das aktuell genutzte Kandidatenpaar zurück ({ local, remote } aus RTCIceCandidate-Objekten) oder null. getLocalCandidates() und getRemoteCandidates() liefern die gesammelten Kandidaten. getLocalParameters() und getRemoteParameters() liefern RTCIceParameters (usernameFragment, password).

Ereignisse: statechange, gatheringstatechange und selectedcandidatepairchange. Sie lassen sich mit addEventListener() oder über die Eigenschaften onstatechange, ongatheringstatechange und onselectedcandidatepairchange abonnieren. Typische Anwendungsfälle sind Diagnose-Tools, die Anzeige der Verbindungsart (direkt, über STUN oder über ein TURN-Relay) und eine genauere Fehlerbehandlung pro Transport als mit RTCPeerConnection.iceConnectionState.

Rückgabewert

Typ

RTCIceTransport

Beschreibung

Wird nicht über einen Konstruktor erzeugt, sondern über RTCDtlsTransport.iceTransport abgerufen.

Beispiele

ICE-Transport einer Verbindung abrufen

const pc = new RTCPeerConnection({
  iceServers: [{ urls: 'stun:stun.l.google.com:19302' }]
});
const stream = await navigator.mediaDevices.getUserMedia({ audio: true });
const sender = pc.addTrack(stream.getAudioTracks()[0], stream);

await pc.setLocalDescription(await pc.createOffer());

// transport ist erst nach setLocalDescription verfügbar
const iceTransport = sender.transport?.iceTransport;
console.log(iceTransport?.state, iceTransport?.gatheringState);

new gathering

Zustandsänderungen überwachen (addEventListener und on-Property)

const iceTransport = pc.getSenders()[0].transport.iceTransport;

const onState = () => {
  console.log('ICE-Zustand:', iceTransport.state);
  if (iceTransport.state === 'failed') {
    pc.restartIce(); // ICE-Neustart anstoßen
  }
};
iceTransport.addEventListener('statechange', onState);

// Alternativ über die on-Property
iceTransport.ongatheringstatechange = () => {
  console.log('Sammlung:', iceTransport.gatheringState);
};

// Aufräumen beim Beenden
pc.addEventListener('connectionstatechange', () => {
  if (pc.connectionState === 'closed') {
    iceTransport.removeEventListener('statechange', onState);
  }
});

Sammlung: complete ICE-Zustand: checking ICE-Zustand: connected

Verbindungsart anhand des gewählten Kandidatenpaars erkennen

const describePair = (iceTransport) => {
  const pair = iceTransport.getSelectedCandidatePair?.();
  if (!pair) return 'Noch kein Kandidatenpaar gewählt';
  const viaRelay = pair.local.type === 'relay' || pair.remote.type === 'relay';
  return `${pair.local.type} ⇄ ${pair.remote.type} (${pair.local.protocol})` +
    (viaRelay ? ' – über TURN-Relay' : ' – direkt/STUN');
};

const iceTransport = pc.sctp?.transport.iceTransport
  ?? pc.getSenders()[0]?.transport?.iceTransport;

iceTransport.addEventListener('selectedcandidatepairchange', () => {
  console.log(describePair(iceTransport));
});

host ⇄ srflx (udp) – direkt/STUN

// Wichtig · Fallstricke

Verfügbarkeit: sender.transport bzw. receiver.transport ist null, solange keine lokale oder entfernte Beschreibung gesetzt wurde. Vorher gibt es keinen RTCIceTransport.
Browser-Kompatibilität: Chromium-Browser und Safari unterstützen die Schnittstelle schon lange. Firefox unterstützt sie erst in neueren Versionen und nicht vollständig. Auch in Chromium fehlen einzelne Methoden, etwa getLocalCandidates() oder getRemoteCandidates(). Prüfe Methoden deshalb vor dem Aufruf, z. B. mit typeof t.getSelectedCandidatePair === 'function' oder mit optionalem Aufruf ?.(). Als Rückfall eignet sich pc.getStats() mit den Einträgen vom Typ candidate-pair.
Bundling: Bei bundlePolicy: "max-bundle" (Standard in modernen Browsern) teilen sich alle Sender, Empfänger und der Datenkanal einen Transport. Ein Listener genügt dann.
Zustand "disconnected" ist oft nur vorübergehend, etwa bei einem Netzwechsel. Starte ICE erst bei "failed" neu.
Datenschutz: Kandidaten können lokale und öffentliche IP-Adressen enthalten. Gib sie nicht ungefiltert an Dritte oder in Logs weiter. Browser verschleiern lokale Adressen teilweise per mDNS (*.local).

Siehe auch

RTCSctpTransport RTCDtlsTransport WebTransport RTCIceCandidate RTCIceParameters