docs.rs failed to build zerodds-c-api-1.0.0-rc.3
Please check the build logs for more information.
See Builds for ideas on how to fix a failed build, or Metadata for how to configure docs.rs builds.
If you believe this is docs.rs' fault, open an issue.

`zerodds-c-api`

ZeroDDS C-FFI — cross-language hub for C, C++, C# and TypeScript. Exports an extern "C" layer over the ZeroDDS DCPS runtime that all non-Rust bindings use as a common binary interface.

Part of the ZeroDDS project. Safety class STANDARD — unsafe allowed at the FFI boundary, every block carries a // SAFETY: comment; internal code is unsafe-free.

Who docks here

Binding	Path to the crate	Mechanism
Pure C	direct	`#include <zerodds.h>` + `-lzerodds`
C++17 RAII wrapper	`crates/cpp`	`#include <zerodds/dds.hpp>` over the C-API
C# (P/Invoke, NativeAOT)	`crates/cs`	`DllImport("zerodds")`
TypeScript / Node.js	`crates/ts-node`	koffi FFI over `libzerodds.so`
ROS-2 RMW shim	`crates/rmw-zerodds-shim`	Apex.AI plugin model

Python (crates/py) and Java (crates/java-omgdds) do not go over the C-API — they use pyo3 / jni-rs direct bridges into the Rust stack.

Quick start — pure C

zerodds.h is generated by cbindgen from the Rust source (see build.rs) and checked in at include/zerodds.h.

#include <stdio.h>
#include <zerodds.h>

int main(void) {
    zerodds_runtime_t* rt = zerodds_runtime_create();
    zerodds_participant_t* p =
        zerodds_runtime_create_participant(rt, /* domain_id */ 0);

    zerodds_topic_t* t =
        zerodds_participant_create_topic(p, "Greetings", "Greeting");

    zerodds_writer_t* w = zerodds_participant_create_writer(p, t);
    uint8_t payload[] = { /* CDR-encoded "Greeting{id:42,text:'hi'}" */ };
    zerodds_writer_write(w, payload, sizeof(payload));

    zerodds_writer_destroy(w);
    zerodds_topic_destroy(t);
    zerodds_participant_destroy(p);
    zerodds_runtime_destroy(rt);
    return 0;
}

Build (Linux/macOS, with a built libzerodds.so on the LD_LIBRARY_PATH):

clang -std=c11 -lzerodds main.c -o demo
./demo

Type model — deliberately byte-oriented

The FFI takes raw CDR bytes for all samples:

zerodds_writer_write(writer, sample_bytes, sample_len);
zerodds_reader_take(reader, &out_buf, &out_len, ...);  // out_buf via _free()

The CDR encode/decode logic lives in the language bindings: idl-cpp emits a C++ encoder, idl-csharp a C# encoder, etc. The C-FFI is neutral — wire-drift tests pass byte-exactly.

Advantages:

No generic-type acrobatics across the FFI boundary.
The Apex.AI plugin and ROS-2 RMW keep their own marshaling paths.
Wire-vector conformance is trivial to validate.

Handle model

All objects are opaque pointers. Callers must pair *_destroy():

Constructor	Paired destructor
`zerodds_runtime_create()`	`zerodds_runtime_destroy()`
`zerodds_participant_create()`	`zerodds_participant_destroy()`
`zerodds_writer_create()`	`zerodds_writer_destroy()` — before the participant
`zerodds_reader_take()` (buffer)	`zerodds_buffer_free()`

Memory ownership is explicitly documented in include/zerodds.h and tested against Apex.AI plugin conformance.

Spec mapping

Spec document	Section
ZeroDDS C-API 1.0 (vendor spec)	`docs/spec-coverage/zerodds-c-api-1.0.md`
OMG DDSI-RTPS 2.5	§8 — wire format
OMG DDS-XCDR2	complete CDR pipeline (byte pass-through in the FFI)

Features

default = [] — no feature needed.
Build output: cdylib (libzerodds.so), staticlib (libzerodds.a), rlib (Rust consumers).

Stability

1.0.0-rc.2. The ABI is stable from 1.0.0-final; until then symbol renames or handle-type changes are possible (every break is marked in the CHANGELOG).

Tests

cargo test -p zerodds-c-api

Plus cross-vendor conformance against Cyclone DDS / Fast-DDS in crates/discovery/tests/cyclone_*.rs.

zerodds-c-api 1.0.0-rc.3