RTCPeerConnection: setRemoteDescription() 方法

語法

setRemoteDescription(sessionDescription)

// deprecated
setRemoteDescription(sessionDescription, successCallback, errorCallback)

引數

sessionDescription

一個物件，用於指定遠端對等方的當前 offer 或 answer。它應包含以下屬性：

type

一個字串，指示會話描述的型別。請參閱 RTCSessionDescription.type。

sdp 可選

一個包含描述會話的 SDP 的字串。如果未提供 sdp，則預設為空字串。如果 type 是 "rollback"，則 sdp 必須為 null 或空字串。請參閱 RTCSessionDescription.sdp。

您也可以傳遞一個實際的 RTCSessionDescription 例項，但沒有區別。因此，RTCSessionDescription 建構函式已棄用。

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

successCallback 已棄用

一個不接受任何輸入引數的 JavaScript Function，當描述成功設定後會被呼叫。屆時，可以透過信令伺服器將 offer 傳送給遠端對等方。

errorCallback 已棄用

一個匹配 RTCPeerConnectionErrorCallback 簽名的函式，如果無法設定描述，則會呼叫該函式。它會收到一個 DOMException 物件，解釋請求失敗的原因。

此方法的已棄用形式會立即返回，而無需等待實際設定完成：如果成功，將呼叫 successCallback；如果失敗，則呼叫 errorCallback。

返回值

一個 Promise，當連線的 remoteDescription 的值成功更改時，該 Promise 會被 fulfilled；如果更改無法應用（例如，指定的描述與連線上的一個或兩個對等方不相容），則會被 rejected。Promise fulfilled 處理程式不接收任何輸入引數。

異常

以下異常會報告給 setRemoteDescription() 返回的 Promise 的 rejection 處理程式：

InvalidAccessError DOMException

如果描述的內容無效，則返回此異常。

InvalidStateError DOMException

如果 RTCPeerConnection 已關閉，或者其狀態與指定的描述的 type 不相容，則返回此異常。例如，如果 type 為 rollback 且信令狀態為 stable、have-local-pranswer 或 have-remote-pranswer 之一，則會丟擲此異常，因為您無法回滾已完全建立或處於連線最終階段的連線。

OperationError DOMException

如果錯誤不符合此處指定的錯誤，則返回此異常。這包括身份驗證錯誤。

RTCError DOMException

當 RTCSessionDescription.sdp 指定的 SDP 無效時，將返回此異常，並將 errorDetail 設定為 sdp-syntax-error。錯誤物件的 sdpLineNumber 屬性指示了檢測到語法錯誤處的 SDP 行號。

TypeError

如果 sessionDescription 缺少 type 屬性，或者根本沒有提供描述引數，則返回此異常。

使用已棄用的基於回撥的 setRemoteDescription() 版本時，可能會發生以下異常：

InvalidStateError 已棄用

連線的 signalingState 為 "closed"，表示連線當前未開啟，因此無法進行協商。

InvalidSessionDescriptionError 已棄用

sessionDescription 引數無效。

用法說明

當您呼叫 setRemoteDescription() 時，ICE 代理會檢查以確保 RTCPeerConnection 處於 stable 或 have-remote-offer signalingState。這些狀態表明正在重新協商現有連線，或者將用新的 offer 替換先前透過呼叫 setRemoteDescription() 指定的 offer。在這兩種情況下，我們都處於協商過程的開始階段，並且 offer 被設定為遠端描述。

另一方面，如果我們處於正在進行的協商過程中，並且將 offer 傳遞給 setRemoteDescription()，ICE 代理會自動開始 ICE 回滾，以將連線恢復到穩定的信令狀態，然後，一旦回滾完成，就將遠端描述設定為指定的 offer。這會啟動一個新的協商會話，以新建立的 offer 作為起點。

在以新建立的 offer 開始新協商後，本地對等方現在成為被叫方，即使它之前是主叫方。這會發生，而不是丟擲異常，從而減少了可能發生的潛在錯誤數量，並透過消除根據本地對等方是主叫方還是被叫方來區分 offer/answer 過程的需要，簡化了您在接收 offer 時需要進行的處理。

示例

這裡我們看到一個處理從遠端對等方接收到的 offer 的函式。這段程式碼改編自文章 信令和視訊通話 中的示例和教程；有關更多詳細資訊和更深入的解釋，請參閱該文章。

function handleOffer(msg) {
  createMyPeerConnection();

  myPeerConnection
    .setRemoteDescription(msg.description)
    .then(() => navigator.mediaDevices.getUserMedia(mediaConstraints))
    .then((stream) => {
      document.getElementById("local_video").srcObject = stream;
      return myPeerConnection.addStream(stream);
    })
    .then(() => myPeerConnection.createAnswer())
    .then((answer) => myPeerConnection.setLocalDescription(answer))
    .then(() => {
      // Send the answer to the remote peer using the signaling server
    })
    .catch(handleGetUserMediaError);
}

在建立我們的 RTCPeerConnection 並將其儲存為 myPeerConnection 後，我們將接收到的 offer 訊息 msg 中包含的描述直接傳遞給 setRemoteDescription()，以告知使用者代理的 WebRTC 層呼叫者使用了什麼配置。當我們的 Promise fulfilled 處理程式被呼叫，表示這已完成，我們就建立一個流，將其新增到連線，然後建立一個 SDP answer 並呼叫 setLocalDescription() 以在通話的我們這一端將其設定為配置，然後再將該 answer 轉發給呼叫者。

規範

瀏覽器相容性

另見

• WebRTC
• RTCPeerConnection.remoteDescription, RTCPeerConnection.pendingRemoteDescription, RTCPeerConnection.currentRemoteDescription
• RTCSessionDescription