RTCIceCandidate: RTCIceCandidate() constructor

candidateInfo Optional

An optional object that can be provided to configure the candidate. The object has the following properties:

candidate Optional

A string describing the properties of the candidate, taken directly from the SDP attribute "candidate". The candidate string specifies the network connectivity information for the candidate. If the candidate is an empty string (""), the end of the candidate list has been reached; this candidate is known as the "end-of-candidates" marker.

The syntax of the candidate string is described in RFC 5245, section 15.1. For an a-line (attribute line) that looks like this:

a=candidate:4234997325 1 udp 2043278322 192.0.2.172 44323 typ host

the corresponding candidate string's value will be "candidate:4234997325 1 udp 2043278322 192.0.2.172 44323 typ host".

The user agent always prefers candidates with the highest priority, all else being equal. In the example above, the priority is 2043278322. The attributes are all separated by a single space character, and are in a specific order. The complete list of attributes for this example candidate is:

• foundation = 4234997325
• component = "rtp" (the number 1 is encoded to this string; 2 becomes "rtcp")
• protocol = "udp"
• priority = 2043278322
• ip = "192.0.2.172"
• port = 44323
• type = "host"

Additional information can be found in RTCIceCandidate.candidate.

Note: For backward compatibility with older versions of the WebRTC specification, the constructor also accepts this string directly as an argument.

sdpMid Optional

A string containing the identification tag of the media stream with which the candidate is associated, or null if there is no associated media stream. The default is null.

Additional information can be found in RTCIceCandidate.sdpMid.

sdpMLineIndex Optional

A number property containing the zero-based index of the m-line with which the candidate is associated, within the SDP of the media description, or null if no such associated exists. The default is null.

Additional information can be found in RTCIceCandidate.sdpMLineIndex.

usernameFragment Optional

A string containing the username fragment (usually referred to in shorthand as "ufrag" or "ice-ufrag"). This fragment, along with the ICE password ("ice-pwd"), uniquely identifies a single ongoing ICE interaction (including for any communication with the STUN server).

The string is generated by WebRTC at the beginning of the session. It may be up to 256 characters long, and at least 24 bits must contain random data. It has no default value and is not present unless set explicitly.

Additional information can be found in RTCIceCandidate.usernameFragment.

A newly-created RTCIceCandidate object.

If candidateInfo is provided, the new RTCIceCandidate is initialized as follows:

• Each member of the RTCIceCandidate object is initialized to the value of the property by the same name from candidateInfo. This includes the candidate, sdpMid, sdpMLineIndex, and usernameFragment properties.
• The candidate string (which is SDP text) is parsed; each property found is stored in the corresponding field in the RTCIceCandidate. If any of the fields is invalid, parsing of the string silently aborts without throwing an exception. The default value of candidate is the empty string, which indicates that the candidate is an "end-of-candidates" message.
• The following fields are initialized to null if they are not included in the RTCIceCandidate.candidate property: foundation, component, priority, address, protocol, port, type, tcpType, relatedAddress, and relatedPort.

TypeError

Thrown if the specified candidateInfo has values of null in both the sdpMid and sdpMLineIndex properties.

This constructor does not do complete validation of the specified candidateInfo object or string.

• Introduction to WebRTC protocols
• WebRTC connectivity
• Lifetime of a WebRTC session
• Signaling and video calling