recursal/MDN huggingface dataset:
RTCDataChannel: reliable property
=================================

**Deprecated:** This feature is no longer recommended. Though some browsers might still support it, it may have already been removed from the relevant web standards, may be in the process of being dropped, or may only be kept for compatibility purposes. Avoid using it, and update existing code if possible; see the compatibility table at the bottom of this page to guide your decision. Be aware that this feature may cease to work at any time.

**Non-standard:** This feature is non-standard and is not on a standards track. Do not use it on production sites facing the Web: it will not work for every user. There may also be large incompatibilities between implementations and the behavior may change in the future.

 The read-only `RTCDataChannel` property
 **`reliable`** indicates whether or not the data channel is
 reliable.


**Warning:** This property is obsolete. Use `RTCDataChannel.ordered` instead in any
 new code, and update existing code as soon as possible.


Value
-----

`true` if the `RTCDataChannel`'s connection is reliable;
 `false` if it isn't.

Specifications
--------------

No longer part of any specification.

Browser compatibility
---------------------

BCD tables only load in the browser with JavaScript enabled. Enable JavaScript to view data.

See also
--------

* WebRTC
* `RTCDataChannel`
* `RTCDataChannel.ordered`
RTCDataChannel: protocol property
=================================

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


**Note:** The permitted values of this property are defined by the website or app using the
 data channel.


 The ability for each channel to have a defined subprotocol lets your app, for example,
 use JSON objects as messages on one channel while another channel is plaintext and
 another is raw binary or even some other format.

Value
-----

 A string identifying the app-defined subprotocol being used for exchanging data on the
 channel. If none has been established, this is an empty string ("").

Example
-------


```js
const pc = new RTCPeerConnection();
const dc = pc.createDataChannel("my channel", {
  protocol: "json",
});

function handleChannelMessage(dataChannel, msg) {
  switch (dataChannel.protocol) {
    case "json":
      /\* process JSON data \*/
      break;
    case "raw":
      /\* process raw binary data \*/
      break;
  }
}
```

Specifications
--------------

| Specification |
| --- |
| WebRTC: Real-Time Communication in Browsers # dom-datachannel-protocol |

Browser compatibility
---------------------

BCD tables only load in the browser with JavaScript enabled. Enable JavaScript to view data.

See also
--------

* WebRTC
* `RTCDataChannel`
* `RTCPeerConnection.createDataChannel()`
RTCDataChannel: bufferedAmountLowThreshold property
===================================================

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

 The user agent may implement the process of actually sending data in any way it
 chooses; this may be done periodically during the event loop or truly asynchronously. As
 messages are actually sent, this value is reduced accordingly.

**Note:** `bufferedamountlow` events are not fired after the data channel is closed.

Value
-----

 The number of queued outgoing data bytes below which the buffer is considered to be
 "low."

Example
-------

 In this snippet of code, `bufferedAmountLowThreshold` is set to 64kB, and a
 handler for the `bufferedamountlow` event is established by setting the
 `onbufferedamountlow` property to a function which should
 send more data into the buffer by calling `send()`.


```js
const dc = peerConnection.createDataChannel("File Transfer");
dc.bufferedAmountLowThreshold = 65535;

dc.onbufferedamountlow = () => {
  /\* use send() to queue more data to be sent \*/
};
```

Specifications
--------------

| Specification |
| --- |
| WebRTC: Real-Time Communication in Browsers # dom-rtcdatachannel-bufferedamountlowthreshold |

Browser compatibility
---------------------

BCD tables only load in the browser with JavaScript enabled. Enable JavaScript to view data.

See also
--------

* WebRTC
* Using WebRTC data channels
* `RTCDataChannel`
* `RTCDataChannel.bufferedAmount`
* `bufferedamountlow` event
RTCDataChannel: ordered property
================================

 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.

Value
-----

 A boolean value which is `true` if in-order delivery is
 guaranteed and is otherwise `false`.

Example
-------


```js
const pc = new RTCPeerConnection();
const dc = pc.createDataChannel("my channel");

if (!dc.ordered) {
  // Handle unordered messaging
}
```

Specifications
--------------

| Specification |
| --- |
| WebRTC: Real-Time Communication in Browsers # dom-datachannel-ordered |

Browser compatibility
---------------------

BCD tables only load in the browser with JavaScript enabled. Enable JavaScript to view data.

See also
--------

