diff --git a/files/en-us/web/api/rtcpeerconnection/createanswer/index.md b/files/en-us/web/api/rtcpeerconnection/createanswer/index.md index 9b3cbd4dcf175dd..c420a94c7435644 100644 --- a/files/en-us/web/api/rtcpeerconnection/createanswer/index.md +++ b/files/en-us/web/api/rtcpeerconnection/createanswer/index.md @@ -52,7 +52,12 @@ The parameters for the older form of `createAnswer()` are described below, to ai ### Return value -A {{jsxref("Promise")}} whose fulfillment handler is called with an object conforming to the {{domxref("RTCSessionDescriptionInit")}} dictionary which contains the SDP answer to be delivered to the other peer. +A {{jsxref("Promise")}} that fulfills with an object containing the same properties as an {{domxref("RTCSessionDescription")}} objects: + +- `type` + - : A string whose value is `"answer"`. +- `sdp` + - : A string containing the SDP describing the session, to be delivered to the remote peer. ## Examples diff --git a/files/en-us/web/api/rtcpeerconnection/createoffer/index.md b/files/en-us/web/api/rtcpeerconnection/createoffer/index.md index f44a59564c00dfd..7ab3b6dcba66d76 100644 --- a/files/en-us/web/api/rtcpeerconnection/createoffer/index.md +++ b/files/en-us/web/api/rtcpeerconnection/createoffer/index.md @@ -12,8 +12,6 @@ The **`createOffer()`** method of the {{domxref("RTCPeerConnection")}} interface The SDP offer includes information about any {{domxref("MediaStreamTrack")}} objects already attached to the WebRTC session, codec, and options supported by the browser, and any candidates already gathered by the {{Glossary("ICE")}} agent, for the purpose of being sent over the signaling channel to a potential peer to request a connection or to update the configuration of an existing connection. -The return value is a {{jsxref("Promise")}} which, when the offer has been created, is resolved with a [RTCSessionDescriptionInit](/en-US/docs/Web/API/RTCSessionDescription/RTCSessionDescription#options) dictionary containing the newly-created offer. - ## Syntax ```js-nolint @@ -57,8 +55,12 @@ The parameters for the older form of `createOffer()` are described below, to aid ### Return value -A {{jsxref("Promise")}} whose fulfillment handler will receive an object conforming to the [RTCSessionDescriptionInit](/en-US/docs/Web/API/RTCSessionDescription/RTCSessionDescription#options) dictionary which contains the SDP describing the generated offer. -That received offer should be delivered through the signaling server to a remote peer. +A {{jsxref("Promise")}} that fulfills with an object containing the same properties as an {{domxref("RTCSessionDescription")}} objects: + +- `type` + - : A string whose value is `"offer"`. +- `sdp` + - : A string containing the SDP describing the generated offer, to be delivered to the remote peer. ### Exceptions @@ -99,7 +101,7 @@ myPeerConnection }); ``` -In this code, the offer is created, and once successful, the local end of the {{domxref("RTCPeerConnection")}} is configured to match by passing the offer (which is represented using an object conforming to [RTCSessionDescriptionInit](/en-US/docs/Web/API/RTCSessionDescription/RTCSessionDescription#options)) into {{domxref("RTCPeerConnection.setLocalDescription", "setLocalDescription()")}}. +In this code, the offer is created, and once successful, the local end of the {{domxref("RTCPeerConnection")}} is configured to match by passing the offer (which is represented using an object in the same shape as {{domxref("RTCSessionDescription")}}) into {{domxref("RTCPeerConnection.setLocalDescription", "setLocalDescription()")}}. Once that's done, the offer is sent to the remote system over the signaling channel; in this case, by using a custom function called `sendToServer()`. The implementation of the signaling server is independent from the WebRTC specification, so it doesn't matter how the offer is sent as long as both the caller and potential receiver are using the same one. diff --git a/files/en-us/web/api/rtcpeerconnection/setlocaldescription/index.md b/files/en-us/web/api/rtcpeerconnection/setlocaldescription/index.md index 4d260c3f1d36b61..c32a24d50867aed 100644 --- a/files/en-us/web/api/rtcpeerconnection/setlocaldescription/index.md +++ b/files/en-us/web/api/rtcpeerconnection/setlocaldescription/index.md @@ -28,47 +28,17 @@ setLocalDescription(sessionDescription, successCallback, errorCallback) // depre ### Parameters - `sessionDescription` {{optional_inline}} - - : An {{domxref("RTCSessionDescriptionInit")}} or {{domxref("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. - -### Return value -A {{jsxref("Promise")}} which is fulfilled once the value of {{domxref("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. + - : An object which specifies the configuration to be applied to the local end of the connection. It should contain the following properties: -> [!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](/en-US/docs/Web/API/WebRTC_API/Connectivity#pending_and_current_descriptions) in the WebRTC Connectivity page for more details on this process. - -#### Implicit description - -If you don't explicitly provide a session description, the WebRTC runtime will try to handle it correctly. -If the signaling state is one of `stable`, `have-local-offer`, or `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 {{domxref("RTCSessionDescription")}} browser object. They're interchangeable: - -```js -myPeerConnection - .createOffer() - .then((offer) => myPeerConnection.setLocalDescription(offer)); -``` + - `type` {{optional_inline}} + - : A string indicating the type of the session description. If you don't explicitly provide a session description, the WebRTC runtime will try to handle it correctly. If the signaling state is one of `stable`, `have-local-offer`, or `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. + - `sdp` {{optional_inline}} + - : A string containing the SDP describing the session. If sdp is not provided, it defaults to an empty string. If `type` is `"rollback"`, `sdp` must be null or an empty string. -This is equivalent to: - -```js -myPeerConnection - .createOffer() - .then((offer) => - myPeerConnection.setLocalDescription(new RTCSessionDescription(offer)), - ); -``` - -For this reason, the {{domxref("RTCSessionDescription.RTCSessionDescription", "RTCSessionDescription()")}} constructor is deprecated. + If the description is omitted, the WebRTC runtime tries to automatically do the right thing. -### Deprecated parameters + You can also pass an actual {{domxref("RTCSessionDescription")}} instance, but there's no difference. For this reason, the `RTCSessionDescription` constructor is deprecated. 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. @@ -84,6 +54,15 @@ The parameters for the older form of `setLocalDescription()` are described below 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. +### Return value + +A {{jsxref("Promise")}} which is fulfilled once the value of {{domxref("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. + +> [!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](/en-US/docs/Web/API/WebRTC_API/Connectivity#pending_and_current_descriptions) in the WebRTC Connectivity page for more details on this process. + ### Deprecated exceptions When using the deprecated callback-based version of `setLocalDescription()`, the following exceptions may occur: @@ -91,7 +70,7 @@ When using the deprecated callback-based version of `setLocalDescription()`, the - `InvalidStateError` {{domxref("DOMException")}} {{deprecated_inline}} - : Thrown if the connection's {{domxref("RTCPeerConnection.signalingState", "signalingState")}} is `"closed"`, indicating that the connection is not currently open, so negotiation cannot take place. - `InvalidSessionDescriptionError` {{domxref("DOMException")}} {{deprecated_inline}} - - : Thrown if the {{domxref("RTCSessionDescription")}} specified by the `sessionDescription` parameter is invalid. + - : Thrown if the `sessionDescription` parameter is invalid. ## Examples @@ -141,3 +120,4 @@ called `signalRemotePeer()`. ## See also - [WebRTC API](/en-US/docs/Web/API/WebRTC_API) +- {{domxref("RTCSessionDescription")}} diff --git a/files/en-us/web/api/rtcpeerconnection/setremotedescription/index.md b/files/en-us/web/api/rtcpeerconnection/setremotedescription/index.md index 9c7dbce89ba7b1f..ae3f89090a2632e 100644 --- a/files/en-us/web/api/rtcpeerconnection/setremotedescription/index.md +++ b/files/en-us/web/api/rtcpeerconnection/setremotedescription/index.md @@ -23,37 +23,37 @@ Only then does the agreed-upon configuration take effect. ```js-nolint setRemoteDescription(sessionDescription) + +// deprecated +setRemoteDescription(sessionDescription, successCallback, errorCallback) ``` ### Parameters - `sessionDescription` - - : An {{domxref("RTCSessionDescriptionInit")}} or {{domxref("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 -The `sessionDescription` parameter is technically of type `RTCSessionDescriptionInit`, but because {{domxref("RTCSessionDescription")}} serializes to be indistinguishable from `RTCSessionDescriptionInit`, you can also pass in an `RTCSessionDescription`. -This lets you simplify code such as the following: + - : An object which specifies the remote peer's current offer or answer. It should contain the following properties: -```js -myPeerConnection - .setRemoteDescription(new RTCSessionDescription(description)) - .then(() => createMyStream()); -``` + - `type` + - : A string indicating the type of the session description. See {{domxref("RTCSessionDescription.type")}}. + - `sdp` {{optional_inline}} + - : A string containing the SDP describing the session. If sdp is not provided, it defaults to an empty string. If `type` is `"rollback"`, `sdp` must be null or an empty string. See {{domxref("RTCSessionDescription.sdp")}}. -to be: + You can also pass an actual {{domxref("RTCSessionDescription")}} instance, but there's no difference. For this reason, the `RTCSessionDescription` constructor is deprecated. -```js -myPeerConnection.setRemoteDescription(description).then(() => createMyStream()); -``` - -Using [`async`](/en-US/docs/Web/JavaScript/Reference/Statements/async_function)/[`await`](/en-US/docs/Web/JavaScript/Reference/Operators/await) syntax, you can further simplify this to: +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 {{jsxref("Promise")}}-based version of `setRemoteDescription()` instead. +The parameters for the older form of `setRemoteDescription()` are described below, to aid in updating existing code. -```js -await myPeerConnection.setRemoteDescription(description); -createMyStream(); -``` +- `successCallback` {{deprecated_inline}} + - : A JavaScript {{jsxref("Function")}} which accepts no input parameters to 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` {{deprecated_inline}} + - : A function matching the signature `RTCPeerConnectionErrorCallback` which gets called if the description can't be set. + It is passed a single {{domxref("DOMException")}} object explaining why the request failed. -Since it's unnecessary, the {{domxref("RTCSessionDescription.RTCSessionDescription", "RTCSessionDescription()")}} constructor is deprecated. +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. ### Return value @@ -80,7 +80,14 @@ The following exceptions are reported to the rejection handler for the promise r - : Returned with the {{domxref("RTCError.errorDetail", "errorDetail")}} set to `sdp-syntax-error` if the {{Glossary("SDP")}} specified by {{domxref("RTCSessionDescription.sdp")}} is not valid. The error object's {{domxref("RTCError.sdpLineNumber", "sdpLineNumber")}} property indicates the line number within the SDP on which the syntax error was detected. - {{jsxref("TypeError")}} - - : Returned if the specified `RTCSessionDescriptionInit` or `RTCSessionDescription` object is missing the {{domxref("RTCSessionDescription.type", "type")}} property, or no description parameter was provided at all. + - : Returned if the `sessionDescription` is missing the {{domxref("RTCSessionDescription.type", "type")}} property, or no description parameter was provided at all. + +When using the deprecated callback-based version of `setRemoteDescription()`, the following exceptions may occur: + +- `InvalidStateError` {{deprecated_inline}} + - : The connection's {{domxref("RTCPeerConnection.signalingState", "signalingState")}} is `"closed"`, indicating that the connection is not currently open, so negotiation cannot take place. +- `InvalidSessionDescriptionError` {{deprecated_inline}} + - : The `sessionDescription` parameter is invalid. ## Usage notes @@ -97,37 +104,6 @@ This happens instead of throwing an exception, thereby reducing the number of po > [!NOTE] > Earlier implementations of WebRTC would throw an exception if an offer was set outside a `stable` or `have-remote-offer` state. -## 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 {{jsxref("Promise")}}-based version of `setRemoteDescription()` instead. -The parameters for the older form of `setRemoteDescription()` are described below, to aid in updating existing code. - -```js -pc.setRemoteDescription(sessionDescription, successCallback, errorCallback); -``` - -### Parameters - -- `successCallback` {{deprecated_inline}} - - : A JavaScript {{jsxref("Function")}} which accepts no input parameters to 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` {{deprecated_inline}} - - : A function matching the signature `RTCPeerConnectionErrorCallback` which gets called if the description can't be set. - It is passed a single {{domxref("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` {{deprecated_inline}} - - : The connection's {{domxref("RTCPeerConnection.signalingState", "signalingState")}} is `"closed"`, indicating that the connection is not currently open, so negotiation cannot take place. -- `InvalidSessionDescriptionError` {{deprecated_inline}} - - : The {{domxref("RTCSessionDescription")}} specified by the `sessionDescription` parameter is invalid. - ## Examples Here we see a function which handles an offer received from the remote peer. @@ -171,3 +147,4 @@ When our promise fulfillment handler is called, indicating that this has been do - {{domxref("RTCPeerConnection.remoteDescription")}}, {{domxref("RTCPeerConnection.pendingRemoteDescription")}}, {{domxref("RTCPeerConnection.currentRemoteDescription")}} +- {{domxref("RTCSessionDescription")}} diff --git a/files/en-us/web/api/rtcsessiondescription/index.md b/files/en-us/web/api/rtcsessiondescription/index.md index c0ae40122fe523d..3ede4b4444acce7 100644 --- a/files/en-us/web/api/rtcsessiondescription/index.md +++ b/files/en-us/web/api/rtcsessiondescription/index.md @@ -11,6 +11,11 @@ The **`RTCSessionDescription`** interface describes one end of a connection—or The process of negotiating a connection between two peers involves exchanging `RTCSessionDescription` objects back and forth, with each description suggesting one combination of connection configuration options that the sender of the description supports. Once the two peers agree upon a configuration for the connection, negotiation is complete. +## Constructor + +- {{domxref("RTCSessionDescription.RTCSessionDescription", "RTCSessionDescription()")}} {{deprecated_inline}} + - : Creates a new `RTCSessionDescription` by specifying the `type` and `sdp`. All methods that accept `RTCSessionDescription` objects also accept objects with the same properties, so you can use a plain object instead of creating an `RTCSessionDescription` instance. + ## Instance properties _The `RTCSessionDescription` interface doesn't inherit any properties._ @@ -24,8 +29,6 @@ _The `RTCSessionDescription` interface doesn't inherit any properties._ _The `RTCSessionDescription` doesn't inherit any methods._ -- {{domxref("RTCSessionDescription.RTCSessionDescription", "RTCSessionDescription()")}} {{deprecated_inline}} - - : This constructor returns a new `RTCSessionDescription`. The parameter is a `RTCSessionDescriptionInit` dictionary containing the values to assign the two properties. - {{domxref("RTCSessionDescription.toJSON()")}} - : Returns a {{Glossary("JSON")}} description of the object. The values of both properties, {{domxref("RTCSessionDescription.type", "type")}} and {{domxref("RTCSessionDescription.sdp", "sdp")}}, are contained in the generated JSON. @@ -36,7 +39,7 @@ signalingChannel.onmessage = (evt) => { if (!pc) start(false); const message = JSON.parse(evt.data); - if (message.sdp) { + if (message.type && message.sdp) { pc.setRemoteDescription( new RTCSessionDescription(message), () => { diff --git a/files/en-us/web/api/rtcsessiondescription/rtcsessiondescription/index.md b/files/en-us/web/api/rtcsessiondescription/rtcsessiondescription/index.md index 339ec967a44b54d..45c4ab4d1205788 100644 --- a/files/en-us/web/api/rtcsessiondescription/rtcsessiondescription/index.md +++ b/files/en-us/web/api/rtcsessiondescription/rtcsessiondescription/index.md @@ -17,8 +17,7 @@ specified object. > [!NOTE] > This constructor has been deprecated because > {{domxref("RTCPeerConnection.setLocalDescription()")}} and other methods which take -> SDP as input now directly accept an object conforming to the -> `RTCSessionDescriptionInit` dictionary, so you don't have to instantiate an +> SDP as input now directly accept an object containing the {{domxref("RTCSessionDescription.type", "type")}} and {{domxref("RTCSessionDescription.sdp", "sdp")}} properties, so you don't have to instantiate an > `RTCSessionDescription` yourself. ## Syntax @@ -29,15 +28,13 @@ new RTCSessionDescription(options) ### Values -- `options` {{optional_inline}} +- `options` - - : An object providing the default values for the session description; the object - conforms to the `RTCSessionDescriptionInit` dictionary. That dictionary has - the following properties: + - : An object providing the default values for the session description. It should contain the following properties: - `type` - - : **Required.** A string which is used to set the `type` property of the new `RTCSessionDescription` object. - - `sdp` + - : **Required.** A string which is used to set the `type` property of the new `RTCSessionDescription` object. Must be one of the valid {{domxref("RTCSessionDescription.type")}} values. + - `sdp` {{optional_inline}} - : A string containing a {{Glossary("SDP")}} message describing the session. This value is an empty string (`""`) by default and may not be `null`. ## Example @@ -48,8 +45,7 @@ This example uses the constructor to convert an SDP offer into an > [!NOTE] > This is no longer necessary, however; > {{domxref("RTCPeerConnection.setLocalDescription()")}} and other methods which take -> SDP as input now directly accept an object conforming to the -> `RTCSessionDescriptionInit` dictionary, so you don't have to instantiate an +> SDP as input now directly accept plain objects, so you don't have to instantiate an > `RTCSessionDescription` yourself. ```js @@ -72,7 +68,7 @@ navigator.getUserMedia({ video: true }, (stream) => { ## Specifications -This feature is not part of any current specification. It is no longer on track to become a standard. +{{Specifications}} ## Browser compatibility