6.1 RTCPeerConnection Interface Extensions

The Peer-to-peer data API extends the RTCPeerConnection interface as described below.

WebIDL          partial interface RTCPeerConnection {
  readonly attribute RTCSctpTransport? sctp;
  RTCDataChannel createDataChannel(USVString label,
                                   optional RTCDataChannelInit dataChannelDict = {});
  attribute EventHandler ondatachannel;
};

Attributes

sctp of type RTCSctpTransport, readonly, nullable

The SCTP transport over which SCTP data is sent and received. If SCTP has not been negotiated, the value is null. This attribute MUST return the RTCSctpTransport object stored in the [[SctpTransport]] internal slot.

ondatachannel of type EventHandler

The event type of this event handler is datachannel.

Methods

createDataChannel

Creates a new RTCDataChannel object with the given label. The RTCDataChannelInit dictionary can be used to configure properties of the underlying channel such as data reliability.

When the createDataChannel method is invoked, the user agent MUST run the following steps.

1. Let connection be the RTCPeerConnection object on which the method is invoked.

2. If connection.[[IsClosed]] is true, throw an InvalidStateError.

3. Create an RTCDataChannel, channel.

4. Initialize channel.[[DataChannelLabel]] to the value of the first argument.

5. If the UTF-8 representation of [[DataChannelLabel]] is longer than 65535 bytes, throw a TypeError.

6. Let options be the second argument.

7. Initialize channel.[[MaxPacketLifeTime]] to option.maxPacketLifeTime, if present, otherwise null.

8. Initialize channel.[[MaxRetransmits]] to option.maxRetransmits, if present, otherwise null.

9. Initialize channel.[[Ordered]] to option.ordered.

10. Initialize channel.[[DataChannelProtocol]] to option.protocol.

11. If the UTF-8 representation of [[DataChannelProtocol]] is longer than 65535 bytes, throw a TypeError.

12. Initialize channel.[[Negotiated]] to option.negotiated.

13. Initialize channel.[[DataChannelId]] to the value of option.id, if it is present and [[Negotiated]] is true, otherwise null.

    Note

    This means the id member will be ignored if the data channel is negotiated in-band; this is intentional. Data channels negotiated in-band should have IDs selected based on the DTLS role, as specified in [RFC8832].

14. If [[Negotiated]] is true and [[DataChannelId]] is null, throw a TypeError.

15. If both [[MaxPacketLifeTime]] and [[MaxRetransmits]] attributes are set (not null), throw a TypeError.

16. If a setting, either [[MaxPacketLifeTime]] or [[MaxRetransmits]], has been set to indicate unreliable mode, and that value exceeds the maximum value supported by the user agent, the value MUST be set to the user agents maximum value.

17. If [[DataChannelId]] is equal to 65535, which is greater than the maximum allowed ID of 65534 but still qualifies as an unsigned short, throw a TypeError.

18. If the [[DataChannelId]] slot is null (due to no ID being passed into createDataChannel, or [[Negotiated]] being false), and the DTLS role of the SCTP transport has already been negotiated, then initialize [[DataChannelId]] to a value generated by the user agent, according to [RFC8832], and skip to the next step. If no available ID could be generated, or if the value of the [[DataChannelId]] slot is being used by an existing RTCDataChannel, throw an OperationError exception.

    Note

    If the [[DataChannelId]] slot is null after this step, it will be populated during the RTCSctpTransport connected procedure.

19. Let transport be connection.[[SctpTransport]].

    If the [[DataChannelId]] slot is not null, transport is in the “connected“ state and [[DataChannelId]] is greater or equal to transport.[[MaxChannels]], throw an OperationError.

20. If channel is the first RTCDataChannel created on connection, update the negotiation-needed flag for connection.

21. Return channel and continue the following steps in parallel.

22. Create channel’s associated underlying data transport and configure it according to the relevant properties of channel.

6.1.1 RTCSctpTransport Interface

The RTCSctpTransport interface allows an application access to information about the SCTP data channels tied to a particular SCTP association.

6.1.1.1 Create an instance

To create an RTCSctpTransport with an initial state, initialState, run the following steps:

1. Let transport be a new RTCSctpTransport object.

2. Let transport have a [[SctpTransportState]] internal slot initialized to initialState.

3. Let transport have a [[MaxMessageSize]] internal slot and run the steps labeled update the data max message size to initialize it.

4. Let transport have a [[MaxChannels]] internal slot initialized to null.

5. Return transport.

6.1.1.2 Update max message size

To update the data max message size of an RTCSctpTransport run the following steps:

1. Let transport be the RTCSctpTransport object to be updated.

2. Let remoteMaxMessageSize be the value of the max-message-size SDP attribute read from the remote description, as described in [RFC8841] (section 6), or 65536 if the attribute is missing.

3. Let canSendSize be the number of bytes that this client can send (i.e. the size of the local send buffer) or 0 if the implementation can handle messages of any size.

4. If both remoteMaxMessageSize and canSendSize are 0, set [[MaxMessageSize]] to the positive Infinity value.

5. Else, if either remoteMaxMessageSize or canSendSize is 0, set [[MaxMessageSize]] to the larger of the two.

6. Else, set [[MaxMessageSize]] to the smaller of remoteMaxMessageSize or canSendSize.

6.1.1.3 Connected procedure

Once an SCTP transport is connected, meaning the SCTP association of an RTCSctpTransport has been established, run the following steps:

1. Let transport be the RTCSctpTransport object.

2. Let connection be the RTCPeerConnection object associated with transport.

3. Set [[MaxChannels]] to the minimum of the negotiated amount of incoming and outgoing SCTP streams.

4. For each of connection’s RTCDataChannel:

   1. Let channel be the RTCDataChannel object.

   2. If channel.[[DataChannelId]] is null, initialize [[DataChannelId]] to the value generated by the underlying sctp data channel, according to [RFC8832].

   3. If channel.[[DataChannelId]] is greater or equal to transport.[[MaxChannels]], or the previous step failed to assign an id, close the channel due to a failure. Otherwise, announce the channel as open.

5. Fire an event named [`statechange`](#event-sctptransport-statechange) at transport.

   Note

   This event is fired before the open events fired by announcing the channel as open; the open events are fired from a queued task.

WebIDL[Exposed=Window]
interface RTCSctpTransport : EventTarget {
  readonly attribute RTCDtlsTransport transport;
  readonly attribute RTCSctpTransportState state;
  readonly attribute unrestricted double maxMessageSize;
  readonly attribute unsigned short? maxChannels;
  attribute EventHandler onstatechange;
};

Attributes

transport of type RTCDtlsTransport, readonly

The transport over which all SCTP packets for data channels will be sent and received.

state of type RTCSctpTransportState, readonly

The current state of the SCTP transport. On getting, this attribute MUST return the value of the [[SctpTransportState]] slot.

maxMessageSize of type unrestricted double, readonly

The maximum size of data that can be passed to RTCDataChannel‘s send() method. The attribute MUST, on getting, return the value of the [[MaxMessageSize]] slot.

maxChannels of type unsigned short , readonly, nullable

The maximum amount of RTCDataChannel‘s that can be used simultaneously. The attribute MUST, on getting, return the value of the [[MaxChannels]] slot.

Note

This attribute’s value will be null until the SCTP transport goes into the “connected“ state.

onstatechange of type EventHandler

The event type of this event handler is [`statechange`](#event-sctptransport-statechange).

6.1.2 RTCSctpTransportState Enum

RTCSctpTransportState indicates the state of the SCTP transport.

WebIDLenum RTCSctpTransportState {
  "connecting",
  "connected",
  "closed"
};