1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
|
---
title: RTCPeerConnection.setConfiguration()
slug: Web/API/RTCPeerConnection/setConfiguration
translation_of: Web/API/RTCPeerConnection/setConfiguration
---
<p>{{APIRef("WebRTC")}}{{SeeCompatTable}}</p>
<p>The <strong><code>RTCPeerConnection.setConfiguration()</code></strong> method sets the current configuration of the {{domxref("RTCPeerConnection")}} based on the values included in the specified {{domxref("RTCConfiguration")}} object. This lets you change the ICE servers used by the connection and which transport policies to use.</p>
<p>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:</p>
<ul>
<li>The {{domxref("RTCPeerConnection")}} was instantiated without specifying any ICE servers. If, for example, the {{domxref("RTCPeerConnection.RTCPeerConnection()", "RTCPeerConnection()")}} constructor was called with no parameters, you would have to then call <code>setConfiguration()</code> to add ICE servers before ICE negotiation could begin.</li>
<li>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 <code>setConfiguration()</code> to switch to new regional ICE servers, then initiate an <a href="/en-US/docs/Web/API/WebRTC_API/Session_lifetime#ICE_restart">ICE restart</a>.</li>
</ul>
<div class="note">
<p>You cannot change the identity information for a connection once it's already been set.</p>
</div>
<h2 id="语法">语法</h2>
<pre class="syntaxbox notranslate"><em>RTCPeerConnection</em>.setConfiguration(<em>configuration</em>);</pre>
<h3 class="syntaxbox" id="参数">参数</h3>
<dl>
<dt><code>configuration</code></dt>
<dd>{{domxref("RTCConfiguration")}}对象提供一些可以设置的选项。这些选项的改动不会附加到原来的设置，相反，新的选项会完全替代旧的选项。</dd>
</dl>
<h3 id="异常">异常</h3>
<dl>
<dt><code>InvalidAccessError</code></dt>
<dd>One or more of the URLs specified in <code>configuration.iceServers</code> is a {{Glossary("TURN")}} server, but complete login information is not provided (that is, either the {{domxref("RTCIceServer.username")}} or {{domxref("RTCIceServer.credentials")}} is missing). This prevents successful login to the server.</dd>
<dt><code>InvalidModificationError</code></dt>
<dd>The <code>configuration</code> includes changed identity information, but the connection already has identity information specified. This happens if <code>configuration.peerIdentity</code> or <code>configuration.certificates</code> is set and their values differ from the current configuration.</dd>
<dt><code>InvalidStateError</code></dt>
<dd>{{domxref("RTCPeerConnection")}} 被关闭.</dd>
<dt><code>SyntaxError</code></dt>
<dd><code>configuration.iceServers</code> 列表提供的一个或多个URL是无效的</dd>
</dl>
<h2 id="Example">Example</h2>
<p>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.</p>
<pre class="brush: js notranslate">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);</pre>
<p>First, a new {{domxref("RTCConfiguration")}} is created, <code>restartConfig</code>, specifying the new ICE server and its credentials. This is then passed into <code>setConfiguration()</code>. ICE negotiation is restarted by calling {{domxref("RTCPeerConnection.createOffer()", "createOffer()")}}, specifying <code>true</code> as the value of the <code>iceRestart</code> 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.</p>
<h2 id="Specifications">Specifications</h2>
<table class="standard-table">
<tbody>
<tr>
<th scope="col">Specification</th>
<th scope="col">Status</th>
<th scope="col">Comment</th>
</tr>
<tr>
<td>{{SpecName('WebRTC 1.0', '#dom-rtcpeerconnection-setconfiguration', 'setConfiguration()')}}</td>
<td>{{Spec2('WebRTC 1.0')}}</td>
<td>Initial definition.</td>
</tr>
</tbody>
</table>
<h2 id="Browser_compatibility">Browser compatibility</h2>
<div>
<p>{{Compat("api.RTCPeerConnection.setConfiguration")}}</p>
</div>
<h2 id="See_also">See also</h2>
<ul>
<li>{{domxref("RTCPeerConnection.getConfiguration()")}}</li>
<li>{{domxref("RTCConfiguration")}}</li>
<li>{{domxref("RTCPeerConnection")}}</li>
</ul>
|
