RTCPeerConnection.setRemoteDescription()
This is an experimental technology
Because this technology's specification has not stabilized, check the compatibility table for usage in various browsers. Also note that the syntax and behavior of an experimental technology is subject to change in future versions of browsers as the specification changes.
Draft
This page is not complete.
The RTCPeerConnection.setRemoteDescription()
method changes the remote description associated with the connection. This description specifies the properties of the remote end of the connection, including the media format. The actual connection is affected by this change, so it must be able to support both the old and new descriptions in order for the change to actually take place. 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.
Syntax
aPromise = pc.setRemoteDescription(sessionDescription); pc.setRemoteDescription(sessionDescription, successCallback, errorCallback); <span title="This deprecated API should no longer be used, but will probably still work.">class="icon-thumbs-down-alt"> </span>
Parameters
sessionDescription
- An
RTCSessionDescriptionInit
orRTCSessionDescription
which specifies the configuration of the remote end of the connection.
Return value
A Promise
which is fulfilled once the value of RTCPeerConnection.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 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. 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.
successCallback
- A JavaScript
Function
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 takes one input parameter:errorInformation
: ADOMString
describing the reason why the description couldn't be set.
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
will be called.
Deprecated exceptions
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
- The
RTCSessionDescription
specified by thesessionDescription
parameter is invalid.
Example
// TBD
Specifications
Specification | Status | Comment |
---|---|---|
WebRTC 1.0: Real-time Communication Between Browser The definition of 'RTCPeerConnection.setRemoteDescription()' in that specification. |
Working Draft | Initial specification. |
WebRTC 1.0: Real-time Communication Between Browser The definition of 'RTCPeerConnection.setRemoteDescription()' in that specification. |
Working Draft | Initial specification. |
Browser compatibility
Feature | Chrome | Firefox (Gecko) | Internet Explorer | Opera | Safari |
---|---|---|---|---|---|
Basic support | (Yes) | 22 (22) [1] | No support | (Yes) | ? |
Promise-based version | 50.0 | (Yes) | (Yes) | (Yes) | (Yes) |
Feature | Android | Android Webview | Firefox Mobile (Gecko) | IE Mobile | Opera Mobile | Safari Mobile | Chrome for Android |
---|---|---|---|---|---|---|---|
Basic support | No support | (Yes) | 22.0 (22) | No support | ? | ? | (Yes) |
Promise-based version | No support | 50.0 | (Yes) | (Yes) | (Yes) | (Yes) | 50.0 |
[1] Though this property is not prefixed, the interface it belongs to is, until Firefox 44.
See also
- WebRTC
RTCPeerConnection.remoteDescription
,RTCPeerConnection.pendingRemoteDescription
,RTCPeerConnection.currentRemoteDescription
License
© 2016 Mozilla Contributors
Licensed under the Creative Commons Attribution-ShareAlike License v2.5 or later.
https://developer.mozilla.org/en-us/docs/web/api/rtcpeerconnection/setremotedescription