Class RtpIceChannel

An RTP ICE Channel carries out connectivity checks with a remote peer in an attempt to determine the best destination end point to communicate with the remote party.

Inheritance

System.Object

RTPChannel

RtpIceChannel

Implements

System.IDisposable

Inherited Members

RTPChannel.m_rtpReceiver

RTPChannel.m_controlReceiver

RTPChannel.RtpSocket

RTPChannel.LastRtpDestination

RTPChannel.RTPPort

RTPChannel.RTPLocalEndPoint

RTPChannel.ControlPort

RTPChannel.ControlLocalEndPoint

RTPChannel.IsDualMode

RTPChannel.IsClosed

RTPChannel.OnControlDataReceived

RTPChannel.OnClosed

RTPChannel.Start()

RTPChannel.StartRtpReceiver()

RTPChannel.StartControlReceiver()

RTPChannel.Close(String)

RTPChannel.Dispose(Boolean)

RTPChannel.Dispose()

System.Object.Equals(System.Object)

System.Object.Equals(System.Object, System.Object)

System.Object.GetHashCode()

System.Object.GetType()

System.Object.MemberwiseClone()

System.Object.ReferenceEquals(System.Object, System.Object)

System.Object.ToString()

Namespace: SIPSorcery.Net

Assembly: SIPSorcery.dll

Syntax

public class RtpIceChannel : RTPChannel, IDisposable

Remarks

Local server reflexive candidates don't get added to the checklist since they are just local "host" candidates with an extra NAT address mapping. The NAT address mapping is needed for the remote ICE peer but locally a server reflexive candidate is always going to be represented by a "host" candidate.

Limitations:

To reduce complexity only a single checklist is used. This is based on the main webrtc use case where RTP (audio and video) and RTCP are all multiplexed on a single socket pair. Therefore there only needs to be a single component and single data stream. If an additional use case occurs then multiple checklists could be added.

Developer Notes: There are 4 main tasks occurring during the ICE checks:

Local candidates: ICE server checks (which can take seconds) are being carried out to gather "server reflexive" and "relay" candidates.
Remote candidates: the remote peer should be trickling in its candidates which need to be validated and if accepted new entries added to the checklist.
Checklist connectivity checks: the candidate pairs in the checklist need to have connectivity checks sent.
Match STUN messages: STUN requests and responses are being received and need to be matched to either an ICE server check or a checklist entry check. After matching action needs to be taken to update the status of the ICE server or checklist entry check.

Constructors

| Improve this Doc View Source

RtpIceChannel()

Creates a new instance of an RTP ICE channel to provide RTP channel functions with ICE connectivity checks.

Declaration

public RtpIceChannel()

| Improve this Doc View Source

RtpIceChannel(IPAddress, RTCIceComponent, List<RTCIceServer>, RTCIceTransportPolicy, Boolean, Int32, PortRange)

Creates a new instance of an RTP ICE channel to provide RTP channel functions with ICE connectivity checks.

Declaration

public RtpIceChannel(IPAddress bindAddress, RTCIceComponent component, List<RTCIceServer> iceServers = null, RTCIceTransportPolicy policy = RTCIceTransportPolicy.all, bool includeAllInterfaceAddresses = false, int bindPort = 0, PortRange rtpPortRange = null)

Parameters

Type	Name	Description
System.Net.IPAddress	bindAddress	Optional. If this is not set then the default is to bind to the IPv6 wildcard address in dual mode to the IPv4 wildcard address if IPv6 is not available.
RTCIceComponent	component	The component (RTP or RTCP) the channel is being used for. Note for cases where RTP and RTCP are multiplexed the component is set to RTP.
System.Collections.Generic.List<RTCIceServer>	iceServers	A list of STUN or TURN servers that can be used by this ICE agent.
RTCIceTransportPolicy	policy	Determines which ICE candidates can be used in this RTP ICE Channel.
System.Boolean	includeAllInterfaceAddresses	If set to true then IP addresses from ALL local interfaces will be used for host ICE candidates. If left as the default false value host candidates will be restricted to the single interface that the OS routing table matches to the destination address or the Internet facing interface if the destination is not known. The restrictive behaviour is as per the recommendation at: https://tools.ietf.org/html/draft-ietf-rtcweb-ip-handling-12#section-5.2.
System.Int32	bindPort
PortRange	rtpPortRange

