RTCPeerConnection: setConfiguration() method
The setConfiguration()
method of the RTCPeerConnection
interface sets the current configuration of the connection based on the values included in the specified object.
This lets you change the ICE servers used by the connection and which transport policies to use.
The most common use case for this method (and even then, probably not a very common use case) is to replace the set of ICE servers to be used. Two potential scenarios in which this might be done:
-
The
RTCPeerConnection
was instantiated without specifying any ICE servers. If, for example, theRTCPeerConnection()
constructor was called with no parameters, you would have to then callsetConfiguration()
to add ICE servers before ICE negotiation could begin. -
Renegotiation of the connection is needed, and a different set of ICE servers needs to be used for some reason.
Perhaps the user has moved into a new region, so using new regional ICE servers is necessary, for example.
In this situation, one might call
setConfiguration()
to switch to new regional ICE servers, then initiate an ICE restart.
Note: You cannot change the identity information for a connection once it's already been set.
Syntax
setConfiguration(configuration)
Parameters
configuration
-
An object which provides the options to be set. The changes are not additive; instead, the new values completely replace the existing ones. See
RTCPeerConnection()
for more information on what options are allowed.
Exceptions
InvalidAccessError
DOMException
-
Thrown if one or more of the URLs specified in
configuration.iceServers
is a TURN server, but complete login information is not provided (that is, either theusername
orcredential
is missing, or ifcredentialType
is"password"
andcredential
is not a string). This prevents successful login to the server. InvalidModificationError
DOMException
-
Thrown if the
configuration
includes changed identity information, but the connection already has identity information specified. This happens ifconfiguration.peerIdentity
orconfiguration.certificates
are set and their values differ from the current configuration. This may also be thrown if there are changes toconfiguration.bundlePolicy
orconfiguration.rtcpMuxPolicy
, or toconfiguration.iceCandidatePoolSize
whenRTCPeerConnection.setLocalDescription()
has already been called. InvalidStateError
DOMException
-
Thrown if the
RTCPeerConnection
is closed. SyntaxError
DOMException
-
Thrown if the
configuration.iceServers
contains no URLs or if one of the values in the list is invalid. NotSupportedError
DOMException
-
Thrown if
configuration.iceServers
contains a URL with a scheme that is not supported.
Example
In this example, it has already been determined that ICE restart is needed, and that negotiation needs to be done using a different ICE server.
const restartConfig = {
iceServers: [
{
urls: "turn:asia.myturnserver.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);
First, a new object is created, restartConfig
, specifying the new ICE server and its credentials.
This is then passed into setConfiguration()
.
ICE negotiation is restarted by calling createOffer()
, specifying true
as the value of the iceRestart
option.
From there, we handle the process as usual, by setting the local description to the returned offer and then sending that offer to the other peer.
Specifications
Specification |
---|
WebRTC: Real-Time Communication in Browsers # dom-rtcpeerconnection-setconfiguration |
Browser compatibility
BCD tables only load in the browser