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
|
---
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>
|
