5.6 RTCIceTransport Interface

The RTCIceTransport interface allows an application access to information about the ICE transport over which packets are sent and received. In particular, ICE manages peer-to-peer connections which involve state which the application may want to access. RTCIceTransport objects are constructed as a result of calls to setLocalDescription() and setRemoteDescription(). The underlying ICE state is managed by the ICE agent; as such, the state of an RTCIceTransport changes when the ICE Agent provides indications to the user agent as described below. Each RTCIceTransport object represents the ICE transport layer for the RTP or RTCP component of a specific RTCRtpTransceiver, or a group of RTCRtpTransceivers if such a group has been negotiated via [RFC8843].

Note

An ICE restart for an existing RTCRtpTransceiver will be represented by an existing RTCIceTransport object, whose state will be updated accordingly, as opposed to being represented by a new object.

When the ICE Agent indicates that it began gathering a generation of candidates for an RTCIceTransport, the user agent MUST queue a task that runs the following steps:

1. Let connection be the RTCPeerConnection object associated with this ICE Agent.

2. If connection.[[IsClosed]] is true, abort these steps.

3. Let transport be the RTCIceTransport for which candidate gathering began.

4. Set transport.[[IceGathererState]] to gathering.

5. Fire an event named gatheringstatechange at transport.

6. Update the ICE gathering state of connection.

When the ICE Agent is finished gathering a generation of candidates for an RTCIceTransport, and those candidates have been surfaced to the application, the user agent MUST queue a task that runs the following steps:

1. Let connection be the RTCPeerConnection object associated with this ICE Agent.

2. If connection.[[IsClosed]] is true, abort these steps.

3. Let transport be the RTCIceTransport for which candidate gathering finished.

4. Let newCandidate be the result of creating an RTCIceCandidate with a new dictionary whose sdpMid and sdpMLineIndex are set to the values associated with this RTCIceTransport, usernameFragment is set to the username fragment of the generation of candidates for which gathering finished, and candidate is set to an empty string.

5. Fire an event named icecandidate using the RTCPeerConnectionIceEvent interface with the candidate attribute set to newCandidate at connection.

6. If another generation of candidates is still being gathered, abort these steps.

   Note

   This may occur if an ICE restart is initiated while the ICE agent is still gathering the previous generation of candidates.

7. Set transport.[[IceGathererState]] to complete.

8. Fire an event named gatheringstatechange at transport.

9. Update the ICE gathering state of connection.

When the ICE Agent indicates that a new ICE candidate is available for an RTCIceTransport, either by taking one from the ICE candidate pool or gathering it from scratch, the user agent MUST queue a task that runs the following steps:

1. Let candidate be the available ICE candidate.

2. Let connection be the RTCPeerConnection object associated with this ICE Agent.

3. If connection.[[IsClosed]] is true, abort these steps.

4. If either connection.[[PendingLocalDescription]] or connection.[[CurrentLocalDescription]] are not null, and represent the ICE generation for which candidate was gathered, surface the candidate with candidate and connection, and abort these steps.

5. Otherwise, append candidate to connection.[[EarlyCandidates]].

When the ICE Agent signals that the ICE role has changed due to an ICE binding request with a role collision per [RFC8445] section 7.3.1.1, the UA will queue a task to set the value of [[IceRole]] to the new value.

To release early candidates of a connection, run the following steps:

1. For each candidate, candidate, in connection.[[EarlyCandidates]], queue a task to surface the candidate with candidate and connection.

2. Set connection.[[EarlyCandidates]] to an empty list.

To surface a candidate with candidate and connection, run the following steps:

1. If connection.[[IsClosed]] is true, abort these steps.

2. Let transport be the RTCIceTransport for which candidate is being made available.

3. If connection.[[PendingLocalDescription]] is not null, and represents the ICE generation for which candidate was gathered, add candidate to connection.[[PendingLocalDescription]].sdp.

4. If connection.[[CurrentLocalDescription]] is not null, and represents the ICE generation for which candidate was gathered, add candidate to connection.[[CurrentLocalDescription]].sdp.

