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 im angegebenen Objekt.
Dies ermöglicht es Ihnen, die von der Verbindung verwendeten ICE-Server und die zu verwendenden Transportpolitiken zu ändern.
Die häufigste Verwendung dieser Methode (und selbst dann wahrscheinlich keine sehr häufige Verwendung) besteht darin, den Satz von ICE-Servern zu ersetzen, die verwendet werden sollen. Zwei mögliche Szenarien, in denen dies geschehen könnte:
-
Die
RTCPeerConnection
wurde instanziiert, ohne dass ICE-Server angegeben wurden. Wenn zum Beispiel derRTCPeerConnection()
Konstruktor ohne Parameter aufgerufen wurde, müssen SiesetConfiguration()
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 hat der Benutzer in eine neue Region gewechselt, sodass es notwendig ist, neue regionale ICE-Server zu verwenden, zum Beispiel.
In dieser Situation könnte man
setConfiguration()
aufrufen, um zu neuen regionalen ICE-Servern zu wechseln und dann ein ICE restart zu initiieren.
Hinweis: Sie können die Identitätsinformationen einer Verbindung nicht ändern, sobald 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 zulässig sind.
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 (d. h. entweder derusername
oder dascredential
fehlt, oder wenncredentialType
"password"
ist undcredential
kein String ist). Dies verhindert eine erfolgreiche Anmeldung beim Server. InvalidModificationError
DOMException
-
Wird ausgelöst, wenn die
configuration
geänderte Identitätsinformationen enthält, aber die Verbindung bereits Identitätsinformationen festgelegt hat. Dies geschieht, wennconfiguration.peerIdentity
oderconfiguration.certificates
festgelegt sind und ihre Werte von der aktuellen Konfiguration abweichen. Diese Ausnahme kann auch ausgelöst werden, wenn es Änderungen anconfiguration.bundlePolicy
oderconfiguration.rtcpMuxPolicy
, oder anconfiguration.iceCandidatePoolSize
gibt, wennRTCPeerConnection.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 dass die Aushandlung mit einem anderen ICE-Server durchgeführt werden muss.
const restartConfig = {
iceServers: [
{
urls: "turn:asia.turn-server.net",
username: "allie@oopcode.com",
credential: "topsecretpassword",
},
],
};
myPeerConnection.setConfiguration(restartConfig);
myPeerConnection
.createOffer({ iceRestart: 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, das den neuen ICE-Server und seine Anmeldeinformationen angibt.
Dieses wird dann an setConfiguration()
übergeben.
Die ICE-Aushandlung wird durch Aufrufen von createOffer()
, wobei true
als Wert für die iceRestart
Option angegeben wird, neu gestartet.
Von dort aus führt man den Prozess wie gewohnt weiter, indem man die lokale Beschreibung auf das zurückgegebene Angebot setzt und dieses Angebot dann an den anderen Teilnehmer sendet.
Spezifikationen
Specification |
---|
WebRTC: Real-Time Communication in Browsers # dom-rtcpeerconnection-setconfiguration |
Browser-Kompatibilität
BCD tables only load in the browser