Skip to content

Commit

Permalink
Merge pull request #2894 from jan-ivar/syncgathering
Browse files Browse the repository at this point in the history 
Queue two tasks upon finishing ICE gathering, and fire gatheringstatechange & icegatheringstatechange in same task
  • Loading branch information
@jan-ivar
jan-ivar authored Mar 29, 2024
2 parents 6e18405 + 40cc420 commit cfd8322
Show file tree
Hide file tree
Showing 3 changed files with 113 additions and 94 deletions.
15 changes: 15 additions & 0 deletions amendments.json
View file
Original file line number Diff line number Diff line change
Expand Up @@ -744,6 +744,21 @@
"id": 36
}
],
"rtcicetransport-gathering": [
{
"description": "Queue two tasks upon finishing ICE gathering, and fire gatheringstatechange & icegatheringstatechange in same task",
"pr": 2894,
"tests": [
"webrtc/RTCPeerConnection-iceGatheringState.html"
],
"testUpdates": [
"web-platform-tests/wpt#44687"
],
"type": "correction",
"status": "candidate",
"id": 37
}
],
"closing-procedure": [
{
"description": "Prevent GC of non-closed RTCDataChannels",
Expand Down
2 changes: 2 additions & 0 deletions base-rec.html
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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:
Expand Down Expand Up @@ -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
Expand Down
190 changes: 96 additions & 94 deletions webrtc.html
View file
Original file line number Diff line number Diff line change
Expand Up @@ -1611,63 +1611,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
Expand Down Expand Up @@ -11913,122 +11856,181 @@ <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}}, 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">
<li>
<p>
Let <var>connection</var> be the {{RTCPeerConnection}} object
associated with this [= ICE Agent =].
If <var>connection</var>.{{RTCPeerConnection/[[IsClosed]]}} is
<code>true</code>, abort these steps.
</p>
</li>
<li>
<p>
If <var>connection</var>.{{RTCPeerConnection/[[IsClosed]]}} is
<code>true</code>, abort these steps.
Set <var>transport</var>.{{RTCIceTransport/[[IceGathererState]]}} to
{{RTCIceGathererState/gathering}}.
</p>
</li>
<li class="no-test-needed">
<li>
<p>
Let <var>transport</var> be the {{RTCIceTransport}} for which
candidate gathering began.
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>
Set <var>transport</var>.{{RTCIceTransport/[[IceGathererState]]}} to
{{RTCIceGathererState/gathering}}.
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
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 a task to run 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 =].
</p>
</li>
<li>
<p>
If <var>connection</var>.{{RTCPeerConnection/[[IsClosed]]}} is
<code>true</code>, abort these steps.
</p>
</li>
<li class="no-test-needed">
<li data-tests=
"RTCPeerConnection-candidate-in-sdp.https.html">
<p>
Let <var>transport</var> be the {{RTCIceTransport}} for which
candidate gathering finished.
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>
Let <var>newCandidate</var> be the result of [= creating an
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
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>
[= Fire an event =] named {{RTCPeerConnection/icecandidate}} using the
{{RTCPeerConnectionIceEvent}} interface with the candidate
attribute set to <var>newCandidate</var> at
attribute set to <var>endOfGatheringCandidate</var> at
<var>connection</var>.
</p>
</li>
</ol>
<p>
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>
If another [= generation =] of candidates is still being
gathered, abort these steps.
If <var>connection</var>.{{RTCPeerConnection/[[IsClosed]]}} is
<code>true</code>, 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
{{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 {{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>
</div>
<p>
When the [= ICE Agent =] indicates that a new ICE candidate is
available for an {{RTCIceTransport}}, either by taking one from the
Expand Down

0 comments on commit cfd8322

Please sign in to comment.