The RTCIceTransport
method getSelectedCandidatePair()
returns an RTCIceCandidatePair
object containing the current best-choice pair of ICE candidates describing the configuration of the endpoints of the transport.
Syntax
candidatePair = RTCIceTransport.getSelectedCandidatePair();
Parameters
None.
Return value
A RTCIceCandidatePair
object describing the configurations of the currently-selected candidate pair's two endpoints. local
describes the configuration of the local end of the connection, while remote
describes the remote peer's configuration.
The return value is null
if no pair of candidates has been selected yet.
Usage notes
As the ICE agent performs negotiation of a RTCPeerConnection
, it gathers and analyzes candidate configurations from each the two peers. As soon as it finds an acceptable matching pair of candidates, meeting the requirements for the connection, a selectedcandidatepairchange
event is fired at the RTCIceTransport
. From that time forward, the best matching pair of candidates will always be available by calling getSelectedCandidatePair()
.
As ICE negotiation continues, any time a pair of candidates is discovered that is better than the currently-selected pair, the new pair is selected, replacing the previous pairing, and the selectedcandidatepairchange
event is fired again.
Note: It's possible for one of the configurations in the selected candidate pair to remain unchanged when a new pairing is chosen.
Example
In this example, an event handler for selectedcandidatepairchange
is set up to update an on-screen display showing the protocol used by the currently selected candidate pair.
var iceTransport = pc.getSenders()[0].transport.iceTransport; var localProto = document.getElementById("local-protocol"); var remoteProto = document.getElementById("remote-protocol"); iceTransport.onselectedcandidatepairchange = function(event) { var pair = iceTransport.getSelectedCandidatePair(); localProtocol.innerText = pair.local.protocol.toUpperCase(); remoteProtocol.innerText = pair.remote.protocol.toUpperCase(); }
Specifications
Specification | Status | Comment |
---|---|---|
WebRTC 1.0: Real-time Communication Between Browsers The definition of 'RTCIceTransport.getSelectedCandidatePair()' in that specification. |
Candidate Recommendation | Initial specification. |
Browser compatibility
Desktop | Mobile | |||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|
getSelectedCandidatePair | Chrome No support No | Edge
No support
15 — 79
| Firefox No support No | IE No support No | Opera No support No | Safari No support No | WebView Android No support No | Chrome Android No support No | Firefox Android No support No | Opera Android No support No | Safari iOS No support No | Samsung Internet Android No support No |
Legend
- No support
- No support
- Uses a non-standard name.
- Uses a non-standard name.