When a web site or app using RTCPeerConnection
receives a new ICE candidate from the remote peer over its signaling channel, it delivers the newly-received candidate to the browser's ICE agent by calling RTCPeerConnection.addIceCandidate()
. This adds this new remote candidate to the RTCPeerConnection
's remote description, which describes the state of the remote end of the connection.
If the candidate
parameter is missing or a value of null
is given when calling addIceCandidate()
, the added ICE candidate is an "end-of-candidates" indicator. The same is the case if the value of the specified object's candidate
is either missing or an empty string (""
), it signals that all remote candidates have been delivered.
The end-of-candidates notification is transmitted to the remote peer using a candidate with an a-line value of end-of-candidates
.
During negotiation, your app will likely receive many candidates which you'll deliver to the ICE agent in this way, allowing it to build up a list of potential connection methods. This is covered in more detail in the articles WebRTC connectivity and Signaling and video calling.
addIceCandidate(candidate)
addIceCandidate(candidate, successCallback)
addIceCandidate(candidate, successCallback, failureCallback)
In older code and documentation, you may see a callback-based version of this function. This has been deprecated and its use is strongly discouraged. You should update any existing code to use the Promise
-based version of addIceCandidate()
instead. The parameters for this form of addIceCandidate()
are described below, to aid in updating existing code.
-
successCallback
Deprecated
-
A function to be called when the ICE candidate has been successfully added. This function receives no input parameters and doesn't return a value.
-
failureCallback
Deprecated
-
A function to be called if attempting to add the ICE candidate fails. Receives as input a DOMException
object describing why failure occurred.
A Promise
that is fulfilled when the candidate has been successfully added to the remote peer's description by the ICE agent. The promise does not receive any input parameters.
When an error occurs while attempting to add the ICE candidate, the Promise
returned by this method is rejected, returning one of the errors below as the name
attribute in the specified DOMException
object passed to the rejection handler.
-
TypeError
DOMException
-
Returned if the specified candidate's sdpMid
and sdpMLineIndex
are both null
.
-
InvalidStateError
DOMException
-
Returned if the RTCPeerConnection
currently has no remote peer established (remoteDescription
is null
).
-
OperationError
DOMException
-
Returned in one of the following situations:
- The value specified for
sdpMid
is non-null
and doesn't match the media description ID of any media description included within the remoteDescription
.
- The specified value of
sdpMLineIndex
is greater than or equal to the number of media descriptions included in the remote description.
- The specified
ufrag
doesn't match the ufrag
field in any of the remote descriptions being considered.
- One or more of the values in the
candidate
string are invalid or could not be parsed.
- Attempting to add the candidate fails for any reason.
This code snippet shows how to signal ICE candidates across an arbitrary signaling channel.
signalingChannel.onmessage = receivedString => {
const message = JSON.parse(receivedString);
if (message.ice) {
pc.addIceCandidate(message.ice).catch(e => {
console.log("Failure during addIceCandidate(): " + e.name);
});
} else {
}
}
The last candidate to be signaled this way by the remote peer will be a special candidate denoting end-of-candidates. Out of interest, end-of-candidates may be manually indicated as follows:
pc.addIceCandidate({candidate:''});
However, in most cases you won't need to look for this explicitly, since the events driving the RTCPeerConnection
will deal with it for you, sending the appropriate events.