RTCPeerConnection：setRemoteDescription() 方法

sessionDescription

一个 RTCSessionDescriptionInit 或 RTCSessionDescription，它指定了远程对等方的当前提议或应答。此值为从远程对等方通过您对

sessionDescription 参数在技术上是 RTCSessionDescriptionInit 类型，但由于 RTCSessionDescription 序列化后与 RTCSessionDescriptionInit 无法区分，因此您也可以传入 RTCSessionDescription。这使您可以简化以下代码

myPeerConnection
  .setRemoteDescription(new RTCSessionDescription(description))
  .then(() => createMyStream());

为

myPeerConnection.setRemoteDescription(description).then(() => createMyStream());

使用 async/await 语法，您可以进一步简化此代码为

await myPeerConnection.setRemoteDescription(description);
createMyStream();

由于没有必要，因此 RTCSessionDescription() 构造函数已弃用。

一个 Promise，当连接的 remoteDescription 值成功更改时完成，如果更改无法应用（例如，如果指定的描述与连接上的一个或两个对等方不兼容），则会被拒绝。Promise 的完成处理程序不接收任何输入参数。

以下异常会报告给 setRemoteDescription() 返回的 Promise 的拒绝处理程序

InvalidAccessError DOMException

如果描述的内容无效，则返回。

InvalidStateError DOMException

如果 RTCPeerConnection 已关闭，或者其状态与指定的描述的 type 不兼容，则返回。例如，如果 type 为 rollback 并且信令状态为 stable、have-local-pranswer 或 have-remote-pranswer 中的一个，则会抛出此异常，因为您无法回滚已完全建立或处于连接最终阶段的连接。

OperationError DOMException

如果错误与此处指定的错误不匹配，则返回。这包括身份验证错误。

RTCError DOMException

如果 RTCSessionDescription.sdp 指定的 SDP 无效，则返回，并且 errorDetail 设置为 sdp-syntax-error。错误对象的 sdpLineNumber 属性指示在 SDP 中检测到语法错误的行号。

TypeError

如果指定的 RTCSessionDescriptionInit 或 RTCSessionDescription 对象缺少 type 属性，或者根本没有提供描述参数，则返回。

当您调用 setRemoteDescription() 时，ICE 代理会检查以确保 RTCPeerConnection 处于 stable 或 have-remote-offer signalingState 状态。这些状态表示要么正在重新协商现有连接，要么要将先前由对 setRemoteDescription() 的早期调用指定的提议替换为新提议。在这两种情况下，我们都处于协商过程的开始，并且提议被设置为远程描述。

另一方面，如果我们处于正在进行的协商过程中，并且将提议传递给 setRemoteDescription()，则 ICE 代理会自动开始 ICE 回滚以将连接返回到稳定的信令状态，然后，一旦回滚完成，将远程描述设置为指定的提议。这将开始一个新的协商会话，以新建立的提议作为起点。

在使用新建立的提议开始新的协商后，本地对等方现在成为被叫方，即使它之前是呼叫方。这是发生在抛出异常之前，从而减少了可能发生的潜在错误的数量，并简化了接收提议时需要执行的处理，从而消除了根据本地对等方是呼叫方还是被叫方以不同方式处理提议/应答过程的需要。

在较旧的代码和文档中，您可能会看到此函数的基于回调的版本。这已被弃用，并且强烈建议不要使用。您应该更新任何现有代码以改用 setRemoteDescription() 的 Promise 版本。为了帮助更新现有代码，下面描述了旧版 setRemoteDescription() 的参数。

pc.setRemoteDescription(sessionDescription, successCallback, errorCallback);

successCallback 已弃用

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

errorCallback 已弃用

一个与签名 RTCPeerConnectionErrorCallback 匹配的函数，如果无法设置描述，则会调用它。它传递一个单独的 DOMException 对象，解释请求失败的原因。

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

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

InvalidStateError 已弃用

连接的 signalingState 为 "closed"，表示连接当前未打开，因此无法进行协商。

InvalidSessionDescriptionError 已弃用

sessionDescription 参数指定的 RTCSessionDescription 无效。

这里我们看到一个处理从远程对等方接收到的 offer 的函数。此代码源自文章 信令与视频通话 中的示例和教程；请查看该文章以获取更多详细信息以及对正在发生情况的更深入解释。

function handleOffer(msg) {
  createMyPeerConnection();

  myPeerConnection
    .setRemoteDescription(msg.description)
    .then(() => navigator.mediaDevices.getUserMedia(mediaConstraints))
    .then((stream) => {
      document.getElementById("local_video").srcObject = stream;
      return myPeerConnection.addStream(stream);
    })
    .then(() => myPeerConnection.createAnswer())
    .then((answer) => myPeerConnection.setLocalDescription(answer))
    .then(() => {
      // Send the answer to the remote peer using the signaling server
    })
    .catch(handleGetUserMediaError);
}

在创建 RTCPeerConnection 并将其保存为 myPeerConnection 后，我们将接收到的 offer 消息 msg 中包含的描述直接传递到 setRemoteDescription()，以告知用户代理的 WebRTC 层呼叫方建议使用的配置。当我们的 promise 履行处理程序被调用，表示此操作已完成时，我们创建一个流，将其添加到连接中，然后创建一个 SDP 答案并调用 setLocalDescription() 将其设置为通话我们这一端的配置，然后将该答案转发给呼叫方。

• WebRTC
• RTCPeerConnection.remoteDescription、RTCPeerConnection.pendingRemoteDescription、RTCPeerConnection.currentRemoteDescription