Table of Contents

Class RTCIceCandidate

Namespace
CSharpToJavaScript.APIs.JS
Assembly
CSharpToJavaScript.dll

The RTCIceCandidate interface—part of the WebRTC API—represents a candidate Interactive Connectivity Establishment ({{Glossary("ICE")}}) configuration which may be used to establish an RTCPeerConnection.

[Value("RTCIceCandidate")]
public class RTCIceCandidate
Inheritance
RTCIceCandidate
Inherited Members

Remarks

An ICE candidate describes the protocols and routing needed for WebRTC to be able to communicate with a remote device. When starting a WebRTC peer connection, typically a number of candidates are proposed by each end of the connection, until they mutually agree upon one which describes the connection they decide will be best. WebRTC then uses that candidate's details to initiate the connection.

For details on how the ICE process works, see Lifetime of a WebRTC session. The article WebRTC connectivity provides additional useful details.

See also on MDN

Constructors

RTCIceCandidate() 

public RTCIceCandidate()

RTCIceCandidate(RTCIceCandidateInit)

The
RTCIceCandidate()
constructor creates and returns a new RTCIceCandidate object, which can
be configured to represent a single ICE candidate.

public RTCIceCandidate(RTCIceCandidateInit candidateInitDict = null)

Parameters

candidateInitDict RTCIceCandidateInit

Remarks

-Introduction to WebRTC protocols
-WebRTC connectivity
-Lifetime of a WebRTC session
-Signaling and video calling

See also on MDN

Properties

Address

The RTCIceCandidate interface's read-only address property is a string providing the IP address of the device which is the source of the candidate.
The address is null by default if not otherwise specified.

[Value("address")]
public string? Address { get; }

Property Value

string

A string providing the IP address from which the candidate comes.

NOTE
If port is null — and
port is supported by the user agent — passing the
candidate to AddIceCandidate(RTCIceCandidateInit)
will fail, throwing an OperationError exception.

Remarks

The address field's value is set from the candidateInfo options object passed to the RTCIceCandidate(RTCIceCandidateInit) constructor.
You can't specify the value of address directly in the options object, but its value is automatically extracted from the object's candidate a-line, if it's formatted properly.

See also on MDN

Candidate

The read-only property candidate on the RTCIceCandidate interface returns a string describing the candidate in detail.
Most of the other properties of RTCIceCandidate are actually extracted from this string.

[Value("candidate")]
public string Candidate { get; }

Property Value

string

A string describing the properties of the candidate, taken directly from the SDP attribute "candidate".
The candidate string specifies the network connectivity information for the candidate.
If the candidate is an empty string (""), the end of the candidate list has been reached; this candidate is known as the "end-of-candidates" marker.The syntax of the candidate string is described in {{RFC(5245, "", 15.1)}}. For an a-line (attribute line) that looks like this:the corresponding candidate string's value will be: "candidate:4234997325 1 udp 2043278322 192.0.2.172 44323 typ host".The user agent always prefers candidates with the highest
Priority, all else being equal. In the
example above, the priority is 2043278322. The attributes are all separated
by a single space character, and are in a specific order. The complete list of
attributes for this example candidate is:

Remarks

This property can be configured using the candidate property of the object passed into the RTCIceCandidate(RTCIceCandidateInit) constructor or AddIceCandidate(RTCIceCandidateInit).

See also on MDN

Component

The read-only component property
on the RTCIceCandidate interface is a string which indicates whether
the candidate is an RTP or
an RTCP candidate.

[Value("component")]
public RTCIceComponent? Component { get; }

Property Value

RTCIceComponent?

A string which is one of the following:

Remarks

If a candidate represents both RTP and RTCP multiplexed together, it is reported as an
RTP candidate.

See also on MDN

Foundation

The foundation read-only property of the RTCIceCandidate interface is a string that allows correlation of candidates from a common network path on multiple RTCIceTransport objects.

[Value("foundation")]
public string? Foundation { get; }

Property Value

string

A string which uniquely identifies the candidate across all RTCIceTransports on which it is available.

NOTE
If port is null — and port is supported by the {{Glossary("user agent")}} — passing the candidate to AddIceCandidate(RTCIceCandidateInit) will fail, throwing an OperationError exception.

Remarks

Candidates share the same foundation if they:

This is used to help optimize ICE performance while prioritizing and correlating candidates that appear on multiple RTCIceTransport objects.

See also on MDN

Port

The RTCIceCandidate interface's read-only port property contains the port
number on the device at the address given by Address at which the candidate's peer can be reached.

[Value("port")]
public ushort? Port { get; }

Property Value

ushort?

A 16-bit number indicating the port number on the device at the address indicated by RTCIceCandidateaddress at which the candidate's peer can be reached.port is initialized to null if it is not specified in the
candidate, or if the candidate string can't be parsed properly.

NOTE
If port is null, passing the candidate to AddIceCandidate(RTCIceCandidateInit)
will fail, throwing an OperationError exception.
This applies only if the candidate implements port.

Remarks

