Skip to main content

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).

Extends

EventTarget

Methods

addEventListener()

Call Signature

addEventListener<K>(
   type, 
   listener, 
   options?
): void;

The addEventListener() method of the EventTarget interface sets up a function that will be called whenever the specified event is delivered to the target.

Type Parameters

Type Parameter
`K` extends keyof `RTCDataChannelEventMap`

Parameters

Parameter	Type
`type`	`K`
`listener`	(`this`, `ev`) => `any`
`options?`	`boolean` \| `AddEventListenerOptions`

Returns

void

Overrides

EventTarget.addEventListener

Call Signature

addEventListener(
   type, 
   listener, 
   options?
): void;

The addEventListener() method of the EventTarget interface sets up a function that will be called whenever the specified event is delivered to the target.

Parameters

Parameter	Type
`type`	`string`
`listener`	`EventListenerOrEventListenerObject`
`options?`	`boolean` \| `AddEventListenerOptions`

Returns

void

Overrides

EventTarget.addEventListener

close()

close(): void;

The RTCDataChannel.close() method closes the RTCDataChannel. Either peer is permitted to call this method to initiate closure of the channel.

Returns

void

dispatchEvent()

dispatchEvent(event): boolean;

The dispatchEvent() method of the EventTarget sends an Event to the object, (synchronously) invoking the affected event listeners in the appropriate order. The normal event processing rules (including the capturing and optional bubbling phase) also apply to events dispatched manually with dispatchEvent().

Parameters

Parameter	Type
`event`	`Event`

Returns

boolean

Inherited from

EventTarget.dispatchEvent

removeEventListener()

Call Signature

removeEventListener<K>(
   type, 
   listener, 
   options?
): void;

The removeEventListener() method of the EventTarget interface removes an event listener previously registered with EventTarget.addEventListener() from the target. The event listener to be removed is identified using a combination of the event type, the event listener function itself, and various optional options that may affect the matching process; see Matching event listeners for removal.

Type Parameters

Type Parameter
`K` extends keyof `RTCDataChannelEventMap`

Parameters

Parameter	Type
`type`	`K`
`listener`	(`this`, `ev`) => `any`
`options?`	`boolean` \| `EventListenerOptions`

Returns

void

Overrides

EventTarget.removeEventListener

Call Signature

removeEventListener(
   type, 
   listener, 
   options?
): void;

The removeEventListener() method of the EventTarget interface removes an event listener previously registered with EventTarget.addEventListener() from the target. The event listener to be removed is identified using a combination of the event type, the event listener function itself, and various optional options that may affect the matching process; see Matching event listeners for removal.

Parameters

Parameter	Type
`type`	`string`
`listener`	`EventListenerOrEventListenerObject`
`options?`	`boolean` \| `EventListenerOptions`

Returns

void

Overrides

EventTarget.removeEventListener

send()

Call Signature

send(data): void;

The send() method of the RTCDataChannel interface sends data across the data channel to the remote peer. This can be done any time except during the initial process of creating the underlying transport channel. Data sent before connecting is buffered if possible (or an error occurs if it's not possible), and is also buffered if sent while the connection is closing or closed.

Parameters

Parameter	Type
`data`	`string`

Returns

void

Call Signature

send(data): void;

Parameters

Parameter	Type
`data`	`Blob`

Returns

void

Call Signature

send(data): void;

Parameters

Parameter	Type
`data`	`ArrayBuffer`

Returns

void

Call Signature

send(data): void;

Parameters

Parameter	Type
`data`	`ArrayBufferView`<`ArrayBuffer`>

Returns

void

Properties

binaryType

binaryType: BinaryType;

The property binaryType on the RTCDataChannel interface is a string which specifies the type of object which should be used to represent binary data received on the RTCDataChannel. Values allowed by the WebSocket.binaryType property are also permitted here: blob if Blob objects are being used or arraybuffer if ArrayBuffer objects are being used. The default is arraybuffer.

bufferedAmount

readonly bufferedAmount: number;

The read-only RTCDataChannel property bufferedAmount returns the number of bytes of data currently queued to be sent over the data channel. The queue may build up as a result of calls to the send() method. This only includes data buffered by the user agent itself; it doesn't include any framing overhead or buffering done by the operating system or network hardware.

bufferedAmountLowThreshold

bufferedAmountLowThreshold: number;

The RTCDataChannel property bufferedAmountLowThreshold is used to specify the number of bytes of buffered outgoing data that is considered "low." The default value is 0. When the number of buffered outgoing bytes, as indicated by the bufferedAmount property, falls to or below this value, a bufferedamountlow event is fired. This event may be used, for example, to implement code which queues more messages to be sent whenever there's room to buffer them. Listeners may be added with onbufferedamountlow or addEventListener().

id

readonly id: number | null;

The read-only RTCDataChannel property id returns an ID number (between 0 and 65,534) which uniquely identifies the RTCDataChannel. This ID is set at the time the data channel is created, either by the user agent (if RTCDataChannel.negotiated is false) or by the site or app script (if negotiated is true).

label

readonly label: string;

The read-only RTCDataChannel property label returns a string containing a name describing the data channel. These labels are not required to be unique.

maxPacketLifeTime

readonly maxPacketLifeTime: number | null;

The read-only RTCDataChannel property maxPacketLifeTime 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. This limits how long the browser can continue to attempt to transmit and retransmit the message before giving up.

maxRetransmits

readonly maxRetransmits: number | null;

The read-only RTCDataChannel property maxRetransmits 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. This can only be set when the RTCDataChannel is created by calling RTCPeerConnection.createDataChannel(), using the maxRetransmits field in the specified options.

negotiated

readonly negotiated: boolean;

The read-only RTCDataChannel property negotiated indicates whether the RTCDataChannel's connection was negotiated by the Web app (true) or by the WebRTC layer (false). The default is false.

onbufferedamountlow

onbufferedamountlow: ((this, ev) => any) | null;

onclose

onclose: ((this, ev) => any) | null;

onclosing

onclosing: ((this, ev) => any) | null;

onerror

onerror: ((this, ev) => any) | null;

onmessage

onmessage: ((this, ev) => any) | null;

onopen

onopen: ((this, ev) => any) | null;

ordered

readonly ordered: boolean;

The read-only RTCDataChannel property ordered 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. This is set when the RTCDataChannel is created, by setting the ordered property on the object passed as RTCPeerConnection.createDataChannel()'s options parameter.

protocol

readonly protocol: string;

The read-only RTCDataChannel property protocol 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

readonly readyState: RTCDataChannelState;

The read-only RTCDataChannel property readyState returns a string which indicates the state of the data channel's underlying data connection.