initial commit

1 files changed, 203 insertions, 0 deletions

diff --git a/files/zh-cn/web/api/rtcpeerconnection/addicecandidate/index.html b/files/zh-cn/web/api/rtcpeerconnection/addicecandidate/index.html
new file mode 100644
index 0000000000..c648d7aac4
--- /dev/null
+++ b/files/zh-cn/web/api/rtcpeerconnection/addicecandidate/index.html
@@ -0,0 +1,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(_=&gt;{
+  // Do stuff when the candidate is successfully passed to the ICE agent
+}).catch(e=&gt;{
+  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>