ice

Documentation

Overview

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

Index

• Constants
• Variables
• type Agent
  • func NewAgent(urls []*URL, notifier func(ConnectionState)) *Agent
  • func (a *Agent) Accept(ctx context.Context, remoteUfrag, remotePwd string) (*Conn, error)
  • func (a *Agent) AddRemoteCandidate(c *Candidate) error
  • func (a *Agent) Close() error
  • func (a *Agent) Dial(ctx context.Context, remoteUfrag, remotePwd string) (*Conn, error)
  • func (a *Agent) GetLocalCandidates() ([]*Candidate, error)
  • func (a *Agent) GetLocalUserCredentials() (frag string, pwd string)
• type Candidate
  • func NewCandidateHost(network string, ip net.IP, port int) (*Candidate, error)
  • func NewCandidateServerReflexive(network string, ip net.IP, port int, relAddr string, relPort int) (*Candidate, error)
  • func (c *Candidate) Equal(other *Candidate) bool
  • func (c *Candidate) LastReceived() time.Time
  • func (c *Candidate) LastSent() time.Time
  • func (c *Candidate) Priority(typePreference uint16, component uint16) uint16
  • func (c *Candidate) String() string
• type CandidateRelatedAddress
  • func (c *CandidateRelatedAddress) Equal(other *CandidateRelatedAddress) bool
  • func (c *CandidateRelatedAddress) String() string
• type CandidateType
  • func (c CandidateType) Preference() uint16
  • func (c CandidateType) String() string
• type Conn
  • func (c *Conn) Close() error
  • func (c *Conn) LocalAddr() net.Addr
  • func (c *Conn) Read(p []byte) (int, error)
  • func (c *Conn) RemoteAddr() net.Addr
  • func (c *Conn) SetDeadline(t time.Time) error
  • func (c *Conn) SetReadDeadline(t time.Time) error
  • func (c *Conn) SetWriteDeadline(t time.Time) error
  • func (c *Conn) Write(p []byte) (int, error)
• type ConnectionState
  • func (c ConnectionState) String() string
• type GatheringState
  • func (t GatheringState) String() string
• type NetworkType
  • func (t NetworkType) IsReliable() bool
  • func (t NetworkType) NetworkShort() string
  • func (t NetworkType) 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 (
	// 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")

	// ErrClosed indicates the agent is closed
	ErrClosed = errors.New("the agent is closed")
)

Types

type Agent

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

Agent represents the ICE agent

func NewAgent

func NewAgent(urls []*URL, notifier func(ConnectionState)) *Agent

NewAgent creates a new Agent

func (*Agent) Accept

func (a *Agent) Accept(ctx context.Context, remoteUfrag, remotePwd string) (*Conn, error)

Accept connects to the remote agent, acting as the controlled ice agent. Accept blocks until at least one ice candidate pair has successfully connected.

func (*Agent) AddRemoteCandidate

func (a *Agent) AddRemoteCandidate(c *Candidate) error

AddRemoteCandidate adds a new remote candidate

func (*Agent) Close

func (a *Agent) Close() error

Close cleans up the Agent

func (*Agent) Dial

func (a *Agent) Dial(ctx context.Context, remoteUfrag, remotePwd string) (*Conn, error)

Dial connects to the remote agent, acting as the controlling ice agent. Dial blocks until at least one ice candidate pair has successfully connected.

func (*Agent) GetLocalCandidates

func (a *Agent) GetLocalCandidates() ([]*Candidate, error)

GetLocalCandidates returns the local candidates

func (*Agent) GetLocalUserCredentials

func (a *Agent) GetLocalUserCredentials() (frag string, pwd string)

GetLocalUserCredentials returns the local user credentials

type Candidate

type Candidate struct {
	NetworkType

	Type           CandidateType
	IP             net.IP
	Port           int
	RelatedAddress *CandidateRelatedAddress
	// contains filtered or unexported fields
}

Candidate represents an ICE candidate

