RTCPeerConnection: setLocalDescription() 方法

setLocalDescription() 是 RTCPeerConnection 接口的方法，用于更改与连接关联的本地描述。此描述指定连接本地端的属性，包括媒体格式。该方法接受一个参数——会话描述，并返回一个 Promise，该承诺在异步更改描述后完成。

如果在已建立连接的情况下调用 setLocalDescription()，则意味着正在进行重新协商（可能是为了适应不断变化的网络条件）。由于描述将交换，直到两个对等体同意配置，因此通过调用 setLocalDescription() 提交的描述不会立即生效。相反，当前连接配置会保持不变，直到协商完成。只有在协商完成后，商定的配置才会生效。

语法

setLocalDescription()
setLocalDescription(sessionDescription)

setLocalDescription(sessionDescription, successCallback, errorCallback) // deprecated

参数

sessionDescription 可选: 一个 RTCSessionDescriptionInit 或 RTCSessionDescription，它指定要应用于连接本地端的配置。如果省略描述，WebRTC 运行时会尝试自动执行正确操作。

返回值

一个 Promise，一旦 RTCPeerConnection.localDescription 的值成功更改，则该承诺将完成，如果更改无法应用（例如，如果指定的描述与连接上的一个或两个对等体不兼容），则该承诺将被拒绝。承诺的实现处理程序不接收任何输入参数。

注意： 更改描述的过程实际上涉及 WebRTC 层处理的中间步骤，以确保可以在不丢失连接的情况下更改活动连接，如果更改不成功。有关此过程的更多详细信息，请参阅 WebRTC 连接页面上的待处理和当前描述。

隐式描述

如果您没有显式提供会话描述，WebRTC 运行时将尝试正确地处理它。如果信令状态是 stable、have-local-offer 或 have-remote-pranswer 之一，WebRTC 运行时会自动创建一个新的提议，并将其设置为新的本地描述。否则，setLocalDescription() 会创建一个答案，该答案将成为新的本地描述。

描述参数的类型

描述的类型为 RTCSessionDescriptionInit，它是 RTCSessionDescription 浏览器对象的序列化版本。它们是可互换的

myPeerConnection
  .createOffer()
  .then((offer) => myPeerConnection.setLocalDescription(offer));

这等效于

myPeerConnection
  .createOffer()
  .then((offer) =>
    myPeerConnection.setLocalDescription(new RTCSessionDescription(offer)),
  );

因此，RTCSessionDescription() 构造函数已弃用。

已弃用的参数

在旧代码和文档中，您可能会看到此函数的基于回调的版本。这已被弃用，强烈建议不要使用它，因为它将在将来被删除。您应该更新任何现有代码以使用基于 Promise 的 setLocalDescription() 版本。旧版 setLocalDescription() 的参数描述如下，以帮助更新现有代码。

successCallback 已弃用: 一个 JavaScript Function，该函数不接受任何输入参数，在成功设置描述后将被调用。在那时，可以将提议通过信令服务器发送到远程对等体。
errorCallback 已弃用: 一个与签名 RTCPeerConnectionErrorCallback 相匹配的函数，如果无法设置描述，则会调用该函数。它传递一个 DOMException 对象，解释请求失败的原因。

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

已弃用的异常

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

InvalidStateError DOMException 已弃用: 如果连接的 signalingState 为 "closed"，则抛出此异常，表示连接当前未打开，因此无法进行协商。
InvalidSessionDescriptionError DOMException 已弃用: 如果 sessionDescription 参数指定的 RTCSessionDescription 无效，则抛出此异常。

示例

隐式描述

无参数形式的 setLocalDescription() 的优点之一是它可以让您大大简化协商代码。这基本上是您 negotiationneeded 事件处理程序需要的样子。只需添加信令服务器代码，这里用 signalRemotePeer() 的调用来表示。

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

除了错误处理，就这些了！

提供您自己的提议或答案

以下示例显示了对 negotiationneeded 事件的处理程序的实现，该处理程序显式地创建了一个提议，而不是让 setLocalDescription() 来创建它。

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

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

规范

规范
WebRTC：浏览器中的实时通信 # dom-peerconnection-setlocaldescription

浏览器兼容性

BCD 表格仅在浏览器中加载

另请参阅

WebRTC API