RTCIceTransport

The ICE transport of a connection, which can also be used on its own.

class webrtc.interfaces.rtc_ice_transport.RTCIceTransport

The ICE transport a webrtc.RTCDtlsTransport of a connection runs over, or a standalone one.

A standalone transport (RTCIceTransport(), from WebRTC Extensions) is driven by hand. Call gather(), start() and add_remote_candidate(), then stop() when done. Those methods raise for a transport of a connection.

See MDN: RTCIceTransport.

Events:

statechange (webrtc.Event) – state changed.
gatheringstatechange (webrtc.Event) – gathering_state changed.
selectedcandidatepairchange (webrtc.Event) – get_selected_candidate_pair() changed.
icecandidate (webrtc.RTCPeerConnectionIceEvent) – A standalone transport gathered a candidate, or None once it gathered them all.
error (webrtc.Event) – A standalone transport failed. It never fires, because the native ICE agent doesn’t report it.

Events

statechange: Event
gatheringstatechange: Event
selectedcandidatepairchange: Event
error: Event
icecandidate: RTCPeerConnectionIceEvent

Handlers are registered with on().

gather(options=None)

Starts gathering the local candidates of a standalone transport, each sent in an icecandidate event.

Parameters:

options (webrtc.RTCIceGatherOptions, optional) – The policy and the ICE servers to gather with.

Raises:

webrtc.InvalidStateError – If it’s stopped, gathering already, or belongs to a connection.
webrtc.InvalidSyntaxError – If an ICE server URL is invalid.
webrtc.InvalidAccessError – If a TURN server has no credentials.
TypeError – If the policy isn’t a value of webrtc.RTCIceTransportPolicy.

start(remote_parameters=None, role='controlled')

Starts connectivity checks of a standalone transport with the remote agent.

Checks use the remote candidates added so far and any added later. Calling it again with other remote parameters (an ICE restart of the remote agent) drops the remote candidates added before.

Parameters:

remote_parameters (webrtc.RTCIceParameters, optional) – The username fragment and the password of the remote agent. Both are required, even though the argument has a default.
role (webrtc.RTCIceRole, optional) – Controlling or controlled (the default). If both agents pick the same role, the conflict is resolved and one of them switches.

Raises:

webrtc.InvalidStateError – If it’s stopped, started with another role, or belongs to a connection.
webrtc.InvalidSyntaxError – If the username fragment or the password is invalid.
ValueError – If the role is neither controlling nor controlled.

add_remote_candidate(remote_candidate=None)

Adds a candidate of the remote agent to a standalone transport.

The object passed is the one get_remote_candidates() returns for it.

Parameters:

remote_candidate (webrtc.RTCIceCandidate or webrtc.RTCIceCandidateInit, optional) – The candidate, which needs sdp_mid or sdp_m_line_index to be set.

Raises:

TypeError – If the candidate has neither sdp_mid nor sdp_m_line_index.
webrtc.InvalidStateError – If it’s stopped, or belongs to a connection.
webrtc.OperationError – If the candidate can’t be parsed.

stop()

Stops a standalone transport for good.

Its state becomes closed without a statechange event.

Raises:: webrtc.InvalidStateError – If it belongs to a connection.

get_selected_candidate_pair()

Returns the local and the remote candidate the transport sends and receives with.

A remote peer-reflexive candidate comes from connectivity checks. It has an empty candidate and no address.

See MDN: RTCIceTransport/getSelectedCandidatePair.

Returns:: webrtc.RTCIceCandidatePair, optional – The pair, or None until one is selected.
Return type:: RTCIceCandidatePair | None

get_local_candidates()

Returns the local candidates gathered for the transport so far.

Each call returns the same objects. For a standalone transport, they’re the ones of its icecandidate events.

See MDN: RTCIceTransport/getLocalCandidates.

Returns:: list of webrtc.RTCIceCandidate – The candidates.
Return type:: list[RTCIceCandidate]

get_remote_candidates()

Returns the candidates the remote peer signaled for the transport, without peer-reflexive ones.

They come from its description, webrtc.RTCPeerConnection.add_ice_candidate() or add_remote_candidate().

See MDN: RTCIceTransport/getRemoteCandidates.

Returns:: list of webrtc.RTCIceCandidate – The candidates.
Return type:: list[RTCIceCandidate]

get_local_parameters()

Returns the local username fragment and password of the transport, with ice_lite False.

See MDN: RTCIceTransport/getLocalParameters.

Returns:: webrtc.RTCIceParameters, optional – The parameters, or None without a local description.
Return type:: RTCIceParameters | None

get_remote_parameters()

Returns the remote username fragment and password of the transport, with ice_lite unknown.

See MDN: RTCIceTransport/getRemoteParameters.

Returns:: webrtc.RTCIceParameters, optional – The parameters, or None without a remote description.
Return type:: RTCIceParameters | None