func NewCandidateHost

func NewCandidateHost(network string, ip net.IP, port int) (*Candidate, error)

NewCandidateHost creates a new host candidate

func NewCandidateServerReflexive

func NewCandidateServerReflexive(network string, ip net.IP, port int, relAddr string, relPort int) (*Candidate, error)

NewCandidateServerReflexive creates a new server reflective candidate

func (*Candidate) Equal

func (c *Candidate) Equal(other *Candidate) bool

Equal is used to compare two CandidateBases

func (*Candidate) LastReceived

func (c *Candidate) LastReceived() time.Time

LastReceived returns a time.Time indicating the last time this candidate was received

func (*Candidate) LastSent

func (c *Candidate) LastSent() time.Time

LastSent returns a time.Time indicating the last time this candidate was sent

func (*Candidate) Priority

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

Priority computes the priority for this ICE Candidate

func (*Candidate) String

func (c *Candidate) String() string

String makes the CandidateHost printable

type CandidateRelatedAddress

type CandidateRelatedAddress struct {
	Address string
	Port    int
}

CandidateRelatedAddress convey transport addresses related to the candidate, useful for diagnostics and other purposes.

func (*CandidateRelatedAddress) Equal

func (c *CandidateRelatedAddress) Equal(other *CandidateRelatedAddress) bool

Equal allows comparing two CandidateRelatedAddresses. The CandidateRelatedAddress are allowed to be nil.

func (*CandidateRelatedAddress) String

func (c *CandidateRelatedAddress) String() string

String makes CandidateRelatedAddress printable

type CandidateType

type CandidateType byte

CandidateType represents the type of candidate

const (
	CandidateTypeHost CandidateType = iota + 1
	CandidateTypeServerReflexive
)

CandidateType enum

func (CandidateType) Preference

func (c CandidateType) Preference() uint16

Preference returns the preference weight of a CandidateType

func (CandidateType) String

func (c CandidateType) String() string

String makes CandidateType printable

type Conn

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

Conn represents the ICE connection. At the moment the lifetime of the Conn is equal to the Agent.

func (*Conn) Close

func (c *Conn) Close() error

Close implements the Conn Close method. It is used to close the connection. Any calls to Read and Write will be unblocked and return an error.

func (*Conn) LocalAddr

func (c *Conn) LocalAddr() net.Addr

LocalAddr is a stub

func (*Conn) Read

func (c *Conn) Read(p []byte) (int, error)

Read implements the Conn Read method.

func (*Conn) RemoteAddr

func (c *Conn) RemoteAddr() net.Addr

RemoteAddr is a stub

func (*Conn) SetDeadline

func (c *Conn) SetDeadline(t time.Time) error

SetDeadline is a stub

func (*Conn) SetReadDeadline

func (c *Conn) SetReadDeadline(t time.Time) error

SetReadDeadline is a stub

func (*Conn) SetWriteDeadline

func (c *Conn) SetWriteDeadline(t time.Time) error

SetWriteDeadline is a stub

func (*Conn) Write

func (c *Conn) Write(p []byte) (int, error)

Write implements the Conn Write method.

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 NetworkType

type NetworkType int

NetworkType represents the type of network

const (
	// NetworkTypeUDP4 indicates UDP over IPv4.
	NetworkTypeUDP4 NetworkType = iota + 1

	// NetworkTypeUDP6 indicates UDP over IPv4.
	NetworkTypeUDP6

	// NetworkTypeTCP4 indicates TCP over IPv4.
	NetworkTypeTCP4

	// NetworkTypeTCP6 indicates TCP over IPv4.
	NetworkTypeTCP6
)

func (NetworkType) IsReliable

func (t NetworkType) IsReliable() bool

IsReliable returns true if the network is reliable

func (NetworkType) NetworkShort

func (t NetworkType) NetworkShort() string

NetworkShort returns the short network description

func (NetworkType) String

func (t NetworkType) 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