* WebRTC
* `RTCDataChannel`
* `RTCPeerConnection.createDataChannel()`
RTCDataChannel: negotiated property
===================================

 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`.**

See Creating a data channel for further information about this property.

Value
-----

`true` if the `RTCDataChannel`'s connection was negotiated by
 the Web app itself; `false` if the negotiation was handled by the WebRTC
 layer. The default is `false`.

Example
-------

 The code snippet below checks the value of `negotiated`; if it's
 `true`, a function called `shutdownRemoteChannel()` is called
 with the channel's `id`; presumably this would be
 implemented to transmit a shutdown signal to the remote peer prior to terminating the
 connection.


```js
if (dataChannel.negotiated) {
  shutdownRemoteChannel(dataChannel.id);
}
```

Specifications
--------------

| Specification |
| --- |
| WebRTC: Real-Time Communication in Browsers # dom-datachannel-negotiated |

Browser compatibility
---------------------

BCD tables only load in the browser with JavaScript enabled. Enable JavaScript to view data.

See also
--------

* WebRTC
* Using WebRTC data channels
* `RTCDataChannel`
* `RTCPeerConnection.createDataChannel()`
RTCDataChannel: message event
=============================

The WebRTC **`message`** event is sent to the `onmessage` event handler on an `RTCDataChannel` object when a message has been received from the remote peer.

**Note:** The `message` event uses as its event object type the `MessageEvent` interface defined by the HTML specification.

This event is not cancelable and does not bubble.

Syntax
------

Use the event name in methods like `addEventListener()`, or set an event handler property.


```js
addEventListener("message", (event) => {});

onmessage = (event) => {};
```

Event type
----------

A `MessageEvent`. Inherits from `Event`.

Event

MessageEventEvent properties
----------------

*Also inherits properties from its parent interface, `Event`.*

`MessageEvent.data` Read only 

The data sent by the message emitter.

`MessageEvent.origin` Read only 

A string representing the origin of the message emitter.

`MessageEvent.lastEventId` Read only 

A string representing a unique ID for the event.

`MessageEvent.source` Read only 

A reference to the message emitter, one of WindowProxy, `MessagePort`, or `ServiceWorker`.

`MessageEvent.ports` Read only 

An array of `MessagePort` objects representing the ports associated with the channel the message is being sent through (where appropriate, e.g. in channel messaging or when sending a message to a shared worker).

Examples
--------

For a given `RTCDataChannel`, `dc`, created for a peer connection using its `createDataChannel()` method, this code sets up a handler for incoming messages and acts on them by adding the data contained within the message to the current document as a new `<p>` (paragraph) element.


```js
dc.addEventListener(
  "message",
  (event) => {
    let newParagraph = document.createElement("p");
    let textNode = document.createTextNode(event.data);
    newParagraph.appendChild(textNode);

    document.body.appendChild(newParagraph);
  },
  false,
);
```


Lines 2-4 create the new paragraph element and add the message data to it as a new text node. Line 6 appends the new paragraph to the end of the document's body.

You can also use an `RTCDataChannel` object's `onmessage` event handler property to set the event handler:


```js
dc.onmessage = (event) => {
  let newParagraph = document.createElement("p");
  let textNode = document.createTextNode(event.data);
  newParagraph.appendChild(textNode);

  document.body.appendChild(newParagraph);
};
```

Specifications
--------------

| Specification |
| --- |
| WebRTC: Real-Time Communication in Browsers # event-datachannel-message |
| WebRTC: Real-Time Communication in Browsers # dom-rtcdatachannel-onmessage |

Browser compatibility
---------------------

BCD tables only load in the browser with JavaScript enabled. Enable JavaScript to view data.

See also
--------

* WebRTC API
* A simple RTCDataChannel example
* Related events: `open`, `close`, and `error`
* `RTCDataChannel.send()`
RTCDataChannel: closing event
=============================

The **`closing`** event is sent to an `RTCDataChannel` just before the channel begins the process of shutting down its underlying data transport.

This event is not cancelable and does not bubble.

Syntax
------

Use the event name in methods like `addEventListener()`, or set an event handler property.


```js
addEventListener("closing", (event) => {});

onclosing = (event) => {};
```

Event type
----------

A generic `Event`.

Description
-----------

While the `closing` event is sent to the channel just before beginning to close the channel's data transport, the `close` event is sent once the closing process is complete.

Examples
--------

This example updates a connection status interface when the `closing` event arrives.

First, an example using `addEventListener()`:


```js
dataChannel.addEventListener("closing", (ev) => {
  myConnectionStatus.icon = closingIcon;
  myConnectionStatus.text = "Connection closing";
});
```


You can also set the `onclosing` event handler property directly:


```js
pc.onclosing = (ev) => {
  myConnectionStatus.icon = closingIcon;
  myConnectionStatus.text = "Connection closing";
};
```

Specifications
--------------

| Specification |
| --- |
| WebRTC: Real-Time Communication in Browsers # event-datachannel-closing |
| WebRTC: Real-Time Communication in Browsers # dom-rtcdatachannel-onclosing |

Browser compatibility
---------------------

BCD tables only load in the browser with JavaScript enabled. Enable JavaScript to view data.

See also
--------

* WebRTC API
* Signaling and video calling
RTCDataChannel: close event
===========================

The **`close`** event is sent to the `onclose` event handler on an `RTCDataChannel` instance when the data transport for the data channel has closed. Before any further data can be transferred using `RTCDataChannel`, a new 'RTCDataChannel' instance must be created.

This event is not cancelable and does not bubble.

Syntax
------

Use the event name in methods like `addEventListener()`, or set an event handler property.


```js
addEventListener("close", (event) => {});

