4.8 Interfaces for Interactive Connectivity Establishment

4.8.1 RTCIceCandidate Interface

This interface describes an ICE candidate, described in [RFC5245] Section 2. Other than candidate, sdpMid, sdpMLineIndex, and usernameFragment, the remaining attributes are derived from parsing the candidate member in candidateInitDict, if it is well formed.

WebIDL[Exposed=Window]
interface RTCIceCandidate {
  constructor(optional RTCIceCandidateInit candidateInitDict = {});
  readonly attribute DOMString candidate;
  readonly attribute DOMString? sdpMid;
  readonly attribute unsigned short? sdpMLineIndex;
  readonly attribute DOMString? foundation;
  readonly attribute RTCIceComponent? component;
  readonly attribute unsigned long? priority;
  readonly attribute DOMString? address;
  readonly attribute RTCIceProtocol? protocol;
  readonly attribute unsigned short? port;
  readonly attribute RTCIceCandidateType? type;
  readonly attribute RTCIceTcpCandidateType? tcpType;
  readonly attribute DOMString? relatedAddress;
  readonly attribute unsigned short? relatedPort;
  readonly attribute DOMString? usernameFragment;
  RTCIceCandidateInit toJSON();
};

Constructor

constructor()

The RTCIceCandidate() constructor takes a dictionary argument, candidateInitDict, whose content is used to initialize the new RTCIceCandidate object.

When invoked, run the following steps:

1. If both the sdpMid and sdpMLineIndex members of candidateInitDict are null, throw a TypeError.
2. Return the result of creating an RTCIceCandidate with candidateInitDict.

To create an RTCIceCandidate with a candidateInitDict dictionary, run the following steps:

1. Let iceCandidate be a newly created RTCIceCandidate object.
2. Create internal slots for the following attributes of iceCandidate, initilized to null: foundation, component, priority, address, protocol, port, type, tcpType, relatedAddress, and relatedPort.
3. Create internal slots for the following attributes of iceCandidate, initilized to their namesakes in candidateInitDict: candidate, sdpMid, sdpMLineIndex, usernameFragment.
4. Let candidate be the candidate dictionary member of candidateInitDict. If candidate is not an empty string, run the following steps:
   1. Parse candidate using the candidate-attribute grammar.
   2. If parsing of candidate-attribute has failed, abort these steps.
   3. If any field in the parse result represents an invalid value for the corresponding attribute in iceCandidate, abort these steps.
   4. Set the corresponding internal slots in iceCandidate to the field values of the parsed result.
5. Return iceCandidate.

Note

The constructor for RTCIceCandidate only does basic parsing and type checking for the dictionary members in candidateInitDict. Detailed validation on the well-formedness of candidate, sdpMid, sdpMLineIndex, usernameFragment with the corresponding session description is done when passing the RTCIceCandidate object to addIceCandidate().

To maintain backward compatibility, any error on parsing the candidate attribute is ignored. In such case, the candidate attribute holds the raw candidate string given in candidateInitDict, but derivative attributes such as foundation, priority, etc are set to null.

Attributes

Most attributes below are defined in section 15.1 of [RFC5245].

candidate of type DOMString, readonly

This carries the candidate-attribute as defined in section 15.1 of [RFC5245]. If this RTCIceCandidate represents an end-of-candidates indication or a peer reflexive remote candidate, candidate is an empty string.

sdpMid of type DOMString, readonly, nullable

If not null, this contains the media stream “identification-tag” defined in [RFC5888] for the media component this candidate is associated with.

sdpMLineIndex of type unsigned short, readonly, nullable

If not null, this indicates the index (starting at zero) of the media description in the SDP this candidate is associated with.

foundation of type DOMString, readonly, nullable

A unique identifier that allows ICE to correlate candidates that appear on multiple RTCIceTransports.

component of type RTCIceComponent, readonly, nullable

The assigned network component of the candidate (“rtp“ or “rtcp“). This corresponds to the component-id field in candidate-attribute, decoded to the string representation as defined in RTCIceComponent.

priority of type unsigned long, readonly, nullable

The assigned priority of the candidate.

address of type DOMString, readonly, nullable

The address of the candidate, allowing for IPv4 addresses, IPv6 addresses, and fully qualified domain names (FQDNs). This corresponds to the connection-address field in candidate-attribute.

Remote candidates may be exposed, for instance via [[SelectedCandidatePair]].remote. By default, the user agent MUST leave the address attribute as null for any exposed remote candidate. Once a RTCPeerConnection instance learns on an address by the web application using addIceCandidate, the user agent can expose the address attribute value in any RTCIceCandidate of the RTCPeerConnection instance representing a remote candidate with that newly learnt address.

Note

The addresses exposed in candidates gathered via ICE and made visibile to the application in RTCIceCandidate instances can reveal more information about the device and the user (e.g. location, local network topology) than the user might have expected in a non-WebRTC enabled browser.

