RTCPeerConnection.addIceCandidate() - Web API 接口参考 编辑

这是一个实验中的功能
此功能某些浏览器尚在开发中，请参考浏览器兼容性表格以得到在不同浏览器中适合使用的前缀。由于该功能对应的标准文档可能被重新修订，所以在未来版本的浏览器中该功能的语法和行为可能随之改变。

当本机当前页面的 RTCPeerConnection 接收到一个从远端页面通过信号通道发来的新的 ICE 候选地址信息，本机可以通过调用RTCPeerConnection.addIceCandidate() 来添加一个 ICE 代理。 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 value of the specified object's candidate is an empty string (""), it signals that all remote candidates have been delivered.

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.

Syntax

aPromise = pc.addIceCandidate(candidate);

addIceCandidate(candidate, successCallback, failureCallback);  

Parameters

candidate

An object conforming to the RTCIceCandidateInit dictionary; the contents of the object should be constructed from a message received over the signaling channel, describing a newly received ICE candidate that's ready to be delivered to the local ICE agent.

Deprecated parameters

在一些老旧的代码和文档中, 你可能会看到一个回调函数(callback)版本的函数。这种函数是过期的，强烈建议不要使用。你应该更新你的代码，使用 Promise-版本的 addIceCandidate() . 这个版本的参数格式附在下面, 方便你更新已有的代码.

successCallback

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

A function to be called if attempting to add the ICE candidate fails. Receives as input a DOMException object describing why failure occurred.

Return value

A Promise which 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.

Exceptions

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

The specified candidate doesn't have values for both sdpMid and sdpMLineIndex.

InvalidStateError

The RTCPeerConnection currently has no remote peer established (remoteDescription is null).

OperationError

A non-null value was specified for sdpMid, but the value doesn't match the mid of any media description in the remoteDescription, or sdpMLineIndex is greater than or equal to the number of media descriptions in remoteDescription. This error can also be thrown if a value is given for ufrag that doesn't match the value of ufrag in any of the remote description being selected.

OperationError also occurs if the attempt to add the candidate fails for any other reason.

Example

下段代码会展示如何使用一个SDP字符串(这个字符串包含了候选的描述)去构建一个候选对象。这个字符串来自于信道(signaling channel)。

// |receivedSDP| is an SDP string received over the signaling channel
// by our handler for "new ICE candidate" messages.

let candidate = new RTCIceCandidate(receivedSDP);

pc.addIceCandidate(candidate).then(_=>{
  // Do stuff when the candidate is successfully passed to the ICE agent
}).catch(e=>{
  console.log("Error: Failure during addIceCandidate()");
});

Specifications

Specification	Status	Comment
WebRTC 1.0: Real-time Communication Between Browsers RTCPeerConnection.addIceCandidate()	Candidate Recommendation	Initial specification.
WebRTC 1.0: Real-time Communication Between Browsers RTCPeerConnection.addIceCandidate()	Candidate Recommendation	Initial specification.

Browser compatibility

We're converting our compatibility data into a machine-readable JSON format. This compatibility table still uses the old format, because we haven't yet converted the data it contains. Find out how you can help!

• Desktop
• Mobile

Feature	Chrome	Edge	Firefox (Gecko)	Internet Explorer	Opera	Safari
Basic support	(Yes)[1]	(Yes)	22 (22) [2]	未实现	(Yes)	?
Promise-based version	50	?	37 (37)	?	?	?
RTCIceCandidateInit as input	?	?	53 (53)	?	?	?

Feature	Android Webview	Chrome for Android	Edge	Firefox Mobile (Gecko)	IE Mobile	Opera Mobile	Safari Mobile
Basic support	(Yes)[1]	(Yes)[1]	(Yes)	22.0 (22)	未实现	?	?
Promise-based version	50	50	?	37.0 (37)	?	?	?
RTCIceCandidateInit as input	?	?	?	53.0 (53)	?	?	?

[1] Though this method is not prefixed, the interface it belongs to was until Chrome 56.

[2] Though this method is not prefixed, the interface it belongs to was until Firefox 44.

See also

• WebRTC API
• Signaling and video calling
• WebRTC architecture overview
• WebRTC connectivity
• Lifetime of a WebRTC session