ice

Documentation

Overview

Package ice implements the Interactive Connectivity Establishment (ICE) protocol defined in rfc5245.

Index

• Constants
• Variables
• type Agent
  • func NewAgent(notifier func(ConnectionState)) *Agent
  • func (a *Agent) AddLocalCandidate(c Candidate)
  • func (a *Agent) AddRemoteCandidate(c Candidate)
  • func (a *Agent) Close()
  • func (a *Agent) HandleInbound(buf []byte, local *stun.TransportAddr, remote *net.UDPAddr)
  • func (a *Agent) SelectedPair() (local *stun.TransportAddr, remote *net.UDPAddr)
  • func (a *Agent) Start(isControlling bool, remoteUfrag, remotePwd string) error
• type Candidate
• type CandidateBase
  • func (c *CandidateBase) Priority(typePreference uint16, component uint16) uint16
• type CandidateHost
  • func (c *CandidateHost) Address() string
  • func (c *CandidateHost) GetBase() *CandidateBase
  • func (c *CandidateHost) Port() int
  • func (c *CandidateHost) String() string
• type CandidatePair
• type CandidateSrflx
  • func (c *CandidateSrflx) GetBase() *CandidateBase
  • func (c *CandidateSrflx) String() string
• type ConnectionState
  • func (c ConnectionState) String() string
• type GatheringState
  • func (t GatheringState) String() string
• type ProtoType
  • func NewProtoType(raw string) ProtoType
  • func (t ProtoType) String() string
• type SchemeType
  • func NewSchemeType(raw string) SchemeType
  • func (t SchemeType) String() string
• type URL
  • func ParseURL(raw string) (*URL, error)
  • func (u URL) IsSecure() bool
  • func (u URL) String() string

Constants

const (
	HostCandidatePreference  uint16 = 126
	SrflxCandidatePreference uint16 = 100
)

Preference enums when generate Priority

const (
	// ConnectionStateNew ICE agent is gathering addresses
	ConnectionStateNew = iota + 1

	// ConnectionStateChecking ICE agent has been given local and remote candidates, and is attempting to find a match
	ConnectionStateChecking

	// ConnectionStateConnected ICE agent has a pairing, but is still checking other pairs
	ConnectionStateConnected

	// ConnectionStateCompleted ICE agent has finished
	ConnectionStateCompleted

	// ConnectionStateFailed ICE agent never could successfully connect
	ConnectionStateFailed

	// ConnectionStateDisconnected ICE agent connected successfully, but has entered a failed state
	ConnectionStateDisconnected

	// ConnectionStateClosed ICE agent has finished and is no longer handling requests
	ConnectionStateClosed
)

List of supported States

const Unknown = iota

Unknown defines default public constant to use for "enum" like struct comparisons when no value was defined.

Variables

var (
	// ErrUnknownType indicates an error with Unknown info.
	ErrUnknownType = errors.New("Unknown")

	// ErrSchemeType indicates the scheme type could not be parsed.
	ErrSchemeType = errors.New("unknown scheme type")

	// ErrSTUNQuery indicates query arguments are provided in a STUN URL.
	ErrSTUNQuery = errors.New("queries not supported in stun address")

	// ErrInvalidQuery indicates an malformed query is provided.
	ErrInvalidQuery = errors.New("invalid query")

	// ErrHost indicates malformed hostname is provided.
	ErrHost = errors.New("invalid hostname")

	// ErrPort indicates malformed port is provided.
	ErrPort = errors.New("invalid port")

	// ErrProtoType indicates an unsupported transport type was provided.
	ErrProtoType = errors.New("invalid transport protocol type")
)

Types

type Agent

type Agent struct {
	sync.RWMutex

	LocalUfrag      string
	LocalPwd        string
	LocalCandidates []Candidate
	// contains filtered or unexported fields
}

Agent represents the ICE agent

func NewAgent

func NewAgent(notifier func(ConnectionState)) *Agent

NewAgent creates a new Agent

func (*Agent) AddLocalCandidate

func (a *Agent) AddLocalCandidate(c Candidate)

AddLocalCandidate adds a new local candidate

func (*Agent) AddRemoteCandidate

func (a *Agent) AddRemoteCandidate(c Candidate)

AddRemoteCandidate adds a new remote candidate

func (*Agent) Close

func (a *Agent) Close()

Close cleans up the Agent

func (*Agent) HandleInbound

func (a *Agent) HandleInbound(buf []byte, local *stun.TransportAddr, remote *net.UDPAddr)

HandleInbound processes traffic from a remote candidate

func (*Agent) SelectedPair

func (a *Agent) SelectedPair() (local *stun.TransportAddr, remote *net.UDPAddr)

