RTCIceCandidate: RTCIceCandidate() constructor
==============================================

 The
 **`RTCIceCandidate()`**
 constructor creates and returns a new `RTCIceCandidate` object, which can
 be configured to represent a single ICE candidate.

Syntax
------


```js
new RTCIceCandidate()
new RTCIceCandidate(candidateInfo)
```

### Parameters

`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`.


### Return value

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`.

**Note:** Parsing of the `candidate` string is performed using the candidate-attribute grammar from the WebRTC Specification.

### Exceptions

`TypeError`

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

Usage notes
-----------

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

Specifications
--------------

| Specification |
| --- |
| WebRTC: Real-Time Communication in Browsers # dom-rtcicecandidate-constructor |

Browser compatibility
---------------------

BCD tables only load in the browser with JavaScript enabled. Enable JavaScript to view data.

See also
--------

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