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
|
---
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>
{{Compat("api.RTCPeerConnection.addIceCandidate")}}
<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>
|
