This is an experimental technology
Because this technology's specification has not stabilized, check the compatibility table for usage in various browsers. Also note that the syntax and behavior of an experimental technology is subject to change in future versions of browsers as the specification changes.
Creates a new channel on the peer connection over which any sort 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.
Syntax
dataChannel = myPeerConnection.createDataChannel(label[, options]);
Parameters
label
- A human-readable name for the channel.
null
is treated as if you specified an empty string (""). options
Optional- An
RTCDataChannelInit
dictionary, which supports the following fields, any or all of which you may include as needed to configure the data channel:ordered
(optional; default istrue
): Indicates whether or not messages sent on theRTCDataChannel
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
).maxPacketLifeTime
(optional; default isnull
): The maximum number of milliseconds that attempts to transfer a message may take in unreliable mode. While this value is a16-bit unsigned number, each user agent may clamp it to whatever maximum it deems appropriate.maxRetransmits
(optional; default isnull
): 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.protocol
(optional; default is the empty string,""
): The name of the sub-protocol being used on theRTCDataChannel
, if any; otherwise, the empty string ("").negotiated
(optional; default isfalse
): 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 resultingRTCDataChannelEvent
(false
).id
(optional): A 16-bit numeric ID for the channel. If one is not provided here, the user agent will select one for you.
The options which can be configured using theRTCDataChannelInit
dictionary represent the script-settable subset of the properties on theRTCDataChannel
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.
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
Feature | Chrome | Firefox (Gecko) | Internet Explorer | Opera | Safari (WebKit) |
---|---|---|---|---|---|
Basic support | (Yes) | 22 (22) | ? | ? | ? |
Feature | Android | Android Webview | Firefox Mobile (Gecko) | Firefox OS | IE Mobile | Opera Mobile | Safari Mobile | Chrome for Android |
---|---|---|---|---|---|---|---|---|
Basic support | No support | No support | 24.0 (24) | ? [2] | ? | ? | ? | (Yes) |