RTCIceTransportState

The RTCIceTransportState enumerated type defines the string values which may be returned by the state property on RTCIceTransport objects. The transport state indicates which stage of the candidate gathering process is currently underway.

Values

"new"
The RTCIceTransport is currently gathering local candidates, or is waiting for the remote device to begin to transmit the remote candidates, or both. In this state, checking of candidates to look for those which might be acceptable has not yet begun.
"checking"
At least one remote candidate has been received, and the RTCIceTransport has begun examining pairings of remote and local candidates in order to attempt to identify viable pairs that could be used to establish a connection. Keep in mind that gathering of local candidates may still be underway, and, similarly, the remote device also may still be gathering candidates of its own.
"connected"

A viable candidate pair has been found and selected, and the RTCIceTransport has connected the two peers together using that pair. However, there are still candidates pairings to consider, and there may still be gathering underway on one or both of the two devices.

The transport may revert from the "connected" state to the "checking" state if either peer decides to cancel consent to use the selected candidate pair, and may revert to "disconnected" if there are no candidates left to check but one or both clients are still gathering candidates.

"completed"
The transport has finished gathering local candidates and has received a notification from the remote peer that no more candidates will be sent. In addition, all candidate pairs have been considered and a pair has been selected for use. If consent checks fail on all successful candidate pairs, the transport state will change to "failed".
"disconnected"
The ICE agent has determined that connectivity has been lost for this RTCIceTransport. This is not a failure state (that's "failed"). A value of "disconnected" means that a transient issue has occurred that has broken the connection, but that should resolve itself automatically without your code having to take any action. See The disconnected state for additional details.
"failed"
The RTCIceTransport has finished the gathering process, has received the "no more candidates" notification from the remote peer, and has finished checking pairs of candidates, without successfully finding a pair that is both valid and for which consent can be obtained. This is a terminal state, indicating that the connection cannot be achieved or maintained.
"closed"
The transport has shut down and is no longer responding to STUN requests.

Usage notes

If an ICE restart occurs, the candidate gathering and connectivity check process is started over again; this will cause a transition from the "connected" state if the restart occurred while the state was "completed". If the restart occured during a transient "disconnected" state,  the state transitions to "checking"

The disconnected state

"disconnected" is a transient state that occurs when the connection between the two peers fails in a manner that the WebRTC infrastructure can automatically correct once the connection is available again. It is not a failure state. Instead, you can think of "disconnected" as being similar to "checking" but with the added information that the connection had been working but at the moment is not.

Every user agent and platform may have its own scenarios that can trigger the "disconnected" state. Possible causes include:

  • The network interface being used by the connection has gone offline.
  • STUN requests being sent to the remote device have gone unanswered repeatedly.

The "disconnected" state can also occur when the transport has finished checking all existing candidate pairs and has not found a pair that will work—or a valid pair was found but rejected due to consent to use the pair being denied. In this scenario, the transport is still continuing to gather candidates, and/or to wait for candidates to be sent by the remote peer.

Specifications

Specification Status Comment
WebRTC 1.0: Real-time Communication Between Browsers
The definition of 'RTCIceRole' in that specification.
Candidate Recommendation Initial definition.

Browser compatibility

No compatibility data found. Please contribute data for "api.RTCIceRole" (depth: 1) to the MDN compatibility data repository.

Document Tags and Contributors

Contributors to this page: Sheppy
Last updated by: Sheppy,