Skip to content
cadkithome

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::Document RAII wrapper
  • crates/cadkit-capi/examples/c/info.c, examples/cpp/info.cpp, CMakeLists.txt

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.

Terminal window
python scripts/buildlock.py cargo build -p cadkit-capi --release

Artifacts 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:

Terminal window
cmake -S crates/cadkit-capi -B build/capi -DCADKIT_LIB_DIR=$PWD/target/release
cmake --build build/capi
./build/capi/info_c plan.dxf plan.svg

Or directly:

Terminal window
gcc -Icrates/cadkit-capi/include crates/cadkit-capi/examples/c/info.c \
-Ltarget/release -lcadkit_capi -o info_c

With MSVC, link cadkit_capi.dll.lib and ship cadkit_capi.dll next to the executable. With MinGW, link the DLL directly.

  • Every fallible function returns cadkit_status; results come back through out-pointers, which are set to NULL on failure.
  • cadkit_last_error_message() returns the message of the last failed call on the calling thread. It is owned by the library, never NULL, 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 NULL returns CADKIT_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.
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.

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
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.

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.

#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;
}

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;
}
}

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.

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_json creates a neutral document.
  • cadkit_document_to_dgn accepts seed bytes and optional Rust WriteOptions JSON, returning a pointer and byte length. Release with cadkit_bytes_free; never pass the binary buffer to cadkit_string_free.
  • cadkit_document_to_citygml accepts an explicit CRS and LoD, returning a UTF-8 string to release with cadkit_string_free.
  • cadkit_document_to_citygml_with_report returns JSON {"xml": ..., "report": ...} (release with cadkit_string_free). metadata_only must be 0 (reject unsupported geometry) or 1 (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_json follows Rust dgn::StripSeedOptions JSON (every field optional; an unknown field returns CADKIT_INVALID_ARGUMENT) and options sets the read limits (NULL selects the defaults of either). Release the seed with cadkit_bytes_free and the dgn::StripSeedReport JSON with cadkit_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 a StrippedDgnSeed { seed, report_json }.
  • cadkit_citygml_read_json / cadkit_citygml_write_json expose the native CityGML tree without losing semantic relationships through neutral geometry. Write options follow Rust gml::ValidationOptions JSON.
  • cadkit_citygml_preflight_tkgm runs local structural/field preflight on native CityGML JSON for an explicit profile ("city-model-tender" or "digital-building-registration"); acceptance_verified in the returned JSON report is always false.

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, &copy) and cadkit_document_convert_units(doc, "meter", &copy) 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:

Terminal window
cmake -S crates/cadkit-capi -B build/capi -DCADKIT_LIB_DIR="$PWD/target/release" \
-DCMAKE_INSTALL_PREFIX="$PWD/build/cadkit-install"
cmake --build build/capi
ctest --test-dir build/capi --output-on-failure
cmake --install build/capi

Consumers 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.