RTCPeerConnection: createOffer() 方法

語法

createOffer()
createOffer(options)

createOffer(successCallback, failureCallback) // deprecated
createOffer(successCallback, failureCallback, options) // deprecated

引數

options 可選

一個提供以下選項的物件，用於請求 offer

iceRestart 可選

要重啟活動連線上的 ICE，請將其設定為 true。這將導致返回的 offer 具有與當前已存在的不同的憑證。如果您隨後應用返回的 offer，ICE 將會重啟。指定 false 則保留相同的憑證，因此不會重啟 ICE。預設值為 false。與其使用此選項，不如考慮呼叫 RTCPeerConnection.restartIce()，它將在下次呼叫 createOffer() 時自動設定此標誌。

offerToReceiveAudio 可選 已棄用

提供對音訊方向的額外控制。例如，無論是否傳送音訊，都可以使用它來確保可以接收音訊。

offerToReceiveVideo 可選 已棄用

提供對影片方向的額外控制。例如，無論是否傳送影片，都可以使用它來確保可以接收影片。

已棄用的引數

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

successCallback 已棄用

一個 回撥函式，它將接收一個單獨的 RTCSessionDescription 物件，該物件描述新建立的 offer。

errorCallback 已棄用

一個 回撥函式，它將接收一個單獨的 DOMException 物件，解釋請求建立 offer 失敗的原因。

options 可選

一個可選物件，提供為 offer 請求的選項。

返回值

一個 Promise，它在解析時會返回一個包含與 RTCSessionDescription 物件相同屬性的物件。

type

一個值為 "offer" 的字串。

SDP

一個包含 SDP 的字串，描述生成的 offer，將傳送給遠端對等端。

異常

這些異常透過拒絕返回的 promise 來返回。您的拒絕處理程式應檢查接收到的異常以確定發生了哪個錯誤。

InvalidStateError DOMException

當 RTCPeerConnection 關閉時返回。

NotReadableError DOMException

如果未提供用於保護連線的證書或證書集，並且 createOffer() 無法建立新的證書，則返回此錯誤。由於所有 WebRTC 連線都需要安全，因此會導致錯誤。

OperationError DOMException

如果確定生成 offer 所需的系統狀態檢查資源可用性時因某種原因失敗，則返回此錯誤。

示例

這裡我們看到了 negotiationneeded 事件的處理程式，該事件建立 offer 並透過信令通道將其傳送到遠端系統。

myPeerConnection
  .createOffer()
  .then((offer) => myPeerConnection.setLocalDescription(offer))
  .then(() => {
    sendToServer({
      name: myUsername,
      target: targetUsername,
      type: "video-offer",
      sdp: myPeerConnection.localDescription,
    });
  })
  .catch((reason) => {
    // An error occurred, so handle the failure to connect
  });

在此程式碼中，建立 offer，一旦成功，本地的 RTCPeerConnection 端將透過將 offer（使用與 RTCSessionDescription 相同的形狀的物件表示）傳遞給 setLocalDescription() 來進行匹配配置。完成此操作後，offer 將透過信令通道傳送到遠端系統；在本例中，是透過使用一個名為 sendToServer() 的自定義函式。信令伺服器的實現獨立於 WebRTC 規範，因此只要呼叫者和潛在接收者使用相同的信令伺服器，傳送 offer 的方式並不重要。

使用 Promise.catch() 來捕獲和處理錯誤。

請參閱 信令與視訊通話 以獲取派生此程式碼片段的完整示例；這將幫助您理解這裡的信令程式碼是如何工作的。

規範

瀏覽器相容性