Adapt RTCDataChannel API to new events structure (#13894)

* Adapt RTCDataChannel API to new events structure This PR adapts the RTCDataChannel API to conform to the new events structure. * Fix up links * Apply suggestions from code review Co-authored-by: Joe Medley <[email protected]> * Apply suggestions from code review Co-authored-by: Joe Medley <[email protected]> Co-authored-by: Florian Scholz <[email protected]>
mdn · Mar 23, 2022 · 34b5c4c · 34b5c4c
1 parent d2ebfea
commit 34b5c4c
Show file tree

Hide file tree

Showing 21 changed files with 155 additions and 621 deletions.
diff --git a/files/en-us/_redirects.txt b/files/en-us/_redirects.txt
@@ -9040,13 +9040,19 @@
 /en-US/docs/Web/API/RTCDataChannel.close	/en-US/docs/Web/API/RTCDataChannel/close
 /en-US/docs/Web/API/RTCDataChannel.id	/en-US/docs/Web/API/RTCDataChannel/id
 /en-US/docs/Web/API/RTCDataChannel.label	/en-US/docs/Web/API/RTCDataChannel/label
-/en-US/docs/Web/API/RTCDataChannel.onclose	/en-US/docs/Web/API/RTCDataChannel/onclose
-/en-US/docs/Web/API/RTCDataChannel.onerror	/en-US/docs/Web/API/RTCDataChannel/onerror
-/en-US/docs/Web/API/RTCDataChannel.onmessage	/en-US/docs/Web/API/RTCDataChannel/onmessage
-/en-US/docs/Web/API/RTCDataChannel.onopen	/en-US/docs/Web/API/RTCDataChannel/onopen
+/en-US/docs/Web/API/RTCDataChannel.onclose	/en-US/docs/Web/API/RTCDataChannel/close_event
+/en-US/docs/Web/API/RTCDataChannel.onerror	/en-US/docs/Web/API/RTCDataChannel/error_event
+/en-US/docs/Web/API/RTCDataChannel.onmessage	/en-US/docs/Web/API/RTCDataChannel/message_event
+/en-US/docs/Web/API/RTCDataChannel.onopen	/en-US/docs/Web/API/RTCDataChannel/open_event
 /en-US/docs/Web/API/RTCDataChannel.ordered	/en-US/docs/Web/API/RTCDataChannel/ordered
 /en-US/docs/Web/API/RTCDataChannel.protocol	/en-US/docs/Web/API/RTCDataChannel/protocol
 /en-US/docs/Web/API/RTCDataChannel.readyState	/en-US/docs/Web/API/RTCDataChannel/readyState
+/en-US/docs/Web/API/RTCDataChannel/onbufferedamountlow	/en-US/docs/Web/API/RTCDataChannel/bufferedamountlow_event
+/en-US/docs/Web/API/RTCDataChannel/onclose	/en-US/docs/Web/API/RTCDataChannel/close_event
+/en-US/docs/Web/API/RTCDataChannel/onclosing	/en-US/docs/Web/API/RTCDataChannel/closing_event
+/en-US/docs/Web/API/RTCDataChannel/onerror	/en-US/docs/Web/API/RTCDataChannel/error_event
+/en-US/docs/Web/API/RTCDataChannel/onmessage	/en-US/docs/Web/API/RTCDataChannel/message_event
+/en-US/docs/Web/API/RTCDataChannel/onopen	/en-US/docs/Web/API/RTCDataChannel/open_event
 /en-US/docs/Web/API/RTCDataChannelEvent.RTCDataChannelEvent	/en-US/docs/Web/API/RTCDataChannelEvent/RTCDataChannelEvent
 /en-US/docs/Web/API/RTCDataChannelEvent.channel	/en-US/docs/Web/API/RTCDataChannelEvent/channel
 /en-US/docs/Web/API/RTCIceCandidate/RTCIceCandidate.address	/en-US/docs/Web/API/RTCIceCandidate/address

diff --git a/files/en-us/_wikihistory.json b/files/en-us/_wikihistory.json
@@ -66009,60 +66009,6 @@
       "jpmedley"
     ]
   },
