adamo_sys/

lib.rs

//! Raw FFI bindings to the Adamo SDK.
//!
//! This crate is a thin, `unsafe` interface — prefer the safe wrappers in
//! [`adamo`](https://docs.rs/adamo) for normal use.
//!
//! All declarations match the C header generated by `cbindgen` for the
//! `adamo-c` crate (`include/adamo/adamo.h`). Keep them in sync.

#![allow(non_camel_case_types)]
#![allow(clippy::missing_safety_doc)]

use std::os::raw::{c_char, c_int, c_void};

pub type adamo_protocol_t = u32;
pub const ADAMO_PROTOCOL_UDP: adamo_protocol_t = 0;
pub const ADAMO_PROTOCOL_QUIC: adamo_protocol_t = 1;
pub const ADAMO_PROTOCOL_TCP: adamo_protocol_t = 2;

pub type adamo_regime_t = u32;
pub const ADAMO_REGIME_STABLE: adamo_regime_t = 0;
pub const ADAMO_REGIME_DEGRADING: adamo_regime_t = 1;
pub const ADAMO_REGIME_VOLATILE: adamo_regime_t = 2;
pub const ADAMO_REGIME_RECOVERING: adamo_regime_t = 3;

pub type adamo_video_backend_t = i32;
pub const ADAMO_VIDEO_BACKEND_AUTO: adamo_video_backend_t = 0;
pub const ADAMO_VIDEO_BACKEND_GSTREAMER: adamo_video_backend_t = 1;
pub const ADAMO_VIDEO_BACKEND_HW_PIPELINE: adamo_video_backend_t = 2;

// Opaque handles. Zero-sized placeholders — callers only ever see pointers
// to them. `PhantomData<*mut ()>` keeps them `!Send + !Sync` by default;
// the safe wrapper re-asserts thread-safety where the C API documents it.
#[repr(C)]
pub struct adamo_session_t {
    _priv: [u8; 0],
    _marker: core::marker::PhantomData<(*mut u8, core::marker::PhantomPinned)>,
}
#[repr(C)]
pub struct adamo_publisher_t {
    _priv: [u8; 0],
    _marker: core::marker::PhantomData<(*mut u8, core::marker::PhantomPinned)>,
}
#[repr(C)]
pub struct adamo_subscriber_t {
    _priv: [u8; 0],
    _marker: core::marker::PhantomData<(*mut u8, core::marker::PhantomPinned)>,
}
#[repr(C)]
pub struct adamo_cb_sub_t {
    _priv: [u8; 0],
    _marker: core::marker::PhantomData<(*mut u8, core::marker::PhantomPinned)>,
}
#[repr(C)]
pub struct adamo_liveliness_token_t {
    _priv: [u8; 0],
    _marker: core::marker::PhantomData<(*mut u8, core::marker::PhantomPinned)>,
}
#[repr(C)]
pub struct adamo_liveliness_sub_t {
    _priv: [u8; 0],
    _marker: core::marker::PhantomData<(*mut u8, core::marker::PhantomPinned)>,
}
#[repr(C)]
pub struct adamo_state_t {
    _priv: [u8; 0],
    _marker: core::marker::PhantomData<(*mut u8, core::marker::PhantomPinned)>,
}
#[repr(C)]
pub struct adamo_task_runner_t {
    _priv: [u8; 0],
    _marker: core::marker::PhantomData<(*mut u8, core::marker::PhantomPinned)>,
}
#[repr(C)]
pub struct adamo_robot_t {
    _priv: [u8; 0],
    _marker: core::marker::PhantomData<(*mut u8, core::marker::PhantomPinned)>,
}
#[repr(C)]
pub struct adamo_video_track_t {
    _priv: [u8; 0],
    _marker: core::marker::PhantomData<(*mut u8, core::marker::PhantomPinned)>,
}

#[repr(C)]
pub struct adamo_sample_t {
    pub key: *mut c_char,
    pub payload: *mut u8,
    pub payload_len: usize,
    pub is_delete: i32,
    pub timestamp_us: u64,
}

