Candidate Types

Core ICE candidate interfaces, types, and base functionality in Pion ICE

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.