5. Let newCandidate be the result of creating an RTCIceCandidate with a new dictionary whose sdpMid and sdpMLineIndex are set to the values associated with this RTCIceTransport, usernameFragment is set to the username fragment of the candidate, and candidate is set to a string encoded using the candidate-attribute grammar to represent candidate.

6. Add newCandidate to transport’s set of local candidates.

7. Fire an event named icecandidate using the RTCPeerConnectionIceEvent interface with the candidate attribute set to newCandidate at connection.

The RTCIceTransportState of an RTCIceTransport may change because a candidate pair with a usable connection was found and selected or it may change without the selected candidate pair changing. The selected pair and RTCIceTransportState are related and are handled in the same task.

When the ICE Agent indicates that an RTCIceTransport has changed either the selected candidate pair, the RTCIceTransportState or both, the user agent MUST queue a task that runs the following steps:

1. Let connection be the RTCPeerConnection object associated with this ICE Agent.

2. If connection.[[IsClosed]] is true, abort these steps.

3. Let transport be the RTCIceTransport whose state is changing.

4. Let selectedCandidatePairChanged be false.

5. Let transportIceConnectionStateChanged be false.

6. Let connectionIceConnectionStateChanged be false.

7. Let connectionStateChanged be false.

8. If transport’s selected candidate pair was changed, run the following steps:

   1. Let newCandidatePair be a newly created RTCIceCandidatePair representing the indicated pair if one is selected, and null otherwise.

   2. Set transport.[[SelectedCandidatePair]] to newCandidatePair.

   3. Set selectedCandidatePairChanged to true.

9. If transport’s RTCIceTransportState was changed, run the following steps:

   1. Set transport.[[IceTransportState]] to the new indicated RTCIceTransportState.

   2. Set transportIceConnectionStateChanged to true.

   3. Set connection’s ICE connection state to the value of deriving a new state value as described by the RTCIceConnectionState enum.

   4. If the ice connection state changed in the previous step, set connectionIceConnectionStateChanged to true.

   5. Set connection’s connection state to the value of deriving a new state value as described by the RTCPeerConnectionState enum.

   6. If the connection state changed in the previous step, set connectionStateChanged to true.

10. If selectedCandidatePairChanged is true, fire an event named selectedcandidatepairchange at transport.

11. If transportIceConnectionStateChanged is true, fire an event named statechange at transport.

12. If connectionIceConnectionStateChanged is true, fire an event named iceconnectionstatechange at connection.

13. If connectionStateChanged is true, fire an event named connectionstatechange at connection.

An RTCIceTransport object has the following internal slots:

• [[IceTransportState]] initialized to “new“
• [[IceGathererState]] initialized to “new“
• [[SelectedCandidatePair]] initialized to null
• [[IceRole]] initialized to “unknown“

WebIDL[Exposed=Window]
interface RTCIceTransport : EventTarget {
  readonly attribute RTCIceRole role;
  readonly attribute RTCIceComponent component;
  readonly attribute RTCIceTransportState state;
  readonly attribute RTCIceGathererState gatheringState;
  sequence<RTCIceCandidate> getLocalCandidates();
  sequence<RTCIceCandidate> getRemoteCandidates();
  RTCIceCandidatePair? getSelectedCandidatePair();
  RTCIceParameters? getLocalParameters();
  RTCIceParameters? getRemoteParameters();
  attribute EventHandler onstatechange;
  attribute EventHandler ongatheringstatechange;
  attribute EventHandler onselectedcandidatepairchange;
};

Attributes

role of type RTCIceRole, readonly

The role attribute MUST, on getting, return the value of the [[IceRole]] internal slot.

component of type RTCIceComponent, readonly

The component attribute MUST return the ICE component of the transport. When RTCP mux is used, a single RTCIceTransport transports both RTP and RTCP and component is set to “rtp“.

state of type RTCIceTransportState, readonly

The state attribute MUST, on getting, return the value of the [[IceTransportState]] slot.

gatheringState of type RTCIceGathererState, readonly

The gatheringState attribute MUST, on getting, return the value of the [[IceGathererState]] slot.

onstatechange of type EventHandler