These addresses are always exposed to the application, and potentially exposed to the communicating party, and can be exposed without any specific user consent (e.g. for peer connections used with data channels, or to receive media only).

These addresses can also be used as temporary or persistent cross-origin states, and thus contribute to the fingerprinting surface of the device.

Applications can avoid exposing addresses to the communicating party, either temporarily or permanently, by forcing the ICE Agent to report only relay candidates via the iceTransportPolicy member of RTCConfiguration.

To limit the addresses exposed to the application itself, browsers can offer their users different policies regarding sharing local addresses, as defined in [RFC8828].

protocol of type RTCIceProtocol, readonly, nullable

The protocol of the candidate (“udp“/“tcp“). This corresponds to the transport field in candidate-attribute.

port of type unsigned short, readonly, nullable

The port of the candidate.

type of type RTCIceCandidateType, readonly, nullable

The type of the candidate. This corresponds to the candidate-types field in candidate-attribute.

tcpType of type RTCIceTcpCandidateType, readonly, nullable

If protocol is “tcp“, tcpType represents the type of TCP candidate. Otherwise, tcpType is null. This corresponds to the tcp-type field in candidate-attribute.

relatedAddress of type DOMString, readonly, nullable

For a candidate that is derived from another, such as a relay or reflexive candidate, the relatedAddress is the IP address of the candidate that it is derived from. For host candidates, the relatedAddress is null. This corresponds to the rel-address field in candidate-attribute.

relatedPort of type unsigned short, readonly, nullable

For a candidate that is derived from another, such as a relay or reflexive candidate, the relatedPort is the port of the candidate that it is derived from. For host candidates, the relatedPort is null. This corresponds to the rel-port field in candidate-attribute.

usernameFragment of type DOMString, readonly, nullable

This carries the ufrag as defined in section 15.4 of [RFC5245].

Methods

toJSON()

To invoke the toJSON() operation of the RTCIceCandidate interface, run the following steps:

1. Let json be a new RTCIceCandidateInit dictionary.
2. For each attribute identifier attr in «candidate, sdpMid, sdpMLineIndex, usernameFragment»:
   1. Let value be the result of getting the underlying value of the attribute identified by attr, given this RTCIceCandidate object.
   2. Set json[attr] to value.
3. Return json.

WebIDLdictionary RTCIceCandidateInit {
  DOMString candidate = "";
  DOMString? sdpMid = null;
  unsigned short? sdpMLineIndex = null;
  DOMString? usernameFragment = null;
};

Dictionary RTCIceCandidateInit Members

candidate of type DOMString, defaulting to ""

This carries the candidate-attribute as defined in section 15.1 of [RFC5245]. If this represents an end-of-candidates indication, candidate is an empty string.

sdpMid of type DOMString, nullable, defaulting to null

If not null, this contains the media stream “identification-tag” defined in [RFC5888] for the media component this candidate is associated with.

sdpMLineIndex of type unsigned short, nullable, defaulting to null

If not null, this indicates the index (starting at zero) of the media description in the SDP this candidate is associated with.

usernameFragment of type DOMString, nullable, defaulting to null

If not null, this carries the ufrag as defined in section 15.4 of [RFC5245].

4.8.1.1 candidate-attribute Grammar

The candidate-attribute grammar is used to parse the candidate member of candidateInitDict in the RTCIceCandidate() constructor.

The primary grammar for candidate-attribute is defined in section 15.1 of [RFC5245]. In addition, the browser MUST support the grammar extension for ICE TCP as defined in section 4.5 of [RFC6544].

The browser MAY support other grammar extensions for candidate-attribute as defined in other RFCs.

4.8.1.2 RTCIceProtocol Enum

The RTCIceProtocol represents the protocol of the ICE candidate.

WebIDLenum RTCIceProtocol {
  "udp",
  "tcp"
};

4.8.1.3 RTCIceTcpCandidateType Enum

The RTCIceTcpCandidateType represents the type of the ICE TCP candidate, as defined in [RFC6544].

WebIDLenum RTCIceTcpCandidateType {
  "active",
  "passive",
  "so"
};

Note

The user agent will typically only gather active ICE TCP candidates.

4.8.1.4 RTCIceCandidateType Enum

The RTCIceCandidateType represents the type of the ICE candidate, as defined in [RFC5245] section 15.1.

WebIDLenum RTCIceCandidateType {
  "host",
  "srflx",
  "prflx",
  "relay"
};

4.8.2 RTCPeerConnectionIceEvent

The icecandidate event of the RTCPeerConnection uses the RTCPeerConnectionIceEvent interface.

When firing an RTCPeerConnectionIceEvent event that contains an RTCIceCandidate object, it MUST include values for both sdpMid and sdpMLineIndex. If the RTCIceCandidate is of type “srflx“ or type “relay“, the url property of the event MUST be set to the URL of the ICE server from which the candidate was obtained.

