RTCPeerConnection: addIceCandidate() 方法

語法

addIceCandidate(candidate)

addIceCandidate(candidate, successCallback) // deprecated
addIceCandidate(candidate, successCallback, failureCallback) // deprecated

引數

candidate 可選

一個 RTCIceCandidate 物件，或一個具有以下屬性的物件

candidate 可選

一個描述候選屬性的字串，直接取自 SDP 屬性 "candidate"。候選字串指定候選的網路連線資訊。如果 candidate 為空字串 ("")，則表示已到達候選列表的末尾；此候選稱為“結束候選”標記。

候選字串的語法在 RFC 5245, section 15.1 中進行了描述。對於如下 a-line (屬性行)：

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

相應的 candidate 字串的值將是：

"candidate:4234997325 1 udp 2043278322 192.0.2.172 44323 typ host"`

在所有條件都相同的情況下，使用者代理總是優先選擇具有最高 priority 的候選。在上面的示例中，優先順序是 2043278322。屬性之間都用單個空格字元分隔，並且順序是固定的。此示例候選的完整屬性列表是：

• foundation = 4234997325
• component = "rtp" (數字 1 被編碼為該字串；2 變為 "rtcp")
• protocol = "udp"
• 優先順序 = 2043278322
• ip = "192.0.2.172"
• port = 44323
• type = "host"

更多資訊可以在 RTCIceCandidate.candidate 中找到。

注意：為了向後相容 WebRTC 規範的舊版本，建構函式也接受此字串作為引數。

sdpMid 可選

一個包含與候選關聯的媒體流的識別符號標籤的字串，如果沒有關聯的媒體流則為 null。預設值為 null。

更多資訊可以在 RTCIceCandidate.sdpMid 中找到。

sdpMLineIndex 可選

一個數字屬性，包含與候選關聯的 m-line 在媒體描述的 SDP 中的零基索引，如果沒有此類關聯則為 null。預設值為 null。

更多資訊可以在 RTCIceCandidate.sdpMLineIndex 中找到。

usernameFragment 可選

一個包含使用者名稱片段（通常簡稱為“ufrag”或“ice-ufrag”）的字串。此片段與 ICE 密碼（“ice-pwd”）一起，唯一標識單個正在進行的 ICE 互動（包括與 STUN 伺服器的任何通訊）。

該字串由 WebRTC 在會話開始時生成。其長度最多可達 256 個字元，並且至少 24 位必須包含隨機資料。它沒有預設值，除非顯式設定，否則不存在。

更多資訊可以在 RTCIceCandidate.usernameFragment 中找到。

如果 sdpMid 和 sdpMLineIndex 都為 null，則該方法將丟擲 TypeError 異常。

物件的內容應由透過信令通道接收到的訊息構建，該訊息描述了一個已準備好傳遞給本地 ICE 代理的新收到的 ICE 候選。

如果未指定 candidate 物件，或其值為 null，則使用 end-of-candidates a-line 向遠端對等方傳送結束候選訊號，格式如下：

a=end-of-candidates

已棄用的引數

在舊程式碼和文件中，您可能會看到該函式的基於回撥的版本。該版本已被棄用，並且**強烈**不建議使用。您應該更新任何現有程式碼以使用 addIceCandidate() 的基於 Promise 的版本。為了幫助更新現有程式碼，下面描述了舊版 addIceCandidate() 的引數。

successCallback 已棄用

當 ICE 候選成功新增時呼叫的函式。此函式不接收任何輸入引數，也不返回值。

failureCallback 已棄用

嘗試新增 ICE 候選失敗時呼叫的函式。接收一個 DOMException 物件作為輸入，描述失敗原因。

返回值

當 ICE 代理成功將候選新增到遠端對等方的描述中時，此方法返回的 Promise 會被 fulfilled。Promise 不接收任何輸入引數。

異常

當嘗試新增 ICE 候選時發生錯誤，此方法返回的 Promise 會被 rejected，將以下錯誤之一作為指定 DOMException 物件中 name 屬性的值傳遞給 rejection handler。

TypeError

如果指定的候選的 sdpMid 和 sdpMLineIndex 都為 null，則返回此錯誤。

InvalidStateError DOMException

如果 RTCPeerConnection 當前沒有已建立的遠端對等方（remoteDescription 為 null），則返回此錯誤。

OperationError DOMException

在以下任一情況發生時返回：

• 為 sdpMid 指定的值非 null，且與 remoteDescription 中包含的任何媒體描述的媒體描述 ID 不匹配。
• 指定的 sdpMLineIndex 值大於或等於遠端描述中包含的媒體描述數量。
• 指定的 ufrag 與正在考慮的任何遠端描述中的 ufrag 欄位不匹配。
• candidate 字串中的一個或多個值無效或無法解析。
• 嘗試新增候選因任何原因失敗。

示例

此程式碼片段顯示瞭如何透過任意信令通道信令 ICE 候選。

// This example assumes that the other peer is using a signaling channel as follows:
//
// pc.onicecandidate = (event) => {
//   if (event.candidate) {
//     signalingChannel.send(JSON.stringify({ice: event.candidate})); // "ice" is arbitrary
//   } else {
//     // All ICE candidates have been sent
//   }
// }

signalingChannel.onmessage = (receivedString) => {
  const message = JSON.parse(receivedString);
  if (message.ice) {
    // A typical value of ice here might look something like this:
    //
    // {candidate: "candidate:0 1 UDP 2122154243 192.0.2.43 53421 typ host", sdpMid: "0", …}
    //
    // Pass the whole thing to addIceCandidate:

    pc.addIceCandidate(message.ice).catch((e) => {
      console.log(`Failure during addIceCandidate(): ${e.name}`);
    });
  } else {
    // handle other things you might be signaling, like sdp
  }
};

遠端對等方透過此方式信令的最後一個候選將是一個特殊的候選，表示結束候選。出於興趣，可以使用以下方法手動指示結束候選：

pc.addIceCandidate({ candidate: "" });

然而，在大多數情況下，您不需要顯式查詢它，因為驅動 RTCPeerConnection 的事件會為您處理它，傳送相應的事件。

規範

瀏覽器相容性

另見

• WebRTC API
• 信令與視訊通話
• WebRTC 協議簡介
• WebRTC 連線
• WebRTC 會話的生命週期