rtc_shared/
lib.rs

1#![warn(rust_2018_idioms)]
2#![warn(missing_docs)]
3#![allow(dead_code)]
4
5//! Shared types and utilities for the Sans-I/O WebRTC stack.
6//!
7//! This crate holds what every other crate in the [`rtc`](https://docs.rs/rtc) stack needs:
8//! the common [`Error`](error::Error) type, the [`Marshal`](marshal::Marshal)/[`Unmarshal`](marshal::Unmarshal)
9//! traits that every protocol codec implements, and the transport plumbing that carries
10//! bytes between the network and a protocol state machine.
11//!
12//! # Key types
13//!
14//! * [`TransportContext`] / [`TransportMessage`] — a datagram plus the 4-tuple and protocol
15//!   it arrived on or should be sent on. Every layer in the stack passes these around
16//!   instead of touching sockets.
17//! * [`marshal`] — [`Marshal`](marshal::Marshal), [`Unmarshal`](marshal::Unmarshal) and
18//!   [`MarshalSize`](marshal::MarshalSize), the wire-format traits shared by STUN, RTP,
19//!   RTCP, SDP, DTLS and SCTP.
20//! * [`error`] — the crate-wide [`Error`](error::Error) enum and `Result` alias, re-exported
21//!   by the higher-level crates so callers import from one place.
22//! * [`replay_detector`] — replay protection shared by DTLS and SRTP. (Cryptography
23//!   itself lives in the separate `rtc-crypto` crate, behind `RTCCryptoProvider`.)
24//! * [`tcp_framing`] — RFC 4571 length-prefixed framing, for ICE-TCP candidates.
25//! * [`ifaces`] — local interface enumeration used during ICE candidate gathering.
26//!
27//! # Feature flags
28//!
29//! `crypto`, `ifaces`, `marshal` and `replay` are all enabled by default; each gates the
30//! correspondingly named module so that dependents can compile only what they use.
31//!
32//! # Example
33//!
34//! Every protocol codec in the stack implements the same three traits, so encoding and decoding
35//! look the same whichever layer you are at:
36//!
37//! ```
38//! use bytes::Bytes;
39//! use rtc_shared::marshal::{Marshal, MarshalSize, Unmarshal};
40//!
41//! # fn round_trip<T: Marshal + Unmarshal + PartialEq + std::fmt::Debug>(value: T)
42//! # -> Result<(), Box<dyn std::error::Error>> {
43//! // Size the buffer, encode into it, then decode the result back.
44//! let n = value.marshal_size();
45//! let encoded = value.marshal()?;
46//! assert_eq!(encoded.len(), n);
47//!
48//! let mut buf = Bytes::from(encoded.to_vec());
49//! assert_eq!(T::unmarshal(&mut buf)?, value);
50//! # Ok(())
51//! # }
52//! ```
53//!
54//! Most applications do not depend on this crate directly — the [`rtc`](https://docs.rs/rtc)
55//! crate re-exports what it needs as `rtc::shared`.
56
57#[cfg(target_family = "windows")]
58#[macro_use]
59extern crate bitflags;
60
61#[cfg(feature = "ifaces")]
62/// Local network interface enumeration, used to gather ICE host candidates.
63pub mod ifaces;
64
65#[cfg(feature = "marshal")]
66/// The wire-format traits every protocol codec in the stack implements.
67pub mod marshal;
68
69#[cfg(feature = "replay")]
70/// Replay protection for sequence-numbered packets, as DTLS and SRTP require.
71pub mod replay_detector;
72
73/// The crate-wide error type shared by every protocol in the stack.
74pub mod error;
75/// `serde` helpers for types that have no natural serialized form, such as [`std::time::Instant`].
76pub mod serde;
77pub mod tcp_framing;
78/// Conversions between monotonic, Unix and NTP time.
79pub mod time;
80pub(crate) mod transport;
81/// Small shared helpers: packet demultiplexing predicates and random-string generation.
82pub mod util;
83
84pub use transport::{
85    EcnCodepoint, FiveTuple, FourTuple, TaggedBytesMut, TransportContext, TransportMessage,
86    TransportProtocol,
87};
rtc_shared/lib.rs

rtc_shared/
lib.rs