onclose = (event) => {};
```

Event type
----------

A generic `Event`.

Examples
--------

This example sets up a handler for the `close` event for the `RTCDataChannel` named `dc`; its responsibility in this example is to update user interface elements to reflect that there is no longer an ongoing call, and to allow a new call to be started.


```js
dc.addEventListener(
  "close",
  (ev) => {
    messageInputBox.disabled = true;
    sendButton.disabled = true;
    connectButton.disabled = false;
    disconnectButton.disabled = true;
  },
  false,
);
```


All this code does in response to receiving the `close` event is to disable an input box and its "Send" button, and to enable the button used to start a call (while disabling the one that ends a call).

You can also use the `onclose` event handler property to set a handler for `close` events:


```js
dc.onclose = (ev) => {
  messageInputBox.disabled = true;
  sendButton.disabled = true;
  connectButton.disabled = false;
  disconnectButton.disabled = true;
};
```

Specifications
--------------

| Specification |
| --- |
| WebRTC: Real-Time Communication in Browsers # event-datachannel-close |
| WebRTC: Real-Time Communication in Browsers # dom-rtcdatachannel-onclose |

Browser compatibility
---------------------

BCD tables only load in the browser with JavaScript enabled. Enable JavaScript to view data.

See also
--------

* WebRTC API
* A simple RTCDataChannel example
* Related events: `open`, `message`, and `error`
RTCDataChannel: close() method
==============================

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

 Closure of the data channel is not instantaneous. Most of the process of closing the
 connection is handled asynchronously; you can detect when the channel has finished
 closing by watching for a `close` event on the data channel.

The sequence of events which occurs in response to this method being called:

1. `RTCDataChannel.readyState` is set to `closing`.
2. A background task is established to handle the remainder of the steps below, and
 `close()` returns to the caller.
3. The transport layer deals with any buffered messages; the protocol layer decides
 whether to send them or discard them.
4. The underlying data transport is closed.
5. The `RTCDataChannel.readyState` property is set to
 `closed`.
6. If the transport was closed with an error,
 the `RTCDataChannel` is sent
 an `error` event
 with its `name` set to `NetworkError`.
7. A `close` event is sent to the channel.
Syntax
------


```js
close()
```

### Parameters

None.

### Return value

None (`undefined`).

Return value
------------

`undefined`.

Examples
--------


```js
const pc = new RTCPeerConnection();
const dc = pc.createDataChannel("my channel");

dc.onmessage = (event) => {
  console.log(`received: ${event.data}`);
  dc.close(); // We decided to close after the first received message
};

dc.onopen = () => {
  console.log("datachannel open");
};

dc.onclose = () => {
  console.log("datachannel close");
};

// Now negotiate the connection and so forth…
```

Specifications
--------------

| Specification |
| --- |
| WebRTC: Real-Time Communication in Browsers # dom-rtcdatachannel-close |

Browser compatibility
---------------------

BCD tables only load in the browser with JavaScript enabled. Enable JavaScript to view data.

See also
--------

* WebRTC
* `RTCDataChannel`
* `RTCDataChannel.readyState`
* `close` event
RTCDataChannel: maxPacketLifeTime property
==========================================

 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.

Value
-----

 The number of milliseconds over which the browser may continue to attempt to transmit
 the message until it either succeeds or gives up. If not set when
 `RTCPeerConnection.createDataChannel()` was called to create the data
 channel, this value is `null`.

Specifications
--------------

| Specification |
| --- |
| WebRTC: Real-Time Communication in Browsers # dom-datachannel-maxpacketlifetime |

Browser compatibility
---------------------

BCD tables only load in the browser with JavaScript enabled. Enable JavaScript to view data.

See also
--------

* WebRTC
* `RTCDataChannel`
* `RTCDataChannel.maxRetransmits`
* `RTCPeerConnection.createDataChannel()`
RTCDataChannel: send() method
=============================

 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.


**Note:** Different browsers have different limitations on the size of the message you can
 send. Specifications exist to define how to automatically fragment large messages, but
 not all browsers implement them, and those that do have various additional
 restrictions. This will get less complicated over time, but for now, if you have
 questions, see Understanding message size limits.


Syntax
------


```js
send(data)
```

### Parameters

`data`

 The data to transmit across the connection. This may be a string,
 a `Blob`, an `ArrayBuffer`, a `TypedArray` or a `DataView` object.


### Return value

None (`undefined`).

### Exceptions

`InvalidStateError` `DOMException`

 Thrown when the data channel has not finished establishing its own connection (that is, its
 `readyState` is `connecting`). The data channel
 must establish its own connection because it uses a transport channel separate from that of the media content. This error occurs without sending or buffering the `data`.


`NetworkError` `DOMException`

 Thrown when the specified `data` would need to be buffered, and there isn't room for
 it in the buffer. In this scenario, the underlying transport is immediately closed.


`TypeError`

 Thrown if the specified `data` is too large for the other peer to receive. Since
 there are multiple techniques for breaking up large data into smaller pieces for
 transfer, it's possible to encounter scenarios in which the other peer does not
 support the same ones. For example, if one peer is a modern browser that supports
 using the `EOR` (End of Record) flag to indicate when a received message is
 the last piece of a multi-part object sent using `send()`. For more
 information about message size restrictions, see
 Understanding message size limits.


Examples
--------

 In this example, a routine called `sendMessage()` is created; it accepts an
 object as input and sends to the remote peer, over the `RTCDataChannel`, a
 JSON string with the specified object and a timestamp.


```js
const pc = new RTCPeerConnection();
const dc = pc.createDataChannel("BackChannel");

