RTCPeerConnection：createOffer() 方法

语法

createOffer()
createOffer(options)

createOffer(successCallback, failureCallback) // 已弃用
createOffer(successCallback, failureCallback, options) // 已弃用

参数

options 可选

为提议提供以下请求选项的对象：

iceRestart 可选

要在活动连接上重新启动 ICE，请将其设置为 true。这将导致返回的提议与已经存在提议的凭据不同。如果你应用返回的提议，则 ICE 将重新启动。指定 false 以保留相同的凭据，因此不重新启动 ICE。默认值为 false。请考虑调用 RTCPeerConnection.restartIce()（会在下一次调用 createOffer() 时自动设置标志）来代替这个选项的使用。

offerToReceiveAudio 可选

提供对音频方向的额外控制。例如，它可以用于确保无论音频是否已发送，都可以接收音频。

offerToReceiveVideo 可选

提供对视频方向的额外控制。例如，它可以用于确保无论视频是否已发送，都可以接收视频。

已弃用的参数

在较早的代码和文档中，你可能会看到此函数的基于回调的版本。其已被弃用并强烈建议不要使用它。你应该更新任何现有代码，以改用基于 Promise 的 createOffer() 版本。下面介绍了这种老形式的 createOffer() 的参数，以帮助更新现有代码。

successCallback

一个回调函数，其将接收一个描述了新创建提议的 RTCSessionDescription 对象。

errorCallback

一个回调函数，其将接收一个解释为什么请求创建提议失败的 DOMException 对象。

options 可选

提供提议所要求的选项的可选对象。

返回值

一个 Promise，会兑现为一个包含与 RTCSessionDescription 对象具有相同属性的对象：

type

值为 "offer" 的字符串。

sdp

包含描述所生成提议的 SDP 的字符串，将传递给远程对等方。

异常

通过拒绝返回的 promise 来返回这些异常。你的拒绝处理器应该检查接收到的异常，以确定发生了哪个异常。

InvalidStateError

RTCPeerConnection 被关闭则返回此异常。

NotReadableError

没有提供用于保护连接的（一组）证书，并且 createOffer() 无法创建新证书则返回此错误。由于所有 WebRTC 连接都需要安全保护，因此这会导致错误。

OperationError

由于某些原因，检查系统状态确定资源可用性以生成提议失败则返回此异常。

示例

在这里我们看到一个 negotiationneeded 事件的处理器，它创建了提议，并通过信令通道将其发送到远程系统。

myPeerConnection
  .createOffer()
  .then((offer) => myPeerConnection.setLocalDescription(offer))
  .then(() => {
    sendToServer({
      name: myUsername,
      target: targetUsername,
      type: "video-offer",
      sdp: myPeerConnection.localDescription,
    });
  })
  .catch((reason) => {
    // 发生错误，处理连接失败的情况
  });

在此代码中，创建了提议，一旦成功，通过将提议（以与 RTCSessionDescription 相同结构的对象表示）传递给 setLocalDescription()，配置 RTCPeerConnection 的本地端以进行匹配。完成后，通过信令通道将提议发送到远程系统。在本例中，使用名为 sendToServer() 的自定义函数。信令服务器的实现独立于 WebRTC 规范，因此只要主叫方和潜在接收方都使用相同的提议，如何发送提议都无关紧要。

用 Promise.catch() 来捕获和处理错误。

请参阅信令与视频通话，以获取此代码片段来源的完整示例；这将帮助你了解此处的信令代码如何工作。

规范

浏览器兼容性