openbim_ifc_capi/open.rs
1//! Opening a model from a file path.
2//!
3//! A strict read keeps the file as the model's source and decodes entities
4//! on access. Reading the file here, straight into that source, saves the
5//! host a read into its own buffer plus the copy `model_parse` makes of it.
6
7use std::path::Path;
8
9use openbim_ifc_binding_core::IfcModel;
10
11use crate::buffer::text;
12use crate::model::{finish_load, OpenbimIfcModel};
13use crate::status::{boundary, OpenbimIfcStatus};
14
15/// Read the STEP file at `path` (UTF-8, `path_len` bytes, no NUL needed)
16/// into a model that owns its bytes, and write the new model's handle. An
17/// ifcZIP archive is read as `openbim_ifc_v0_1_model_parse` reads one.
18///
19/// Errors as `openbim_ifc_v0_1_model_parse`, plus `Io` when the file cannot
20/// be opened or read.
21///
22/// # Safety
23/// `path` must be valid for `path_len` reads; `out_model` for one write;
24/// `error_buffer`, if non-null, for `capacity` writes.
25#[no_mangle]
26pub unsafe extern "C" fn openbim_ifc_v0_1_model_open(
27 path: *const u8,
28 path_len: usize,
29 out_model: *mut OpenbimIfcModel,
30 error_buffer: *mut u8,
31 capacity: usize,
32) -> OpenbimIfcStatus {
33 boundary(|| {
34 if out_model.is_null() || (capacity != 0 && error_buffer.is_null()) {
35 return OpenbimIfcStatus::NullPointer;
36 }
37 // SAFETY: caller contract above.
38 let path = match unsafe { text(path, path_len) } {
39 Ok(path) => path,
40 Err(status) => return status,
41 };
42 let loaded = IfcModel::open(Path::new(path));
43 // SAFETY: checked above; caller contract above.
44 unsafe { finish_load(loaded, out_model, error_buffer, capacity) }
45 })
46}
47
48/// Read the STEP file at `path` through a memory mapping, and write the new
49/// model's handle. No copy of the file is made, and its pages belong to the
50/// page cache rather than the process heap.
51///
52/// # Safety
53/// As `openbim_ifc_v0_1_model_open`, and additionally: the file must not
54/// be modified or truncated until the model is destroyed. The model decodes
55/// entities from the mapping on access; a changed file makes that fail
56/// (reported as `Panic`), end the process (`SIGBUS` on truncation), or read
57/// other content.
58#[no_mangle]
59pub unsafe extern "C" fn openbim_ifc_v0_1_model_open_mapped(
60 path: *const u8,
61 path_len: usize,
62 out_model: *mut OpenbimIfcModel,
63 error_buffer: *mut u8,
64 capacity: usize,
65) -> OpenbimIfcStatus {
66 boundary(|| {
67 if out_model.is_null() || (capacity != 0 && error_buffer.is_null()) {
68 return OpenbimIfcStatus::NullPointer;
69 }
70 // SAFETY: caller contract above.
71 let path = match unsafe { text(path, path_len) } {
72 Ok(path) => path,
73 Err(status) => return status,
74 };
75 // SAFETY: the caller guarantees the file stays unchanged while the
76 // model lives.
77 let loaded = unsafe { IfcModel::open_mapped(Path::new(path)) };
78 // SAFETY: checked above; caller contract above.
79 unsafe { finish_load(loaded, out_model, error_buffer, capacity) }
80 })
81}