ICEGatherer

Gathers local host, server reflexive and relay ICE candidates for WebRTC connectivity

Overview

The ICEGatherer gathers local host, server reflexive and relay candidates, as well as enabling the retrieval of local Interactive Connectivity Establishment (ICE) parameters which can be exchanged in signaling.

This is part of the ORTC API. It is not meant to be used together with the basic WebRTC API.

Type Definition

icegatherer.go

type ICEGatherer struct {
    // Contains internal state management for ICE gathering
}

Constructor

NewICEGatherer

Creates a new ICEGatherer with the specified options.

icegatherer.go

func (api *API) NewICEGatherer(opts ICEGatherOptions) (*ICEGatherer, error)

opts · ICEGatherOptions · required

Configuration options for the ICE gatherer

Show ICEGatherOptions fields

ICEServers · []ICEServer

List of ICE servers (STUN/TURN) to use for gathering

ICEGatherPolicy · ICETransportPolicy

Policy for gathering candidates (all, relay, nohost)

ICECandidatePoolSize · uint8

Size of the prefetched ICE pool

return · *ICEGatherer, error

Returns a new ICEGatherer instance or an error if creation fails

Example:

api := webrtc.NewAPI()
gatherer, err := api.NewICEGatherer(webrtc.ICEGatherOptions{
    ICEServers: []webrtc.ICEServer{
        {
            URLs: []string{"stun:stun.l.google.com:19302"},
        },
    },
})
if err != nil {
    panic(err)
}

Methods

Gather

Starts gathering ICE candidates.

icegatherer.go

func (g *ICEGatherer) Gather() error

return · error

Returns nil on success, or an error if gathering cannot be started

Example:

err := gatherer.Gather()
if err != nil {
    panic(err)
}

GetLocalParameters

Returns the ICE parameters of the ICEGatherer.

icegatherer.go

func (g *ICEGatherer) GetLocalParameters() (ICEParameters, error)

return · ICEParameters, error

Returns the local ICE parameters (username fragment, password) or an error

Show ICEParameters structure

UsernameFragment · string

ICE username fragment

Password · string

ICE password

ICELite · bool

Whether ICE-lite mode is enabled

Example:

params, err := gatherer.GetLocalParameters()
if err != nil {
    panic(err)
}
fmt.Printf("Username: %s, Password: %s\n", params.UsernameFragment, params.Password)

GetLocalCandidates

Returns the sequence of valid local candidates associated with the ICEGatherer.

icegatherer.go

func (g *ICEGatherer) GetLocalCandidates() ([]ICECandidate, error)

return · []ICECandidate, error

Returns a slice of local ICE candidates or an error

Example:

candidates, err := gatherer.GetLocalCandidates()
if err != nil {
    panic(err)
}
for _, candidate := range candidates {
    fmt.Printf("Candidate: %s\n", candidate.String())
}

State

Returns the current state of the ICE gatherer.

icegatherer.go

func (g *ICEGatherer) State() ICEGathererState

return · ICEGathererState

The current ICE gatherer state (New, Gathering, Complete, Closed)

Example:

state := gatherer.State()
fmt.Printf("Gatherer state: %s\n", state)

OnLocalCandidate

Sets an event handler which fires when a new local ICE candidate is available.

The handler will be called with a nil pointer when gathering is finished.

icegatherer.go

func (g *ICEGatherer) OnLocalCandidate(f func(*ICECandidate))

f · func(*ICECandidate) · required

Callback function that receives ICE candidates. Called with nil when gathering completes.

Example:

gatherer.OnLocalCandidate(func(candidate *ICECandidate) {
    if candidate == nil {
        fmt.Println("Gathering complete")
        return
    }
    fmt.Printf("New candidate: %s\n", candidate.String())
})

OnStateChange

Sets a handler that fires when the ICEGatherer state changes.

icegatherer.go

func (g *ICEGatherer) OnStateChange(f func(ICEGathererState))

f · func(ICEGathererState) · required

Callback function that receives state change notifications

Example:

gatherer.OnStateChange(func(state webrtc.ICEGathererState) {
    fmt.Printf("Gatherer state changed to: %s\n", state)
})

Close

Prunes all local candidates and closes the ports.

icegatherer.go

func (g *ICEGatherer) Close() error

return · error

Returns nil on success, or an error if closing fails

Example:

err := gatherer.Close()
if err != nil {
    panic(err)
}

GracefulClose

Prunes all local candidates and closes the ports, waiting for goroutines to complete.

This is only safe to call outside of ICEGatherer callbacks or if in a callback, in its own goroutine.

icegatherer.go

func (g *ICEGatherer) GracefulClose() error

return · error

Returns nil on success, or an error if closing fails

Example:

go func() {
    err := gatherer.GracefulClose()
    if err != nil {
        log.Printf("Error closing gatherer: %v", err)
    }
}()

Related Types

ICEAddressRewriteRule

Represents a rule for remapping candidate addresses.

icegatherer.go

type ICEAddressRewriteRule struct {
    External        []string
    Local           string
    Iface           string
    CIDR            string
    AsCandidateType ICECandidateType
    Mode            ICEAddressRewriteMode
    Networks        []NetworkType
}

External · []string

External IP addresses to use

Local · string

Local IP address to match

Iface · string

Network interface name to match

CIDR · string

CIDR notation to match local addresses

AsCandidateType · ICECandidateType

Type to use for rewritten candidates

Mode · ICEAddressRewriteMode

Whether to replace or append candidates

Networks · []NetworkType

Network types to apply this rule to

ICEAddressRewriteMode

Controls whether a rule replaces or appends candidates.

icegatherer.go

type ICEAddressRewriteMode byte

const (
    ICEAddressRewriteModeUnspecified ICEAddressRewriteMode = iota
    ICEAddressRewriteReplace
    ICEAddressRewriteAppend
)

States

The ICEGatherer can be in one of the following states:

• ICEGathererStateNew: Initial state
• ICEGathererStateGathering: Currently gathering candidates
• ICEGathererStateComplete: Gathering has completed
• ICEGathererStateClosed: Gatherer has been closed

Usage Example

Complete Example

package main

import (
    "fmt"
    "github.com/pion/webrtc/v4"
)

func main() {
    // Create API
    api := webrtc.NewAPI()
    
    // Create ICE gatherer with STUN server
    gatherer, err := api.NewICEGatherer(webrtc.ICEGatherOptions{
        ICEServers: []webrtc.ICEServer{
            {
                URLs: []string{"stun:stun.l.google.com:19302"},
            },
        },
    })
    if err != nil {
        panic(err)
    }
    defer gatherer.Close()
    
    // Set up event handlers
    gatherer.OnLocalCandidate(func(candidate *webrtc.ICECandidate) {
        if candidate == nil {
            fmt.Println("Gathering complete")
            return
        }
        fmt.Printf("New candidate: %s\n", candidate.String())
    })
    
    gatherer.OnStateChange(func(state webrtc.ICEGathererState) {
        fmt.Printf("State changed: %s\n", state)
    })
    
    // Start gathering
    if err = gatherer.Gather(); err != nil {
        panic(err)
    }
    
    // Get local parameters
    params, err := gatherer.GetLocalParameters()
    if err != nil {
        panic(err)
    }
    fmt.Printf("ICE Parameters - User: %s, Pass: %s\n", 
        params.UsernameFragment, params.Password)
    
    // Wait for gathering to complete...
    select {}
}

See Also

• ICETransport - Manages ICE connectivity
• DTLSTransport - Handles DTLS encryption over ICE
• PeerConnection - High-level WebRTC API