Skip to main content

openbim_ifc_capi/
status.rs

1//! Status codes, the version record, and the panic boundary.
2
3use std::panic::{catch_unwind, AssertUnwindSafe};
4
5use openbim_ifc_binding_core::BindingError;
6
7/// Result of every ABI call. `Ok` is zero; every failure is non-zero.
8///
9/// The values from `Parse` to `FeatureDisabled`, `InvalidModel`, and
10/// `MissingReference` to `AmbiguousValue`, are the binding errors shared
11/// with the JavaScript and Python bindings; the rest describe misuse of the
12/// C boundary itself.
13#[repr(i32)]
14#[derive(Debug, Clone, Copy, PartialEq, Eq)]
15pub enum OpenbimIfcStatus {
16    /// Success.
17    Ok = 0,
18    /// A required pointer was null.
19    NullPointer = 1,
20    /// An argument was malformed (bad UTF-8, a malformed value tape, ...).
21    InvalidArgument = 2,
22    /// The model handle is zero, stale, or already destroyed.
23    InvalidHandle = 3,
24    /// The output buffer is smaller than `*out_required`.
25    BufferTooSmall = 4,
26    /// The STEP input could not be parsed (`parse`).
27    Parse = 10,
28    /// The model could not be serialized (`write`).
29    Write = 11,
30    /// No entity has the given id (`missing-entity`).
31    MissingEntity = 12,
32    /// A value did not follow the encoding (`invalid-value`).
33    InvalidValue = 13,
34    /// An id or index is outside the representable range (`out-of-range`).
35    OutOfRange = 14,
36    /// The file's schema is not bundled, or a domain view does not read it
37    /// (`unsupported-schema`).
38    UnsupportedSchema = 15,
39    /// A file could not be opened or read (`io`).
40    Io = 16,
41    /// No ifcXML XSD profile has that name (`unsupported-profile`).
42    UnsupportedProfile = 17,
43    /// This build leaves out the feature the call needs (`feature-disabled`).
44    FeatureDisabled = 18,
45    /// A domain view refused the file's data as malformed, ambiguous or
46    /// unprovable (`invalid-model`).
47    InvalidModel = 19,
48    /// The requested value does not exist (no schema token, no error, ...).
49    NoValue = 20,
50    /// A domain view followed a reference to an entity the file lacks
51    /// (`missing-reference`).
52    MissingReference = 21,
53    /// A domain view stopped at a cycle or its depth budget
54    /// (`budget-exceeded`).
55    BudgetExceeded = 22,
56    /// A domain view met a construct it does not interpret (`unsupported`).
57    Unsupported = 23,
58    /// A domain query named an entity of a type it does not accept, or a
59    /// property edit a set type the set does not have (`wrong-entity-type`).
60    WrongEntityType = 24,
61    /// A property edit wrote a value its PSD/QTO template or property
62    /// enumeration refuses (`template-violation`).
63    TemplateViolation = 25,
64    /// A property edit removed a property the object does not state
65    /// (`missing-property`).
66    MissingProperty = 26,
67    /// A property edit wrote to a `Pset_`/`Qto_` set before its release's
68    /// catalog was loaded (`catalog-not-loaded`). This library embeds the
69    /// catalog, so it never returns this; the value is reserved so every
70    /// binding code has one.
71    CatalogNotLoaded = 27,
72    /// A by-name attribute access named no attribute of the entity's type
73    /// in the declared release, explicit or (for a read) `INVERSE`
74    /// (`unknown-attribute`).
75    UnknownAttribute = 28,
76    /// A by-name attribute write named a slot the entity's type derives,
77    /// written `*` (`derived-attribute`).
78    DerivedAttribute = 29,
79    /// An authoring batch left a required attribute of the declared
80    /// release unset (`missing-attribute`).
81    MissingAttribute = 30,
82    /// An authoring batch removed an entity that an entity other than a
83    /// relationship still references (`still-referenced`).
84    StillReferenced = 31,
85    /// A plain value written by name does not fit the attribute's declared
86    /// type (`type-mismatch`).
87    TypeMismatch = 32,
88    /// A plain value written by name fits several members of the
89    /// attribute's SELECT; write it exactly instead (`ambiguous-value`).
90    AmbiguousValue = 33,
91    /// A selector or value path does not follow the grammar, or names a
92    /// class or attribute the declared release does not declare
93    /// (`invalid-selector`); `openbim_ifc_v0_1_last_error_span` gives the
94    /// byte range it refuses.
95    InvalidSelector = 34,
96    /// A by-name attribute write named an `INVERSE` attribute, which holds
97    /// no slot (`inverse-attribute`).
98    InverseAttribute = 35,
99    /// EXPRESS rule text declares another schema than the model's, or
100    /// disagrees with the release's tables (`express-mismatch`).
101    ExpressMismatch = 36,
102    /// EXPRESS rule text does not parse, or names something that binds to
103    /// nothing (`invalid-express`).
104    InvalidExpress = 37,
105    /// An undo or redo with nothing to step through: history is off, or
106    /// that stack is empty (`history-empty`).
107    HistoryEmpty = 38,
108    /// An undo or redo after the model changed outside the history
109    /// (`history-stale`); nothing was changed.
110    HistoryStale = 39,
111    /// A Rust panic was contained at the boundary. Report it as a bug.
112    Panic = 255,
113}
114
115impl From<&BindingError> for OpenbimIfcStatus {
116    fn from(error: &BindingError) -> Self {
117        match error {
118            BindingError::Parse(_) => Self::Parse,
119            BindingError::Write(_) => Self::Write,
120            BindingError::MissingEntity(_) => Self::MissingEntity,
121            BindingError::InvalidValue(_) => Self::InvalidValue,
122            BindingError::OutOfRange(_) => Self::OutOfRange,
123            BindingError::UnsupportedSchema(_) => Self::UnsupportedSchema,
124            BindingError::Io(_) => Self::Io,
125            BindingError::UnsupportedProfile(_) => Self::UnsupportedProfile,
126            BindingError::FeatureDisabled(_) => Self::FeatureDisabled,
127            BindingError::InvalidModel(_) => Self::InvalidModel,
128            BindingError::MissingReference(_) => Self::MissingReference,
129            BindingError::BudgetExceeded(_) => Self::BudgetExceeded,
130            BindingError::Unsupported(_) => Self::Unsupported,
131            BindingError::WrongEntityType(_) => Self::WrongEntityType,
132            BindingError::TemplateViolation(_) => Self::TemplateViolation,
133            BindingError::MissingProperty(_) => Self::MissingProperty,
134            BindingError::CatalogNotLoaded(_) => Self::CatalogNotLoaded,
135            BindingError::UnknownAttribute(_) => Self::UnknownAttribute,
136            BindingError::DerivedAttribute(_) => Self::DerivedAttribute,
137            BindingError::MissingAttribute(_) => Self::MissingAttribute,
138            BindingError::StillReferenced(_) => Self::StillReferenced,
139            BindingError::TypeMismatch(_) => Self::TypeMismatch,
140            BindingError::AmbiguousValue(_) => Self::AmbiguousValue,
141            BindingError::InvalidSelector { .. } => Self::InvalidSelector,
142            BindingError::InverseAttribute(_) => Self::InverseAttribute,
143            BindingError::ExpressMismatch(_) => Self::ExpressMismatch,
144            BindingError::InvalidExpress(_) => Self::InvalidExpress,
145            BindingError::HistoryEmpty(_) => Self::HistoryEmpty,
146            BindingError::HistoryStale(_) => Self::HistoryStale,
147        }
148    }
149}
150
151/// ABI and crate versions, reported separately: the ABI version changes only
152/// when the C surface does, the crate version on every release.
153#[repr(C)]
154#[derive(Debug, Default, Clone, Copy, PartialEq, Eq)]
155pub struct OpenbimIfcVersion {
156    /// ABI major; also the `v0_1` in every symbol name.
157    pub abi_major: u16,
158    /// ABI minor.
159    pub abi_minor: u16,
160    /// ABI patch.
161    pub abi_patch: u16,
162    /// Crate major.
163    pub crate_major: u16,
164    /// Crate minor.
165    pub crate_minor: u16,
166    /// Crate patch.
167    pub crate_patch: u16,
168}
169
170/// Run one export, containing any panic.
171pub(crate) fn boundary(operation: impl FnOnce() -> OpenbimIfcStatus) -> OpenbimIfcStatus {
172    catch_unwind(AssertUnwindSafe(operation)).unwrap_or(OpenbimIfcStatus::Panic)
173}
174
175#[cfg(test)]
176mod tests {
177    use super::*;
178
179    #[test]
180    fn a_panic_is_contained() {
181        assert_eq!(boundary(|| panic!("contained")), OpenbimIfcStatus::Panic);
182    }
183
184    #[test]
185    fn binding_errors_keep_their_shared_meaning() {
186        let cases = [
187            (BindingError::Parse(String::new()), OpenbimIfcStatus::Parse),
188            (BindingError::Write(String::new()), OpenbimIfcStatus::Write),
189            (
190                BindingError::MissingEntity(1),
191                OpenbimIfcStatus::MissingEntity,
192            ),
193            (
194                BindingError::InvalidValue(String::new()),
195                OpenbimIfcStatus::InvalidValue,
196            ),
197            (
198                BindingError::OutOfRange(String::new()),
199                OpenbimIfcStatus::OutOfRange,
200            ),
201            (
202                BindingError::UnsupportedSchema(String::new()),
203                OpenbimIfcStatus::UnsupportedSchema,
204            ),
205            (BindingError::Io(String::new()), OpenbimIfcStatus::Io),
206            (
207                BindingError::UnsupportedProfile(String::new()),
208                OpenbimIfcStatus::UnsupportedProfile,
209            ),
210            (
211                BindingError::FeatureDisabled(""),
212                OpenbimIfcStatus::FeatureDisabled,
213            ),
214            (
215                BindingError::InvalidModel(String::new()),
216                OpenbimIfcStatus::InvalidModel,
217            ),
218            (
219                BindingError::MissingReference(String::new()),
220                OpenbimIfcStatus::MissingReference,
221            ),
222            (
223                BindingError::BudgetExceeded(String::new()),
224                OpenbimIfcStatus::BudgetExceeded,
225            ),
226            (
227                BindingError::Unsupported(String::new()),
228                OpenbimIfcStatus::Unsupported,
229            ),
230            (
231                BindingError::WrongEntityType(String::new()),
232                OpenbimIfcStatus::WrongEntityType,
233            ),
234            (
235                BindingError::TemplateViolation(String::new()),
236                OpenbimIfcStatus::TemplateViolation,
237            ),
238            (
239                BindingError::MissingProperty(String::new()),
240                OpenbimIfcStatus::MissingProperty,
241            ),
242            (
243                BindingError::CatalogNotLoaded(String::new()),
244                OpenbimIfcStatus::CatalogNotLoaded,
245            ),
246            (
247                BindingError::UnknownAttribute(String::new()),
248                OpenbimIfcStatus::UnknownAttribute,
249            ),
250            (
251                BindingError::DerivedAttribute(String::new()),
252                OpenbimIfcStatus::DerivedAttribute,
253            ),
254            (
255                BindingError::MissingAttribute(String::new()),
256                OpenbimIfcStatus::MissingAttribute,
257            ),
258            (
259                BindingError::StillReferenced(String::new()),
260                OpenbimIfcStatus::StillReferenced,
261            ),
262            (
263                BindingError::TypeMismatch(String::new()),
264                OpenbimIfcStatus::TypeMismatch,
265            ),
266            (
267                BindingError::AmbiguousValue(String::new()),
268                OpenbimIfcStatus::AmbiguousValue,
269            ),
270            (
271                BindingError::InvalidSelector {
272                    detail: String::new(),
273                    span: (0, 0),
274                },
275                OpenbimIfcStatus::InvalidSelector,
276            ),
277            (
278                BindingError::InverseAttribute(String::new()),
279                OpenbimIfcStatus::InverseAttribute,
280            ),
281            (
282                BindingError::ExpressMismatch(String::new()),
283                OpenbimIfcStatus::ExpressMismatch,
284            ),
285            (
286                BindingError::InvalidExpress(String::new()),
287                OpenbimIfcStatus::InvalidExpress,
288            ),
289            (
290                BindingError::HistoryEmpty(String::new()),
291                OpenbimIfcStatus::HistoryEmpty,
292            ),
293            (
294                BindingError::HistoryStale(String::new()),
295                OpenbimIfcStatus::HistoryStale,
296            ),
297        ];
298        for (error, status) in cases {
299            assert_eq!(OpenbimIfcStatus::from(&error), status, "{}", error.code());
300        }
301    }
302}