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

rtc_shared/
lib.rs
