Crate pamoja_ffi 

The curated C ABI surface for the pamoja SDK.

This crate exposes a small, hand-written extern "C" API over [pamoja_core] and the capability crates so that languages without a native Rust bridge - C, C++, and C#/.NET through P/Invoke - can drive the SDK. It is deliberately the project’s single auditable unsafe boundary: every raw pointer is dereferenced here and nowhere else.

The committed header include/pamoja.h is generated from this source by cbindgen (see build.rs) and is drift-checked in CI, so the C contract can never fall behind the Rust surface.

Conventions

• Fallible calls return a PamojaStatus code. On any non-Ok result a human-readable message is stored for the calling thread and can be read with pamoja_last_error_message.
• Handles are opaque, heap-allocated, and owned by the caller, who must release each with its matching *_free function.
• All strings crossing the boundary are UTF-8. Inputs are borrowed for the duration of the call; returned pointers document their own lifetime.

Choosing what the library carries

Every capability is a cargo feature, all on by default, so a host that builds this crate itself gets the same “compile only what you use” property a Rust consumer has, and it is worth using. The seven capabilities that need an async runtime (mqtt, coap, loopback, sync, ladder, bus, and sim) carry Tokio and the network stacks with them, and are about half the compiled library on their own: dropping just those, keeping every other capability, took a release build from 2.07 MB to 1.01 MB. A host that only decodes protocol bytes can go much further, to 0.41 MB:

cargo build --release -p pamoja-ffi --no-default-features \
  --features "modbus,can,serial,gpio,sensors,codec,security"

Those figures are one x86_64-pc-windows-msvc build and will differ per platform; cargo xtask builds reports the sizes on the machine at hand. The Node, Python, and .NET packages ship the full default build regardless, because their package managers cannot express the choice per consumer.

Modules

actuators

The C ABI for the actuator drivers.

audit

The C ABI for tamper-evident audit logs.

bus

The C ABI for the in-process event bus.

can

The C ABI for CAN bus framing.

coap

The C ABI for CoAP.

codec

The C ABI for wire formats and metered-link packing.

gpio

The C ABI for on-board bus addressing and pin logic.

kit

The C ABI for the goal-named helper math.

ladder

The C ABI for the cost-aware transport ladder.

loopback

The C ABI for the in-process loopback broker.

lora

The C ABI for LoRa link math.

lora_region

The C ABI for LoRaWAN regional channel plans.

lorawan

The C ABI for LoRaWAN 1.0.x MAC framing.

mavlink

The C ABI for the MAVLink wire protocol.

mavlink_protocol

The C ABI for the MAVLink service protocols: mission transfer, commands, and offboard setpoints.

mavlink_schema

The C ABI for MAVLink message shapes: reading and writing a message by field name.

mesh

The C ABI for mesh packet framing.

modbus

The C ABI for Modbus RTU framing.

mqtt

The C ABI for the MQTT transport.

power

The C ABI for power-aware scheduling.

profile

The C ABI for device profiles.

ros2

The C ABI for the ROS 2 naming and encoding rules.

routing

The C ABI for cost-aware mesh routing.

security

The C ABI for device identity and signed telemetry.

sensors

The C ABI for the sensor drivers.

serial

The C ABI for serial-line packet framing.

session

The C ABI for encrypted, authenticated sessions.

sim

The C ABI for simulated devices.

sync

The C ABI for store-and-forward buffers.

telemetry

The C ABI for device-side telemetry.

transport

The C ABI for composing transports.

update

The C ABI for signed firmware updates.

zenoh

The C ABI for Zenoh key expressions.

Structs

PamojaBuffer

An opaque handle to a byte buffer owned by the caller.

PamojaString

An owned, null-terminated UTF-8 string produced by the library.

Enums

PamojaStatus

The result of a fallible pamoja call.

Functions

pamoja_buffer_data^⚠

Returns a pointer to a buffer’s bytes.

pamoja_buffer_free^⚠

Releases a buffer handle.

pamoja_buffer_len^⚠

Returns the length in bytes of a buffer.

pamoja_last_error_message

Returns the calling thread’s most recent error message, or null if none.

pamoja_string_data^⚠

Returns a pointer to a string’s bytes.

pamoja_string_free^⚠

Releases a string handle.

pamoja_string_len^⚠

Returns the length in bytes of a string, excluding its null terminator.

pamoja_version

Returns the version string of the native pamoja library.