WebRTC - RTCDataChannel APIs

WebRTC excels not only at streaming audio and video but also at transferring arbitrary data between peers. The RTCDataChannel object is the key to this capability, enabling low-latency, peer-to-peer data exchange.

RTCDataChannel API Overview

An RTCDataChannel can be configured to be reliable (like TCP) or unreliable (like UDP), and ordered or unordered. This flexibility makes it suitable for a wide range of applications, from file sharing and gaming to text chat and real-time sensor data.

Properties

label (read-only string): Returns the name assigned to the channel when it was created. Useful for distinguishing multiple data channels.
ordered (read-only boolean): Returns true if the channel guarantees message order, false otherwise. Set at creation.
protocol (read-only string): Returns the name of the subprotocol in use, if any. This is an application-defined string.
id (read-only unsigned short?): Returns a unique numerical ID for the channel, assigned by the browser. Nullable if the channel is not yet negotiated or associated with an underlying SCTP stream.
readyState (read-only string): Returns an enum (RTCDataChannelState) representing the current state of the channel. Possible values are:

*   `"connecting"`: The channel is not yet open, but is in the process of connecting. This is the initial state for a newly created channel.

*   `"open"`: The channel is open and ready to send and receive messages.

*   `"closing"`: The channel is in the process of closing.

*   `"closed"`: The channel has been closed or could not be established.

bufferedAmount (read-only unsigned long): Returns the number of bytes of data currently queued to be sent but not yet transmitted. This value decreases as data is sent over the network.
bufferedAmountLowThreshold (unsigned long): A configurable threshold. When bufferedAmount drops below this value, the bufferedamountlow event is fired. This can be used for flow control.
binaryType (string): Specifies the type of JavaScript object to be used for representing binary data received on the channel. Can be set to "blob" or "arraybuffer". Defaults to "blob" if not specified for received data, but when sending, send() accepts String, Blob, ArrayBuffer, or ArrayBufferView.
maxPacketLifeTime (read-only unsigned short?): For unreliable channels, indicates the maximum time (in milliseconds) for which the channel will attempt to transmit or retransmit a message before giving up. Mutually exclusive with maxRetransmits.
maxRetransmits (read-only unsigned short?): For unreliable channels, indicates the maximum number of times the channel will attempt to retransmit a message if it’s not acknowledged. Mutually exclusive with maxPacketLifeTime.
negotiated (read-only boolean): Returns true if the channel was negotiated out-of-band by the application (e.g., using a specific ID pre-agreed via signaling), or false if it was negotiated in-band by WebRTC itself. Defaults to false.
reliable (read-only boolean): This property is deprecated. Use ordered and (maxPacketLifeTime or maxRetransmits) to determine reliability characteristics. Historically, it indicated if the channel was configured for reliable transmission.

Note: Some properties like maxPacketLifeTime and maxRetransmits are configured when the data channel is created using RTCPeerConnection.createDataChannel(label, options).

Event Handlers

onopen: An event handler called when the open event is fired. This signifies that the data channel is successfully established and ready for communication.
onmessage: An event handler called when the message event is fired. This occurs when a message is received from the remote peer. The event object contains a data property with the received message (String, Blob, or ArrayBuffer, depending on binaryType and what was sent).
onbufferedamountlow: An event handler called when the bufferedamountlow event is fired. This occurs when the bufferedAmount drops below the bufferedAmountLowThreshold.
onclosing: An event handler called when the closing event is fired. This indicates the channel is in the process of closing. It is fired before the onclose event.
onclose: An event handler called when the close event is fired. This signifies that the data channel has been closed.
onerror: An event handler called when the error event is fired. This occurs when an error is encountered on the data channel. The event object may contain details about the error.

Methods

close(): Initiates the closing of the data channel. This will eventually lead to the readyState becoming "closing" and then "closed".
send(data): Sends data across the channel to the remote peer. The data parameter can be a DOMString, Blob, ArrayBuffer, or ArrayBufferView. The browser will handle appropriate serialization for transmission.

Understanding these APIs is crucial for building applications that leverage WebRTC’s data transfer capabilities. The next chapters will demonstrate how to use RTCDataChannel in practical examples, such as a text chat application.

For further details, always refer to the latest W3C WebRTC specifications and MDN Web Docs for RTCDataChannel.