RTCIceGatherer object

[Some information relates to pre-released product which may be substantially modified before it's commercially released. Microsoft makes no warranties, express or implied, with respect to the information provided here.]

Gathers local host, server reflexive and relay candidates, as well as enabling the retrieval of local Interactive Connectivity Establishment (ICE) parameters which can be exchanged in signaling.

Overview

The Microsoft Edge implementation of the RTCIceGatherer does not support the component or state attributes, nor does it support the close() method or the ongatherstatechange event handler.

Note  Edge Interop Note: In the Microsoft Edge implementation, an RTCIceGatherer instance can only be associated to a single RTCIceTransport object. As a result, forking scenarios are not supported. The RTCIceGatherer prunes local candidates when its associated RTCIceTransport object enters the "completed" state.

 

As noted in [RFC5245] Section 7.1.2.2, an incoming connectivity check contains an ICE-CONTROLLING or ICE-CONTROLLED attribute, depending on the role of the ICE agent initiating the check. Since an RTCIceGatherer object does not have a role, it cannot determine whether to respond to an incoming connectivity check with a 487 (Role Conflict) error; however, it can validate that an incoming connectivity check utilizes the correct local username fragment and password, and if not, can respond with an 401 (Unauthorized) error, as described in [RFC5389] Section 10.1.2.

Operation

An RTCIceGatherer instance is constructed from an RTCIceGatherOptions object.

Syntax

var iceGatherer = new RTCIceGatherer(gatherOptions);

 

Members

The RTCIceGatherer object has these types of members:

• Events
• Methods
• Properties

Events

The RTCIceGatherer object has these events.

Event	Description
onerror	This event fires if TURN credentials are invalid.
onlocalcandidate	Fires when a new local ICE candidate is available.
RTCIceGathererEvent	Fires in relation to RTCIceCandidates being gathered by the RTCIceGatherer object.

 

Methods

The RTCIceGatherer object has these methods.

Method	Description
createAssociatedGatherer	Create an associated RTCIceGatherer for RTCP.
getLocalCandidates	Retrieves the sequence of valid local candidates associated with the RTCIceGatherer. All unpruned local candidates currently known (except for peer reflexive candidates) will be retrieved, even if an onlocalcandidate event hasn't been processed yet.
getLocalParameters	Retrieves the ICE parameters of the RTCIceGatherer.

 

Properties

The RTCIceGatherer object has these properties.

Property	Access type	Description
component	Read-only	The component-id of the RTCIceGatherer.
RTCIceCandidateComplete		A dictionary signifying that all RTCIceCandidates are gathered.
RTCIceGatherPolicy		Determines the policy relating to the gathering of ICE candidates.

 

Standards information

• Object RTC (ORTC) API for WebRTC

Remarks

Interface Definition

[Constructor(RTCIceGatherOptions options)]
interface RTCIceGatherer : RTCStatsProvider {
    RTCIceParameters          getLocalParameters ();
    sequence<RTCIceCandidate> getLocalCandidates ();
    RTCIceGatherer            createAssociatedGatherer ();
                attribute EventHandler? onerror;
                attribute EventHandler? onlocalcandidate;
};

EXAMPLES

Example to demonstrate use of RTCIceCandidateComplete including helper functions:

// Include some helper functions
import "helper.js";
// Create ICE gather options
var gatherOptions = new RTCIceGatherOptions();
gatherOptions.gatherPolicy = RTCIceGatherPolicy.relay;
gatherOptions.iceservers = [ { urls: "stun:stun1.example.net" } , 
  { urls:"turn:turn.example.org", username: "user", credential:"myPassword"} ];
// Create ICE gatherer objects
var iceGatherer = new RTCIceGatherer(gatherOptions);
// Prepare to signal local candidates as well as "end of candidates"
iceGatherer.onlocalcandidate = function (event) {
  mySendLocalCandidate(event.candidate);
}; 
// Set up response function
mySignaller.onResponse = function(responseSignaller,response) {
  // The Microsoft Edge ORTC implementation only supports a single response. 
};

mySignaller.send({
   "ice": iceGatherer.getLocalParameters()
});

Example 2

// Helper functions used in all the examples (helper.js)
function trace(text) {
  // This function is used for logging.
  if (text[text.length - 1] === '\n') {
    text = text.substring(0, text.length - 1);
  }
  if (window.performance) {
    var now = (window.performance.now() / 1000).toFixed(3);
    console.log(now + ': ' + text);
  } else {
    console.log(text);
  }
}

function errorHandler (error) {
  trace('Error encountered: ' + error.name);
}

function mySendLocalCandidate(candidate, component, kind){
  // Set default values
  kind = kind || "all";
  component = component || RTCIceComponent.RTP;
  parameters = parameters || null; 
  // Signal the local candidate 
  mySignaller.mySendLocalCandidate({
  "candidate": candidate,
  "component": component,
  "kind": kind
  });
}

function myIceTransportStateChange(name, state){
  switch(state){
  case RTCIceTransportState.new:
     trace('IceTransport: ' + name + ' Has been created');
     break;
  case RTCIceTransportState.checking:
     trace('IceTransport: ' + name + ' Is checking');
     break;
  case RTCIceTransportState.connected:
     trace('IceTransport: ' + name + ' Is connected');
     break;
  case RTCIceTransportState.disconnected:
     trace('IceTransport: ' + name + ' Is disconnected');
     break;
  case RTCIceTransportState.completed:
     trace('IceTransport: ' + name + ' Has finished checking (for now)');
     break;
  case RTCIceTransportState.closed:
     trace('IceTransport: ' + name + ' Is closed');
     break;
  default:
     trace('IceTransport: ' + name + ' Invalid state');
  }
}

function myDtlsTransportStateChange(name, state){
  switch(state){
  case RTCDtlsTransportState.new:
     trace('DtlsTransport: ' + name + ' Has been created');
     break;
  case RTCDtlsTransportState.connecting:
     trace('DtlsTransport: ' + name + ' Is connecting');
     break;
  case RTCDtlsTransportState.connected:
     trace('DtlsTransport: ' + name + ' Is connected');
     break;
  case RTCDtlsTransportState.closed:
     trace('DtlsTransport: ' + name + ' Is closed');
     break;
  default:
     trace('DtlsTransport: ' + name + ' Invalid state');
  }
}