Skip to main content

​
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)
​
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
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
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

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

Build docs developers (and LLMs) love

Get started for freeTalk to us