IceGatherer States #164

Closed
aboba opened this Issue Dec 3, 2014 · 6 comments

Projects

None yet

2 participants

@aboba
Contributor
aboba commented Dec 3, 2014

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 aboba added the 1.1 label Dec 3, 2014
@aboba
Contributor
aboba commented Dec 4, 2014

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 aboba added 1.0 and removed 1.1 labels Jan 5, 2015
@aboba
Contributor
aboba commented Jan 5, 2015

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
Contributor
aboba commented Jan 5, 2015

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
Contributor
aboba commented Jan 12, 2015

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
Contributor

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.

@robin-raymond robin-raymond pushed a commit that referenced this issue Jan 22, 2015
Robin Raymond Updated Section 8.3 to reflect proposed matching rules, reflecting:
#48

Update to the Statistics API, reflecting:
#85

Update on 'automatic' use of scalable video coding, as noted in:
#156

Update to the H.264 parameters, as noted in:
#158

Update to the 'Big Picture', as noted in:
#159

Added support for maxptime, as noted in:
#160

Changed 'RTCIceTransportEvent' to 'RTCIceGathererEvent' as noted in:
#161

Update to RTCRtpUnhandledEvent as noted in:
#163

Added support for RTCIceGatherer.state as noted in:
#164

Revised the text relating to RTCIceTransport.start() as noted in:
#166

Added text relating to DTLS interoperability with WebRTC 1.0, as noted in:
#167

Revised the text relating to RTCDtlsTransport.start() as noted in:
#168

Clarified handling of incoming connectivity checks by the RTCIceGatherer as noted in:
#170

Added a reference to the ICE consent specification, as noted in:
#171
a927ecf
@aboba
Contributor
aboba commented May 1, 2015

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

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

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment