在此页

• 句法
• 用法注意事项
• Deprecated syntax
• 范例
• 规范
• 浏览器兼容性
• 另请参阅
• 相关话题

RTCPeerConnection 方法 setRemoteDescription() sets the specified session description as the remote peer's current offer or answer. The description specifies the properties of the remote end of the connection, including the media format. The method takes a single parameter—the session description—and it returns a Promise which is fulfilled once the description has been changed, asynchronously.

This is typically called after receiving an offer or answer from another peer over the signaling server. Keep in mind that if setRemoteDescription() is called while a connection is already in place, it means renegotiation is underway (possibly to adapt to changing network conditions).

Because descriptions will be exchanged until the two peers agree on a configuration, the description submitted by calling setRemoteDescription() does not immediately take effect. Instead, the current connection configuration remains in place until negotiation is complete. Only then does the agreed-upon configuration take effect.

句法

aPromise = rtcPeerConnection.setRemoteDescription(sessionDescription);
					

参数

sessionDescription

RTCSessionDescriptionInit or RTCSessionDescription which specifies the remote peer's current offer or answer. This value is an offer or answer received from the remote peer through your implementation of

sessionDescription parameter is technically of type RTCSessionDescriptionInit , but because RTCSessionDescription serializes to be indistinguishable from RTCSessionDescriptionInit , you can also pass in an RTCSessionDescription . This lets you simplify code such as the following:

myPeerConnection.setRemoteDescription(new RTCSessionDescription(description))
.then(function () {
  return createMyStream();
})
					

to simply be:

myPeerConnection.setRemoteDescription(description)
.then(function () {
  return createMyStream();
})
					

使用 async / await syntax, you can further simplify this to:

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

Since it's unnecessary, the RTCSessionDescription() constructor is deprecated.

返回值

A Promise which is fulfilled once the value of the connection's remoteDescription is successfully changed or rejected if the change cannot be applied (for example, if the specified description is incompatible with one or both of the peers on the connection). The promise fulfillment handler receives no input parameters.

注意： The process of changing descriptions actually involves intermediary steps handled by the WebRTC layer to ensure that an active connection can be changed without losing the connection if the change does not succeed. See Pending and current descriptions in WebRTC connectivity for more details on this process.

异常

The following exceptions are reported to the rejection handler for the promise returned by setRemoteDescription() :

InvalidAccessError

The content of the description is invalid.

InvalidStateError

RTCPeerConnection is closed, or it's in a state which isn't compatible with the specified description's type 。例如，若 type is rollback and the signaling state is one of stable , have-local-pranswer ，或 have-remote-pranswer , this exception is thrown, because you can't roll back a connection that's either fully established or is in the final stage of becoming connected.

OperationError

Any errors that occur which don't match the others specifeid here are reported as OperationError . This includes identity validation errors.

RTCError

An RTCError 采用 errorDetail 设为 sdp-syntax-error is reported if the SDP 指定通过 RTCSessionDescription.sdp . The error object's sdpLineNumber property indicates the line number within the SDP on which the syntax error was detected.

TypeError

指定 RTCSessionDescriptionInit or RTCSessionDescription object is missing the type property, or no description parameter was provided at all.

用法注意事项

当调用 setRemoteDescription() , the ICE agent checks to make sure the RTCPeerConnection is in either the stable or have-remote-offer signalingState . These states indicate that either an existing connection is being renegotiated or that an offer previously specified by an earlier call to setRemoteDescription() is to be replaced with the new offer. In either of those two cases, we're at the beginning of the negotiation process, and the offer is set as the remote description.

On the other hand, if we're in the middle of an ongoing negotiation and an offer is passed into setRemoteDescription() , the ICE agent automatically begins an ICE rollback in order to return the connection to a stable signaling state, then, once the rollback is completed, sets the remote description to the specified offer. This begins a new negotiation session, with the newly-established offer as the starting point.

Upon starting the new negotiation with the newly-established offer, the local peer is now the callee, even if it was previously the caller. This happens instead of throwing an exception, thereby reducing the number of potential errors which might occur, and simplifies the processing you need to do when you receive an offer, by eliminating the need to handle the offer/answer process differently depending on whether the local peer is the caller or callee.

注意： Earlier implementations of WebRTC would throw an exception if an offer was set outside a stable or have-remote-offer 状态。

Deprecated syntax

In older code and documentation, you may see a callback-based version of this function used. This has been deprecated and its use is strongly discouraged. You should update any existing code to use the Promise -based version of setRemoteDescription() instead. The parameters for the older form of setRemoteDescription() are described below, to aid in updating existing code.

pc.setRemoteDescription(sessionDescription, successCallback, errorCallback);
						

参数

successCallback

A JavaScript 函数 which accepts no input parameters to be be called once the description has been successfully set. At that time, the offer can be sent to a remote peer via the signaling server.

errorCallback

A function matching the signautre RTCPeerConnectionErrorCallback which gets called if the description can't be set. It is passed a single DOMException object explaining why the request failed.

This deprecated form of the method returns instantaneously without waiting for the actual setting to be done: in case of success, the successCallback will be called; in case of failure, the errorCallback 将被调用。

异常

When using the deprecated callback-based version of setRemoteDescription() , the following exceptions may occur:

InvalidStateError

The connection's signalingState is "closed" , indicating that the connection is not currently open, so negotiation cannot take place.

InvalidSessionDescriptionError

RTCSessionDescription 指定通过 sessionDescription parameter is invalid.

范例

Here we see a function which handles an offer received from the remote peer. This code is derived from the example and tutorial in the article Signaling and video calling ; take a look at that for more details and a more in-depth explanation of what's going on.

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

After creating our RTCPeerConnection and saving it as myPeerConnection , we pass the description included in the received offer message, msg , directly into setRemoteDescription() to tell the user agent's WebRTC layer what configuration the caller has proposed using. When our promise fulfillment handler is called, indicating that this has been done, we create a stream, add it to the connection, then create an SDP answer and call setLocalDescription() to set that as the configuration at our end of the call before forwarding that answer to the caller.

规范

规范	状态	注释
WebRTC 1.0: Real-time Communication Between Browsers The definition of 'RTCPeerConnection.setRemoteDescription()' in that specification.	候选推荐	最初的规范。

浏览器兼容性

The compatibility table on this page is generated from structured data. If you'd like to contribute to the data, please check out https://github.com/mdn/browser-compat-data and send us a pull request. 更新 GitHub 上的兼容性数据

	桌面						移动
	Chrome	Edge	Firefox	Internet Explorer	Opera	Safari	Android webview	Chrome for Android	Firefox for Android	Opera for Android	Safari on iOS	Samsung Internet
setRemoteDescription()	Chrome 51 51 Promise-based version. 24	Edge 15	Firefox 22	IE No	Opera 43 43 Promise-based version. 不支持 37 — 43	Safari 11	WebView Android 51 51 Promise-based version. Yes	Chrome Android 51 51 Promise-based version. Yes	Firefox Android 44	Opera Android 43 43 Promise-based version. 不支持 37 — 43	Safari iOS Yes	Samsung Internet Android 5.0 5.0 Promise-based version. Yes
Implicit rollback	Chrome 80	Edge 80	Firefox 70	IE No	Opera No	Safari No	WebView Android 80	Chrome Android 80	Firefox Android No	Opera Android No	Safari iOS No	Samsung Internet Android No
Description is optional	Chrome 80	Edge 80	Firefox 75	IE No	Opera No	Safari No	WebView Android 80	Chrome Android 80	Firefox Android No	Opera Android No	Safari iOS No	Samsung Internet Android No

图例

完整支持

完整支持

不支持

不支持

见实现注意事项。

另请参阅

• WebRTC
• RTCPeerConnection.remoteDescription , RTCPeerConnection.pendingRemoteDescription , RTCPeerConnection.currentRemoteDescription

元数据

• 最后修改： Mar 11, 2020

相关话题

1. WebRTC API
2. RTCPeerConnection
3. 构造函数

   1. RTCPeerConnection()
4. 特性

   1. canTrickleIceCandidates
   2. connectionState
   3. currentLocalDescription
   4. currentRemoteDescription
   5. getDefaultIceServers()
   6. iceConnectionState
   7. iceGatheringState
   8. localDescription
   9. onaddstream
   10. onconnectionstatechange
   11. ondatachannel
   12. onicecandidate
   13. oniceconnectionstatechange
   14. onicegatheringstatechange
   15. onidentityresult
   16. onidpassertionerror
   17. onidpvalidationerror
   18. onnegotiationneeded
   19. onpeeridentity
   20. onremovestream
   21. onsignalingstatechange
   22. ontrack
   23. peerIdentity
   24. pendingLocalDescription
   25. pendingRemoteDescription
   26. remoteDescription
   27. sctp
   28. signalingState
5. 方法

   1. addIceCandidate()
   2. addStream()
   3. addTrack()
   4. close()
   5. createAnswer()
   6. createDataChannel()
   7. createOffer()
   8. generateCertificate()
   9. getConfiguration()
   10. getIdentityAssertion()
   11. getReceivers()
   12. getSenders()
   13. getStats()
   14. getStreamById()
   15. getTransceivers()
   16. removeStream()
   17. removeTrack()
   18. restartIce()
   19. setConfiguration()
   20. setIdentityProvider()
   21. setLocalDescription()
   22. setRemoteDescription()
6. 事件

   1. addstream
   2. identityresult
   3. negotiationneeded
   4. removestream
   5. signalingstatechange
7. 继承：

   1. EventTarget
8. Related pages for WebRTC

   1. MediaDevices.getUserMedia()
   2. Navigator.mediaDevices
   3. RTCCertificate
   4. RTCDTMFSender
   5. RTCDTMFToneChangeEvent
   6. RTCDataChannel
   7. RTCDataChannelEvent
   8. RTCDtlsTransport
   9. RTCErrorEvent
   10. RTCIceCandidate
   11. RTCIceTransport
   12. RTCPeerConnectionIceErrorEvent
   13. RTCPeerConnectionIceEvent
   14. RTCRtpReceiver
   15. RTCRtpSender
   16. RTCRtpTransceiver
   17. RTCSctpTransport
   18. RTCSessionDescription
   19. RTCStatsEvent
   20. RTCStatsReport
   21. RTCTrackEvent