Fields

| Improve this Doc View Source

ALLOCATION_TIME_TO_EXPIRY_VALUE

The lifetime value used in refresh request.

Declaration

public static uint ALLOCATION_TIME_TO_EXPIRY_VALUE

Field Value

Type	Description
System.UInt32

| Improve this Doc View Source

DISCONNECTED_TIMEOUT_PERIOD

The period in seconds after which a connection will be flagged as disconnected.

Declaration

public static int DISCONNECTED_TIMEOUT_PERIOD

Field Value

Type	Description
System.Int32

| Improve this Doc View Source

FAILED_TIMEOUT_PERIOD

The period in seconds after which a connection will be flagged as failed.

Declaration

public static int FAILED_TIMEOUT_PERIOD

Field Value

Type	Description
System.Int32

| Improve this Doc View Source

LocalIcePassword

Declaration

public readonly string LocalIcePassword

Field Value

Type	Description
System.String

| Improve this Doc View Source

LocalIceUser

Declaration

public readonly string LocalIceUser

Field Value

Type	Description
System.String

| Improve this Doc View Source

m_rtpTcpReceiverByUri

Declaration

protected Dictionary<STUNUri, RtpIceChannel.IceTcpReceiver> m_rtpTcpReceiverByUri

Field Value

Type	Description
System.Collections.Generic.Dictionary<STUNUri, RtpIceChannel.IceTcpReceiver>

| Improve this Doc View Source

MdnsGetAddresses

An optional callback function to resolve remote ICE candidates with MDNS hostnames.

Declaration

public Func<string, Task<IPAddress[]>> MdnsGetAddresses

Field Value

Type	Description
System.Func<System.String, System.Threading.Tasks.Task<System.Net.IPAddress[]>>

Remarks

The order is MdnsGetAddresses, then MdnsResolve. If both are null system System.Net.Dns will be used.

| Improve this Doc View Source

MdnsResolve

An optional callback function to resolve remote ICE candidates with MDNS hostnames.

Declaration

public Func<string, Task<IPAddress>> MdnsResolve

Field Value

Type	Description
System.Func<System.String, System.Threading.Tasks.Task<System.Net.IPAddress>>

Remarks

The order is MdnsGetAddresses, then MdnsResolve. If both are null system System.Net.Dns will be used.

| Improve this Doc View Source

REFRESH_PERMISSION_PERIOD

The period in seconds after which a CreatePermission will be sent.

Declaration

public static int REFRESH_PERMISSION_PERIOD

Field Value

Type	Description
System.Int32

| Improve this Doc View Source

SDP_MID

Declaration

public const string SDP_MID = "0"

Field Value

Type	Description
System.String

| Improve this Doc View Source

SDP_MLINE_INDEX

Declaration

public const int SDP_MLINE_INDEX = 0

Field Value

Type	Description
System.Int32

Properties

| Improve this Doc View Source

Candidates

The list of host ICE candidates that have been gathered for this peer.

Declaration

public List<RTCIceCandidate> Candidates { get; }

Property Value

Type	Description
System.Collections.Generic.List<RTCIceCandidate>

| Improve this Doc View Source

Component

Declaration

public RTCIceComponent Component { get; }

Property Value

Type	Description
RTCIceComponent

| Improve this Doc View Source

DefaultNameServers

Declaration

public static List<NameServer> DefaultNameServers { get; set; }

Property Value

Type	Description
System.Collections.Generic.List<DnsClient.NameServer>

| Improve this Doc View Source

IceConnectionState

Declaration

public RTCIceConnectionState IceConnectionState { get; }

Property Value

Type	Description
RTCIceConnectionState

| Improve this Doc View Source

IceGatheringState

Declaration

public RTCIceGatheringState IceGatheringState { get; }

Property Value

Type	Description
RTCIceGatheringState

| Improve this Doc View Source

IsController

True if we are the "controlling" ICE agent (we initiated the communications) or false if we are the "controlled" agent.

Declaration

public bool IsController { get; }

Property Value

Type	Description
System.Boolean

| Improve this Doc View Source

NominatedEntry

