mozilla-central/third_party/libwebrtc/p2p/g3doc/ice.md

Source code

Revision control

Copy as Markdown

Other Tools

<!-- go/cmark -->
<!--* freshness: {owner: 'jonaso' reviewed: '2021-04-12'} *-->
# ICE
## Overview
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.
is the interface that does ICE (manage ports, candidates, connections to
send/receive packets). The interface is implemented by
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`
and
The ports share lots of functionality in a base class,
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`
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
to create ports and discover local candidates. The `cricket::PortAllocator`
is implemented by
* `cricket::P2PTransportChannel` uses an
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
All of these steps are invoked by interactions with `PeerConnection`.
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.
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.
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.
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.
The initial selection of a connection makes `P2PTransportChannel` signal up
initiate a DTLS handshake (depending on the DTLS role).