#[repr(C)]
pub struct adamo_latency_stats_t {
    pub regime: adamo_regime_t,
    pub jitter_hint_ms: f32,
    pub garch_sigma_ms: f32,
    pub target_bitrate_kbps: u32,
    pub loss_rate: f32,
    pub queuing_delay_ms: f32,
    pub timestamp_ms: u64,
}

#[repr(C)]
#[derive(Clone, Copy)]
pub struct adamo_video_options_t {
    pub width: u32,
    pub height: u32,
    pub pixel_format: *const c_char,
    pub codec: *const c_char,
    pub encoder: *const c_char,
    pub bitrate_kbps: u32,
    pub adaptive_bitrate: i32,
    pub min_bitrate_kbps: u32,
    pub max_bitrate_kbps: u32,
    pub bitrate_priority: f32,
    pub fps: u32,
    pub keyframe_distance: f64,
    pub stereo: i32,
    pub backend: adamo_video_backend_t,
    /// Optional iceoryx2 service name to also publish every raw captured
    /// frame to (V4L2 tracks only; null = disabled).
    pub shm_publish: *const c_char,
    /// Per-track video protocol (null = adamo default).
    pub reliability: *const c_char,
    /// Forward an already-encoded H.264/H.265 bitstream without re-encoding
    /// (0 = off). Appended last to keep prior field offsets ABI-stable.
    pub passthrough: i32,
}

pub type adamo_sample_cb_t =
    Option<unsafe extern "C" fn(sample: *const adamo_sample_t, user: *mut c_void)>;
pub type adamo_liveliness_cb_t =
    Option<unsafe extern "C" fn(key: *const c_char, alive: c_int, user: *mut c_void)>;

