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.

Methods

The RTCIceGatherer object has these methods.

Properties

The RTCIceGatherer object has these properties.

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');
  }
}