openbim_ifc_capi/relations.rs
1//! Entities by `GlobalId`, new `GlobalId`s, and an object's type, a type's
2//! occurrences and the openings and fillings of elements (#463).
3//!
4//! An optional answer (`by_guid`, `type_object`, `voided_element_of`) is
5//! written to `out_id`, or is `NoValue` when there is none; a list of ids
6//! fills the caller's buffer as `openbim_ifc_v0_1_model_ids` does.
7
8use openbim_ifc_binding_core::{name_based_guid, new_guid, relations, BindingError, IfcModel};
9
10use crate::buffer::{fill, fill_c_string, put, text};
11use crate::model::{done, fill_tape, with_model, OpenbimIfcModel};
12use crate::status::{boundary, OpenbimIfcStatus};
13use crate::tape::{OpenbimIfcValueNode, Tape};
14
15/// Write `id` to `out_id`, or answer `NoValue`.
16///
17/// # Safety
18/// `out_id` valid for one write (checked non-null by the caller).
19unsafe fn optional(id: Option<u64>, out_id: *mut u64) -> OpenbimIfcStatus {
20 match id {
21 // SAFETY: forwarded caller contract.
22 Some(id) => match unsafe { put(out_id, id) } {
23 Ok(()) => OpenbimIfcStatus::Ok,
24 Err(status) => status,
25 },
26 None => OpenbimIfcStatus::NoValue,
27 }
28}
29
30/// The entity whose `GlobalId` is `global_id` (UTF-8, `global_len` bytes),
31/// written to `out_id`; `NoValue` when none carries it.
32///
33/// The first lookup indexes every `GlobalId` once; later ones reuse the
34/// index until the model changes. `InvalidValue` for text that is not a
35/// `GlobalId`, `InvalidModel` when several entities carry it (the last
36/// error names them), `UnsupportedSchema`.
37///
38/// # Safety
39/// `global_id` valid for `global_len` reads; `out_id` valid for one write.
40#[no_mangle]
41pub unsafe extern "C" fn openbim_ifc_v0_1_model_by_guid(
42 model: OpenbimIfcModel,
43 global_id: *const u8,
44 global_len: usize,
45 out_id: *mut u64,
46) -> OpenbimIfcStatus {
47 boundary(|| {
48 if out_id.is_null() {
49 return OpenbimIfcStatus::NullPointer;
50 }
51 // SAFETY: caller contract above.
52 let global_id = match unsafe { text(global_id, global_len) } {
53 Ok(global_id) => global_id,
54 Err(status) => return status,
55 };
56 with_model(model, |m| {
57 let found = m.by_guid(global_id)?;
58 // SAFETY: checked non-null; caller contract above.
59 done(unsafe { optional(found, out_id) })
60 })
61 })
62}
63
64/// Every `GlobalId` several entities carry, in `GlobalId` order, and how
65/// many. The tape is a `LIST`; each item a `LIST` of the `GlobalId`
66/// (`TEXT`) and its holders in file order (`LIST` of `REF`). Empty for a
67/// conformant file. `UnsupportedSchema`.
68///
69/// # Safety
70/// `out_count` valid for one write; otherwise as for
71/// `openbim_ifc_v0_1_entity_attribute`.
72#[no_mangle]
73pub unsafe extern "C" fn openbim_ifc_v0_1_model_duplicate_global_ids(
74 model: OpenbimIfcModel,
75 out_count: *mut usize,
76 nodes: *mut OpenbimIfcValueNode,
77 node_capacity: usize,
78 out_nodes_required: *mut usize,
79 strings: *mut u8,
80 string_capacity: usize,
81 out_strings_required: *mut usize,
82) -> OpenbimIfcStatus {
83 boundary(|| {
84 if out_count.is_null() {
85 return OpenbimIfcStatus::NullPointer;
86 }
87 with_model(model, |m| {
88 let duplicates = m.duplicate_global_ids()?;
89 // SAFETY: checked non-null; caller contract above.
90 if let Err(status) = unsafe { put(out_count, duplicates.len()) } {
91 return done(status);
92 }
93 let tape = Tape::encode(&relations::duplicates_to_tagged(&duplicates));
94 // SAFETY: caller contract above.
95 done(unsafe {
96 fill_tape(
97 &tape,
98 nodes,
99 node_capacity,
100 out_nodes_required,
101 strings,
102 string_capacity,
103 out_strings_required,
104 )
105 })
106 })
107 })
108}
109
110/// An optional-id query: `out_id` checked, the answer written or `NoValue`.
111///
112/// # Safety
113/// `out_id` valid for one write.
114unsafe fn optional_query(
115 model: OpenbimIfcModel,
116 out_id: *mut u64,
117 query: impl FnOnce(&IfcModel) -> Result<Option<u64>, BindingError>,
118) -> OpenbimIfcStatus {
119 boundary(|| {
120 if out_id.is_null() {
121 return OpenbimIfcStatus::NullPointer;
122 }
123 with_model(model, |m| {
124 let found = query(m)?;
125 // SAFETY: checked non-null; caller contract above.
126 done(unsafe { optional(found, out_id) })
127 })
128 })
129}
130
131/// A list-of-ids query, filling the caller's buffer.
132///
133/// # Safety
134/// As for `openbim_ifc_v0_1_model_ids`.
135unsafe fn list_query(
136 model: OpenbimIfcModel,
137 buffer: *mut u64,
138 capacity: usize,
139 out_required: *mut usize,
140 query: impl FnOnce(&IfcModel) -> Result<Vec<u64>, BindingError>,
141) -> OpenbimIfcStatus {
142 boundary(|| {
143 with_model(model, |m| {
144 let ids = query(m)?;
145 // SAFETY: forwarded caller contract.
146 done(unsafe { fill(&ids, buffer, capacity, out_required) })
147 })
148 })
149}
150
151/// The type object of occurrence `id` (`IfcRelDefinesByType`), written to
152/// `out_id`; `NoValue` when it has none. `MissingEntity`,
153/// `WrongEntityType` (not an `IfcObject`), `InvalidModel` (two types, or a
154/// malformed relationship), `MissingReference`, `UnsupportedSchema`.
155///
156/// # Safety
157/// `out_id` valid for one write.
158#[no_mangle]
159pub unsafe extern "C" fn openbim_ifc_v0_1_entity_type_object(
160 model: OpenbimIfcModel,
161 id: u64,
162 out_id: *mut u64,
163) -> OpenbimIfcStatus {
164 // SAFETY: caller contract above.
165 unsafe { optional_query(model, out_id, |m| m.type_object(id)) }
166}
167
168/// Every object type object `id` types, in file order. Refusals as for
169/// [`openbim_ifc_v0_1_entity_type_object`] (`WrongEntityType`: not an
170/// `IfcTypeObject`).
171///
172/// # Safety
173/// As for `openbim_ifc_v0_1_model_ids`.
174#[no_mangle]
175pub unsafe extern "C" fn openbim_ifc_v0_1_entity_occurrences(
176 model: OpenbimIfcModel,
177 id: u64,
178 buffer: *mut u64,
179 capacity: usize,
180 out_required: *mut usize,
181) -> OpenbimIfcStatus {
182 // SAFETY: caller contract above.
183 unsafe {
184 list_query(model, buffer, capacity, out_required, |m| {
185 m.occurrences_of(id)
186 })
187 }
188}
189
190/// Every opening voiding element `id` (`IfcRelVoidsElement`), in file
191/// order. Refusals as for [`openbim_ifc_v0_1_entity_type_object`]
192/// (`WrongEntityType`: not an `IfcElement`).
193///
194/// # Safety
195/// As for `openbim_ifc_v0_1_model_ids`.
196#[no_mangle]
197pub unsafe extern "C" fn openbim_ifc_v0_1_entity_openings(
198 model: OpenbimIfcModel,
199 id: u64,
200 buffer: *mut u64,
201 capacity: usize,
202 out_required: *mut usize,
203) -> OpenbimIfcStatus {
204 // SAFETY: caller contract above.
205 unsafe { list_query(model, buffer, capacity, out_required, |m| m.openings_of(id)) }
206}
207
208/// Every element filling opening `id` (`IfcRelFillsElement`), in file
209/// order. Refusals as for [`openbim_ifc_v0_1_entity_type_object`]
210/// (`WrongEntityType`: not an `IfcOpeningElement`).
211///
212/// # Safety
213/// As for `openbim_ifc_v0_1_model_ids`.
214#[no_mangle]
215pub unsafe extern "C" fn openbim_ifc_v0_1_entity_fillings(
216 model: OpenbimIfcModel,
217 id: u64,
218 buffer: *mut u64,
219 capacity: usize,
220 out_required: *mut usize,
221) -> OpenbimIfcStatus {
222 // SAFETY: caller contract above.
223 unsafe { list_query(model, buffer, capacity, out_required, |m| m.fillings_of(id)) }
224}
225
226/// The element opening `id` voids (`IfcRelVoidsElement`), written to
227/// `out_id`; `NoValue` when it voids none. Refusals as for
228/// [`openbim_ifc_v0_1_entity_type_object`] (`WrongEntityType`: not an
229/// `IfcFeatureElementSubtraction`; `InvalidModel`: two hosts).
230///
231/// # Safety
232/// `out_id` valid for one write.
233#[no_mangle]
234pub unsafe extern "C" fn openbim_ifc_v0_1_entity_voided_element(
235 model: OpenbimIfcModel,
236 id: u64,
237 out_id: *mut u64,
238) -> OpenbimIfcStatus {
239 // SAFETY: caller contract above.
240 unsafe { optional_query(model, out_id, |m| m.voided_element_of(id)) }
241}
242
243/// A new random `GlobalId` (RFC 9562 version 4, from the operating
244/// system's generator) in IFC's 22-character form, NUL-terminated: 23
245/// bytes. Needs no model. `Unsupported` when the system has no random
246/// source.
247///
248/// # Safety
249/// `buffer` null (with `capacity` 0) or valid for `capacity` writes;
250/// `out_required` valid for one write.
251#[no_mangle]
252pub unsafe extern "C" fn openbim_ifc_v0_1_new_guid(
253 buffer: *mut u8,
254 capacity: usize,
255 out_required: *mut usize,
256) -> OpenbimIfcStatus {
257 boundary(|| match new_guid() {
258 // SAFETY: caller contract above.
259 Ok(guid) => unsafe { fill_c_string(&guid, buffer, capacity, out_required) },
260 Err(error) => OpenbimIfcStatus::from(&error),
261 })
262}
263
264/// The `GlobalId` named by `parts` (RFC 9562 version 8), NUL-terminated:
265/// the same parts give the same `GlobalId` in every binding and release.
266/// `parts` holds `part_count` UTF-8 strings of `part_lengths[i]` bytes
267/// each. Needs no model; `InvalidArgument` for a part that is not UTF-8.
268///
269/// # Safety
270/// `parts` and `part_lengths` null (with `part_count` 0) or valid for
271/// `part_count` reads, each part valid for its length; `buffer` and
272/// `out_required` as for [`openbim_ifc_v0_1_new_guid`].
273#[no_mangle]
274pub unsafe extern "C" fn openbim_ifc_v0_1_name_based_guid(
275 parts: *const *const u8,
276 part_lengths: *const usize,
277 part_count: usize,
278 buffer: *mut u8,
279 capacity: usize,
280 out_required: *mut usize,
281) -> OpenbimIfcStatus {
282 boundary(|| {
283 if part_count > 0 && (parts.is_null() || part_lengths.is_null()) {
284 return OpenbimIfcStatus::NullPointer;
285 }
286 let mut names = Vec::with_capacity(part_count);
287 for index in 0..part_count {
288 // SAFETY: both arrays hold `part_count` items (caller contract).
289 let (part, length) = unsafe { (*parts.add(index), *part_lengths.add(index)) };
290 // SAFETY: each part is valid for its length (caller contract).
291 match unsafe { text(part, length) } {
292 Ok(name) => names.push(name),
293 Err(status) => return status,
294 }
295 }
296 let guid = name_based_guid(&names);
297 // SAFETY: caller contract above.
298 unsafe { fill_c_string(&guid, buffer, capacity, out_required) }
299 })
300}