webrtc_m130/p2p/g3doc/ice.md

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.

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

• cricket::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 cricket::PortInterface cricket::UDPPort, cricket::StunPort, cricket::TcpPort and cricket::TurnPort. The ports share lots of functionality in a base class, cricket::Port.

• cricket::Candidate represents an address discovered by a cricket::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)

• cricket::Connection provides the management of a cricket::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).

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

• cricket::P2PTransportChannel uses an cricket::IceControllerInterface to manage a set of connections. The cricket::IceControllerInterface decides which cricket::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 cricket::PortAllocator to create a cricket::PortAllocatorSession. The cricket::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 cricket::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 cricket::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 cricket::Connection(s) will be added to the cricket::IceController that will decide which cricket::Connection to send STUN ping on.

4. P2PTransportChannel::SignalCandidatePairChanged When a remote connection replies to a STUN ping, cricket::IceController will instruct P2PTransportChannel to use the connection. This is signalled up the stack using P2PTransportChannel::SignalCandidatePairChanged. Note that cricket::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 cricket::DtlsTransportInternal initiate a DTLS handshake (depending on the DTLS role).