RTCPeerConnection.createDataChannel()
Baseline Widely available
This feature is well established and works across many devices and browser versions. It’s been available across browsers since January 2020.
RTCPeerConnection
的 createDataChannel()
方法创建一个可以发送任意数据的数据通道 (data channel)。常用于后台传输内容,例如:图像,文件传输,聊天文字,游戏数据更新包,等等。
基于某个连接创建第一个 data channel 时,会通过发送一个 negotiationneeded
事件来开始重新谈判(renegotiation)。
语法
createDataChannel(label)
createDataChannel(label, options)
参数
label
-
一个便于理解的通道名。该字符串不能长于 65,535 字节.
options
可选-
提供 data channel 设置的一个
RTCDataChannelInit
dictionary
RTCDataChannelInit dictionary
RTCDataChannelInit
字典提供以下字段,用以构造可选的 options 参数来设置 data channel 以满足你的需求:
ordered
可选-
表示通过
RTCDataChannel
的信息的到达顺序需要和发送顺序一致 (true
), 或者到达顺序不需要和发送顺序一致 (false
). 默认:true
. maxPacketLifeTime
可选-
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. Default:
null
. maxRetransmits
可选-
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. Default:
null
. protocol
可选-
The name of the sub-protocol being used on the
RTCDataChannel
, if any; otherwise, the empty string (""). Default: empty string,""
. This string may not be longer than 65,535 bytes. negotiated
可选-
By default (
false
), data channels are negotiated in-band, where one side callscreateDataChannel
, and the other side listens to theRTCDataChannelEvent
event using theondatachannel
EventHandler
. Alternatively (true
), they can be negotiated out of-band, where both sides callcreateDataChannel
with an agreed-upon id. Default:false
. id
可选-
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.
备注:The options which can be configured using the RTCDataChannelInit
dictionary represent the script-settable subset of the properties on the RTCDataChannel
interface.
Return value
A new RTCDataChannel
object with the specified label
, configured using the options specified by options
if that parameter is included; otherwise, the defaults listed above are established.
Exceptions
InvalidStateError
-
The
RTCPeerConnection
is closed. TypeError
-
This can happen in a couple of situations:
- The label and/or protocol string is too long; these cannot be longer than 65,535 bytes (bytes, rather than characters).
- The
id
is 65535. While this is a valid unsigned 16-bit value, it's not a permitted value forid
.
SyntaxError
-
Values were specified for both the
maxPacketLifeTime
andmaxRetransmits
options. You may only specify a non-null
value for one of these. ResourceInUse
-
An
id
was specified, but anotherRTCDataChannel
is already using the same value. OperationError
-
Either the specified
id
is already in use or, if noid
was specified, the WebRTC layer was unable to automatically generate an ID because all IDs are in use.
Examples
This example shows how to create a data channel and set up handlers for the open
and message
events to send and receive messages on it (For brievity, the example assumes onnegotiationneeded is set up).
// 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);
};
// 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);
};
};
Alternatively, more symmetrical out-of-band negotiation can be used, using an agreed-upon id (0 here):
// 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);
};
For a more thorough example showing how the connection and channel are established, see A simple RTCDataChannel sample.
Specifications
Specification |
---|
WebRTC: Real-Time Communication in Browsers # dom-peerconnection-createdatachannel |
Browser compatibility
BCD tables only load in the browser