# RTCDataChannel

The data channel, which carries text and binary messages between the peers over SCTP.

### webrtc.interfaces.rtc_data_channel.MAX_UNSIGNED_SHORT *= 65535*

The largest unsigned short, which bounds the label, the protocol and the retransmission limits of a channel

### webrtc.interfaces.rtc_data_channel.check_utf8_length(name, value)

Checks that a string, like the label of a channel, is at most 65535 bytes in UTF-8.

* **Parameters:**
  * **name** ([`str`](https://docs.python.org/3/builtins/stdtypes.html#str)) – The name of the string, for the error message.
  * **value** ([`str`](https://docs.python.org/3/builtins/stdtypes.html#str)) – The string.
* **Raises:**
  [**TypeError**](https://docs.python.org/3/builtins/exceptions.html#TypeError) – If it’s longer.

### *class* webrtc.interfaces.rtc_data_channel.RTCDataChannelInit(ordered=True, max_packet_life_time=None, max_retransmits=None, protocol='', negotiated=False, id=None, priority=RTCPriorityType.low)

The options of [`webrtc.RTCPeerConnection.create_data_channel()`](rtc_peer_connection.md#webrtc.interfaces.rtc_peer_connection.RTCPeerConnection.create_data_channel).

[`webrtc.RTCPeerConnection.create_data_channel()`](rtc_peer_connection.md#webrtc.interfaces.rtc_peer_connection.RTCPeerConnection.create_data_channel) checks them and raises [`TypeError`](https://docs.python.org/3/builtins/exceptions.html#TypeError) for invalid ones.

See [MDN: RTCPeerConnection/createDataChannel](https://developer.mozilla.org/en-US/docs/Web/API/RTCPeerConnection/createDataChannel).

* **Parameters:**
  * **ordered** ([`bool`](https://docs.python.org/3/builtins/functions.html#bool), optional) – Whether messages arrive in the order they were sent, [`True`](https://docs.python.org/3/builtins/constants.html#True) by default.
  * **max_packet_life_time** ([`int`](https://docs.python.org/3/builtins/functions.html#int), optional) – For how many milliseconds (0 to 65535) a message
    may be retransmitted. Setting it makes the channel unreliable.
  * **max_retransmits** ([`int`](https://docs.python.org/3/builtins/functions.html#int), optional) – How many times (0 to 65535) a message may be
    retransmitted. Setting it makes the channel unreliable. It can’t be set together with
    `max_packet_life_time`.
  * **protocol** ([`str`](https://docs.python.org/3/builtins/stdtypes.html#str), optional) – The subprotocol name, up to 65535 bytes in UTF-8, empty by default.
  * **negotiated** ([`bool`](https://docs.python.org/3/builtins/functions.html#bool), optional) – Whether the application creates the channel on both peers with the
    same `id`. Otherwise the connection announces it to the remote peer. [`False`](https://docs.python.org/3/builtins/constants.html#False) by default.
  * **id** ([`int`](https://docs.python.org/3/builtins/functions.html#int), optional) – The SCTP stream id (0 to 65534) of a `negotiated` channel.
    It’s required for such a channel and ignored otherwise, because the connection picks the id.
  * **priority** ([`webrtc.RTCPriorityType`](../enums.md#webrtc.enums.RTCPriorityType), optional) – The priority of the channel, `'low'` by default.

### *class* webrtc.interfaces.rtc_data_channel.RTCDataChannel(native_obj=None)

A bidirectional channel of text and binary messages between the peers.

Created with [`webrtc.RTCPeerConnection.create_data_channel()`](rtc_peer_connection.md#webrtc.interfaces.rtc_peer_connection.RTCPeerConnection.create_data_channel), or delivered by the `datachannel` event of
the connection when the remote peer creates one.

See [MDN: RTCDataChannel](https://developer.mozilla.org/en-US/docs/Web/API/RTCDataChannel).

* **Events:**
  * **open** ([`webrtc.Event`](../models/events.md#webrtc.models.events.Event)) – The channel is open and messages can be sent. It isn’t emitted if the
    channel closes before it opens.
  * **message** ([`webrtc.MessageEvent`](../models/events.md#webrtc.models.events.MessageEvent)) – A message arrived. Its `data` is a [`str`](https://docs.python.org/3/builtins/stdtypes.html#str) for text, and
    [`bytes`](https://docs.python.org/3/builtins/stdtypes.html#bytes) or a [`webrtc.Blob`](../models/blob.md#webrtc.models.blob.Blob) for binary, depending on [`binary_type`](#webrtc.interfaces.rtc_data_channel.RTCDataChannel.binary_type) at delivery.
  * **bufferedamountlow** ([`webrtc.Event`](../models/events.md#webrtc.models.events.Event)) – [`buffered_amount`](#webrtc.interfaces.rtc_data_channel.RTCDataChannel.buffered_amount) dropped to
    [`buffered_amount_low_threshold`](#webrtc.interfaces.rtc_data_channel.RTCDataChannel.buffered_amount_low_threshold) or below.
  * **error** ([`webrtc.RTCErrorEvent`](../models/events.md#webrtc.models.events.RTCErrorEvent)) – The channel failed, and closes right after.
  * **closing** ([`webrtc.Event`](../models/events.md#webrtc.models.events.Event)) – The channel started closing.
  * **close** ([`webrtc.Event`](../models/events.md#webrtc.models.events.Event)) – The channel is closed.

### Events

- `open`: [`Event`](../models/events.md#webrtc.models.events.Event)
- `bufferedamountlow`: [`Event`](../models/events.md#webrtc.models.events.Event)
- `closing`: [`Event`](../models/events.md#webrtc.models.events.Event)
- `close`: [`Event`](../models/events.md#webrtc.models.events.Event)
- `message`: [`MessageEvent`](../models/events.md#webrtc.models.events.MessageEvent)
- `error`: [`RTCErrorEvent`](../models/events.md#webrtc.models.events.RTCErrorEvent)

Handlers are registered with [`on()`](../events.md#webrtc.utils.events.UniformEventTarget.on).

#### *property* label *: [str](https://docs.python.org/3/builtins/stdtypes.html#str)*

The label the channel was created with. Several channels can share one.

See [MDN: RTCDataChannel/label](https://developer.mozilla.org/en-US/docs/Web/API/RTCDataChannel/label).

* **Type:**
  [`str`](https://docs.python.org/3/builtins/stdtypes.html#str)

#### *property* ordered *: [bool](https://docs.python.org/3/builtins/functions.html#bool)*

Whether messages arrive in the order they were sent.

See [MDN: RTCDataChannel/ordered](https://developer.mozilla.org/en-US/docs/Web/API/RTCDataChannel/ordered).

* **Type:**
  [`bool`](https://docs.python.org/3/builtins/functions.html#bool)

#### *property* max_packet_life_time *: [int](https://docs.python.org/3/builtins/functions.html#int) | [None](https://docs.python.org/3/builtins/constants.html#None)*

For how many milliseconds a message may be retransmitted, or [`None`](https://docs.python.org/3/builtins/constants.html#None) if unlimited.

See [MDN: RTCDataChannel/maxPacketLifeTime](https://developer.mozilla.org/en-US/docs/Web/API/RTCDataChannel/maxPacketLifeTime).

* **Type:**
  [`int`](https://docs.python.org/3/builtins/functions.html#int), optional

#### *property* max_retransmits *: [int](https://docs.python.org/3/builtins/functions.html#int) | [None](https://docs.python.org/3/builtins/constants.html#None)*

How many times a message may be retransmitted, or [`None`](https://docs.python.org/3/builtins/constants.html#None) if unlimited.

See [MDN: RTCDataChannel/maxRetransmits](https://developer.mozilla.org/en-US/docs/Web/API/RTCDataChannel/maxRetransmits).

* **Type:**
  [`int`](https://docs.python.org/3/builtins/functions.html#int), optional

#### *property* protocol *: [str](https://docs.python.org/3/builtins/stdtypes.html#str)*

The subprotocol name of the channel, or an empty string if there’s none.

See [MDN: RTCDataChannel/protocol](https://developer.mozilla.org/en-US/docs/Web/API/RTCDataChannel/protocol).

* **Type:**
  [`str`](https://docs.python.org/3/builtins/stdtypes.html#str)

#### *property* negotiated *: [bool](https://docs.python.org/3/builtins/functions.html#bool)*

Whether the application negotiated the channel.

Otherwise the connection announced it to the remote peer.
See [MDN: RTCDataChannel/negotiated](https://developer.mozilla.org/en-US/docs/Web/API/RTCDataChannel/negotiated).

* **Type:**
  [`bool`](https://docs.python.org/3/builtins/functions.html#bool)

#### *property* id *: [int](https://docs.python.org/3/builtins/functions.html#int) | [None](https://docs.python.org/3/builtins/constants.html#None)*

The SCTP stream id of the channel.

It’s [`None`](https://docs.python.org/3/builtins/constants.html#None) until the connection assigns it.
See [MDN: RTCDataChannel/id](https://developer.mozilla.org/en-US/docs/Web/API/RTCDataChannel/id).

* **Type:**
  [`int`](https://docs.python.org/3/builtins/functions.html#int), optional

#### *property* priority *: [webrtc.RTCPriorityType](../enums.md#webrtc.enums.RTCPriorityType)*

The priority of the channel.

See [MDN: RTCDataChannel/priority](https://developer.mozilla.org/en-US/docs/Web/API/RTCDataChannel/priority).

* **Type:**
  [`webrtc.RTCPriorityType`](../enums.md#webrtc.enums.RTCPriorityType)

#### *property* ready_state *: [webrtc.RTCDataChannelState](../enums.md#webrtc.enums.RTCDataChannelState)*

The state of the channel. It changes along with its events.

See [MDN: RTCDataChannel/readyState](https://developer.mozilla.org/en-US/docs/Web/API/RTCDataChannel/readyState).

* **Type:**
  [`webrtc.RTCDataChannelState`](../enums.md#webrtc.enums.RTCDataChannelState)

#### *property* buffered_amount *: [int](https://docs.python.org/3/builtins/functions.html#int)*

The bytes passed to [`send()`](#webrtc.interfaces.rtc_data_channel.RTCDataChannel.send) that aren’t sent yet.

See [MDN: RTCDataChannel/bufferedAmount](https://developer.mozilla.org/en-US/docs/Web/API/RTCDataChannel/bufferedAmount).

* **Type:**
  [`int`](https://docs.python.org/3/builtins/functions.html#int)

#### *property* buffered_amount_low_threshold *: [int](https://docs.python.org/3/builtins/functions.html#int)*

The [`buffered_amount`](#webrtc.interfaces.rtc_data_channel.RTCDataChannel.buffered_amount) at or below which `bufferedamountlow` is emitted, 0 by default.

Setting a value outside of 0 to 2\*\*64-1 raises [`ValueError`](https://docs.python.org/3/builtins/exceptions.html#ValueError).

See [MDN: RTCDataChannel/bufferedAmountLowThreshold](https://developer.mozilla.org/en-US/docs/Web/API/RTCDataChannel/bufferedAmountLowThreshold).

* **Type:**
  [`int`](https://docs.python.org/3/builtins/functions.html#int)

#### *property* binary_type *: [BinaryType](../enums.md#webrtc.enums.BinaryType)*

What binary messages are delivered as, `'arraybuffer'` by default.

`'arraybuffer'` delivers [`bytes`](https://docs.python.org/3/builtins/stdtypes.html#bytes) and `'blob'` a [`webrtc.Blob`](../models/blob.md#webrtc.models.blob.Blob). Setting a value that isn’t a
member raises [`ValueError`](https://docs.python.org/3/builtins/exceptions.html#ValueError).

See [MDN: RTCDataChannel/binaryType](https://developer.mozilla.org/en-US/docs/Web/API/RTCDataChannel/binaryType).

* **Type:**
  [`webrtc.BinaryType`](../enums.md#webrtc.enums.BinaryType)

#### send(data)

Queues a message to the remote peer, adding its size to [`buffered_amount`](#webrtc.interfaces.rtc_data_channel.RTCDataChannel.buffered_amount).

A [`str`](https://docs.python.org/3/builtins/stdtypes.html#str) is sent as a text message in UTF-8, anything else as a binary one.

See [MDN: RTCDataChannel/send](https://developer.mozilla.org/en-US/docs/Web/API/RTCDataChannel/send).

* **Parameters:**
  **data** ([`str`](https://docs.python.org/3/builtins/stdtypes.html#str), bytes-like or [`webrtc.Blob`](../models/blob.md#webrtc.models.blob.Blob)) – The message.
* **Raises:**
  * [**TypeError**](https://docs.python.org/3/builtins/exceptions.html#TypeError) – If the data is neither a [`str`](https://docs.python.org/3/builtins/stdtypes.html#str), bytes-like nor a [`webrtc.Blob`](../models/blob.md#webrtc.models.blob.Blob), or the message is
        larger than the maximum message size of the SCTP transport.
  * [**webrtc.InvalidStateError**](../exceptions.md#webrtc.exceptions.InvalidStateError) – If the channel isn’t open.
  * [**webrtc.OperationError**](../exceptions.md#webrtc.exceptions.OperationError) – If the send queue is full.

#### close()

Starts closing the channel, but messages queued before are still sent.

It does nothing if the channel is already closing.
See [MDN: RTCDataChannel/close](https://developer.mozilla.org/en-US/docs/Web/API/RTCDataChannel/close).