RTCPeerConnection.createDataChannel

The createDataChannel() method on the RTCPeerConnection interface creates a new channel over which any kind of data may be transmitted. This can be useful for back-channel content such as images, file transfer, text chat, game update packets, and so forth.

If the new data channel is the first one added to the connection, renegotiation is started by delivering a notificationneeded event.

Syntax

dataChannel = RTCPeerConnection.createDataChannel(label[, options]);

Parameters

label

A human-readable name for the channel. null is treated as if you specified an empty string (""). This string may not be longer than 65,535 bytes.

options Optional

An RTCDataChannelInit dictionary providing configuration options for the data channel

RTCDataChannelInit dictionary

The RTCDataChannelInit dictionary provides the following fields, any of which may be included as needed in the object passed as the options parameter in order to configure the data channel to suit your needs:

ordered Optional

Indicates whether or not messages sent on the RTCDataChannel are required to arrive at their destination in the same order in which they were sent (true), or if they're allowed to arrive out-of-order (false). Default: true.

maxPacketLifeTime Optional

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 Optional

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 Optional

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 Optional

Indicates whether or not the two peers negotiated when creating the data channel (true), or if the channel was simply created by one of the peers, letting the other peer choose to accept the connection or not when it receives the resulting RTCDataChannelEvent (false). Default: false.

id Optional

A 16-bit numeric ID for the channel. If you don't include this option, the user agent will select an ID for you.

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

The label and/or protocol string is too long; these cannot be longer than 65,535 bytes (bytes, rather than characters).

SyntaxError

Values were specified for both the maxPacketLifeTime and maxRetransmits options. You may only specify a non-null value for one of these.

ResourceInUse

An id was specified, but another RTCDataChannel is already using the same value.

Example

This simple example opens a channel and sets up handlers for the open and message events to send and receive messages on the data channel. For a more thorough example showing how the connection and channel are established, see A simple RTCDataChannel sample.

var pc = new RTCPeerConnection();
var channel = pc.createDataChannel("Mydata");
channel.onopen = function(event) {
  channel.send('sending a message');
}
channel.onmessage = function(event) {
  console.log(event.data);
}

Specifications

Specification	Status	Comment
WebRTC 1.0: Real-time Communication Between Browser The definition of 'createDataChannel()' in that specification.	Working Draft	Initial definition.

Browser compatibility

See also

• RTCDataChannel
• A simple RTCDataChannel sample
• RTCPeerConnection