大网数据广告活动
Web 标准与前端开发

RTCIceCandidate: RTCIceCandidate() constructor

· 52CE 我爱测

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

WebRTC

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

Syntax

new RTCIceCandidate()
new RTCIceCandidate(candidateInfo)

Parameters

  • candidateInfo
    • : An optional object that can be provided to configure the candidate. The object has the following properties:

      • candidate

        • : 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 . For an a-line (attribute line) that looks like this:

          a=candidate:4234997325 1 udp 2043278322 192.0.2.172 44323 typ host
          

          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 RTCIceCandidate.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:

          • RTCIceCandidate.foundation = 4234997325
          • RTCIceCandidate.component = "rtp" (the number 1 is encoded to this string; 2 becomes "rtcp")
          • RTCIceCandidate.protocol = "udp"
          • RTCIceCandidate.priority = 2043278322
          • RTCIceCandidate/address = "192.0.2.172"
          • RTCIceCandidate.port = 44323
          • RTCIceCandidate.type = "host"

          Additional information can be found in RTCIceCandidate.candidate.

          [!NOTE] For backward compatibility with older versions of the WebRTC specification, the constructor also accepts this string directly as an argument.

      • sdpMid

        • : A string containing the identification tag of the media stream with which the candidate is associated, or null if there is no associated media stream. The default is null.

          Additional information can be found in RTCIceCandidate.sdpMid.

      • sdpMLineIndex

        • : A number property containing the zero-based index of the m-line with which the candidate is associated, within the SDP of the media description, or null if no such associated exists. The default is null.

          Additional information can be found in RTCIceCandidate.sdpMLineIndex.

      • usernameFragment

        • : A string containing the username fragment (usually referred to in shorthand as "ufrag" or "ice-ufrag"). This fragment, along with the ICE password ("ice-pwd"), uniquely identifies a single ongoing ICE interaction (including for any communication with the STUN server).

          The string is generated by WebRTC at the beginning of the session. It may be up to 256 characters long, and at least 24 bits must contain random data. It has no default value and is not present unless set explicitly.

          Additional information can be found in RTCIceCandidate.usernameFragment.

Return value

A newly-created RTCIceCandidate object.

If candidateInfo is provided, the new RTCIceCandidate is initialized as follows:

  • Each member of the RTCIceCandidate object is initialized to the value of the property by the same name from candidateInfo. This includes the RTCIceCandidate.candidate, RTCIceCandidate.sdpMid, RTCIceCandidate.sdpMLineIndex, and RTCIceCandidate.usernameFragment properties.
  • The candidate string (which is SDP text) is parsed; each property found is stored in the corresponding field in the RTCIceCandidate. If any of the fields is invalid, parsing of the string silently aborts without throwing an exception. The default value of candidate is the empty string, which indicates that the candidate is an "end-of-candidates" message.
  • The following fields are initialized to null if they are not included in the RTCIceCandidate.candidate property: RTCIceCandidate.foundation, RTCIceCandidate.component, RTCIceCandidate.priority, RTCIceCandidate/address, RTCIceCandidate.protocol, RTCIceCandidate.port, RTCIceCandidate.type, RTCIceCandidate.tcpType, RTCIceCandidate.relatedAddress, and RTCIceCandidate.relatedPort.

[!NOTE] Parsing of the candidate string is performed using the candidate-attribute grammar from the WebRTC Specification.

Exceptions

  • TypeError
    • : Thrown if the specified candidateInfo has values of null in both the sdpMid and sdpMLineIndex properties.

Usage notes

This constructor does not do complete validation of the specified candidateInfo object or string.

Specifications

Browser compatibility

See also

来源:MDN Web Docs / Mozilla 贡献者 · 作者与贡献记录 · CC BY-SA 2.5。离线整理了版式、链接和媒体显示。

资料来源与适用范围

资料来源
MDN Web Docs / Mozilla 贡献者
适用范围
请按文中版本与环境说明核对
内容语言
中文;命令、路径和错误标识保留技术原文
本地收录日期
2026-11-15
授权说明
CC BY-SA 2.5

正文与所需资源由本站本地存储。查看来源及更新记录 ↗

请按适用版本和实际日志确认原因;本站没有对每一种系统或设备逐项执行文中的操作。