rtc_ice/
lib.rs

1#![warn(rust_2018_idioms)]
2#![warn(missing_docs)]
3#![allow(dead_code)]
4
5//! ICE for the Sans-I/O WebRTC stack.
6//!
7//! Interactive Connectivity Establishment ([RFC 8445], superseding [RFC 5245]) with the
8//! extensions WebRTC uses: ICE-TCP candidates ([RFC 6544]), consent freshness
9//! ([RFC 7675]), and Trickle ICE. ICE is what finds a path between two peers behind NATs:
10//! it gathers candidate addresses, pairs local with remote, and probes each pair with STUN
11//! connectivity checks until one succeeds.
12//!
13//! # Structure
14//!
15//! * [`agent`] — the Sans-I/O [`Agent`]: give it candidates and inbound
16//!   datagrams, poll it for checks to send, state transitions, and the selected pair. It
17//!   owns no sockets and no clock.
18//! * [`candidate`] — the candidate types (host, server-reflexive, peer-reflexive, relay),
19//!   their priorities, and SDP `a=candidate` parsing.
20//! * [`state`] — connection and gathering states, and the checklist state machine.
21//! * [`url`] — parsing `stun:`/`turn:` server URLs into something the agent can gather from.
22//! * [`network_type`], [`tcp_type`] — UDP/TCP and active/passive/simultaneous-open.
23//! * [`stats`] — per-candidate and per-pair counters, surfaced through `getStats`.
24//! * [`mdns`] — mDNS candidate handling, for hiding private addresses.
25//!
26//! # Example
27//!
28//! ```
29//! use rtc_ice::url::{ProtoType, SchemeType, Url};
30//!
31//! # fn example() -> Result<(), Box<dyn std::error::Error>> {
32//! let stun = Url::parse_url("stun:stun.l.google.com:19302")?;
33//! assert_eq!(stun.scheme, SchemeType::Stun);
34//! assert_eq!(stun.port, 19302);
35//!
36//! // TURN URLs may pin the transport used to reach the server.
37//! let turn = Url::parse_url("turn:turn.example.com:3478?transport=tcp")?;
38//! assert_eq!(turn.scheme, SchemeType::Turn);
39//! assert_eq!(turn.proto, ProtoType::Tcp);
40//! # Ok(())
41//! # }
42//! ```
43//!
44//! Most applications do not depend on this crate directly — the
45//! [`rtc`](https://docs.rs/rtc) crate drives the agent as one layer of the peer-connection
46//! pipeline.
47//!
48//! [RFC 8445]: https://datatracker.ietf.org/doc/html/rfc8445
49//! [RFC 5245]: https://datatracker.ietf.org/doc/html/rfc5245
50//! [RFC 6544]: https://datatracker.ietf.org/doc/html/rfc6544
51//! [RFC 7675]: https://datatracker.ietf.org/doc/html/rfc7675
52
53/// The Sans-I/O ICE agent: candidate pairing, connectivity checks, and nomination.
54pub mod agent;
55/// The ICE-specific STUN attributes carried in connectivity checks.
56pub mod attributes;
57/// Candidate types, priorities, and SDP `a=candidate` parsing.
58pub mod candidate;
59/// mDNS candidate handling, which hides private addresses behind `.local` names.
60pub mod mdns;
61/// UDP/TCP over IPv4/IPv6, as a candidate's transport.
62pub mod network_type;
63/// Random ICE credentials and identifiers.
64pub mod rand;
65/// Connection and gathering states.
66pub mod state;
67/// Per-candidate and per-pair counters, surfaced through `getStats`.
68pub mod stats;
69/// Active, passive and simultaneous-open, for ICE-TCP candidates.
70pub mod tcp_type;
71/// Parsing `stun:`/`turn:` server URLs.
72pub mod url;
73
74pub use agent::{
75    Agent, Credentials, Event,
76    agent_config::AgentConfig,
77    agent_stats::{CandidatePairStats, CandidateStats},
78};
rtc_ice/lib.rs

rtc_ice/
lib.rs
