RTCPeerConnection: setConfiguration() Methode

Baseline Widely available

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

Die setConfiguration() Methode der RTCPeerConnection Schnittstelle setzt die aktuelle Konfiguration der Verbindung basierend auf den in dem angegebenen Objekt enthaltenen Werten. Dies ermöglicht es Ihnen, die von der Verbindung verwendeten ICE-Server sowie die zu verwendenden Transportprotokoll-Richtlinien zu ändern.

Der häufigste Anwendungsfall für diese Methode (und selbst dann wahrscheinlich kein sehr häufiger Anwendungsfall) besteht darin, die Menge der zu verwendenden ICE-Server zu ersetzen. Zwei mögliche Szenarien, in denen dies geschehen könnte:

Die RTCPeerConnection wurde erstellt, ohne irgendwelche ICE-Server anzugeben. Wenn zum Beispiel der RTCPeerConnection() Konstruktor ohne Parameter aufgerufen wurde, müssten Sie setConfiguration() aufrufen, um ICE-Server hinzuzufügen, bevor die ICE-Verhandlung beginnen kann.
Eine Neuaushandlung der Verbindung ist erforderlich, und es muss aus irgendeinem Grund eine andere Menge von ICE-Servern verwendet werden. Vielleicht ist der Benutzer in eine neue Region umgezogen, daher ist es notwendig, neue regionale ICE-Server zu verwenden. In dieser Situation könnte man setConfiguration() aufrufen, um zu neuen regionalen ICE-Servern zu wechseln und dann einen ICE-Neustart zu initiieren.

Hinweis: Sie können die Identitätsinformationen einer Verbindung nicht ändern, wenn sie bereits festgelegt wurden.

Syntax

setConfiguration(configuration)

Parameter

configuration: Ein Objekt, das die festzulegenden Optionen bereitstellt. Die Änderungen sind nicht additiv; stattdessen ersetzen die neuen Werte die vorhandenen vollständig. Siehe RTCPeerConnection() für weitere Informationen darüber, welche Optionen erlaubt sind.

Rückgabewert

Keiner (undefined).

Ausnahmen

InvalidAccessError DOMException: Wird ausgelöst, wenn eine oder mehrere der in configuration.iceServers angegebenen URLs ein TURN Server sind, aber keine vollständigen Anmeldeinformationen bereitgestellt werden (das heißt, entweder der username oder das credential fehlt, oder wenn credentialType "password" ist und credential kein String ist). Dies verhindert eine erfolgreiche Anmeldung am Server.
InvalidModificationError DOMException: Wird ausgelöst, wenn die configuration geänderte Identitätsinformationen enthält, aber die Verbindung bereits Identitätsinformationen spezifiziert hat. Dies geschieht, wenn configuration.peerIdentity oder configuration.certificates gesetzt sind und ihre Werte von der aktuellen Konfiguration abweichen. Dies kann auch ausgelöst werden, wenn Änderungen an configuration.bundlePolicy oder configuration.rtcpMuxPolicy oder an configuration.iceCandidatePoolSize vorgenommen werden, wenn RTCPeerConnection.setLocalDescription() bereits aufgerufen wurde.
InvalidStateError DOMException: Wird ausgelöst, wenn die RTCPeerConnection geschlossen ist.
SyntaxError DOMException: Wird ausgelöst, wenn die configuration.iceServers keine URLs enthält oder wenn einer der Werte in der Liste ungültig ist.
NotSupportedError DOMException: Wird ausgelöst, wenn configuration.iceServers eine URL mit einem nicht unterstützten Schema enthält.

Beispiel

In diesem Beispiel wurde bereits festgestellt, dass ein ICE-Neustart erforderlich ist und dass die Verhandlung mit einem anderen ICE-Server durchgeführt werden muss.

const restartConfig = {
  iceServers: [
    {
      urls: "turn:asia.turn-server.net",
      username: "[email protected]",
      credential: "topsecretpassword",
    },
  ],
};

myPeerConnection.setConfiguration(restartConfig);

myPeerConnection.restartIce();

myPeerConnection
  .createOffer() // restartIce() causes iceRestart to be set true
  .then((offer) => myPeerConnection.setLocalDescription(offer))
  .then(() => {
    // send the offer to the other peer using the signaling server
  })
  .catch(window.reportError);

Zunächst wird ein neues Objekt restartConfig erstellt, das den neuen ICE-Server und seine Anmeldeinformationen spezifiziert. Dies wird dann an setConfiguration() übergeben. Die ICE-Verhandlung wird durch den Aufruf von restartIce() neu gestartet, was dazu führt, dass das nächste erstellte Angebot die neuen ICE-Serverinformationen enthält. Von dort aus bearbeiten wir den Prozess wie gewohnt, indem die lokale Beschreibung auf das zurückgegebene Angebot gesetzt und dieses Angebot dann an den anderen Teilnehmer gesendet wird.

Spezifikationen

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