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//! * [`turn_framing`] — splitting a TURN stream into its self-delimiting messages, for TURN
26//!   over TCP.
27//! * [`ifaces`] — local interface enumeration used during ICE candidate gathering.
28//!
29//! # Feature flags
30//!
31//! `crypto`, `ifaces`, `marshal` and `replay` are all enabled by default; each gates the
32//! correspondingly named module so that dependents can compile only what they use.
33//!
34//! # Example
35//!
36//! Every protocol codec in the stack implements the same three traits, so encoding and decoding
37//! look the same whichever layer you are at:
38//!
39//! ```
40//! use bytes::Bytes;
41//! use rtc_shared::marshal::{Marshal, MarshalSize, Unmarshal};
42//!
43//! # fn round_trip<T: Marshal + Unmarshal + PartialEq + std::fmt::Debug>(value: T)
44//! # -> Result<(), Box<dyn std::error::Error>> {
45//! // Size the buffer, encode into it, then decode the result back.
46//! let n = value.marshal_size();
47//! let encoded = value.marshal()?;
48//! assert_eq!(encoded.len(), n);
49//!
50//! let mut buf = Bytes::from(encoded.to_vec());
51//! assert_eq!(T::unmarshal(&mut buf)?, value);
52//! # Ok(())
53//! # }
54//! ```
55//!
56//! Most applications do not depend on this crate directly — the [`rtc`](https://docs.rs/rtc)
57//! crate re-exports what it needs as `rtc::shared`.
58
59#[cfg(target_family = "windows")]
60#[macro_use]
61extern crate bitflags;
62
63#[cfg(feature = "ifaces")]
64/// Local network interface enumeration, used to gather ICE host candidates.
65pub mod ifaces;
66
67#[cfg(feature = "marshal")]
68/// The wire-format traits every protocol codec in the stack implements.
69pub mod marshal;
70
71#[cfg(feature = "replay")]
72/// Replay protection for sequence-numbered packets, as DTLS and SRTP require.
73pub mod replay_detector;
74
75/// The crate-wide error type shared by every protocol in the stack.
76pub mod error;
77/// `serde` helpers for types that have no natural serialized form, such as [`std::time::Instant`].
78pub mod serde;
79pub mod tcp_framing;
80/// Conversions between monotonic, Unix and NTP time.
81pub mod time;
82pub(crate) mod transport;
83/// Splitting a TURN-over-TCP byte stream into STUN and ChannelData messages.
84pub mod turn_framing;
85/// Small shared helpers: packet demultiplexing predicates and random-string generation.
86pub mod util;
87
88pub use transport::{
89    EcnCodepoint, FiveTuple, FourTuple, TaggedBytesMut, TransportContext, TransportMessage,
90    TransportProtocol,
91};
rtc_shared/lib.rs

rtc_shared/
lib.rs
