-
Notifications
You must be signed in to change notification settings - Fork 42
/
index.html
12509 lines (12397 loc) · 593 KB
/
index.html
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
948
949
950
951
952
953
954
955
956
957
958
959
960
961
962
963
964
965
966
967
968
969
970
971
972
973
974
975
976
977
978
979
980
981
982
983
984
985
986
987
988
989
990
991
992
993
994
995
996
997
998
999
1000
<!DOCTYPE html>
<html lang="en" dir="ltr">
<head>
<meta name="generator" content="HTML Tidy for HTML5 for Linux/x86 version 5.3.9">
<meta charset="utf-8">
<link href="webrtc.css" rel="stylesheet">
<title>Object RTC (ORTC) API for WebRTC</title>
<script src="respec-w3c-common.js" async class="remove"></script>
<script src="respec-config.js" class="remove"></script>
</head>
<body>
<section id="abstract">
<p>This document defines a set of ECMAScript APIs in WebIDL to allow media to be sent
and received from another browser or device implementing the appropriate set of
real-time protocols. However, unlike the WebRTC 1.0 API, Object Real-Time
Communications (ORTC) does not utilize Session Description Protocol (SDP) in the API,
nor does it mandate support for the Offer/Answer state machine (though an application
is free to choose SDP and Offer/Answer as an on-the-wire signaling mechanism).
Instead, ORTC uses "sender", "receiver" and "transport" objects, which have
"capabilities" describing what they are capable of doing, as well as "parameters"
which define what they are configured to do. "Tracks" are encoded by senders and sent
over transports, then decoded by receivers while "data channels" are sent over
transports directly.</p>
</section>
<section id="sotd"></section>
<section id="overview*">
<h2>Overview</h2>
<p>Object Real-Time Communications (ORTC) provides a powerful API for the development
of WebRTC based applications. ORTC does not utilize Session Description Protocol
(SDP) in the API, nor does it mandate support for the Offer/Answer state machine
(though an application is free to choose SDP and Offer/Answer as an on-the-wire
signaling mechanism). Instead, ORTC uses "sender", "receiver" and "transport"
objects, which have "capabilities" describing what they are capable of doing, as well
as "parameters" which define what they are configured to do. "Tracks" are encoded by
senders and sent over transports, then decoded by receivers while "data channels" are
sent over transports directly.</p>
<p>In a Javascript application utilizing the ORTC API, the relationship between the
application and the objects, as well as between the objects themselves is shown
below. Horizontal or slanted arrows denote the flow of media or data, whereas
vertical arrows denote interactions via methods and events.</p>
<figure>
<img alt="The non-normative ORTC Big Picture Diagram" src=
"images/quic.svg" style="width:100%">
<figcaption>
Non-normative ORTC Big Picture Diagram
</figcaption>
</figure>
<p>In the figure above, the <code><a>RTCRtpSender</a></code> (<a href=
"#rtcrtpsender*">Section 5</a>) encodes the track provided as input, which is
transported over a <code><a>RTCDtlsTransport</a></code> (<a href=
"#rtcdtlstransport*">Section 4</a>). An <code><a>RTCDataChannel</a></code> (<a href=
"#rtcdatachannel*">Section 11</a>) utilizes an <code><a>RTCSctpTransport</a></code>
(<a href="#sctp-transport*">Section 12</a>) which can also be multiplexed over the
<code><a>RTCDtlsTransport</a></code>. Sending of Dual Tone Multi Frequency (DTMF)
tones is supported via the <code><a>RTCDtmfSender</a></code> (<a href=
"#rtcdtmfsender*">Section 10</a>).</p>
<p>The <code><a>RTCDtlsTransport</a></code> utilizes an
<code><a>RTCIceTransport</a></code> (<a href="#rtcicetransport*">Section 3</a>) to
select a communication path to reach the receiving peer's
<code><a>RTCIceTransport</a></code>, which is in turn associated with an
<code><a>RTCDtlsTransport</a></code> which de-multiplexes media to the
<code><a>RTCRtpReceiver</a></code> (<a href="#rtcrtpreceiver*">Section 6</a>) and
data to the <code><a>RTCSctpTransport</a></code> and
<code><a>RTCDataChannel</a></code>. The <code><a>RTCRtpReceiver</a></code> then
decodes media, producing a track which is rendered by an audio or video tag.</p>
<p>Several other objects also play a role. The <code><a>RTCIceGatherer</a></code>
(<a href="#rtcicegatherer*">Section 2</a>) gathers local ICE candidates for use by
one or more <code><a>RTCIceTransport</a></code> objects, enabling forking scenarios.
The <code><a>RTCIceTransportController</a></code> (<a href=
"#rtcicetransportcontroller*">Section 7</a>) manages freezing/unfreezing (defined in
[[!RFC5245]]) and bandwidth estimation. The <code><a>RTCRtpListener</a></code>
(<a href="#rtcrtplistener*">Section 8</a>) detects whether an RTP stream is received
that cannot be delivered to any existing <code><a>RTCRtpReceiver</a></code>,
providing an <code>onunhandledrtp</code> event handler that the application can use
to correct the situation. The <code><a>RTCQuicTransport</a></code>
(<a href="#quic-transport*">Section 13</a>) utilizes an
<code><a>RTCIceTransport</a></code> to select a communication path to reach the
receiving peer's <code><a>RTCIceTransport</a></code>, which is in turn associated
with an <code><a>RTCQuicTransport</a></code>. An <code><a>RTCQuicTransport</a></code>
is associated with zero or more <code><a>RTCQuicStream</a></code>
(<a href="#quicstream*">Section 14</a>) objects which
read data from and write data to <code><a>RTCQuicStream</a></code> objects on the
remote peer.</p>
<p>Remaining sections of the specification fill in details relating to RTP
capabilities and parameters, operational statistics, media authentication via
Certificates and Identity Providers (IdP) and compatibility with the WebRTC 1.0 API.
RTP dictionaries are described in <a href="#rtcrtpdictionaries*">Section 9</a>, the
Statistics API is described in <a href="#statistics-api">Section 15</a>, the Identity
API is described in <a href="#identity-api">Section 16</a>, the Certificate API is
described in <a href="#certificate-api">Section 17</a>, privacy and security
considerations are described in <a href="#privacy-security">Section 18</a>,
an event summary is provided
in <a href="#event-summary">Section 19</a>, WebRTC 1.0 compatibility issues are
discussed in <a href="#webrtc-compat*">Section 20</a>, and complete examples are
provided in <a href="#examples*">Section 21</a>.</p>
<section id="conformance">
<p>This specification defines conformance criteria that apply to a single
product: the <a>user agent</a> that implements the interfaces that it
contains.</p>
<p>Conformance requirements phrased as algorithms or specific steps may be
implemented in any manner, so long as the end result is equivalent. In
particular, the algorithms defined in this specification are intended to be
easy to follow, and not intended to be performant.</p>
<p>Implementations that use ECMAScript to implement the APIs defined in
this specification MUST implement them in a manner consistent with the
ECMAScript Bindings defined in the Web IDL specification [[!WEBIDL-1]], as
this specification uses that specification and terminology.</p>
<p>Implementation of the following interfaces is mandatory:
<code><a>RTCIceGatherer</a></code> (<a href="#rtcicegatherer*">Section 2</a>),
<code><a>RTCIceTransport</a></code> (<a href="#rtcicetransport*">Section 3</a>),
<code><a>RTCDtlsTransport</a></code> (<a href="#rtcdtlstransport*">Section 4</a>),
<code><a>RTCRtpSender</a></code> (<a href="#rtcrtpsender*">Section 5</a>),
<code><a>RTCRtpReceiver</a></code> (<a href="#rtcrtpreceiver*">Section 6</a>),
<code><a>RTCDtmfSender</a></code> (<a href="#rtcdtmfsender*">Section 10</a>),
<code><a>RTCDataChannel</a></code> (<a href="#rtcdatachannel*">Section 11</a>),
<code><a>RTCSctpTransport</a></code> (<a href="#sctp-transport*">Section 12</a>) and
<code><a>RTCCertificate</a></code> (<a href="#certificate-api">Section 17</a>).
Since the <code>send</code> and <code>receive</code> methods are mandatory-to-implement, the
RTP dictionaries (<a href="#rtcrtpdictionaries*">Section 9</a>) that these methods depend on are also
mandatory-to-implement. Mandatory-to-implement statistics are described in
<a href="#mandatory-to-implement-stats">Section 15.3</a>.</p>
<p>Implementation of the following interfaces is optional:
<code><a>RTCIceTransportController</a></code> (<a href="#rtcicetransportcontroller*">Section 7</a>),
<code><a>RTCRtpListener</a></code> (<a href="#rtcrtplistener*">Section 8</a>),
<code><a>RTCQuicTransport</a></code> (<a href="#quic-transport*">Section 13</a>),
<code><a>RTCQuicStream</a></code> (<a href="#quicstream*">Section 14</a>) and
<code><a>RTCIdentity</a></code> (<a href="#identity-api">Section 16</a>).
</section>
<section>
<h3>Terminology</h3>
<p>The <code><a href=
"http://dev.w3.org/html5/spec/webappapis.html#eventhandler">EventHandler</a></code>
interface, representing a callback used for event handlers, and the <a href=
"http://dev.w3.org/html5/spec/webappapis.html#errorevent"><code><dfn>ErrorEvent</dfn></code></a>
interface are defined in [[!HTML5]].</p>
<p>The concepts <dfn><a href=
"http://dev.w3.org/html5/spec/webappapis.html#queue-a-task">queue a task</a></dfn>,
<dfn><a href=
"http://dev.w3.org/html5/spec/webappapis.html#fire-a-simple-event">fires a simple
event</a></dfn> and <dfn><a href=
"http://dev.w3.org/html5/spec/webappapis.html#networking-task-source">networking
task source</a></dfn> are defined in [[!HTML5]].</p>
<p>The terms <dfn>event</dfn>, <dfn><a href=
"http://dev.w2.org/html5/spec/webappapis.html#event-handlers">event
handlers</a></dfn> and <dfn><a href=
"http://dev.w3.org/html5/spec/webappapis.html#event-handler-event-type">event
handler event types</a></dfn> are defined in [[!HTML5]].</p>
<p>The terms <dfn>MediaStream</dfn>, <dfn>MediaStreamTrack</dfn>, and
<dfn>MediaStreamConstraints</dfn> are defined in [[!GETUSERMEDIA]].</p>
<p>The term <code><a>RTCStatsType</a></code>
is defined in [[!WEBRTC-STATS]].</p>
<p>When referring to exceptions, the terms <dfn><a
href="https://www.w3.org/TR/WebIDL-1/#dfn-throw">throw</a></dfn> and
<dfn data-dfn-for="exception"><a href=
"https://www.w3.org/TR/WebIDL-1/#dfn-create-exception">create</a></dfn> are
defined in [[!WEBIDL-1]].</p>
<p>The terms <dfn data-lt="fulfill|fulfillment">fulfilled</dfn>, <dfn
data-lt="reject|rejection|rejecting">rejected</dfn>,
<dfn data-lt="resolve|resolves">resolved</dfn>, <dfn>pending</dfn> and
<dfn>settled</dfn> used in the context of Promises are defined in
[[!ECMASCRIPT-6.0]].</p>
<p>In this specification the term <dfn>user agent</dfn> refers to any
implementation; the term <dfn>browser</dfn> specifically refers to browser
implementations.</p>
<p>The <dfn>RTCIceCredentialType</dfn> enum and <dfn>RTCOauthCredential</dfn>
dictionary is defined in [[!WEBRTC10]].</p>
</section>
<section>
<h3>Scope</h3>
<p>For Scalable Video Coding (SVC), the terms single-session transmission
(<dfn>SST</dfn>) and multi-session transmission (<dfn>MST</dfn>) are defined in
[[RFC6190]]. This specification only supports <a>SST</a> but not <a>MST</a>. The
term Single Real-time transport protocol stream Single Transport (<dfn>SRST</dfn>),
defined in [[RFC7656]] Section 3.7, refers to a Scalable Video Coding
(<dfn>SVC</dfn>) implementation that transmits all layers within
a single transport, using a single Real-time Transport Protocol (RTP) stream
and synchronization source (SSRC). The term Multiple RTP stream Single Transport
(<dfn>MRST</dfn>), also defined in [[RFC7656]] Section 3.7, refers to an
implementation that transmits all layers within a single transport, using
multiple RTP streams with a distinct SSRC for each layer. This specification
supports SVC codecs that can only utilize <a>SRST</a> transport (such as VP8
and VP9) as well as implementations of codecs (such as H.264/SVC or HEVC)
that support <a>SRST</a> transport. Also, sending of simulcast
is supported. SVC codecs supporting <a>MRST</a> transport
(such as H.264/SVC and HEVC) can also be supported, along with reception of
simulcast. However, these features should be considered experimental, since
implementation experience is limited.</p>
<div class="note">
At the time of publication, there were two ORTC implementations supporting
simulcast reception. Since neither implementation supported [[!RFC6051]],
mechanisms needed to be provided to handle intermingling of received simulcast
streams due to reordering. The ORTC Lib implementation deals with this by
utilizing timing heuristics as well as "hidden" receivers for each received
simulcast stream, with each "hidden" receiver producing a "hidden" track. The
"hidden" tracks are then mixed internally to produce a single
<code><a>MediaStreamTrack</a></code> <code>RTCRtpReceiver.track</code>.
</div>
</section>
</section>
<section id="rtcicegatherer*">
<h2><dfn>RTCIceGatherer</dfn> Interface</h2>
<p>The <code>RTCIceGatherer</code> gathers local host, server reflexive
and relay candidates, as well as enabling the retrieval of local Interactive
Connectivity Establishment (ICE) parameters which can be exchanged in signaling. By
enabling an endpoint to use a set of local candidates to construct multiple
<code><a>RTCIceTransport</a></code> objects, the <code><a>RTCIceGatherer</a></code>
enables support for scenarios such as parallel forking.</p>
<section id="rtcicegatherer-overview*">
<h3>Overview</h3>
<p>An <code><a>RTCIceGatherer</a></code> instance can be associated to multiple
<code><a>RTCIceTransport</a></code> objects. The <code><a>RTCIceGatherer</a></code>
does not prune local candidates until at least one
<code><a>RTCIceTransport</a></code> object has become associated and all associated
<code><a>RTCIceTransport</a></code> objects are in the <code>completed</code> or
<code>failed</code> state.</p>
<p>As noted in [[!RFC5245]] Section 7.1.2.2, an incoming connectivity check
contains an <code>ICE-CONTROLLING</code> or <code>ICE-CONTROLLED</code> attribute,
depending on the role of the ICE agent initiating the check. Since an
<code><a>RTCIceGatherer</a></code> object does not have a role, it cannot determine
whether to respond to an incoming connectivity check with a 487 (Role Conflict)
error; however, it can validate that an incoming connectivity check utilizes the
correct local username fragment and password, and if not, can respond with an 401
(Unauthorized) error, as described in [[!RFC5389]] Section 10.1.2.</p>
<p>For incoming connectivity checks that pass validation, the
<code><a>RTCIceGatherer</a></code> <em class="rfc2119" title="MUST">MUST</em>
buffer the incoming connectivity checks so as to be able to provide them to
associated <code><a>RTCIceTransport</a></code> objects so that they can
respond.</p>
</section>
<section id="rtcicegatherer-operation*">
<h3>Operation</h3>
<p>An <code><a>RTCIceGatherer</a></code> instance is constructed from an
<code><a>RTCIceGatherOptions</a></code> object.</p>
<p>An <code><a>RTCIceGatherer</a></code> object in the <code>closed</code> state
can be garbage-collected when it is no longer referenced.</p>
</section>
<section id="rtcicegatherer-interface-definition*">
<h3>Interface Definition</h3>
<div>
<pre class="idl">[ Constructor (RTCIceGatherOptions options), Exposed=Window]
interface RTCIceGatherer : RTCStatsProvider {
readonly attribute RTCIceComponent component;
readonly attribute RTCIceGathererState state;
static sequence<RTCIceServer> getDefaultIceServers ();
void close ();
void gather (optional RTCIceGatherOptions options);
RTCIceParameters getLocalParameters ();
sequence<RTCIceCandidate> getLocalCandidates ();
RTCIceGatherer createAssociatedGatherer ();
attribute EventHandler onstatechange;
attribute EventHandler onerror;
attribute EventHandler onlocalcandidate;
};</pre>
<section>
<h2>Constructors</h2>
<p>To validate the <code>options</code> argument in the <code><a>RTCIceGatherer</a></code>
constructor, implementations MUST run the following steps:</p>
<ol>
<li>
<p>Let <var>options</var> be the argument passed in the constructor.</p>
</li>
<li>
<p>Let <var>servers</var> be the value of <code><var>options</var>.iceServers</code>.</p>
</li>
<li>
<p>Let <var>validatedServers</var> be an empty list.</p>
</li>
<li>
<p>Run the following steps for each element in <var>servers</var>:</p>
<ol>
<li>
<p>Let <var>server</var> be the current list element.</p>
</li>
<li>
<p>If <code><var>server</var>.urls</code> is a string,
let <code><var>server</var>.urls</code> be a list
consisting of just that string.</p>
</li>
<li>
<p>For each <var>url</var> in
<code><var>server</var>.urls</code> run the following steps:
<ol>
<li>
<p>Parse the <var>url</var> using the generic URI syntax
defined in [[!RFC3986]] and obtain the
<var>scheme name</var>. If the parsing based
on the syntax defined in [[!RFC3986]] fails,
<a>throw</a> a <code>SyntaxError</code>. If
the <var>scheme name</var> is not implemented
by the browser <a>throw</a> a
<code>NotSupportedError</code>. If
<var>scheme name</var> is <code>turn</code> or
<code>turns</code>, and parsing the
<var>url</var> using the syntax defined in
[[!RFC7064]] fails, <a>throw</a> a
<code>SyntaxError</code>. If <var>scheme
name</var> is <code>stun</code> or
<code>stuns</code>, and parsing the
<var>url</var> using the syntax defined in
[[!RFC7065]] fails, <a>throw</a> a
<code>SyntaxError</code>. </p>
</li>
<li>
<p>If <var>scheme name</var> is <code>turn</code> or
<code>turns</code>, and either of
<code><var>server</var>.username</code> or
<code><var>server</var>.credential</code> are omitted,
then <a>throw</a> an <code>InvalidAccessError</code>.</p>
</li>
<li>
<p>If <var>scheme name</var> is <code>turn</code> or
<code>turns</code>, and
<code><var>server</var>.credentialType</code> is
<code>"password"</code>, and
<code><var>server</var>.credential</code> is not a
<span class="idlMemberType"><a>DOMString</a></span>, then
<a>throw</a> an <code>InvalidAccessError</code> and abort these
steps.</p>
</li>
<li>
<p>If <var>scheme name</var> is <code>turn</code> or
<code>turns</code>, and
<code><var>server</var>.credentialType</code> is
<code>"oauth"</code>, and
<code><var>server</var>.credential</code> is not an
<a>RTCOAuthCredential</a>, then <a>throw</a> an
<code>InvalidAccessError</code> and abort these steps.</p>
</li>
</ol>
</li>
<li>
<p>Append <var>server</var> to <var>validatedServers</var>.</p>
</li>
</ol>
<p>Let <var>validatedServers</var> be the <dfn id="ice-servers-list">
ICE servers list</dfn>.</p>
<dl data-link-for="RTCIceGatherer" data-dfn-for="RTCIceGatherer" class=
"constructors">
<dt><code><a>RTCIceGatherer</a></code></dt>
<dd>
<table class="parameters">
<tbody>
<tr>
<th>Parameter</th>
<th>Type</th>
<th>Nullable</th>
<th>Optional</th>
<th>Description</th>
</tr>
<tr>
<td class="prmName">options</td>
<td class="prmType"><code><a>RTCIceGatherOptions</a></code></td>
<td class="prmNullFalse"><span role="img" aria-label=
"False">✘</span></td>
<td class="prmOptFalse"><span role="img" aria-label=
"False">✘</span></td>
<td class="prmDesc"></td>
</tr>
</tbody>
</table>
</dd>
</dl>
</section>
<section>
<h2>Attributes</h2>
<dl data-link-for="RTCIceGatherer" data-dfn-for="RTCIceGatherer" class=
"attributes">
<dt><dfn>component</dfn> of type <span class=
"idlAttrType"><a>RTCIceComponent</a></span>, readonly</dt>
<dd>
<p>The component-id of the <code><a>RTCIceGatherer</a></code> object. In
<code><a>RTCIceGatherer</a></code> objects returned by
<code><a>createAssociatedGatherer</a>()</code> the value of the
<code><a>component</a></code> attribute is <code>rtcp</code>. In all other
<code><a>RTCIceGatherer</a></code> objects, the value of the
<code><a>component</a></code> attribute is <code>rtp</code>.</p>
</dd>
<dt><dfn><code>state</code></dfn> of type <span class=
"idlAttrType"><a>RTCIceGathererState</a></span>, readonly</dt>
<dd>
<p>The current state of the ICE gatherer.</p>
</dd>
<dt><dfn><code>onstatechange</code></dfn> of type <span class=
"idlAttrType"><a>EventHandler</a></span></dt>
<dd>
<p>This event handler, of event handler event type
<code><a>statechange</a></code>, <em class="rfc2119" title="MUST">MUST</em>
be fired any time the <code><a>RTCIceGathererState</a></code> changes.</p>
</dd>
<dt><dfn><code>onerror</code></dfn> of type <span class=
"idlAttrType"><a>EventHandler</a></span></dt>
<dd>
<p>This event handler, of event handler event type
<code><a>icecandidateerror</a></code>, <em class="rfc2119" title=
"MUST">MUST</em> be fired if an error occurs in the gathering of ICE
candidates (such as if TURN credentials are invalid).</p>
</dd>
<dt><dfn><code>onlocalcandidate</code></dfn> of type <span class=
"idlAttrType"><a>EventHandler</a></span></dt>
<dd>
<p>This event handler, of event handler event type
<code><a>icecandidate</a></code>, uses the
<code><a>RTCIceGathererEvent</a></code> interface.
It receives events when a new local ICE candidate
is available. Since ICE candidate gathering begins
once an <code><a>RTCIceGatherer</a></code> object is
created, <code>candidate</code> events are queued
until an <code>onlocalcandidate</code> event handler
is assigned. When the final candidate is gathered,
a <code>candidate</code> event occurs with an
<code>RTCIceCandidateComplete</code> emitted.</p>
</dd>
</dl>
</section>
<section>
<h2>Methods</h2>
<dl data-link-for="RTCIceGatherer" data-dfn-for="RTCIceGatherer" class=
"methods">
<dt><dfn><code>getDefaultIceServers</code></dfn></dt>
<dd>
<p>Returns a list of ICE servers that are configured into the
browser. A browser might be configured to use local or private
STUN or TURN servers. This method allows an application to learn
about these servers and optionally use them.</p>
<p class="fingerprint">This list is likely to be persistent and
is the same across origins. It thus increases the
fingerprinting surface of the browser. In privacy-sensitive
contexts, browsers can consider mitigations such as only
providing this data to whitelisted origins (or not providing it
at all.)</p>
<p class="note">Since the use of this information is left to
the discretion of application developers, configuring a user
agent with these defaults does not per se increase a user's
ability to limit the exposure of their IP addresses.</p>
</dd>
<dt><dfn><code>close</code></dfn></dt>
<dd>
<p>Prunes all local candidates, and closes the port. Associated
<code><a>RTCIceTransport</a></code> objects transition to the
<code>disconnected</code> state (unless they were in the
<code>failed</code> state). Calling <code>close()</code> when
<code>state</code> is <code>closed</code> has no effect.</p>
<div>
<em>No parameters.</em>
</div>
<div>
<em>Return type:</em> <code>void</code>
</div>
</dd>
<dt><dfn><code>gather</code></dfn></dt>
<dd>
<p>Gather ICE candidates. If <var>options</var> is omitted, utilize the
value of <var>options</var> passed in the constructor. If
<code>state</code> is <code>closed</code>, <a>throw</a> an
<code>InvalidStateError</code>.</p>
<table class="parameters">
<tbody>
<tr>
<th>Parameter</th>
<th>Type</th>
<th>Nullable</th>
<th>Optional</th>
<th>Description</th>
</tr>
<tr>
<td class="prmName">options</td>
<td class="prmType"><code><a>RTCIceGatherOptions</a></code></td>
<td class="prmNullFalse"><span role="img" aria-label=
"False">✘</span></td>
<td class="prmOptTrue"><span role="img" aria-label=
"True">✔</span></td>
<td class="prmDesc"></td>
</tr>
</tbody>
</table>
<div>
<em>Return type:</em> <code>void</code>
</div>
</dd>
<dt><code>getLocalParameters</code></dt>
<dd>
<p><dfn>getLocalParameters()</dfn> obtains the ICE
parameters of the <code><a>RTCIceGatherer</a></code>.
If <code>state</code> is <code>closed</code>, <a>throw</a> an
<code>InvalidStateError</code>.</p>
<div>
<em>No parameters.</em>
</div>
<div>
<em>Return type:</em> <code><a>RTCIceParameters</a></code>
</div>
</dd>
<dt><dfn><code>getLocalCandidates</code></dfn></dt>
<dd>
<p>Retrieve the sequence of valid local candidates associated with the
<code><a>RTCIceGatherer</a></code>. This retrieves all unpruned local
candidates currently known (except for peer reflexive candidates), even if
an <code><a>onlocalcandidate</a></code> event hasn't been processed yet.
Prior to calling <code><a>gather</a>()</code> an empty list will be
returned. If <code>state</code> is <code>closed</code>, <a>throw</a> an
<code>InvalidStateError</code>.</p>
<div>
<em>No parameters.</em>
</div>
<div>
<em>Return type:</em>
<code>sequence</code><<code><a>RTCIceCandidate</a></code>>
</div>
</dd>
<dt><dfn><code>createAssociatedGatherer</code></dfn></dt>
<dd>
<p>Create an associated <code><a>RTCIceGatherer</a></code> for RTCP, with
the same <code><a>RTCIceParameters</a></code> and
<code><a>RTCIceGatherOptions</a></code>. If <code>state</code> is
<code>closed</code>, <a>throw</a> an <code>InvalidStateError</code>. If
an <code><a>RTCIceGatherer</a></code> calls the method more than once, or
if <code><a>component</a></code> is <code>rtcp</code>, <a>throw</a> an
<code>InvalidStateError</code>.</p>
<div>
<em>No parameters.</em>
</div>
<div>
<em>Return type:</em> <code><a>RTCIceGatherer</a></code>
</div>
</dd>
</dl>
</section>
</div>
</section>
<section id="rtciceparameters*">
<h3><dfn>RTCIceParameters</dfn> Dictionary</h3>
<p>The <code>RTCIceParameters</code> dictionary includes the ICE username
fragment and password and other ICE-related parameters.</p>
<div>
<pre class="idl">dictionary RTCIceParameters {
DOMString usernameFragment;
DOMString password;
boolean iceLite;
};</pre>
<section>
<h2>Dictionary <a class="idlType">RTCIceParameters</a> Members</h2>
<dl data-link-for="RTCIceParameters" data-dfn-for="RTCIceParameters" class=
"dictionary-members">
<dt><dfn><code>usernameFragment</code></dfn> of type <span class=
"idlMemberType"><a>DOMString</a></span></dt>
<dd>
<p>ICE username fragment.</p>
</dd>
<dt><dfn><code>password</code></dfn> of type <span class=
"idlMemberType"><a>DOMString</a></span></dt>
<dd>
<p>ICE password.</p>
</dd>
<dt><dfn><code>iceLite</code></dfn> of type <span class=
"idlMemberType"><a>boolean</a></span></dt>
<dd>
<p>If only ICE-lite is supported (<code>true</code>) or not
(<code>false</code> or unset). Since [[!RTCWEB-TRANSPORT]] Section 3.4
requires browser support for full ICE, <code><a>iceLite</a></code> will
only be <code>true</code> for a remote peer such as a gateway.
<code>getLocalParameters().iceLite</code> MUST NOT be set.</p>
</dd>
</dl>
</section>
</div>
</section>
<section id="rtcicecandidate*">
<h3><dfn>RTCIceCandidate</dfn> Dictionary</h3>
<p>The <code>RTCIceCandidate</code> dictionary includes information relating
to an ICE candidate.</p>
<pre class="example highlight">{
foundation: "abcd1234",
priority: 1694498815,
ip: "192.0.2.33",
protocol: "udp",
port: 10000,
type: "host"
};
</pre>
<div>
<p>The <dfn><code>RTCIceGatherCandidate</code></dfn> provides either an
<code><a>RTCIceCandidate</a></code> or an <code><a>RTCIceCandidateComplete</a></code>
indication that candidate gathering is complete.</p>
<pre class="idl">
typedef (RTCIceCandidate or RTCIceCandidateComplete) RTCIceGatherCandidate;</pre>
<div class="idlTypedefDesc"></div>
</div>
<div>
<pre class="idl">dictionary RTCIceCandidate {
required DOMString foundation;
required unsigned long priority;
required DOMString ip;
required RTCIceProtocol protocol;
required unsigned short port;
required RTCIceCandidateType type;
RTCIceTcpCandidateType tcpType;
DOMString relatedAddress;
unsigned short relatedPort;
};</pre>
<section>
<h2>Dictionary <a class="idlType">RTCIceCandidate</a> Members</h2>
<dl data-link-for="RTCIceCandidate" data-dfn-for="RTCIceCandidate" class=
"dictionary-members">
<dt><dfn><code>foundation</code></dfn> of type <span class=
"idlMemberType"><a>DOMString</a></span>, required</dt>
<dd>
<p>A unique identifier that allows ICE to correlate candidates that appear
on multiple <code><a>RTCIceTransport</a></code>s.</p>
</dd>
<dt><dfn><code>priority</code></dfn> of type <span class=
"idlMemberType"><a>unsigned long</a></span>, required</dt>
<dd>
<p>The assigned priority of the candidate. This is automatically populated
by the browser.</p>
</dd>
<dt><dfn><code>ip</code></dfn> of type <span class=
"idlMemberType"><a>DOMString</a></span>, required</dt>
<dd>
<p>The IP address of the candidate.</p>
</dd>
<dt><dfn><code>protocol</code></dfn> of type <span class=
"idlMemberType"><a>RTCIceProtocol</a></span>, required</dt>
<dd>
<p>The protocol of the candidate (udp/tcp).</p>
</dd>
<dt><dfn><code>port</code></dfn> of type <span class=
"idlMemberType"><a>unsigned short</a></span>, required</dt>
<dd>
<p>The port for the candidate.</p>
</dd>
<dt><dfn><code>type</code></dfn> of type <span class=
"idlMemberType"><a>RTCIceCandidateType</a></span>, required</dt>
<dd>
<p>The type of candidate.</p>
</dd>
<dt><dfn><code>tcpType</code></dfn> of type <span class=
"idlMemberType"><a>RTCIceTcpCandidateType</a></span></dt>
<dd>
<p>The type of TCP candidate. For UDP candidates, this
attribute is unset.</p>
</dd>
<dt><code>relatedAddress</code> of type <span class=
"idlMemberType"><a>DOMString</a></span></dt>
<dd>
<p>For candidates that are derived from others, such as relay or reflexive
candidates, the <dfn><code>relatedAddress</code></dfn> refers to the
candidate that these are derived from. For host candidates, the
<code><a>relatedAddress</a></code> is unset.</p>
</dd>
<dt><code>relatedPort</code> of type <span class="idlMemberType"><a>unsigned
short</a></span></dt>
<dd>
<p>For candidates that are derived from others, such as relay or reflexive
candidates, the <dfn><code>relatedPort</code></dfn> refers to the host
candidate that these are derived from. For host candidates, the
<code><a>relatedPort</a></code> is unset.</p>
</dd>
</dl>
</section>
</div>
<section>
<h4><dfn>RTCIceProtocol</dfn> Enum</h4>
<p>The <code>RTCIceProtocol</code> includes the protocol of the ICE
candidate.</p>
<div>
<pre class="idl">enum RTCIceProtocol {
"udp",
"tcp"
};</pre>
<table data-link-for="RTCIceProtocol" data-dfn-for="RTCIceProtocol" class=
"simple">
<tbody>
<tr>
<th colspan="2">Enumeration description</th>
</tr>
<tr>
<td><dfn><code id="idl-def-RTCIceProtocol.udp">udp</code></dfn></td>
<td>
<p>A UDP candidate, as described in [[!RFC5245]].</p>
</td>
</tr>
<tr>
<td><dfn><code id="idl-def-RTCIceProtocol.tcp">tcp</code></dfn></td>
<td>
<p>A TCP candidate, as described in [[!RFC6544]].</p>
</td>
</tr>
</tbody>
</table>
</div>
</section>
<section>
<h4><dfn>RTCIceTcpCandidateType</dfn> Enum</h4>
<p>The <code>RTCIceTcpCandidateType</code> includes the type of the
ICE TCP candidate, as described in [[!RFC6544]]. Browsers MUST gather active TCP
candidates and only active TCP candidates. Servers and other endpoints MAY gather
active, passive or so candidates.</p>
<div>
<pre class="idl">enum RTCIceTcpCandidateType {
"active",
"passive",
"so"
};</pre>
<table data-link-for="RTCIceTcpCandidateType" data-dfn-for=
"RTCIceTcpCandidateType" class="simple">
<tbody>
<tr>
<th colspan="2">Enumeration description</th>
</tr>
<tr>
<td><dfn><code id=
"idl-def-RTCIceTcpCandidateType.active">active</code></dfn></td>
<td>
<p>An active TCP candidate is one for which the transport will attempt
to open an outbound connection but will not receive incoming connection
requests.</p>
</td>
</tr>
<tr>
<td><dfn><code id=
"idl-def-RTCIceTcpCandidateType.passive">passive</code></dfn></td>
<td>
<p>A passive TCP candidate is one for which the transport will receive
incoming connection attempts but not attempt a connection.</p>
</td>
</tr>
<tr>
<td><dfn><code id=
"idl-def-RTCIceTcpCandidateType.so">so</code></dfn></td>
<td>
<p>An so candidate is one for which the transport will attempt to open
a connection simultaneously with its peer.</p>
</td>
</tr>
</tbody>
</table>
</div>
</section>
<section>
<h4><dfn>RTCIceCandidateType</dfn> Enum</h4>
<p>The <code>RTCIceCandidateType</code> includes the type of the ICE
candidate as defined in [[!RFC5245]] section 15.1.</p>
<div>
<pre class="idl">enum RTCIceCandidateType {
"host",
"srflx",
"prflx",
"relay"
};</pre>
<table data-link-for="RTCIceCandidateType" data-dfn-for="RTCIceCandidateType"
class="simple">
<tbody>
<tr>
<th colspan="2">Enumeration description</th>
</tr>
<tr>
<td><dfn><code id=
"idl-def-RTCIceCandidateType.host">host</code></dfn></td>
<td>
<p>A host candidate, as defined in Section 4.1.1.1 of [[!RFC5245]].</p>
</td>
</tr>
<tr>
<td><dfn><code id=
"idl-def-RTCIceCandidateType.srflx">srflx</code></dfn></td>
<td>
<p>A server reflexive candidate, as defined in Section 4.1.1.2 of
[[!RFC5245]].</p>
</td>
</tr>
<tr>
<td><dfn><code id=
"idl-def-RTCIceCandidateType.prflx">prflx</code></dfn></td>
<td>
<p>A peer reflexive candidate, as defined in Section 4.1.1.2 of
[[!RFC5245]].</p>
</td>
</tr>
<tr>
<td><dfn><code id=
"idl-def-RTCIceCandidateType.relay">relay</code></dfn></td>
<td>
<p>A relay candidate, as defined in Section 7.1.3.2.1 of
[[!RFC5245]].</p>
</td>
</tr>
</tbody>
</table>
</div>
</section>
</section>
<section id="rtcicecandidatecomplete*">
<h3><dfn>RTCIceCandidateComplete</dfn> Dictionary</h3>
<p><code>RTCIceCandidateComplete</code> is a dictionary signifying that
all <code>RTCIceCandidate</code>s are gathered.</p>
<div>
<pre class="idl">dictionary RTCIceCandidateComplete {
boolean complete = true;
};</pre>
<section>
<h2>Dictionary <a class="idlType">RTCIceCandidateComplete</a> Members</h2>
<dl data-link-for="RTCIceCandidateComplete" data-dfn-for=
"RTCIceCandidateComplete" class="dictionary-members">
<dt><dfn><code>complete</code></dfn> of type <span class=
"idlMemberType"><a>boolean</a></span>, defaulting to <code>true</code></dt>
<dd>
<p>This attribute is always present and set to <code>true</code>,
indicating that ICE candidate gathering is complete.</p>
</dd>
</dl>
</section>
</div>
</section>
<section id="rtcicegathererstate*">
<h3><dfn>RTCIceGathererState</dfn> Enum</h3>
<p><code>RTCIceGathererState</code> represents the current state of the
ICE gatherer.</p>
<div>
<pre class="idl">enum RTCIceGathererState {
"new",
"gathering",
"complete",
"closed"
};</pre>
<table data-link-for="RTCIceGathererState" data-dfn-for="RTCIceGathererState"
class="simple">
<tbody>
<tr>
<th colspan="2">Enumeration description</th>
</tr>
<tr>
<td><dfn><code id="idl-def-RTCIceGathererState.new">new</code></dfn></td>
<td>
<p>The object has been created but <code>gather()</code> has not been
called.</p>
</td>
</tr>
<tr>
<td><dfn><code id=
"idl-def-RTCIceGathererState.gathering">gathering</code></dfn></td>
<td>
<p><code>gather()</code> has been called, and the
<code><a>RTCIceGatherer</a></code> is in the process of gathering
candidates (which includes adding new candidates and removing invalidated
candidates).</p>
</td>
</tr>
<tr>
<td><dfn><code id=
"idl-def-RTCIceGathererState.complete">complete</code></dfn></td>
<td>
<p>The <code><a>RTCIceGatherer</a></code> has completed gathering. Events
such as adding, updating or removing an interface, or adding, changing or
removing a TURN server will cause the state to go back to
<code>gathering</code> before re-entering <code>complete</code> once all
candidate changes are finalized.</p>
</td>
</tr>
<tr>
<td><dfn><code id=
"idl-def-RTCIceGathererState.closed">closed</code></dfn></td>
<td>
<p>The <code>closed</code> state can only be entered when
the <code><a>RTCIceGatherer</a></code> has been closed
intentionally by calling <code>close()</code>. This is a
terminal state.</p>
</td>
</tr>
</tbody>
</table>
</div>
</section>
<section>
<h4><dfn>RTCIceGathererIceErrorEvent</dfn></h4>
<p>The <code><a>icecandidateerror</a></code> event of the
<code><a>RTCIceGatherer</a></code> object uses the
<code><a>RTCIceGathererIceErrorEvent</a></code> interface.</p>
<div>
<pre class="idl">
[ Constructor (DOMString type, RTCIceGathererIceErrorEventInit eventInitDict), Exposed=Window]
interface RTCIceGathererIceErrorEvent : Event {
readonly attribute RTCIceCandidate? hostCandidate;
readonly attribute DOMString url;
readonly attribute unsigned short errorCode;
readonly attribute USVString statusText;
};</pre>
<section>
<h2>Constructors</h2>
<dl data-link-for="RTCIceGathererIceErrorEvent" data-dfn-for=
"RTCIceGathererIceErrorEvent" class="constructors">
<dt><code>RTCIceGathererIceErrorEvent</code></dt>
<dd>
<table class="parameters">
<tbody>
<tr>
<th>Parameter</th>
<th>Type</th>
<th>Nullable</th>
<th>Optional</th>
<th>Description</th>
</tr>
<tr>
<td class="prmName">type</td>
<td class="prmType"><code>DOMString</code></td>
<td class="prmNullFalse"><span role="img" aria-label=
"False">✘</span></td>
<td class="prmOptFalse"><span role="img" aria-label=
"False">✘</span></td>
<td class="prmDesc"></td>
</tr>
<tr>
<td class="prmName">eventInitDict</td>
<td class="prmType">
<code><a>RTCIceGathererIceErrorEventInit</a></code></td>
<td class="prmNullFalse"><span role="img" aria-label=
"False">✘</span></td>
<td class="prmOptFalse"><span role="img" aria-label=
"False">✘</span></td>
<td class="prmDesc"></td>
</tr>
</tbody>
</table>
</dd>
</dl>
</section>
<section>
<h2>Attributes</h2>
<dl data-link-for="RTCIceGathererIceErrorEvent" data-dfn-for=
"RTCIceGathererIceErrorEvent" class="attributes">
<dt><dfn><code>hostCandidate</code></dfn> of type <span class=
"idlAttrType"><a>RTCIceCandidate</a></span>, readonly , nullable</dt>
<dd>
<p>The <code><a>RTCIceCandidate</a></code> used to communicate with the
STUN or TURN server. On a multihomed system, multiple interfaces may be
used to contact the server, and this attribute allows the application to
figure out on which one the failure occurred. If the browser is in a
privacy mode disallowing host candidates, this attribute will be null.</p>
<p>If use of multiple interfaces has been prohibited for privacy reasons,
<code><a>hostCandidate</a></code> will be null.</p>
</dd>
<dt><dfn><code>url</code></dfn> of type <span class=
"idlAttrType"><a>DOMString</a></span>, readonly , nullable</dt>
<dd>
<p>The <code><a>url</a></code> attribute is the STUN or TURN URL
identifying the server on which the failure ocurred.</p>
</dd>
<dt><dfn><code>errorCode</code></dfn> of type <span class=
"idlAttrType"><a>unsigned short</a></span>, readonly</dt>
<dd>
<p>The <code><a>errorCode</a></code> attribute is the numeric STUN error
code returned by the STUN or TURN server [[STUN-PARAMETERS]].</p>
<p>If no host candidate can reach the server, <code><a>errorCode</a></code>
will be set to a value of 701, as this does not conflict with the STUN
error code range, and <code><a>hostCandidate</a></code> will be null. This
error is only fired once per server URL while in the
<code><a>RTCIceGathererState</a></code> of <code>gathering</code>.</p>
</dd>
<dt><dfn><code>statusText</code></dfn> of type <span class=
"idlAttrType"><a>USVString</a></span>, readonly</dt>
<dd>
<p>The STUN reason text returned by the STUN or TURN server [[STUN-PARAMETERS]].</p>
<p>If the server could not be reached, <code><a>statusText</a></code> will
be set to an implementation-specific value providing details about the
error.</p>
</dd>
</dl>
</section>
</div>
<div>
<p>The <dfn><code>RTCIceGathererIceErrorEventInit</code></dfn> dictionary
provides information on ICE gathering errors.</p>
<pre class="idl">
dictionary RTCIceGathererIceErrorEventInit : EventInit {
RTCIceCandidate hostCandidate;
DOMString url;
required unsigned short errorCode;
USVString errorText;
};</pre>
<section>
<h2>Dictionary <a class="idlType">RTCIceGathererIceErrorEventInit</a>
Members</h2>
<dl data-link-for="RTCIceGathererIceErrorEventInit" data-dfn-for=
"RTCIceGathererIceErrorEventInit" class="dictionary-members">
<dt><dfn><code>hostCandidate</code></dfn> of type <span class=
"idlMemberType"><a>RTCIceCandidate</a></span></dt>
<dd>
<p>The <code><a>RTCIceCandidate</a></code> used to communicate with the
STUN or TURN server.</p>
</dd>
<dt><dfn><code>url</code></dfn> of type <span class=
"idlMemberType"><a>DOMString</a></span></dt>
<dd>
<p>The <code>url</code> attribute is the STUN or TURN URL identifying the
server on which the failure ocurred.</p>
</dd>
<dt><dfn><code>errorCode</code></dfn> of type <span class=
"idlMemberType"><a>unsigned short</a></span></dt>
<dd>
<p>The <code>errorCode</code> attribute is the numeric STUN error code
returned by the STUN or TURN server [[STUN-PARAMETERS]].</p>