WebRTC在RTCPeerConnection的扩展接口提供了数据通道API的入口,这些API接收/发送数据的使用方法与WebSocket一致。RTCPeerConnection数据通道扩展接口如下面的代码清单所示。
//RTCPeerConnection数据通道扩展接口
partial interface RTCPeerConnection {
readonly attribute RTCSctpTransport? sctp;
RTCDataChannel createDataChannel(USVString label,
optional RTCDatachannelInit dataChannelDict = {});
attribute EventHandler ondatachannel;
};
sctp是扩展接口的只读属性,类型为RTCSctpTransport,表示收发SCTP的数据传输通道。
createDataChannel()方法会创建一个新的数据通道,用于传输图片、文件、文本、数据包等任意数据。该方法会触发 negotiationneeded事件,其使用语法如下。
const dataChannel = RTCPeerConnection.createDataChannel(label[, options]);
参数:label,为通道指定的名称,类型为字符串,长度不能超过65535个字节;options,可选参数,类型为 RTCDataChannelInit,提供了数据通道的配置选型。
返回值:该方法返回类型为RTCDataChannel的数据通道对象。
异常:该方法调用失败时,抛出的异常值如下表所示。
createDataChannel()方法的异常值 | |
异常值 | 说明 |
InvalidStateError | RTCPeerConnection 处于关闭状态 |
TypeError | 指定的 label 或者 protocol 字符串长度超过了 65536 字节 |
SyntaxError | 同时为 maxPacketLifeTime 和 maxRetransmits 选项指定值,但是只能为其中一个指定非空值 |
ResourceInUse | 指定的ID与另外一个正在使用的数据通道相同 |
OperationError | 如果没有指定id,则WebRTC自动创建ID失败 |
字典类型 RTCDataChannelInit 包含定制数据通道行为的配置选项,其定义如下面的代码清单所示。
//RTCDataChannelInit的定义
dictionary RTCDataChannelInit {
boolean ordered = true;
[EnforceRange] unsigned short maxPacketLifeTime;
[EnforceRange] unsigned short maxRetransmits;
USVString protocol = "";
boolean negotiated = false;
[EnforceRange] unsigned short id;
};
RTCDataChannelInit 属性说明 | ||
配置项 | 类型 | 说明 |
ordered | 布尔 | 可选配置。表示是否保持发包顺序,true表示确保接收包的顺序与发出时一致;false表示不保证一致。默认值是true |
maxPacketLifeTime | 数值 | 可选配置。表示发送消息间隔的最大毫秒数,如果超出该值仍未收到确认,则开始重传。当为该配置项指定值时,默认开启不可靠传输模式。默认值是null |
maxRetransmits | 数值 | 可选配置。表示发送消息失败后的重传次数。当为该配置项指定值时,默认开启不可靠传输模式。默认值是 null |
protocol | 字符串 | 可选配置。数据通道使用的子协议名称 |
negotiated | 布尔 |
可选配置。取值为false时,数据通道在带内协商,一方调用createDataChannel()方法,另一方使用监听事件datachannel。 取值为true时,数据通道在带外协商,双方都调用createDataChannel()方法,使用商定的ID进行通话。 默认值是 false |
id | 数值 | 可选配置。数据通道的16位标识ID,如果没有指定该配置项,WebRTC会自动创建一个 |
数据通道可以配置在不同的模式中。一种是使用重传机制的可靠传输模式,这是默认模式,可以确保数据成功传输到对等端。另一种是不可靠传输模式,这种模式可以通过为maxRetransmits指定最大重传次数,或者通过maxPacketLifeTime 设置传输间隔时间实现。注意,maxRetransmits 和 maxPacketLifeTime 这两个配置项不能同时指定,否则会出错。在两个属性的值都是 null 时,使用的是可靠传输模式,而这两个属性中任意一个为非 null 值时即开启不可靠传输模式。
我们使用 createDataChannel() 方法和事件句柄 ondatachannel 建立一条数据通道。通常在发起端调用 createDataChannel() 方法,获得数据通道对象。如果通道成功建立,则应答端触发 datachannel 事件,从事件参数 event.channel 获取代表数据通道的对象。
发起端调用 createDataChannel() 方法的示例如下面的代码清单所示。
//createDataChannel方法示例
const pc = new RTCPeerConnection(options);
const channel = pc.createDataChannel("chat" );
channel.onopen = (event) => {
channel.send('Hi you!');
}
channel.onmessage = (event) => {
console.log(event.data);
}
当发起端调用 createDataChannel()方法创建数据通道时,应答端触发datachannel事件,对应事件句柄ondatachannel。事件参数类型是RTCDataChannelEvent,定义如下面的代码清单所示。
//RTCDataChannelEvent的定义
interface RTCDataChannelEvent : Event {
constructor(DOMString type, RTCDataChannelEventInit eventInitDict);
readonly attribute RTCDataChannel channel;
};
RTCDataChannelEvent事件只包含一个属性,即channel,代表与发起端相对应的数据通道。
应答端使用 ondatachannel 事件句柄的示例如下面的代码清单所示。
//ondatachannel事件句柄示例
const pc = new RTCPeerConnection(options);
pc.ondatachannel = (event) => {
const channel = event.channel;
channel.onopen = (event) => {
channel.send('Hi back!');
}
channel.onmessage = (event) => {
console.log(event.data);
}
};