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 thecandidateis 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 hostthe corresponding
candidatestring'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
nullif there is no associated media stream. The default isnull.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
nullif no such associated exists. The default isnull.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
RTCIceCandidateobject is initialized to the value of the property by the same name fromcandidateInfo. This includes the RTCIceCandidate.candidate, RTCIceCandidate.sdpMid, RTCIceCandidate.sdpMLineIndex, and RTCIceCandidate.usernameFragment properties. - The
candidatestring (which is SDP text) is parsed; each property found is stored in the corresponding field in theRTCIceCandidate. If any of the fields is invalid, parsing of the string silently aborts without throwing an exception. The default value ofcandidateis the empty string, which indicates that the candidate is an "end-of-candidates" message. - The following fields are initialized to
nullif 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
candidatestring is performed using the candidate-attribute grammar from the WebRTC Specification.
Exceptions
- TypeError
- : Thrown if the specified
candidateInfohas values ofnullin both thesdpMidandsdpMLineIndexproperties.
- : Thrown if the specified
Usage notes
This constructor does not do complete validation of the specified candidateInfo object or string.
Specifications
Browser compatibility
See also
- Introduction to WebRTC protocols
- WebRTC connectivity
- Lifetime of a WebRTC session
- Signaling and video calling
来源:MDN Web Docs / Mozilla 贡献者 · 作者与贡献记录 · CC BY-SA 2.5。离线整理了版式、链接和媒体显示。
