Skip to content

Commit

Permalink
Merge pull request w3c#174 from sam-vi/samvi-171-setselected
Browse files Browse the repository at this point in the history 
Extend RTCIceTransport to allow changing the selected candidate pair
  • Loading branch information
@aboba
aboba authored Oct 26, 2023
2 parents 3ab7dbd + 403e85a commit 2833e5b
Showing 1 changed file with 226 additions and 25 deletions.
251 changes: 226 additions & 25 deletions index.html
View file
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

0 comments on commit 2833e5b

Please sign in to comment.