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: 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: Variable number of configuration options. See Agent Options for available options. Returns: (*Agent, error)Example: Basic Usage
Advanced Configuration
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: 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: Remote username fragment (must not be empty)
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: Context for controlling the dial operation lifetime.
Remote username fragment (from remote agent’s GetLocalUserCredentials).
Remote password (from remote agent’s GetLocalUserCredentials).
Returns: (*Conn, error) - Connection for data transferExample: 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: Context for controlling the accept operation lifetime.
Remote username fragment (from remote agent’s GetLocalUserCredentials).
Remote password (from remote agent’s GetLocalUserCredentials).
Returns: (*Conn, error) - Connection for data transferRestart 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: New username fragment. Empty string generates a random value.
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) }
