ICE

Overview

ICE (link) provides unreliable packet transport between two clients (p2p) or between a client and a server.

This documentation provides an overview of how ICE is implemented, i.e how the following classes interact.

  • webrtc::IceTransportInternal - is the interface that does ICE (manage ports, candidates, connections to send/receive packets). The interface is implemented by webrtc::P2PTransportChannel.

  • webrtc::PortInterface Represents a local communication mechanism that can be used to create connections to similar mechanisms of the other client. There are 4 implementations of webrtc::PortInterface webrtc::UDPPort, webrtc::StunPort, webrtc::TcpPort and webrtc::TurnPort. The ports share lots of functionality in a base class, webrtc::Port.

  • webrtc::Candidate represents an address discovered by a webrtc::Port. A candidate can be local (i.e discovered by a local port) or remote. Remote candidates are transported using signaling, i.e outside of webrtc. There are 4 types of candidates: local, stun, prflx or relay (standard)

  • webrtc::Connection provides the management of a webrtc::CandidatePair, i.e for sending data between two candidates. It sends STUN Binding requests (aka STUN pings) to verify that packets can traverse back and forth and keep connections alive (both that NAT binding is kept, and that the remote peer still wants the connection to remain open).

  • webrtc::P2PTransportChannel uses an webrtc::PortAllocator to create ports and discover local candidates. The webrtc::PortAllocator is implemented by webrtc::BasicPortAllocator.

  • webrtc::P2PTransportChannel uses an webrtc::IceControllerInterface to manage a set of connections. The webrtc::IceControllerInterface decides which webrtc::Connection to send data on.

Connection establishment

This section describes a normal sequence of interactions to establish ice state completed link ( standard )

All of these steps are invoked by interactions with PeerConnection.

  1. P2PTransportChannel::MaybeStartGathering This function is invoked as part of PeerConnection::SetLocalDescription. P2PTransportChannel will use the webrtc::PortAllocator to create a webrtc::PortAllocatorSession. The webrtc::PortAllocatorSession will create local ports as configured, and the ports will start gathering candidates.

  2. IceTransportInternal::SignalCandidateGathered When a port finds a local candidate, it will be added to a list on webrtc::P2PTransportChannel and signaled to application using IceTransportInternal::SignalCandidateGathered. A p2p application can then send them to peer using favorite transport mechanism whereas a client-server application will do nothing.

  3. P2PTransportChannel::AddRemoteCandidate When the application get a remote candidate, it can add it using PeerConnection::AddRemoteCandidate (after PeerConnection::SetRemoteDescription has been called!), this will trickle down to P2PTransportChannel::AddRemoteCandidate. P2PTransportChannel will combine the remote candidate with all compatible local candidates to form new webrtc::Connection(s). Candidates are compatible if it is possible to send/receive data (e.g ipv4 can only send to ipv4, tcp can only connect to tcp etc...) The newly formed webrtc::Connection(s) will be added to the webrtc::IceController that will decide which webrtc::Connection to send STUN ping on.

  4. P2PTransportChannel::SignalCandidatePairChanged When a remote connection replies to a STUN ping, webrtc::IceController will instruct P2PTransportChannel to use the connection. This is signalled up the stack using P2PTransportChannel::SignalCandidatePairChanged. Note that webrtc::IceController will continue to send STUN pings on the selected connection, as well as other connections.

  5. P2PTransportChannel::SignalIceTransportStateChanged The initial selection of a connection makes P2PTransportChannel signal up stack that state has changed, which may make webrtc::DtlsTransportInternal initiate a DTLS handshake (depending on the DTLS role).