ICETransport

Provides access to ICE transport information for WebRTC packet transmission

Overview

The ICETransport allows an application access to information about the ICE transport over which packets are sent and received.

This is part of the ORTC API. It is not meant to be used together with the basic WebRTC API.

Type Definition

icetransport.go

type ICETransport struct {
    // Contains internal state management for ICE transport
}

Constructor

NewICETransport

Creates a new ICETransport with the given ICEGatherer.

icetransport.go

func NewICETransport(gatherer *ICEGatherer, loggerFactory logging.LoggerFactory) *ICETransport

gatherer · *ICEGatherer · required

The ICE gatherer to use for candidate gathering

loggerFactory · logging.LoggerFactory · required

Factory for creating loggers

return · *ICETransport

Returns a new ICETransport instance

Example:

api := webrtc.NewAPI()
gatherer, _ := api.NewICEGatherer(webrtc.ICEGatherOptions{})
transport := webrtc.NewICETransport(gatherer, api.LoggerFactory)

Methods

Start

Starts incoming connectivity checks based on the configured role.

icetransport.go

func (t *ICETransport) Start(
    gatherer *ICEGatherer, 
    params ICEParameters, 
    role *ICERole,
) error

gatherer · *ICEGatherer

Optional ICE gatherer to use (can be nil to use the existing one)

params · ICEParameters · required

Remote ICE parameters (username fragment and password)

Show ICEParameters structure

UsernameFragment · string

ICE username fragment from remote peer

Password · string

ICE password from remote peer

ICELite · bool

Whether remote peer is using ICE-lite

role · *ICERole

ICE role (controlling or controlled). If nil, defaults to controlled.

return · error

Returns nil on success, or an error if the transport cannot be started

Example:

role := webrtc.ICERoleControlling
err := transport.Start(nil, remoteParams, &role)
if err != nil {
    panic(err)
}

Stop

Irreversibly stops the ICETransport.

icetransport.go

func (t *ICETransport) Stop() error

return · error

Returns nil on success, or an error if stopping fails

Example:

err := transport.Stop()
if err != nil {
    panic(err)
}

GracefulStop

Irreversibly stops the ICETransport and waits for goroutines to complete.

This is only safe to call outside of ICETransport callbacks or if in a callback, in its own goroutine.

icetransport.go

func (t *ICETransport) GracefulStop() error

return · error

Returns nil on success, or an error if stopping fails

Example:

go func() {
    err := transport.GracefulStop()
    if err != nil {
        log.Printf("Error stopping transport: %v", err)
    }
}()

State

Returns the current ICE transport state.

icetransport.go

func (t *ICETransport) State() ICETransportState

return · ICETransportState

The current state (New, Checking, Connected, Completed, Failed, Disconnected, Closed)

Example:

state := transport.State()
fmt.Printf("Transport state: %s\n", state)

Role

Returns the current role of the ICE transport.

icetransport.go

func (t *ICETransport) Role() ICERole

return · ICERole

The current ICE role (Controlling or Controlled)

Example:

role := transport.Role()
fmt.Printf("ICE role: %s\n", role)

GetLocalParameters

Returns an ICEParameters object uniquely identifying the local peer.

icetransport.go

func (t *ICETransport) GetLocalParameters() (ICEParameters, error)

return · ICEParameters, error

Returns the local ICE parameters or an error

Example:

params, err := transport.GetLocalParameters()
if err != nil {
    panic(err)
}
fmt.Printf("Local ICE params: %+v\n", params)

GetRemoteParameters

Returns an ICEParameters object uniquely identifying the remote peer.

icetransport.go

func (t *ICETransport) GetRemoteParameters() (ICEParameters, error)

return · ICEParameters, error

Returns the remote ICE parameters or an error

Example:

params, err := transport.GetRemoteParameters()
if err != nil {
    panic(err)
}
fmt.Printf("Remote ICE params: %+v\n", params)

GetSelectedCandidatePair

Returns the selected candidate pair on which packets are sent.

icetransport.go

func (t *ICETransport) GetSelectedCandidatePair() (*ICECandidatePair, error)

return · *ICECandidatePair, error

Returns the selected candidate pair or nil if no pair is selected

Show ICECandidatePair structure

Local · *ICECandidate

The local ICE candidate

Remote · *ICECandidate

The remote ICE candidate

Example:

pair, err := transport.GetSelectedCandidatePair()
if err != nil {
    panic(err)
}
if pair != nil {
    fmt.Printf("Selected pair - Local: %s, Remote: %s\n", 
        pair.Local.String(), pair.Remote.String())
}

GetSelectedCandidatePairStats

Returns statistics for the selected candidate pair.

icetransport.go

func (t *ICETransport) GetSelectedCandidatePairStats() (ICECandidatePairStats, bool)

return · ICECandidatePairStats, bool

Returns stats and true if available, or empty stats and false if not available

Example:

