From 21d59fe5b5322f33f0a4810fa0836fd3f2edaa43 Mon Sep 17 00:00:00 2001 From: Jan-Ivar Bruaroey <jan-ivar@users.noreply.github.com> Date: Mon, 21 Aug 2023 15:39:12 -0400 Subject: [PATCH 01/10] Fire icecandidate, gatheringstatechange, icegatheringstatechange & icecandidate events in same task. --- webrtc.html | 102 +++++++++++++++++++++++++++++++++++++--------------- 1 file changed, 73 insertions(+), 29 deletions(-) diff --git a/webrtc.html b/webrtc.html index d2e3a06f2..74ab4fd2d 100644 --- a/webrtc.html +++ b/webrtc.html @@ -11898,14 +11898,14 @@ <h3> </div> <p> When the [= ICE Agent =] indicates that it began gathering a [= - generation =] of candidates for an {{RTCIceTransport}}, the user + generation =] of candidates for an {{RTCIceTransport}} <var>transport</var>, the user agent MUST queue a task that runs the following steps: </p> <ol class=algorithm> <li class="no-test-needed"> <p> Let <var>connection</var> be the {{RTCPeerConnection}} object - associated with this [= ICE Agent =]. + associated with <var>transport</var>. </p> </li> <li> @@ -11914,33 +11914,47 @@ <h3> <code>true</code>, abort these steps. </p> </li> - <li class="no-test-needed"> + <li> <p> - Let <var>transport</var> be the {{RTCIceTransport}} for which - candidate gathering began. + Set <var>transport</var>.{{RTCIceTransport/[[IceGathererState]]}} to + {{RTCIceGathererState/gathering}}. </p> </li> <li> <p> - Set <var>transport</var>.{{RTCIceTransport/[[IceGathererState]]}} to - {{RTCIceGathererState/gathering}}. + Set <var>connection</var>.{{RTCPeerConnection/[[IceGatheringState]]}} + to the value of deriving a new state value as described by the + {{RTCIceGatheringState}} enum. </p> </li> + <li> + <p> + Let <var>connectionIceGatheringStateChanged</var> be + <code>true</code> if + <var>connection</var>.{{RTCPeerConnection/[[IceGatheringState]]}} + changed in the previous step, otherwise <code>false</code>. + </p> + </li> + <li> + <p>Do not read or modify state beyond this point.</p> + </li> <li> <p> [= Fire an event =] named {{RTCIceTransport/gatheringstatechange}} at <var>transport</var>. </p> </li> - <li class="needs-test"> + <li data-tests="protocol/candidate-exchange.https.html"> <p> - <a>Update the ICE gathering state</a> of <var>connection</var>. + If <var>connectionIceGatheringStateChanged</var> is + <code>true</code>, [= fire an event =] named + {{RTCPeerConnection/icegatheringstatechange}} at <var>connection</var>. </p> </li> </ol> <p> When the [= ICE Agent =] is finished gathering a [= generation =] of - candidates for an {{RTCIceTransport}}, and those candidates have been + candidates for an {{RTCIceTransport}} <var>transport</var>, and those candidates have been surfaced to the application, the user agent MUST queue a task that runs the following steps: </p> @@ -11948,7 +11962,7 @@ <h3> <li class="no-test-needed"> <p> Let <var>connection</var> be the {{RTCPeerConnection}} object - associated with this [= ICE Agent =]. + associated with <var>transport</var>. </p> </li> <li> @@ -11957,15 +11971,9 @@ <h3> <code>true</code>, abort these steps. </p> </li> - <li class="no-test-needed"> - <p> - Let <var>transport</var> be the {{RTCIceTransport}} for which - candidate gathering finished. - </p> - </li> <li> <p> - Let <var>newCandidate</var> be the result of [= creating an + Let <var>emptyCandidate</var> be the result of [= creating an RTCIceCandidate =] with a new dictionary whose {{RTCIceCandidateInit/sdpMid}} and {{RTCIceCandidateInit/sdpMLineIndex}} are set to the values @@ -11976,18 +11984,13 @@ <h3> to an empty string. </p> </li> - <li> - <p> - [= Fire an event =] named {{RTCPeerConnection/icecandidate}} using the - {{RTCPeerConnectionIceEvent}} interface with the candidate - attribute set to <var>newCandidate</var> at - <var>connection</var>. - </p> - </li> <li> <p> If another [= generation =] of candidates is still being - gathered, abort these steps. + gathered, [= fire an event =] named {{RTCPeerConnection/icecandidate}} using the + {{RTCPeerConnectionIceEvent}} interface with the candidate + attribute set to <var>emptyCandidate</var> at + <var>connection</var>, and abort these steps. </p> <div class="note"> This may occur if an ICE restart is initiated while the ICE agent @@ -12000,17 +12003,58 @@ <h3> {{RTCIceGathererState/complete}}. </p> </li> + <li> + <p> + Set <var>connection</var>.{{RTCPeerConnection/[[IceGatheringState]]}} + to the value of deriving a new state value as described by the + {{RTCIceGatheringState}} enum. + </p> + </li> + <li> + <p> + Let <var>connectionIceGatheringStateChanged</var> be + <code>true</code> if + <var>connection</var>.{{RTCPeerConnection/[[IceGatheringState]]}} + changed in the previous step, otherwise <code>false</code>. + </p> + </li> + <li> + <p>Do not read or modify state beyond this point.</p> + </li> + <li> + <p> + [= Fire an event =] named {{RTCPeerConnection/icecandidate}} using the + {{RTCPeerConnectionIceEvent}} interface with the candidate + attribute set to <var>emptyCandidate</var> at + <var>connection</var>. + </p> + </li> <li> <p> [= Fire an event =] named {{RTCIceTransport/gatheringstatechange}} at <var>transport</var>. </p> </li> - <li> + <li data-tests="protocol/candidate-exchange.https.html"> <p> - <a>Update the ICE gathering state</a> of <var>connection</var>. + If <var>connectionIceGatheringStateChanged</var> is + <code>true</code>, [= fire an event =] named + {{RTCPeerConnection/icegatheringstatechange}} at <var>connection</var>. </p> </li> + <li data-tests="RTCPeerConnection-iceGatheringState.html"> + <p> + [= Fire an event =] + named {{RTCPeerConnection/icecandidate}} using the + {{RTCPeerConnectionIceEvent}} interface with the candidate + attribute set to <code>null</code> at <var>connection</var>. + </p> + <div class="note"> + The null candidate event is fired to ensure legacy + compatibility. New code should monitor the gathering state of + {{RTCIceTransport}} and/or {{RTCPeerConnection}}. + </div> + </li> </ol> <p> When the [= ICE Agent =] indicates that a new ICE candidate is From e975f6c41895593192936c0a44dee173f2a8f54a Mon Sep 17 00:00:00 2001 From: Jan-Ivar Bruaroey <jan-ivar@users.noreply.github.com> Date: Mon, 21 Aug 2023 16:59:38 -0400 Subject: [PATCH 02/10] Queue two tasks upon finishing ICE gathering. --- webrtc.html | 59 +++++++++++++++++++++++++---------------------------- 1 file changed, 28 insertions(+), 31 deletions(-) diff --git a/webrtc.html b/webrtc.html index 74ab4fd2d..ebbaa62be 100644 --- a/webrtc.html +++ b/webrtc.html @@ -11898,16 +11898,11 @@ <h3> </div> <p> When the [= ICE Agent =] indicates that it began gathering a [= - generation =] of candidates for an {{RTCIceTransport}} <var>transport</var>, the user + generation =] of candidates for an {{RTCIceTransport}} <var>transport</var> + associated with an {{RTCPeerConnection}} <var>connection</var>, the user agent MUST queue a task that runs the following steps: </p> <ol class=algorithm> - <li class="no-test-needed"> - <p> - Let <var>connection</var> be the {{RTCPeerConnection}} object - associated with <var>transport</var>. - </p> - </li> <li> <p> If <var>connection</var>.{{RTCPeerConnection/[[IsClosed]]}} is @@ -11954,17 +11949,12 @@ <h3> </ol> <p> When the [= ICE Agent =] is finished gathering a [= generation =] of - candidates for an {{RTCIceTransport}} <var>transport</var>, and those candidates have been - surfaced to the application, the user agent MUST queue a task that - runs the following steps: + candidates for an {{RTCIceTransport}} <var>transport</var> associated + with an {{RTCPeerConnection}} <var>connection</var>, and those candidates have been + surfaced to the application, the user agent MUST queue two tasks. + The first task MUST run the following steps: </p> <ol class=algorithm> - <li class="no-test-needed"> - <p> - Let <var>connection</var> be the {{RTCPeerConnection}} object - associated with <var>transport</var>. - </p> - </li> <li> <p> If <var>connection</var>.{{RTCPeerConnection/[[IsClosed]]}} is @@ -11973,24 +11963,39 @@ <h3> </li> <li> <p> - Let <var>emptyCandidate</var> be the result of [= creating an + Let <var>endOfGatheringCandidate</var> be the result of [= creating an RTCIceCandidate =] with a new dictionary whose {{RTCIceCandidateInit/sdpMid}} and {{RTCIceCandidateInit/sdpMLineIndex}} are set to the values associated with this {{RTCIceTransport}}, {{RTCIceCandidateInit/usernameFragment}} is set to the username fragment of the [= generation =] of candidates for which - gathering finished, and {{RTCIceCandidateInit/candidate}} is set - to an empty string. + gathering finished, and {{RTCIceCandidateInit/candidate}} is set to `""`. </p> </li> <li> <p> - If another [= generation =] of candidates is still being - gathered, [= fire an event =] named {{RTCPeerConnection/icecandidate}} using the + [= Fire an event =] named {{RTCPeerConnection/icecandidate}} using the {{RTCPeerConnectionIceEvent}} interface with the candidate - attribute set to <var>emptyCandidate</var> at - <var>connection</var>, and abort these steps. + attribute set to <var>endOfGatheringCandidate</var> at + <var>connection</var>. + </p> + </li> + </ol> + <p> + The second task MUST run the following steps: + </p> + <ol class=algorithm> + <li> + <p> + If <var>connection</var>.{{RTCPeerConnection/[[IsClosed]]}} is + <code>true</code>, abort these steps. + </p> + </li> + <li> + <p> + If another [= generation =] of candidates is still being + gathered, abort these steps. </p> <div class="note"> This may occur if an ICE restart is initiated while the ICE agent @@ -12021,14 +12026,6 @@ <h3> <li> <p>Do not read or modify state beyond this point.</p> </li> - <li> - <p> - [= Fire an event =] named {{RTCPeerConnection/icecandidate}} using the - {{RTCPeerConnectionIceEvent}} interface with the candidate - attribute set to <var>emptyCandidate</var> at - <var>connection</var>. - </p> - </li> <li> <p> [= Fire an event =] named {{RTCIceTransport/gatheringstatechange}} at From 8a9fdfc7e457e749e740b6c20fda98ca9be801e9 Mon Sep 17 00:00:00 2001 From: Jan-Ivar Bruaroey <jan-ivar@users.noreply.github.com> Date: Wed, 23 Aug 2023 14:47:24 -0400 Subject: [PATCH 03/10] Remove 4.4.1.4 Update the ICE gathering state --- webrtc.html | 57 ----------------------------------------------------- 1 file changed, 57 deletions(-) diff --git a/webrtc.html b/webrtc.html index ebbaa62be..9f3fb4547 100644 --- a/webrtc.html +++ b/webrtc.html @@ -1604,63 +1604,6 @@ <h4> </li> </ol> </section> - <section> - <h4> - Update the ICE gathering state - </h4> - <p> - To <dfn class="abstract-op" id="update-ice-gathering-state">update the ICE - gathering state</dfn> of an {{RTCPeerConnection}} instance - <var>connection</var>, the user agent MUST queue a task that runs - the following steps: - </p> - <ol class=algorithm> - <li> - <p> - If <var>connection</var>.{{RTCPeerConnection/[[IsClosed]]}} is - <code>true</code>, abort these steps. - </p> - </li> - <li> - <p> - Let <var>newState</var> be the value of deriving a new state - value as described by the {{RTCIceGatheringState}} enum. - </p> - </li> - <li> - <p> - If <var>connection</var>.{{RTCPeerConnection/[[IceGatheringState]]}} is equal - to <var>newState</var>, abort these steps. - </p> - </li> - <li> - <p> - Set <var>connection</var>.{{RTCPeerConnection/[[IceGatheringState]]}} to - <var>newState</var>. - </p> - </li> - <li data-tests="protocol/candidate-exchange.https.html"> - <p> - [= Fire an event =] named {{RTCPeerConnection/icegatheringstatechange}} at - <var>connection</var>. - </p> - </li> - <li data-tests="RTCPeerConnection-iceGatheringState.html"> - <p> - If <var>newState</var> is - {{RTCIceGatheringState/"complete"}}, [= fire an event =] - named {{RTCPeerConnection/icecandidate}} using the - {{RTCPeerConnectionIceEvent}} interface with the candidate - attribute set to <code>null</code> at <var>connection</var>. - </p> - <div class="note"> - The null candidate event is fired to ensure legacy - compatibility. New code should monitor the gathering state of - {{RTCIceTransport}} and/or {{RTCPeerConnection}}. - </div> - </li> - </ol> - </section> <section> <h4> Set the session description From e12f6167656574ef6d9f314e5fd7187786eb3e6c Mon Sep 17 00:00:00 2001 From: Jan-Ivar Bruaroey <jan-ivar@users.noreply.github.com> Date: Wed, 23 Aug 2023 15:18:20 -0400 Subject: [PATCH 04/10] Only queue second task if no other generations are being gathered. --- webrtc.html | 23 ++++++++++------------- 1 file changed, 10 insertions(+), 13 deletions(-) diff --git a/webrtc.html b/webrtc.html index 9f3fb4547..20c77b93d 100644 --- a/webrtc.html +++ b/webrtc.html @@ -11894,8 +11894,8 @@ <h3> When the [= ICE Agent =] is finished gathering a [= generation =] of candidates for an {{RTCIceTransport}} <var>transport</var> associated with an {{RTCPeerConnection}} <var>connection</var>, and those candidates have been - surfaced to the application, the user agent MUST queue two tasks. - The first task MUST run the following steps: + surfaced to the application, the user agent MUST queue a task to run the following + steps: </p> <ol class=algorithm> <li> @@ -11926,8 +11926,15 @@ <h3> </li> </ol> <p> - The second task MUST run the following steps: + When the [= ICE Agent =] has queued the above task, and no other + [= generation | generations =] of candidates is being gathered, the user agent + MUST also queue a second task to run the following steps: </p> + <div class="note"> + Other [= generation | generations =] of candidates might still be gathering + if an ICE restart was initiated while the ICE agent is still gathering the + previous [= generation =] of candidates. + </div> <ol class=algorithm> <li> <p> @@ -11935,16 +11942,6 @@ <h3> <code>true</code>, abort these steps. </p> </li> - <li> - <p> - If another [= generation =] of candidates is still being - gathered, abort these steps. - </p> - <div class="note"> - This may occur if an ICE restart is initiated while the ICE agent - is still gathering the previous [= generation =] of candidates. - </div> - </li> <li> <p> Set <var>transport</var>.{{RTCIceTransport/[[IceGathererState]]}} to From b44be93e5bbe576b2786ea0e5509008801eb2405 Mon Sep 17 00:00:00 2001 From: Jan-Ivar Bruaroey <jan-ivar@users.noreply.github.com> Date: Wed, 23 Aug 2023 16:59:41 -0400 Subject: [PATCH 05/10] Add amendments --- amendments.json | 11 ++++++++++- 1 file changed, 10 insertions(+), 1 deletion(-) diff --git a/amendments.json b/amendments.json index e2dea36de..82f59e7b3 100644 --- a/amendments.json +++ b/amendments.json @@ -520,5 +520,14 @@ "status": "candidate", "id": 36 } - ] + ], + "rtcicetransport": [ + { + "description": "Queue two tasks upon finishing ICE gathering, and fire gatheringstatechange & icegatheringstatechange in same task", + "pr": 2894, + "type": "correction", + "status": "candidate", + "id": 37 + } + ], } From 489998f5381e5c174777795ab10f214753a60617 Mon Sep 17 00:00:00 2001 From: Jan-Ivar Bruaroey <jan-ivar@users.noreply.github.com> Date: Wed, 23 Aug 2023 17:01:59 -0400 Subject: [PATCH 06/10] remove spurious comma --- amendments.json | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/amendments.json b/amendments.json index 82f59e7b3..9eff35cc2 100644 --- a/amendments.json +++ b/amendments.json @@ -529,5 +529,5 @@ "status": "candidate", "id": 37 } - ], + ] } From 5dbb2b31c83294f9e1e02688324e5a57681ea2bc Mon Sep 17 00:00:00 2001 From: Jan-Ivar Bruaroey <jan-ivar@users.noreply.github.com> Date: Fri, 25 Aug 2023 09:25:03 -0400 Subject: [PATCH 07/10] Add a=end-of-candidates to description(s). --- webrtc.html | 19 +++++++++++++++++++ 1 file changed, 19 insertions(+) diff --git a/webrtc.html b/webrtc.html index 20c77b93d..84df61fba 100644 --- a/webrtc.html +++ b/webrtc.html @@ -11904,6 +11904,25 @@ <h3> <code>true</code>, abort these steps. </p> </li> + <li data-tests= + "RTCPeerConnection-candidate-in-sdp.https.html"> + <p> + If <var>connection</var>.{{RTCPeerConnection/[[PendingLocalDescription]]}} is + not <code>null</code>, and represents the ICE [= generation =] + for which gathering finished, add + `a=end-of-candidates` to + <var>connection</var>.{{RTCPeerConnection/[[PendingLocalDescription]]}}.sdp. + </p> + </li> + <li> + <p> + If <var>connection</var>.{{RTCPeerConnection/[[CurrentLocalDescription]]}} is + not <code>null</code>, and represents the ICE [= generation =] + for which gathering finished, add + `a=end-of-candidates` to + <var>connection</var>.{{RTCPeerConnection/[[CurrentLocalDescription]]}}.sdp. + </p> + </li> <li> <p> Let <var>endOfGatheringCandidate</var> be the result of [= creating an From c6b03311b67f6e66e6e141a17801c4e00e58ca5b Mon Sep 17 00:00:00 2001 From: Jan-Ivar Bruaroey <jan-ivar@users.noreply.github.com> Date: Thu, 28 Mar 2024 10:56:15 -0400 Subject: [PATCH 08/10] Add testUpdates to amendments.json --- amendments.json | 6 ++++++ 1 file changed, 6 insertions(+) diff --git a/amendments.json b/amendments.json index afd7e989d..5afed30eb 100644 --- a/amendments.json +++ b/amendments.json @@ -738,6 +738,12 @@ { "description": "Queue two tasks upon finishing ICE gathering, and fire gatheringstatechange & icegatheringstatechange in same task", "pr": 2894, + "tests": [ + "RTCPeerConnection-iceGatheringState.html" + ], + "testUpdates": [ + "web-platform-tests/wpt#44687" + ], "type": "correction", "status": "candidate", "id": 37 From 00f15e5552ba73a1294939e6562ca3961bf62681 Mon Sep 17 00:00:00 2001 From: Jan-Ivar Bruaroey <jan-ivar@users.noreply.github.com> Date: Thu, 28 Mar 2024 11:01:43 -0400 Subject: [PATCH 09/10] fix link typo in amendments.json --- amendments.json | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/amendments.json b/amendments.json index 5afed30eb..6a667e985 100644 --- a/amendments.json +++ b/amendments.json @@ -739,7 +739,7 @@ "description": "Queue two tasks upon finishing ICE gathering, and fire gatheringstatechange & icegatheringstatechange in same task", "pr": 2894, "tests": [ - "RTCPeerConnection-iceGatheringState.html" + "webrtc/RTCPeerConnection-iceGatheringState.html" ], "testUpdates": [ "web-platform-tests/wpt#44687" From 40cc4202584c513ef93ccff07bfee7d67a722187 Mon Sep 17 00:00:00 2001 From: Jan-Ivar Bruaroey <jan-ivar@users.noreply.github.com> Date: Fri, 29 Mar 2024 16:55:56 -0400 Subject: [PATCH 10/10] Add <div id=rtcicetransport-gathering> --- amendments.json | 2 +- base-rec.html | 2 ++ webrtc.html | 2 ++ 3 files changed, 5 insertions(+), 1 deletion(-) diff --git a/amendments.json b/amendments.json index 6a667e985..7ab71c073 100644 --- a/amendments.json +++ b/amendments.json @@ -734,7 +734,7 @@ "id": 36 } ], - "rtcicetransport": [ + "rtcicetransport-gathering": [ { "description": "Queue two tasks upon finishing ICE gathering, and fire gatheringstatechange & icegatheringstatechange in same task", "pr": 2894, diff --git a/base-rec.html b/base-rec.html index 99d8426da..755938ad3 100644 --- a/base-rec.html +++ b/base-rec.html @@ -11711,6 +11711,7 @@ <h3 id="x5-6-rtcicetransport-interface"><bdi class="secno">5.6 </bdi> <a data-link-type="idl" href="#dom-icetransport-state" class="internalDFN" id="ref-for-dom-icetransport-state-1"><code><code>state</code></code></a> will be updated accordingly, as opposed to being represented by a new object. </div></div> + <div id="rtcicetransport-gathering"> <p> When the <a data-link-type="dfn" href="#dfn-ice-agent" class="internalDFN" id="ref-for-dfn-ice-agent-25">ICE Agent</a> indicates that it began gathering a <a data-link-type="dfn" href="#dfn-generation" class="internalDFN" id="ref-for-dfn-generation-7">generation</a> of candidates for an <a data-link-type="idl" href="#dom-rtcicetransport" class="internalDFN" id="ref-for-dom-rtcicetransport-33"><code><code>RTCIceTransport</code></code></a>, the user agent <em class="rfc2119">MUST</em> queue a task that runs the following steps: @@ -11826,6 +11827,7 @@ <h3 id="x5-6-rtcicetransport-interface"><bdi class="secno">5.6 </bdi> </p> </li> </ol> + </div> <p> When the <a data-link-type="dfn" href="#dfn-ice-agent" class="internalDFN" id="ref-for-dfn-ice-agent-29">ICE Agent</a> indicates that a new ICE candidate is available for an <a data-link-type="idl" href="#dom-rtcicetransport" class="internalDFN" id="ref-for-dom-rtcicetransport-38"><code><code>RTCIceTransport</code></code></a>, either by taking one from the diff --git a/webrtc.html b/webrtc.html index dce9d8bd9..6a7b802d2 100644 --- a/webrtc.html +++ b/webrtc.html @@ -11856,6 +11856,7 @@ <h3> {{RTCIceTransport/state}} will be updated accordingly, as opposed to being represented by a new object. </div> + <div id="rtcicetransport-gathering"> <p> When the [= ICE Agent =] indicates that it began gathering a [= generation =] of candidates for an {{RTCIceTransport}} <var>transport</var> @@ -12029,6 +12030,7 @@ <h3> </div> </li> </ol> + </div> <p> When the [= ICE Agent =] indicates that a new ICE candidate is available for an {{RTCIceTransport}}, either by taking one from the