dvb_si/descriptors/
multilingual_component.rs

1//! Multilingual Component Descriptor — ETSI EN 300 468 §6.2.23 (tag 0x5E).
2//!
3//! Table 77 (PDF p. 94). Carried in the EIT / PMT. A leading `component_tag`
4//! byte ties the descriptor to a component, followed by a loop of (ISO 639-2
5//! language code, text) pairs, each text length-prefixed by an 8-bit field.
6
7use crate::error::{Error, Result};
8use crate::traits::Descriptor;
9use dvb_common::{Parse, Serialize};
10
11/// Descriptor tag for multilingual_component_descriptor.
12pub const TAG: u8 = 0x5E;
13const HEADER_LEN: usize = 2;
14const COMPONENT_TAG_LEN: usize = 1;
15const LANG_LEN: usize = 3;
16const TEXT_LEN_FIELD: usize = 1;
17
18/// One localised component description.
19#[derive(Debug, Clone, PartialEq, Eq)]
20#[cfg_attr(feature = "serde", derive(serde::Serialize, serde::Deserialize))]
21pub struct ComponentTextEntry<'a> {
22    /// ISO 639-2 language code.
23    pub language_code: [u8; 3],
24    /// Raw DVB-encoded text bytes.
25    #[cfg_attr(feature = "serde", serde(borrow))]
26    pub text: &'a [u8],
27}
28
29/// Multilingual Component Descriptor (tag 0x5E).
30#[derive(Debug, Clone, PartialEq, Eq)]
31#[cfg_attr(feature = "serde", derive(serde::Serialize, serde::Deserialize))]
32#[cfg_attr(feature = "serde", serde(bound(deserialize = "'de: 'a")))]
33pub struct MultilingualComponentDescriptor<'a> {
34    /// component_tag linking this descriptor to a stream_identifier_descriptor.
35    pub component_tag: u8,
36    /// Localised descriptions in wire order.
37    #[cfg_attr(feature = "serde", serde(borrow))]
38    pub entries: Vec<ComponentTextEntry<'a>>,
39}
40
41impl<'a> Parse<'a> for MultilingualComponentDescriptor<'a> {
42    type Error = crate::error::Error;
43    fn parse(bytes: &'a [u8]) -> Result<Self> {
44        if bytes.len() < HEADER_LEN {
45            return Err(Error::BufferTooShort {
46                need: HEADER_LEN,
47                have: bytes.len(),
48                what: "MultilingualComponentDescriptor header",
49            });
50        }
51        if bytes[0] != TAG {
52            return Err(Error::InvalidDescriptor {
53                tag: bytes[0],
54                reason: "unexpected tag for multilingual_component_descriptor",
55            });
56        }
57        let length = bytes[1] as usize;
58        let end = HEADER_LEN + length;
59        if bytes.len() < end {
60            return Err(Error::BufferTooShort {
61                need: end,
62                have: bytes.len(),
63                what: "MultilingualComponentDescriptor body",
64            });
65        }
66        if length < COMPONENT_TAG_LEN {
67            return Err(Error::InvalidDescriptor {
68                tag: TAG,
69                reason: "multilingual_component_descriptor body missing component_tag",
70            });
71        }
72        let component_tag = bytes[HEADER_LEN];
73        let mut entries = Vec::new();
74        let mut pos = HEADER_LEN + COMPONENT_TAG_LEN;
75        while pos < end {
76            if pos + LANG_LEN + TEXT_LEN_FIELD > end {
77                return Err(Error::InvalidDescriptor {
78                    tag: TAG,
79                    reason: "entry header runs past descriptor end",
80                });
81            }
82            let language_code = [bytes[pos], bytes[pos + 1], bytes[pos + 2]];
83            let text_len = bytes[pos + LANG_LEN] as usize;
84            let text_start = pos + LANG_LEN + TEXT_LEN_FIELD;
85            let text_end = text_start + text_len;
86            if text_end > end {
87                return Err(Error::InvalidDescriptor {
88                    tag: TAG,
89                    reason: "text_length runs past descriptor end",
90                });
91            }
92            entries.push(ComponentTextEntry {
93                language_code,
94                text: &bytes[text_start..text_end],
95            });
96            pos = text_end;
97        }
98        Ok(Self {
99            component_tag,
100            entries,
101        })
102    }
103}
104
105impl Serialize for MultilingualComponentDescriptor<'_> {
106    type Error = crate::error::Error;
107    fn serialized_len(&self) -> usize {
108        HEADER_LEN
109            + COMPONENT_TAG_LEN
110            + self
111                .entries
112                .iter()
113                .map(|e| LANG_LEN + TEXT_LEN_FIELD + e.text.len())
114                .sum::<usize>()
115    }
116
117    fn serialize_into(&self, buf: &mut [u8]) -> Result<usize> {
118        for e in &self.entries {
119            if e.text.len() > u8::MAX as usize {
120                return Err(Error::InvalidDescriptor {
121                    tag: TAG,
122                    reason: "text exceeds 255 bytes (text_length is 8-bit)",
123                });
124            }
125        }
126        let len = self.serialized_len();
127        let body = len - HEADER_LEN;
128        if body > u8::MAX as usize {
129            return Err(Error::InvalidDescriptor {
130                tag: TAG,
131                reason: "multilingual_component_descriptor body exceeds 255 bytes",
132            });
133        }
134        if buf.len() < len {
135            return Err(Error::OutputBufferTooSmall {
136                need: len,
137                have: buf.len(),
138            });
139        }
140        buf[0] = TAG;
141        buf[1] = body as u8;
142        buf[HEADER_LEN] = self.component_tag;
143        let mut pos = HEADER_LEN + COMPONENT_TAG_LEN;
144        for e in &self.entries {
145            buf[pos..pos + LANG_LEN].copy_from_slice(&e.language_code);
146            buf[pos + LANG_LEN] = e.text.len() as u8;
147            let text_start = pos + LANG_LEN + TEXT_LEN_FIELD;
148            buf[text_start..text_start + e.text.len()].copy_from_slice(e.text);
149            pos = text_start + e.text.len();
150        }
151        Ok(len)
152    }
153}
154
155impl<'a> Descriptor<'a> for MultilingualComponentDescriptor<'a> {
156    const TAG: u8 = TAG;
157    fn descriptor_length(&self) -> u8 {
158        (self.serialized_len() - HEADER_LEN) as u8
159    }
160}
161
162#[cfg(test)]
163mod tests {
164    use super::*;
165
166    fn build(component_tag: u8, entries: &[([u8; 3], &[u8])]) -> Vec<u8> {
167        let body: usize = COMPONENT_TAG_LEN
168            + entries
169                .iter()
170                .map(|(_, t)| LANG_LEN + 1 + t.len())
171                .sum::<usize>();
172        let mut v = Vec::with_capacity(HEADER_LEN + body);
173        v.push(TAG);
174        v.push(body as u8);
175        v.push(component_tag);
176        for (lang, text) in entries {
177            v.extend_from_slice(lang);
178            v.push(text.len() as u8);
179            v.extend_from_slice(text);
180        }
181        v
182    }
183
184    #[test]
185    fn parse_extracts_component_tag_and_entries() {
186        let bytes = build(0x12, &[(*b"eng", b"Video")]);
187        let d = MultilingualComponentDescriptor::parse(&bytes).unwrap();
188        assert_eq!(d.component_tag, 0x12);
189        assert_eq!(d.entries.len(), 1);
190        assert_eq!(&d.entries[0].language_code, b"eng");
191        assert_eq!(d.entries[0].text, b"Video");
192    }
193
194    #[test]
195    fn parse_multiple_entries() {
196        let bytes = build(0x03, &[(*b"eng", b"Audio"), (*b"fra", b"Son")]);
197        let d = MultilingualComponentDescriptor::parse(&bytes).unwrap();
198        assert_eq!(d.component_tag, 0x03);
199        assert_eq!(d.entries.len(), 2);
200        assert_eq!(d.entries[1].text, b"Son");
201    }
202
203    #[test]
204    fn parse_component_tag_only_valid() {
205        // Body = just the component_tag, no language entries.
206        let bytes = [TAG, 1, 0x09];
207        let d = MultilingualComponentDescriptor::parse(&bytes).unwrap();
208        assert_eq!(d.component_tag, 0x09);
209        assert_eq!(d.entries.len(), 0);
210    }
211
212    #[test]
213    fn parse_rejects_wrong_tag() {
214        let err = MultilingualComponentDescriptor::parse(&[0x5D, 1, 0x00]).unwrap_err();
215        assert!(matches!(err, Error::InvalidDescriptor { tag: 0x5D, .. }));
216    }
217
218    #[test]
219    fn parse_rejects_short_buffer() {
220        let err = MultilingualComponentDescriptor::parse(&[TAG]).unwrap_err();
221        assert!(matches!(err, Error::BufferTooShort { .. }));
222    }
223
224    #[test]
225    fn parse_rejects_missing_component_tag() {
226        // length=0: no component_tag.
227        let err = MultilingualComponentDescriptor::parse(&[TAG, 0]).unwrap_err();
228        assert!(matches!(err, Error::InvalidDescriptor { .. }));
229    }
230
231    #[test]
232    fn parse_rejects_text_length_overrun() {
233        // component_tag + lang + text_len=100 but no text bytes.
234        let bytes = [TAG, 5, 0x01, b'e', b'n', b'g', 100];
235        let err = MultilingualComponentDescriptor::parse(&bytes).unwrap_err();
236        assert!(matches!(err, Error::InvalidDescriptor { .. }));
237    }
238
239    #[test]
240    fn serialize_round_trip() {
241        let bytes = build(0x07, &[(*b"eng", b"Subtitle"), (*b"deu", b"Untertitel")]);
242        let parsed = MultilingualComponentDescriptor::parse(&bytes).unwrap();
243        let mut buf = vec![0u8; parsed.serialized_len()];
244        parsed.serialize_into(&mut buf).unwrap();
245        assert_eq!(buf, bytes);
246        let re = MultilingualComponentDescriptor::parse(&buf).unwrap();
247        assert_eq!(parsed, re);
248    }
249
250    #[test]
251    fn serialize_rejects_too_small_buffer() {
252        let d = MultilingualComponentDescriptor {
253            component_tag: 0x01,
254            entries: vec![],
255        };
256        let mut tiny = [0u8; 2];
257        let err = d.serialize_into(&mut tiny).unwrap_err();
258        assert!(matches!(err, Error::OutputBufferTooSmall { .. }));
259    }
260
261    #[test]
262    fn serialize_rejects_over_range_text() {
263        let text = vec![0u8; 256];
264        let d = MultilingualComponentDescriptor {
265            component_tag: 0x01,
266            entries: vec![ComponentTextEntry {
267                language_code: *b"eng",
268                text: &text,
269            }],
270        };
271        let mut buf = vec![0u8; d.serialized_len()];
272        let err = d.serialize_into(&mut buf).unwrap_err();
273        assert!(matches!(err, Error::InvalidDescriptor { tag: TAG, .. }));
274    }
275
276    #[cfg(feature = "serde")]
277    #[test]
278    fn serde_serialize_is_stable() {
279        // Borrowed `&[u8]` cannot be deserialized from a JSON array by
280        // serde_json; matching the borrowed-bytes descriptors in this crate we
281        // exercise the serialize path and assert it is deterministic.
282        let d = MultilingualComponentDescriptor {
283            component_tag: 0x12,
284            entries: vec![ComponentTextEntry {
285                language_code: *b"eng",
286                text: b"Video",
287            }],
288        };
289        let json = serde_json::to_string(&d).unwrap();
290        assert_eq!(json, serde_json::to_string(&d.clone()).unwrap());
291    }
292}
dvb_si/descriptors/multilingual_component.rs

dvb_si/descriptors/
multilingual_component.rs