Note

The icecandidate event is used for three different types of indications:

• A candidate has been gathered. The candidate member of the event will be populated normally. It should be signaled to the remote peer and passed into addIceCandidate.

• An RTCIceTransport has finished gathering a generation of candidates, and is providing an end-of-candidates indication as defined by Section 8.2 of [RFC8838]. This is indicated by candidate.candidate being set to an empty string. The candidate object should be signaled to the remote peer and passed into addIceCandidate like a typical ICE candidate, in order to provide the end-of-candidates indication to the remote peer.

• All RTCIceTransports have finished gathering candidates, and the RTCPeerConnection‘s RTCIceGatheringState has transitioned to “complete“. This is indicated by the candidate member of the event being set to null. This only exists for backwards compatibility, and this event does not need to be signaled to the remote peer. It’s equivalent to an icegatheringstatechange event with the “complete“ state.

WebIDL[Exposed=Window]
interface RTCPeerConnectionIceEvent : Event {
  constructor(DOMString type, optional RTCPeerConnectionIceEventInit eventInitDict = {});
  readonly attribute RTCIceCandidate? candidate;
  readonly attribute DOMString? url;
};

Constructors

RTCPeerConnectionIceEvent.constructor()

Attributes

candidate of type RTCIceCandidate, readonly, nullable

The candidate attribute is the RTCIceCandidate object with the new ICE candidate that caused the event.

This attribute is set to null when an event is generated to indicate the end of candidate gathering.

Note

Even where there are multiple media components, only one event containing a null candidate is fired.

url of type DOMString, readonly, nullable

The url attribute is the STUN or TURN URL that identifies the STUN or TURN server used to gather this candidate. If the candidate was not gathered from a STUN or TURN server, this parameter will be set to null.

WebIDL            dictionary RTCPeerConnectionIceEventInit : EventInit {
  RTCIceCandidate? candidate;
  DOMString? url;
};

Dictionary RTCPeerConnectionIceEventInit Members

candidate of type RTCIceCandidate, nullable

See the candidate attribute of the RTCPeerConnectionIceEvent interface.

url of type DOMString, nullable

The url attribute is the STUN or TURN URL that identifies the STUN or TURN server used to gather this candidate.

4.8.3 RTCPeerConnectionIceErrorEvent

The icecandidateerror event of the RTCPeerConnection uses the RTCPeerConnectionIceErrorEvent interface.

WebIDL[Exposed=Window]
interface RTCPeerConnectionIceErrorEvent : Event {
  constructor(DOMString type, RTCPeerConnectionIceErrorEventInit eventInitDict);
  readonly attribute DOMString? address;
  readonly attribute unsigned short? port;
  readonly attribute DOMString url;
  readonly attribute unsigned short errorCode;
  readonly attribute USVString errorText;
};

Constructors

RTCPeerConnectionIceErrorEvent.constructor()

Attributes

address of type DOMString, readonly, nullable

The address attribute is the local IP address used to communicate with the STUN or TURN server.

On a multihomed system, multiple interfaces may be used to contact the server, and this attribute allows the application to figure out on which one the failure occurred.

If the local IP address value is not already exposed as part of a local candidate, the address attribute will be set to null.

port of type unsigned short, readonly, nullable

The port attribute is the port used to communicate with the STUN or TURN server.

If the address attribute is null, the port attribute is also set to null.

url of type DOMString, readonly

The url attribute is the STUN or TURN URL that identifies the STUN or TURN server for which the failure occurred.

errorCode of type unsigned short, readonly

The errorCode attribute is the numeric STUN error code returned by the STUN or TURN server [STUN-PARAMETERS].

If no host candidate can reach the server, errorCode will be set to the value 701 which is outside the STUN error code range. This error is only fired once per server URL while in the RTCIceGatheringState of “gathering“.

errorText of type USVString, readonly

The errorText attribute is the STUN reason text returned by the STUN or TURN server [STUN-PARAMETERS].

If the server could not be reached, errorText will be set to an implementation-specific value providing details about the error.

WebIDL            dictionary RTCPeerConnectionIceErrorEventInit : EventInit {
  DOMString? address;
  unsigned short? port;
  DOMString url;
  required unsigned short errorCode;
  USVString errorText;
};

Dictionary RTCPeerConnectionIceErrorEventInit Members

address of type DOMString, nullable

The local address used to communicate with the STUN or TURN server, or null.

port of type unsigned short, nullable

The local port used to communicate with the STUN or TURN server, or null.

url of type DOMString

The STUN or TURN URL that identifies the STUN or TURN server for which the failure occurred.

errorCode of type unsigned short, required

The numeric STUN error code returned by the STUN or TURN server.

errorText of type USVString

The STUN reason text returned by the STUN or TURN server.