Skip to main content

​
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
​
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
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)
    }
}()

​
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

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

Build docs developers (and LLMs) love

Get started for freeTalk to us