Agent

ICE Agent implementation for establishing peer-to-peer connections

Overview

The Agent represents the ICE agent responsible for gathering candidates, performing connectivity checks, and establishing peer-to-peer connections according to RFC 5245.

Creating an Agent

NewAgent (Deprecated)

func NewAgent(config *AgentConfig) (*Agent, error)

Creates a new Agent using the legacy configuration struct.

Deprecated: Use NewAgentWithOptions instead for better flexibility and forward compatibility.

Parameters:

config · *AgentConfig

Configuration for the agent. See AgentConfig for details.

Returns: (*Agent, error)

NewAgentWithOptions

func NewAgentWithOptions(opts ...AgentOption) (*Agent, error)

Creates a new Agent using functional options. This is the recommended way to create agents.

Parameters:

opts · ...AgentOption

Variable number of configuration options. See Agent Options for available options.

Returns: (*Agent, error)

Example:

Basic Usage

import (
    "github.com/pion/ice/v4"
    "github.com/pion/stun/v3"
)

// Create agent with STUN server
stunURL, _ := stun.ParseURI("stun:stun.l.google.com:19302")
agent, err := ice.NewAgentWithOptions(
    ice.WithUrls([]*stun.URI{stunURL}),
)
if err != nil {
    panic(err)
}
defer agent.Close()

Key Methods

GatherCandidates

func (a *Agent) GatherCandidates() error

Starts the candidate gathering process. This discovers available local addresses and queries STUN/TURN servers.

GetLocalCandidates

func (a *Agent) GetLocalCandidates() ([]Candidate, error)

Returns all gathered local candidates.

AddRemoteCandidate

func (a *Agent) AddRemoteCandidate(cand Candidate) error

Adds a remote candidate received from the peer. This triggers connectivity checks for candidate pairs.

Parameters:

cand · Candidate

Remote candidate to add. Can be nil (ignored).

GetSelectedCandidatePair

func (a *Agent) GetSelectedCandidatePair() (*CandidatePair, error)

Returns the currently selected candidate pair, or nil if no pair is selected.

SetRemoteCredentials

func (a *Agent) SetRemoteCredentials(remoteUfrag, remotePwd string) error

Sets the remote agent’s ICE credentials.

Parameters:

remoteUfrag · string · required

Remote username fragment (must not be empty)

remotePwd · string · required

Remote password (must not be empty)

GetLocalUserCredentials

func (a *Agent) GetLocalUserCredentials() (frag string, pwd string, err error)

Returns the local ICE credentials (username fragment and password).

GetRemoteUserCredentials

func (a *Agent) GetRemoteUserCredentials() (frag string, pwd string, err error)

Returns the remote ICE credentials that have been set via SetRemoteCredentials.

GetRemoteCandidates

func (a *Agent) GetRemoteCandidates() ([]Candidate, error)

Returns all remote candidates that have been added to the agent.

Dial

func (a *Agent) Dial(ctx context.Context, remoteUfrag, remotePwd string) (*Conn, error)

Connects to the remote agent in controlling mode. Returns a Conn that can be used to send and receive data.

Parameters:

ctx · context.Context

Context for controlling the dial operation lifetime.

remoteUfrag · string

Remote username fragment (from remote agent’s GetLocalUserCredentials).

remotePwd · string

Remote password (from remote agent’s GetLocalUserCredentials).

Returns: (*Conn, error) - Connection for data transfer

Example:

localUfrag, localPwd, _ := agent.GetLocalUserCredentials()
// Exchange credentials with peer (out of band)

conn, err := agent.Dial(context.Background(), remoteUfrag, remotePwd)
if err != nil {
    panic(err)
}
defer conn.Close()

// Use conn for data transfer
_, err = conn.Write([]byte("Hello"))

Accept

func (a *Agent) Accept(ctx context.Context, remoteUfrag, remotePwd string) (*Conn, error)

Waits for connection from the remote agent in controlled mode. Returns a Conn that can be used to send and receive data.

Parameters:

ctx · context.Context

Context for controlling the accept operation lifetime.

remoteUfrag · string

Remote username fragment (from remote agent’s GetLocalUserCredentials).

remotePwd · string

Remote password (from remote agent’s GetLocalUserCredentials).

Returns: (*Conn, error) - Connection for data transfer

Restart

func (a *Agent) Restart(ufrag, pwd string) error

Restarts the ICE agent with new credentials. If empty strings are provided, the agent generates new credentials.

Parameters:

ufrag · string

New username fragment. Empty string generates a random value.

pwd · string

New password. Empty string generates a random value.

Credentials must meet minimum entropy requirements: ufrag >= 24 bits, pwd >= 128 bits.

UpdateOptions

func (a *Agent) UpdateOptions(opts ...AgentOption) error

Applies options to the agent at runtime. Only a subset of options can be updated after creation (e.g., WithUrls).

Close

func (a *Agent) Close() error

Cleans up the agent and releases resources. Does not wait for goroutines to complete.

GracefulClose

func (a *Agent) GracefulClose() error

Cleans up the agent and waits for all goroutines to complete. Should only be called outside of agent callbacks or in a separate goroutine.

State Management

GetGatheringState

func (a *Agent) GetGatheringState() (GatheringState, error)

Returns the current gathering state. See GatheringState.

OnConnectionStateChange

func (a *Agent) OnConnectionStateChange(f func(ConnectionState))

Registers a handler that is called when the connection state changes.

OnSelectedCandidatePairChange

func (a *Agent) OnSelectedCandidatePairChange(f func(Candidate, Candidate))

Registers a handler called when the selected candidate pair changes.

OnCandidate

func (a *Agent) OnCandidate(f func(Candidate))

Registers a handler called when a new local candidate is gathered. Called with nil when gathering is complete.

Renomination

RenominateCandidate

func (a *Agent) RenominateCandidate(local, remote Candidate) error

Allows the controlling agent to nominate a new candidate pair. Requires renomination to be enabled.

Returns: Error if agent is not controlling, renomination is disabled, or candidate pair not found.

Type Definition

type Agent struct {
    // Internal fields (not directly accessible)
}

Related Types

• AgentConfig - Legacy configuration struct
• AgentOption - Functional options for agent creation
• ConnectionState - Connection state enum
• GatheringState - Gathering state enum
• Candidate - Candidate interface