From 64eec53e2c4f5ea110e3dd6c4cb62e28c5875c79 Mon Sep 17 00:00:00 2001 From: Byoungchan Lee Date: Thu, 6 Jun 2024 21:51:09 +0900 Subject: [PATCH 1/9] fix: Add missing documentation for RTCSessionDescriptionInit, RTCLocalSessionDescriptionInit Add missing documentation for RTCSessionDescriptionInit, RTCLocalSessionDescriptionInit interfaces. Also correct several links referencing those interfaces. Also add a clear explanation of the relationship between RTCSessionDescription, RTCSessionDescriptionInit, and RTCLocalSessionDescriptionInit interfaces. Fixes #33962 --- .../rtclocalsessiondescriptioninit/index.md | 29 ++++++++++++++++++ .../rtcpeerconnection/createoffer/index.md | 4 +-- .../setlocaldescription/index.md | 7 +++-- .../setremotedescription/index.md | 5 ++-- .../web/api/rtcsessiondescription/index.md | 14 ++++++++- .../rtcsessiondescription/index.md | 4 +-- .../api/rtcsessiondescriptioninit/index.md | 30 +++++++++++++++++++ 7 files changed, 83 insertions(+), 10 deletions(-) create mode 100644 files/en-us/web/api/rtclocalsessiondescriptioninit/index.md create mode 100644 files/en-us/web/api/rtcsessiondescriptioninit/index.md diff --git a/files/en-us/web/api/rtclocalsessiondescriptioninit/index.md b/files/en-us/web/api/rtclocalsessiondescriptioninit/index.md new file mode 100644 index 000000000000000..a5dbbb0662c3f9d --- /dev/null +++ b/files/en-us/web/api/rtclocalsessiondescriptioninit/index.md @@ -0,0 +1,29 @@ +--- +title: RTCLocalSessionDescriptionInit +slug: Web/API/RTCLocalSessionDescriptionInit +page-type: web-api-interface +browser-compat: api.RTCSessionDescription +--- + +{{APIRef("WebRTC")}} + +The **`RTCLocalSessionDescriptionInit`** dictionary is used to provide {{Glossary("SDP")}} values in {{domxref("RTCPeerConnection.setLocalDescription")}}. Especially, empty object(`{}`) conforms the `RTCLocalSessionDescriptionInit` dictionary. + +### Properties + +- `type` + - : A string which is used to set the `type` property of the new `RTCSessionDescription` object. For more information, see documentation for the {{domxref("RTCSessionDescription.type")}} property. +- `sdp` + - : A string containing the {{Glossary("SDP")}} describing the session. If `type` is `"rollback"`, this member is unused. + + +## Specifications + +https://w3c.github.io/webrtc-pc/#dom-rtclocalsessiondescriptioninit + +## See also + +- [WebRTC](/en-US/docs/Web/API/WebRTC_API) +- {{domxref("RTCSessionDescription")}} +- {{domxref("RTCSessionDescriptionInit")}} +- {{domxref("RTCPeerConnection.setLocalDescription")}} diff --git a/files/en-us/web/api/rtcpeerconnection/createoffer/index.md b/files/en-us/web/api/rtcpeerconnection/createoffer/index.md index 022887dee582f69..9715db8a11ed119 100644 --- a/files/en-us/web/api/rtcpeerconnection/createoffer/index.md +++ b/files/en-us/web/api/rtcpeerconnection/createoffer/index.md @@ -57,7 +57,7 @@ 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#rtcsessiondescriptioninit) dictionary which contains the SDP describing the generated offer. +A {{jsxref("Promise")}} whose fulfillment handler will receive an object conforming to the {{domxref("RTCSessionDescriptionInit")}} dictionary which contains the SDP describing the generated offer. That received offer should be delivered through the signaling server to a remote peer. ### Exceptions @@ -98,7 +98,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#rtcsessiondescriptioninit)) 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 conforming to {{domxref("RTCSessionDescriptionInit")}} 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 bf1a393e0c80bd4..5c4e0f40035dd97 100644 --- a/files/en-us/web/api/rtcpeerconnection/setlocaldescription/index.md +++ b/files/en-us/web/api/rtcpeerconnection/setlocaldescription/index.md @@ -28,7 +28,7 @@ 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. + - : An {{domxref("RTCLocalSessionDescriptionInit")}} 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 @@ -47,7 +47,7 @@ Otherwise, `setLocalDescription()` creates an answer, which becomes the new loca #### 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: +The description is of type `RTCLocalSessionDescriptionInit`, which is a serialized version of a {{domxref("RTCSessionDescription")}} browser object. They're interchangeable: ```js myPeerConnection @@ -90,7 +90,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 {{domxref("RTCLocalSessionDescriptionInit")}} specified by the `sessionDescription` parameter is invalid. ## Examples @@ -140,3 +140,4 @@ called `signalRemotePeer()`. ## See also - [WebRTC API](/en-US/docs/Web/API/WebRTC_API) +- {{domxref("RTCLocalSessionDescriptionInit")}} diff --git a/files/en-us/web/api/rtcpeerconnection/setremotedescription/index.md b/files/en-us/web/api/rtcpeerconnection/setremotedescription/index.md index 1cd73d9b89d40f5..fd3a35814cc296b 100644 --- a/files/en-us/web/api/rtcpeerconnection/setremotedescription/index.md +++ b/files/en-us/web/api/rtcpeerconnection/setremotedescription/index.md @@ -124,7 +124,7 @@ When using the deprecated callback-based version of `setRemoteDescription()`, th - `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. + - : The {{domxref("RTCSessionDescriptionInit")}} specified by the `sessionDescription` parameter is invalid. ## Examples @@ -168,4 +168,5 @@ When our promise fulfillment handler is called, indicating that this has been do - [WebRTC](/en-US/docs/Web/API/WebRTC_API) - {{domxref("RTCPeerConnection.remoteDescription")}}, {{domxref("RTCPeerConnection.pendingRemoteDescription")}}, - {{domxref("RTCPeerConnection.currentRemoteDescription")}} + {{domxref("RTCPeerConnection.currentRemoteDescription")}} +- {{domxref("RTCSessionDescriptionInit")}} diff --git a/files/en-us/web/api/rtcsessiondescription/index.md b/files/en-us/web/api/rtcsessiondescription/index.md index c0ae40122fe523d..09c5247c95dc7ed 100644 --- a/files/en-us/web/api/rtcsessiondescription/index.md +++ b/files/en-us/web/api/rtcsessiondescription/index.md @@ -25,7 +25,7 @@ _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. + - : This constructor returns a new `RTCSessionDescription`. The parameter is a {{domxref("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. @@ -57,6 +57,16 @@ signalingChannel.onmessage = (evt) => { }; ``` +## RTCSessionDescription, RTCSessionDescriptionInit, and RTCLocalSessionDescriptionInit + +There are other similar interfaces that are used to provide the SDP values for `RTCSessionDescription` objects. These are: +- {{domxref("RTCSessionDescriptionInit")}} +- {{domxref("RTCLocalSessionDescriptionInit")}} + +These interfaces are used in several methods of the {{domxref("RTCPeerConnection")}} interface utilize these interfaces, including {{domxref("RTCPeerConnection.createOffer")}}, {{domxref("RTCPeerConnection.createAnswer")}}, {{domxref("RTCPeerConnection.setLocalDescription")}}, and {{domxref("RTCPeerConnection.setRemoteDescription")}}. + +In essence, `RTCSessionDescriptionInit` and `RTCLocalSessionDescriptionInit` are defined as dictionaries, enabling users to provide necessary values without creating a full `RTCSessionDescription` object. Also, `RTCPeerConnection.setLocalDescription()` accepts `RTCLocalSessionDescriptionInit` as an argument, allowing users to omit this argument altogether. This eliminates the need for separate calls to `RTCPeerConnection.createOffer()` and `RTCPeerConnection.setLocalDescription()`. (For more information, see [Implicit description in RTCPeerConnection.setLocalDescription()](/en-US/docs/Web/API/RTCPeerConnection/setLocalDescription#implicit_description)). + ## Specifications {{Specifications}} @@ -69,3 +79,5 @@ signalingChannel.onmessage = (evt) => { - [WebRTC](/en-US/docs/Web/API/WebRTC_API) - {{domxref("RTCPeerConnection.setLocalDescription()")}} and {{domxref("RTCPeerConnection.setRemoteDescription()")}} +- {{domxref("RTCSessionDescriptionInit")}} +- {{domxref("RTCLocalSessionDescriptionInit")}} diff --git a/files/en-us/web/api/rtcsessiondescription/rtcsessiondescription/index.md b/files/en-us/web/api/rtcsessiondescription/rtcsessiondescription/index.md index 26cd3ba8a9289dc..5ecb650a682b4eb 100644 --- a/files/en-us/web/api/rtcsessiondescription/rtcsessiondescription/index.md +++ b/files/en-us/web/api/rtcsessiondescription/rtcsessiondescription/index.md @@ -17,7 +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 +> {{domxref("RTCSessionDescriptionInit")}} dictionary, so you don't have to instantiate an > `RTCSessionDescription` yourself. ## Syntax @@ -31,7 +31,7 @@ new RTCSessionDescription(options) - `options` {{optional_inline}} - : An object providing the default values for the session description; the object - conforms to the `RTCSessionDescriptionInit` dictionary. That dictionary has + conforms to the {{domxref("RTCSessionDescriptionInit")}} dictionary. That dictionary has the following properties: - `type` diff --git a/files/en-us/web/api/rtcsessiondescriptioninit/index.md b/files/en-us/web/api/rtcsessiondescriptioninit/index.md new file mode 100644 index 000000000000000..d74c16a75b8086d --- /dev/null +++ b/files/en-us/web/api/rtcsessiondescriptioninit/index.md @@ -0,0 +1,30 @@ +--- +title: RTCSessionDescriptionInit +slug: Web/API/RTCSessionDescriptionInit +page-type: web-api-interface +browser-compat: api.RTCSessionDescription +--- + +{{APIRef("WebRTC")}} + +The **`RTCSessionDescriptionInit`** dictionary is used to provide {{Glossary("SDP")}} values in several methods of the {{domxref("RTCPeerConnection")}} interface, such as {{domxref("RTCPeerConnection.createOffer")}}, {{domxref("RTCPeerConnection.createAnswer")}}, and {{domxref("RTCPeerConnection.setRemoteDescription")}}. Also it can be used to create new `RTCSessionDescription` objects, though this is less common. + +### Properties + +- `type` + - : A string which is used to set the `type` property of the new `RTCSessionDescription` object. This is a required property. For more information, see documentation for the {{domxref("RTCSessionDescription.type")}} property. +- `sdp` + - : A string containing the {{Glossary("SDP")}} describing the session. If `type` is `"rollback"`, this member is unused. + +## Specifications + +https://w3c.github.io/webrtc-pc/#dom-rtcsessiondescriptioninit + +## See also + +- [WebRTC](/en-US/docs/Web/API/WebRTC_API) +- {{domxref("RTCSessionDescription")}} +- {{domxref("RTCLocalSessionDescriptionInit")}} +- {{domxref("RTCPeerConnection.createOffer")}} +- {{domxref("RTCPeerConnection.createAnswer")}} +- {{domxref("RTCPeerConnection.setRemoteDescription")}} From 8e5581a4ad0ede36ac44f03cf17555eeeaf9d83f Mon Sep 17 00:00:00 2001 From: Byoungchan Lee Date: Thu, 6 Jun 2024 21:58:49 +0900 Subject: [PATCH 2/9] Apply suggestions from code review Co-authored-by: github-actions[bot] <41898282+github-actions[bot]@users.noreply.github.com> --- files/en-us/web/api/rtclocalsessiondescriptioninit/index.md | 1 - .../web/api/rtcpeerconnection/setremotedescription/index.md | 2 +- files/en-us/web/api/rtcsessiondescription/index.md | 1 + 3 files changed, 2 insertions(+), 2 deletions(-) diff --git a/files/en-us/web/api/rtclocalsessiondescriptioninit/index.md b/files/en-us/web/api/rtclocalsessiondescriptioninit/index.md index a5dbbb0662c3f9d..4f15777abbe3edd 100644 --- a/files/en-us/web/api/rtclocalsessiondescriptioninit/index.md +++ b/files/en-us/web/api/rtclocalsessiondescriptioninit/index.md @@ -16,7 +16,6 @@ The **`RTCLocalSessionDescriptionInit`** dictionary is used to provide {{Glossar - `sdp` - : A string containing the {{Glossary("SDP")}} describing the session. If `type` is `"rollback"`, this member is unused. - ## Specifications https://w3c.github.io/webrtc-pc/#dom-rtclocalsessiondescriptioninit diff --git a/files/en-us/web/api/rtcpeerconnection/setremotedescription/index.md b/files/en-us/web/api/rtcpeerconnection/setremotedescription/index.md index fd3a35814cc296b..a379f009f1ae044 100644 --- a/files/en-us/web/api/rtcpeerconnection/setremotedescription/index.md +++ b/files/en-us/web/api/rtcpeerconnection/setremotedescription/index.md @@ -168,5 +168,5 @@ When our promise fulfillment handler is called, indicating that this has been do - [WebRTC](/en-US/docs/Web/API/WebRTC_API) - {{domxref("RTCPeerConnection.remoteDescription")}}, {{domxref("RTCPeerConnection.pendingRemoteDescription")}}, - {{domxref("RTCPeerConnection.currentRemoteDescription")}} + {{domxref("RTCPeerConnection.currentRemoteDescription")}} - {{domxref("RTCSessionDescriptionInit")}} diff --git a/files/en-us/web/api/rtcsessiondescription/index.md b/files/en-us/web/api/rtcsessiondescription/index.md index 09c5247c95dc7ed..b5e1f9a93f91da1 100644 --- a/files/en-us/web/api/rtcsessiondescription/index.md +++ b/files/en-us/web/api/rtcsessiondescription/index.md @@ -60,6 +60,7 @@ signalingChannel.onmessage = (evt) => { ## RTCSessionDescription, RTCSessionDescriptionInit, and RTCLocalSessionDescriptionInit There are other similar interfaces that are used to provide the SDP values for `RTCSessionDescription` objects. These are: + - {{domxref("RTCSessionDescriptionInit")}} - {{domxref("RTCLocalSessionDescriptionInit")}} From ce7d7933c52a990ee70a743dc621593ea7596c1c Mon Sep 17 00:00:00 2001 From: Byoungchan Lee Date: Sat, 8 Jun 2024 04:21:10 +0900 Subject: [PATCH 3/9] Apply Code Review Combine RTCSessionDescriptionInit and RTCLocalSessionDescriptionInit descriptions within the RTCSessionDescription page. Additionally, update any related links. --- .../rtclocalsessiondescriptioninit/index.md | 28 ----------- .../rtcpeerconnection/createanswer/index.md | 2 +- .../rtcpeerconnection/createoffer/index.md | 6 +-- .../setlocaldescription/index.md | 6 +-- .../setremotedescription/index.md | 6 +-- .../web/api/rtcsessiondescription/index.md | 46 +++++++++++++++---- .../rtcsessiondescription/index.md | 6 +-- .../api/rtcsessiondescriptioninit/index.md | 30 ------------ 8 files changed, 49 insertions(+), 81 deletions(-) delete mode 100644 files/en-us/web/api/rtclocalsessiondescriptioninit/index.md delete mode 100644 files/en-us/web/api/rtcsessiondescriptioninit/index.md diff --git a/files/en-us/web/api/rtclocalsessiondescriptioninit/index.md b/files/en-us/web/api/rtclocalsessiondescriptioninit/index.md deleted file mode 100644 index 4f15777abbe3edd..000000000000000 --- a/files/en-us/web/api/rtclocalsessiondescriptioninit/index.md +++ /dev/null @@ -1,28 +0,0 @@ ---- -title: RTCLocalSessionDescriptionInit -slug: Web/API/RTCLocalSessionDescriptionInit -page-type: web-api-interface -browser-compat: api.RTCSessionDescription ---- - -{{APIRef("WebRTC")}} - -The **`RTCLocalSessionDescriptionInit`** dictionary is used to provide {{Glossary("SDP")}} values in {{domxref("RTCPeerConnection.setLocalDescription")}}. Especially, empty object(`{}`) conforms the `RTCLocalSessionDescriptionInit` dictionary. - -### Properties - -- `type` - - : A string which is used to set the `type` property of the new `RTCSessionDescription` object. For more information, see documentation for the {{domxref("RTCSessionDescription.type")}} property. -- `sdp` - - : A string containing the {{Glossary("SDP")}} describing the session. If `type` is `"rollback"`, this member is unused. - -## Specifications - -https://w3c.github.io/webrtc-pc/#dom-rtclocalsessiondescriptioninit - -## See also - -- [WebRTC](/en-US/docs/Web/API/WebRTC_API) -- {{domxref("RTCSessionDescription")}} -- {{domxref("RTCSessionDescriptionInit")}} -- {{domxref("RTCPeerConnection.setLocalDescription")}} diff --git a/files/en-us/web/api/rtcpeerconnection/createanswer/index.md b/files/en-us/web/api/rtcpeerconnection/createanswer/index.md index a364319c5e54c07..5a724c324ba98a4 100644 --- a/files/en-us/web/api/rtcpeerconnection/createanswer/index.md +++ b/files/en-us/web/api/rtcpeerconnection/createanswer/index.md @@ -52,7 +52,7 @@ 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")}} whose fulfillment handler is called with an object conforming to the [`RTCSessionDescriptionInit`](/en-US/docs/Web/API/RTCSessionDescription#rtcsessiondescriptioninit) dictionary which contains the SDP answer to be delivered to the other 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 9715db8a11ed119..d4002290ebcef13 100644 --- a/files/en-us/web/api/rtcpeerconnection/createoffer/index.md +++ b/files/en-us/web/api/rtcpeerconnection/createoffer/index.md @@ -12,7 +12,7 @@ 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 {{domxref("RTCSessionDescription")}} object containing the newly-created offer. +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#rtcsessiondescriptioninit) dictionary containing the newly-created offer. ## Syntax @@ -57,7 +57,7 @@ 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 {{domxref("RTCSessionDescriptionInit")}} dictionary which contains the SDP describing the generated offer. +A {{jsxref("Promise")}} whose fulfillment handler will receive an object conforming to the [`RTCSessionDescriptionInit`](/en-US/docs/Web/API/RTCSessionDescription#rtcsessiondescriptioninit) dictionary which contains the SDP describing the generated offer. That received offer should be delivered through the signaling server to a remote peer. ### Exceptions @@ -98,7 +98,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 {{domxref("RTCSessionDescriptionInit")}} 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 conforming to [`RTCSessionDescriptionInit`](/en-US/docs/Web/API/RTCSessionDescription#rtcsessiondescriptioninit) 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 5c4e0f40035dd97..8c3d69012e8211b 100644 --- a/files/en-us/web/api/rtcpeerconnection/setlocaldescription/index.md +++ b/files/en-us/web/api/rtcpeerconnection/setlocaldescription/index.md @@ -28,7 +28,7 @@ setLocalDescription(sessionDescription, successCallback, errorCallback) // depre ### Parameters - `sessionDescription` {{optional_inline}} - - : An {{domxref("RTCLocalSessionDescriptionInit")}} or {{domxref("RTCSessionDescription")}} which specifies the configuration to be applied to the local end of the connection. + - : An [`RTCLocalSessionDescriptionInit`](/en-US/docs/Web/API/RTCSessionDescription#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 @@ -90,7 +90,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("RTCLocalSessionDescriptionInit")}} specified by the `sessionDescription` parameter is invalid. + - : Thrown if the [`RTCLocalSessionDescriptionInit`](/en-US/docs/Web/API/RTCSessionDescription#rtcsessiondescriptioninit) specified by the `sessionDescription` parameter is invalid. ## Examples @@ -140,4 +140,4 @@ called `signalRemotePeer()`. ## See also - [WebRTC API](/en-US/docs/Web/API/WebRTC_API) -- {{domxref("RTCLocalSessionDescriptionInit")}} +- {{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 a379f009f1ae044..32200ac53b3876c 100644 --- a/files/en-us/web/api/rtcpeerconnection/setremotedescription/index.md +++ b/files/en-us/web/api/rtcpeerconnection/setremotedescription/index.md @@ -28,7 +28,7 @@ setRemoteDescription(sessionDescription) ### Parameters - `sessionDescription` - - : An {{domxref("RTCSessionDescriptionInit")}} or {{domxref("RTCSessionDescription")}} which specifies the remote peer's current offer or answer. + - : An [`RTCSessionDescriptionInit`](/en-US/docs/Web/API/RTCSessionDescription#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`. @@ -124,7 +124,7 @@ When using the deprecated callback-based version of `setRemoteDescription()`, th - `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("RTCSessionDescriptionInit")}} specified by the `sessionDescription` parameter is invalid. + - : The [`RTCSessionDescriptionInit`](/en-US/docs/Web/API/RTCSessionDescription#rtcsessiondescriptioninit) specified by the `sessionDescription` parameter is invalid. ## Examples @@ -169,4 +169,4 @@ When our promise fulfillment handler is called, indicating that this has been do - {{domxref("RTCPeerConnection.remoteDescription")}}, {{domxref("RTCPeerConnection.pendingRemoteDescription")}}, {{domxref("RTCPeerConnection.currentRemoteDescription")}} -- {{domxref("RTCSessionDescriptionInit")}} +- {{domxref("RTCSessionDescription")}} diff --git a/files/en-us/web/api/rtcsessiondescription/index.md b/files/en-us/web/api/rtcsessiondescription/index.md index b5e1f9a93f91da1..8f65ba7f71fee9c 100644 --- a/files/en-us/web/api/rtcsessiondescription/index.md +++ b/files/en-us/web/api/rtcsessiondescription/index.md @@ -25,7 +25,7 @@ _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 {{domxref("RTCSessionDescriptionInit")}} dictionary containing the values to assign the two properties. + - : This constructor returns a new `RTCSessionDescription`. The parameter is a [`RTCSessionDescriptionInit`](#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 +36,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), () => { @@ -57,16 +57,44 @@ signalingChannel.onmessage = (evt) => { }; ``` -## RTCSessionDescription, RTCSessionDescriptionInit, and RTCLocalSessionDescriptionInit +## RTCSessionDescriptionInit -There are other similar interfaces that are used to provide the SDP values for `RTCSessionDescription` objects. These are: +`RTCSessionDescriptionInit` is a dictionary that holds same properties to `RTCSessionDescription`. It's used as an argument for the {{domxref("RTCPeerConnection.setLocalDescription")}}, and {{domxref("RTCPeerConnection.setRemoteDescription")}} methods, and a return value from the {{domxref("RTCPeerConnection.createOffer")}}, and {{domxref("RTCPeerConnection.createAnswer")}} methods. -- {{domxref("RTCSessionDescriptionInit")}} -- {{domxref("RTCLocalSessionDescriptionInit")}} +The `RTCSessionDescriptionInit` dictionary has the following properties: -These interfaces are used in several methods of the {{domxref("RTCPeerConnection")}} interface utilize these interfaces, including {{domxref("RTCPeerConnection.createOffer")}}, {{domxref("RTCPeerConnection.createAnswer")}}, {{domxref("RTCPeerConnection.setLocalDescription")}}, and {{domxref("RTCPeerConnection.setRemoteDescription")}}. +- `type` (required): A string indicating the type of the session description. +- `sdp`: 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. -In essence, `RTCSessionDescriptionInit` and `RTCLocalSessionDescriptionInit` are defined as dictionaries, enabling users to provide necessary values without creating a full `RTCSessionDescription` object. Also, `RTCPeerConnection.setLocalDescription()` accepts `RTCLocalSessionDescriptionInit` as an argument, allowing users to omit this argument altogether. This eliminates the need for separate calls to `RTCPeerConnection.createOffer()` and `RTCPeerConnection.setLocalDescription()`. (For more information, see [Implicit description in RTCPeerConnection.setLocalDescription()](/en-US/docs/Web/API/RTCPeerConnection/setLocalDescription#implicit_description)). +For `setLocalDescription`, Web Specification uses `RTCLocalSessionDescriptionInit` dictionary, which is a subset of `RTCSessionDescriptionInit`. It has the same properties, but the `type` property is optional (explained in more detail in the [Implicit description in RTCPeerConnection.setLocalDescription()](/en-US/docs/Web/API/RTCPeerConnection/setLocalDescription#implicit_description)). + +For using in `setLocalDescription` and `setRemoteDescription` methods, creating an `RTCSessionDescription` also works, but it's not necessary. Some older examples may use this method, but such usage has no advantage over passing a dictionary directly to the method. + +```js +signalingChannel.onmessage = (evt) => { + if (!pc) start(false); + + const message = JSON.parse(evt.data); + if (message.type && message.sdp) { + // This line is changed not to use RTCSessionDescription constructor + pc.setRemoteDescription(message).then( + () => { + // if we received an offer, we need to answer + if (pc.remoteDescription.type === "offer") { + pc.createAnswer(localDescCreated, logError); + } + }, + logError, + ); + } else { + pc.addIceCandidate( + new RTCIceCandidate(message.candidate), + () => {}, + logError, + ); + } +}; +``` ## Specifications @@ -80,5 +108,3 @@ In essence, `RTCSessionDescriptionInit` and `RTCLocalSessionDescriptionInit` are - [WebRTC](/en-US/docs/Web/API/WebRTC_API) - {{domxref("RTCPeerConnection.setLocalDescription()")}} and {{domxref("RTCPeerConnection.setRemoteDescription()")}} -- {{domxref("RTCSessionDescriptionInit")}} -- {{domxref("RTCLocalSessionDescriptionInit")}} diff --git a/files/en-us/web/api/rtcsessiondescription/rtcsessiondescription/index.md b/files/en-us/web/api/rtcsessiondescription/rtcsessiondescription/index.md index 5ecb650a682b4eb..b0d5c4e2729e450 100644 --- a/files/en-us/web/api/rtcsessiondescription/rtcsessiondescription/index.md +++ b/files/en-us/web/api/rtcsessiondescription/rtcsessiondescription/index.md @@ -17,7 +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 -> {{domxref("RTCSessionDescriptionInit")}} dictionary, so you don't have to instantiate an +> [`RTCSessionDescriptionInit`](/en-US/docs/Web/API/RTCSessionDescription#rtcsessiondescriptioninit) dictionary, so you don't have to instantiate an > `RTCSessionDescription` yourself. ## Syntax @@ -31,7 +31,7 @@ new RTCSessionDescription(options) - `options` {{optional_inline}} - : An object providing the default values for the session description; the object - conforms to the {{domxref("RTCSessionDescriptionInit")}} dictionary. That dictionary has + conforms to the [`RTCSessionDescriptionInit`](/en-US/docs/Web/API/RTCSessionDescription#rtcsessiondescriptioninit) dictionary. That dictionary has the following properties: - `type` @@ -45,7 +45,7 @@ This example uses the constructor to convert an SDP offer into an `RTCSessionDescription` object. > **Note:** This is no longer necessary, however; -> {{domxref("RTCPeerConnection.setLocalDescription()")}} and other methods which take +> [`RTCSessionDescriptionInit`](/en-US/docs/Web/API/RTCSessionDescription#rtcsessiondescriptioninit) 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 > `RTCSessionDescription` yourself. diff --git a/files/en-us/web/api/rtcsessiondescriptioninit/index.md b/files/en-us/web/api/rtcsessiondescriptioninit/index.md deleted file mode 100644 index d74c16a75b8086d..000000000000000 --- a/files/en-us/web/api/rtcsessiondescriptioninit/index.md +++ /dev/null @@ -1,30 +0,0 @@ ---- -title: RTCSessionDescriptionInit -slug: Web/API/RTCSessionDescriptionInit -page-type: web-api-interface -browser-compat: api.RTCSessionDescription ---- - -{{APIRef("WebRTC")}} - -The **`RTCSessionDescriptionInit`** dictionary is used to provide {{Glossary("SDP")}} values in several methods of the {{domxref("RTCPeerConnection")}} interface, such as {{domxref("RTCPeerConnection.createOffer")}}, {{domxref("RTCPeerConnection.createAnswer")}}, and {{domxref("RTCPeerConnection.setRemoteDescription")}}. Also it can be used to create new `RTCSessionDescription` objects, though this is less common. - -### Properties - -- `type` - - : A string which is used to set the `type` property of the new `RTCSessionDescription` object. This is a required property. For more information, see documentation for the {{domxref("RTCSessionDescription.type")}} property. -- `sdp` - - : A string containing the {{Glossary("SDP")}} describing the session. If `type` is `"rollback"`, this member is unused. - -## Specifications - -https://w3c.github.io/webrtc-pc/#dom-rtcsessiondescriptioninit - -## See also - -- [WebRTC](/en-US/docs/Web/API/WebRTC_API) -- {{domxref("RTCSessionDescription")}} -- {{domxref("RTCLocalSessionDescriptionInit")}} -- {{domxref("RTCPeerConnection.createOffer")}} -- {{domxref("RTCPeerConnection.createAnswer")}} -- {{domxref("RTCPeerConnection.setRemoteDescription")}} From 3855b30b3d5fbe5b83e0dc3d13510cdacc518212 Mon Sep 17 00:00:00 2001 From: Byoungchan Lee Date: Sat, 8 Jun 2024 04:26:34 +0900 Subject: [PATCH 4/9] Update files/en-us/web/api/rtcsessiondescription/index.md Co-authored-by: github-actions[bot] <41898282+github-actions[bot]@users.noreply.github.com> --- .../en-us/web/api/rtcsessiondescription/index.md | 15 ++++++--------- 1 file changed, 6 insertions(+), 9 deletions(-) diff --git a/files/en-us/web/api/rtcsessiondescription/index.md b/files/en-us/web/api/rtcsessiondescription/index.md index 8f65ba7f71fee9c..3f47a669365b600 100644 --- a/files/en-us/web/api/rtcsessiondescription/index.md +++ b/files/en-us/web/api/rtcsessiondescription/index.md @@ -77,15 +77,12 @@ signalingChannel.onmessage = (evt) => { const message = JSON.parse(evt.data); if (message.type && message.sdp) { // This line is changed not to use RTCSessionDescription constructor - pc.setRemoteDescription(message).then( - () => { - // if we received an offer, we need to answer - if (pc.remoteDescription.type === "offer") { - pc.createAnswer(localDescCreated, logError); - } - }, - logError, - ); + pc.setRemoteDescription(message).then(() => { + // if we received an offer, we need to answer + if (pc.remoteDescription.type === "offer") { + pc.createAnswer(localDescCreated, logError); + } + }, logError); } else { pc.addIceCandidate( new RTCIceCandidate(message.candidate), From 615dc67952fa77520cde05af2ee26d4bd976c9c2 Mon Sep 17 00:00:00 2001 From: Joshua Chen Date: Sun, 22 Sep 2024 23:36:24 -0400 Subject: [PATCH 5/9] Update files/en-us/web/api/rtcsessiondescription/rtcsessiondescription/index.md --- .../api/rtcsessiondescription/rtcsessiondescription/index.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/files/en-us/web/api/rtcsessiondescription/rtcsessiondescription/index.md b/files/en-us/web/api/rtcsessiondescription/rtcsessiondescription/index.md index b0d5c4e2729e450..3a3e1ec1b9bc80b 100644 --- a/files/en-us/web/api/rtcsessiondescription/rtcsessiondescription/index.md +++ b/files/en-us/web/api/rtcsessiondescription/rtcsessiondescription/index.md @@ -45,7 +45,7 @@ This example uses the constructor to convert an SDP offer into an `RTCSessionDescription` object. > **Note:** This is no longer necessary, however; -> [`RTCSessionDescriptionInit`](/en-US/docs/Web/API/RTCSessionDescription#rtcsessiondescriptioninit) and other methods which take +> {{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 > `RTCSessionDescription` yourself. From d8388a96c1d3c5f52e4b3fcefbc3d35867cd3a74 Mon Sep 17 00:00:00 2001 From: Joshua Chen Date: Sun, 22 Sep 2024 23:41:49 -0400 Subject: [PATCH 6/9] Update --- .../setlocaldescription/index.md | 53 ++++++------------- 1 file changed, 16 insertions(+), 37 deletions(-) diff --git a/files/en-us/web/api/rtcpeerconnection/setlocaldescription/index.md b/files/en-us/web/api/rtcpeerconnection/setlocaldescription/index.md index 8c3d69012e8211b..b10c9263bc5fae7 100644 --- a/files/en-us/web/api/rtcpeerconnection/setlocaldescription/index.md +++ b/files/en-us/web/api/rtcpeerconnection/setlocaldescription/index.md @@ -28,46 +28,16 @@ setLocalDescription(sessionDescription, successCallback, errorCallback) // depre ### Parameters - `sessionDescription` {{optional_inline}} - - : An [`RTCLocalSessionDescriptionInit`](/en-US/docs/Web/API/RTCSessionDescription#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. - -> **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 `RTCLocalSessionDescriptionInit`, which is a serialized version of a {{domxref("RTCSessionDescription")}} browser object. They're interchangeable: - -```js -myPeerConnection - .createOffer() - .then((offer) => myPeerConnection.setLocalDescription(offer)); -``` + - : An object which specifies the configuration to be applied to the local end of the connection. It should contain the following properties: -This is equivalent to: + - `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. -```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. This is why 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. @@ -83,6 +53,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: From d45cee76616b568fb9f7f81d5196249d1d44a992 Mon Sep 17 00:00:00 2001 From: Joshua Chen Date: Sun, 22 Sep 2024 23:44:08 -0400 Subject: [PATCH 7/9] Update files/en-us/web/api/rtcpeerconnection/setlocaldescription/index.md Co-authored-by: github-actions[bot] <41898282+github-actions[bot]@users.noreply.github.com> --- .../en-us/web/api/rtcpeerconnection/setlocaldescription/index.md | 1 + 1 file changed, 1 insertion(+) diff --git a/files/en-us/web/api/rtcpeerconnection/setlocaldescription/index.md b/files/en-us/web/api/rtcpeerconnection/setlocaldescription/index.md index b10c9263bc5fae7..eb8ffbc274aba3f 100644 --- a/files/en-us/web/api/rtcpeerconnection/setlocaldescription/index.md +++ b/files/en-us/web/api/rtcpeerconnection/setlocaldescription/index.md @@ -28,6 +28,7 @@ setLocalDescription(sessionDescription, successCallback, errorCallback) // depre ### Parameters - `sessionDescription` {{optional_inline}} + - : An object which specifies the configuration to be applied to the local end of the connection. It should contain the following properties: - `type` {{optional_inline}} From fdc2e92cb9d2484f9c2631b20b549827577118c8 Mon Sep 17 00:00:00 2001 From: Joshua Chen Date: Sun, 22 Sep 2024 23:45:56 -0400 Subject: [PATCH 8/9] Fix --- .../web/api/rtcpeerconnection/setlocaldescription/index.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/files/en-us/web/api/rtcpeerconnection/setlocaldescription/index.md b/files/en-us/web/api/rtcpeerconnection/setlocaldescription/index.md index eb8ffbc274aba3f..e7d48c2d9ca8054 100644 --- a/files/en-us/web/api/rtcpeerconnection/setlocaldescription/index.md +++ b/files/en-us/web/api/rtcpeerconnection/setlocaldescription/index.md @@ -70,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 [`RTCLocalSessionDescriptionInit`](/en-US/docs/Web/API/RTCSessionDescription#rtcsessiondescriptioninit) specified by the `sessionDescription` parameter is invalid. + - : Thrown if the `sessionDescription` parameter is invalid. ## Examples From 6d20474e70d0508a8855b0881aae36552e4295dc Mon Sep 17 00:00:00 2001 From: Joshua Chen Date: Mon, 23 Sep 2024 00:03:04 -0400 Subject: [PATCH 9/9] Fix others --- .../rtcpeerconnection/createanswer/index.md | 7 +- .../rtcpeerconnection/createoffer/index.md | 12 +-- .../setlocaldescription/index.md | 2 +- .../setremotedescription/index.md | 80 +++++++------------ .../web/api/rtcsessiondescription/index.md | 43 ++-------- .../rtcsessiondescription/index.md | 18 ++--- 6 files changed, 54 insertions(+), 108 deletions(-) diff --git a/files/en-us/web/api/rtcpeerconnection/createanswer/index.md b/files/en-us/web/api/rtcpeerconnection/createanswer/index.md index 3dd103f9a8af3ba..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 [`RTCSessionDescriptionInit`](/en-US/docs/Web/API/RTCSessionDescription#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 0bfd9b7618b07bd..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#rtcsessiondescriptioninit) 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#rtcsessiondescriptioninit) 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#rtcsessiondescriptioninit) 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 e7d48c2d9ca8054..c32a24d50867aed 100644 --- a/files/en-us/web/api/rtcpeerconnection/setlocaldescription/index.md +++ b/files/en-us/web/api/rtcpeerconnection/setlocaldescription/index.md @@ -38,7 +38,7 @@ setLocalDescription(sessionDescription, successCallback, errorCallback) // depre If the description is omitted, the WebRTC runtime tries to automatically do the right thing. - You can also pass an actual {{domxref("RTCSessionDescription")}} instance, but there's no difference. This is why the `RTCSessionDescription` constructor is deprecated. + 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. diff --git a/files/en-us/web/api/rtcpeerconnection/setremotedescription/index.md b/files/en-us/web/api/rtcpeerconnection/setremotedescription/index.md index 870990afbc96b6c..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 [`RTCSessionDescriptionInit`](/en-US/docs/Web/API/RTCSessionDescription#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 [`RTCSessionDescriptionInit`](/en-US/docs/Web/API/RTCSessionDescription#rtcsessiondescriptioninit) specified by the `sessionDescription` parameter is invalid. - ## Examples Here we see a function which handles an offer received from the remote peer. diff --git a/files/en-us/web/api/rtcsessiondescription/index.md b/files/en-us/web/api/rtcsessiondescription/index.md index 3f47a669365b600..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`](#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. @@ -57,42 +60,6 @@ signalingChannel.onmessage = (evt) => { }; ``` -## RTCSessionDescriptionInit - -`RTCSessionDescriptionInit` is a dictionary that holds same properties to `RTCSessionDescription`. It's used as an argument for the {{domxref("RTCPeerConnection.setLocalDescription")}}, and {{domxref("RTCPeerConnection.setRemoteDescription")}} methods, and a return value from the {{domxref("RTCPeerConnection.createOffer")}}, and {{domxref("RTCPeerConnection.createAnswer")}} methods. - -The `RTCSessionDescriptionInit` dictionary has the following properties: - -- `type` (required): A string indicating the type of the session description. -- `sdp`: 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. - -For `setLocalDescription`, Web Specification uses `RTCLocalSessionDescriptionInit` dictionary, which is a subset of `RTCSessionDescriptionInit`. It has the same properties, but the `type` property is optional (explained in more detail in the [Implicit description in RTCPeerConnection.setLocalDescription()](/en-US/docs/Web/API/RTCPeerConnection/setLocalDescription#implicit_description)). - -For using in `setLocalDescription` and `setRemoteDescription` methods, creating an `RTCSessionDescription` also works, but it's not necessary. Some older examples may use this method, but such usage has no advantage over passing a dictionary directly to the method. - -```js -signalingChannel.onmessage = (evt) => { - if (!pc) start(false); - - const message = JSON.parse(evt.data); - if (message.type && message.sdp) { - // This line is changed not to use RTCSessionDescription constructor - pc.setRemoteDescription(message).then(() => { - // if we received an offer, we need to answer - if (pc.remoteDescription.type === "offer") { - pc.createAnswer(localDescCreated, logError); - } - }, logError); - } else { - pc.addIceCandidate( - new RTCIceCandidate(message.candidate), - () => {}, - logError, - ); - } -}; -``` - ## Specifications {{Specifications}} diff --git a/files/en-us/web/api/rtcsessiondescription/rtcsessiondescription/index.md b/files/en-us/web/api/rtcsessiondescription/rtcsessiondescription/index.md index b3a97ebaa0a4a5e..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`](/en-US/docs/Web/API/RTCSessionDescription#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`](/en-US/docs/Web/API/RTCSessionDescription#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