GatheringState

ICE candidate gathering state enumeration

Overview

The GatheringState enum describes the current state of the ICE candidate gathering process. It tracks whether the agent is discovering local network addresses and querying STUN/TURN servers.

Type Definition

type GatheringState int

States

GatheringStateNew

const GatheringStateNew GatheringState = iota + 1

Candidate gathering has not yet started. The agent has been created but GatherCandidates() has not been called.

GatheringStateGathering

const GatheringStateGathering

The agent is actively gathering candidates. This includes:

• Discovering local network interfaces
• Creating host candidates
• Querying STUN servers for server reflexive candidates
• Allocating TURN relays for relay candidates

GatheringStateComplete

const GatheringStateComplete

Candidate gathering has completed. All local addresses have been discovered and all STUN/TURN queries have finished or timed out.

GatheringStateUnknown

const GatheringStateUnknown GatheringState = 0

Represents an unknown or uninitialized gathering state.

Methods

String

func (t GatheringState) String() string

Returns the string representation of the gathering state.

Returns:

• "new" for GatheringStateNew
• "gathering" for GatheringStateGathering
• "complete" for GatheringStateComplete
• Error string for unknown states

State Transitions

Transitions:

1. New → Gathering: When GatherCandidates() is called
2. Gathering → Complete: When all gathering operations finish
3. Complete → Gathering: When using continual gathering and new interfaces appear

Usage Example

Basic Gathering

agent, _ := ice.NewAgentWithOptions(
    ice.WithUrls([]*stun.URI{stunURL}),
)

// Monitor gathering with OnCandidate
agent.OnCandidate(func(c ice.Candidate) {
    if c == nil {
        log.Println("Gathering complete")
        return
    }
    log.Printf("New candidate: %s", c.String())
})

// Start gathering
if err := agent.GatherCandidates(); err != nil {
    panic(err)
}

// Check state programmatically
state, _ := agent.GetGatheringState()
log.Printf("Current gathering state: %s", state.String())

Continual Gathering

When continual gathering is enabled, the state can transition back from Complete to Gathering when new network interfaces are detected:

agent, _ := ice.NewAgentWithOptions(
    ice.WithContinualGatheringPolicy(ice.GatherContinually),
    ice.WithNetworkMonitorInterval(2 * time.Second),
)

// With continual gathering:
// New → Gathering → Complete → Gathering → Complete → ...

Gathering Timeout

You can configure how long to wait for STUN server responses:

agent, _ := ice.NewAgentWithOptions(
    ice.WithUrls([]*stun.URI{stunURL}),
    ice.WithSTUNGatherTimeout(5 * time.Second), // Default: 5s
)

Gathering Complete Signal

The agent signals gathering completion by calling the OnCandidate handler with a nil candidate:

agent.OnCandidate(func(c ice.Candidate) {
    if c == nil {
        // Gathering is complete
        log.Println("All candidates gathered")
        
        // Safe to send candidates to remote peer
        candidates, _ := agent.GetLocalCandidates()
        sendToRemote(candidates)
    } else {
        // New candidate discovered
        log.Printf("Candidate: %s", c.String())
    }
})

Continual Gathering Policy

type ContinualGatheringPolicy int

const (
    GatherOnce        ContinualGatheringPolicy = iota
    GatherContinually
)

GatherOnce (Default)

Gathering completes after the initial phase and stops monitoring for new interfaces.

GatherContinually

The agent continuously monitors network interfaces and gathers new candidates when changes are detected.

agent, _ := ice.NewAgentWithOptions(
    ice.WithContinualGatheringPolicy(ice.GatherContinually),
)

Related

• Agent - ICE Agent with gathering methods
• ConnectionState - Connection state enum
• Candidate Types - Types of ICE candidates