Class IceAgent

A full ICE agent for one component over UDP, IPv4 and IPv6, as WebRTC's bundled, RTCP-multiplexed media needs: gathers candidates, checks pairs with the peer, selects one, and carries datagrams over it.

Inheritance

object

IceAgent

Implements

IAsyncDisposable

Inherited Members

object.Equals(object)

object.Equals(object, object)

object.GetHashCode()

object.GetType()

object.ReferenceEquals(object, object)

object.ToString()

Namespace: Uniform.Matrix.WebRtc.Ice

Assembly: Uniform.Matrix.WebRtc.dll

Syntax

public sealed class IceAgent : IAsyncDisposable

Remarks

One IPv4 socket bound to all interfaces is the base of every IPv4 host candidate, and of the server-reflexive ones; each TURN allocation on that socket is the base of a relayed candidate. An IPv6 socket is likewise the base of the IPv6 host candidates, which are preferred, as RFC 8421 recommends. So pairs are bases times remote candidates of the same family; relays, being IPv4, pair with IPv4 peers. Candidates trickle: CandidateGathered raises each as found, and AddRemoteCandidate(IceCandidate) takes the peer's at any time. The controlling agent nominates the best pair that works, shortly after the first one does; checks then continue every few seconds, for consent. Datagrams that are not STUN, i.e. DTLS and SRTP, go to DataReceived.

Constructors

IceAgent(IceOptions)

Open the socket, and start reading it.

Declaration

public IceAgent(IceOptions options)

Parameters

Type	Name	Description
IceOptions	options

Properties

Controlling

Whether this agent is the controlling one now; a role conflict may change it.

Declaration

public bool Controlling { get; }

Property Value

Type	Description
bool

LocalCandidates

The candidates gathered so far.

Declaration

public IReadOnlyList<IceCandidate> LocalCandidates { get; }

Property Value

Type	Description
IReadOnlyList<IceCandidate>

LocalPassword

This agent's password, for the SDP's a=ice-pwd.

Declaration

public string LocalPassword { get; }

Property Value

Type	Description
string

LocalUfrag

This agent's username fragment, for the SDP's a=ice-ufrag.

Declaration

public string LocalUfrag { get; }

Property Value

Type	Description
string

SelectedLocal

The local candidate of the selected pair, once connected.

Declaration

public IceCandidate? SelectedLocal { get; }

Property Value

Type	Description
IceCandidate

SelectedRemote

The remote candidate of the selected pair, once connected.

Declaration

public IceCandidate? SelectedRemote { get; }

Property Value

Type	Description
IceCandidate

State

The state.

Declaration

public IceState State { get; }

Property Value

Type	Description
IceState

Methods

AddRemoteCandidate(IceCandidate)

Add a candidate of the peer, and pair it with the local bases of its family; ignored when it is not usable, e.g. IPv6 without an IPv6 socket.

Declaration

public void AddRemoteCandidate(IceCandidate candidate)

Parameters

Type	Name	Description
IceCandidate	candidate

ConnectAsync(TimeSpan, CancellationToken)

Check pairs until one is selected; return whether one was before timeout.

Declaration

public Task<bool> ConnectAsync(TimeSpan timeout, CancellationToken cancellationToken = default)

Parameters

Type	Name	Description
TimeSpan	timeout
CancellationToken	cancellationToken

Returns

Type	Description
Task<bool>

DisposeAsync()

Stop, release the allocations, and close the socket.

Declaration

public ValueTask DisposeAsync()

Returns

Type	Description
ValueTask

GatherAsync(CancellationToken)

Gather host candidates, then reflexive and relayed ones from the servers; return when all servers answered or timed out.

Declaration

public Task GatherAsync(CancellationToken cancellationToken = default)

Parameters

Type	Name	Description
CancellationToken	cancellationToken

Returns

Type	Description
Task

SendAsync(ReadOnlyMemory<byte>, CancellationToken)

Send a datagram to the peer over the selected pair.

Declaration

public ValueTask SendAsync(ReadOnlyMemory<byte> datagram, CancellationToken cancellationToken = default)

Parameters

Type	Name	Description
ReadOnlyMemory<byte>	datagram
CancellationToken	cancellationToken

Returns

Type	Description
ValueTask

SetRemoteCredentials(string, string)

Set the peer's username fragment and password, from its SDP; checks wait for them.

Declaration

public void SetRemoteCredentials(string ufrag, string password)

Parameters

Type	Name	Description
string	ufrag
string	password

Events

CandidateGathered

Raised for each local candidate as it is gathered, to trickle it to the peer.

Declaration

public event Action<IceCandidate>? CandidateGathered

Event Type

Type	Description
Action<IceCandidate>

DataReceived

Raised on the read loop for each datagram from the peer that is not STUN, e.g. DTLS or SRTP.

Declaration

public event Action<byte[]>? DataReceived

Event Type

Type	Description
Action<byte[]>

StateChanged

Raised when State changes.

Declaration

public event Action<IceState>? StateChanged

Event Type

Type	Description
Action<IceState>

Implements

IAsyncDisposable