RTCPeerConnection.setRemoteDescription()

Nos bénévoles n'ont pas encore traduit cet article en Français. Inscrivez-vous et aidez-nous à réaliser cette tâche !
Vous pouvez également lire cet article en English (US).

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 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.

Syntax

aPromise = pc.setRemoteDescription(sessionDescription);

Parameters

sessionDescription
An RTCSessionDescriptionInit or RTCSessionDescription which specifies the configuration taken on by the remote end of the connection.

The 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();
})

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

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

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

Return value

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.

Note: 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.

Exceptions

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

InvalidAccessError
The content of the description is invalid.
InvalidStateError
The RTCPeerConnection is closed, or it's in a state which isn't compatible with the specified description's type. For example, if the type is rollback and the signaling state is one of stable, have-local-pranswer, or 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 with the errorDetail set to sdp-syntax-error is reported if the SDP specified by RTCSessionDescription.sdp. The error object's sdpLineNumber property indicates the line number within the SDP on which the syntax error was detected.
TypeError
The specified RTCSessionDescriptionInit or RTCSessionDescription object is missing the type property, or no description parameter was provided at all.

Usage notes

When you call 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.

Otherwise—if the offer cannot be set because of the current signaling state—the ICE agent is in the middle of negotiating a connection and it's not an appropriate time to set a new offer. In taht situation, the ICE agent automatically initiates an ICE rollback in order to bring the connection back to a stable signaling status before then trying to set the remote description with the new offer.

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.

Note: Earlier implementations of WebRTC would throw an exception if an offer was set outside a stable or have-remote-offer state, rather than .

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);

Parameters

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 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 will be called.

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 the sessionDescription parameter is invalid.

Example

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 setLocalConnection() to set that as the configuration at our end of the call before forwarding that answer to the caller.

Specifications

Specification Status Comment
WebRTC 1.0: Real-time Communication Between Browsers
The definition of 'RTCPeerConnection.setRemoteDescription()' in that specification.
Candidate Recommendation Initial specification.
WebRTC 1.0: Real-time Communication Between Browsers
The definition of 'RTCPeerConnection.setRemoteDescription()' in that specification.
Candidate Recommendation Initial specification.

Browser compatibility

Update compatibility data on GitHub
DesktopMobile
ChromeEdgeFirefoxInternet ExplorerOperaSafariAndroid webviewChrome for AndroidFirefox for AndroidOpera for AndroidSafari on iOSSamsung Internet
setRemoteDescriptionChrome Full support 51
Notes
Full support 51
Notes
Notes Promise-based version.
Full support 24
Edge Full support 15Firefox Full support 22IE No support NoOpera Full support 43
Notes
Full support 43
Notes
Notes Promise-based version.
No support 37 — 43
Safari Full support 11WebView Android Full support 51
Notes
Full support 51
Notes
Notes Promise-based version.
Full support Yes
Chrome Android Full support 51
Notes
Full support 51
Notes
Notes Promise-based version.
Full support Yes
Firefox Android Full support 44Opera Android Full support 43
Notes
Full support 43
Notes
Notes Promise-based version.
No support 37 — 43
Safari iOS Full support YesSamsung Internet Android Full support 6.0

Legend

Full support  
Full support
No support  
No support
See implementation notes.
See implementation notes.

See also

Étiquettes et contributeurs liés au document

Contributeurs à cette page : Sheppy, mdnwebdocs-bot, fscholz, chrisdavidmills, jpmedley, abbycar, teoli
Dernière mise à jour par : Sheppy,