function sendMessage(msg) {
  const obj = {
    message: msg,
    timestamp: new Date(),
  };
  dc.send(JSON.stringify(obj));
}
```

Specifications
--------------

| Specification |
| --- |
| WebRTC: Real-Time Communication in Browsers # dom-rtcdatachannel-send |

Browser compatibility
---------------------

BCD tables only load in the browser with JavaScript enabled. Enable JavaScript to view data.

See also
--------

* WebRTC
* `RTCDataChannel`
* `RTCDataChannel.readyState`
* `close` event
RTCDataChannel: id property
===========================

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

 Each `RTCPeerConnection` can therefore have up to a theoretical maximum of
 65,534 data channels on it, although the actual maximum may vary from browser to
 browser.

Value
-----

 An `unsigned short` value (that is, an integer between 0 and 65,535) which
 uniquely identifies the data channel.

 While the `label` property doesn't have to be
 unique, this ID number is guaranteed to be unique among all data channels. Additionally,
 known implementations of WebRTC use the same ID on both peers. A unique ID makes it
 easier for your code to do its own out-of-band data channel-related signaling.

This can be also useful for logging and debugging purposes.

Example
-------


```js
const pc = new RTCPeerConnection();
const dc = pc.createDataChannel("my channel");

console.log(`Channel id: ${dc.id}`);
```

Specifications
--------------

| Specification |
| --- |
| WebRTC: Real-Time Communication in Browsers # dom-rtcdatachannel-id |

Browser compatibility
---------------------

BCD tables only load in the browser with JavaScript enabled. Enable JavaScript to view data.

See also
--------

* WebRTC
* `RTCDataChannel`
* `RTCPeerConnection.createDataChannel()`
RTCDataChannel: readyState property
===================================

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

Values
------

A string indicating the current state of the underlying data transport, which is one of the following values:

`connecting`

 The user agent (browser) is in the process of creating the underlying data transport;
 this is the state of a new `RTCDataChannel` after being created by `RTCPeerConnection.createDataChannel()`,
 on the peer which started the connection process.


`open`

 The underlying data transport has been established
 and data can be transferred bidirectionally across it.
 This is the default state of a new `RTCDataChannel` created by the WebRTC layer
 when the remote peer created the channel
 and delivered it to the site or app
 in a `datachannel` event.


`closing`

 The process of closing the underlying data transport has begun.
 It is no longer possible to queue new messages to be sent,
 but previously queued messages may still be send or received
 before entering the `closed` state.


`closed`

 The underlying data transport has closed,
 or the attempt to make the connection failed.


Example
-------


```js
const dataChannel = peerConnection.createDataChannel("File Transfer");
const sendQueue = [];

function sendMessage(msg) {
  switch (dataChannel.readyState) {
    case "connecting":
      console.log(`Connection not open; queueing: ${msg}`);
      sendQueue.push(msg);
      break;
    case "open":
      sendQueue.forEach((msg) => dataChannel.send(msg));
      break;
    case "closing":
      console.log(`Attempted to send message while closing: ${msg}`);
      break;
    case "closed":
      console.log("Error! Attempt to send while connection closed.");
      break;
  }
}
```

Specifications
--------------

| Specification |
| --- |
| WebRTC: Real-Time Communication in Browsers # dom-datachannel-readystate |

Browser compatibility
---------------------

BCD tables only load in the browser with JavaScript enabled. Enable JavaScript to view data.

See also
--------

* WebRTC
* Using WebRTC data channels
* `RTCDataChannel`
* `RTCPeerConnection.createDataChannel()`