RTCDataChannel

Experimental: 这是一个实验中的功能
此功能某些浏览器尚在开发中,请参考浏览器兼容性表格以得到在不同浏览器中适合使用的前缀。由于该功能对应的标准文档可能被重新修订,所以在未来版本的浏览器中该功能的语法和行为可能随之改变。

RTCDataChannel接口代表在两者之间建立了一个双向数据通道的连接。

可以用RTCDataChannel.createDataChannel()或者在现有的 RTCPeerConnection上用 RTCDataChannelEvent (en-US)类型的 datachannel 事件接收,创建出 RTCDataChannel类型的对象。

这个API在Gecko中被称作DataChannel而不是标准的'RTCDataChannel'。

属性

RTCDataChannel.label (en-US) 只读
返回一个包含有描述数据通道名字的DOMString。这个字段没有唯一性要求。
RTCDataChannel.ordered (en-US) 只读
返回一个Boolean (en-US)对象,表示传递信息的顺序是否有保证。
RTCDataChannel.protocol (en-US) 只读
返回一个包含有正在使用的子协议的名称的 DOMString,如果没有这样的子协议,返回""
RTCDataChannel.id (en-US) 只读
RTCDataChannel对象被创建出来的时候,返回一个无符号short类型的数据,作为通道的标识id。
RTCDataChannel.readyState (en-US) 只读
返回枚举类型的 RTCDataChannelState,表示数据连接的状态,有以下几种类型:
  • "connecting" 该状态表示底层链路还未建立和激活,该状态还是由RTCPeerConnection.createDataChannel()生成的datachannel初始状态。
  • "open" 该状态表示底层链路已经连接成功并且运行。这个状态还是由RTCDataChannelEvent (en-US)分发的datachannel的初始状态。 
  • "closing" 该状态表示底层链路已经在关闭的过程中。该状态下将不会接受新的发送任务,但是缓冲队列中的消息还是会被继续发送或者接收。
  • "closed" 该状态表示底层链路已经完全被关闭(或者无法处于established状态)。
RTCDataChannel.bufferedAmount (en-US) 只读

返回一个unsigned long,表示缓冲队列中等待发送的字节数。这些数据是通过RTCDataChannel.send() (en-US)添加进缓冲队列但还未被发送的数据请求。注意:就算channel处于closed状态,队列中的缓存还会保持。

RTCDataChannel.binaryType (en-US)

是一个DOMString 类型,表示由链路发送的二进制数据的类型。该项的值应该为"blob"或者"arraybuffer",默认值为"blob"。当值为"blob"的时候,使用Blob对象,当值为"arraybuffer"时,使用ArrayBuffer对象

RTCDataChannel.maxPacketLifeType 只读
是一个unsigned short类型,表示不可靠模式下的消息发送允许时间长度,单位为毫秒。
RTCDataChannel.maxRetransmits (en-US) 只读
是一个unsigned short类型,表示不可靠模式下消息允许尝试重发的最大次数。
RTCDataChannel.negotiated (en-US) 只读
是一个Boolean (en-US)类型,表示这个channel是否已经通过应用协商。
DataChannel.reliable 只读
是一个Boolean (en-US)类型,表示这个链接能不能以非可靠模式发送消息。已经废弃的api。
DataChannel.stream 只读
RTCDataChannel.id (en-US)等效,已经废弃的api。

事件处理器

RTCDataChannel.onopen (en-US)
当接收到open 事件时的事件处理器,当底层链路数据传输成功,端口状态处于established的时候会触发该事件。
RTCDataChannel.onmessage (en-US)
当接收到message事件时的事件处理器。当有数据被接收的时候会触发该事件。
RTCDataChannel.onclose (en-US)
当接收到close事件时候的事件处理器。当底层链路被关闭的时候会触发该事件。
RTCDataChannel.onerror (en-US)
当接收到error (en-US) 事件时候的事件处理器。当遇到错误的时候会触发该事件。

方法

RTCDataChannel.close() (en-US)

关闭channel的方法。这个关闭动作不是直接生效的。这个方法会将channel的state (en-US) 属性设置为"closing"状态,在消息队列中的消息全部发送完毕之后,channel才会被关闭。

RTCDataChannel.send() (en-US)
将参数中的数据通过channel发送。这个数据可以是DOMString, Blob, ArrayBuffer或者是 ArrayBufferView类型。

Example

var pc = new RTCPeerConnection();
var dc = pc.createDataChannel("my channel");

dc.onmessage = function (event) {
  console.log("received: " + event.data);
};

dc.onopen = function () {
  console.log("datachannel open");
};

dc.onclose = function () {
  console.log("datachannel close");
};

 

Specifications

Specification Status Comment
WebRTC 1.0: Real-time Communication Between Browsers
RTCDataChannel
Candidate Recommendation Initial specification.

Browser compatibility

We're converting our compatibility data into a machine-readable JSON format. This compatibility table still uses the old format, because we haven't yet converted the data it contains. Find out how you can help! (en-US)

Feature Chrome Firefox (Gecko) Internet Explorer Opera Safari
Basic support (Yes) (Yes) [1] 未实现 (Yes) ?
Feature Android Chrome for Android Firefox Mobile (Gecko) IE Mobile Opera Mobile Safari Mobile
Basic support ? ? ? 未实现 ? ?

[1] The interface is called DataChannel and not RTCDataChannel

See also