// docs.rs builds can't link libadamo; stub the extern block out there so
// rustdoc still succeeds.
#[cfg(not(docsrs))]
unsafe extern "C" {
    pub fn adamo_last_error() -> *const c_char;

    /// Category of the last error on this thread. 0 = OK, 1 = auth,
    /// 2 = network, 3 = timeout, 4 = invalid argument, 5 = video,
    /// 6 = internal. Stable across releases.
    pub fn adamo_last_error_code() -> core::ffi::c_int;

    pub fn adamo_sample_free(sample: *mut adamo_sample_t);

    pub fn adamo_open(api_key: *const c_char, protocol: adamo_protocol_t) -> *mut adamo_session_t;
    pub fn adamo_open_default(api_key: *const c_char) -> *mut adamo_session_t;
    pub fn adamo_open_mtls(
        api_key: *const c_char,
        protocol: adamo_protocol_t,
    ) -> *mut adamo_session_t;
    pub fn adamo_session_free(sess: *mut adamo_session_t);
    pub fn adamo_session_org(sess: *const adamo_session_t) -> *const c_char;
    pub fn adamo_session_org_len(sess: *const adamo_session_t) -> usize;

    pub fn adamo_put(
        sess: *const adamo_session_t,
        key: *const c_char,
        payload: *const u8,
        payload_len: usize,
        priority: u8,
        express: i32,
    ) -> i32;

    pub fn adamo_publisher(
        sess: *const adamo_session_t,
        key: *const c_char,
        priority: u8,
        express: i32,
        reliable: i32,
    ) -> *mut adamo_publisher_t;
    pub fn adamo_publisher_put(
        pub_: *const adamo_publisher_t,
        payload: *const u8,
        payload_len: usize,
    ) -> i32;
    pub fn adamo_publisher_free(pub_: *mut adamo_publisher_t);

    pub fn adamo_subscribe(
        sess: *const adamo_session_t,
        key: *const c_char,
    ) -> *mut adamo_subscriber_t;
    pub fn adamo_sub_recv(
        sub: *const adamo_subscriber_t,
        timeout_ms: u64,
    ) -> *mut adamo_sample_t;
    pub fn adamo_sub_try_recv(sub: *const adamo_subscriber_t) -> *mut adamo_sample_t;
    pub fn adamo_sub_free(sub: *mut adamo_subscriber_t);

    pub fn adamo_subscribe_cb(
        sess: *const adamo_session_t,
        key: *const c_char,
        cb: adamo_sample_cb_t,
        user: *mut c_void,
    ) -> *mut adamo_cb_sub_t;
    pub fn adamo_cb_sub_free(sub: *mut adamo_cb_sub_t);

    pub fn adamo_get(
        sess: *const adamo_session_t,
        key: *const c_char,
        timeout_ms: u64,
        count_out: *mut usize,
    ) -> *mut *mut adamo_sample_t;
    pub fn adamo_get_replies_free(replies: *mut *mut adamo_sample_t, count: usize);

    pub fn adamo_state_declare(
        sess: *const adamo_session_t,
        robot: *const c_char,
    ) -> *mut adamo_state_t;
    pub fn adamo_state_set(
        state: *const adamo_state_t,
        key: *const c_char,
        payload: *const u8,
        payload_len: usize,
    ) -> i32;
    pub fn adamo_state_get(
        state: *const adamo_state_t,
        key: *const c_char,
        out_payload: *mut *mut u8,
        out_len: *mut usize,
    ) -> i32;
    pub fn adamo_state_delete(state: *const adamo_state_t, key: *const c_char) -> i32;
    pub fn adamo_state_bytes_free(payload: *mut u8, payload_len: usize);
    pub fn adamo_state_free(state: *mut adamo_state_t);

    pub fn adamo_task_runner_declare(
        sess: *const adamo_session_t,
        robot: *const c_char,
    ) -> *mut adamo_task_runner_t;
    pub fn adamo_task_runner_select(
        runner: *const adamo_task_runner_t,
        task_set_id: *const c_char,
        name: *const c_char,
        ids: *const *const c_char,
        names: *const *const c_char,
        count: usize,
    ) -> i32;
    pub fn adamo_task_runner_advance(runner: *const adamo_task_runner_t) -> i32;
    pub fn adamo_task_runner_reset(runner: *const adamo_task_runner_t) -> i32;
    pub fn adamo_task_runner_free(runner: *mut adamo_task_runner_t);

    pub fn adamo_liveliness_declare(
        sess: *const adamo_session_t,
        token_key: *const c_char,
    ) -> *mut adamo_liveliness_token_t;
    pub fn adamo_liveliness_token_free(tok: *mut adamo_liveliness_token_t);
    pub fn adamo_liveliness_get(
        sess: *const adamo_session_t,
        pattern: *const c_char,
        count_out: *mut usize,
    ) -> *mut *mut c_char;
    pub fn adamo_liveliness_tokens_free(tokens: *mut *mut c_char, count: usize);
    pub fn adamo_liveliness_subscribe(
        sess: *const adamo_session_t,
        pattern: *const c_char,
        history: c_int,
        cb: adamo_liveliness_cb_t,
        user: *mut c_void,
    ) -> *mut adamo_liveliness_sub_t;
    pub fn adamo_liveliness_sub_free(sub: *mut adamo_liveliness_sub_t);

    pub fn adamo_robot_new(
        api_key: *const c_char,
        name: *const c_char,
        protocol: adamo_protocol_t,
    ) -> *mut adamo_robot_t;
    pub fn adamo_robot_new_default(
        api_key: *const c_char,
        name: *const c_char,
    ) -> *mut adamo_robot_t;
    pub fn adamo_video_options_default() -> adamo_video_options_t;
    pub fn adamo_robot_video(
        robot: *mut adamo_robot_t,
        name: *const c_char,
        width: u32,
        height: u32,
        pixel_format: *const c_char,
        fps: u32,
        bitrate_kbps: u32,
        stereo: bool,
    ) -> *mut adamo_video_track_t;
    pub fn adamo_robot_video_with_options(
        robot: *mut adamo_robot_t,
        name: *const c_char,
        width: u32,
        height: u32,
        pixel_format: *const c_char,
        fps: u32,
        bitrate_kbps: u32,
        stereo: bool,
        encoder: *const c_char,
        hw_pipeline: bool,
    ) -> *mut adamo_video_track_t;
    pub fn adamo_robot_video_configured(
        robot: *mut adamo_robot_t,
        name: *const c_char,
        opts: *const adamo_video_options_t,
    ) -> *mut adamo_video_track_t;
    pub fn adamo_robot_attach_video_v4l2(
        robot: *mut adamo_robot_t,
        name: *const c_char,
        device: *const c_char,
        width: u32,
        height: u32,
        fps: u32,
        bitrate_kbps: u32,
        stereo: bool,
    ) -> i32;
    pub fn adamo_robot_attach_video_v4l2_configured(
        robot: *mut adamo_robot_t,
        name: *const c_char,
        device: *const c_char,
        opts: *const adamo_video_options_t,
    ) -> i32;
    pub fn adamo_robot_attach_video_gst(
        robot: *mut adamo_robot_t,
        name: *const c_char,
        pipeline: *const c_char,
        width: u32,
        height: u32,
        fps: u32,
        bitrate_kbps: u32,
        stereo: bool,
    ) -> i32;
    pub fn adamo_robot_attach_video_gst_with_format(
        robot: *mut adamo_robot_t,
        name: *const c_char,
        pipeline: *const c_char,
        width: u32,
        height: u32,
        fps: u32,
        bitrate_kbps: u32,
        stereo: bool,
        source_format: *const c_char,
    ) -> i32;
    pub fn adamo_robot_attach_video_gst_configured(
        robot: *mut adamo_robot_t,
        name: *const c_char,
        pipeline: *const c_char,
        opts: *const adamo_video_options_t,
    ) -> i32;
    pub fn adamo_robot_attach_video_shm(
        robot: *mut adamo_robot_t,
        name: *const c_char,
        service: *const c_char,
        width: u32,
        height: u32,
        pixel_format: *const c_char,
        fps: u32,
        bitrate_kbps: u32,
        stereo: bool,
    ) -> i32;
    pub fn adamo_robot_attach_video_shm_configured(
        robot: *mut adamo_robot_t,
        name: *const c_char,
        service: *const c_char,
        opts: *const adamo_video_options_t,
    ) -> i32;
    pub fn adamo_video_track_send(
        track: *mut adamo_video_track_t,
        payload: *const u8,
        payload_len: usize,
    ) -> i32;
    pub fn adamo_video_track_free(track: *mut adamo_video_track_t);
    pub fn adamo_robot_run(robot: *mut adamo_robot_t) -> i32;
    pub fn adamo_robot_free(robot: *mut adamo_robot_t);

    pub fn adamo_detect_encoder() -> *const c_char;

    pub fn adamo_fabric_now_us() -> u64;
    pub fn adamo_fabric_synced() -> i32;
    pub fn adamo_relay_rtt_us(sess: *const adamo_session_t, out_us: *mut u64) -> i32;

    pub fn adamo_parse_heartbeat(
        payload: *const u8,
        payload_len: usize,
        out: *mut adamo_latency_stats_t,
    ) -> i32;
    pub fn adamo_heartbeat_topic(
        robot: *const c_char,
        out: *mut c_char,
        out_cap: usize,
    ) -> isize;
    pub fn adamo_ping_topic(
        robot: *const c_char,
        out: *mut c_char,
        out_cap: usize,
    ) -> isize;
    pub fn adamo_pong_topic(
        robot: *const c_char,
        out: *mut c_char,
        out_cap: usize,
    ) -> isize;
    pub fn adamo_measure_rtt(
        sess: *const adamo_session_t,
        robot: *const c_char,
        timeout_ms: u64,
        out_us: *mut u64,
    ) -> i32;
}

// Silence `unused_imports` if someone pulls in the crate without calling
// anything (e.g. docs builds).
#[doc(hidden)]
pub const _IMPORTS: (Option<c_int>, Option<*mut c_void>) = (None, None);