RTCDataChannel
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.
RTCDataChannel
is a transferable object.
Instance properties
Also inherits properties from EventTarget
.
binaryType
-
A string specifying the type of object that should be used to represent binary data received on the
RTCDataChannel
. Values are the same as allowed on theWebSocket.binaryType
property:blob
ifBlob
objects are being used, orarraybuffer
ifArrayBuffer
objects are being used. The default isblob
. bufferedAmount
Read only-
Returns the number of bytes of data currently queued to be sent over the data channel.
bufferedAmountLowThreshold
-
Specifies the number of bytes of buffered outgoing data that is considered "low". The default value is 0.
id
Read only-
Returns an ID number (between 0 and 65,534) which uniquely identifies the
RTCDataChannel
. label
Read only-
Returns a string that contains a name describing the data channel. These labels are not required to be unique.
maxPacketLifeTime
Read only-
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, or
null
. maxRetransmits
Read only-
Returns the maximum number of times the browser should try to retransmit a message before giving up, as set when the data channel was created, or
null
, which indicates that there is no maximum. negotiated
Read only-
Indicates whether the
RTCDataChannel
's connection was negotiated by the Web app (true
) or by the WebRTC layer (false
). The default isfalse
. ordered
Read only-
Indicates whether or not the data channel guarantees in-order delivery of messages; the default is
true
, which indicates that the data channel is indeed ordered. protocol
Read only-
Returns a string 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-
Returns a string which indicates the state of the data channel's underlying data connection. It can have one of the following values:
connecting
,open
,closing
, orclosed
.
Obsolete properties
reliable
Read only Deprecated Non-standard-
Indicates whether or not the data channel is reliable.
Instance methods
Also inherits methods from EventTarget
.
close()
-
Closes the
RTCDataChannel
. Either peer is permitted to call this method to initiate closure of the channel. send()
-
Sends data across the data channel to the remote peer.
Events
bufferedamountlow
-
Sent when the number of bytes of data in the outgoing data buffer falls below the value specified by
bufferedAmountLowThreshold
. close
-
Sent when the underlying data transport closes.
closing
-
Sent when the underlying data transport is about to start closing.
error
-
Sent when an error occurs on the data channel.
message
-
Sent when a message has been received from the remote peer. The message contents can be found in the event's
data
property. open
-
Sent when the data channel is first opened, or when an existing data channel's underlying connection re-opens.
Data format
The underlying data format is defined by the IEEE specification SDP Offer/Answer Procedures for SCTP over DTLS Transport(RFC 8841). The current format specifies its protocol as either "UDP/DTLS/SCTP"
(UDP carrying DTLS carrying SCTP) or "TCP/DTLS/SCTP"
(TCP carrying DTLS carrying SCTP). Older browsers may only specify "DTLS/SCTP"
.
Example
js
const pc = new RTCPeerConnection();
const dc = pc.createDataChannel("my channel");
dc.onmessage = (event) => {
console.log(`received: ${event.data}`);
};
dc.onopen = () => {
console.log("datachannel open");
};
dc.onclose = () => {
console.log("datachannel close");
};
Specifications
Specification |
---|
WebRTC: Real-Time Communication in Browsers # rtcdatachannel |
Browser compatibility
BCD tables only load in the browser