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() 来捕获和处理错误。

请参阅 信令与视频通话 以获取派生此代码片段的完整示例；这将帮助您理解这里的信令代码是如何工作的。

规范

浏览器兼容性