Add module overview of ICE
Bug: webrtc:12550 Change-Id: I9e14c916d978db092406a248d7895b3c22c82cbc Reviewed-on: https://webrtc-review.googlesource.com/c/src/+/214982 Commit-Queue: Jonas Oreland <jonaso@webrtc.org> Reviewed-by: Artem Titov <titovartem@webrtc.org> Cr-Commit-Position: refs/heads/master@{#33692}
This commit is contained in:
Jonas Oreland
committed by
Commit Bot
Commit Bot
parent
9de39f6c45
commit
0aa1a19be0
@ -5,7 +5,11 @@
|
||||
* [Public C++ API](/api/g3doc/index.md)
|
||||
* [Threading](/api/g3doc/threading_design.md)
|
||||
* Implementation
|
||||
* Network
|
||||
* Network
|
||||
* [ICE](/p2p/g3doc/ice.md)
|
||||
* STUN
|
||||
* DTLS
|
||||
* TURN
|
||||
* Congestion control and bandwidth estimation
|
||||
* Audio
|
||||
* Video
|
||||
|
||||
102
p2p/g3doc/ice.md
Normal file
102
p2p/g3doc/ice.md
Normal file
@ -0,0 +1,102 @@
|
||||
# ICE
|
||||
|
||||
<?% config.freshness.owner = 'jonaso' %?> <?% config.freshness.reviewed =
|
||||
'2021-04-12' %?>
|
||||
|
||||
## Overview
|
||||
|
||||
ICE ([link](https://developer.mozilla.org/en-US/docs/Glossary/ICE)) 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`](https://source.chromium.org/chromium/chromium/src/+/master:third_party/webrtc/p2p/base/ice_transport_internal.h;l=225;drc=8cb97062880b0e0a78f9d578370a01aced81a13f) -
|
||||
is the interface that does ICE (manage ports, candidates, connections to
|
||||
send/receive packets). The interface is implemented by
|
||||
[`cricket::P2PTransportChannel`](https://source.chromium.org/chromium/chromium/src/+/master:third_party/webrtc/p2p/base/p2p_transport_channel.h;l=103;drc=0ccfbd2de7bc3b237a0f8c30f48666c97b9e5523).
|
||||
|
||||
* [`cricket::PortInterface`](https://source.chromium.org/chromium/chromium/src/+/master:third_party/webrtc/p2p/base/port_interface.h;l=47;drc=c3a486c41e682cce943f2b20fe987c9421d4b631)
|
||||
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`](https://source.chromium.org/chromium/chromium/src/+/master:third_party/webrtc/p2p/base/stun_port.h;l=33;drc=a4d873786f10eedd72de25ad0d94ad7c53c1f68a),
|
||||
[`cricket::StunPort`](https://source.chromium.org/chromium/chromium/src/+/master:third_party/webrtc/p2p/base/stun_port.h;l=265;drc=a4d873786f10eedd72de25ad0d94ad7c53c1f68a),
|
||||
[`cricket::TcpPort`](https://source.chromium.org/chromium/chromium/src/+/master:third_party/webrtc/p2p/base/tcp_port.h;l=33;drc=7a284e1614a38286477ed2334ecbdde78e87b79c)
|
||||
and
|
||||
[`cricket::TurnPort`](https://source.chromium.org/chromium/chromium/src/+/master:third_party/webrtc/p2p/base/turn_port.h;l=44;drc=ffb7603b6025fbd6e79f360d293ab49092bded54).
|
||||
The ports share lots of functionality in a base class,
|
||||
[`cricket::Port`](https://source.chromium.org/chromium/chromium/src/+/master:third_party/webrtc/p2p/base/port.h;l=187;drc=3ba7beba29c4e542c4a9bffcc5a47d5e911865be).
|
||||
|
||||
* [`cricket::Candidate`](https://source.chromium.org/chromium/chromium/src/+/master:third_party/webrtc/api/candidate.h;l=30;drc=10542f21c8e4e2d60b136fab45338f2b1e132dde)
|
||||
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](https://developer.mozilla.org/en-US/docs/Web/API/RTCIceCandidateType))
|
||||
|
||||
* [`cricket::Connection`](https://source.chromium.org/chromium/chromium/src/+/master:third_party/webrtc/p2p/base/connection.h)
|
||||
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`](https://source.chromium.org/chromium/chromium/src/+/master:third_party/webrtc/p2p/base/port_allocator.h;l=335;drc=9438fb3fff97c803d1ead34c0e4f223db168526f)
|
||||
to create ports and discover local candidates. The `cricket::PortAllocator`
|
||||
is implemented by
|
||||
[`cricket::BasicPortAllocator`](https://source.chromium.org/chromium/chromium/src/+/master:third_party/webrtc/p2p/client/basic_port_allocator.h;l=29;drc=e27f3dea8293884701283a54f90f8a429ea99505).
|
||||
|
||||
* `cricket::P2PTransportChannel` uses an
|
||||
[`cricket::IceControllerInterface`](https://source.chromium.org/chromium/chromium/src/+/master:third_party/webrtc/p2p/base/ice_controller_interface.h;l=73;drc=9438fb3fff97c803d1ead34c0e4f223db168526f)
|
||||
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 ](https://source.chromium.org/chromium/chromium/src/+/master:third_party/webrtc/p2p/base/ice_transport_internal.h;l=208;drc=9438fb3fff97c803d1ead34c0e4f223db168526f)
|
||||
([ standard ](https://developer.mozilla.org/en-US/docs/Web/API/RTCPeerConnection/iceConnectionState))
|
||||
|
||||
All of these steps are invoked by interactions with `PeerConnection`.
|
||||
|
||||
1. [`P2PTransportChannel::MaybeStartGathering`](https://source.chromium.org/chromium/chromium/src/+/master:third_party/webrtc/p2p/base/p2p_transport_channel.cc;l=864;drc=0ccfbd2de7bc3b237a0f8c30f48666c97b9e5523)
|
||||
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`](https://source.chromium.org/chromium/chromium/src/+/master:third_party/webrtc/p2p/base/ice_transport_internal.h;l=293;drc=8cb97062880b0e0a78f9d578370a01aced81a13f)
|
||||
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`](https://source.chromium.org/chromium/chromium/src/+/master:third_party/webrtc/p2p/base/p2p_transport_channel.cc;l=1233;drc=0ccfbd2de7bc3b237a0f8c30f48666c97b9e5523)
|
||||
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 decides which
|
||||
`cricket::Connection` to send STUN ping on.
|
||||
|
||||
4. [`P2PTransportChannel::SignalCandidatePairChanged`](https://source.chromium.org/chromium/chromium/src/+/master:third_party/webrtc/p2p/base/ice_transport_internal.h;l=310;drc=8cb97062880b0e0a78f9d578370a01aced81a13f)
|
||||
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`](https://source.chromium.org/chromium/chromium/src/+/master:third_party/webrtc/p2p/base/ice_transport_internal.h;l=323;drc=8cb97062880b0e0a78f9d578370a01aced81a13f)
|
||||
The initial selection of a connection makes `P2PTransportChannel` signal up
|
||||
stack that state has changed, which will make [`cricket::DtlsTransport`]
|
||||
initiate DTLS handshake.
|
||||
Reference in New Issue
Block a user