openbim-ifc

Appearance

C and C++ ​

openbim-ifc-capi is a versioned C ABI over the IFC core, usable from C, C++, or anything with a C FFI. It is not packaged yet: build it from a checkout.

bash
cargo build -p openbim-ifc-capi --release

This produces a static and a shared library under target/release/. The header is crates/openbim-ifc-capi/include/openbim_ifc.h. It is generated by cbindgen, and the gate fails when the committed copy is stale.

The binding exposes the record model over STEP: parse, read and edit attributes, and write. Domain views such as property sets or the spatial tree (#123), ifcXML, validation and checked transactions (#244) are not bound yet; use the Rust crates for those. Packaging is #41.

Read an entity ​

c
OpenbimIfcModel model = 0;
if (openbim_ifc_v0_1_model_parse(data, len, &model, NULL, 0) != OPENBIM_IFC_STATUS_OK) {
  return 1;
}

/* Every call that returns a buffer: ask for the size, then fetch. */
size_t need = 0;
openbim_ifc_v0_1_entity_type(model, 1, NULL, 0, &need);
uint8_t *type = (uint8_t *)malloc(need);
openbim_ifc_v0_1_entity_type(model, 1, type, need, &need);
printf("#1 is %s\n", (const char *)type); /* #1 is IFCWALL */
free(type);

openbim_ifc_v0_1_model_destroy(model);

The protocol is documented in the crate's README:

  • every export is versioned (openbim_ifc_v0_1_*);
  • models are opaque integer handles;
  • no Rust allocation crosses the ABI, so every variable-size output is a caller-owned buffer, sized by a first call with NULL, 0;
  • every failure is an OpenbimIfcStatus, never a crash.

API ​

Generated from crates/openbim-ifc-capi/include/openbim_ifc.h.

Functions ​

openbim_ifc_v0_1_entity_add ​

c
OpenbimIfcStatus openbim_ifc_v0_1_entity_add(OpenbimIfcModel model, const uint8_t *type_name, size_t type_len, size_t attribute_count, const OpenbimIfcValueNode *nodes, size_t node_count, const uint8_t *strings, size_t string_len, uint64_t *out_id);

Append an entity of type_name whose attribute_count attributes are on the tape back to back, and write its new id to out_id.

Safety. As for openbim_ifc_v0_1_entity_set_attribute; type_name valid for type_len reads; out_id valid for one write.

openbim_ifc_v0_1_entity_attribute ​

c
OpenbimIfcStatus openbim_ifc_v0_1_entity_attribute(OpenbimIfcModel model, uint64_t id, size_t index, OpenbimIfcValueNode *nodes, size_t node_capacity, size_t *out_nodes_required, uint8_t *strings, size_t string_capacity, size_t *out_strings_required);

Attribute index of entity id as a value tape ($ past the end).

Safety. As for fill_tape: each buffer null with capacity 0, or valid for its capacity; both out_*_required valid for one write.

openbim_ifc_v0_1_entity_attributes ​

c
OpenbimIfcStatus openbim_ifc_v0_1_entity_attributes(OpenbimIfcModel model, uint64_t id, size_t *out_count, OpenbimIfcValueNode *nodes, size_t node_capacity, size_t *out_nodes_required, uint8_t *strings, size_t string_capacity, size_t *out_strings_required);

Every attribute of entity id, back to back on one tape, plus how many top-level values it holds.

Safety. As for openbim_ifc_v0_1_entity_attribute; out_count valid for one write.

openbim_ifc_v0_1_entity_remove ​

c
OpenbimIfcStatus openbim_ifc_v0_1_entity_remove(OpenbimIfcModel model, uint64_t id);

Remove entity id; references to it are left dangling.

openbim_ifc_v0_1_entity_set_attribute ​

c
OpenbimIfcStatus openbim_ifc_v0_1_entity_set_attribute(OpenbimIfcModel model, uint64_t id, size_t index, const OpenbimIfcValueNode *nodes, size_t node_count, const uint8_t *strings, size_t string_len);

Set attribute index of entity id from a one-value tape. Writing past the end pads the gap with $.

Safety.nodes must be valid for node_count reads and strings for string_len reads (either may be null when its length is 0).

openbim_ifc_v0_1_entity_type ​

c
OpenbimIfcStatus openbim_ifc_v0_1_entity_type(OpenbimIfcModel model, uint64_t id, uint8_t *buffer, size_t capacity, size_t *out_required);

The type name of entity id, upper-case, NUL-terminated.

Safety. As for openbim_ifc_v0_1_model_write.

openbim_ifc_v0_1_last_error_code ​

c
OpenbimIfcStatus openbim_ifc_v0_1_last_error_code(OpenbimIfcModel model, uint8_t *buffer, size_t capacity, size_t *out_required);

The last error on model as its stable code (parse, missing-entity, ...), NUL-terminated; NoValue if the last call succeeded.

Safety.buffer must be null (with capacity 0) or valid for capacity writes; out_required valid for one write.

openbim_ifc_v0_1_last_error_message ​

c
OpenbimIfcStatus openbim_ifc_v0_1_last_error_message(OpenbimIfcModel model, uint8_t *buffer, size_t capacity, size_t *out_required);

The last error on model as a human message, NUL-terminated; NoValue if the last call succeeded.

Safety. As for openbim_ifc_v0_1_last_error_code.

openbim_ifc_v0_1_live_models ​

c
OpenbimIfcStatus openbim_ifc_v0_1_live_models(size_t *out_count);

Number of live models, for leak checks.

Safety.out_count must be null or valid for one write.

openbim_ifc_v0_1_model_create ​

c
OpenbimIfcStatus openbim_ifc_v0_1_model_create(OpenbimIfcModel *out_model);

Create an empty model and write its handle to out_model.

Safety.out_model must be null or valid for one write.

openbim_ifc_v0_1_model_dangling_references ​

c
OpenbimIfcStatus openbim_ifc_v0_1_model_dangling_references(OpenbimIfcModel model, uint64_t *buffer, size_t capacity, size_t *out_required);

Every dangling reference as (from, to) pairs, flattened: element 2k is a referencing id, 2k+1 the missing id it points to.

Safety. As for openbim_ifc_v0_1_model_ids; sizes count u64s, not pairs.

openbim_ifc_v0_1_model_destroy ​

c
OpenbimIfcStatus openbim_ifc_v0_1_model_destroy(OpenbimIfcModel model);

Destroy a model. A stale or repeated handle is InvalidHandle.

openbim_ifc_v0_1_model_diagnostic ​

c
OpenbimIfcStatus openbim_ifc_v0_1_model_diagnostic(OpenbimIfcModel model, size_t index, uint8_t *buffer, size_t capacity, size_t *out_required);

Diagnostic index as a NUL-terminated string; OutOfRange past the end.

Safety. As for openbim_ifc_v0_1_model_write.

openbim_ifc_v0_1_model_diagnostic_count ​

c
OpenbimIfcStatus openbim_ifc_v0_1_model_diagnostic_count(OpenbimIfcModel model, size_t *out_count);

Number of non-fatal parse diagnostics.

Safety.out_count must be null or valid for one write.

openbim_ifc_v0_1_model_ids ​

c
OpenbimIfcStatus openbim_ifc_v0_1_model_ids(OpenbimIfcModel model, uint64_t *buffer, size_t capacity, size_t *out_required);

Every entity id, in file order.

Safety.buffer must be null (with capacity 0) or valid for capacity u64 writes; out_required valid for one write.

openbim_ifc_v0_1_model_ids_of_type ​

c
OpenbimIfcStatus openbim_ifc_v0_1_model_ids_of_type(OpenbimIfcModel model, const uint8_t *type_name, size_t type_len, uint64_t *buffer, size_t capacity, size_t *out_required);

Ids of every entity of exactly type_name (UTF-8, type_len bytes, case-insensitive). Subtypes are not included.

Safety.type_name must be valid for type_len reads; otherwise as for openbim_ifc_v0_1_model_ids.

openbim_ifc_v0_1_model_ids_of_type_including_subtypes ​

c
OpenbimIfcStatus openbim_ifc_v0_1_model_ids_of_type_including_subtypes(OpenbimIfcModel model, const uint8_t *type_name, size_t type_len, uint64_t *buffer, size_t capacity, size_t *out_required);

Ids of every entity of type_name or any of its subtypes, using the schema the file's header declares. UnsupportedSchema if none is bundled.

Safety. As for openbim_ifc_v0_1_model_ids_of_type.

openbim_ifc_v0_1_model_len ​

c
OpenbimIfcStatus openbim_ifc_v0_1_model_len(OpenbimIfcModel model, size_t *out_count);

Number of entities.

Safety.out_count must be null or valid for one write.

openbim_ifc_v0_1_model_open ​

c
OpenbimIfcStatus openbim_ifc_v0_1_model_open(const uint8_t *path, size_t path_len, OpenbimIfcModel *out_model, uint8_t *error_buffer, size_t capacity);

Read the STEP file at path (UTF-8, path_len bytes, no NUL needed) into a model that owns its bytes, and write the new model's handle.

Errors as openbim_ifc_v0_1_model_parse, plus Io when the file cannot be opened or read.

Safety.path must be valid for path_len reads; out_model for one write; error_buffer, if non-null, for capacity writes.

openbim_ifc_v0_1_model_open_mapped ​

c
OpenbimIfcStatus openbim_ifc_v0_1_model_open_mapped(const uint8_t *path, size_t path_len, OpenbimIfcModel *out_model, uint8_t *error_buffer, size_t capacity);

Read the STEP file at path through a memory mapping, and write the new model's handle. No copy of the file is made, and its pages belong to the page cache rather than the process heap.

Safety. As openbim_ifc_v0_1_model_open, and additionally: the file must not be modified or truncated until the model is destroyed. The model decodes entities from the mapping on access; a changed file makes that fail (reported as Panic), end the process (SIGBUS on truncation), or read other content.

openbim_ifc_v0_1_model_parse ​

c
OpenbimIfcStatus openbim_ifc_v0_1_model_parse(const uint8_t *data, size_t len, OpenbimIfcModel *out_model, uint8_t *error_buffer, size_t capacity);

Parse len bytes of STEP and write the new model's handle.

A parse failure has no model to hold its error, so the message is written to the optional error_buffer (NUL-terminated, truncated to capacity).

Safety.data must be valid for len reads; out_model for one write; error_buffer, if non-null, for capacity writes.

openbim_ifc_v0_1_model_schema ​

c
OpenbimIfcStatus openbim_ifc_v0_1_model_schema(OpenbimIfcModel model, uint8_t *buffer, size_t capacity, size_t *out_required);

The first FILE_SCHEMA token as a NUL-terminated string, or NoValue.

Safety. As for openbim_ifc_v0_1_model_write.

openbim_ifc_v0_1_model_write ​

c
OpenbimIfcStatus openbim_ifc_v0_1_model_write(OpenbimIfcModel model, uint8_t *buffer, size_t capacity, size_t *out_required);

Serialize as STEP into a caller buffer; out_required gets the size.

Safety.buffer must be null (with capacity 0) or valid for capacity writes; out_required valid for one write.

openbim_ifc_v0_1_version ​

c
OpenbimIfcStatus openbim_ifc_v0_1_version(OpenbimIfcVersion *out_version);

Write the ABI and crate versions.

Safety.out_version must be null or valid for one write.

Status codes ​

StatusValueMeaning
OPENBIM_IFC_STATUS_OK0Success.
OPENBIM_IFC_STATUS_NULL_POINTER1A required pointer was null.
OPENBIM_IFC_STATUS_INVALID_ARGUMENT2An argument was malformed (bad UTF-8, a malformed value tape, ...).
OPENBIM_IFC_STATUS_INVALID_HANDLE3The model handle is zero, stale, or already destroyed.
OPENBIM_IFC_STATUS_BUFFER_TOO_SMALL4The output buffer is smaller than *out_required.
OPENBIM_IFC_STATUS_PARSE10The STEP input could not be parsed (parse).
OPENBIM_IFC_STATUS_WRITE11The model could not be serialized (write).
OPENBIM_IFC_STATUS_MISSING_ENTITY12No entity has the given id (missing-entity).
OPENBIM_IFC_STATUS_INVALID_VALUE13A value did not follow the encoding (invalid-value).
OPENBIM_IFC_STATUS_OUT_OF_RANGE14An id or index is outside the representable range (out-of-range).
OPENBIM_IFC_STATUS_UNSUPPORTED_SCHEMA15The file's schema is not bundled (unsupported-schema).
OPENBIM_IFC_STATUS_IO16A file could not be opened or read (io).
OPENBIM_IFC_STATUS_NO_VALUE20The requested value does not exist (no schema token, no error, ...).
OPENBIM_IFC_STATUS_PANIC255A Rust panic was contained at the boundary. Report it as a bug.

Released under the AGPL-3.0-or-later licence. ISO and CEN standards material is not redistributed.

Copyright (c) 2026 openbimrs contributors