IceGatherer States

[aboba]

While we have RTCIceTransportState to indicate the state of the RTCIceTransport, there is no equivalent state variable for the RTCIceGatherer.

When the RTCIceGatherer object is constructed, it begins to actively gather candidates. When "end of candidates" is delivered, candidate gathering has been completed.

However, recently continuous gathering has been proposed:
http://juberti.github.io/draughts/nombis/draft-uberti-mmusic-nombis.html

Where continuous gathering is allowed, there can be an intermediate state where the RTCIceGatherer is idle. The addition of an IceGathererStates attribute could allow this to be indicated:

enum IceGathererStates {
"gathering", // actively gathering candidates
"idle", // candidates gathered but awake for connectivity checks
"sleeping" // non warm / used candidates have been pruned
};

In addition, an event would be needed for changes to the IceGatherer state:

partial interface RTCIceGatherer {
attribute EventHandler? onstatechanged;
};

[aboba]

Here is a more detailed proposal:

partial interface RTCIceGatherer {
readonly attribute RTCIceGathererState state;
attribute EventHandler? ongathererstatechange;
};

ongathererstatechange of type EventHandler, , nullable
This event handler, of event handler type gathererstatechange, uses the RTCIceGathererStateChangedEvent interface. It must be supported by all objects implementing the RTCIceGatherer interface. It is called any time the RTCIceGathererState changes.

5.4 enum RTCIceGathererState

RTCIceGathererState represents the current state of the ICE gatherer.

enum RTCIceGathererState {
"gathering",
"idle",
"sleeping"
};

Enumeration description

gathering
The RTCIceGatherer object is actively gathering candidates.

idle
The RTCIceGatherer object has completed gathering, but will respond to connectivity checks (even before RTCIceTransport.start() is called).

sleeping
ICE connectivity checks have been completed, and non-nominated candidate pairs have been pruned.

5.5 RTCIceGathererStateChangedEvent

The icegathererstatechange event of the RTCIceGatherer object uses the RTCIceGathererStateChangedEvent interface.

Firing an RTCIceGathererStateChangedEvent event named e with an RTCIceGathererState state means that an event with the name e, which does not bubble (except where otherwise stated) and is not cancelable (except where otherwise stated), and which uses the RTCIceGathererStateChangedEvent interface with the state attribute set to the new RTCIceGathererState, must be created and dispatched at the given target.

dictionary RTCIceGathererStateChangedEventInit : EventInit {
RTCIceGathererState? state;
};

[Constructor(DOMString type, RTCIceGathererStateChangedEventInit eventInitDict)]
interface RTCIceGathererStateChangedEvent : Event {
readonly attribute RTCIceGathererState state;
};

5.5.1 Attributes

state of type RTCIceGathererState, readonly
The state attribute is the new RTCIceGathererState that caused the event.

5.5.2 Dictionary RTCIceGathererStateChangedEventInit Members

state of type RTCIceGathererState, nullable
The state attribute is the new RTCIceGathererState that caused the event.

[aboba]

Note that WebRTC 1.0 has RTCIceGatheringState:

enum RTCIceGatheringState {
"new",
"gathering",
"complete"
};

new The object was just created, and no networking has occurred yet.
gathering The ICE engine is in the process of gathering candidates for this RTCPeerConnection.
complete The ICE engine has completed gathering. Events such as adding a new interface or a new TURN server will cause the state to go back to gathering.

For backward compatibility, I would propose the following for RTCIceGathererState:

enum RTCIceGathererState {
"new",
"gathering",
"complete",
"sleeping"
};

new
The object was just created, and no gathering has occurred yet.

gathering
The RTCIceGatherer is in the process of gathering candidates.

complete
The RTCIceGatherer has completed gathering. Events such as adding a new interface or a new TURN server will cause the state to go back to gathering.

sleeping
ICE connectivity checks have been completed, and non-nominated candidate pairs have been pruned. Events such as adding a new interface or a new TURN server will cause the state to go back to gathering.

[aboba]

Iñaki has questioned the relevance of the "sleeping" state:
http://lists.w3.org/Archives/Public/public-ortc/2015Jan/0001.html

This raised questions about the relationship between the IceTransport and IceGatherer objects. Several clarifications may be useful to add to section 5.1:

5.1 Overview

An RTCIceGatherer instance is associated to an RTCIceTransport. However, the RTCIceGatherer object responds to connectivity checks even before an RTCIceTransport is constructed or RTCIceTransport.start() is called. Note that the pruning of candidate pairs within an RTCIceTransport does not affect the availability of candidates within an RTCIceGatherer object.

[aboba]

Here is the proposed text for Section 5.4:

5.4 enum RTCIceGathererState

RTCIceGathererState represents the current state of the ICE gatherer.

enum RTCIceGathererState {
"new",
"gathering",
"complete"
};

Enumeration description

new
The object was just created, and no gathering has occurred yet.

gathering
The RTCIceGatherer is in the process of gathering candidates.

complete
The RTCIceGatherer has completed gathering. Events such as adding a new interface or a new TURN server will cause the state to go back to gathering.

[robin-raymond]

Just to make it more clear:

new
The object was just created, and no gathering has occurred yet.

gathering
The RTCIceGatherer is in the process of gathering candidates (which includes adding newly found candidates or removing invalidated candidates).

complete

The RTCIceGatherer has completed gathering. Events such as adding, updating, or removing an interface or a new, changing, or removing TURN server will cause the state to go back to gathering before entering complete again once all gathered candidate changes are finalized.

[aboba]

Also add an entry to the RTCIceGatherer event table in Section 15:

Event name Interface Fired when...
icegatherstatechange RTCIceGathererStateChangedEvent The RTCIceGathererState changed.