RTCPeerConnection.setConfiguration()

翻译不完整。 请帮助我们翻译这篇文章!

这是一个实验中的功能
此功能某些浏览器尚在开发中,请参考浏览器兼容性表格以得到在不同浏览器中适合使用的前缀。由于该功能对应的标准文档可能被重新修订,所以在未来版本的浏览器中该功能的语法和行为可能随之改变。

The RTCPeerConnection.setConfiguration() method sets the current configuration of the RTCPeerConnection based on the values included in the specified RTCConfiguration 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, the RTCPeerConnection() constructor was called with no parameters, you would have to then call setConfiguration() 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.

You cannot change the identity information for a connection once it's already been set.

语法

RTCPeerConnection.setConfiguration(configuration);

参数

configuration
RTCConfiguration对象提供一些可以设置的选项。这些选项的改动不会附加到原来的设置,相反,新的选项会完全替代旧的选项。

异常

InvalidAccessError
One or more of the URLs specified in configuration.iceServers is a TURN server, but complete login information is not provided (that is, either the RTCIceServer.username or RTCIceServer.credentials is missing). This prevents successful login to the server.
InvalidModificationError
The configuration includes changed identity information, but the connection already has identity information specified. This happens if configuration.peerIdentity or configuration.certificates is set and their values differ from the current configuration.
InvalidStateError
RTCPeerConnection 被关闭.
SyntaxError
configuration.iceServers 列表提供的一个或多个URL是无效的

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.

var restartConfig = { iceServers: [{
                          urls: "turn:asia.myturnserver.net",
                          username: "allie@oopcode.com",
                          credential: "topsecretpassword"
                      }]
};

myPeerConnection.setConfiguration(restartConfig);

myPeerConnection.createOffer({"iceRestart": true}).then(function(offer) {
  return myPeerConnection.setLocalDescription(offer);
})
.then(function() {
  // send the offer to the other peer using the signaling server
})
.catch(reportError);

First, a new RTCConfiguration 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 Status Comment
WebRTC 1.0: Real-time Communication Between Browsers
setConfiguration()
Candidate Recommendation Initial definition.

Browser compatibility

Update compatibility data on GitHub
DesktopMobile
ChromeEdgeFirefoxInternet ExplorerOperaSafariAndroid webviewChrome for AndroidFirefox for AndroidOpera for AndroidSafari on iOSSamsung Internet
setConfigurationChrome Full support 48Edge Full support ≤18Firefox No support No
Notes
No support No
Notes
Notes See bug 1253706.
IE No support NoOpera Full support 43
Notes
Full support 43
Notes
Notes Promise-based version.
No support 37 — 43
Safari Full support 11WebView Android Full support 48Chrome Android Full support 48Firefox Android No support No
Notes
No support No
Notes
Notes See bug 1253706.
Opera Android Full support 43
Notes
Full support 43
Notes
Notes Promise-based version.
No support 37 — 43
Safari iOS Full support YesSamsung Internet Android Full support 6.0

Legend

Full support  
Full support
No support  
No support
See implementation notes.
See implementation notes.

See also