dvb_si/tables/
cit.rs

1//! Content Identifier Table — ETSI TS 102 323 v1.4.1 §12.2.
2//!
3//! The CIT maps content reference identifiers (CRIDs) to events for a given
4//! service. Carried on PID 0x0012 (shared with the EIT) with table_id 0x77.
5//! Structure: fixed header + prepend-string block + typed CRID entry loop + CRC-32.
6//!
7//! The CRID entry loop is unfolded into [`CridEntry`] instances (Table 119,
8//! §12.2). The prepend-string block is a flat byte array of null-terminated
9//! fragments addressed by index; it is kept raw (`&[u8]`) since each entry is
10//! just a single byte — there is no per-entry sub-structure to unfold.
11
12use crate::error::{Error, Result};
13use crate::text::DvbText;
14use dvb_common::{Parse, Serialize};
15
16/// `table_id` for Content Identifier Table.
17pub const TABLE_ID: u8 = 0x77;
18
19/// PID on which CIT sections are carried.
20///
21/// Note: PID 0x0012 is shared with the EIT family; demultiplexers must filter
22/// by table_id in addition to PID to isolate CIT sections.
23pub const PID: u16 = 0x0012;
24
25const HEADER_LEN: usize = 3;
26const EXTENSION_LEN: usize = 10;
27const CRC_LEN: usize = 4;
28const MIN_SECTION_LEN: usize = HEADER_LEN + EXTENSION_LEN + CRC_LEN;
29
30const CRID_REF_LEN: usize = 2;
31const CRID_ENTRY_FIXED_LEN: usize = CRID_REF_LEN + 1 + 1;
32
33/// A single CRID entry in the CIT loop (Table 119, §12.2).
34///
35/// Wire layout: `crid_ref(16) | prepend_string_index(8) | unique_string_length(8)
36/// | unique_string_byte[8]×unique_string_length`.
37#[derive(Debug, Clone, PartialEq, Eq)]
38#[cfg_attr(feature = "serde", derive(serde::Serialize))]
39pub struct CridEntry<'a> {
40    /// `crid_ref` — 16-bit reference into the CRID resolution system.
41    pub crid_ref: u16,
42    /// `prepend_string_index` — index into the prepend-string block.
43    /// `0xFF` means no prepend string (the unique string is the full CRID).
44    pub prepend_string_index: u8,
45    /// `unique_string` — the unique portion of the CRID, decoded as DVB text.
46    pub unique_string: DvbText<'a>,
47}
48
49/// Content Identifier Table (ETSI TS 102 323 v1.4.1 §12.2, Table 119).
50///
51/// The `crid_entries` loop is unfolded into typed [`CridEntry`] instances.
52/// The `prepend_strings` block is kept as a raw byte slice (flat array of
53/// null-terminated fragments with no per-entry sub-structure to type).
54#[derive(Debug, Clone, PartialEq, Eq)]
55#[cfg_attr(feature = "serde", derive(serde::Serialize))]
56#[cfg_attr(feature = "yoke", derive(yoke::Yokeable))]
57pub struct CitSection<'a> {
58    /// `private_indicator` bit from byte 1.
59    pub private_indicator: bool,
60    /// `service_id` — identifies the container this section belongs to
61    /// (table_id_extension, bytes 3-4).
62    pub service_id: u16,
63    /// 5-bit `version_number`.
64    pub version_number: u8,
65    /// `current_next_indicator` bit.
66    pub current_next_indicator: bool,
67    /// Section counter within the sub-table.
68    pub section_number: u8,
69    /// Final section number in the sub-table.
70    pub last_section_number: u8,
71    /// `transport_stream_id` of the carrying TS.
72    pub transport_stream_id: u16,
73    /// `original_network_id` of the originating network.
74    pub original_network_id: u16,
75    /// Prepend-string block (null-terminated fragments addressed by index),
76    /// decoded as DVB text.
77    pub prepend_strings: DvbText<'a>,
78    /// CRID entry loop — unfolded per Table 119.
79    pub crid_entries: Vec<CridEntry<'a>>,
80}
81
82impl<'a> CitSection<'a> {
83    /// Resolve a prepend string by its `prepend_string_index`.
84    ///
85    /// Returns `None` if `index` is out of range. The block is a sequence of
86    /// null-terminated fragments; index 0 is the first fragment, index 1 the
87    /// second, etc. The returned slice includes everything up to (but not
88    /// including) the terminating NUL byte; an empty slice means the index
89    /// points to an empty or immediately-terminated fragment.
90    pub fn prepend_string(&self, index: u8) -> Option<&[u8]> {
91        let raw: &[u8] = &self.prepend_strings;
92        let mut remaining: &[u8] = raw;
93        let mut current: u8 = 0;
94        while !remaining.is_empty() {
95            let nul_pos = remaining
96                .iter()
97                .position(|&b| b == 0)
98                .unwrap_or(remaining.len());
99            let fragment = &remaining[..nul_pos];
100            if current == index {
101                return Some(fragment);
102            }
103            current += 1;
104            remaining = if nul_pos < remaining.len() {
105                &remaining[nul_pos + 1..]
106            } else {
107                &[]
108            };
109        }
110        None
111    }
112}
113
114fn crid_entry_serialized_len(e: &CridEntry) -> usize {
115    CRID_ENTRY_FIXED_LEN + e.unique_string.len()
116}
117
118impl<'a> Parse<'a> for CitSection<'a> {
119    type Error = crate::error::Error;
120
121    fn parse(bytes: &'a [u8]) -> Result<Self> {
122        if bytes.len() < MIN_SECTION_LEN {
123            return Err(Error::BufferTooShort {
124                need: MIN_SECTION_LEN,
125                have: bytes.len(),
126                what: "CitSection",
127            });
128        }
129        if bytes[0] != TABLE_ID {
130            return Err(Error::UnexpectedTableId {
131                table_id: bytes[0],
132                what: "CitSection",
133                expected: &[TABLE_ID],
134            });
135        }
136
137        let section_length = (((bytes[1] & 0x0F) as usize) << 8) | bytes[2] as usize;
138        let total =
139            super::check_section_length(bytes.len(), HEADER_LEN, section_length, MIN_SECTION_LEN)?;
140
141        let private_indicator = (bytes[1] & 0x40) != 0;
142        let service_id = u16::from_be_bytes([bytes[3], bytes[4]]);
143        let version_number = (bytes[5] >> 1) & 0x1F;
144        let current_next_indicator = (bytes[5] & 0x01) != 0;
145        let section_number = bytes[6];
146        let last_section_number = bytes[7];
147        let transport_stream_id = u16::from_be_bytes([bytes[8], bytes[9]]);
148        let original_network_id = u16::from_be_bytes([bytes[10], bytes[11]]);
149        let prepend_strings_length = bytes[12];
150
151        let ps_start = HEADER_LEN + EXTENSION_LEN;
152        let ps_end = ps_start + prepend_strings_length as usize;
153        let payload_end = total - CRC_LEN;
154        if ps_end > payload_end {
155            return Err(Error::SectionLengthOverflow {
156                declared: prepend_strings_length as usize,
157                available: payload_end.saturating_sub(ps_start),
158            });
159        }
160        let prepend_strings = DvbText::new(&bytes[ps_start..ps_end]);
161
162        let mut pos = ps_end;
163        let mut crid_entries = Vec::new();
164        while pos < payload_end {
165            if pos + CRID_ENTRY_FIXED_LEN > payload_end {
166                return Err(Error::BufferTooShort {
167                    need: pos + CRID_ENTRY_FIXED_LEN,
168                    have: payload_end,
169                    what: "CitSection crid_entry",
170                });
171            }
172            let crid_ref = u16::from_be_bytes([bytes[pos], bytes[pos + 1]]);
173            let prepend_string_index = bytes[pos + 2];
174            let unique_string_length = bytes[pos + 3] as usize;
175            pos += CRID_ENTRY_FIXED_LEN;
176            if pos + unique_string_length > payload_end {
177                return Err(Error::BufferTooShort {
178                    need: pos + unique_string_length,
179                    have: payload_end,
180                    what: "CitSection unique_string",
181                });
182            }
183            let unique_string = DvbText::new(&bytes[pos..pos + unique_string_length]);
184            pos += unique_string_length;
185            crid_entries.push(CridEntry {
186                crid_ref,
187                prepend_string_index,
188                unique_string,
189            });
190        }
191
192        Ok(CitSection {
193            private_indicator,
194            service_id,
195            version_number,
196            current_next_indicator,
197            section_number,
198            last_section_number,
199            transport_stream_id,
200            original_network_id,
201            prepend_strings,
202            crid_entries,
203        })
204    }
205}
206
207impl Serialize for CitSection<'_> {
208    type Error = crate::error::Error;
209
210    fn serialized_len(&self) -> usize {
211        HEADER_LEN
212            + EXTENSION_LEN
213            + self.prepend_strings.len()
214            + self
215                .crid_entries
216                .iter()
217                .map(crid_entry_serialized_len)
218                .sum::<usize>()
219            + CRC_LEN
220    }
221
222    fn serialize_into(&self, buf: &mut [u8]) -> Result<usize> {
223        let len = self.serialized_len();
224        if buf.len() < len {
225            return Err(Error::OutputBufferTooSmall {
226                need: len,
227                have: buf.len(),
228            });
229        }
230        if self.prepend_strings.len() > u8::MAX as usize {
231            return Err(Error::SectionLengthOverflow {
232                declared: self.prepend_strings.len(),
233                available: u8::MAX as usize,
234            });
235        }
236
237        let section_length = (len - HEADER_LEN) as u16;
238        if section_length > 0x0FFF {
239            return Err(Error::SectionLengthOverflow {
240                declared: section_length as usize,
241                available: 0x0FFF,
242            });
243        }
244        buf[0] = TABLE_ID;
245        buf[1] = super::SECTION_B1_SSI
246            | (u8::from(self.private_indicator) << 6)
247            | super::SECTION_B1_RESERVED_HI
248            | ((section_length >> 8) as u8 & 0x0F);
249        buf[2] = (section_length & 0xFF) as u8;
250
251        buf[3..5].copy_from_slice(&self.service_id.to_be_bytes());
252        buf[5] = 0xC0 | ((self.version_number & 0x1F) << 1) | u8::from(self.current_next_indicator);
253        buf[6] = self.section_number;
254        buf[7] = self.last_section_number;
255        buf[8..10].copy_from_slice(&self.transport_stream_id.to_be_bytes());
256        buf[10..12].copy_from_slice(&self.original_network_id.to_be_bytes());
257        buf[12] = self.prepend_strings.len() as u8;
258
259        let ps_start = HEADER_LEN + EXTENSION_LEN;
260        let ps_end = ps_start + self.prepend_strings.len();
261        buf[ps_start..ps_end].copy_from_slice(&self.prepend_strings);
262
263        let mut pos = ps_end;
264        for entry in &self.crid_entries {
265            buf[pos..pos + 2].copy_from_slice(&entry.crid_ref.to_be_bytes());
266            buf[pos + 2] = entry.prepend_string_index;
267            buf[pos + 3] = entry.unique_string.len() as u8;
268            pos += CRID_ENTRY_FIXED_LEN;
269            buf[pos..pos + entry.unique_string.len()].copy_from_slice(&entry.unique_string);
270            pos += entry.unique_string.len();
271        }
272
273        let crc = dvb_common::crc32_mpeg2::compute(&buf[..pos]);
274        buf[pos..pos + CRC_LEN].copy_from_slice(&crc.to_be_bytes());
275        Ok(len)
276    }
277}
278impl<'a> crate::traits::TableDef<'a> for CitSection<'a> {
279    const TABLE_ID_RANGES: &'static [(u8, u8)] = &[(TABLE_ID, TABLE_ID)];
280    const NAME: &'static str = "CONTENT_IDENTIFIER";
281}
282
283#[cfg(test)]
284mod tests {
285    use super::*;
286
287    #[test]
288    fn parse_happy_path_no_crid_entries() {
289        let prepend = DvbText::new(b"CRID://example.com\x00");
290        let cit = CitSection {
291            private_indicator: false,
292            service_id: 0x1234,
293            version_number: 3,
294            current_next_indicator: true,
295            section_number: 0,
296            last_section_number: 0,
297            transport_stream_id: 0x0064,
298            original_network_id: 0x0002,
299            prepend_strings: prepend,
300            crid_entries: Vec::new(),
301        };
302        let mut buf = vec![0u8; cit.serialized_len()];
303        cit.serialize_into(&mut buf).unwrap();
304        let parsed = CitSection::parse(&buf).unwrap();
305        assert_eq!(parsed.service_id, 0x1234);
306        assert_eq!(parsed.version_number, 3);
307        assert!(parsed.current_next_indicator);
308        assert_eq!(parsed.prepend_strings, prepend);
309        assert!(parsed.crid_entries.is_empty());
310    }
311
312    #[test]
313    fn parse_happy_path_with_crid_entries() {
314        let prepend = DvbText::new(b"crid://bbc.co.uk/\x00");
315        let entries = vec![
316            CridEntry {
317                crid_ref: 0x0001,
318                prepend_string_index: 0x00,
319                unique_string: DvbText::new(b"ep1"),
320            },
321            CridEntry {
322                crid_ref: 0x0002,
323                prepend_string_index: 0xFF,
324                unique_string: DvbText::new(b"crid://bbc.co.uk/EV-1"),
325            },
326        ];
327        let cit = CitSection {
328            private_indicator: false,
329            service_id: 0xABCD,
330            version_number: 7,
331            current_next_indicator: true,
332            section_number: 1,
333            last_section_number: 3,
334            transport_stream_id: 0x01F4,
335            original_network_id: 0x0028,
336            prepend_strings: prepend,
337            crid_entries: entries,
338        };
339        let mut buf = vec![0u8; cit.serialized_len()];
340        cit.serialize_into(&mut buf).unwrap();
341        let parsed = CitSection::parse(&buf).unwrap();
342        assert_eq!(parsed.service_id, 0xABCD);
343        assert_eq!(parsed.crid_entries.len(), 2);
344        assert_eq!(parsed.crid_entries[0].crid_ref, 0x0001);
345        assert_eq!(parsed.crid_entries[0].prepend_string_index, 0x00);
346        assert_eq!(parsed.crid_entries[0].unique_string, DvbText::new(b"ep1"));
347        assert_eq!(parsed.crid_entries[1].crid_ref, 0x0002);
348        assert_eq!(parsed.crid_entries[1].prepend_string_index, 0xFF);
349        assert_eq!(
350            parsed.crid_entries[1].unique_string,
351            DvbText::new(b"crid://bbc.co.uk/EV-1")
352        );
353    }
354
355    #[test]
356    fn byte_exact_round_trip() {
357        let prepend = DvbText::new(b"crid://example.com/\x00");
358        let entries = vec![CridEntry {
359            crid_ref: 0x0042,
360            prepend_string_index: 0x00,
361            unique_string: DvbText::new(b"episode42"),
362        }];
363        let original = CitSection {
364            private_indicator: true,
365            service_id: 0x4321,
366            version_number: 15,
367            current_next_indicator: false,
368            section_number: 2,
369            last_section_number: 4,
370            transport_stream_id: 0x03E8,
371            original_network_id: 0x0050,
372            prepend_strings: prepend,
373            crid_entries: entries,
374        };
375        let mut buf = vec![0u8; original.serialized_len()];
376        original.serialize_into(&mut buf).unwrap();
377        let parsed = CitSection::parse(&buf).unwrap();
378        let mut buf2 = vec![0u8; parsed.serialized_len()];
379        parsed.serialize_into(&mut buf2).unwrap();
380        assert_eq!(buf, buf2, "byte-exact re-serialize");
381        assert_eq!(parsed.crid_entries.len(), 1);
382        assert_eq!(parsed.crid_entries[0].crid_ref, 0x0042);
383        assert_eq!(
384            parsed.crid_entries[0].unique_string,
385            DvbText::new(b"episode42")
386        );
387    }
388
389    #[test]
390    fn parse_rejects_wrong_table_id() {
391        let cit = CitSection {
392            private_indicator: false,
393            service_id: 0x0001,
394            version_number: 0,
395            current_next_indicator: true,
396            section_number: 0,
397            last_section_number: 0,
398            transport_stream_id: 0x0001,
399            original_network_id: 0x0001,
400            prepend_strings: DvbText::new(&[]),
401            crid_entries: Vec::new(),
402        };
403        let mut buf = vec![0u8; cit.serialized_len()];
404        cit.serialize_into(&mut buf).unwrap();
405        buf[0] = 0x40;
406        assert!(matches!(
407            CitSection::parse(&buf).unwrap_err(),
408            Error::UnexpectedTableId { table_id: 0x40, .. }
409        ));
410    }
411
412    #[test]
413    fn parse_rejects_buffer_too_short() {
414        assert!(matches!(
415            CitSection::parse(&[TABLE_ID, 0x00]).unwrap_err(),
416            Error::BufferTooShort { .. }
417        ));
418    }
419
420    #[test]
421    fn parse_rejects_truncated_crid_entry() {
422        let prepend = DvbText::new(&[]);
423        let cit = CitSection {
424            private_indicator: false,
425            service_id: 0x0001,
426            version_number: 0,
427            current_next_indicator: true,
428            section_number: 0,
429            last_section_number: 0,
430            transport_stream_id: 0x0001,
431            original_network_id: 0x0001,
432            prepend_strings: prepend,
433            crid_entries: Vec::new(),
434        };
435        let mut buf = vec![0u8; cit.serialized_len()];
436        cit.serialize_into(&mut buf).unwrap();
437        let mut truncated = buf.clone();
438        truncated.truncate(buf.len() - 2);
439        let sl = (truncated.len() - HEADER_LEN) as u16;
440        truncated[1] = (truncated[1] & 0xF0) | ((sl >> 8) as u8 & 0x0F);
441        truncated[2] = (sl & 0xFF) as u8;
442        assert!(CitSection::parse(&truncated).is_err());
443    }
444
445    #[test]
446    fn serialize_rejects_output_buffer_too_small() {
447        let cit = CitSection {
448            private_indicator: false,
449            service_id: 0x0001,
450            version_number: 0,
451            current_next_indicator: true,
452            section_number: 0,
453            last_section_number: 0,
454            transport_stream_id: 0x0001,
455            original_network_id: 0x0001,
456            prepend_strings: DvbText::new(&[]),
457            crid_entries: Vec::new(),
458        };
459        let mut buf = vec![0u8; 2];
460        assert!(matches!(
461            cit.serialize_into(&mut buf).unwrap_err(),
462            Error::OutputBufferTooSmall { .. }
463        ));
464    }
465
466    #[test]
467    fn parse_rejects_zero_section_length() {
468        let mut buf = vec![0u8; 64];
469        buf[0] = TABLE_ID;
470        buf[1] = 0xF0;
471        buf[2] = 0x00;
472        for b in &mut buf[3..] {
473            *b = 0xFF;
474        }
475        assert!(matches!(
476            CitSection::parse(&buf).unwrap_err(),
477            Error::SectionLengthOverflow { .. }
478        ));
479    }
480
481    #[test]
482    fn parse_handwritten_cit_no_entries() {
483        let mut bytes: Vec<u8> = vec![
484            0x77, 0xF0, 0x0E, 0x12, 0x34, 0xC7, 0x00, 0x00, 0x00, 0x64, 0x00, 0x02, 0x00,
485        ];
486        let crc = dvb_common::crc32_mpeg2::compute(&bytes);
487        bytes.extend_from_slice(&crc.to_be_bytes());
488        let cit = CitSection::parse(&bytes).unwrap();
489        assert_eq!(cit.service_id, 0x1234);
490        assert_eq!(cit.transport_stream_id, 0x0064);
491        assert!(cit.crid_entries.is_empty());
492    }
493
494    #[test]
495    fn prepend_string_resolver() {
496        let cit = CitSection {
497            private_indicator: false,
498            service_id: 0x0001,
499            version_number: 0,
500            current_next_indicator: true,
501            section_number: 0,
502            last_section_number: 0,
503            transport_stream_id: 0x0001,
504            original_network_id: 0x0001,
505            prepend_strings: DvbText::new(b"crid://example.com/\x00crid://other.com/\x00"),
506            crid_entries: Vec::new(),
507        };
508        assert_eq!(cit.prepend_string(0), Some(&b"crid://example.com/"[..]));
509        assert_eq!(cit.prepend_string(1), Some(&b"crid://other.com/"[..]));
510        assert_eq!(cit.prepend_string(2), None);
511    }
512}
dvb_si/tables/cit.rs

dvb_si/tables/
cit.rs
