RTCPeerConnection：setLocalDescription() 方法

语法

setLocalDescription()
setLocalDescription(sessionDescription)

setLocalDescription(sessionDescription, successCallback, errorCallback) // deprecated

参数

sessionDescription 可选

一个对象，用于指定要应用于连接本地端的配置。它应包含以下属性：

type 可选

一个字符串，指示会话描述的类型。如果您不明确提供会话描述，WebRTC 运行时将尝试正确处理。如果信令状态是 stable、have-local-offer 或 have-remote-pranswer 之一，WebRTC 运行时会自动创建一个新的 offer 并将其设置为新的本地描述。否则，setLocalDescription() 会创建一个 answer，并将其作为新的本地描述。

sdp 可选

一个包含会话 SDP 的字符串。如果未提供 sdp，则默认为空字符串。如果 type 为 "rollback"，则 sdp 必须为 null 或空字符串。

如果省略了描述，WebRTC 运行时会尝试自动执行正确的操作。

您也可以传入一个实际的 RTCSessionDescription 实例，但没有区别。因此，RTCSessionDescription 构造函数已弃用。

在旧代码和文档中，您可能会看到此函数的基于回调的版本。此版本已弃用，并且**强烈**不建议使用，因为它将来会被移除。您应该更新任何现有代码以使用 setLocalDescription() 的基于 Promise 的版本。为了帮助更新现有代码，下面将介绍 setLocalDescription() 旧形式的参数。

successCallback 已弃用

一个 JavaScript Function，它不接受任何输入参数，将在成功设置描述后被调用。届时，可以通过信令服务器将 offer 发送到远程对等端。

errorCallback 已弃用

一个函数，其签名符合 RTCPeerConnectionErrorCallback，如果无法设置描述，则调用此函数。它会接收一个 DOMException 对象，解释请求失败的原因。

此方法的已弃用形式会立即返回，而不等待实际设置完成：如果成功，将调用 successCallback；如果失败，将调用 errorCallback。

返回值

一个 Promise，在 RTCPeerConnection.localDescription 的值成功更改后兑现，或者在更改无法应用时（例如，如果指定的描述与连接中的一个或两个对等端不兼容）拒绝。Promise 的兑现处理程序不接收任何输入参数。

已弃用的异常

在使用已弃用的基于回调的 setLocalDescription() 版本时，可能会发生以下异常：

InvalidStateError DOMException 已弃用

如果连接的 signalingState 为 "closed"，则抛出此异常，表示连接当前未打开，因此无法进行协商。

InvalidSessionDescriptionError DOMException 已弃用

如果 sessionDescription 参数无效，则抛出此异常。

示例

隐式描述

setLocalDescription() 无参数形式的一个优点是，它可以大大简化您的协商代码。在大多数情况下，您的 negotiationneeded 事件处理程序只需要如下所示。只需添加信令服务器代码，此处用 signalRemotePeer() 调用表示。

pc.addEventListener("negotiationneeded", async (event) => {
  await pc.setLocalDescription();
  signalRemotePeer({ description: pc.localDescription });
});

除错误处理外，就是这样了！

提供您自己的 offer 或 answer

下面的示例演示了一个 negotiationneeded 事件的处理程序的实现，该处理程序显式创建 offer，而不是让 setLocalDescription() 来完成。

async function handleNegotiationNeededEvent() {
  try {
    const offer = await pc.createOffer();
    pc.setLocalDescription(offer);
    signalRemotePeer({ description: pc.localDescription });
  } catch (err) {
    window.reportError(err);
  }
}

这首先通过调用 createOffer() 来创建 offer；成功后，我们调用 setLocalDescription()。然后，我们可以使用信令服务器将新创建的 offer 发送到另一方对等端，此处是通过调用一个名为 signalRemotePeer() 的函数来完成的。

规范

浏览器兼容性

另见

• WebRTC API
• RTCSessionDescription