stats, ok := transport.GetSelectedCandidatePairStats()
if ok {
    fmt.Printf("Bytes sent: %d, Bytes received: %d\n", 
        stats.BytesSent, stats.BytesReceived)
}

AddRemoteCandidate

Adds a candidate associated with the remote ICETransport.

icetransport.go

func (t *ICETransport) AddRemoteCandidate(remoteCandidate *ICECandidate) error

remoteCandidate · *ICECandidate

The remote ICE candidate to add (can be nil to signal end-of-candidates)

return · error

Returns nil on success, or an error if the candidate cannot be added

Example:

err := transport.AddRemoteCandidate(candidate)
if err != nil {
    panic(err)
}

SetRemoteCandidates

Sets the sequence of candidates associated with the remote ICETransport.

icetransport.go

func (t *ICETransport) SetRemoteCandidates(remoteCandidates []ICECandidate) error

remoteCandidates · []ICECandidate · required

Slice of remote ICE candidates to set

return · error

Returns nil on success, or an error if candidates cannot be set

Example:

err := transport.SetRemoteCandidates(remoteCandidates)
if err != nil {
    panic(err)
}

OnConnectionStateChange

Sets a handler that fires when the ICE connection state changes.

icetransport.go

func (t *ICETransport) OnConnectionStateChange(f func(ICETransportState))

f · func(ICETransportState) · required

Callback function that receives state change notifications

Example:

transport.OnConnectionStateChange(func(state webrtc.ICETransportState) {
    fmt.Printf("ICE transport state changed to: %s\n", state)
})

OnSelectedCandidatePairChange

Sets a handler invoked when a new ICE candidate pair is selected.

icetransport.go

func (t *ICETransport) OnSelectedCandidatePairChange(f func(*ICECandidatePair))

f · func(*ICECandidatePair) · required

Callback function that receives the selected candidate pair

Example:

transport.OnSelectedCandidatePairChange(func(pair *webrtc.ICECandidatePair) {
    fmt.Printf("Selected candidate pair changed\n")
    fmt.Printf("  Local: %s\n", pair.Local.String())
    fmt.Printf("  Remote: %s\n", pair.Remote.String())
})

Stats

Reports the current statistics of the ICETransport.

icetransport.go

func (t *ICETransport) Stats() TransportStats

return · TransportStats

Returns transport statistics including bytes sent and received

Show TransportStats structure

Timestamp · StatsTimestamp

Timestamp of the stats

Type · StatsType

Stats type (always StatsTypeTransport)

ID · string

Stats identifier

BytesSent · uint64

Number of bytes sent

BytesReceived · uint64

Number of bytes received

Example:

stats := transport.Stats()
fmt.Printf("Bytes sent: %d, received: %d\n", 
    stats.BytesSent, stats.BytesReceived)

States

The ICETransport can be in one of the following states:

• ICETransportStateNew: Initial state
• ICETransportStateChecking: Checking candidate pairs
• ICETransportStateConnected: Successfully connected
• ICETransportStateCompleted: Completed gathering and checks
• ICETransportStateFailed: Failed to establish connection
• ICETransportStateDisconnected: Temporarily disconnected
• ICETransportStateClosed: Transport has been closed

Usage Example

Complete Example

package main

import (
    "fmt"
    "github.com/pion/webrtc/v4"
)

func main() {
    // Create API
    api := webrtc.NewAPI()
    
    // Create ICE gatherer
    gatherer, err := api.NewICEGatherer(webrtc.ICEGatherOptions{
        ICEServers: []webrtc.ICEServer{
            {URLs: []string{"stun:stun.l.google.com:19302"}},
        },
    })
    if err != nil {
        panic(err)
    }
    
    // Create ICE transport
    transport := webrtc.NewICETransport(gatherer, api.LoggerFactory)
    
    // Set up event handlers
    transport.OnConnectionStateChange(func(state webrtc.ICETransportState) {
        fmt.Printf("ICE transport state: %s\n", state)
    })
    
    transport.OnSelectedCandidatePairChange(func(pair *webrtc.ICECandidatePair) {
        fmt.Printf("Selected pair: %s <-> %s\n", 
            pair.Local.String(), pair.Remote.String())
    })
    
    // Gather candidates
    if err = gatherer.Gather(); err != nil {
        panic(err)
    }
    
    // Start transport with remote parameters
    // (remoteParams would come from signaling)
    role := webrtc.ICERoleControlling
    err = transport.Start(nil, remoteParams, &role)
    if err != nil {
        panic(err)
    }
    
    // Add remote candidates as they arrive
    // transport.AddRemoteCandidate(remoteCandidate)
    
    // Get stats periodically
    stats := transport.Stats()
    fmt.Printf("Stats: %+v\n", stats)
    
    // Clean up
    defer transport.Stop()
}

See Also

• ICEGatherer - Gathers ICE candidates
• DTLSTransport - Handles DTLS encryption over ICE
• PeerConnection - High-level WebRTC API