The port field's value is set from the candidateInfo options object passed to the RTCIceCandidate(RTCIceCandidateInit) constructor.
You can't specify the value of port directly in the options object, but its value is automatically extracted from the object's candidate a-line, if it's formatted properly.

See also on MDN

Priority

The RTCIceCandidate interface's read-only priority property specifies the candidate's priority according to the remote peer; the higher this value is, the better the remote peer considers the candidate to be.

[Value("priority")]
public ulong? Priority { get; }

Property Value

ulong?

A long, unsigned integer value indicating the priority of the candidate according to the remote peer.
The larger this value is, the more preferable the remote peer considers this candidate to be.priority is initialized to null if it is not specified in the candidate, or if the candidate string can't be parsed properly.

NOTE
If priority is null, passing the
candidate to AddIceCandidate(RTCIceCandidateInit)
will fail, throwing an OperationError exception. This applies only if the
candidate implements the priority property.

Remarks

The priority field's value is set from the candidateInfo options object passed to the RTCIceCandidate(RTCIceCandidateInit) constructor.
You can't specify the value of priority directly in the options object, but its value is automatically extracted from the object's candidate a-line, if it's formatted properly.

See also on MDN

Protocol

The RTCIceCandidate interface's read-only protocol property is a string
which indicates whether the candidate uses UDP or TCP as its transport protocol.

[Value("protocol")]
public RTCIceProtocol? Protocol { get; }

Property Value

RTCIceProtocol?

A string that indicates what network protocol the candidate uses:

NOTE
If protocol is null — and protocol is supported by the user agent — passing the
candidate to AddIceCandidate(RTCIceCandidateInit) will fail, throwing an OperationError exception.

Remarks

The protocol field's value is set from the candidateInfo options object passed to the RTCIceCandidate(RTCIceCandidateInit) constructor.
You can't specify the value of protocol directly in the options object, but its value is automatically extracted from the object's candidate a-line, if it's formatted properly.

protocol is null by default if not specified properly in the SDP, but this is an error condition and will result in a thrown exception when you call AddIceCandidate(RTCIceCandidateInit).

See also on MDN

RelatedAddress

The RTCIceCandidate interface's read-only relatedAddress property is a string indicating the related address of a relay or reflexive candidate.

[Value("relatedAddress")]
public string? RelatedAddress { get; }

Property Value

string

A string which contains the candidate's related address.
For both peer and server reflexive candidates, the related address (and related port) are the base for that server or peer reflexive candidate.
For relay candidates, the related address and port are set to the mapped address selected by the TURN server.For host candidates, relatedAddress is null, meaning the field is not included in the candidate's a-line.

Remarks

If the candidate is a host candidate (that is, its RTCIceCandidateaddress is in fact the real IP address of the remote peer), relatedAddress is null.

The relatedAddress field's value is set from the candidateInfo options object passed to the RTCIceCandidate(RTCIceCandidateInit) constructor.
You can't specify the value of relatedAddress directly in the options object, but its value is automatically extracted from the object's candidate a-line if it's formatted properly(the rel-address field).

The related address and port (RelatedPort) are not used at all by {{Glossary("ICE")}} itself; they are provided for analysis and diagnostic purposes only, and their inclusion may be blocked by security systems, so do not rely on them having non-null values.

-WebRTC API
-Introduction to WebRTC protocols
-WebRTC connectivity
-Lifetime of a WebRTC session
-RelatedPort
-Address and Port

See also on MDN

RelatedPort

The RTCIceCandidate interface's read-only relatedPort property indicates the port number of reflexive or relay candidates.

[Value("relatedPort")]
public ushort? RelatedPort { get; }

Property Value

ushort?

An unsigned 16-bit value containing the candidate's related port number, if any. For
both peer and server reflexive candidates, the related address and port describe the
base for that candidate. For relay candidates, the related address and port provide the
mapped address selected by the TURN server.For host candidates, relatedPort is null, meaning the field is not included in the candidate's a-line.

Remarks

If the candidate is a host candidate (that is, its RTCIceCandidateaddress is in fact the real IP address of the remote peer), relatedPort is null.

The relatedPort field's value is set from the candidateInfo options object passed to the RTCIceCandidate(RTCIceCandidateInit) constructor.
You can't specify the value of relatedPort directly in the options object, but its value is automatically extracted from the object's candidate a-line, if it's formatted properly (the rel-port field).

The related address (RelatedAddress) and port are not used at all by {{Glossary("ICE")}} itself; they are provided for
analysis and diagnostic purposes only, and their inclusion may be blocked by security systems, so do not rely on them having non-null values.

-WebRTC API
-Introduction to WebRTC protocols
-WebRTC connectivity
-Lifetime of a WebRTC session
-RelatedAddress
-Address and Port

See also on MDN

RelayProtocol 

[Value("relayProtocol")]
public RTCIceServerTransportProtocol? RelayProtocol { get; }

Property Value

RTCIceServerTransportProtocol?

SdpMLineIndex

