Skip to main content

​
Overview

ICE candidates represent potential network paths for establishing peer-to-peer connections. The Pion ICE library provides a comprehensive type system for working with different candidate types defined in RFC 8445.

​
Candidate Interface

The Candidate interface defines the core functionality shared by all candidate types.

​
Interface Definition

candidate.go
type Candidate interface {
    Foundation() string
    ID() string
    Component() uint16
    SetComponent(uint16)
    LastReceived() time.Time
    LastSent() time.Time
    NetworkType() NetworkType
    Address() string
    Port() int
    Priority() uint32
    RelatedAddress() *CandidateRelatedAddress
    Extensions() []CandidateExtension
    GetExtension(key string) (value CandidateExtension, ok bool)
    AddExtension(extension CandidateExtension) error
    RemoveExtension(key string) (ok bool)
    String() string
    Type() CandidateType
    TCPType() TCPType
    Equal(other Candidate) bool
    DeepEqual(other Candidate) bool
    Marshal() string
}

​
Key Methods

​
Foundation()
string
Returns an arbitrary string used in the freezing algorithm to group similar candidates. It is the same for two candidates that have the same type, base IP address, protocol (UDP, TCP, etc.), and STUN or TURN server.
​
ID()
string
Returns a unique identifier for this candidate. Unlike the foundation, this is different for each candidate instance.
​
Component()
uint16
Returns the component identifier. A component is a piece of a data stream. Common values are ComponentRTP (1) for RTP and ComponentRTCP (2) for RTCP.
​
LastReceived()
time.Time
Returns the last time this candidate received traffic.
​
LastSent()
time.Time
Returns the last time this candidate sent traffic.
​
NetworkType()
NetworkType
Returns the network type (UDP4, UDP6, TCP4, or TCP6) for this candidate.
​
Address()
string
Returns the IP address of the candidate.
​
Port()
int
Returns the port number of the candidate.
​
Priority()
uint32
Returns the priority value for this candidate. Priority is computed according to RFC 8445 Section 5.1.2.1.
​
RelatedAddress()
*CandidateRelatedAddress
Returns a transport address related to the candidate, useful for diagnostics and other purposes. For reflexive and relay candidates, this is the base address.
​
Type()
CandidateType
Returns the type of this candidate (host, srflx, prflx, or relay).
​
Marshal()
string
Returns the string representation of the candidate in SDP format.

​
CandidateType Enum

The CandidateType represents the different types of ICE candidates.
candidatetype.go
type CandidateType byte

const (
    CandidateTypeUnspecified CandidateType = iota
    CandidateTypeHost
    CandidateTypeServerReflexive
    CandidateTypePeerReflexive
    CandidateTypeRelay
)

​
Type Values

​
CandidateTypeHost
CandidateType
Represents a host candidate - a candidate obtained directly from a local interface.
​
CandidateTypeServerReflexive
CandidateType
Represents a server reflexive candidate (srflx) - a candidate whose IP address and port are a binding allocated by a STUN server.
​
CandidateTypePeerReflexive
CandidateType
Represents a peer reflexive candidate (prflx) - a candidate whose IP address and port are a binding allocated by a NAT, discovered through connectivity checks.
​
CandidateTypeRelay
CandidateType
Represents a relay candidate - a candidate obtained from a TURN server.

​
Methods

​
String()
string
Returns the string representation: “host”, “srflx”, “prflx”, or “relay”.
​
Preference()
uint16
Returns the type preference value used in priority calculation. Returns 126 for host, 110 for peer reflexive, 100 for server reflexive, and 0 for relay candidates.

​
CandidateBase

The candidateBase struct provides common functionality for all candidate types. It is embedded in all concrete candidate implementations.

​
Priority Calculation

Candidate priority is calculated according to RFC 8445: 
priority = (2^24 * type-preference) + (2^8 * local-preference) + (2^0 * (256 - component))

​
Foundation Calculation

The foundation is computed as a CRC32 checksum of the candidate type, base address, and network type, unless explicitly overridden.

​
CandidateRelatedAddress

Conveys transport addresses related to the candidate, useful for diagnostics.
candidaterelatedaddress.go
type CandidateRelatedAddress struct {
    Address string
    Port    int
}
​
Address
string
The related IP address.
​
Port
int
The related port number.

​
CandidateExtension

Represents a single candidate extension as defined in RFC 5245 Section 15.1.
candidate_base.go
type CandidateExtension struct {
    Key   string
    Value string
}
​
Key
string
The extension attribute name.
​
Value
string
The extension attribute value.

​
NetworkType

Represents the network protocol and IP version for a candidate.
networktype.go
type NetworkType int

const (
    NetworkTypeUDP4 NetworkType = iota + 1
    NetworkTypeUDP6
    NetworkTypeTCP4
    NetworkTypeTCP6
)

​
Methods

​
IsUDP()
bool
Returns true when network is UDP4 or UDP6.
​
IsTCP()
bool
Returns true when network is TCP4 or TCP6.
​
IsIPv4()
bool
Returns true when network is IPv4 (UDP4 or TCP4).
​
IsIPv6()
bool
Returns true when network is IPv6 (UDP6 or TCP6).

​
Component Constants

candidate.go
const (
    ComponentRTP  uint16 = 1
    ComponentRTCP uint16 = 2
)
​
ComponentRTP
uint16
Indicates that the candidate is used for RTP (value: 1).
​
ComponentRTCP
uint16
Indicates that the candidate is used for RTCP (value: 2).

​
Unmarshaling Candidates

Parse a candidate from its string representation: 
func UnmarshalCandidate(raw string) (Candidate, error)

​
Example

candidate, err := ice.UnmarshalCandidate(
    "candidate:842163049 1 udp 1677729535 192.168.1.100 50000 typ srflx raddr 10.0.0.5 rport 50000",
)
if err != nil {
    log.Fatal(err)
}

fmt.Println("Type:", candidate.Type())
fmt.Println("Address:", candidate.Address())
fmt.Println("Port:", candidate.Port())
The UnmarshalCandidate function accepts candidates with or without the “candidate:” prefix as defined in RFC 5245 Section 15.1.

Build docs developers (and LLMs) love

Get started for freeTalk to us