openbim_ifc_binding_core/catalog.rs
1//! The PSD/QTO catalog that property edits check `Pset_` and `Qto_` sets
2//! against (ADR 0017; #123, #318).
3//!
4//! A build gets the catalog one of two ways:
5//!
6//! - `property-catalog` (default; the C and Python bindings) embeds every
7//! edition. Nothing needs loading: [`is_loaded`] is `true` and [`load`]
8//! accepts the bytes without reading them.
9//! - `property-catalog-runtime` (the npm package) embeds none. The host
10//! reads an edition's snapshot file, named by [`file_name`], and hands its
11//! bytes to [`load`], which checks them against the edition's pinned
12//! SHA-256 and keeps the catalog for the process (for WebAssembly, the
13//! module instance). Until then a write to a `Pset_`/`Qto_` set of that
14//! release is refused with `catalog-not-loaded`; removals and other sets
15//! are not affected.
16//!
17//! Without either feature every function here refuses with
18//! `feature-disabled`, as such a write does.
19//!
20//! A release is named as a file header names it: `IFC2X3`, `IFC4` or
21//! `IFC4X3` (`IFC4X3_ADD2`), any case. Each reads one edition: IFC2X3 TC1,
22//! IFC4 ADD2 TC1 or IFC4X3 ADD2. Any other release has no catalog and is
23//! refused with `unsupported-schema`.
24
25use crate::BindingError;
26
27/// The releases that have a catalog edition, in edition order.
28pub const RELEASES: [&str; 3] = ["IFC2X3", "IFC4", "IFC4X3"];
29
30#[cfg(any(feature = "property-catalog", feature = "property-catalog-runtime"))]
31fn edition(
32 release: &str,
33) -> Result<ifc::property_catalog::definition::CatalogEdition, BindingError> {
34 ifc::SchemaVersion::from_header_token(release)
35 .and_then(ifc::release_edition)
36 .ok_or_else(|| {
37 BindingError::UnsupportedSchema(format!(
38 "{release}: no PSD/QTO catalog edition (IFC2X3, IFC4 or IFC4X3)"
39 ))
40 })
41}
42
43/// The file name of `release`'s catalog snapshot, such as
44/// `ifc4x3-add2.bin`; the npm package ships it as `catalog/<name>`.
45pub fn file_name(release: &str) -> Result<&'static str, BindingError> {
46 #[cfg(any(feature = "property-catalog", feature = "property-catalog-runtime"))]
47 {
48 Ok(ifc::property_catalog::snapshot::file_name(edition(
49 release,
50 )?))
51 }
52 #[cfg(not(any(feature = "property-catalog", feature = "property-catalog-runtime")))]
53 {
54 let _ = release;
55 Err(BindingError::FeatureDisabled("property-catalog"))
56 }
57}
58
59/// Whether a write to `release`'s catalog sets can be checked now.
60pub fn is_loaded(release: &str) -> Result<bool, BindingError> {
61 #[cfg(feature = "property-catalog")]
62 {
63 edition(release).map(|_| true)
64 }
65 #[cfg(all(
66 feature = "property-catalog-runtime",
67 not(feature = "property-catalog")
68 ))]
69 {
70 Ok(ifc::property_catalog::runtime::is_installed(edition(
71 release,
72 )?))
73 }
74 #[cfg(not(any(feature = "property-catalog", feature = "property-catalog-runtime")))]
75 {
76 let _ = release;
77 Err(BindingError::FeatureDisabled("property-catalog"))
78 }
79}
80
81/// Load `release`'s catalog from its snapshot bytes: the per-edition file
82/// [`file_name`] names, or the container of every edition. Refused with
83/// `invalid-value` when the bytes are not the pinned snapshot (another
84/// edition's file, another version, a damaged download); nothing is loaded
85/// then. Loading an edition again is a no-op.
86pub fn load(release: &str, bytes: &[u8]) -> Result<(), BindingError> {
87 #[cfg(feature = "property-catalog")]
88 {
89 // Embedded: every edition is present already.
90 let _ = bytes;
91 edition(release).map(|_| ())
92 }
93 #[cfg(all(
94 feature = "property-catalog-runtime",
95 not(feature = "property-catalog")
96 ))]
97 {
98 let edition = edition(release)?;
99 ifc::property_catalog::runtime::install(edition, bytes)
100 .map_err(|error| BindingError::InvalidValue(format!("{release} catalog: {error}")))
101 }
102 #[cfg(not(any(feature = "property-catalog", feature = "property-catalog-runtime")))]
103 {
104 let _ = (release, bytes);
105 Err(BindingError::FeatureDisabled("property-catalog"))
106 }
107}