RTCPeerConnection：setConfiguration() 方法

setConfiguration() 是 RTCPeerConnection 接口的方法，它根据指定对象中包含的值设置连接的当前配置。这使您可以更改连接使用的 ICE 服务器以及要使用的传输策略。

此方法最常见的用例（即使那样，可能也不是很常见的用例）是替换要使用的 ICE 服务器集。可能会执行此操作的两种潜在场景

  • 在没有指定任何 ICE 服务器的情况下实例化了 RTCPeerConnection。例如，如果 RTCPeerConnection() 构造函数在没有参数的情况下被调用，则您必须在 ICE 协商开始之前调用 setConfiguration() 来添加 ICE 服务器。
  • 需要重新协商连接，并且出于某种原因需要使用不同的 ICE 服务器集。例如，用户可能已移动到新的区域，因此需要使用新的区域 ICE 服务器。在这种情况下，可以使用 setConfiguration() 切换到新的区域 ICE 服务器，然后启动 ICE 重启。

注意：一旦连接被设置，就不能更改连接的标识信息。

语法

js
setConfiguration(configuration)

参数

configuration

提供要设置的选项的对象。更改不是累加的；相反，新值会完全替换现有值。有关允许的选项的更多信息，请参见 RTCPeerConnection()。

异常

InvalidAccessError DOMException

如果 configuration.iceServers 中指定的 URL 之一是 TURN 服务器，但未提供完整的登录信息（即，username 或 credential 丢失，或者如果 credentialType 为 "password" 并且 credential 不是字符串），则会抛出此异常。这将阻止成功登录服务器。

InvalidModificationError DOMException

如果 configuration 包含更改的标识信息，但连接已指定标识信息，则会抛出此异常。如果 configuration.peerIdentity 或 configuration.certificates 被设置并且其值与当前配置不同，则会发生这种情况。如果对 configuration.bundlePolicy 或 configuration.rtcpMuxPolicy 进行了更改，或者在 RTCPeerConnection.setLocalDescription() 已被调用时对 configuration.iceCandidatePoolSize 进行了更改，则也会抛出此异常。

InvalidStateError DOMException

如果 RTCPeerConnection 已关闭，则会抛出此异常。

SyntaxError DOMException

如果 configuration.iceServers 不包含任何 URL 或列表中的某个值无效，则会抛出此异常。

NotSupportedError DOMException

如果 configuration.iceServers 包含一个方案不受支持的 URL，则会抛出此异常。

示例

在此示例中，已经确定需要 ICE 重启，并且需要使用不同的 ICE 服务器进行协商。

js
const restartConfig = {
  iceServers: [
    {
      urls: "turn:asia.myturnserver.net",
      username: "[email protected]",
      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(reportError);

首先，创建一个新对象 restartConfig，指定新的 ICE 服务器及其凭据。然后将其传递给 setConfiguration()。通过调用 createOffer() 来重启 ICE 协商，并将 true 作为 iceRestart 选项的值指定。从那里，我们像往常一样处理该过程，将本地描述设置为返回的提议，然后将该提议发送给另一个对等方。

规范

规范
WebRTC：浏览器中的实时通信
# dom-rtcpeerconnection-setconfiguration

浏览器兼容性

BCD 表格仅在启用 JavaScript 的浏览器中加载。

另请参阅