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) – The name of the string, for the error message.

• value (str) – The string.

Raises:

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

webrtc.RTCPeerConnection.create_data_channel() checks them and raises TypeError for invalid ones.

See MDN: RTCPeerConnection/createDataChannel.

Parameters:

• ordered (bool, optional) – Whether messages arrive in the order they were sent, True by default.

• max_packet_life_time (int, optional) – For how many milliseconds (0 to 65535) a message may be retransmitted. Setting it makes the channel unreliable.

• max_retransmits (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, optional) – The subprotocol name, up to 65535 bytes in UTF-8, empty by default.

• negotiated (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 by default.

• id (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, 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(), or delivered by the datachannel event of the connection when the remote peer creates one.

See MDN: RTCDataChannel.

Events:

• open (webrtc.Event) – The channel is open and messages can be sent. It isn’t emitted if the channel closes before it opens.

• message (webrtc.MessageEvent) – A message arrived. Its data is a str for text, and bytes or a webrtc.Blob for binary, depending on binary_type at delivery.

• bufferedamountlow (webrtc.Event) – buffered_amount dropped to buffered_amount_low_threshold or below.

• error (webrtc.RTCErrorEvent) – The channel failed, and closes right after.

• closing (webrtc.Event) – The channel started closing.

• close (webrtc.Event) – The channel is closed.

Events

• open: Event

• bufferedamountlow: Event

• closing: Event

• close: Event

• message: MessageEvent

• error: RTCErrorEvent

Handlers are registered with on().

property label: str

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

See MDN: RTCDataChannel/label.

Type:

str

property ordered: bool

Whether messages arrive in the order they were sent.

See MDN: RTCDataChannel/ordered.

Type:

bool

property max_packet_life_time: int | None

For how many milliseconds a message may be retransmitted, or None if unlimited.

See MDN: RTCDataChannel/maxPacketLifeTime.

Type:

int, optional

property max_retransmits: int | None

How many times a message may be retransmitted, or None if unlimited.

See MDN: RTCDataChannel/maxRetransmits.

Type:

int, optional

property protocol: str

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

See MDN: RTCDataChannel/protocol.

Type:

str

property negotiated: bool

Whether the application negotiated the channel.

Otherwise the connection announced it to the remote peer. See MDN: RTCDataChannel/negotiated.

Type:

bool

property id: int | None

The SCTP stream id of the channel.

It’s None until the connection assigns it. See MDN: RTCDataChannel/id.

Type:

int, optional

property priority: webrtc.RTCPriorityType

The priority of the channel.

See MDN: RTCDataChannel/priority.

Type:

webrtc.RTCPriorityType

property ready_state: webrtc.RTCDataChannelState

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

See MDN: RTCDataChannel/readyState.

Type:

webrtc.RTCDataChannelState

property buffered_amount: int

The bytes passed to send() that aren’t sent yet.

See MDN: RTCDataChannel/bufferedAmount.

Type:

int

property buffered_amount_low_threshold: int

The buffered_amount at or below which bufferedamountlow is emitted, 0 by default.

Setting a value outside of 0 to 2**64-1 raises ValueError.

See MDN: RTCDataChannel/bufferedAmountLowThreshold.

Type:

int

property binary_type: BinaryType

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

'arraybuffer' delivers bytes and 'blob' a webrtc.Blob. Setting a value that isn’t a member raises ValueError.

See MDN: RTCDataChannel/binaryType.

Type:

webrtc.BinaryType

send(data)

Queues a message to the remote peer, adding its size to buffered_amount.

A str is sent as a text message in UTF-8, anything else as a binary one.

See MDN: RTCDataChannel/send.

Parameters:

data (str, bytes-like or webrtc.Blob) – The message.

Raises:

• TypeError – If the data is neither a str, bytes-like nor a webrtc.Blob, or the message is larger than the maximum message size of the SCTP transport.

• webrtc.InvalidStateError – If the channel isn’t open.

• webrtc.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.