If the connectivity checks are successful this will hold the entry that was nominated by the connection check process.

Declaration

public ChecklistEntry NominatedEntry { get; }

Property Value

Type	Description
ChecklistEntry

| Improve this Doc View Source

RemoteIcePassword

Declaration

public string RemoteIcePassword { get; }

Property Value

Type	Description
System.String

| Improve this Doc View Source

RemoteIceUser

Declaration

public string RemoteIceUser { get; }

Property Value

Type	Description
System.String

| Improve this Doc View Source

RtpTcpSocketByUri

Declaration

public Dictionary<STUNUri, Socket> RtpTcpSocketByUri { get; }

Property Value

Type	Description
System.Collections.Generic.Dictionary<STUNUri, System.Net.Sockets.Socket>

Methods

| Improve this Doc View Source

AddRemoteCandidate(RTCIceCandidate)

Adds a remote ICE candidate to the RTP ICE Channel.

Declaration

public void AddRemoteCandidate(RTCIceCandidate candidate)

Parameters

Type	Name	Description
RTCIceCandidate	candidate	An ICE candidate from the remote party.

| Improve this Doc View Source

Close()

Closes the RTP ICE Channel and stops any further connectivity checks.

Declaration

public void Close()

| Improve this Doc View Source

CloseTcp(RtpIceChannel.IceTcpReceiver, String)

Declaration

protected void CloseTcp(RtpIceChannel.IceTcpReceiver target, string reason)

Parameters

Type	Name	Description
RtpIceChannel.IceTcpReceiver	target
System.String	reason

| Improve this Doc View Source

CloseTcp(String)

Declaration

protected void CloseTcp(string reason)

Parameters

Type	Name	Description
System.String	reason

| Improve this Doc View Source

EndSendToTCP(IAsyncResult)

Declaration

protected virtual void EndSendToTCP(IAsyncResult ar)

Parameters

Type	Name	Description
System.IAsyncResult	ar

| Improve this Doc View Source

OnRTPPacketReceived(UdpReceiver, Int32, IPEndPoint, Byte[])

Event handler for packets received on the RTP UDP socket. This channel will detect STUN messages and extract STUN messages to deal with ICE connectivity checks and TURN relays.

Declaration

protected override void OnRTPPacketReceived(UdpReceiver receiver, int localPort, IPEndPoint remoteEndPoint, byte[] packet)

Parameters

Type	Name	Description
UdpReceiver	receiver	The UDP receiver the packet was received on.
System.Int32	localPort	The local port it was received on.
System.Net.IPEndPoint	remoteEndPoint	The remote end point of the sender.
System.Byte[]	packet	The raw packet received (note this may not be RTP if other protocols are being multiplexed).

Overrides

RTPChannel.OnRTPPacketReceived(UdpReceiver, Int32, IPEndPoint, Byte[])

| Improve this Doc View Source

ProcessStunMessage(STUNMessage, IPEndPoint, Boolean)

Processes a received STUN request or response.

Declaration

public async Task ProcessStunMessage(STUNMessage stunMessage, IPEndPoint remoteEndPoint, bool wasRelayed)

Parameters

Type	Name	Description
STUNMessage	stunMessage	The STUN message received.
System.Net.IPEndPoint	remoteEndPoint	The remote end point the STUN packet was received from.
System.Boolean	wasRelayed

Returns

Type	Description
System.Threading.Tasks.Task

Remarks

Actions to take on a successful STUN response https://tools.ietf.org/html/rfc8445#section-7.2.5.3

Discover peer reflexive remote candidates as per https://tools.ietf.org/html/rfc8445#section-7.2.5.3.1.
Construct a valid pair which means match a candidate pair in the check list and mark it as valid (since a successful STUN exchange has now taken place on it). A new entry may need to be created for this pair for a peer reflexive candidate.
Update state of candidate pair that generated the check to Succeeded.
If the controlling candidate set the USE_CANDIDATE attribute then the ICE agent that receives the successful response sets the nominated flag of the pair to true. Once the nominated flag is set it concludes the ICE processing for that component.

| Improve this Doc View Source

Restart()

Restarts the ICE gathering and connection checks for this RTP ICE Channel.

Declaration

public void Restart()

| Improve this Doc View Source

