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
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
|
---
title: RTCPeerConnection.addIceCandidate()
slug: Web/API/RTCPeerConnection/addIceCandidate
translation_of: Web/API/RTCPeerConnection/addIceCandidate
---
<p>{{APIRef("WebRTC")}}{{SeeCompatTable}}</p>
<p><span class="seoSummary">当本机当前页面的 {{domxref("RTCPeerConnection")}} 接收到一个从远端页面通过信号通道发来的新的 ICE 候选地址信息，本机可以通过调用<code><strong>RTCPeerConnection.addIceCandidate()</strong></code> 来添加一个 {{Glossary("ICE")}} 代理。</span> This adds this new remote candidate to the <code>RTCPeerConnection</code>'s remote description, which describes the state of the remote end of the connection.</p>
<p>If the value of the specified object'<code>s</code> {{domxref("RTCIceCandidate.candidate", "candidate")}} is an empty string (<code>""</code>), it signals that all remote candidates have been delivered.</p>
<p>During negotiation, your app will likely receive many candidates which you'll deliver to the ICE agent in this way, allowing it to build up a list of potential connection methods. This is covered in more detail in the articles <a href="/en-US/docs/Web/API/WebRTC_API/Connectivity">WebRTC connectivity</a> and <a href="/en-US/docs/Web/API/WebRTC_API/Signaling_and_video_calling">Signaling and video calling</a>.</p>
<h2 id="Syntax">Syntax</h2>
<pre class="syntaxbox"><em>aPromise </em>= <em>pc</em>.addIceCandidate(<em>candidate</em>);
addIceCandidate(<em>candidate</em>, <em>successCallback</em>, <em>failureCallback</em>); {{deprecated_inline}}
</pre>
<h3 id="Parameters">Parameters</h3>
<dl>
<dt><code>candidate</code></dt>
<dd>An object conforming to the {{domxref("RTCIceCandidateInit")}} dictionary; the contents of the object should be constructed from a message received over the signaling channel, describing a newly received ICE candidate that's ready to be delivered to the local ICE agent.</dd>
</dl>
<h3 id="Deprecated_parameters">Deprecated parameters</h3>
<p>在一些老旧的代码和文档中, 你可能会看到一个回调函数(callback)版本的函数。这种函数是过期的，强烈建议不要使用。你应该更新你的代码，使用 {{jsxref("Promise")}}-版本的 <code>addIceCandidate()</code> . 这个版本的参数格式附在下面, 方便你更新已有的代码.</p>
<dl>
<dt><code>successCallback</code> {{deprecated_inline}}</dt>
<dd>A function to be called when the ICE candidate has been successfully added. This function receives no input parameters and doesn't return a value.</dd>
<dt><code>failureCallback</code> {{deprecated_inline}}</dt>
<dd>A function to be called if attempting to add the ICE candidate fails. Receives as input a {{domxref("DOMException")}} object describing why failure occurred.</dd>
</dl>
<h3 id="Return_value">Return value</h3>
<p>A {{jsxref("Promise")}} which is fulfilled when the candidate has been successfully added to the remote peer's description by the ICE agent. The promise does not receive any input parameters.</p>
<h3 id="Exceptions">Exceptions</h3>
<p>When an error occurs while attempting to add the ICE candidate, the {{jsxref("Promise")}} returned by this method is rejected, returning one of the errors below as the {{domxref("DOMException.name", "name")}} attribute in the specified {{domxref("DOMException")}} object passed to the rejection handler.</p>
<dl>
<dt><code>TypeError</code></dt>
<dd>The specified candidate doesn't have values for both {{domxref("RTCIceCandidate.sdpMid", "sdpMid")}} and {{domxref("RTCIceCandidate.sdpMLineIndex", "sdpMLineIndex")}}.</dd>
<dt><code>InvalidStateError</code></dt>
<dd>The <code>RTCPeerConnection</code> currently has no remote peer established ({{domxref("RTCPeerConnection.remoteDescription", "remoteDescription")}} is <code>null</code>).</dd>
<dt><code>OperationError</code></dt>
<dd>A non-<code>null</code> value was specified for {{domxref("RTCIceCandidate.sdpMid", "sdpMid")}}, but the value doesn't match the mid of any media description in the <code>remoteDescription</code>, or {{domxref("RTCIceCandidate.sdpMLineIndex", "sdpMLineIndex")}} is greater than or equal to the number of media descriptions in <code>remoteDescription</code>. This error can also be thrown if a value is given for {{domxref("RTCIceCandidate.ufrag", "ufrag")}} that doesn't match the value of <code>ufrag</code> in any of the remote description being selected.<br>
<br>
<code>OperationError</code> also occurs if the attempt to add the candidate fails for any other reason.</dd>
</dl>
<h2 id="Example">Example</h2>
<p>下段代码会展示如何使用一个SDP字符串(这个字符串包含了候选的描述)去构建一个候选对象。这个字符串来自于信道(signaling channel)。</p>
<pre class="brush: js">// |receivedSDP| is an SDP string received over the signaling channel
// by our handler for "new ICE candidate" messages.
let candidate = new RTCIceCandidate(receivedSDP);
pc.addIceCandidate(candidate).then(_=>{
// Do stuff when the candidate is successfully passed to the ICE agent
}).catch(e=>{
console.log("Error: Failure during addIceCandidate()");
});</pre>
<h2 id="Specifications">Specifications</h2>
<table class="standard-table">
<thead>
<tr>
<th scope="col">Specification</th>
<th scope="col">Status</th>
<th scope="col">Comment</th>
</tr>
</thead>
<tbody>
<tr>
<td>{{ SpecName('WebRTC 1.0', '#widl-RTCPeerConnection-addIceCandidate-Promise-void--RTCIceCandidateInit-RTCIceCandidate-candidate', 'RTCPeerConnection.addIceCandidate()') }}</td>
<td>{{ Spec2('WebRTC 1.0') }}</td>
<td>Initial specification.</td>
</tr>
<tr>
<td>{{SpecName("WebRTC 1.0", "#widl-RTCPeerConnection-addIceCandidate-void-RTCIceCandidateInit-RTCIceCandidate-candidate-VoidFunction-successCallback-RTCPeerConnectionErrorCallback-failureCallback", "RTCPeerConnection.addIceCandidate()")}} {{deprecated_inline}}</td>
<td>{{Spec2("WebRTC 1.0")}}</td>
<td>Initial specification.</td>
</tr>
</tbody>
</table>
<h2 id="Browser_compatibility">Browser compatibility</h2>
<p>{{ CompatibilityTable}}</p>
<div id="compat-desktop">
<table class="compat-table">
<tbody>
<tr>
<th>Feature</th>
<th>Chrome</th>
<th>Edge</th>
<th>Firefox (Gecko)</th>
<th>Internet Explorer</th>
<th>Opera</th>
<th>Safari</th>
</tr>
<tr>
<td>Basic support</td>
<td>{{ CompatVersionUnknown}}[1]</td>
<td>{{CompatVersionUnknown}}</td>
<td>{{ CompatGeckoDesktop(22) }} [2]</td>
<td>{{ CompatNo}}</td>
<td>{{ CompatVersionUnknown}}</td>
<td>{{ CompatUnknown}}</td>
</tr>
<tr>
<td>Promise-based version</td>
<td>{{CompatChrome(50)}}</td>
<td>{{CompatUnknown}}</td>
<td>{{ CompatGeckoDesktop(37)}}</td>
<td>{{ CompatUnknown}}</td>
<td>{{ CompatUnknown}}</td>
<td>{{ CompatUnknown}}</td>
</tr>
<tr>
<td>{{domxref("RTCIceCandidateInit")}} as input</td>
<td>{{CompatUnknown}}</td>
<td>{{CompatUnknown}}</td>
<td>{{CompatGeckoDesktop(53)}}</td>
<td>{{CompatUnknown}}</td>
<td>{{CompatUnknown}}</td>
<td>{{CompatUnknown}}</td>
</tr>
</tbody>
</table>
</div>
<div id="compat-mobile">
<table class="compat-table">
<tbody>
<tr>
<th>Feature</th>
<th>Android Webview</th>
<th>Chrome for Android</th>
<th>Edge</th>
<th>Firefox Mobile (Gecko)</th>
<th>IE Mobile</th>
<th>Opera Mobile</th>
<th>Safari Mobile</th>
</tr>
<tr>
<td>Basic support</td>
<td>{{ CompatVersionUnknown}}[1]</td>
<td>{{ CompatVersionUnknown}}[1]</td>
<td>{{CompatVersionUnknown}}</td>
<td>{{ CompatGeckoMobile(22)}}</td>
<td>{{ CompatNo}}</td>
<td>{{ CompatUnknown}}</td>
<td>{{ CompatUnknown}}</td>
</tr>
<tr>
<td>Promise-based version</td>
<td>{{CompatChrome(50)}}</td>
<td>{{CompatChrome(50)}}</td>
<td>{{CompatUnknown}}</td>
<td>{{CompatGeckoMobile(37)}}</td>
<td>{{ CompatUnknown}}</td>
<td>{{ CompatUnknown}}</td>
<td>{{ CompatUnknown}}</td>
</tr>
<tr>
<td>{{domxref("RTCIceCandidateInit")}} as input</td>
<td>{{CompatUnknown}}</td>
<td>{{CompatUnknown}}</td>
<td>{{CompatUnknown}}</td>
<td>{{CompatGeckoMobile(53)}}</td>
<td>{{CompatUnknown}}</td>
<td>{{CompatUnknown}}</td>
<td>{{CompatUnknown}}</td>
</tr>
</tbody>
</table>
</div>
<p>[1] Though this method is not prefixed, the interface it belongs to was until Chrome 56.</p>
<p>[2] Though this method is not prefixed, the interface it belongs to was until Firefox 44.</p>
<h2 id="See_also">See also</h2>
<ul>
<li><a href="/en-US/docs/Web/API/WebRTC_API">WebRTC API</a></li>
<li><a href="/en-US/docs/Web/API/WebRTC_API/Signaling_and_video_calling">Signaling and video calling</a></li>
<li><a href="/en-US/docs/Web/API/WebRTC_API/Architecture">WebRTC architecture overview</a></li>
<li><a href="/en-US/docs/Web/API/WebRTC_API/Connectivity">WebRTC connectivity</a></li>
<li><a href="/en-US/docs/Web/API/WebRTC_API/Session_lifetime">Lifetime of a WebRTC session</a></li>
</ul>
|
