4.1.20. onicecandidate Event

4.1.20. onicecandidate Event

The onicecandidate event is dispatched to the application in two situations: (1) when the ICE agent has discovered a new allowed local ICE candidate during ICE gathering, as outlined in Section 3.5.1 and subject to the restrictions discussed in Section 3.5.3, or (2) when an ICE gathering phase completes. The event contains a single IceCandidate object, as defined in Section 3.5.2.1.

In the first case, the newly discovered candidate is reflected in the IceCandidate object, and all of its fields MUST be non-null. This candidate will also be added to the current and/or pending local description according to the rules defined for Trickle ICE.

In the second case, the event's IceCandidate object MUST have its candidate field set to null to indicate that the current gathering phase is complete, i.e., there will be no further onicecandidate events in this phase. However, the IceCandidate's ufrag field MUST be specified to indicate which ICE candidate generation is ending. The IceCandidate's "m=" section index and MID fields MAY be specified to indicate that the event applies to a specific "m=" section, or set to null to indicate it applies to all "m=" sections in the current ICE candidate generation. This event can be used by the application to generate an end-of-candidates indication, as defined in [RFC8838], Section 13.