Interface Definition

[Exposed=Window]
interface RTCIceController : EventTarget {
  constructor();

  readonly attribute RTCIceRole role;
  RTCIceCandidatePair? getSelectedCandidatePair();

  attribute EventHandler oncandidatepairadded;
  attribute EventHandler oncandidatepairupdated;
  attribute EventHandler oncandidatepairswitched;
  attribute EventHandler oncandidatepairdestroyed;

  attribute EventHandler onicepingproposed;
  attribute EventHandler oniceswitchproposed;
  attribute EventHandler onicepruneproposed;

  Promise<undefined> sendIcePing(RTCIceCandidatePair candidatePair);
  Promise<undefined> switchToCandidatePair(RTCIceCandidatePair candidatePair);
  Promise<undefined> pruneCandidatePairs(sequence<RTCIceCandidatePair> candidatePairs);
};

Constructor

constructor()

When the constructor is invoked, the [= user agent =] MUST run the following steps:

1. Let |controller:RTCIceController| be a newly created {{RTCIceController}} object.
2. Let |controller| have an [[\IceRole]] internal slot, initialized to {{RTCIceRole/"unknown"}}.
3. Let |controller| have a [[\SelectedCandidatePair]] internal slot, initialized to null.
4. Let |controller| have a [[\PeerConnection]] internal slot, initialized to null.
5. Let |controller| have a [[\ProposalPending]] internal slot, initialized to false.
6. Return |controller|.

No parameters.

Attributes

role of type {{RTCIceRole}}, readonly

The {{role}} attribute MUST, on getting, return the value of the {{RTCIceController/[[IceRole]]}} internal slot.

oncandidatepairadded of type {{EventHandler}}

The event type of this event handler is {{candidatepairadded}}.

When the [= ICE agent =] has found a candidate pair, the [= user agent =] MUST queue a task to [= fire an event =] named {{candidatepairadded}} using the {{RTCIceCandidatePairEvent}} interface with the {{RTCIceCandidatePairEvent/candidatePair}} attribute set to the found candidate pair.

oncandidatepairupdated of type {{EventHandler}}

The event type of this event handler is {{candidatepairupdated}}.

When the [= ICE agent =] completes a connectivity check on a candidate pair, or when a candidate pair undergoes a state change, the [= user agent =] MUST queue a task to [= fire an event =] named {{candidatepairupdated}} using the {{RTCIceCandidatePairUpdateEvent}} interface. This may have been a consequence of the application invoking {{RTCIceController/sendIcePing()}}.

The [= user agent =] MAY choose to batch together these events to reduce the volume and increase the efficiency of the updates.

oncandidatepairswitched of type {{EventHandler}}

The event type of this event handler is {{candidatepairswitched}}.

This event is fired when the [= ICE agent =] indicates that the selected candidate pair for the transport has changed, causing {{RTCIceTransport}} to [= update the selected candidate pair =]. The change may have been a consequence of the application invoking {{RTCIceController/switchToCandidatePair()}}.

oncandidatepairdestroyed of type {{EventHandler}}

The event type of this event handler is {{candidatepairdestroyed}}.

When the [= ICE agent =] destroys a candidate pair, the [= user agent =] MUST queue a task to [= fire an event =] named {{candidatepairdestroyed}} using the {{RTCIceCandidatePairEvent}} interface with the {{RTCIceCandidatePairEvent/candidatePair}} attribute set to the destroyed candidate pair. This may have been a consequence of the application invoking {{RTCIceController/pruneCandidatePairs()}}.

onicepingproposed of type {{EventHandler}}

The event type of this event handler is {{icepingproposed}}.

When the [= ICE agent =] has selected a candidate pair to ping for a connectivity check, but before the ping has actually been sent, the [= user agent =] MUST [= propose an ICE ping =].

This event handler MUST not be fired when the application has requested a connectivity check by invoking {{RTCIceController/sendIcePing()}}, which does not cause the [= ICE agent =] to select a candidate pair for a connectivity check.

oniceswitchproposed of type {{EventHandler}}

The event type of this event handler is {{iceswitchproposed}}.

