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}