SelectedPair gets the current selected pair's Addresses (or returns nil)

func (*Agent) Start

func (a *Agent) Start(isControlling bool, remoteUfrag, remotePwd string) error

Start starts the agent

type Candidate

type Candidate interface {
	GetBase() *CandidateBase
	String() string
}

Candidate represents an ICE candidate

type CandidateBase

type CandidateBase struct {
	Protocol     ProtoType
	Address      string
	Port         int
	LastSent     time.Time
	LastReceived time.Time
	Conn         *ipv4.PacketConn // TODO: make private
}

CandidateBase represents an ICE candidate, a base with enough attributes for host candidates, see CandidateSrflx and CandidateRelay for more

func (*CandidateBase) Priority

func (c *CandidateBase) Priority(typePreference uint16, component uint16) uint16

Priority computes the priority for this ICE Candidate

type CandidateHost

type CandidateHost struct {
	CandidateBase
}

CandidateHost is a Candidate of typ Host

func (*CandidateHost) Address

func (c *CandidateHost) Address() string

Address for CandidateHost

func (*CandidateHost) GetBase

func (c *CandidateHost) GetBase() *CandidateBase

GetBase returns the CandidateBase, attributes shared between all Candidates

func (*CandidateHost) Port

func (c *CandidateHost) Port() int

Port for CandidateHost

func (*CandidateHost) String

func (c *CandidateHost) String() string

String makes the CandidateHost printable

type CandidatePair

type CandidatePair struct {
	// contains filtered or unexported fields
}

CandidatePair represents a combination of a local and remote candidate

type CandidateSrflx

type CandidateSrflx struct {
	CandidateBase
	RemoteAddress string
	RemotePort    int
}

CandidateSrflx is a Candidate of typ Server-Reflexive

func (*CandidateSrflx) GetBase

func (c *CandidateSrflx) GetBase() *CandidateBase

GetBase returns the CandidateBase, attributes shared between all Candidates

func (*CandidateSrflx) String

func (c *CandidateSrflx) String() string

String makes the CandidateSrflx printable

type ConnectionState

type ConnectionState int

ConnectionState is an enum showing the state of a ICE Connection

func (ConnectionState) String

func (c ConnectionState) String() string

type GatheringState

type GatheringState int

GatheringState describes the state of the candidate gathering process

const (
	// GatheringStateNew indicates candidate gatering is not yet started
	GatheringStateNew GatheringState = iota + 1

	// GatheringStateGathering indicates candidate gatering is ongoing
	GatheringStateGathering

	// GatheringStateComplete indicates candidate gatering has been completed
	GatheringStateComplete
)

func (GatheringState) String

func (t GatheringState) String() string

type ProtoType

type ProtoType int

ProtoType indicates the transport protocol type that is used in the ice.URL structure.

const (
	// ProtoTypeUDP indicates the URL uses a UDP transport.
	ProtoTypeUDP ProtoType = iota + 1

	// ProtoTypeTCP indicates the URL uses a TCP transport.
	ProtoTypeTCP
)

func NewProtoType

func NewProtoType(raw string) ProtoType

NewProtoType defines a procedure for creating a new ProtoType from a raw string naming the transport protocol type.

func (ProtoType) String

func (t ProtoType) String() string

type SchemeType

type SchemeType int

SchemeType indicates the type of server used in the ice.URL structure.

const (
	// SchemeTypeSTUN indicates the URL represents a STUN server.
	SchemeTypeSTUN SchemeType = iota + 1

	// SchemeTypeSTUNS indicates the URL represents a STUNS (secure) server.
	SchemeTypeSTUNS

	// SchemeTypeTURN indicates the URL represents a TURN server.
	SchemeTypeTURN

	// SchemeTypeTURNS indicates the URL represents a TURNS (secure) server.
	SchemeTypeTURNS
)

func NewSchemeType

func NewSchemeType(raw string) SchemeType

NewSchemeType defines a procedure for creating a new SchemeType from a raw string naming the scheme type.

func (SchemeType) String

func (t SchemeType) String() string

type URL

type URL struct {
	Scheme SchemeType
	Host   string
	Port   int
	Proto  ProtoType
}

URL represents a STUN (rfc7064) or TURN (rfc7065) URL

func ParseURL

func ParseURL(raw string) (*URL, error)

ParseURL parses a STUN or TURN urls following the ABNF syntax described in https://tools.ietf.org/html/rfc7064 and https://tools.ietf.org/html/rfc7065 respectively.

func (URL) IsSecure

func (u URL) IsSecure() bool

IsSecure returns whether the this URL's scheme describes secure scheme or not.

func (URL) String

func (u URL) String() string