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 January 2020.

Die setConfiguration() Methode der RTCPeerConnection Schnittstelle setzt die aktuelle Konfiguration der Verbindung basierend auf den Werten des angegebenen Objekts. Dies ermöglicht es Ihnen, die von der Verbindung verwendeten ICE-Server und die zu verwendenden Transport-Richtlinien zu ändern.

Der häufigste Anwendungsfall für diese Methode (und selbst dann ist es wahrscheinlich kein sehr häufiger Anwendungsfall) ist der Austausch des Satzes von zu verwendenden ICE-Servern. Zwei mögliche Szenarien, in denen dies geschehen könnte:

  • Die RTCPeerConnection wurde ohne Angabe von ICE-Servern instanziiert. Wenn beispielsweise der RTCPeerConnection() Konstruktor ohne Parameter aufgerufen wurde, müssten Sie setConfiguration() aufrufen, um ICE-Server hinzuzufügen, bevor die ICE-Aushandlung beginnen kann.
  • Eine Neuverhandlung der Verbindung ist erforderlich, und aus irgendeinem Grund muss ein anderer Satz 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 diesem Fall könnte man setConfiguration() aufrufen, um auf neue regionale ICE-Server zu wechseln, und dann einen ICE-Neustart initiieren.

Hinweis: Sie können die Identitätsinformationen für eine Verbindung nicht ändern, nachdem sie bereits festgelegt wurden.

Syntax

js
setConfiguration(configuration)

Parameter

configuration

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

Ausnahmen

InvalidAccessError DOMException

Wird ausgelöst, wenn eine oder mehrere der in configuration.iceServers angegebenen URLs ein TURN Server ist, aber vollständige Anmeldeinformationen nicht bereitgestellt wurden (d.h. entweder der username oder das credential fehlt, oder wenn credentialType "password" ist und credential kein String ist). Dies verhindert eine erfolgreiche Anmeldung beim Server.

InvalidModificationError DOMException

Wird ausgelöst, wenn die configuration geänderte Identitätsinformationen enthält, die Verbindung jedoch bereits Identitätsinformationen spezifiziert hat. Dies passiert, wenn configuration.peerIdentity oder configuration.certificates gesetzt sind und ihre Werte von der aktuellen Konfiguration abweichen. Dies kann auch ausgelöst werden, wenn es Änderungen an configuration.bundlePolicy oder configuration.rtcpMuxPolicy gibt, oder an configuration.iceCandidatePoolSize, wenn RTCPeerConnection.setLocalDescription() bereits aufgerufen wurde.

InvalidStateError DOMException

Wird ausgelöst, wenn die RTCPeerConnection geschlossen ist.

SyntaxError DOMException

Wird ausgelöst, wenn 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 die Aushandlung mit einem anderen ICE-Server durchgeführt werden muss.

js
const restartConfig = {
  iceServers: [
    {
      urls: "turn:asia.turn-server.net",
      username: "allie@oopcode.com",
      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);

Zuerst wird ein neues Objekt restartConfig erstellt, welches den neuen ICE-Server und dessen Anmeldedaten spezifiziert. Dieses wird dann an setConfiguration() übergeben. Die ICE-Aushandlung wird durch Aufruf von restartIce() neu gestartet, was dazu führt, dass das nächste erstellte Angebot die neuen ICE-Serverinformationen enthält. Von dort aus wird der Prozess wie gewohnt fortgesetzt, indem die lokale Beschreibung auf das zurückgegebene Angebot gesetzt und dieses Angebot an den anderen Beteiligten gesendet wird.

Spezifikationen

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

Browser-Kompatibilität

BCD tables only load in the browser

Siehe auch