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

interface RTCDataChannel {
    binaryType: BinaryType;
    bufferedAmount: number;
    bufferedAmountLowThreshold: number;
    id: number | null;
    label: string;
    maxPacketLifeTime: number | null;
    maxRetransmits: number | null;
    negotiated: boolean;
    onbufferedamountlow: ((this: RTCDataChannel, ev: Event) => any) | null;
    onclose: ((this: RTCDataChannel, ev: Event) => any) | null;
    onclosing: ((this: RTCDataChannel, ev: Event) => any) | null;
    onerror: ((this: RTCDataChannel, ev: RTCErrorEvent) => any) | null;
    onmessage: ((this: RTCDataChannel, ev: MessageEvent) => any) | null;
    onopen: ((this: RTCDataChannel, ev: Event) => any) | null;
    ordered: boolean;
    protocol: string;
    readyState: RTCDataChannelState;
    addEventListener<K extends keyof RTCDataChannelEventMap>(
        type: K,
        listener: (this: RTCDataChannel, ev: RTCDataChannelEventMap[K]) => any,
        options?: boolean | AddEventListenerOptions,
    ): void;
    addEventListener(
        type: string,
        listener: EventListenerOrEventListenerObject,
        options?: boolean | AddEventListenerOptions,
    ): void;
    close(): void;
    dispatchEvent(event: Event): boolean;
    removeEventListener<K extends keyof RTCDataChannelEventMap>(
        type: K,
        listener: (this: RTCDataChannel, ev: RTCDataChannelEventMap[K]) => any,
        options?: boolean | EventListenerOptions,
    ): void;
    removeEventListener(
        type: string,
        listener: EventListenerOrEventListenerObject,
        options?: boolean | EventListenerOptions,
    ): void;
    send(data: string): void;
    send(data: Blob): void;
    send(data: ArrayBuffer): void;
    send(data: ArrayBufferView<ArrayBuffer>): void;
}

Hierarchy (View Summary)

EventTarget
- RTCDataChannel

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.

`Readonly`bufferedAmount

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

`Readonly`id

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

`Readonly`label

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.

`Readonly`maxPacketLifeTime

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.

`Readonly`maxRetransmits

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.

`Readonly`negotiated

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: RTCDataChannel, ev: Event) => any) | null

onclose

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

onclosing

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

onerror

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

onmessage

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

onopen

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

`Readonly`ordered

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.

`Readonly`protocol

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

`Readonly`readyState

readyState: RTCDataChannelState

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

Methods

addEventListener

addEventListener<K extends keyof RTCDataChannelEventMap>(
    type: K,
    listener: (this: RTCDataChannel, ev: RTCDataChannelEventMap[K]) => any,
    options?: boolean | AddEventListenerOptions,
): 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.

MDN Reference
Type Parameters
- K extends keyof RTCDataChannelEventMap
Parameters
- type: K
- listener: (this: RTCDataChannel, ev: RTCDataChannelEventMap[K]) => any
- Optionaloptions: boolean | AddEventListenerOptions
Returns void
Overrides EventTarget.addEventListener
addEventListener(
    type: string,
    listener: EventListenerOrEventListenerObject,
    options?: boolean | AddEventListenerOptions,
): 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.

MDN Reference
Parameters
- type: string
- listener: EventListenerOrEventListenerObject
- Optionaloptions: 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.

MDN Reference

Returns void

dispatchEvent

dispatchEvent(event: 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().

MDN Reference
Parameters
- event: Event
Returns boolean
Inherited from EventTarget.dispatchEvent

removeEventListener

removeEventListener<K extends keyof RTCDataChannelEventMap>(
    type: K,
    listener: (this: RTCDataChannel, ev: RTCDataChannelEventMap[K]) => any,
    options?: boolean | EventListenerOptions,
): 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.

MDN Reference
Type Parameters
- K extends keyof RTCDataChannelEventMap
Parameters
- type: K
- listener: (this: RTCDataChannel, ev: RTCDataChannelEventMap[K]) => any
- Optionaloptions: boolean | EventListenerOptions
Returns void
Overrides EventTarget.removeEventListener
removeEventListener(
    type: string,
    listener: EventListenerOrEventListenerObject,
    options?: boolean | EventListenerOptions,
): 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.

MDN Reference
Parameters
- type: string
- listener: EventListenerOrEventListenerObject
- Optionaloptions: boolean | EventListenerOptions
Returns void
Overrides EventTarget.removeEventListener

send

send(data: string): 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.

MDN Reference
Parameters
- data: string
Returns void
send(data: Blob): void
Parameters
- data: Blob
Returns void
send(data: ArrayBuffer): void
Parameters
- data: ArrayBuffer
Returns void
send(data: ArrayBufferView<ArrayBuffer>): void
Parameters
- data: ArrayBufferView<ArrayBuffer>
Returns void