When the [=ICE agent =] has selected a candidate pair to switch the transport to, but before the switch has actually occurred, the [= user agent =] MUST [= propose an ICE switch =].

This event handler MUST not be fired when the application has requested a candidate pair switch by invoking {{RTCIceController/switchToCandidatePair()}}, which does not cause the [= ICE agent =] to select a candidate pair to switch to.

onicepruneproposed of type {{EventHandler}}

The event type of this event handler is {{icepruneproposed}}.

When the [=ICE agent =] has selected one or more candidate pairs to prune, but before the pruning has actually occurred, the [= user agent =] MUST [= propose an ICE pruning =].

This event handler MUST not be fired when the application has requested to prune candidate pairs by invoking {{RTCIceController/pruneCandidatePairs()}}, which does not cause the [= ICE agent =] to select candidate pairs to prune.

Methods

getSelectedCandidatePair

The {{getSelectedCandidatePair}} method returns the candidate pair currently selected for the ICE transport. This method MUST return the value of the {{RTCIceController/[[SelectedCandidatePair]]}} slot. {{getSelectedCandidatePair}} returns null before at least one {{candidatepairswitched}} event is fired.

sendIcePing

The {{sendIcePing}} method attempts to send an ICE connectivity check on the provided candidate pair. When the {{sendIcePing}} method is invoked, the [= user agent =] MUST run the following steps:

1. Let |candidatePair:RTCIceCandidatePair| be the method's first argument.

2. Let |controller:RTCIceController| be the {{RTCIceController}} object on which {{sendIcePing}} is invoked.

3. If |controller|.{{RTCIceController/[[ProposalPending]]}} is true, return a [= rejected =] promise with a newly [= exception/created =] {{InvalidStateError}}.

4. Let |connection:RTCPeerConnection| be the {{RTCPeerConnection}} object stored in |controller|.{{RTCIceController/[[PeerConnection]]}}.

5. Validate |candidatePair| by running the [= validate() algorithm =] to which |connection| and a new sequence containing |candidatePair| are supplied as arguments.

6. Let |p:Promise| be a new promise.

7. Run the following steps in parallel:

   1. If either the local or remote candidate pair identified by |candidatePair| is [= administratively prohibited =], [= resolve =] |p| with undefined.

      A candidate is administratively prohibited if the [= user agent =] has decided not to allow connection attempts to this address, as described further in {{RTCPeerConnection/addIceCandidate()}}.

   2. If the current {{RTCIceCandidatePairReport/state}} of the candidate pair {{RTCStatsIceCandidatePairState}} is {{RTCStatsIceCandidatePairState/"failed"}}, [= reject =] |p| with a newly [= exception/created =] {{InvalidStateError}}.

   3. If X connectivity checks have been sent in the previous Y duration of time, reject |p| with a newly [= exception/created =] {{QuotaExceededError}}.

      The exact nature of this rate-limiting check is TBD.

   4. Instruct the [= ICE agent=] to construct and send a STUN check from |candidatePair|.{{RTCIceCandidatePair/local}} to |candidatePair|.{{RTCIceCandidatePair/remote}}.

   5. [= Resolve =] |p| with undefined.

8. Return |p|.

switchToCandidatePair

The {{switchToCandidatePair}} method attempts to switch the transport to the provided candidate pair. When the {{switchToCandidatePair}} method is invoked, the [= user agent =] MUST run the following steps:

1. Let |candidatePair:RTCIceCandidatePair| be the method's first argument.

2. Let |controller:RTCIceController| be the {{RTCIceController}} object on which {{switchToCandidatePair}} is invoked.

3. If |controller|.{{RTCIceController/[[ProposalPending]]}} is true, return a [= rejected =] promise with a newly [= exception/created =] {{InvalidStateError}}.

4. Let |connection:RTCPeerConnection| be the {{RTCPeerConnection}} object stored in |controller|.{{RTCIceController/[[PeerConnection]]}}.

5. Validate |candidatePair| by running the [= validate() algorithm =] to which |connection| and a new sequence containing |candidatePair| are supplied as arguments.

6. Let |p:Promise| be a new promise.

7. Run the following steps in parallel:

   1. If the current {{RTCIceCandidatePairReport/state}} of the candidate pair {{RTCStatsIceCandidatePairState}} is not {{RTCStatsIceCandidatePairState/"succeeded"}}, reject |p| with a newly [= exception/created =] {{InvalidStateError}}.

      Attempting to switch to a candidate pair with either a local or remote candidate that is [= administratively prohibited =] will also lead to an abort at this stage, because connectivity checks are prohibited on such a candidate pair, so it will never transition to the {{RTCStatsIceCandidatePairState/"succeeded"}} state.

   2. Instruct the [= ICE agent =] to change the selected candidate pair to |candidatePair|.

   3. [= Resolve =] |p| with undefined.

8. Return |p|.

pruneCandidatePairs

The {{pruneCandidatePairs}} method attempts to prune the provided candidate pairs. When the {{pruneCandidatePairs}} method is invoked, the [= user agent =] MUST run the following steps:

1. Let |candidatePairs:sequence<RTCIceCandidatePair>| be the method's first argument.

2. Let |controller:RTCIceController| be the {{RTCIceController}} object on which {{pruneCandidatePairs}} is invoked.

3. If |controller|.{{RTCIceController/[[ProposalPending]]}} is true, return a [= rejected =] promise with a newly [= exception/created =] {{InvalidStateError}}.

4. Let |connection:RTCPeerConnection| be the {{RTCPeerConnection}} object stored in |controller|.{{RTCIceController/[[PeerConnection]]}}.

5. Validate |candidatePairs| by running the [= validate() algorithm =] to which |connection| and |candidatePairs| are supplied as arguments.

6. Let |p:Promise| be a new promise.

7. Run the following steps in parallel:

   1. Instruct the [= ICE agent =] to prune the candidate pairs in |candidatePairs|.

   2. [= Resolve =] |p| with undefined.

8. Return |p|.

RTCIceCandidatePairEvent

The {{RTCIceController/candidatepairadded}}, {{RTCIceController/candidatepairswitched}}, and {{RTCIceController/candidatepairdestroyed}} events use the {{RTCIceCandidatePairEvent}} interface.

[Exposed=Window]
interface RTCIceCandidatePairEvent : Event {
  constructor(DOMString type, RTCIceCandidatePairEventInit eventInitDict);
  readonly attribute RTCIceCandidatePair candidatePair;
};

dictionary RTCIceCandidatePairEventInit : EventInit {
  required RTCIceCandidatePair candidatePair;
};

RTCIceCandidatePairUpdateEvent

The {{RTCIceController/candidatepairupdated}} event uses the {{RTCIceCandidatePairUpdateEvent}} interface.

[Exposed=Window]
interface RTCIceCandidatePairUpdateEvent : Event {
  constructor(DOMString type, RTCIceCandidatePairUpdateEventInit eventInitDict);
  readonly attribute RTCIceCandidatePair candidatePair;
  readonly attribute RTCIceCandidatePairReport report;
};

dictionary RTCIceCandidatePairUpdateEventInit : EventInit {
  required RTCIceCandidatePair candidatePair;
  required RTCIceCandidatePairReport report;
};

[Exposed=Window]
interface RTCIceCandidatePairReport {
  constructor(RTCIceCandidatePairReportInit reportInitDict);
  readonly attribute boolean connected;
  readonly attribute RTCStatsIceCandidatePairState state;
  readonly attribute RTCIceCandidatePairWriteState writeState;
  readonly attribute DOMHighResTimeStamp? lastPingSentTimestamp;
  readonly attribute DOMHighResTimeStamp? lastPingResponseReceivedTimestamp;
  readonly attribute DOMHighResTimeStamp? lastPingReceivedTimestamp;
  readonly attribute DOMHighResTimeStamp? lastPacketReceivedTimestamp;
  readonly attribute unsigned long long pingsSent;
  sequence<RTCRoundTripTimeSample> getRoundTripTimeSamples();
};

