st377_1/
error.rs

1//! Error type for MXF (SMPTE ST 377-1) parsing/serialization.
2//!
3//! Field-by-field semantics are documented in the curated spec oracle,
4//! `st377-1/docs/st377-1.md`.
5
6/// Result alias for `st377-1` parsing/serialization.
7pub type Result<T> = core::result::Result<T, Error>;
8
9/// An MXF parse / serialize error.
10#[derive(Debug, Clone, Copy, PartialEq, Eq, thiserror::Error)]
11#[non_exhaustive]
12pub enum Error {
13    /// Input (on parse) or output buffer (on serialize) shorter than
14    /// required.
15    #[error("buffer too short: need {need}, have {have} ({what})")]
16    BufferTooShort {
17        /// Bytes required.
18        need: usize,
19        /// Bytes available.
20        have: usize,
21        /// What was being parsed/serialized.
22        what: &'static str,
23    },
24    /// A BER length token used the reserved "unspecified length" value
25    /// (`0x80` with zero following bytes), forbidden in MXF files
26    /// (`docs/st377-1.md` §6.3.4).
27    #[error("BER length used the reserved indefinite-length token (0x80)")]
28    BerIndefiniteLength,
29    /// A BER long-form length used more following bytes than an
30    /// unsigned 64-bit length could ever need, or than MXF's own 9-byte
31    /// cap (1 header + up to 8 length bytes, §6.3.4) allows.
32    #[error("BER long-form length has {bytes} following bytes, exceeding the 8-byte cap")]
33    BerLengthTooLong {
34        /// Following-byte count found (or requested on serialize).
35        bytes: usize,
36    },
37    /// A KLV Key was not the expected 16 bytes ( §6.3.8 — MXF Keys and
38    /// Universal Labels are always exactly 16 bytes; this only fires when
39    /// a caller-supplied buffer is short, since [`crate::klv::KlvItem`]
40    /// itself always reads exactly 16).
41    #[error("KLV key must be 16 bytes, found {found}")]
42    InvalidKeyLength {
43        /// Bytes actually available for the key.
44        found: usize,
45    },
46    /// A Partition Pack's Key byte 14 (Partition Kind) was not one of the
47    /// three defined values (`docs/st377-1.md` §7.1 Table 4).
48    #[error("unknown Partition Kind byte: {byte:#04X}")]
49    UnknownPartitionKind {
50        /// The offending byte 14 value.
51        byte: u8,
52    },
53    /// A Partition Pack's Key byte 15 (Partition Status) was not one of
54    /// the four defined values (`docs/st377-1.md` §7.1 Table 4 / §6.2.3).
55    #[error("unknown Partition Status byte: {byte:#04X}")]
56    UnknownPartitionStatus {
57        /// The offending byte 15 value.
58        byte: u8,
59    },
60    /// A Footer Partition Pack (Table 8) used an Open status byte, which
61    /// §7.4.1's note forbids ("Open Footer Partitions are not permitted").
62    #[error("Footer Partition must not be Open (status byte {byte:#04X})")]
63    OpenFooterPartition {
64        /// The offending status byte.
65        byte: u8,
66    },
67    /// A KLV Key did not match the expected fixed 13-byte Partition Pack /
68    /// Primer Pack / Random Index Pack prefix (`docs/st377-1.md` §7.1
69    /// Table 4 / §9.2 Table 13 / §12.1 Table 29).
70    #[error("key prefix mismatch for {what}")]
71    KeyPrefixMismatch {
72        /// Which fixed-prefix pack was expected.
73        what: &'static str,
74    },
75    /// A required Header Metadata property (Annex A) was absent from a
76    /// typed Set's underlying [`crate::LocalSet`].
77    #[error("required property {tag:#06X} ({name}) missing from {set}")]
78    MissingRequiredProperty {
79        /// The property's local tag.
80        tag: u16,
81        /// The property's spec name.
82        name: &'static str,
83        /// The enclosing Set's name.
84        set: &'static str,
85    },
86    /// A property's value had a length that does not match its fixed-size
87    /// wire type (e.g. a 16-byte UUID field encoded with fewer/more bytes).
88    #[error("property {tag:#06X} ({name}) has invalid length {found}, expected {expected}")]
89    InvalidPropertyLength {
90        /// The property's local tag.
91        tag: u16,
92        /// The property's spec name.
93        name: &'static str,
94        /// Bytes found.
95        found: usize,
96        /// Bytes expected.
97        expected: usize,
98    },
99    /// A Batch/Array's 8-byte header (`count: u32`, `item_len: u32`) did
100    /// not agree with the actual buffer length, or `item_len` did not
101    /// match the expected fixed element size (`docs/st377-1.md` §4.3).
102    #[error("batch header invalid: count={count} item_len={item_len} buffer_len={buffer_len}")]
103    InvalidBatchHeader {
104        /// Declared element count.
105        count: u32,
106        /// Declared per-element length.
107        item_len: u32,
108        /// Actual remaining buffer length after the 8-byte header.
109        buffer_len: usize,
110    },
111    /// A UTF-16 string property contained an invalid UTF-16 code unit
112    /// sequence (unpaired surrogate).
113    #[error("invalid UTF-16 in property {tag:#06X} ({name})")]
114    InvalidUtf16 {
115        /// The property's local tag.
116        tag: u16,
117        /// The property's spec name.
118        name: &'static str,
119    },
120}
st377_1/error.rs

st377_1/
error.rs
