RTCPeerConnection: restartIce()-Methode

Baseline Widely available

This feature is well established and works across many devices and browser versions. It’s been available across browsers since January 2020.

Die restartIce()-Methode des RTCPeerConnection-Interfaces ermöglicht es einer Webanwendung, dass die Erfassung der ICE-Kandidaten an beiden Enden der Verbindung erneut durchgeführt wird. Dies vereinfacht den Prozess, da dieselbe Methode sowohl vom Anrufer als auch vom Empfänger verwendet werden kann, um einen ICE-Neustart auszulösen.

Nachdem restartIce() zurückgegeben wird, ist das Angebot, das durch den nächsten Aufruf von createOffer() zurückgegeben wird, automatisch so konfiguriert, dass es den ICE-Neustart sowohl am lokalen Teilnehmer (sobald dieser gesetzt wurde) als auch am entfernten Teilnehmer auslöst, sobald das Angebot über Ihren Signalisierungsmechanismus gesendet und die Beschreibung auch vom entfernten Teilnehmer gesetzt wurde.

restartIce() löst das negotiationneeded-Ereignis auf dem RTCPeerConnection aus, um die Anwendung darüber zu informieren, dass sie eine Verhandlung über ihren Signalisierungskanal durchführen sollte.

Wenn die Verhandlung nicht abgeschlossen werden kann - entweder aufgrund eines Rollbacks oder weil eingehende Angebote gerade verhandelt werden - wird sich das RTCPeerConnection merken, dass Sie einen ICE-Neustart angefordert haben. Das nächste Mal, wenn sich der signalingState der Verbindung auf stable ändert, wird das Verbindung das negotiationneeded-Ereignis auslösen. Dieser Prozess setzt sich fort, bis ein ICE-Neustart erfolgreich durchgeführt wurde.

Syntax

js
restartIce()

Parameter

Keine.

Rückgabewert

Keiner (undefined).

Anwendungshinweise

Nach dem Aufruf von restartIce() wird das nächste Angebot, das mit createOffer() erstellt wird, den ICE-Neustart einleiten, sobald es über Ihren Signalisierungsmechanismus an den entfernten Teilnehmer gesendet wird. Ein Neustart von ICE setzt im Wesentlichen ICE zurück, sodass alle neuen Kandidaten unter Verwendung neuer Anmeldeinformationen erstellt werden. Bestehende Medienübertragungen werden während dieses Prozesses nicht unterbrochen.

Für Details darüber, wie ein ICE-Neustart funktioniert, siehe ICE restart und RFC 5245, Abschnitt 9.1.1.1: ICE-Spezifikation.

Beispiele

Dieses Beispiel erstellt einen Handler für das iceconnectionstatechange-Ereignis, der einen Übergang in den Zustand failed behandelt, indem er ICE neustartet, um es erneut zu versuchen.

js
pc.addEventListener("iceconnectionstatechange", (event) => {
  if (pc.iceConnectionState === "failed") {
    /* possibly reconfigure the connection in some way here */
    /* then request ICE restart */
    pc.restartIce();
  }
});

Mit diesem Code wird bei einem Übergang in den failed-Zustand während der ICE-Verhandlung ein negotiationneeded-Ereignis ausgelöst, auf das Ihr Code wie gewohnt durch eine Neuverhandlung reagieren sollte. Da Sie jedoch restartIce() aufgerufen haben, wird Ihr Aufruf von createOffer(), der im Handler für negotiationneeded erfolgt, eher einen ICE-Neustart als nur eine normale Neuverhandlung auslösen.

Spezifikationen

Specification
WebRTC: Real-Time Communication in Browsers
# dom-rtcpeerconnection-restartice

Browser-Kompatibilität

BCD tables only load in the browser

Siehe auch