The read-only sdpMLineIndex property on the RTCIceCandidate interface
is a zero-based index of the m-line describing the media associated with the candidate.

[Value("sdpMLineIndex")]
public ushort? SdpMLineIndex { get; }

Property Value

ushort?

A number containing a 0-based index into the set of m-lines providing media descriptions,
indicating which media source is associated with the candidate, or null if no such association is available.

NOTE
Attempting to add a candidate (using
AddIceCandidate(RTCIceCandidateInit)) that has a
value of null for either sdpMid or
sdpMLineIndex will throw a TypeError exception.

Remarks

This property can be configured by specifying the value of the sdpMLineIndex property in the candidateInfo options object that is passed to the RTCIceCandidate(RTCIceCandidateInit) constructor.
If you call the constructor with an m-line string instead of the options object, the value of sdpMLineIndex is extracted from the specified candidate m-line string.

See also on MDN

SdpMid

The read-only property sdpMid on the RTCIceCandidate interface returns a string
specifying the media stream identification tag of the media component with which the candidate is associated.
This ID uniquely identifies a given stream for the component with which the candidate is associated.

[Value("sdpMid")]
public string? SdpMid { get; }

Property Value

string

A string which uniquely identifies the source media component from
which the candidate draws data, or null if no such association exists for the candidate.

NOTE
Attempting to add a candidate (using AddIceCandidate(RTCIceCandidateInit)) that has a
value of null for both sdpMid and sdpMLineIndex will throw a TypeError exception.

Remarks

This property can be configured by specifying the value of the sdpMid property in the candidateInfo options object that is passed to the RTCIceCandidate(RTCIceCandidateInit) constructor.
If you call the constructor with an m-line string instead of the options object, the value of sdpMid is extracted from the specified candidate m-line string.

See also on MDN

TcpType

The RTCIceCandidate interface's read-only tcpType property is included on TCP candidates to provide additional details about the candidate type.

[Value("tcpType")]
public RTCIceTcpCandidateType? TcpType { get; }

Property Value

RTCIceTcpCandidateType?

If the Protocol is "tcp", tcpType has one of the following values:tcpType is null for UDP candidates.

Remarks

The tcpType field's value is set from the candidateInfo options object passed to the RTCIceCandidate(RTCIceCandidateInit) constructor.
You can't specify the value of tcpType directly in the options object, but its value is automatically extracted from the object's candidate a-line, if it's formatted properly.

-WebRTC API
-Introduction to WebRTC protocols
-WebRTC connectivity
-Protocol
-Type

See also on MDN

Type

The RTCIceCandidate interface's read-only type specifies the type of candidate the object represents.

[Value("type")]
public RTCIceCandidateType? Type { get; }

Property Value

RTCIceCandidateType?

A string whose value is one of those defined below. These candidate types are listed in order of priority; the higher in the list they are, the more efficient they are.If type is null, that information was missing from the
Candidate's a-line, which will cause
AddIceCandidate(RTCIceCandidateInit) to throw an
OperationError exception.

Remarks

The type field's value is set from the candidateInfo options object passed to the RTCIceCandidate(RTCIceCandidateInit) constructor.
You can't specify the value of type directly in the options object, but its value is automatically extracted from the object's candidate a-line (the cand-type field), if it's formatted properly.

-WebRTC API
-Introduction to WebRTC protocols
-WebRTC connectivity
-TcpType

See also on MDN

Url 

[Value("url")]
public string? Url { get; }

Property Value

string

UsernameFragment

The read-only usernameFragment property on the RTCIceCandidate interface is a string indicating the
username fragment ("ufrag") that uniquely identifies a single ICE interaction session.

[Value("usernameFragment")]
public string? UsernameFragment { get; }

Property Value

string

A string containing the username fragment (usually referred to in
shorthand as "ufrag" or "ice-ufrag") that, along with the ICE password ("ice-pwd"),
uniquely identifies a single ongoing ICE interaction, including for any communication
with the STUN server. The string may be up to 256 characters long, and
has no default value.

Remarks

This value is specified using the usernameFragment property in the candidateInfo options object that is passed to the RTCIceCandidate(RTCIceCandidateInit) constructor.
If you call the constructor with an m-line string instead of the options object, the value of usernameFragment is extracted from the specified candidate m-line string.

Note that 24 bits of the username fragment are required to be randomized by the browser. See Randomization below for details.

See also on MDN

Methods

ToJSON()

The RTCIceCandidate method toJSON() converts the RTCIceCandidate on which it's called into JSON.

[Value("toJSON")]
public RTCIceCandidateInit ToJSON()

Returns

RTCIceCandidateInit

A JSON object with the following properties, which have been set to the corresponding values in the RTCIceCandidate object:

NOTE
The returned JSON object has the same form/properties as the candidateInfo object that can optionally be passed to the RTCIceCandidate(RTCIceCandidateInit) constructor to configure the candidate.

Remarks

A stringified version of the object can then be obtained by calling JSONStringify on the returned object.

See also on MDN

Edit this page