C and C++ API
crates/cadkit-capi exposes cadkit through a small, stable C ABI plus a header-only C++17
wrapper.
crates/cadkit-capi/include/cadkit.h: the C header (hand-maintained)crates/cadkit-capi/include/cadkit.hpp:cadkit::DocumentRAII wrappercrates/cadkit-capi/examples/c/info.c,examples/cpp/info.cpp,CMakeLists.txt
Prebuilt libraries
Section titled “Prebuilt libraries”Each GitHub release has a cadkit-capi-<target> archive (Linux x86_64 and aarch64 built
against glibc 2.28, macOS arm64 and x86_64, Windows x64) with include/, the shared and
static libraries in lib/, and the license files. CADKIT_LIB_DIR below can point at its
lib/ folder.
python scripts/buildlock.py cargo build -p cadkit-capi --releaseArtifacts in target/release/: the shared library (cadkit_capi.dll with import library
cadkit_capi.dll.lib, libcadkit_capi.so, libcadkit_capi.dylib) and the static library
(cadkit_capi.lib / libcadkit_capi.a). The static library needs the platform libraries
that Rust’s std requires (cargo rustc -p cadkit-capi -- --print native-static-libs lists
them); prefer the shared library.
Examples with CMake:
cmake -S crates/cadkit-capi -B build/capi -DCADKIT_LIB_DIR=$PWD/target/releasecmake --build build/capi./build/capi/info_c plan.dxf plan.svgOr directly:
gcc -Icrates/cadkit-capi/include crates/cadkit-capi/examples/c/info.c \ -Ltarget/release -lcadkit_capi -o info_cWith MSVC, link cadkit_capi.dll.lib and ship cadkit_capi.dll next to the executable.
With MinGW, link the DLL directly.
Conventions
Section titled “Conventions”- Every fallible function returns
cadkit_status; results come back through out-pointers, which are set toNULLon failure. cadkit_last_error_message()returns the message of the last failed call on the calling thread. It is owned by the library, neverNULL, and valid until the next cadkit call on that thread. Do not free it.- Strings are UTF-8 and NUL-terminated.
- No panic crosses the boundary: an internal panic is returned as
CADKIT_PANIC. - Every pointer argument is null-checked; passing
NULLreturnsCADKIT_NULL_POINTER. - Not thread-affine: a document is immutable and may be read from several threads at once. Do not free it while another thread uses it.
Ownership
Section titled “Ownership”| Object | Created by | Released by |
|---|---|---|
cadkit_document* |
cadkit_read_file, cadkit_read_bytes, cadkit_document_from_json, _explode_inserts, _convert_units |
cadkit_document_free (once; NULL is a no-op) |
char* |
cadkit_document_to_json, _to_svg, _to_dxf, _to_citygml, _to_citygml_with_report, _info_json, cadkit_citygml_read_json, _write_json, _preflight_tkgm, the report of cadkit_dgn_strip_seed |
cadkit_string_free (once; NULL is a no-op) |
uint8_t* |
cadkit_document_to_dgn, _to_dxf_bytes, cadkit_dgn_strip_seed |
cadkit_bytes_free (NULL or repeated free is a no-op; never pass to cadkit_string_free) |
const char* |
cadkit_version, cadkit_status_string, cadkit_last_error_message |
never freed |
Freeing a document twice, or using one after it was freed, is detected through a registry of
live handles and returns CADKIT_INVALID_HANDLE. This is a safety net, not a contract: if
the freed address is reused by a later document the stale pointer cannot be told apart.
Functions
Section titled “Functions”| Function | Purpose |
|---|---|
cadkit_version |
Library version string |
cadkit_status_string(status) |
Static text for a status code |
cadkit_last_error_message |
Thread-local message of the last failure |
cadkit_options_init, cadkit_svg_options_init |
Fill option structs with defaults |
cadkit_detect(data, len) |
Format from the header only (CADKIT_FORMAT_DWG, _DXF, _DGN_V7, _DGN_V8, _CITY_GML, or _UNKNOWN; "city_gml" in JSON) |
cadkit_read_file(path, options, &doc) |
Read a drawing from a UTF-8 path |
cadkit_read_bytes(data, len, options, &doc) |
Read a drawing from memory |
cadkit_document_from_json(json, &doc) |
Construct a format-neutral document from JSON |
cadkit_document_free(doc) |
Release a document |
cadkit_document_info(doc, &info) |
Format and counts as a plain struct |
cadkit_document_info_json(doc, &s) |
Summary as JSON (adds version, application, per-kind counts) |
cadkit_document_to_json(doc, pretty, &s) |
Full model as JSON |
cadkit_document_to_svg(doc, options, &s) |
One model rendered as SVG |
cadkit_document_to_dxf(doc, version, &s) |
ASCII DXF of the given version |
cadkit_document_to_dgn(doc, seed, seed_len, options_json, &bytes, &len) |
Seed-based DGN V8 binary output |
cadkit_dgn_strip_seed(seed, seed_len, options_json, options, &bytes, &len, &report) |
DGN V8 seed without the model’s drawing content and identifying document properties, plus its report JSON |
cadkit_bytes_free(bytes) |
Release a binary buffer returned by cadkit_document_to_dgn, _to_dxf_bytes, cadkit_dgn_strip_seed |
cadkit_document_to_citygml(doc, srs_name, lod, &s) |
Generic CityGML 2.0 XML with an explicit CRS and LoD |
cadkit_document_to_citygml_with_report(doc, srs_name, lod, metadata_only, &s) |
Generic CityGML 2.0 XML + conversion ExportReport as JSON ({"xml", "report"}) |
cadkit_citygml_read_json(data, len, options, &s) |
Read native CityGML 2.0 bytes into editable object-graph JSON |
cadkit_citygml_write_json(json, validation_options_json, &s) |
Serialize native CityGML JSON to UTF-8 CityGML 2.0 XML |
cadkit_citygml_preflight_tkgm(json, profile, &s) |
Local structural TKGM preflight report JSON for native CityGML JSON |
cadkit_string_free(s) |
Release a returned string |
Status codes
Section titled “Status codes”| Code | Value | Meaning |
|---|---|---|
CADKIT_OK |
0 | Success |
CADKIT_NULL_POINTER |
1 | A required pointer was NULL |
CADKIT_INVALID_ARGUMENT |
2 | Out-of-range value or invalid UTF-8 |
CADKIT_IO |
3 | File could not be read |
CADKIT_TRUNCATED |
4 | Input ended early |
CADKIT_INVALID_DATA |
5 | Input violates the format |
CADKIT_UNSUPPORTED |
6 | Valid input using a feature that is not implemented |
CADKIT_LIMIT_EXCEEDED |
7 | A configured limit was exceeded |
CADKIT_UNKNOWN_FORMAT |
8 | Not a recognized drawing format |
CADKIT_PANIC |
9 | Internal panic caught (a bug; please report) |
CADKIT_INTERNAL |
10 | Unexpected internal failure |
CADKIT_INVALID_HANDLE |
11 | Handle is not a live document |
Enum values are part of the ABI and never change; new values may be added.
Options
Section titled “Options”cadkit_options: resource limits (max_input_bytes, max_decompressed_bytes,
max_objects, max_depth, max_string_bytes, max_vertices; zero selects the default),
keep_raw, fallback_codepage (WHATWG label such as "windows-1254"). Pass NULL for all
defaults. Lower the limits when reading untrusted files (see SECURITY.md).
cadkit_svg_options: model_index, width_px, stroke_px (both must be finite and > 0),
background (CSS color, NULL for transparent), text, expand_blocks. Pass NULL for
defaults, or start from cadkit_svg_options_init.
Example (C)
Section titled “Example (C)”#include <stdio.h>#include "cadkit.h"
int main(void) { cadkit_document *doc = NULL; cadkit_status st = cadkit_read_file("plan.dxf", NULL, &doc); if (st != CADKIT_OK) { fprintf(stderr, "%s: %s\n", cadkit_status_string(st), cadkit_last_error_message()); return 1; } cadkit_info info; if (cadkit_document_info(doc, &info) == CADKIT_OK) printf("%llu entities\n", (unsigned long long)info.entity_count);
char *svg = NULL; if (cadkit_document_to_svg(doc, NULL, &svg) == CADKIT_OK) { fputs(svg, stdout); cadkit_string_free(svg); } cadkit_document_free(doc); return 0;}C++ wrapper
Section titled “C++ wrapper”cadkit::Document is move-only and releases its handle in the destructor. Failures throw
cadkit::Error (derives std::runtime_error; status() returns the cadkit_status, what()
the library message). Getters return std::string.
#include <iostream>#include "cadkit.hpp"
int main() { try { auto doc = cadkit::Document::read_file("plan.dxf"); std::cout << doc.info().entity_count << " entities\n"; cadkit::SvgOptions svg; svg.width_px = 1200; std::string text = doc.to_svg(svg); std::string dxf = doc.to_dxf(CADKIT_DXF_R2000); } catch (const cadkit::Error& e) { std::cerr << e.what() << " (status " << static_cast<int>(e.status()) << ")\n"; return 1; }}Stability
Section titled “Stability”The header is the contract. Functions are only added in minor versions; existing signatures,
enum values and struct layouts change only with a major version (structs gain fields at the
end only after a major bump, which is why options are filled with the _init functions).
Files that use features a reader does not handle return CADKIT_UNSUPPORTED; the support
matrix is in the README.
DGN V8 and native CityGML
Section titled “DGN V8 and native CityGML”CADKIT_FORMAT_CITY_GML = 5 extends the format enum without changing existing
values or struct layouts. New entry points are declared in cadkit.h:
cadkit_document_from_jsoncreates a neutral document.cadkit_document_to_dgnaccepts seed bytes and optional RustWriteOptionsJSON, returning a pointer and byte length. Release withcadkit_bytes_free; never pass the binary buffer tocadkit_string_free.cadkit_document_to_citygmlaccepts an explicit CRS and LoD, returning a UTF-8 string to release withcadkit_string_free.cadkit_document_to_citygml_with_reportreturns JSON{"xml": ..., "report": ...}(release withcadkit_string_free).metadata_onlymust be0(reject unsupported geometry) or1(retain unsupported entities as JSON metadata).cadkit_dgn_strip_seed(seed, seed_len, options_json, options, &bytes, &len, &report)copies a DGN V8 seed without the drawing content of its model and without the document properties that name people or organisations (dgn::strip_seed_v8).options_jsonfollows Rustdgn::StripSeedOptionsJSON (every field optional; an unknown field returnsCADKIT_INVALID_ARGUMENT) andoptionssets the read limits (NULL selects the defaults of either). Release the seed withcadkit_bytes_freeand thedgn::StripSeedReportJSON withcadkit_string_free; all outputs are NULL / 0 on failure. Names in the kept tables remain and are counted in the report; the result is not anonymous. C++:cadkit::strip_dgn_seed(seed, options_json, read_options)returns aStrippedDgnSeed { seed, report_json }.cadkit_citygml_read_json/cadkit_citygml_write_jsonexpose the native CityGML tree without losing semantic relationships through neutral geometry. Write options follow Rustgml::ValidationOptionsJSON.cadkit_citygml_preflight_tkgmruns local structural/field preflight on native CityGML JSON for an explicitprofile("city-model-tender"or"digital-building-registration");acceptance_verifiedin the returned JSON report is alwaysfalse.
Null/error paths reset outputs. Owned binary buffers are tracked to make repeated
free calls harmless. As with existing document handles, caller-controlled input
pointers must remain valid for the call and live documents cannot be freed
concurrently. C++ adds RAII Document::from_json, to_dgn, to_citygml, and
to_citygml_with_report.
Header inspection and immutable operations
Section titled “Header inspection and immutable operations”cadkit_inspect_file(path, options, &json) and
cadkit_inspect_bytes(data, len, options, &json) return header-only summary JSON.
Release each returned string with cadkit_string_free. Resource limits use the existing
cadkit_options contract.
cadkit_document_explode_inserts(doc, max_depth, ©) and
cadkit_document_convert_units(doc, "meter", ©) return a new document handle.
The source remains immutable and safe for concurrent readers; release the copy with
cadkit_document_free. Missing, cyclic or deeper block references remain as inserts.
cadkit_document_to_dxf_bytes(doc, version, codepage, &data, &len) supports legacy output
encodings such as DOS857; codepage=NULL selects the default. Release the byte buffer
with cadkit_bytes_free. On failure the pointer and length are reset to NULL/zero.
The existing structs and enum values remain unchanged (64-bit layouts: options 48 bytes,
SVG options 40 bytes, info 48 bytes). The C++17 wrapper exposes inspect_file,
inspect_bytes, explode_inserts, convert_units, and to_dxf_bytes with RAII ownership.
Install for CMake and pkg-config consumers
Section titled “Install for CMake and pkg-config consumers”After building the shared library:
cmake -S crates/cadkit-capi -B build/capi -DCADKIT_LIB_DIR="$PWD/target/release" \ -DCMAKE_INSTALL_PREFIX="$PWD/build/cadkit-install"cmake --build build/capictest --test-dir build/capi --output-on-failurecmake --install build/capiConsumers use find_package(cadkit CONFIG REQUIRED) and link cadkit::cadkit, or set
PKG_CONFIG_PATH to the installed lib/pkgconfig and use pkg-config --cflags --libs cadkit.
On Unix, configure the runtime library path/rpath for the installed shared library. On
Windows, ship the DLL next to the consuming executable or put its directory on PATH.
The installer packages the already-built shared library and headers; it does not run Cargo.
Block expansion raises a limit error if its work budget is exhausted; it does not return a silently partial copy. Missing, cyclic and deeper references remain as inserts.