This event handler, of event handler event type statechange, MUST be fired any time the RTCIceTransport state changes.

ongatheringstatechange of type EventHandler

This event handler, of event handler event type gatheringstatechange, MUST be fired any time the RTCIceTransport ICE gathering state changes.

onselectedcandidatepairchange of type EventHandler

This event handler, of event handler event type selectedcandidatepairchange, MUST be fired any time the RTCIceTransport‘s selected candidate pair changes.

Methods

getLocalCandidates

Returns a sequence describing the local ICE candidates gathered for this RTCIceTransport and sent in onicecandidate.

getRemoteCandidates

Returns a sequence describing the remote ICE candidates received by this RTCIceTransport via addIceCandidate().

Note

getRemoteCandidates will not expose peer reflexive candidates since they are not received via addIceCandidate().

getSelectedCandidatePair

Returns the selected candidate pair on which packets are sent. This method MUST return the value of the [[SelectedCandidatePair]] slot. When RTCIceTransport.state is “new“ or “closed“ getSelectedCandidatePair returns null.

getLocalParameters

Returns the local ICE parameters received by this RTCIceTransport via setLocalDescription, or null if the parameters have not yet been received.

getRemoteParameters

Returns the remote ICE parameters received by this RTCIceTransport via setRemoteDescription or null if the parameters have not yet been received.

5.6.1 RTCIceParameters Dictionary

WebIDLdictionary RTCIceParameters {
  DOMString usernameFragment;
  DOMString password;
};

Dictionary RTCIceParameters Members

usernameFragment of type DOMString

The ICE username fragment as defined in [RFC5245], Section 7.1.2.3.

password of type DOMString

The ICE password as defined in [RFC5245], Section 7.1.2.3.

5.6.2 RTCIceCandidatePair Dictionary

WebIDLdictionary RTCIceCandidatePair {
  RTCIceCandidate local;
  RTCIceCandidate remote;
};

Dictionary RTCIceCandidatePair Members

local of type RTCIceCandidate

The local ICE candidate.

remote of type RTCIceCandidate

The remote ICE candidate.

5.6.3 RTCIceGathererState Enum

WebIDLenum RTCIceGathererState {
  "new",
  "gathering",
  "complete"
};

5.6.4 RTCIceTransportState Enum

WebIDLenum RTCIceTransportState {
  "new",
  "checking",
  "connected",
  "completed",
  "disconnected",
  "failed",
  "closed"
};

Note

The most common transitions for a successful call will be new -> checking -> connected -> completed, but under specific circumstances (only the last checked candidate succeeds, and gathering and the no-more candidates indication both occur prior to success), the state can transition directly from “checking“ to “completed“.

An ICE restart causes candidate gathering and connectivity checks to begin anew, causing a transition to “connected“ if begun in the “completed“ state. If begun in the transient “disconnected“ state, it causes a transition to “checking“, effectively forgetting that connectivity was previously lost.

The “failed“ and “completed“ states require an indication that there are no additional remote candidates. This can be indicated by calling addIceCandidate with a candidate value whose candidate property is set to an empty string or by canTrickleIceCandidates being set to false.

Some example state transitions are:

• (RTCIceTransport first created, as a result of setLocalDescription or setRemoteDescription): “new“
• (“new“, remote candidates received): “checking“
• (“checking“, found usable connection): “connected“
• (“checking“, checks fail but gathering still in progress): “disconnected“
• (“checking“, gave up): “failed“
• (“disconnected“, new local candidates): “checking“
• (“connected“, finished all checks): “completed“
• (“completed“, lost connectivity): “disconnected“
• (“disconnected“ or “failed“, ICE restart occurs): “checking“
• (“completed“, ICE restart occurs): “connected“
• RTCPeerConnection.close(): “closed“

Figure 2 Non-normative ICE transport state transition diagram

5.6.5 RTCIceRole Enum

WebIDLenum RTCIceRole {
  "unknown",
  "controlling",
  "controlled"
};

5.6.6 RTCIceComponent Enum

WebIDLenum RTCIceComponent {
  "rtp",
  "rtcp"
};