IceTransport Extensions for WebRTC

Dictionary RTCIceParameters Members

usernameFragment of type DOMString, required

ICE username fragment.

password of type DOMString, required

ICE password.

iceLite of type boolean

If only ICE-lite is supported (true) or not (false or unset). Since [RTCWEB-TRANSPORT] Section 3.4 requires browser support for full ICE, iceLite will only be true for a remote peer such as a gateway. getLocalParameters().iceLite MUST NOT be set.

Dictionary RTCIceGatherOptions Members

gatherPolicy of type RTCIceTransportPolicy

The ICE gather policy.

iceServers of type sequence<RTCIceServer>

Additional ICE servers to be configured. Since implementations MAY provide default ICE servers, and applications can desire to restrict communications to the local LAN, iceServers need not be set.

networkIds of type sequence<DOMString>

If set and non-null, ICE gathering will be limited to the network interfaces specfied by the network IDs (obtained by calling getLocalCandidates().

Constructors

RTCIceTransport

When the constructor is invoked, the user agent MUST run the following steps:

1. Create an RTCIceTransport transport.
2. Initialize transport's [[IceTransportState]], [[IceGathererState]], [[SelectedCandidatePair]] and [[IceRole]] internal slots as specified in [WEBRTC] Section 5.6.
3. Initialize transport's local ICE parameters.
4. Return transport.

No parameters.

Attributes

onerror of type EventHandler

This event handler, of event handler event type icecandidateerror, MUST be fired if an error occurs in the gathering of ICE candidates (such as if TURN credentials are invalid).

onlocalcandidate of type EventHandler

This event handler utilizes the event handler event type icecandidate.

onchecksent of type EventHandler

This event handler utilizes the event handler event type icecheck.

Methods

gather

Gather ICE candidates. If state is closed, throw an InvalidStateError.

To validate the options argument, implementations MUST run the following steps:

1. Let options be the first argument.

2. Let servers be the value of options.iceServers.

3. Let validatedServers be an empty list.

4. Run the following steps for each element in servers:

   1. Let server be the current list element.

   2. If server.urls is a string, let server.urls be a list consisting of just that string.

   3. For each url in server.urls run the following steps:

      1. Parse the url using the generic URI syntax defined in [RFC3986] and obtain the scheme name. If the parsing based on the syntax defined in [RFC3986] fails, throw a SyntaxError. If the scheme name is not implemented by the browser throw a NotSupportedError. If scheme name is turn or turns, and parsing the url using the syntax defined in [RFC7064] fails, throw a SyntaxError. If scheme name is stun or stuns, and parsing the url using the syntax defined in [RFC7065] fails, throw a SyntaxError.

      2. If scheme name is turn or turns, and either of server.username or server.credential are omitted, then throw an InvalidAccessError.

      3. If scheme name is turn or turns, and server.credentialType is "password", and server.credential is not a DOMString, then throw an InvalidAccessError and abort these steps.

   4. Append server to validatedServers.

5. Let validatedServers be the ICE servers list.

Parameter	Type	Nullable	Optional	Description
options	RTCIceGatherOptions	✘	✔

Return type: void

start

As noted in [RFC5245] Section 7.1.2.3, an incoming connectivity check utilizes the local/remote username fragment and the local password, whereas an outgoing connectivity check utilizes the local/remote username fragment and the remote password. Since start() provides role information, as well as the remote username fragment and password, once start() is called an RTCIceTransport object can respond to incoming connectivity checks based on its configured role. Since start() enables candidate pairs to be formed, it also enables initiating connectivity checks. When start() is called, the following steps MUST be run:

1. If state is closed, throw an InvalidStateError.
2. If remoteParameters.usernameFragment or remoteParameters.password is unset, throw an TypeError.
3. If remoteParameters.usernameFragment or remoteParameters.password does not conform to the syntax described in [ICE-SDP] Section 5.4, throw a SyntaxError.
4. If start() is called again and role is changed, throw an InvalidStateError.
5. If start() is called again with the same value of remoteParameters, this has no effect.
6. If start() is called for the first time, if there are remote candidates, set state to checking and start connectivity checks. If there are no remote candidates, state remains new.
7. If start() is called again but the value of remoteParameters has changed, local candidates are kept, remote candidates are flushed, candidate pairs are flushed and state transitions to new.
8. If start() is called again but the value of remoteParameters is unchanged, local candidates are flushed, candidate pairs are flushed, new candidate pairs are formed with existing remote candidates, and state transitions to checking.
9. If start() is called again with new values of remoteParameters, local candidates are flushed, remote candidates are flushed, candidate pairs are flushed and state transitions to new.

Parameter	Type	Nullable	Optional	Description
remoteParameters	RTCIceParameters	✘	✘
role	RTCIceRole = controlled	✘	✔

Return type: void

stop

Irreversibly stops the RTCIceTransport. When stop is called, the following steps MUST be run:

1. Let iceTransport be the RTCIceTransport object on which the stop method is invoked.
2. If iceTransport.state is closed, abort these steps.
3. Set iceTransport.state to closed.
4. Fire a simple event statechange at iceTransport.

No parameters.

Return type: void

addRemoteCandidate

Add a remote candidate associated with the remote RTCIceTransport. If state is closed, throw an InvalidStateError. If remoteCandidate is malformed, throw an OperationError. When the remote RTCIceTransport emits its end-of-candidates indication (as described in [WEBRTC] Section 4.8.2), addRemoteCandidate() should be called with the end-of-candidates indication as an argument, so that the local RTCIceTransport can know there are no more remote candidates expected, and can enter the completed state.

Parameter	Type	Nullable	Optional	Description
remoteCandidate	RTCIceCandidateInit	✘	✘

Return type: void

removeLocalCandidate

Removes the given local candidate. This will trigger the removal of all candidate pairs with the given local candidate, the prevention of pairing with the given local candidate, and prevention of any network activity using the given local candidate.

Parameter	Type	Nullable	Optional	Description
localCandidate	RTCIceCandidate	✘	✘

Return type: void

retainLocalCandidate

Cause the RTCIceTransport to not automatically remove the local candidate due to ICE pruning (such as when a candidate pair with a different local candidate is selected). However, the local candidate may be removed if it completely fails (such as a network interface going down).

Parameter	Type	Nullable	Optional	Description
localCandidate	RTCIceCandidate	✘	✘

Return type: void

getCandidatePairs()

Return all the candidate pairs.

Return type: sequence<RTCIceCandidatePair>

Interface Definition

[Exposed=Window]
partial dictionary RTCIceCandidateInit {
    attribute DOMString? networkId;
    // TODO: Add reference to https://wicg.github.io/netinfo/#dom-networkinformation
    attribute NetworkInformation? networkInfo;
};

Interface Definition

[Exposed=Window]
partial interface RTCIceCandidatePairInt {
    void setMinCheckInterval(double seconds);
    void setFrozen(boolean frozen);
    void select();
    Promise nominate();
    Promise waitForReceiveTimeout(double seconds);	    
};

Interface Definition

[Exposed=Window]
interface RTCIceCheck {
    readonly        attribute Promise response;
};