Re: Issue 164: IceGatherer states

While we have RTCIceTransportState to indicate the state of the RTCIceTransport, there is no equivalent state variable for the RTCIceGatherer, nor is there an event when the state of the RTCIceGatherer changes.

Here is a proposal:


Partial interface RTCIceGatherer : RTCStatsProvider {
    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.
state of type RTCIceGathererState<http://internaut.com:8080/~baboba/ortc/ortc-5-01-2015.html#idl-def-RTCIceGathererState>, readonly

The current state of the ICE gatherer.

5.4 enum RTCIceGathererState

RTCIceGathererState represents the current state of the ICE gatherer.

enum RTCIceGathererState {

    "new<http://internaut.com:8080/~baboba/ortc/ortc-5-01-2015.html#idl-def-RTCIceGathererState.new>",

    "gathering<http://internaut.com:8080/~baboba/ortc/ortc-5-01-2015.html#idl-def-RTCIceGathererState.gathering>",

    "complete<http://internaut.com:8080/~baboba/ortc/ortc-5-01-2015.html#idl-def-RTCIceGathererState.complete>",

    "closed<http://internaut.com:8080/~baboba/ortc/ortc-5-01-2015.html#idl-def-RTCIceGathererState.closed>"

};
Enumeration description

new


The object was just created, and no gathering has occurred yet. Since RTCIceGatherer objects gather upon construction, this state will only exist momentarily.

gathering


The RTCIceGatherer is in the process of gathering candidates (which includes adding new candidates and removing invalidated candidates).

complete


The RTCIceGatherer 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 gathering before re-entering "complete" once all candidate changes are finalized.

closed


The RTCIceGatherer has been closed intentionally or as the result of an error.


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<http://internaut.com:8080/~baboba/ortc/ortc-5-01-2015.html#widl-RTCIceGathererStateChangedEventInit-state>;

};

[Constructor(DOMString type, RTCIceGathererStateChangedEventInit eventInitDict)]

interface RTCIceGathererStateChangedEvent : Event<http://internaut.com:8080/~baboba/ortc/ortc-5-01-2015.html#dfn-event> {

    readonly    attribute RTCIceGathererState state<http://internaut.com:8080/~baboba/ortc/ortc-5-01-2015.html#widl-RTCIceGathererStateChangedEvent-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.