initial commit

1 files changed, 146 insertions, 0 deletions

diff --git a/files/zh-cn/web/api/rtcpeerconnection/createdatachannel/index.html b/files/zh-cn/web/api/rtcpeerconnection/createdatachannel/index.html
new file mode 100644
index 0000000000..35f2d35441
--- /dev/null
+++ b/files/zh-cn/web/api/rtcpeerconnection/createdatachannel/index.html
@@ -0,0 +1,146 @@
+---
+title: RTCPeerConnection.createDataChannel()
+slug: Web/API/RTCPeerConnection/createDataChannel
+translation_of: Web/API/RTCPeerConnection/createDataChannel
+---
+<p>{{APIRef("WebRTC")}}{{SeeCompatTable}}</p>
+
+<p>{{domxref("RTCPeerConnection")}} 的 <code>createDataChannel()</code> 方法创建一个可以发送任意数据的数据通道(data channel)。常用于后台传输内容, 例如: 图像, 文件传输, 聊天文字, 游戏数据更新包, 等等。</p>
+
+<p>基于某个连接创建第一个data channel时, 会通过发送一个{{event("negotiationneeded")}} event来开始重新谈判(renegotiation)。</p>
+
+<h2 id="语法">语法</h2>
+
+<pre class="syntaxbox"><em>dataChannel</em> = <em>RTCPeerConnection</em>.createDataChannel(<em>label</em>[, <em>options</em>]);</pre>
+
+<h3 class="syntaxbox" id="参数">参数</h3>
+
+<dl>
+ <dt><code>label</code></dt>
+ <dd>一个便于理解的通道名. 该字符串不能长于 65,535 <em>字节</em>.</dd>
+ <dt><code>options</code> {{optional_inline}}</dt>
+ <dd>提供data channel设置的一个 <a href="#RTCDataChannelInit_dictionary"><code>RTCDataChannelInit</code> dictionary</a> </dd>
+</dl>
+
+<h3 id="RTCDataChannelInit_dictionary">RTCDataChannelInit dictionary</h3>
+
+<p><code>RTCDataChannelInit</code> 字典提供以下字段, 用以构造可选的options参数来设置data channel以满足你的需求:</p>
+
+<dl>
+ <dt><code>ordered</code> {{optional_inline}}</dt>
+ <dd>表示通过 {{domxref("RTCDataChannel")}} 的信息的到达顺序需要和发送顺序一致(<code>true</code>), 或者到达顺序不需要和发送顺序一致 (<code>false</code>). <strong>默认: <code>true</code>.</strong></dd>
+ <dt><strong><code>maxPacketLifeTime</code> {{optional_inline}}</strong></dt>
+ <dd>The maximum number of milliseconds that attempts to transfer a message may take in unreliable mode. While this value is a 16-bit unsigned number, each user agent may clamp it to whatever maximum it deems appropriate. <strong>Default: <code>null</code>.</strong></dd>
+ <dt><code>maxRetransmits</code> {{optional_inline}}</dt>
+ <dd>The maximum number of times the user agent should attempt to retransmit a message which fails the first time in unreliable mode. While this value is a16-bit unsigned number, each user agent may clamp it to whatever maximum it deems appropriate. <strong>Default: <code>null</code>.</strong></dd>
+ <dt><code>protocol</code> {{optional_inline}}</dt>
+ <dd>The name of the sub-protocol being used on the {{domxref("RTCDataChannel")}}, if any; otherwise, the empty string (""). <strong>Default: empty string, <code>""</code>. </strong> This string may not be longer than 65,535 <em>bytes</em>.</dd>
+ <dt><code>negotiated</code> {{optional_inline}}</dt>
+ <dd>By default (<code>false</code>), data channels are negotiated in-band, where one side calls <code>createDataChannel</code>, and the other side listens to the {{domxref("RTCDataChannelEvent")}} event using the <code>ondatachannel</code> <code>EventHandler</code> . Alternatively (<code>true</code>), they can be negotiated out of-band, where both sides call <code>createDataChannel </code>with an agreed-upon id. <strong>Default: <code>false</code>.</strong></dd>
+ <dt><code>id</code> {{optional_inline}}</dt>
+ <dd>An 16-bit numeric ID for the channel; permitted values are 0-65534. If you don't include this option, the user agent will select an ID for you.</dd>
+</dl>
+
+<div class="note">
+<p>The options which can be configured using the <code>RTCDataChannelInit</code> dictionary represent the script-settable subset of the properties on the {{domxref("RTCDataChannel")}} interface.</p>
+</div>
+
+<h3 id="Return_value">Return value</h3>
+
+<p>A new {{domxref("RTCDataChannel")}} object with the specified <code>label</code>, configured using the options specified by <code>options</code> if that parameter is included; otherwise, the defaults listed above are established.</p>
+
+<h3 id="Exceptions">Exceptions</h3>
+
+<dl>
+ <dt><code>InvalidStateError</code></dt>
+ <dd>The {{domxref("RTCPeerConnection")}} is closed.</dd>
+ <dt><code>TypeError</code></dt>
+ <dd>This can happen in a couple of situations:
+ <ul>
+  <li>The label and/or protocol string is too long; these cannot be longer than 65,535 bytes (bytes, rather than characters).</li>
+  <li>The <code>id</code> is 65535. While this is a valid unsigned 16-bit value, it's not a permitted value for <code>id</code>.</li>
+ </ul>
+ </dd>
+ <dt><code>SyntaxError</code></dt>
+ <dd>Values were specified for both the <code>maxPacketLifeTime</code> and <code>maxRetransmits</code> options. You may only specify a non-<code>null</code> value for one of these.</dd>
+ <dt><code>ResourceInUse</code></dt>
+ <dd>An <code>id</code> was specified, but another {{domxref("RTCDataChannel")}} is already using the same value.</dd>
+ <dt><code>OperationError</code></dt>
+ <dd>Either the specified <code>id</code> is already in use or, if no <code>id</code> was specified, the WebRTC layer was unable to automatically generate an ID because all IDs are in use.</dd>
+</dl>
+
+<h2 id="Examples">Examples</h2>
+
+<p>This example shows how to create a data channel and set up handlers for the {{event("open")}} and {{event("message")}} events to send and receive messages on it (For brievity, the example assumes onnegotiationneeded is set up).</p>
+
+<pre class="brush: js">// Offerer side
+
+var pc = new RTCPeerConnection(options);
+var channel = pc.createDataChannel("chat");
+channel.onopen = function(event) {
+  channel.send('Hi you!');
+}
+channel.onmessage = function(event) {
+  console.log(event.data);
+}</pre>
+
+<pre class="brush: js">// Answerer side
+
+var pc = new RTCPeerConnection(options);
+pc.ondatachannel = function(event) {
+  var channel = event.channel;
+  channel.onopen = function(event) {
+    channel.send('Hi back!');
+  }
+  channel.onmessage = function(event) {
+    console.log(event.data);
+  }
+}</pre>
+
+<p>Alternatively, more symmetrical out-of-band negotiation can be used, using an agreed-upon id (0 here):</p>
+
+<pre class="brush: js">// Both sides
+
+var pc = new RTCPeerConnection(options);
+var channel = pc.createDataChannel("chat", {negotiated: true, id: 0});
+channel.onopen = function(event) {
+  channel.send('Hi!');
+}
+channel.onmessage = function(event) {
+  console.log(event.data);
+}</pre>
+
+<p>For a more thorough example showing how the connection and channel are established, see <a href="/en-US/docs/Web/API/WebRTC_API/Simple_RTCDataChannel_sample">A simple RTCDataChannel sample</a>.</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', '#widl-RTCPeerConnection-createDataChannel-RTCDataChannel-DOMString-label-RTCDataChannelInit-dataChannelDict', 'createDataChannel()')}}</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.createDataChannel")}}</p>
+</div>
+
+<h2 id="See_also">See also</h2>
+
+<ul>
+ <li>{{domxref("RTCDataChannel")}}</li>
+ <li><a href="/en-US/docs/Web/API/WebRTC_API/Simple_RTCDataChannel_sample">A simple RTCDataChannel sample</a></li>
+ <li>{{domxref("RTCPeerConnection")}}</li>
+</ul>