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::text::{DvbText, LangCode};
9use crate::traits::Descriptor;
10use dvb_common::{Parse, Serialize};
11
12/// Descriptor tag for multilingual_component_descriptor.
13pub const TAG: u8 = 0x5E;
14const HEADER_LEN: usize = 2;
15const COMPONENT_TAG_LEN: usize = 1;
16const LANG_LEN: usize = 3;
17const TEXT_LEN_FIELD: usize = 1;
18
19/// One localised component description.
20#[derive(Debug, Clone, PartialEq, Eq)]
21#[cfg_attr(feature = "serde", derive(serde::Serialize))]
22#[cfg_attr(feature = "yoke", derive(yoke::Yokeable))]
23pub struct ComponentTextEntry<'a> {
24    /// ISO 639-2 language code.
25    pub language_code: LangCode,
26    /// DVB Annex-A encoded component description text.
27    pub text: DvbText<'a>,
28}
29
30/// Multilingual Component Descriptor (tag 0x5E).
31#[derive(Debug, Clone, PartialEq, Eq)]
32#[cfg_attr(feature = "serde", derive(serde::Serialize))]
33#[cfg_attr(feature = "yoke", derive(yoke::Yokeable))]
34pub struct MultilingualComponentDescriptor<'a> {
35    /// component_tag linking this descriptor to a stream_identifier_descriptor.
36    pub component_tag: u8,
37    /// Localised descriptions in wire order.
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 = LangCode([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: DvbText::new(&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.0);
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.raw());
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
162impl<'a> crate::traits::DescriptorDef<'a> for MultilingualComponentDescriptor<'a> {
163    const TAG: u8 = TAG;
164    const NAME: &'static str = "MULTILINGUAL_COMPONENT";
165}
166
167#[cfg(test)]
168mod tests {
169    use super::*;
170
171    fn build(component_tag: u8, entries: &[([u8; 3], &[u8])]) -> Vec<u8> {
172        let body: usize = COMPONENT_TAG_LEN
173            + entries
174                .iter()
175                .map(|(_, t)| LANG_LEN + 1 + t.len())
176                .sum::<usize>();
177        let mut v = Vec::with_capacity(HEADER_LEN + body);
178        v.push(TAG);
179        v.push(body as u8);
180        v.push(component_tag);
181        for (lang, text) in entries {
182            v.extend_from_slice(lang);
183            v.push(text.len() as u8);
184            v.extend_from_slice(text);
185        }
186        v
187    }
188
189    #[test]
190    fn parse_extracts_component_tag_and_entries() {
191        let bytes = build(0x12, &[(*b"eng", b"Video")]);
192        let d = MultilingualComponentDescriptor::parse(&bytes).unwrap();
193        assert_eq!(d.component_tag, 0x12);
194        assert_eq!(d.entries.len(), 1);
195        assert_eq!(d.entries[0].language_code, LangCode(*b"eng"));
196        assert_eq!(d.entries[0].text.raw(), b"Video");
197    }
198
199    #[test]
200    fn parse_multiple_entries() {
201        let bytes = build(0x03, &[(*b"eng", b"Audio"), (*b"fra", b"Son")]);
202        let d = MultilingualComponentDescriptor::parse(&bytes).unwrap();
203        assert_eq!(d.component_tag, 0x03);
204        assert_eq!(d.entries.len(), 2);
205        assert_eq!(d.entries[1].text.raw(), b"Son");
206    }
207
208    #[test]
209    fn parse_component_tag_only_valid() {
210        // Body = just the component_tag, no language entries.
211        let bytes = [TAG, 1, 0x09];
212        let d = MultilingualComponentDescriptor::parse(&bytes).unwrap();
213        assert_eq!(d.component_tag, 0x09);
214        assert_eq!(d.entries.len(), 0);
215    }
216
217    #[test]
218    fn parse_rejects_wrong_tag() {
219        let err = MultilingualComponentDescriptor::parse(&[0x5D, 1, 0x00]).unwrap_err();
220        assert!(matches!(err, Error::InvalidDescriptor { tag: 0x5D, .. }));
221    }
222
223    #[test]
224    fn parse_rejects_short_buffer() {
225        let err = MultilingualComponentDescriptor::parse(&[TAG]).unwrap_err();
226        assert!(matches!(err, Error::BufferTooShort { .. }));
227    }
228
229    #[test]
230    fn parse_rejects_missing_component_tag() {
231        // length=0: no component_tag.
232        let err = MultilingualComponentDescriptor::parse(&[TAG, 0]).unwrap_err();
233        assert!(matches!(err, Error::InvalidDescriptor { .. }));
234    }
235
236    #[test]
237    fn parse_rejects_text_length_overrun() {
238        // component_tag + lang + text_len=100 but no text bytes.
239        let bytes = [TAG, 5, 0x01, b'e', b'n', b'g', 100];
240        let err = MultilingualComponentDescriptor::parse(&bytes).unwrap_err();
241        assert!(matches!(err, Error::InvalidDescriptor { .. }));
242    }
243
244    #[test]
245    fn serialize_round_trip() {
246        let bytes = build(0x07, &[(*b"eng", b"Subtitle"), (*b"deu", b"Untertitel")]);
247        let parsed = MultilingualComponentDescriptor::parse(&bytes).unwrap();
248        let mut buf = vec![0u8; parsed.serialized_len()];
249        parsed.serialize_into(&mut buf).unwrap();
250        assert_eq!(buf, bytes);
251        let re = MultilingualComponentDescriptor::parse(&buf).unwrap();
252        assert_eq!(parsed, re);
253    }
254
255    #[test]
256    fn serialize_rejects_too_small_buffer() {
257        let d = MultilingualComponentDescriptor {
258            component_tag: 0x01,
259            entries: vec![],
260        };
261        let mut tiny = [0u8; 2];
262        let err = d.serialize_into(&mut tiny).unwrap_err();
263        assert!(matches!(err, Error::OutputBufferTooSmall { .. }));
264    }
265
266    #[test]
267    fn serialize_rejects_over_range_text() {
268        let text = vec![0u8; 256];
269        let d = MultilingualComponentDescriptor {
270            component_tag: 0x01,
271            entries: vec![ComponentTextEntry {
272                language_code: LangCode(*b"eng"),
273                text: DvbText::new(&text),
274            }],
275        };
276        let mut buf = vec![0u8; d.serialized_len()];
277        let err = d.serialize_into(&mut buf).unwrap_err();
278        assert!(matches!(err, Error::InvalidDescriptor { tag: TAG, .. }));
279    }
280
281    #[cfg(feature = "serde")]
282    #[test]
283    fn serde_serialize_is_stable() {
284        // Borrowed `&[u8]` cannot be deserialized from a JSON array by
285        // serde_json; matching the borrowed-bytes descriptors in this crate we
286        // exercise the serialize path and assert it is deterministic.
287        let d = MultilingualComponentDescriptor {
288            component_tag: 0x12,
289            entries: vec![ComponentTextEntry {
290                language_code: LangCode(*b"eng"),
291                text: DvbText::new(b"Video"),
292            }],
293        };
294        let json = serde_json::to_string(&d).unwrap();
295        assert_eq!(json, serde_json::to_string(&d.clone()).unwrap());
296    }
297}
dvb_si/descriptors/multilingual_component.rs

dvb_si/descriptors/
multilingual_component.rs
