Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Extend RTCIceTransport to allow changing the selected candidate pair #174

Merged
merged 10 commits into from
Oct 26, 2023
Merged

Extend RTCIceTransport to allow changing the selected candidate pair #174

Changes from all commits
Commits
Show all changes
10 commits
Select commit Hold shift + click to select a range
e0f69a6
Add candidatepairnominate event.
sam-vi Sep 4, 2023
609a8e7
Add setSelectedCandidatePair method.
sam-vi Sep 4, 2023
a2c2cac
Make a note of nomination after selection.
sam-vi Sep 4, 2023
3a815e6
Only allow cancelling remove pre-nomination.
sam-vi Sep 4, 2023
9565680
Fix formatting and section IDs.
sam-vi Sep 5, 2023
b89e3f3
Guard setSelected with ProposalPending slot.
sam-vi Sep 5, 2023
cb4a936
Fix boolean literal references.
sam-vi Sep 5, 2023
2778d5f
Relax the check for previous nomination on setSelected.
sam-vi Sep 6, 2023
e0e07a5
Allow setSelected on the controlled side.
sam-vi Sep 6, 2023
403e85a
Merge branch 'w3c:main' into samvi-171-setselected
sam-vi Sep 22, 2023
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
251 changes: 226 additions & 25 deletions index.html
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -74,6 +74,10 @@ <h2>Terminology</h2>
<p>
The terms [= event =], [= event handlers =] and [= event handler event types =] are defined in [[!HTML]].
</p>
<p>
The process of <dfn data-lt="nominate|nominated|nomination">nominating</dfn> a candidate pair is defined in
[[RFC8445]] Section 8.1.1.
</p>
</section>
<section id="ice-csp">
<h3>
Expand Down Expand Up @@ -687,7 +691,7 @@ <h2>{{RTCRtpSender}} {{RTCRtpSender/setParameters()}} modifications to existing
<ul>
<li>
<p>For each <var>setParameterOptions.encodingOptions</var> indexed by <var>i</var>,
if <code><var>setParameterOptions.encodingOptions</var>[i].keyFrame</code> is set to <var>true</var>,
if <code><var>setParameterOptions.encodingOptions</var>[i].keyFrame</code> is set to <code>true</code>,
request that the encoder associated with <code><var>parameters</var>.encodings[i]</code> generates a key frame.</p>
</li>
</ul>
Expand All @@ -705,7 +709,138 @@ <h3>
application to observe and affect certain actions that an <dfn>ICE agent</dfn> [[RFC5245]] performs.
</p>
<p>
When the [= ICE agent =] has picked a candidate pair to remove, the [= user agent =] MUST [= queue a task =] to <dfn id="rtcicetransport-remove">remove a candidate pair</dfn>:
The [= ICE agent =] performs connectivity checks to identify valid candidate pairs on which it is possible to send
and receive media and data. In order to conclude ICE processing, the [= ICE agent =] {{nominates}} a valid candidate
pair as the selected candidate pair. Prior to nomination, any valid candidate pair may be used to send and receive data.
Once
a candidate pair is nominated successfully, only the selected candidate pair will be used to send and receive data.
Changing
the selected candidate pair after a successful nomination requires an ICE restart.
</p>
<p>
When the [= ICE agent =] has picked a candidate pair to {{nominate}} as the selected candidate pair, the [= user
agent =]
MUST [= queue a task =] to <dfn id="rtcicetransport-nominate" data-lt="nominate the candidate pair">nominate a
candidate pair</dfn>:
</p>
<ol class="algorithm">
<li>
<p>
Let |connection:RTCPeerConnection| 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>
<p>
Let |transport:RTCIceTransport| be the {{RTCIceTransport}} object associated with this candidate pair.
</p>
</li>
<li>
<p>
Let |candidatePair:RTCIceCandidatePair| be the candidate pair which is being {{nominated}}.
</p>
</li>
<li>
<p>
Set |transport|.{{RTCIceTransport/[[ProposalPending]]}} to <code>true</code>.
</p>
</li>
<li>
<p>
Let |accepted:boolean| be the result of [= fire an event | firing an event =] named
{{RTCIceTransport/icecandidatepairnominate}} at |transport|, using {{RTCIceCandidatePairEvent}}, with the
{{Event/cancelable}} attribute initialized to <code>true</code>, and the {{RTCIceCandidatePairEvent/local}} and
{{RTCIceCandidatePairEvent/remote}} attributes initialized to the local and remote candidates, respectively, of
|candidatePair|.
</p>
</li>
<li>
<p>
Set |transport|.{{RTCIceTransport/[[ProposalPending]]}} to <code>false</code>.
</p>
</li>
<li>
<p>
If |accepted| is <code>false</code>, instruct the [= ICE agent =] to not {{nominate}} |candidatePair|, and instead to
continue to perform connectivity checks. The [= ICE agent =] may continue to send data using the candidate pair
indicated by |candidatePair| unless instructed to use another candidate pair with
{{RTCIceTransport/setSelectedCandidatePair}}.
</p>
</li>
<li>
<p>
Otherwise, instruct the [= ICE agent =] to {{nominate}} the candidate pair indicated by |candidatePair|.
</p>
</li>
</ol>
<p>
If the application defers the {{nomination}} of a candidate pair by cancelling the
{{RTCIceTransport/icecandidatepairnominate}} event, it may select a different candidate pair to send data by calling
{{RTCIceTransport/setSelectedCandidatePair}}. When the method is called, the [= user agent =] MUST run the steps to <dfn
id="rtcicetransport-select">change the selected candidate pair</dfn>:
</p>
<ol class="algorithm">
<li>
<p>
Let |connection:RTCPeerConnection| be the {{RTCPeerConnection}} object associated with this [= ICE agent =].
</p>
</li>
<li>
<p>
If <var>connection</var>.{{RTCPeerConnection/[[IsClosed]]}} is
<code>true</code>, [= exception/throw =] an {{InvalidStateError}}.
</p>
</li>
<li>
<p>
Let |transport:RTCIceTransport| be the {{RTCIceTransport}} object associated with this candidate pair.
</p>
</li>
<li>
<p>
If |transport|.{{RTCIceTransport/[[ProposalPending]]}} is <code>true</code>, [= exception/throw =] an {{InvalidStateError}}.
</p>
</li>
<li>
<p>
If |transport|.{{RTCIceTransport/[[IceTransportState]]}} is either of
{{RTCIceTransportState/"new"}}, {{RTCIceTransportState/"failed"}} or {{RTCIceTransportState/"closed"}}, [=
exception/throw =]
an {{InvalidStateError}}.
</p>
</li>
<li>
<p>
Let |candidatePair:RTCIceCandidatePair| be the candidate pair which is being set as the selected candidate pair.
</p>
</li>
<li>
<p>
If |candidatePair| does not describe a candidate pair formed for this {{RTCIceTransport}} and sent in
{{RTCIceTransport/onicecandidatepairadd}}, [= exception/throw =] a {{NotFoundError}}.
</p>
</li>
<li>
<p>
Instruct the [= ICE agent =] to use |candidatePair| to send data, and continue to the steps for a change in the selected
candidate pair (leading up to {{RTCIceTransport/onselectedcandidatepairchange}}).
</p>
</li>
</ol>
<p class="note">
After changing the selected candidate pair, the controlling [= ICE agent =] may attempt to [= nominate the candidate
pair =] as
well to conclude ICE processing. The application may cancel the nomination to allow further changes to the selected
candidate pair.
</p>
<p>
When the [= ICE agent =] has picked a candidate pair to remove, the [= user agent =] MUST [= queue a task =] to <dfn
id="rtcicetransport-remove">remove a candidate pair</dfn>:
</p>
<ol class="algorithm">
<li>
Expand All @@ -731,19 +866,34 @@ <h3>
</li>
<li>
<p>
Let |cancelable:boolean| be <code>true</code> if the candidate pair is being removed in order to free an unused candidate, and <code>false</code> otherwise.
Let |cancelable:boolean| be <code>true</code> if the candidate pair is being removed in order to free an unused candidate, and
<code>false</code> otherwise.
</p>
</li>
<li>
<p>
Set |transport|.{{RTCIceTransport/[[ProposalPending]]}} to <code>true</code>.
</p>
</li>
<li>
<p>
Let |accepted:boolean| be the result of [= fire an event | firing an event =] named
{{RTCIceTransport/icecandidatepairremove}} at |transport|, using {{RTCIceCandidatePairEvent}}, with the
{{Event/cancelable}} attribute initialized to <var>cancelable</var>, and the {{RTCIceCandidatePairEvent/local}} and {{RTCIceCandidatePairEvent/remote}} attributes initialized to the local and remote candidates, respectively, of |candidatePair|.
{{Event/cancelable}} attribute initialized to <var>cancelable</var>, and the {{RTCIceCandidatePairEvent/local}}
and {{RTCIceCandidatePairEvent/remote}} attributes initialized to the local and remote candidates, respectively,
of |candidatePair|.
</p>
</li>
<li>
<p>
Set |transport|.{{RTCIceTransport/[[ProposalPending]]}} to <code>false</code>.
</p>
</li>
<li>
<p>
If |accepted| is <code>false</code>, instruct the [= ICE agent =] to not remove the candidate pair indicated by |candidatePair|, and instead continue to send and respond to ICE connectivity checks on the candidate pair as before.
If |accepted| is <code>false</code>, instruct the [= ICE agent =] to not remove the candidate pair indicated by
|candidatePair|, and instead continue to send and respond to ICE connectivity checks on the candidate pair as
before.
</p>
</li>
<li>
Expand All @@ -752,12 +902,22 @@ <h3>
</p>
</li>
</ol>
<p>
The {{RTCIceTransport}} object is extended by adding the following internal slot:
</p>
<ul>
<li>
<dfn data-dfn-for="RTCIceTransport">[[\ProposalPending]]</dfn> initialized to <code>false</code>.
</li>
</ul>
<pre class="idl">
partial interface RTCIceTransport {
attribute EventHandler onicecandidatepairadd;
attribute EventHandler onicecandidatepairremove;
};</pre>
<section>
partial interface RTCIceTransport {
attribute EventHandler onicecandidatepairadd;
attribute EventHandler onicecandidatepairremove;
attribute EventHandler onicecandidatepairnominate;
undefined setSelectedCandidatePair(RTCIceCandidatePair candidatePair);
};</pre>
<section id="rtcicetransport-attributes">
<h2>Attributes</h2>
<dl data-link-for="RTCIceTransport" data-dfn-for="RTCIceTransport" class="attributes">
<dt>
Expand All @@ -770,7 +930,8 @@ <h2>Attributes</h2>
<p>
When the [= ICE agent =] has formed a candidate pair, the [= user agent =] MUST queue a task to [= fire an
event =] named {{icecandidatepairadd}} using the {{RTCIceCandidatePairEvent}} interface, with the
{{RTCIceCandidatePairEvent/local}} and {{RTCIceCandidatePairEvent/remote}} attributes set to the local and remote candidates, respectively, of the formed candidate pair.
{{RTCIceCandidatePairEvent/local}} and {{RTCIceCandidatePairEvent/remote}} attributes set to the local and
remote candidates, respectively, of the formed candidate pair.
</p>
</dd>
<dt>
Expand All @@ -785,57 +946,89 @@ <h2>Attributes</h2>
the [= user agent =] MUST run the steps to [= remove a candidate pair =].
</p>
</dd>
<dt>
<dfn>onicecandidatepairnominate</dfn> of type <span class="idlAttrType">{{EventHandler}}</span>
</dt>
<dd>
<p>
The event type of this event handler is {{icecandidatepairnominate}}.
</p>
<p>
When the [= ICE agent =] has picked a candidate pair to {{nominate}} as the selected candidate pair, but
before
the
nomination takes place, the [= user agent =] MUST run the steps to [= nominate a candidate pair =].
</p>
</dd>
</dl>
</section>
<section id="rtcicetransport-methods">
<h2>Methods</h2>
<dl data-link-for="RTCIceTransport" data-dfn-for="RTCIceTransport" class="methods">
<dt>
<dfn>setSelectedCandidatePair</dfn>
</dt>
<dd>
<p>
The {{setSelectedCandidatePair}} method attempts to change the selected candidate pair. If successful, data will be sent
on the provided candidate pair. When this method is invoked, the [= user agent =] MUST run the steps to [= change the
selected candidate pair =].
</p>
</dd>
</dl>
</section>
<section>
<h2>
<dfn>RTCIceCandidatePairEvent</dfn>
</h2>
<p>
The {{RTCIceTransport/icecandidatepairadd}} and {{RTCIceTransport/icecandidatepairremove}} events use the {{RTCIceCandidatePairEvent}} interface.
The {{RTCIceTransport/icecandidatepairadd}} and {{RTCIceTransport/icecandidatepairremove}} events use the
{{RTCIceCandidatePairEvent}} interface.
</p>
<div>
<pre class="idl">[Exposed=Window]
interface RTCIceCandidatePairEvent : Event {
constructor(DOMString type, RTCIceCandidatePairEventInit eventInitDict);
readonly attribute RTCIceCandidate local;
readonly attribute RTCIceCandidate remote;
};</pre>
<section>
interface RTCIceCandidatePairEvent : Event {
constructor(DOMString type, RTCIceCandidatePairEventInit eventInitDict);
readonly attribute RTCIceCandidate local;
readonly attribute RTCIceCandidate remote;
};</pre>
<section id="rtcicecandidatepairevent-constructors">
<h4>Constructors</h4>
<dl data-link-for="RTCIceCandidatePairEvent" data-dfn-for="RTCIceCandidatePairEvent" class="constructors">
<dt><dfn>RTCIceCandidatePairEvent.constructor()</dfn></dt>
<dd></dd>
</dl>
</section>
<section>
<section id="rtcicecandidatepairevent-attributes">
<h4>Attributes</h4>
<dl data-link-for="RTCIceCandidatePairEvent" data-dfn-for="RTCIceCandidatePairEvent" class="attributes">
<dt>
<dfn>local</dfn> of type <span class="idlAttrType">{{RTCIceCandidate}}</span>, readonly
</dt>
<dd>
<p>
The {{local}} attribute represents the local {{RTCIceCandidate}} of the candidate pair associated with the event.
The {{local}} attribute represents the local {{RTCIceCandidate}} of the candidate pair associated with the
event.
</p>
</dd>
<dt>
<dfn>remote</dfn> of type <span class="idlAttrType">{{RTCIceCandidate}}</span>, readonly
</dt>
<dd>
<p>
The {{remote}} attribute represents the remote {{RTCIceCandidate}} of the candidate pair associated with the event.
The {{remote}} attribute represents the remote {{RTCIceCandidate}} of the candidate pair associated with
the event.
</p>
</dd>
</dl>
</section>
</div>
<div>
<pre class="idl">
dictionary RTCIceCandidatePairEventInit : EventInit {
required RTCIceCandidate local;
required RTCIceCandidate remote;
};</pre>
dictionary RTCIceCandidatePairEventInit : EventInit {
required RTCIceCandidate local;
required RTCIceCandidate remote;
};</pre>
<section id="rtcicecandidatepaireventinit">
<h4>Dictionary <dfn>RTCIceCandidatePairEventInit</dfn> Members</h4>
<dl data-link-for="RTCIceCandidatePairEventInit" data-dfn-for="RTCIceCandidatePairEventInit"
Expand Down Expand Up @@ -1300,6 +1493,14 @@ <h2>Event summary</h2>
The [= ICE agent =] has picked a candidate pair to remove, and unless the operation is canceled by invoking the <code>preventDefault()</code> method on the event, it will be removed.
</td>
</tr>
<tr>
<th scope=row><dfn data-dfn-for="RTCIceTransport" data-dfn-type=event>icecandidatepairnominate</dfn></th>
<td>{{RTCIceCandidatePairEvent}}</td>
<td>
The [= ICE agent =] has picked a valid candidate pair to {{nominate}}, and unless the operation is canceled by
invoking the <code>preventDefault()</code> method on the event, it will be {{nominated}}.
</td>
</tr>
</tbody>
</table>
</section>
Expand Down
Loading