Skip to content

Use RTCIceCandidatePair interface in RTCIceTransport #205

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

Open
wants to merge 6 commits into
base: main
Choose a base branch
from
Open

Use RTCIceCandidatePair interface in RTCIceTransport #205

Changes from all commits
Commits
Show all changes
6 commits
Select commit Hold shift + click to select a range
7c3a703
Use RTCIceCandidatePair interface in RTCIceTransport.
sam-vi Apr 18, 2024
83d5a3c
Compare RTCIceCandidatePair identity instead of match algo.
sam-vi Apr 18, 2024
cd26c2a
Modify the change of selected pair algo in RTCIceTransport.
sam-vi Apr 18, 2024
56a6071
Fix markup typo (unrelated to this PR)
dontcallmedom Oct 15, 2024
ca19e02
Merge branch 'w3c:main' into 2930-candidatepair-interface
sam-vi May 14, 2025
469ff70
Qualify the CandidatePairs slot with the associated transport.
sam-vi May 19, 2025
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
209 changes: 87 additions & 122 deletions index.html
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -599,10 +599,9 @@ <h3>
</li>
<li>
<p>
Let |candidatePair:RTCIceCandidatePair| be a new {{RTCIceCandidatePair}} dictionary
with its {{RTCIceCandidatePair/local}} and {{RTCIceCandidatePair/remote}} members
initialized to new {{RTCIceCandidate}}s representing the local and remote part of the
[= formed =] pair respectively.
Let |candidatePair:RTCIceCandidatePair| be the result of [= creating an RTCIceCandidatePair =] with
|local:RTCIceCandidate| and |remote:RTCIceCandidate|, representing the local and remote candidates of the [= formed =]
pair respectively.
</p>
</li>
<li>
Expand All @@ -612,21 +611,20 @@ <h3>
</li>
<li>
<p>
[=Assert=]: |candidatePair| does not [= candidate pair match | match =] any
item in |transport|.{{RTCIceTransport/[[CandidatePairs]]}}
[=Assert=]: |transport|.{{RTCIceTransport/[[CandidatePairs]]}} does not [= list/contain =] |candidatePair|.
</p>
</li>
<li>
<p>
[= list/Append =] |candidatePair| to {{RTCIceTransport/[[CandidatePairs]]}}.
[= list/Append =] |candidatePair| to |transport|.{{RTCIceTransport/[[CandidatePairs]]}}.
</p>
</li>
<li>
<p>
[= Fire an event =] named
{{RTCIceTransport/icecandidatepairadd}} at |transport|, using {{RTCIceCandidatePairEvent}},
with the {{RTCIceCandidatePairEvent/local}} and {{RTCIceCandidatePairEvent/remote}} attributes
initialized to the local and remote candidates, respectively, of |candidatePair|.
with the {{RTCIceCandidatePairEvent/candidatePair}} attribute
initialized to |candidatePair|.
</p>
</li>
</ol>
Expand Down Expand Up @@ -667,9 +665,8 @@ <h3>
<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|.
{{Event/cancelable}} attribute initialized to <code>true</code>, and the {{RTCIceCandidatePairEvent/candidatePair}} attribute
initialized to |candidatePair|.
</p>
</li>
<li>
Expand Down Expand Up @@ -733,9 +730,8 @@ <h3>
<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/candidatePair}} attribute
initialized to |candidatePair|.
</p>
</li>
<li>
Expand Down Expand Up @@ -867,8 +863,7 @@ <h2>Methods</h2>
</li>
<li>
<p>
If |candidatePair| does not [= candidate pair match | match =] any item in [=this=].
{{RTCIceTransport/[[CandidatePairs]]}}, [= exception/throw =] a {{NotFoundError}}.
If [=this=].{{RTCIceTransport/[[CandidatePairs]]}} does not [= list/contain =] |candidatePair|, [= exception/throw =] a {{NotFoundError}}.
</p>
</li>
<li>
Expand Down Expand Up @@ -957,15 +952,13 @@ <h2>Methods</h2>
</li>
<li>
<p>
If |candidatePair| does not [= candidate pair match | match =] any item in [=this=].
{{RTCIceTransport/[[CandidatePairs]]}}, [= exception/throw =] a {{NotFoundError}}.
If [=this=].{{RTCIceTransport/[[CandidatePairs]]}} does not [= list/contain =] |candidatePair|, [= exception/throw =] a {{NotFoundError}}.
</p>
</li>
<li>
<p>
[= list/Remove =] the item in
[=this=].{{RTCIceTransport/[[CandidatePairs]]}} that
[= candidate pair match | matches =] |candidatePair|.
[= list/Remove =] |candidatePair| from
[=this=].{{RTCIceTransport/[[CandidatePairs]]}}.
</p>
</li>
<li>
Expand All @@ -985,7 +978,7 @@ <h2>Methods</h2>
<ol>
<li>
<p>
[= Fire an event =] named {{RTCIceTransport/icecandidatepairremove}} at |transport|, using {{RTCIceCandidatePairEvent}}, with the {{Event/cancelable}} attribute initialized to <code>false</code>, and the {{RTCIceCandidatePairEvent/local}} and {{RTCIceCandidatePairEvent/remote}} attributes initialized to the {{RTCIceCandidatePair/local}} and {{RTCIceCandidatePair/remote}} candidates, respectively, of <var>candidatePair</var>.
[= Fire an event =] named {{RTCIceTransport/icecandidatepairremove}} at |transport|, using {{RTCIceCandidatePairEvent}}, with the {{Event/cancelable}} attribute initialized to <code>false</code>, and the {{RTCIceCandidatePairEvent/candidatePair}} attribute initialized to |candidatePair|.
</p>
</li>
<li>
Expand All @@ -1011,15 +1004,15 @@ <h2>
<dfn>RTCIceCandidatePairEvent</dfn>
</h2>
<p>
The {{RTCIceTransport/icecandidatepairadd}} and {{RTCIceTransport/icecandidatepairremove}} events use the
The {{RTCIceTransport/icecandidatepairadd}}, {{RTCIceTransport/icecandidatepairnominate}} 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;
readonly attribute RTCIceCandidatePair candidatePair;
};</pre>
<section id="rtcicecandidatepairevent-constructors">
<h4>Constructors</h4>
Expand All @@ -1032,21 +1025,11 @@ <h4>Constructors</h4>
<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
<dfn>candidatePair</dfn> of type <span class="idlAttrType">{{RTCIceCandidatePair}}</span>, readonly
</dt>
<dd>
<p>
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 {{candidatePair}} attribute represents the candidate pair associated with the event.
</p>
</dd>
</dl>
Expand All @@ -1055,105 +1038,87 @@ <h4>Attributes</h4>
<div>
<pre class="idl">
dictionary RTCIceCandidatePairEventInit : EventInit {
required RTCIceCandidate local;
required RTCIceCandidate remote;
required RTCIceCandidatePair candidatePair;
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Was this change discussed?
It looks ok to me but this reduces the ability of creating event to candidate pairs created by the UA

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This is in line with the goals of w3c/webrtc-pc#2930, namely restricting JS's ability to create invalid pairs and simplifying validation steps in specs. It reduces the burden of validation in the RTCIceTransport extension API specs, and provides web developers with a loose guarantee that events will signal candidate pairs that can be provided as inputs to other RTCIceTransport methods (barring state errors).

I hadn't considered this particular change to be especially significant, but we could discuss in the next interim if needed.

My thoughts are:

  • It is a good idea to limit the general purpose RTCIceCandidatePairEventInit to valid candidate pairs created by the UA.
  • If in the future there is a need for an event to signal candidate pairs not created by the UA, it should be a more specific event (similar to RTCPeerConnectionIceErrorEvent) that is used in that limited scope.
    • If this is found to be too restrictive, then it could be discussed whether it makes sense to introduce a JS-accessible constructor for RTCIceCandidatePair.

};</pre>
<section id="rtcicecandidatepaireventinit">
<h4>Dictionary <dfn>RTCIceCandidatePairEventInit</dfn> Members</h4>
<dl data-link-for="RTCIceCandidatePairEventInit" data-dfn-for="RTCIceCandidatePairEventInit"
class="dictionary-members">
<dt>
<dfn>local</dfn> of type <span class="idlAttrType">{{RTCIceCandidate}}</span>, required
</dt>
<dd>
<p>
The local {{RTCIceCandidate}} of the candidate pair announced by the event.
</p>
</dd>
<dt>
<dfn>remote</dfn> of type <span class="idlAttrType">{{RTCIceCandidate}}</span>, required
<dfn>candidatePair</dfn> of type <span class="idlAttrType">{{RTCIceCandidatePair}}</span>, required
</dt>
<dd>
<p>
The remote {{RTCIceCandidate}} of the candidate pair announced by the event.
The candidate pair announced by the event.
</p>
</dd>
</dl>
</section>
</div>
</section>
<p>
The <dfn>candidate match</dfn> algorithm given two {{RTCIceCandidate}} |first:RTCIceCandidate| and
|second:RTCIceCandidate| is as follows:
</p>
<ol class="algorithm">
<li>
<p>
If |first|.{{RTCIceCandidate/candidate}} is not [= string/identical to =] |second|.{{RTCIceCandidate/candidate}}, return <code>false</code>.
</p>
</li>
<li>
<p>
If either (but not both) of |first|.{{RTCIceCandidate/sdpMid}} and |second|.{{RTCIceCandidate/sdpMid}} is
<code>null</code>, return <code>false</code>.
</p>
</li>
<li>
<p>
If neither of |first|.{{RTCIceCandidate/sdpMid}} and |second|.{{RTCIceCandidate/sdpMid}} is <code>null</code>, and |first|.{{RTCIceCandidate/sdpMid}} is not [= string/identical to =]
|second|.{{RTCIceCandidate/sdpMid}}, return <code>false</code>.
</p>
</li>
<li>
<p>
If either (but not both) of |first|.{{RTCIceCandidate/sdpMLineIndex}} and |second|.{{RTCIceCandidate/sdpMLineIndex}} is
<code>null</code>, return <code>false</code>.
</p>
</li>
<li>
<p>
If neither of |first|.{{RTCIceCandidate/sdpMLineIndex}} and |second|.{{RTCIceCandidate/sdpMLineIndex}} is <code>null</code> and |first|.{{RTCIceCandidate/sdpMLineIndex}} is not equal to
|second|.{{RTCIceCandidate/sdpMLineIndex}}, return <code>false</code>.
</p>
</li>
<li>
<p>
If either (but not both) of |first|.{{RTCIceCandidate/usernameFragment}} and |second|.{{RTCIceCandidate/usernameFragment}} is
<code>null</code>, return <code>false</code>.
</p>
</li>
<li>
<p>
If neither of |first|.{{RTCIceCandidate/usernameFragment}} and |second|.{{RTCIceCandidate/usernameFragment}} is <code>null</code> and |first|.{{RTCIceCandidate/usernameFragment}} is not [= string/identical to =]
|second|.{{RTCIceCandidate/usernameFragment}}, return <code>false</code>.
</p>
</li>
<li>
<p>
Return <code>true</code>.
</p>
</li>
</ol>
<p>
The <dfn>candidate pair match</dfn> algorithm given two {{RTCIceCandidatePair}} |first:RTCIceCandidatePair| and |second:RTCIceCandidatePair| is as follows:
</p>
<ol class="algorithm">
<li>
<p>
If |first|.{{RTCIceCandidatePair/local}} does not [= candidate match | match =] |second|.{{RTCIceCandidatePair/local}}, return <code>false</code>.
</p>
</li>
<li>
<p>
If |first|.{{RTCIceCandidatePair/remote}} does not [= candidate match | match =] |second|.{{RTCIceCandidatePair/remote}}, return <code>false</code>.
</p>
</li>
<li>
<p>
Return <code>true</code>.
</p>
</li>
</ol>
<section id="rtcicetransport-change-pair-state-modifications">
<h2>Modifications to existing procedures</h2>
<p>
In the steps to [=RTCIceTransport/change the selected candidate pair and state=], if the selected candidate pair was changed, modify the first step to the following:
</p>
<ol class="algorithm">
<li>
Let <var>newCandidatePair</var> be the [= list/item =] [= list/contained =] in |this|.{{RTCIceTransport/[[CandidatePairs]]}} whose {{RTCIceCandidatePair/local}} and {{RTCIceCandidatePair/remote}} attributes respectively [= candidate match | match =] the local and remote candidates of the indicated pair if one is selected, and <code>null</code> otherwise.
</li>
</ol>
<p>
The <dfn class="export">candidate match</dfn> algorithm given two {{RTCIceCandidate}} |first:RTCIceCandidate| and
|second:RTCIceCandidate| is as follows:
</p>
<ol class="algorithm">
<li>
<p>
If |first|.{{RTCIceCandidate/candidate}} is not [= string/identical to =] |second|.{{RTCIceCandidate/candidate}}, return <code>false</code>.
</p>
</li>
<li>
<p>
If either (but not both) of |first|.{{RTCIceCandidate/sdpMid}} and |second|.{{RTCIceCandidate/sdpMid}} is
<code>null</code>, return <code>false</code>.
</p>
</li>
<li>
<p>
If neither of |first|.{{RTCIceCandidate/sdpMid}} and |second|.{{RTCIceCandidate/sdpMid}} is <code>null</code>, and |first|.{{RTCIceCandidate/sdpMid}} is not [= string/identical to =]
|second|.{{RTCIceCandidate/sdpMid}}, return <code>false</code>.
</p>
</li>
<li>
<p>
If either (but not both) of |first|.{{RTCIceCandidate/sdpMLineIndex}} and |second|.{{RTCIceCandidate/sdpMLineIndex}} is
<code>null</code>, return <code>false</code>.
</p>
</li>
<li>
<p>
If neither of |first|.{{RTCIceCandidate/sdpMLineIndex}} and |second|.{{RTCIceCandidate/sdpMLineIndex}} is <code>null</code> and |first|.{{RTCIceCandidate/sdpMLineIndex}} is not equal to
|second|.{{RTCIceCandidate/sdpMLineIndex}}, return <code>false</code>.
</p>
</li>
<li>
<p>
If either (but not both) of |first|.{{RTCIceCandidate/usernameFragment}} and |second|.{{RTCIceCandidate/usernameFragment}} is
<code>null</code>, return <code>false</code>.
</p>
</li>
<li>
<p>
If neither of |first|.{{RTCIceCandidate/usernameFragment}} and |second|.{{RTCIceCandidate/usernameFragment}} is <code>null</code> and |first|.{{RTCIceCandidate/usernameFragment}} is not [= string/identical to =]
|second|.{{RTCIceCandidate/usernameFragment}}, return <code>false</code>.
</p>
</li>
<li>
<p>
Return <code>true</code>.
</p>
</li>
</ol>
</section>
</section>
<section id="rtcrtpcontributingsource-extensions">
<h3>
Expand Down