4.8.1 RTCIceCandidate Interface

Constructor

constructor()

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

When invoked, run the following steps:

1. If both the sdpMid and members of candidateInitDict are null, throw a .
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 object.
2. Create internal slots for the following attributes of iceCandidate, initilized to null: foundation, , priority, , protocol, , type, , relatedAddress, and .
3. Create internal slots for the following attributes of iceCandidate, initilized to their namesakes in candidateInitDict: candidate, , sdpMLineIndex, .
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 grammar.
   2. If any field in the parse result represents an invalid value for the corresponding attribute in iceCandidate, abort these steps.
   3. 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 , sdpMid, , usernameFragment with the corresponding session description is done when passing the object to addIceCandidate().

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

Attributes

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

candidate of type DOMString, readonly

This carries the candidate-attribute as defined in section 15.1 of []. If this RTCIceCandidate represents an end-of-candidates indication or a peer reflexive remote 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 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 , readonly, nullable

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

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 .remote. By default, the user agent MUST leave the attribute as null for any exposed remote candidate. Once a RTCPeerConnection instance learns on an address by the web application using , the user agent can expose the address attribute value in any 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 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 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 [].

protocol of type RTCIceProtocol, readonly, nullable

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

port of type unsigned short, readonly, nullable

The port of the candidate.

type of type , readonly, nullable

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

If protocol is ““, tcpType represents the type of TCP candidate. Otherwise, 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 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 .

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 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 [].

Methods

toJSON()

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

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

WebIDLdictionary  {
  DOMString  = "";
  DOMString?  = null;
  unsigned short?  = null;
  DOMString?  = null;
};

Dictionary RTCIceCandidateInit Members

candidate of type DOMString, defaulting to ""

This carries the candidate-attribute as defined in section 15.1 of []. 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 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 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 grammar is used to parse the candidate member of candidateInitDict in the () constructor.

The primary grammar for candidate-attribute is defined in section 15.1 of []. 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 as defined in other RFCs.

4.8.1.2 RTCIceProtocol Enum

The RTCIceProtocol represents the protocol of the ICE candidate.

enum RTCIceProtocol {
  "",
  "tcp"
};

4.8.1.3 RTCIceTcpCandidateType Enum

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

Note

The user agent will typically only gather ICE TCP candidates.

4.8.1.4 RTCIceCandidateType Enum

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

WebIDLenum  {
  "host",
  "",
  "prflx",
  ""
};

4.8.2 RTCPeerConnectionIceEvent

The event of the RTCPeerConnection uses the interface.

When firing an RTCPeerConnectionIceEvent event that contains an object, it MUST include values for both sdpMid and . If the RTCIceCandidate is of type ““ or type “relay“, the 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:

• An has finished gathering a generation of candidates, and is providing an end-of-candidates indication as defined by Section 8.2 of []. This is indicated by candidate. being set to an empty string. The candidate object should be signaled to the remote peer and passed into 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 ‘s RTCIceGatheringState has transitioned to ““. 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 event with the “complete“ state.

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

Constructors

RTCPeerConnectionIceEvent.constructor()

Attributes

candidate of type , readonly, nullable

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

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.

Dictionary RTCPeerConnectionIceEventInit Members

candidate of type , nullable

See the candidate attribute of the 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 uses the RTCPeerConnectionIceErrorEvent interface.

[Exposed=]
interface RTCPeerConnectionIceErrorEvent :  {
  constructor( type, RTCPeerConnectionIceErrorEventInit eventInitDict);
  readonly attribute ? address;
  readonly attribute ? port;
  readonly attribute  url;
  readonly attribute  errorCode;
  readonly attribute  errorText;
};

Constructors

RTCPeerConnectionIceErrorEvent.constructor()

Attributes

address of type DOMString, readonly, nullable

The 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 attribute is the port used to communicate with the STUN or TURN server.

If the address attribute is null, the 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 attribute is the numeric STUN error code returned by the STUN or TURN server [STUN-PARAMETERS].

If no host candidate can reach the server, 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 ““.

errorText of type USVString, readonly

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

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

            dictionary RTCPeerConnectionIceErrorEventInit :  {
  DOMString? ;
  unsigned short? ;
  DOMString ;
  required unsigned short ;
  USVString ;
};

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.

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.