RTCIceCandidateInit.candidate
The optional property candidate
in the RTCIceCandidateInit
dictionary specifies the value of the RTCIceCandidate
object's candidate
property.
Value
A DOMString
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.168.0.56 44323 typ host
the corresponding candidate
string's value will be
"candidate:4234997325 1 udp 2043278322 192.168.0.56 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:
Example
When a new ICE candidate is received by your signaling code from the remote peer, you need to construct the RTCIceCandidate
object that encapsulates it. This is done in the event handler for the icecandidate
event. If your client-side signaling layer builds and transmits a JSON string including the candidate to the remote peer, the remote peer might handle receiving that JSON message like this:
function gotICECandidateMessage(msg) {
var iceCandidate = new RTCIceCandidate({
candidate: msg.candidate;
});
pc.addIceCandidate(iceCandidate).catch({
/* handle error */
});
}
It's helpful to note that for backward compatibility with older versions of the WebRTC specification, the RTCIceCandidate()
constructor accepts the value of candidate
as its only input, in place of the RTCIceCandidateInit
dictionary. That usage would change the above sample to look like this:
function gotICECandidateMessage(msg) {
var iceCandidate = new RTCIceCandidate(msg.candidate);
pc.addIceCandidate(iceCandidate).catch({
/* handle error */
});
}
Specifications
Specification | Status | Comment |
---|---|---|
WebRTC 1.0: Real-time Communication Between Browsers The definition of 'RTCIceCandidateInit.candidate' in that specification. |
Candidate Recommendation | Initial specification. |
Browser compatibility
BCD tables only load in the browser