RTCIceTransport.getSelectedCandidatePair()

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.transport;
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

Update compatibility data on GitHub
DesktopMobile
ChromeEdgeFirefoxInternet ExplorerOperaSafariAndroid webviewChrome for AndroidEdge MobileFirefox for AndroidOpera for AndroidiOS SafariSamsung Internet
Basic supportChrome No support NoEdge Full support 13
Alternate Name
Full support 13
Alternate Name
Alternate Name Uses the non-standard name: getNominatedCandidatePair
Firefox No support NoIE No support NoOpera No support NoSafari No support NoWebView Android No support NoChrome Android No support NoEdge Mobile ? Firefox Android No support NoOpera Android No support NoSafari iOS No support NoSamsung Internet Android No support No

Legend

Full support  
Full support
No support  
No support
Compatibility unknown  
Compatibility unknown
Uses a non-standard name.
Uses a non-standard name.

 

Document Tags and Contributors

Contributors to this page: Sheppy
Last updated by: Sheppy,