RTCPeerConnection.setLocalDescription()

在此页

句法
范例
规范
浏览器兼容性
另请参阅
相关话题

RTCPeerConnection 方法 setLocalDescription() changes the local description associated with the connection. This description specifies the properties of the local 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.

若 setLocalDescription() 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 setLocalDescription() 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.setLocalDescription(sessionDescription);
pc.setLocalDescription(sessionDescription, successCallback, errorCallback);

参数

sessionDescription 可选: RTCSessionDescriptionInit or RTCSessionDescription which specifies the configuration to be applied to the local end of the connection. If the description is omitted, the WebRTC runtime tries to automatically do the right thing.

Implicit description

If you don't explicity provide a session description, the WebRTC runtime will try to handle it correctly. If the signaling state is one of stable , have-local-offer ，或 have-remote-pranswer , the WebRTC runtime automatically creates a new offer and sets that as the new local description. Otherwise, setLocalDescription() creates an answer, which becomes the new local description.

Type of the description parameter

The description is of type RTCSessionDescriptionInit , which is a serialized version of a RTCSessionDescription browser object. They're interchangeable:

myPeerConnection.createOffer().then(function(offer) {
  return myPeerConnection.setLocalDescription(offer);
});

这相当于：

myPeerConnection.createOffer().then(function(offer) {
  return myPeerConnection.setLocalDescription(new RTCSessionDescription(offer));
});

For this reason, the RTCSessionDescription() constructor is deprecated.

返回值

A Promise which is fulfilled once the value of RTCPeerConnection.localDescription 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's 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.

Deprecated parameters

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, as it will be removed in the future. You should update any existing code to use the Promise -based version of setLocalDescription() instead. The parameters for the older form of setLocalDescription() are described below, to aid in updating existing code.

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 signature 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 将被调用。

Deprecated exceptions

When using the deprecated callback-based version of setLocalDescription() , 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.

范例

Implicit descriptions

One of the advantages of the parameter-free form of setLocalDescription() is that it lets you simplify your negotiation code substantially. This is all your negotiationneeded event handler needs to look like, for the most part. Just add the signaling server code, which here is represented by the call to signalRemotePeer() .

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

Other than error handling, that's about it!

Providing your own offer or answer

The example below shows the implementation of a handler for the negotiationneeded event that explicitly creates an offer, rather than letting setLocalDescription() do it.

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

This begins by creating an offer by calling createOffer() ; when that succeeds, we call setLocalDescription() . We can then send the newly-created offer along to the other peer using the signaling server, which here is done by calling a function called signalRemotePeer() .

规范

规范	状态	注释
WebRTC 1.0: Real-time Communication Between Browsers The definition of 'RTCPeerConnection.setLocalDescription()' 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
`setLocalDescription()`	Chrome 51 51 Promise-based version. 24	Edge 15	Firefox 22 22 Firefox does not support descriptions of type `pranswer` .	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 6.0 6.0 Promise-based version and unprefixed. 不支持 5.0 — 6.0 Promise-based version.
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 API

元数据

最后修改： Aug 19, 2020

WebRTC API
RTCPeerConnection
构造函数
1. RTCPeerConnection()
特性
方法
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()
事件
1. ~~addstream~~
2. icecandidateerror
3. ~~identityresult~~
4. negotiationneeded
5. removestream
6. signalingstatechange
继承：
1. EventTarget
Related pages for WebRTC

在此页

句法

参数