Send(RTPChannelSocketsEnum, IPEndPoint, Byte[])

The send method for the RTP ICE channel. The sole purpose of this overload is to package up sends that need to be relayed via a TURN server. If the connected channel is not a relay then the send can be passed straight through to the underlying RTP channel.

Declaration

public override SocketError Send(RTPChannelSocketsEnum sendOn, IPEndPoint dstEndPoint, byte[] buffer)

Parameters

Type	Name	Description
RTPChannelSocketsEnum	sendOn	The socket to send on. Can be the RTP or Control socket.
System.Net.IPEndPoint	dstEndPoint	The destination end point to send to.
System.Byte[]	buffer	The data to send.

Returns

Type	Description
System.Net.Sockets.SocketError	The result of initiating the send. This result does not reflect anything about whether the remote party received the packet or not.

Overrides

RTPChannel.Send(RTPChannelSocketsEnum, IPEndPoint, Byte[])

| Improve this Doc View Source

SendOverTCP(IceServer, Byte[])

Declaration

protected virtual SocketError SendOverTCP(IceServer iceServer, byte[] buffer)

Parameters

Type	Name	Description
IceServer	iceServer
System.Byte[]	buffer

Returns

Type	Description
System.Net.Sockets.SocketError

| Improve this Doc View Source

SetRemoteCredentials(String, String)

Set the ICE credentials that have been supplied by the remote peer. Once these are set the connectivity checks should be able to commence.

Declaration

public void SetRemoteCredentials(string username, string password)

Parameters

Type	Name	Description
System.String	username	The remote peer's ICE username.
System.String	password	The remote peer's ICE password.

| Improve this Doc View Source

StartGathering()

We've been given the green light to start the ICE candidate gathering process. This could include contacting external STUN and TURN servers. Events will be fired as each ICE is identified and as the gathering state machine changes state.

Declaration

public void StartGathering()

| Improve this Doc View Source

StartTcpRtpReceiver()

Declaration

protected void StartTcpRtpReceiver()

Events

| Improve this Doc View Source

OnIceCandidate

Declaration

public event Action<RTCIceCandidate> OnIceCandidate

Event Type

Type	Description
System.Action<RTCIceCandidate>

| Improve this Doc View Source

OnIceCandidateError

Declaration

public event Action<RTCIceCandidate, string> OnIceCandidateError

Event Type

Type	Description
System.Action<RTCIceCandidate, System.String>

| Improve this Doc View Source

OnIceConnectionStateChange

Declaration

public event Action<RTCIceConnectionState> OnIceConnectionStateChange

Event Type

Type	Description
System.Action<RTCIceConnectionState>

| Improve this Doc View Source

OnIceGatheringStateChange

Declaration

public event Action<RTCIceGatheringState> OnIceGatheringStateChange

Event Type

Type	Description
System.Action<RTCIceGatheringState>

| Improve this Doc View Source

OnRTPDataReceived

Declaration

public event Action<int, IPEndPoint, byte[]> OnRTPDataReceived

Event Type

Type	Description
System.Action<System.Int32, System.Net.IPEndPoint, System.Byte[]>

| Improve this Doc View Source

OnStunMessageReceived

This event gets fired when a STUN message is received by this channel. The event is for diagnostic purposes only. Parameters:

STUNMessage: The received STUN message.
IPEndPoint: The remote end point the STUN message was received from.
bool: True if the message was received via a TURN server relay.

Declaration

public event Action<STUNMessage, IPEndPoint, bool> OnStunMessageReceived

Event Type

Type	Description
System.Action<STUNMessage, System.Net.IPEndPoint, System.Boolean>

| Improve this Doc View Source

OnStunMessageSent

This event gets fired when a STUN message is sent by this channel. The event is for diagnostic purposes only. Parameters:

STUNMessage: The STUN message that was sent.
IPEndPoint: The remote end point the STUN message was sent to.
bool: True if the message was sent via a TURN server relay.

Declaration

public event Action<STUNMessage, IPEndPoint, bool> OnStunMessageSent

Event Type

Type	Description
System.Action<STUNMessage, System.Net.IPEndPoint, System.Boolean>

Implements

System.IDisposable

Extension Methods

JSONWriter.ToJson(Object)