rtcp_packet/lib.rs
1//! RTCP control packets — RFC 3550 §6, spec-complete (not just a happy-path
2//! subset).
3//!
4//! Typed, symmetric [`Parse`](broadcast_common::Parse)/[`Serialize`](broadcast_common::Serialize)
5//! for every RTCP packet type described in the curated spec transcription at
6//! `rtcp-packet/docs/rtcp.md` (fetched directly from
7//! [RFC 3550](https://www.rfc-editor.org/rfc/rfc3550.txt)) — cite that file,
8//! not this doc comment, as the field-semantics oracle.
9//!
10//! - [`SenderReport`] — SR (§6.4.1, PT 200).
11//! - [`ReceiverReport`] — RR (§6.4.2, PT 201).
12//! - [`ReportBlock`] — the 24-byte reception report block shared by SR/RR.
13//! - [`SourceDescription`] / [`SdesChunk`] / [`SdesItem`] / [`SdesItemType`]
14//! — SDES (§6.5, PT 202).
15//! - [`Bye`] — BYE (§6.6, PT 203).
16//! - [`App`] — APP (§6.7, PT 204).
17//! - [`RtcpPacket`] / [`RtcpPacketType`] — the packet-type dispatch enum.
18//! - [`CompoundPacket`] — §6.1's compound packet (a sequence of RTCP packets
19//! that must begin with SR or RR), with byte-exact round-trip.
20//!
21//! Two decode-completeness gaps are documented (not silently glossed over)
22//! in `docs/rtcp.md`: SR/RR profile-specific extensions and the SDES PRIV
23//! item's internal `prefix`/`value` sub-structure are not separately typed.
24//!
25//! RTCP carries **no media** — this is a standalone wire codec for the RTP
26//! control channel (a companion to the `rtp-packet` crate), not a hub
27//! `Package`/`Unpackage` spoke.
28//!
29//! Depends only on `broadcast-common`. `#![no_std]` (+ `alloc`) when the
30//! `std` feature is disabled.
31//!
32//! # Examples
33//!
34//! Build a Sender Report with two reception report blocks and round-trip it:
35//!
36//! ```
37//! use broadcast_common::{Parse, Serialize};
38//! use rtcp_packet::{ReportBlock, SenderReport};
39//!
40//! let sr = SenderReport {
41//! ssrc: 0x1122_3344,
42//! ntp_msw: 0xE0E1_E2E3,
43//! ntp_lsw: 0x1020_3040,
44//! rtp_timestamp: 0x0009_0000,
45//! packet_count: 4321,
46//! octet_count: 999_999,
47//! report_blocks: vec![ReportBlock {
48//! ssrc: 0xAAAA_AAAA,
49//! fraction_lost: 12,
50//! cumulative_lost: -3,
51//! ext_highest_seq: 0x0001_2345,
52//! jitter: 500,
53//! lsr: 0xAABB_CCDD,
54//! dlsr: 0x0000_1000,
55//! }],
56//! };
57//! let mut bytes = vec![0u8; sr.serialized_len()];
58//! sr.serialize_into(&mut bytes).unwrap();
59//! assert_eq!(SenderReport::parse(&bytes).unwrap(), sr);
60//! ```
61#![cfg_attr(not(feature = "std"), no_std)]
62#![cfg_attr(docsrs, feature(doc_cfg))]
63#![warn(missing_docs)]
64// Runnable examples, embedded so they render on docs.rs and stay in sync with
65// the actual `examples/*.rs` files (shown, not compiled).
66#![doc = "\n## Runnable examples\n"]
67#![doc = "Run with `cargo run -p rtcp-packet --example <name>`.\n"]
68#![doc = "\n### `build_sender_report`\n\n```rust,ignore"]
69#![doc = include_str!("../examples/build_sender_report.rs")]
70#![doc = "```\n\n### `parse_compound_packet`\n\n```rust,ignore"]
71#![doc = include_str!("../examples/parse_compound_packet.rs")]
72#![doc = "```"]
73
74extern crate alloc;
75
76mod error;
77mod packet;
78
79pub use error::{Error, Result};
80pub use packet::{
81 APP_NAME_LEN, App, Bye, CommonHeader, CompoundPacket, PT_APP, PT_BYE, PT_RECEIVER_REPORT,
82 PT_SENDER_REPORT, PT_SOURCE_DESCRIPTION, REPORT_BLOCK_LEN, ReceiverReport, ReportBlock,
83 RtcpPacket, RtcpPacketType, SDES_CNAME, SDES_EMAIL, SDES_LOC, SDES_NAME, SDES_NOTE, SDES_PHONE,
84 SDES_PRIV, SDES_TOOL, SdesChunk, SdesItem, SdesItemType, SenderReport, SourceDescription,
85};