dvb_si/tables/
nit.rs

1//! Network Information Table — ETSI EN 300 468 §5.2.1.
2//!
3//! NIT describes the transport streams belonging to a DVB network, with
4//! network-wide descriptors and per-transport-stream descriptors. The
5//! table is split into two variants by table_id: `0x40` for the actual
6//! TS the receiver is tuned to, `0x41` for other TSes in the same network.
7
8use crate::error::{Error, Result};
9use crate::traits::Table;
10use dvb_common::{Parse, Serialize};
11
12/// table_id value for NIT actual (current TS).
13pub const TABLE_ID_ACTUAL: u8 = 0x40;
14/// table_id value for NIT other (other TSes in the network).
15pub const TABLE_ID_OTHER: u8 = 0x41;
16/// Well-known PID on which NIT is carried.
17pub const PID: u16 = 0x0010;
18
19const MIN_HEADER_LEN: usize = 3;
20const EXTENSION_HEADER_LEN: usize = 5;
21/// Bytes after the extension header: reserved_future_use (4 bits) + network_descriptors_length (12 bits) = 2 bytes.
22/// (Previously incorrectly defined as 4 — the parser assumed `network_id`
23/// was duplicated *after* the extension header; spec says it lives IN
24/// the extension header at bytes 3-4 as `table_id_extension`.)
25const POST_EXTENSION_LEN: usize = 2;
26const CRC_LEN: usize = 4;
27/// Per-transport-stream header: ts_id (2) + original_network_id (2) + reserved_future_use (4 bits) + transport_descriptors_length (12 bits).
28const TS_HEADER_LEN: usize = 6;
29
30/// NIT kind — distinguishes `0x40` (actual) from `0x41` (other).
31#[derive(Debug, Clone, Copy, PartialEq, Eq)]
32#[cfg_attr(feature = "serde", derive(serde::Serialize, serde::Deserialize))]
33pub enum NitKind {
34    /// NIT for the transport stream the receiver is tuned to.
35    Actual,
36    /// NIT describing other transport streams in the same network.
37    Other,
38}
39
40/// One transport-stream entry inside the NIT transport_stream_loop.
41#[derive(Debug, Clone, PartialEq, Eq)]
42#[cfg_attr(feature = "serde", derive(serde::Serialize, serde::Deserialize))]
43pub struct NitTransportStream<'a> {
44    /// transport_stream_id of the described TS.
45    pub transport_stream_id: u16,
46    /// original_network_id of the described TS.
47    pub original_network_id: u16,
48    /// Raw descriptor bytes for this transport stream.
49    #[cfg_attr(feature = "serde", serde(borrow))]
50    pub descriptors: &'a [u8],
51}
52
53/// Network Information Table.
54#[derive(Debug, Clone, PartialEq, Eq)]
55#[cfg_attr(feature = "serde", derive(serde::Serialize, serde::Deserialize))]
56pub struct Nit<'a> {
57    /// Variant discriminator (table_id 0x40 vs 0x41).
58    pub kind: NitKind,
59    /// Network identifier.
60    pub network_id: u16,
61    /// 5-bit version_number.
62    pub version_number: u8,
63    /// current_next_indicator bit.
64    pub current_next_indicator: bool,
65    /// section_number in the sub-table sequence.
66    pub section_number: u8,
67    /// last_section_number in the sub-table sequence.
68    pub last_section_number: u8,
69    /// Raw network-wide descriptor bytes.
70    #[cfg_attr(feature = "serde", serde(borrow))]
71    pub network_descriptors: &'a [u8],
72    /// Transport-stream loop entries in wire order.
73    #[cfg_attr(feature = "serde", serde(borrow))]
74    pub transport_streams: Vec<NitTransportStream<'a>>,
75}
76
77impl<'a> Parse<'a> for Nit<'a> {
78    type Error = crate::error::Error;
79    fn parse(bytes: &'a [u8]) -> Result<Self> {
80        let min_len = MIN_HEADER_LEN + EXTENSION_HEADER_LEN + POST_EXTENSION_LEN + CRC_LEN;
81        if bytes.len() < min_len {
82            return Err(Error::BufferTooShort {
83                need: min_len,
84                have: bytes.len(),
85                what: "Nit",
86            });
87        }
88        let kind = match bytes[0] {
89            TABLE_ID_ACTUAL => NitKind::Actual,
90            TABLE_ID_OTHER => NitKind::Other,
91            other => {
92                return Err(Error::UnexpectedTableId {
93                    table_id: other,
94                    what: "Nit",
95                    expected: &[TABLE_ID_ACTUAL, TABLE_ID_OTHER],
96                });
97            }
98        };
99
100        let section_length = ((bytes[1] & 0x0F) as u16) << 8 | bytes[2] as u16;
101        let total = MIN_HEADER_LEN + section_length as usize;
102        if bytes.len() < total {
103            return Err(Error::SectionLengthOverflow {
104                declared: section_length as usize,
105                available: bytes.len() - MIN_HEADER_LEN,
106            });
107        }
108
109        // Extension header bytes [3..8] per ETSI EN 300 468 §5.2.1:
110        //   bytes[3..5] = table_id_extension = network_id (16 bits)
111        //   bytes[5]    = reserved(2) | version_number(5) | current_next_indicator(1)
112        //   bytes[6]    = section_number
113        //   bytes[7]    = last_section_number
114        let network_id = u16::from_be_bytes([bytes[3], bytes[4]]);
115        let version_number = (bytes[5] >> 1) & 0x1F;
116        let current_next_indicator = (bytes[5] & 0x01) != 0;
117        let section_number = bytes[6];
118        let last_section_number = bytes[7];
119
120        // bytes[8..10] = reserved(4) | network_descriptors_length(12)
121        let network_descriptors_length = (((bytes[8] & 0x0F) as usize) << 8) | bytes[9] as usize;
122
123        let network_desc_start = MIN_HEADER_LEN + EXTENSION_HEADER_LEN + POST_EXTENSION_LEN;
124        let network_desc_end = network_desc_start + network_descriptors_length;
125
126        // Verify network descriptors don't overflow
127        if network_desc_end > total - CRC_LEN {
128            return Err(Error::SectionLengthOverflow {
129                declared: network_descriptors_length,
130                available: (total - CRC_LEN) - network_desc_start,
131            });
132        }
133
134        let network_descriptors = &bytes[network_desc_start..network_desc_end];
135
136        // Parse transport stream loop starting after network descriptors
137        let ts_loop_start = network_desc_end;
138        let ts_loop_end = total - CRC_LEN;
139
140        // First 2 bytes of the loop are: reserved_future_use (4 bits) + transport_stream_loop_length (12 bits)
141        if ts_loop_end - ts_loop_start < 2 {
142            return Err(Error::BufferTooShort {
143                need: ts_loop_end - ts_loop_start + 2,
144                have: ts_loop_end - ts_loop_start,
145                what: "Nit transport_stream_loop",
146            });
147        }
148
149        let transport_stream_loop_length =
150            (((bytes[ts_loop_start] & 0x0F) as usize) << 8) | bytes[ts_loop_start + 1] as usize;
151
152        let mut pos = ts_loop_start + 2;
153        let loop_end = ts_loop_start + 2 + transport_stream_loop_length;
154
155        if loop_end > ts_loop_end {
156            return Err(Error::SectionLengthOverflow {
157                declared: transport_stream_loop_length,
158                available: ts_loop_end - (ts_loop_start + 2),
159            });
160        }
161
162        let mut transport_streams = Vec::new();
163
164        while pos < loop_end {
165            if pos + TS_HEADER_LEN > loop_end {
166                return Err(Error::BufferTooShort {
167                    need: pos + TS_HEADER_LEN,
168                    have: loop_end,
169                    what: "Nit transport_stream_entry",
170                });
171            }
172
173            let transport_stream_id = u16::from_be_bytes([bytes[pos], bytes[pos + 1]]);
174            let original_network_id = u16::from_be_bytes([bytes[pos + 2], bytes[pos + 3]]);
175
176            // transport_descriptors_length is 12 bits: high 4 bits reserved, low 12 bits length
177            let transport_descriptors_length =
178                (((bytes[pos + 4] & 0x0F) as usize) << 8) | bytes[pos + 5] as usize;
179
180            let desc_start = pos + TS_HEADER_LEN;
181            let desc_end = desc_start + transport_descriptors_length;
182
183            if desc_end > loop_end {
184                return Err(Error::SectionLengthOverflow {
185                    declared: transport_descriptors_length,
186                    available: loop_end - desc_start,
187                });
188            }
189
190            transport_streams.push(NitTransportStream {
191                transport_stream_id,
192                original_network_id,
193                descriptors: &bytes[desc_start..desc_end],
194            });
195
196            pos = desc_end;
197        }
198
199        Ok(Nit {
200            kind,
201            network_id,
202            version_number,
203            current_next_indicator,
204            section_number,
205            last_section_number,
206            network_descriptors,
207            transport_streams,
208        })
209    }
210}
211
212impl Serialize for Nit<'_> {
213    type Error = crate::error::Error;
214    fn serialized_len(&self) -> usize {
215        let net_desc_len = self.network_descriptors.len();
216        let ts_bytes: usize = self
217            .transport_streams
218            .iter()
219            .map(|ts| TS_HEADER_LEN + ts.descriptors.len())
220            .sum();
221        MIN_HEADER_LEN
222            + EXTENSION_HEADER_LEN
223            + POST_EXTENSION_LEN
224            + net_desc_len
225            + 2 // transport_stream_loop_length header
226            + ts_bytes
227            + CRC_LEN
228    }
229
230    fn serialize_into(&self, buf: &mut [u8]) -> Result<usize> {
231        let len = self.serialized_len();
232        if buf.len() < len {
233            return Err(Error::OutputBufferTooSmall {
234                need: len,
235                have: buf.len(),
236            });
237        }
238
239        let section_length: u16 = (len - MIN_HEADER_LEN) as u16;
240        buf[0] = match self.kind {
241            NitKind::Actual => TABLE_ID_ACTUAL,
242            NitKind::Other => TABLE_ID_OTHER,
243        };
244        buf[1] = 0xB0 | ((section_length >> 8) as u8 & 0x0F);
245        buf[2] = (section_length & 0xFF) as u8;
246
247        // Extension header per ETSI EN 300 468 §5.2.1:
248        //   bytes[3..5] = network_id (table_id_extension)
249        //   bytes[5]    = reserved | version | current_next
250        //   bytes[6..8] = section_number + last_section_number
251        buf[3..5].copy_from_slice(&self.network_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
256        // bytes[8..10] = reserved(4) | network_descriptors_length(12)
257        let net_dll = self.network_descriptors.len() as u16;
258        buf[8] = 0xF0 | ((net_dll >> 8) as u8 & 0x0F);
259        buf[9] = (net_dll & 0xFF) as u8;
260
261        let net_desc_start = MIN_HEADER_LEN + EXTENSION_HEADER_LEN + POST_EXTENSION_LEN;
262        buf[net_desc_start..net_desc_start + self.network_descriptors.len()]
263            .copy_from_slice(self.network_descriptors);
264
265        let ts_loop_start = net_desc_start + self.network_descriptors.len();
266        let ts_loop_length: u16 = (len - ts_loop_start - 2 - CRC_LEN) as u16;
267        buf[ts_loop_start] = 0xF0 | ((ts_loop_length >> 8) as u8 & 0x0F);
268        buf[ts_loop_start + 1] = (ts_loop_length & 0xFF) as u8;
269
270        let mut pos = ts_loop_start + 2;
271        for ts in &self.transport_streams {
272            buf[pos..pos + 2].copy_from_slice(&ts.transport_stream_id.to_be_bytes());
273            buf[pos + 2..pos + 4].copy_from_slice(&ts.original_network_id.to_be_bytes());
274            let ts_dll = ts.descriptors.len() as u16;
275            buf[pos + 4] = 0xF0 | ((ts_dll >> 8) as u8 & 0x0F);
276            buf[pos + 5] = (ts_dll & 0xFF) as u8;
277            let desc_start = pos + TS_HEADER_LEN;
278            buf[desc_start..desc_start + ts.descriptors.len()].copy_from_slice(ts.descriptors);
279            pos = desc_start + ts.descriptors.len();
280        }
281
282        let crc_pos = len - CRC_LEN;
283        let crc = dvb_common::crc32_mpeg2::compute(&buf[..crc_pos]);
284        buf[crc_pos..len].copy_from_slice(&crc.to_be_bytes());
285        Ok(len)
286    }
287}
288
289impl<'a> Table<'a> for Nit<'a> {
290    const TABLE_ID: u8 = TABLE_ID_ACTUAL;
291    const PID: u16 = PID;
292}
293
294#[cfg(test)]
295mod tests {
296    use super::*;
297
298    type TestTs = (u16, u16, Vec<u8>);
299
300    fn build_nit(
301        kind: NitKind,
302        network_id: u16,
303        network_desc: &[u8],
304        transport_streams: &[TestTs],
305    ) -> Vec<u8> {
306        let ts_bytes: usize = transport_streams
307            .iter()
308            .map(|(_, _, d)| TS_HEADER_LEN + d.len())
309            .sum();
310        let loop_length = ts_bytes as u16;
311        let section_length: u16 = (EXTENSION_HEADER_LEN
312            + POST_EXTENSION_LEN
313            + network_desc.len()
314            + 2
315            + ts_bytes
316            + CRC_LEN) as u16;
317        let mut v = Vec::new();
318        v.push(match kind {
319            NitKind::Actual => TABLE_ID_ACTUAL,
320            NitKind::Other => TABLE_ID_OTHER,
321        });
322        v.push(0xB0 | ((section_length >> 8) as u8 & 0x0F));
323        v.push((section_length & 0xFF) as u8);
324        // Extension header (spec layout): bytes[3..5] = network_id
325        v.extend_from_slice(&network_id.to_be_bytes());
326        v.push(0xC0 | 0x01); // version=0, current_next=1
327        v.push(0); // section_number
328        v.push(0); // last_section_number
329                   // bytes[8..10] = reserved(4) | network_descriptors_length(12)
330        let net_dll = network_desc.len() as u16;
331        v.push(0xF0 | ((net_dll >> 8) as u8 & 0x0F));
332        v.push((net_dll & 0xFF) as u8);
333        v.extend_from_slice(network_desc);
334        // reserved(4) | transport_stream_loop_length(12)
335        v.push(0xF0 | ((loop_length >> 8) as u8 & 0x0F));
336        v.push((loop_length & 0xFF) as u8);
337        for (tsid, onid, desc) in transport_streams {
338            v.extend_from_slice(&tsid.to_be_bytes());
339            v.extend_from_slice(&onid.to_be_bytes());
340            let ts_dll = desc.len() as u16;
341            // reserved(4) | transport_descriptors_length(12)
342            v.push(0xF0 | ((ts_dll >> 8) as u8 & 0x0F));
343            v.push((ts_dll & 0xFF) as u8);
344            v.extend_from_slice(desc);
345        }
346        v.extend_from_slice(&[0, 0, 0, 0]); // CRC placeholder
347        v
348    }
349
350    #[test]
351    fn parse_actual_and_other_distinguished_by_table_id() {
352        let a = build_nit(NitKind::Actual, 0x0001, &[], &[]);
353        let o = build_nit(NitKind::Other, 0x0001, &[], &[]);
354        assert!(matches!(Nit::parse(&a).unwrap().kind, NitKind::Actual));
355        assert!(matches!(Nit::parse(&o).unwrap().kind, NitKind::Other));
356    }
357
358    #[test]
359    fn parse_network_id_extracted() {
360        let bytes = build_nit(NitKind::Actual, 0x0020, &[], &[]);
361        let nit = Nit::parse(&bytes).unwrap();
362        assert_eq!(nit.network_id, 0x0020);
363    }
364
365    #[test]
366    fn parse_network_wide_descriptors() {
367        let net_desc: [u8; 4] = [0x40, 0x02, 0x4E, 0x65]; // network_name descriptor
368        let bytes = build_nit(NitKind::Actual, 0x0001, &net_desc, &[]);
369        let nit = Nit::parse(&bytes).unwrap();
370        assert_eq!(nit.network_descriptors, &net_desc[..]);
371    }
372
373    #[test]
374    fn parse_transport_stream_entries() {
375        let bytes = build_nit(
376            NitKind::Actual,
377            0x0001,
378            &[],
379            &[
380                (
381                    0x1234,
382                    0x0020,
383                    vec![0x43, 0x07, 0x0B, 0xB8, 0x00, 0x02, 0x00, 0x05],
384                ),
385                (0x5678, 0x0020, vec![]),
386            ],
387        );
388        let nit = Nit::parse(&bytes).unwrap();
389        assert_eq!(nit.transport_streams.len(), 2);
390        assert_eq!(nit.transport_streams[0].transport_stream_id, 0x1234);
391        assert_eq!(nit.transport_streams[0].original_network_id, 0x0020);
392        assert_eq!(
393            nit.transport_streams[0].descriptors,
394            &[0x43, 0x07, 0x0B, 0xB8, 0x00, 0x02, 0x00, 0x05][..]
395        );
396        assert_eq!(nit.transport_streams[1].transport_stream_id, 0x5678);
397        assert_eq!(nit.transport_streams[1].descriptors.len(), 0);
398    }
399
400    #[test]
401    fn parse_version_and_current_next() {
402        let bytes = build_nit(NitKind::Actual, 0x0001, &[], &[]);
403        let nit = Nit::parse(&bytes).unwrap();
404        assert_eq!(nit.version_number, 0);
405        assert!(nit.current_next_indicator);
406    }
407
408    #[test]
409    fn serialize_round_trip() {
410        let net_desc: [u8; 4] = [0x40, 0x02, 0x4E, 0x65];
411        let ts_desc: [u8; 3] = [0x43, 0x01, 0x01];
412        let nit = Nit {
413            kind: NitKind::Actual,
414            network_id: 0x0020,
415            version_number: 3,
416            current_next_indicator: true,
417            section_number: 0,
418            last_section_number: 0,
419            network_descriptors: &net_desc,
420            transport_streams: vec![
421                NitTransportStream {
422                    transport_stream_id: 0x1234,
423                    original_network_id: 0x0020,
424                    descriptors: &ts_desc,
425                },
426                NitTransportStream {
427                    transport_stream_id: 0x5678,
428                    original_network_id: 0x0020,
429                    descriptors: &[],
430                },
431            ],
432        };
433        let mut buf = vec![0u8; nit.serialized_len()];
434        nit.serialize_into(&mut buf).unwrap();
435        let re = Nit::parse(&buf).unwrap();
436        assert_eq!(nit, re);
437    }
438
439    #[test]
440    fn zero_transport_streams_is_valid() {
441        let bytes = build_nit(NitKind::Actual, 0x0001, &[], &[]);
442        let nit = Nit::parse(&bytes).unwrap();
443        assert_eq!(nit.transport_streams.len(), 0);
444    }
445
446    #[test]
447    fn parse_rejects_short_buffer() {
448        let err = Nit::parse(&[0x40, 0x00]).unwrap_err();
449        assert!(matches!(err, Error::BufferTooShort { .. }));
450    }
451
452    #[test]
453    fn parse_rejects_wrong_table_id() {
454        let mut bytes = build_nit(NitKind::Actual, 0x0001, &[], &[]);
455        bytes[0] = 0x00;
456        let err = Nit::parse(&bytes).unwrap_err();
457        assert!(matches!(
458            err,
459            Error::UnexpectedTableId { table_id: 0x00, .. }
460        ));
461    }
462
463    #[test]
464    fn serialize_too_small_buffer_returns_error() {
465        let nit = Nit {
466            kind: NitKind::Actual,
467            network_id: 0x0001,
468            version_number: 0,
469            current_next_indicator: true,
470            section_number: 0,
471            last_section_number: 0,
472            network_descriptors: &[],
473            transport_streams: vec![],
474        };
475        let mut buf = vec![0u8; 2];
476        let err = nit.serialize_into(&mut buf).unwrap_err();
477        assert!(matches!(err, Error::OutputBufferTooSmall { .. }));
478    }
479}
dvb_si/tables/nit.rs

dvb_si/tables/
nit.rs
