RTCDataChannel
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.
The RTCDataChannel
interface represents a network channel which can be used for bidirectional peer-to-peer transfers of arbitrary data. Every data channel is associated with an RTCPeerConnection
, and each peer connection can have up to a theoretical maximum of 65,534 data channels (the actual limit may vary from browser to browser).
To create a data channel and ask a remote peer to join you, call the RTCPeerConnection
's createDataChannel()
method. The peer being invited to exchange data receives a datachannel
event (which has type RTCDataChannelEvent
) to let it know the data channel has been added to the connection.
Properties
Also inherits properties from: EventTarget
binaryType
- The property
binaryType
on theRTCDataChannel
interface is aDOMString
which specifies the type of JavaScript object which should be used to represent binary data received on theRTCDataChannel
. Values allowed by theWebSocket.binaryType
property are also permitted here:"blob"
ifBlob
objects are being used or"arraybuffer"
ifArrayBuffer
objects are being used. The default is"blob"
. bufferedAmount
Read only- The read-only
RTCDataChannel
propertybufferedAmount
returns the number of bytes of data currently queued to be sent over the data channel. bufferedAmountLowThreshold
- The
RTCDataChannel
propertybufferedAmountLowThreshold
is used to specify the number of bytes of buffered outgoing data that is considered "low." The default value is 0 (meaning nobufferedamountlow
events are sent). id
Read only- The read-only
RTCDataChannel
propertyid
returns an ID number (between 0 and 65,534) which uniquely identifies theRTCDataChannel
. label
Read only- The read-only
RTCDataChannel
propertylabel
returns aDOMString
containing a name describing the data channel. These labels are not required to be unique. maxPacketLifeTime
Read only- The read-only
RTCDataChannel
propertymaxPacketLifeTime
returns the amount of time, in milliseconds, the browser is allowed to take to attempt to transmit a message, as set when the data channel was created, ornull
. maxRetransmits
Read only- The read-only
RTCDataChannel
propertymaxRetransmits
returns the maximum number of times the browser should try to transmit a message before giving up when in unordered mode, as set when the data channel was created, ornull
, which indicates that there is no maximum. negotiated
Read only- The read-only
RTCDataChannel
propertynegotiated
indicates whether theRTCDataChannel
's connection was negotiated by the Web app (true
) or by the WebRTC layer (false
). The default isfalse
. ordered
Read only- The read-only
RTCDataChannel
propertyordered
indicates whether or not the data channel guarantees in-order delivery of messages; the default istrue
, which indicates that the data channel is indeed ordered. protocol
Read only- The read-only
RTCDataChannel
propertyprotocol
returns aDOMString
containing the name of the subprotocol in use. If no protocol was specified when the data channel was created, then this property's value is "" (the empty string). readyState
Read only- The read-only
RTCDataChannel
propertyreadyState
returns an enum of typeRTCDataChannelState
which indicates the state of the data channel's underlying data connection. Read onlyreliable
- The read-only
RTCDataChannel
propertyreliable
indicates whether or not the data channel is reliable. Read onlystream
- The deprecated (and never part of the official specification) read-only
RTCDataChannel
propertystream
returns an ID number (between 0 and 65,535) which uniquely identifies theRTCDataChannel
. onbufferedamountlow
- The
RTCDataChannel.onbufferedamountlow
property is anEventHandler
which specifies a function the browser calls when thebufferedamountlow
event is sent to theRTCDataChannel
. This event, which is represented by a simpleEvent
object, is sent when the amount of data buffered to be sent falls to or below the threshold specified by the channel'sbufferedAmountLowThreshold
. onclose
- The
RTCDataChannel.onclose
property is anEventHandler
which specifies a function to be called by the browser when theclose
event is received by theRTCDataChannel
. This is a simpleEvent
which indicates that the data channel has closed down. onerror
- The
RTCDataChannel.onerror
property is anEventHandler
which specifies a function to be called when theerror
event is received. When an error occurs on the data channel, the function receives as input anErrorEvent
object describing the error which occurred. onmessage
- The
RTCDataChannel.ommessage
property stores anEventHandler
which specifies a function to be called when themessage
event is fired on the channel. This event is represented by theMessageEvent
interface. This event is sent to the channel when a message is received from the other peer. onopen
- The
RTCDataChannel.onopen
property is anEventHandler
which specifies a function to be called when theopen
event is fired; this is a simpleEvent
which is sent when the data channel's underlying data transport—the link over which theRTCDataChannel
's messages flow—is established or re-established. close()
- The
RTCDataChannel.close()
method closes theRTCDataChannel
. Either peer is permitted to call this method to initiate closure of the channel. send()
- The
send()
method of theRTCDataChannel
interface sends data across the data channel to the remote peer.
Event handlers
Also inherits event handlers from: EventTarget
Methods
Also inherits methods from: EventTarget
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 Browser The definition of 'RTCDataChannel' in that specification. |
Working Draft | Initial specification. |
Browser compatibility
Feature | Chrome | Firefox (Gecko) | Internet Explorer | Opera | Safari |
---|---|---|---|---|---|
Basic support | (Yes) | 22 (22) [1] | No support | (Yes) | ? |
onbufferedamountlow |
No support | No support | No support | 33 | No support |
Feature | Android | Chrome for Android | Firefox Mobile (Gecko) | IE Mobile | Opera Mobile | Safari Mobile | Chrome for Android |
---|---|---|---|---|---|---|---|
Basic support | No support | 28 [2] | 22.0 (22) [1] | No support | No support | No support | (Yes) |
onbufferedamountlow |
No support | No support | No support | ? | ? | ? | No support |
[1] The interface is called DataChannel
and not RTCDataChannel
in Firefox. However, a binding has been in place since Firefox 24 so that either name will work.
[2] WebRTC, including RTCDataChannel
, was introduced in Chrome 28 for Android behind a flag, and enabled by default starting in Chrome 29 for Android.
See also
License
© 2016 Mozilla Contributors
Licensed under the Creative Commons Attribution-ShareAlike License v2.5 or later.
https://developer.mozilla.org/en-us/docs/web/api/rtcdatachannel