Skip to main content

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}