dvb_si/tables/
container.rs

1//! Container table section — ETSI TS 102 323 v1.4.1 §7.3.1.4 (table_id 0x75).
2//!
3//! The container section carries TV-Anytime container data (an MHP object
4//! carousel file fragment, after optional compression). Syntax per "Table 20 —
5//! Container section" (`dvb-si/docs/ts_102_323_tva.md`, §7.3.1.4, PDF p. 36):
6//!
7//! ```text
8//! container_section() {
9//!   table_id                 8   (0x75)
10//!   section_syntax_indicator 1
11//!   private_indicator        1
12//!   reserved                 2
13//!   private_section_length  12
14//!   container_id            16   (table_id_extension)
15//!   reserved                 2
16//!   version_number           5
17//!   current_next_indicator   1
18//!   section_number           8
19//!   last_section_number      8
20//!   container_data()        N*8
21//!   CRC_32                  32
22//! }
23//! ```
24//!
25//! This is a private section (the spec's byte-1 bit 6 is `private_indicator`),
26//! so it is handled with the same idiom as [`crate::tables::cit`]. The
27//! `container_data` payload is kept as a borrowed raw slice; its internal
28//! structure (compression_wrapper / object-carousel fragments) is out of scope.
29//!
30//! Carriage is signalled via descriptors (no well-known PID), following the
31//! [`crate::tables::dsmcc`] precedent of `PID = 0x0000`.
32
33use crate::error::{Error, Result};
34use dvb_common::{Parse, Serialize};
35
36/// table_id for the Container table.
37pub const TABLE_ID: u8 = 0x75;
38
39/// The Container table has no well-known PID — its carriage is signalled via
40/// descriptors. `0x0000` is a placeholder following the DSM-CC precedent.
41pub const PID: u16 = 0x0000;
42
43/// Bytes 0-2: table_id (1) + flags + private_section_length (2).
44const HEADER_LEN: usize = 3;
45
46/// Bytes 3-7: container_id(2) + reserved/version/cni(1) + section_number(1)
47/// + last_section_number(1).
48const EXTENSION_HEADER_LEN: usize = 5;
49
50/// Bytes occupied by the trailing CRC-32 field.
51const CRC_LEN: usize = 4;
52
53/// Minimum total encoded length: header + extension + CRC.
54const MIN_LEN: usize = HEADER_LEN + EXTENSION_HEADER_LEN + CRC_LEN;
55
56/// Container table section parser (ETSI TS 102 323 v1.4.1 §7.3.1.4).
57///
58/// `container_data` borrows the payload region (everything between the extension
59/// header and the CRC-32 trailer) without parsing its internal structure.
60#[derive(Debug, Clone, PartialEq, Eq)]
61#[cfg_attr(feature = "serde", derive(serde::Serialize))]
62#[cfg_attr(feature = "yoke", derive(yoke::Yokeable))]
63pub struct ContainerSection<'a> {
64    /// `private_indicator` bit from byte 1 (this is a private section).
65    pub private_indicator: bool,
66    /// 16-bit `container_id` (carried in the table_id_extension slot, bytes 3-4).
67    pub container_id: u16,
68    /// 5-bit `version_number`.
69    pub version_number: u8,
70    /// `current_next_indicator` bit.
71    pub current_next_indicator: bool,
72    /// section_number in the sub-table sequence.
73    pub section_number: u8,
74    /// last_section_number in the sub-table sequence.
75    pub last_section_number: u8,
76    /// Raw `container_data` bytes (everything between the extension header and
77    /// the CRC-32 trailer). Internal structure is not parsed.
78    pub container_data: &'a [u8],
79}
80
81impl<'a> Parse<'a> for ContainerSection<'a> {
82    type Error = crate::error::Error;
83
84    fn parse(bytes: &'a [u8]) -> Result<Self> {
85        if bytes.len() < MIN_LEN {
86            return Err(Error::BufferTooShort {
87                need: MIN_LEN,
88                have: bytes.len(),
89                what: "ContainerSection",
90            });
91        }
92
93        if bytes[0] != TABLE_ID {
94            return Err(Error::UnexpectedTableId {
95                table_id: bytes[0],
96                what: "ContainerSection",
97                expected: &[TABLE_ID],
98            });
99        }
100
101        // byte 1 = section_syntax_indicator(1) | private_indicator(1)
102        //          | reserved(2) | private_section_length[11:8](4)
103        // byte 2 = private_section_length[7:0]
104        let section_length = (((bytes[1] & 0x0F) as usize) << 8) | bytes[2] as usize;
105        let total = super::check_section_length(bytes.len(), HEADER_LEN, section_length, MIN_LEN)?;
106
107        let private_indicator = (bytes[1] & 0x40) != 0;
108
109        // Extension header (bytes 3..8).
110        let container_id = u16::from_be_bytes([bytes[3], bytes[4]]);
111        // byte 5: reserved(2) | version_number(5) | current_next_indicator(1)
112        let version_number = (bytes[5] >> 1) & 0x1F;
113        let current_next_indicator = (bytes[5] & 0x01) != 0;
114        let section_number = bytes[6];
115        let last_section_number = bytes[7];
116
117        // container_data: from end of extension header up to (not including) CRC.
118        let data_start = HEADER_LEN + EXTENSION_HEADER_LEN;
119        let data_end = total - CRC_LEN;
120        let container_data = &bytes[data_start..data_end];
121
122        Ok(ContainerSection {
123            private_indicator,
124            container_id,
125            version_number,
126            current_next_indicator,
127            section_number,
128            last_section_number,
129            container_data,
130        })
131    }
132}
133
134impl Serialize for ContainerSection<'_> {
135    type Error = crate::error::Error;
136
137    fn serialized_len(&self) -> usize {
138        HEADER_LEN + EXTENSION_HEADER_LEN + self.container_data.len() + CRC_LEN
139    }
140
141    fn serialize_into(&self, buf: &mut [u8]) -> Result<usize> {
142        let len = self.serialized_len();
143        if buf.len() < len {
144            return Err(Error::OutputBufferTooSmall {
145                need: len,
146                have: buf.len(),
147            });
148        }
149
150        let section_length = (len - HEADER_LEN) as u16;
151        if section_length > 0x0FFF {
152            return Err(Error::SectionLengthOverflow {
153                declared: section_length as usize,
154                available: 0x0FFF,
155            });
156        }
157
158        // Byte 0: table_id.
159        buf[0] = TABLE_ID;
160        // Byte 1: section_syntax_indicator(1)=1 | private_indicator(1)
161        //         | reserved(2)=11 | private_section_length[11:8](4).
162        buf[1] = 0x80
163            | (u8::from(self.private_indicator) << 6)
164            | 0x30
165            | ((section_length >> 8) as u8 & 0x0F);
166        // Byte 2: private_section_length[7:0].
167        buf[2] = (section_length & 0xFF) as u8;
168
169        // Extension header.
170        buf[3..5].copy_from_slice(&self.container_id.to_be_bytes());
171        buf[5] = 0xC0 // reserved(2) = 11
172            | ((self.version_number & 0x1F) << 1)
173            | u8::from(self.current_next_indicator);
174        buf[6] = self.section_number;
175        buf[7] = self.last_section_number;
176
177        // container_data.
178        let data_start = HEADER_LEN + EXTENSION_HEADER_LEN;
179        let data_end = data_start + self.container_data.len();
180        buf[data_start..data_end].copy_from_slice(self.container_data);
181
182        // CRC-32 over everything up to (but not including) the CRC slot.
183        let crc = dvb_common::crc32_mpeg2::compute(&buf[..data_end]);
184        buf[data_end..len].copy_from_slice(&crc.to_be_bytes());
185
186        Ok(len)
187    }
188}
189impl<'a> crate::traits::TableDef<'a> for ContainerSection<'a> {
190    const TABLE_ID_RANGES: &'static [(u8, u8)] = &[(TABLE_ID, TABLE_ID)];
191    const NAME: &'static str = "CONTAINER";
192}
193
194#[cfg(test)]
195mod tests {
196    use super::*;
197
198    /// Build a syntactically valid Container section. `container_data` is pasted
199    /// verbatim; the CRC slot is filled by the serializer.
200    fn build_container(
201        container_id: u16,
202        version: u8,
203        current_next: bool,
204        section_number: u8,
205        last_section_number: u8,
206        container_data: &[u8],
207    ) -> Vec<u8> {
208        let c = ContainerSection {
209            private_indicator: true,
210            container_id,
211            version_number: version,
212            current_next_indicator: current_next,
213            section_number,
214            last_section_number,
215            container_data,
216        };
217        let mut buf = vec![0u8; c.serialized_len()];
218        c.serialize_into(&mut buf).unwrap();
219        buf
220    }
221
222    #[test]
223    fn parse_happy_path() {
224        let data = [0x00u8, 0xDE, 0xAD, 0xBE, 0xEF];
225        let bytes = build_container(0x1234, 7, true, 1, 3, &data);
226        let c = ContainerSection::parse(&bytes).unwrap();
227        assert!(c.private_indicator);
228        assert_eq!(c.container_id, 0x1234);
229        assert_eq!(c.version_number, 7);
230        assert!(c.current_next_indicator);
231        assert_eq!(c.section_number, 1);
232        assert_eq!(c.last_section_number, 3);
233        assert_eq!(c.container_data, &data[..]);
234    }
235
236    #[test]
237    fn parse_empty_container_data() {
238        let bytes = build_container(0x0000, 0, false, 0, 0, &[]);
239        let c = ContainerSection::parse(&bytes).unwrap();
240        assert_eq!(c.container_id, 0x0000);
241        assert_eq!(c.version_number, 0);
242        assert!(!c.current_next_indicator);
243        assert!(c.container_data.is_empty());
244    }
245
246    #[test]
247    fn parse_rejects_wrong_tag() {
248        let mut bytes = build_container(0x0001, 0, true, 0, 0, &[]);
249        bytes[0] = 0x70; // not 0x75
250        assert!(matches!(
251            ContainerSection::parse(&bytes).unwrap_err(),
252            Error::UnexpectedTableId { table_id: 0x70, .. }
253        ));
254    }
255
256    #[test]
257    fn parse_rejects_short_buffer() {
258        assert!(matches!(
259            ContainerSection::parse(&[0x75, 0x80]).unwrap_err(),
260            Error::BufferTooShort { .. }
261        ));
262    }
263
264    #[test]
265    fn parse_rejects_section_length_overflow() {
266        let mut bytes = build_container(0x0001, 0, true, 0, 0, &[]);
267        let fake_sl: u16 = (bytes.len() as u16) + 100 - HEADER_LEN as u16;
268        bytes[1] = (bytes[1] & 0xF0) | ((fake_sl >> 8) as u8 & 0x0F);
269        bytes[2] = (fake_sl & 0xFF) as u8;
270        assert!(matches!(
271            ContainerSection::parse(&bytes).unwrap_err(),
272            Error::SectionLengthOverflow { .. }
273        ));
274    }
275
276    #[test]
277    fn serialize_round_trip() {
278        let data = [0x01u8, 0x02, 0x03];
279        let original = ContainerSection {
280            private_indicator: false,
281            container_id: 0xABCD,
282            version_number: 15,
283            current_next_indicator: false,
284            section_number: 2,
285            last_section_number: 4,
286            container_data: &data,
287        };
288        let mut buf = vec![0u8; original.serialized_len()];
289        original.serialize_into(&mut buf).unwrap();
290        assert_eq!(ContainerSection::parse(&buf).unwrap(), original);
291    }
292
293    #[test]
294    fn serialize_rejects_output_buffer_too_small() {
295        let c = ContainerSection {
296            private_indicator: false,
297            container_id: 0x0001,
298            version_number: 0,
299            current_next_indicator: true,
300            section_number: 0,
301            last_section_number: 0,
302            container_data: &[],
303        };
304        let mut buf = vec![0u8; 2];
305        assert!(matches!(
306            c.serialize_into(&mut buf).unwrap_err(),
307            Error::OutputBufferTooSmall { .. }
308        ));
309    }
310
311    #[test]
312    fn table_trait_constants() {
313        assert_eq!(TABLE_ID, 0x75);
314        assert_eq!(PID, 0x0000);
315    }
316
317    #[test]
318    fn parse_rejects_zero_section_length() {
319        let mut buf = vec![0u8; 64];
320        buf[0] = TABLE_ID;
321        buf[1] = 0xF0;
322        buf[2] = 0x00;
323        for b in &mut buf[3..] {
324            *b = 0xFF;
325        }
326        assert!(matches!(
327            ContainerSection::parse(&buf).unwrap_err(),
328            Error::SectionLengthOverflow { .. }
329        ));
330    }
331
332    #[cfg(feature = "serde")]
333    #[test]
334    fn serde_json_round_trip() {
335        // `container_data` is a borrowed `&[u8]` (the rnt/cit idiom), so a
336        // deserialize round-trip is not possible — serde encodes a byte slice
337        // as a JSON sequence which cannot be re-borrowed. Mirror the borrowed
338        // tables by asserting serialization yields valid, field-bearing JSON.
339        let data = [0xCAu8, 0xFE];
340        let bytes = build_container(0xBEEF, 9, true, 0, 0, &data);
341        let c = ContainerSection::parse(&bytes).unwrap();
342        let v: serde_json::Value = serde_json::to_value(&c).unwrap();
343        assert_eq!(v["container_id"], 0xBEEF);
344        assert_eq!(v["version_number"], 9);
345        assert_eq!(v["current_next_indicator"], true);
346        assert_eq!(v["container_data"], serde_json::json!([0xCA, 0xFE]));
347    }
348}
dvb_si/tables/container.rs

dvb_si/tables/
container.rs
