3.5.1. ICE Gathering Overview

3.5.1. ICE Gathering Overview

JSEP gathers ICE candidates as needed by the application. Collection of ICE candidates is referred to as a gathering phase, and this is triggered either by the addition of a new or recycled "m=" section to the local session description or by new ICE credentials in the description, indicating an ICE restart. Use of new ICE credentials can be triggered explicitly by the application or implicitly by the JSEP implementation in response to changes in the ICE configuration.

When the ICE configuration changes in a way that requires a new gathering phase, a 'needs-ice-restart' bit is set. When this bit is set, calls to the createOffer API will generate new ICE credentials. This bit is cleared by a call to the setLocalDescription API with new ICE credentials from either an offer or an answer, i.e., from either a locally or remotely initiated ICE restart.

When a new gathering phase starts, the ICE agent will notify the application that gathering is occurring through a state change event. Then, when each new ICE candidate becomes available, the ICE agent will supply it to the application via an onicecandidate event; these candidates will also automatically be added to the current and/or pending local session description. Finally, when all candidates have been gathered, a final onicecandidate event will be dispatched to signal that the gathering process is complete.

Note that gathering phases only gather the candidates needed by new/recycled/restarting "m=" sections; other "m=" sections continue to use their existing candidates. Also, if an "m=" section is bundled (either by a successful bundle negotiation or by being marked as bundle-only), then candidates will be gathered and exchanged for that "m=" section if and only if its MID item is a BUNDLE-tag, as described in [RFC8843].