-  "Web/API/RTCDataChannel/onbufferedamountlow": {
-    "modified": "2020-12-10T14:54:31.667Z",
-    "contributors": [
-      "bershanskiy",
-      "kdxu",
-      "fscholz",
-      "jpmedley",
-      "Sheppy",
-      "rolfedh"
-    ]
-  },
-  "Web/API/RTCDataChannel/onclose": {
-    "modified": "2020-10-15T21:29:06.143Z",
-    "contributors": [
-      "fscholz",
-      "jpmedley",
-      "Sheppy",
-      "teoli"
-    ]
-  },
-  "Web/API/RTCDataChannel/onclosing": {
-    "modified": "2020-10-15T22:28:18.800Z",
-    "contributors": [
-      "bershanskiy"
-    ]
-  },
-  "Web/API/RTCDataChannel/onerror": {
-    "modified": "2020-10-15T21:29:06.359Z",
-    "contributors": [
-      "fscholz",
-      "jpmedley",
-      "Sheppy",
-      "teoli"
-    ]
-  },
-  "Web/API/RTCDataChannel/onmessage": {
-    "modified": "2020-10-15T21:29:06.158Z",
-    "contributors": [
-      "fscholz",
-      "joerlo",
-      "jpmedley",
-      "Sheppy",
-      "teoli"
-    ]
-  },
-  "Web/API/RTCDataChannel/onopen": {
-    "modified": "2020-10-15T21:29:06.165Z",
-    "contributors": [
-      "fscholz",
-      "jpmedley",
-      "Sheppy",
-      "teoli"
-    ]
-  },
   "Web/API/RTCDataChannel/open_event": {
     "modified": "2020-10-15T22:15:06.409Z",
     "contributors": [

diff --git a/files/en-us/mozilla/firefox/releases/44/index.md b/files/en-us/mozilla/firefox/releases/44/index.md
@@ -148,7 +148,7 @@ Highlights:
   - `mozRTCIceCandidate` is now {{domxref("RTCIceCandidate")}}.
   - `mozRTCSessionDescription` is now {{domxref("RTCSessionDescription")}}.
 
-- The {{domxref("RTCDataChannel.bufferedAmountLowThreshold")}} and {{domxref("RTCDataChannel.onbufferedamountlow")}} properties, as well as the {{event("bufferedamountlow")}} event, have been implemented ({{bug(1178091)}}).
+- The {{domxref("RTCDataChannel.bufferedAmountLowThreshold")}} property, as well as the {{event("bufferedamountlow")}} event and its event handler, have been implemented ({{bug(1178091)}}).
 - The attribute {{domxref("RTCPeerConnection.canTrickleIceCandidates")}} has been added, the non-standard method {{domxref("RTCPeerConnection.updateIce()")}} removed ({{bug(1209744)}}).
 - The {{domxref("MediaStream")}} interface now supports the {{domxref("MediaStream.addTrack()")}} and {{domxref("MediaStream.removeTrack()")}} methods ({{bug(1103188)}}).
 - The constructor {{domxref("MediaStream.MediaStream", "MediaStream()")}} has been implemented ({{bug(1070216)}}).

diff --git a/files/en-us/web/api/messageevent/index.md b/files/en-us/web/api/messageevent/index.md
@@ -24,7 +24,7 @@ This is used to represent messages in:
 - [Channel messaging](/en-US/docs/Web/API/Channel_Messaging_API) (see {{domxref("MessagePort.postMessage()")}} and {{domxref("MessagePort.onmessage")}}).
 - Cross-worker/document messaging (see the above two entries, but also {{domxref("Worker.postMessage()")}}, {{domxref("Worker.onmessage")}}, {{domxref("ServiceWorkerGlobalScope.onmessage")}}, etc.)
 - [Broadcast channels](/en-US/docs/Web/API/Broadcast_Channel_API) (see {{domxref("Broadcastchannel.postMessage()")}}) and {{domxref("BroadcastChannel.onmessage")}}).
-- WebRTC data channels (see {{domxref("RTCDataChannel.onmessage")}}).
+- WebRTC data channels (see {{domxref("RTCDataChannel.message_event", "onmessage")}}).
 
 The action triggered by this event is defined in a function set as the event handler for the relevant {{event("message")}} event (e.g. using an `onmessage` handler as listed above).
 

diff --git a/files/en-us/web/api/rtcdatachannel/bufferedamount/index.md b/files/en-us/web/api/rtcdatachannel/bufferedamount/index.md
@@ -79,4 +79,3 @@ function showBufferedAmount(channel) {
 - {{domxref("RTCDataChannel")}}
 - {{domxref("RTCDataChannel.bufferedAmountLowThreshold")}}
 - {{DOMxRef("RTCDataChannel.bufferedamountlow_event", "bufferedamountlow")}} event
-- {{domxref("RTCDataChannel.onbufferedamountlow")}}
diff --git a/files/en-us/web/api/rtcdatachannel/bufferedamountlow_event/index.md b/files/en-us/web/api/rtcdatachannel/bufferedamountlow_event/index.md
@@ -22,28 +22,21 @@ browser-compat: api.RTCDataChannel.bufferedamountlow_event
 
 A **`bufferedamountlow`** event is sent to an {{domxref("RTCDataChannel")}} when the number of bytes currently in the outbound data transfer buffer falls below the threshold specified in {{domxref("RTCDataChannel.bufferedAmountLowThreshold", "bufferedAmountLowThreshold")}}. `bufferedamountlow` events aren't sent if `bufferedAmountLowThreshold` is 0.
 
-<table class="properties">
-  <tbody>
-    <tr>
-      <th scope="row">Bubbles</th>
-      <td>No</td>
-    </tr>
-    <tr>
-      <th scope="row">Cancelable</th>
-      <td>No</td>
-    </tr>
-    <tr>
-      <th scope="row">Interface</th>
-      <td>{{DOMxRef("Event")}}</td>
-    </tr>
-    <tr>
-      <th scope="row">Event handler property</th>
-      <td>
-        {{DOMxRef("RTCDataChannel.onbufferedamountlow", "onbufferedamountlow")}}
-      </td>
-    </tr>
-  </tbody>
-</table>
+This event is not cancelable and does not bubble.
+
+## Syntax
+
+Use the event name in methods like {{domxref("EventTarget.addEventListener", "addEventListener()")}}, or set an event handler property.
+
+```js
+addEventListener('bufferedamountlow', event => { });
+
+onbufferedamountlow = event => { };
+```
+
+## Event type
+
+A generic {{domxref("Event")}}.
 
 ## Examples
 
@@ -65,7 +58,7 @@ pc.addEventListener("bufferedamountlow", ev => {
 
 After creating the `RTCPeerConnection`, this calls {{domxref("RTCPeerConnection.createDataChannel()")}} to create the data channel. Then a listener is created for `bufferedamountlow` to refill the incoming data buffer any time its contents fall below 65536 bytes.
 
-You can also set up a listener for `bufferedamountlow` using its event handler property, {{domxref("RTCDataChannel.onbufferedamountlow", "onbufferedamountlow")}}:
+You can also set up a listener for `bufferedamountlow` using its event handler property, {{domxref("RTCDataChannel.bufferedamountlow_event", "onbufferedamountlow")}}:
 
 ```js
 pc.onbufferedamountlow = ev => {
@@ -87,5 +80,4 @@ pc.onbufferedamountlow = ev => {
 
 - [WebRTC API](/en-US/docs/Web/API/WebRTC_API)
 - {{domxref("RTCDataChannel")}}
-- {{domxref("RTCDataChannel.onbufferedamountlow")}}
 - {{domxref("RTCDataChannel.bufferedAmountLowThreshold")}}
diff --git a/files/en-us/web/api/rtcdatachannel/bufferedamountlowthreshold/index.md b/files/en-us/web/api/rtcdatachannel/bufferedamountlowthreshold/index.md
@@ -19,7 +19,7 @@ of bytes of buffered outgoing data that is considered "low." The default value i
 below this value, a {{DOMxRef("RTCDataChannel.bufferedamountlow_event", "bufferedamountlow")}} event is fired. This event may be
 used, for example, to implement code which queues more messages to be sent whenever
 there's room to buffer them. Listeners may be added with
-{{domxref("RTCDataChannel.onbufferedamountlow", "onbufferedamountlow")}} or
+{{domxref("RTCDataChannel.bufferedamountlow_event", "onbufferedamountlow")}} or
 {{domxref("EventTarget.addEventListener", "addEventListener()")}}.
 
 The user agent may implement the process of actually sending data in any way it
@@ -45,7 +45,7 @@ The number of queued outgoing data bytes below which the buffer is considered to
 
 In this snippet of code, `bufferedAmountLowThreshold` is set to 64kB, and a
 handler for the {{DOMxRef("RTCDataChannel.bufferedamountlow_event", "bufferedamountlow")}} event is established by setting the
-{{domxref("RTCDataChannel.onbufferedamountlow")}} property to a function which should
+{{domxref("RTCDataChannel.bufferedamountlow_event", "onbufferedamountlow")}} property to a function which should
 send more data into the buffer by calling {{domxref("RTCDataChannel.send", "send()")}}.
 
 ```js
@@ -73,4 +73,3 @@ dc.onbufferedamountlow = function() {
 - {{domxref("RTCDataChannel")}}
 - {{domxref("RTCDataChannel.bufferedAmount")}}
 - {{DOMxRef("RTCDataChannel.bufferedamountlow_event", "bufferedamountlow")}} event
-- {{domxref("RTCDataChannel.onbufferedamountlow")}}
diff --git a/files/en-us/web/api/rtcdatachannel/close_event/index.md b/files/en-us/web/api/rtcdatachannel/close_event/index.md
@@ -19,28 +19,23 @@ browser-compat: api.RTCDataChannel.close_event
 ---
 {{APIRef("WebRTC")}}
 
-The **`close`** event is sent to the {{domxref("RTCDataChannel.onclose", "onclose")}} event handler on an {{domxref("RTCDataChannel")}} instance when the data transport being used for the data channel has closed. Before any further data can be transferred using `RTCDataChannel`, a new data channel instance must be created.
-
-<table class="properties">
-  <tbody>
-    <tr>
-      <th scope="row">Bubbles</th>
-      <td>No</td>
-    </tr>
-    <tr>
-      <th scope="row">Cancelable</th>
-      <td>No</td>
-    </tr>
-    <tr>
-      <th scope="row">Interface</th>
-      <td>{{domxref("Event")}}</td>
-    </tr>
-    <tr>
-      <th scope="row">Event handler property</th>
-      <td>{{domxref("RTCDataChannel.onclose")}}</td>
-    </tr>
-  </tbody>
-</table>
+The **`close`** event is sent to the {{domxref("RTCDataChannel.close_event", "onclose")}} event handler on an {{domxref("RTCDataChannel")}} instance when the data transport for the data channel has closed. Before any further data can be transferred using `RTCDataChannel`, a new 'RTCDataChannel' instance must be created.
+
+This event is not cancelable and does not bubble.
+
+## Syntax
+
+Use the event name in methods like {{domxref("EventTarget.addEventListener", "addEventListener()")}}, or set an event handler property.
+
+```js
+addEventListener('close', event => { });
+
+onclose = event => { };
+```
+
+## Event type
+
+A generic {{domxref("Event")}}.
 
 ## Examples
 
@@ -57,7 +52,7 @@ dc.addEventListener("close", ev => {
 
 All this code does in response to receiving the `close` event is to disable an input box and its "Send" button, and to enable the button used to start a call (while disabling the one that ends a call).
 
-You can also use the {{domxref("RTCDataChannel.onclose", "onclose")}} event handler property to set a handler for `close` events:
+You can also use the {{domxref("RTCDataChannel.close_event", "onclose")}} event handler property to set a handler for `close` events:
 
 ```js
 dc.onclose = ev => {

diff --git a/files/en-us/web/api/rtcdatachannel/closing_event/index.md b/files/en-us/web/api/rtcdatachannel/closing_event/index.md
@@ -22,26 +22,21 @@ browser-compat: api.RTCDataChannel.closing_event
 
 The **`closing`** event is sent to an {{domxref("RTCDataChannel")}} just before the channel begins the process of shutting down its underlying data transport.
 
-<table class="properties">
-  <tbody>
-    <tr>
-      <th scope="row">Bubbles</th>
-      <td>No</td>
-    </tr>
-    <tr>
-      <th scope="row">Cancelable</th>
-      <td>No</td>
-    </tr>
-    <tr>
-      <th scope="row">Interface</th>
-      <td>{{DOMxRef("Event")}}</td>
-    </tr>
-    <tr>
-      <th scope="row">Event handler property</th>
-      <td>{{DOMxRef("RTCDataChannel.onclosing")}}</td>
-    </tr>
-  </tbody>
-</table>
+This event is not cancelable and does not bubble.
+
+## Syntax
+
+Use the event name in methods like {{domxref("EventTarget.addEventListener", "addEventListener()")}}, or set an event handler property.
+
+```js
+addEventListener('bufferedamountlow', event => { });
+
+onbufferedamountlow = event => { };
+```
+
+## Event type
+
+A generic {{domxref("Event")}}.
 
 ## Description
 
@@ -60,7 +55,7 @@ dataChannel.addEventListener("closing", ev => {
 });
 ```
 
-You can also set the {{domxref("RTCDataChannel.onclosing", "onclosing")}} event handler property directly:
+You can also set the {{domxref("RTCDataChannel.closing_event", "onclosing")}} event handler property directly:
 
 ```js
 pc.onclosing = ev => {

diff --git a/files/en-us/web/api/rtcdatachannel/error_event/index.md b/files/en-us/web/api/rtcdatachannel/error_event/index.md
@@ -21,31 +21,35 @@ browser-compat: api.RTCDataChannel.error_event
 ---
 {{APIRef("WebRTC")}}
 
-A WebRTC {{domxref("RTCDataChannel.error_event", "error")}} event is sent to an {{domxref("RTCDataChannel")}} object's {{domxref("RTCDataChannel.onerror", "onerror")}} error handler when an error occurs on the data channel.
-
-<table class="properties">
-  <tbody>
-    <tr>
-      <th scope="row">Bubbles</th>
-      <td>Yes</td>
-    </tr>
-    <tr>
-      <th scope="row">Cancelable</th>
-      <td>No</td>
-    </tr>
-    <tr>
-      <th scope="row">Interface</th>
-      <td>{{DOMxRef("RTCErrorEvent")}}</td>
-    </tr>
-    <tr>
-      <th scope="row">Event handler property</th>
-      <td>{{DOMxRef("RTCDataChannel.onerror", "onerror")}}</td>
-    </tr>
-  </tbody>
-</table>
+A WebRTC {{domxref("RTCDataChannel.error_event", "error")}} event is sent to an {{domxref("RTCDataChannel")}} object's `onerror` event handler when an error occurs on the data channel.
 
 The {{domxref("RTCErrorEvent")}} object provides details about the error that occurred; see that article for details.
 
+This event is not cancelable and does not bubble.
+
+## Syntax
+
+Use the event name in methods like {{domxref("EventTarget.addEventListener", "addEventListener()")}}, or set an event handler property.
+
+```js
+addEventListener('error', event => { });
+
+onerror = event => { };
+```
+
+## Event type
+
+An {{domxref("RTCErrorEvent")}}. Inherits from {{domxref("Event")}}.
+
+{{InheritanceDiagram("RTCErrorEvent")}}
+
+## Event properties
+
+_In addition to the properties listed below, properties from the parent interface, {{domxref("Event")}}, are available._
+
+- {{domxref("RTCErrorEvent.error", "error")}} {{ReadOnlyInline}}
+  - : An {{domxref("RTCError")}} object specifying the error which occurred; this object includes the type of error that occurred, and information about where the error occurred (such as which line number in the {{Glossary("SDP")}} or what {{Glossary("SCTP")}} cause code was at issue).
+
 ## Examples
 
 ```js
@@ -115,7 +119,7 @@ Error information is output to the console using {{domxref("console.error()")}}.
 
 In addition, however, depending on the value of {{domxref("RTCError.errorDetail", "errorDetail")}}, additional information may be output. Each error type has a different set of information output. For example, an SDP syntax error displays the line number of the error within the SDP, and an SCTP error displays a message corresponding to the SCTP cause code. Other error types similarly output appropriate information.
 
-You can also set up an event handler for `error` events using the `RTCDataChannel` interface's {{domxref("RTCDataChannel.onerror", "onerror")}} event handler property:
+You can also set up an event handler for `error` events using the `RTCDataChannel` interface's {{domxref("RTCDataChannel.error_event", "onerror")}} event handler property:
 
 ```js
 dc.onerror = ev => {