dictionary RTCIceCandidatePairReportInit {
  required boolean connected;
  required RTCStatsIceCandidatePairState state;
  required RTCIceCandidatePairWriteState writeState;
  DOMHighResTimeStamp lastPingSentTimestamp;
  DOMHighResTimeStamp lastPingResponseReceivedTimestamp;
  DOMHighResTimeStamp lastPingReceivedTimestamp;
  DOMHighResTimeStamp lastPacketReceivedTimestamp;
  required unsigned long long pingsSent;
  sequence<RTCRoundTripTimeSample> roundTripTimeSamples;
};

dictionary RTCRoundTripTimeSample {
  required DOMHighResTimeStamp timestamp;
  required double value;
};

enum RTCIceCandidatePairWriteState {
  "init",
  "writeable",
  "unreliable",
  "timeout"
};

RTCIcePingProposalEvent

The {{RTCIceController/icepingproposed}} event uses the {{RTCIcePingProposalEvent}} interface.

The [= user agent =] MAY continue to propose further connectivity checks in the future for the same or other candidate pairs.

[Exposed=Window]
interface RTCIcePingProposalEvent : Event {
  constructor(DOMString type, RTCIcePingProposalEventInit eventInitDict);
  readonly attribute RTCIceCandidatePair candidatePair;
  readonly attribute DOMHighResTimeStamp? lastPingSentTimestamp;
  readonly attribute DOMHighResTimeStamp? earliestNextPingTimestamp;
};

dictionary RTCIcePingProposalEventInit : EventInit {
  required RTCIceCandidatePair candidatePair;
  DOMHighResTimeStamp lastPingSentTimestamp;
  DOMHighResTimeStamp earliestNextPingTimestamp;
};

RTCIceSwitchProposalEvent

The {{RTCIceController/iceswitchproposed}} event uses the {{RTCIceSwitchProposalEvent}} interface.

The [= user agent =] MAY continue to propose further switches in the future to the same or other candidate pairs.

[Exposed=Window]
interface RTCIceSwitchProposalEvent : Event {
  constructor(DOMString type, RTCIceSwitchProposalEventInit eventInitDict);
  readonly attribute RTCIceCandidatePair candidatePair;
  readonly attribute RTCIceSwitchReason reason;
  readonly attribute RTCIceRecheck? recheck;
};

dictionary RTCIceSwitchProposalEventInit : EventInit {
  required RTCIceCandidatePair candidatePair;
  required RTCIceSwitchReason reason;
  RTCIceRecheck recheck;
};

enum RTCIceSwitchReason {
  "remote-candidate-generation-change",
  "network-preference-change",
  "new-connection-from-local-candidate",
  "new-connection-from-remote-candidate",
  "new-connection-from-unknown-remote-address",
  "nomination-on-controlled-side",
  "data-received",
  "connect-state-change",
  "selected-connection-destroyed",
  "scheduled-recheck"
};

dictionary RTCIceRecheck {
  required RTCIceSwitchReason reason;
  required DOMHighResTimeStamp earliestRecheckTimestamp;
};

RTCIcePruneProposalEvent

The {{RTCIceController/icepruneproposed}} event uses the {{RTCIcePruneProposalEvent}} interface.

The [= user agent =] MAY continue to propose pruning of the same or other candidate pairs in the future.

[Exposed=Window]
interface RTCIcePruneProposalEvent : Event {
  constructor(DOMString type, RTCIcePruneProposalEventInit eventInitDict);
  sequence<RTCIceCandidatePair> getCandidatePairs();
};

dictionary RTCIcePruneProposalEventInit : EventInit {
  required sequence<RTCIceCandidatePair> candidatePairs;
};

{{RTCConfiguration}} Extensions

The {{RTCConfiguration}} dictionary is extended with an {{RTCConfiguration/iceController}} member.

partial dictionary RTCConfiguration {
  RTCIceController iceController;
};

Operation

Certain additional steps need to be performed during the construction of an {{RTCPeerConnection}} and when {{RTCPeerConnection/setConfiguration()}} is invoked to establish its association with an {{RTCIceController}}, if supplied. Both operations achieve this through an extension to [= Set the configuration =] operation.