adamo_sys/
lib.rs

1//! Raw FFI bindings to the Adamo SDK.
2//!
3//! This crate is a thin, `unsafe` interface — prefer the safe wrappers in
4//! [`adamo`](https://docs.rs/adamo) for normal use.
5//!
6//! All declarations match the C header generated by `cbindgen` for the
7//! `adamo-c` crate (`include/adamo/adamo.h`). Keep them in sync.
8
9#![allow(non_camel_case_types)]
10#![allow(clippy::missing_safety_doc)]
11
12use std::os::raw::{c_char, c_int, c_void};
13
14pub type adamo_protocol_t = u32;
15pub const ADAMO_PROTOCOL_UDP: adamo_protocol_t = 0;
16pub const ADAMO_PROTOCOL_QUIC: adamo_protocol_t = 1;
17pub const ADAMO_PROTOCOL_TCP: adamo_protocol_t = 2;
18
19pub type adamo_regime_t = u32;
20pub const ADAMO_REGIME_STABLE: adamo_regime_t = 0;
21pub const ADAMO_REGIME_DEGRADING: adamo_regime_t = 1;
22pub const ADAMO_REGIME_VOLATILE: adamo_regime_t = 2;
23pub const ADAMO_REGIME_RECOVERING: adamo_regime_t = 3;
24
25pub type adamo_video_backend_t = i32;
26pub const ADAMO_VIDEO_BACKEND_AUTO: adamo_video_backend_t = 0;
27pub const ADAMO_VIDEO_BACKEND_GSTREAMER: adamo_video_backend_t = 1;
28pub const ADAMO_VIDEO_BACKEND_HW_PIPELINE: adamo_video_backend_t = 2;
29
30// Opaque handles. Zero-sized placeholders — callers only ever see pointers
31// to them. `PhantomData<*mut ()>` keeps them `!Send + !Sync` by default;
32// the safe wrapper re-asserts thread-safety where the C API documents it.
33#[repr(C)]
34pub struct adamo_session_t {
35    _priv: [u8; 0],
36    _marker: core::marker::PhantomData<(*mut u8, core::marker::PhantomPinned)>,
37}
38#[repr(C)]
39pub struct adamo_publisher_t {
40    _priv: [u8; 0],
41    _marker: core::marker::PhantomData<(*mut u8, core::marker::PhantomPinned)>,
42}
43#[repr(C)]
44pub struct adamo_subscriber_t {
45    _priv: [u8; 0],
46    _marker: core::marker::PhantomData<(*mut u8, core::marker::PhantomPinned)>,
47}
48#[repr(C)]
49pub struct adamo_cb_sub_t {
50    _priv: [u8; 0],
51    _marker: core::marker::PhantomData<(*mut u8, core::marker::PhantomPinned)>,
52}
53#[repr(C)]
54pub struct adamo_liveliness_token_t {
55    _priv: [u8; 0],
56    _marker: core::marker::PhantomData<(*mut u8, core::marker::PhantomPinned)>,
57}
58#[repr(C)]
59pub struct adamo_liveliness_sub_t {
60    _priv: [u8; 0],
61    _marker: core::marker::PhantomData<(*mut u8, core::marker::PhantomPinned)>,
62}
63#[repr(C)]
64pub struct adamo_state_t {
65    _priv: [u8; 0],
66    _marker: core::marker::PhantomData<(*mut u8, core::marker::PhantomPinned)>,
67}
68#[repr(C)]
69pub struct adamo_task_runner_t {
70    _priv: [u8; 0],
71    _marker: core::marker::PhantomData<(*mut u8, core::marker::PhantomPinned)>,
72}
73#[repr(C)]
74pub struct adamo_robot_t {
75    _priv: [u8; 0],
76    _marker: core::marker::PhantomData<(*mut u8, core::marker::PhantomPinned)>,
77}
78#[repr(C)]
79pub struct adamo_video_track_t {
80    _priv: [u8; 0],
81    _marker: core::marker::PhantomData<(*mut u8, core::marker::PhantomPinned)>,
82}
83
84#[repr(C)]
85pub struct adamo_sample_t {
86    pub key: *mut c_char,
87    pub payload: *mut u8,
88    pub payload_len: usize,
89    pub is_delete: i32,
90    pub timestamp_us: u64,
91}
92
93#[repr(C)]
94pub struct adamo_latency_stats_t {
95    pub regime: adamo_regime_t,
96    pub jitter_hint_ms: f32,
97    pub garch_sigma_ms: f32,
98    pub target_bitrate_kbps: u32,
99    pub loss_rate: f32,
100    pub queuing_delay_ms: f32,
101    pub timestamp_ms: u64,
102}
103
104#[repr(C)]
105#[derive(Clone, Copy)]
106pub struct adamo_video_options_t {
107    pub width: u32,
108    pub height: u32,
109    pub pixel_format: *const c_char,
110    pub codec: *const c_char,
111    pub encoder: *const c_char,
112    pub bitrate_kbps: u32,
113    pub adaptive_bitrate: i32,
114    pub min_bitrate_kbps: u32,
115    pub max_bitrate_kbps: u32,
116    pub bitrate_priority: f32,
117    pub fps: u32,
118    pub keyframe_distance: f64,
119    pub stereo: i32,
120    pub backend: adamo_video_backend_t,
121    /// Optional iceoryx2 service name to also publish every raw captured
122    /// frame to (V4L2 tracks only; null = disabled).
123    pub shm_publish: *const c_char,
124    /// Per-track video protocol (null = adamo default).
125    pub reliability: *const c_char,
126    /// Forward an already-encoded H.264/H.265 bitstream without re-encoding
127    /// (0 = off). Appended last to keep prior field offsets ABI-stable.
128    pub passthrough: i32,
129    /// Keep the robot running when this track fails (0 = required/default).
130    /// Appended last to keep prior field offsets ABI-stable.
131    pub allow_missing: i32,
132}
133
134pub type adamo_sample_cb_t =
135    Option<unsafe extern "C" fn(sample: *const adamo_sample_t, user: *mut c_void)>;
136pub type adamo_liveliness_cb_t =
137    Option<unsafe extern "C" fn(key: *const c_char, alive: c_int, user: *mut c_void)>;
138
139// docs.rs builds can't link libadamo; stub the extern block out there so
140// rustdoc still succeeds.
141#[cfg(not(docsrs))]
142unsafe extern "C" {
143    pub fn adamo_last_error() -> *const c_char;
144
145    /// Category of the last error on this thread. 0 = OK, 1 = auth,
146    /// 2 = network, 3 = timeout, 4 = invalid argument, 5 = video,
147    /// 6 = internal. Stable across releases.
148    pub fn adamo_last_error_code() -> core::ffi::c_int;
149    pub fn adamo_last_stream_error_code() -> *const c_char;
150    pub fn adamo_last_stream_error_stage() -> *const c_char;
151    pub fn adamo_last_stream_error_track() -> *const c_char;
152    pub fn adamo_last_stream_error_backend() -> *const c_char;
153    pub fn adamo_last_stream_error_source() -> *const c_char;
154
155    pub fn adamo_sample_free(sample: *mut adamo_sample_t);
156
157    pub fn adamo_open(api_key: *const c_char, protocol: adamo_protocol_t) -> *mut adamo_session_t;
158    pub fn adamo_open_default(api_key: *const c_char) -> *mut adamo_session_t;
159    pub fn adamo_open_mtls(
160        api_key: *const c_char,
161        protocol: adamo_protocol_t,
162    ) -> *mut adamo_session_t;
163    pub fn adamo_session_free(sess: *mut adamo_session_t);
164    pub fn adamo_session_org(sess: *const adamo_session_t) -> *const c_char;
165    pub fn adamo_session_org_len(sess: *const adamo_session_t) -> usize;
166
167    pub fn adamo_put(
168        sess: *const adamo_session_t,
169        key: *const c_char,
170        payload: *const u8,
171        payload_len: usize,
172        priority: u8,
173        express: i32,
174    ) -> i32;
175
176    pub fn adamo_publisher(
177        sess: *const adamo_session_t,
178        key: *const c_char,
179        priority: u8,
180        express: i32,
181        reliable: i32,
182    ) -> *mut adamo_publisher_t;
183    pub fn adamo_publisher_put(
184        pub_: *const adamo_publisher_t,
185        payload: *const u8,
186        payload_len: usize,
187    ) -> i32;
188    pub fn adamo_publisher_free(pub_: *mut adamo_publisher_t);
189
190    pub fn adamo_subscribe(
191        sess: *const adamo_session_t,
192        key: *const c_char,
193    ) -> *mut adamo_subscriber_t;
194    pub fn adamo_sub_recv(
195        sub: *const adamo_subscriber_t,
196        timeout_ms: u64,
197    ) -> *mut adamo_sample_t;
198    pub fn adamo_sub_try_recv(sub: *const adamo_subscriber_t) -> *mut adamo_sample_t;
199    pub fn adamo_sub_free(sub: *mut adamo_subscriber_t);
200
201    pub fn adamo_subscribe_cb(
202        sess: *const adamo_session_t,
203        key: *const c_char,
204        cb: adamo_sample_cb_t,
205        user: *mut c_void,
206    ) -> *mut adamo_cb_sub_t;
207    pub fn adamo_cb_sub_free(sub: *mut adamo_cb_sub_t);
208
209    pub fn adamo_get(
210        sess: *const adamo_session_t,
211        key: *const c_char,
212        timeout_ms: u64,
213        count_out: *mut usize,
214    ) -> *mut *mut adamo_sample_t;
215    pub fn adamo_get_replies_free(replies: *mut *mut adamo_sample_t, count: usize);
216
217    pub fn adamo_state_declare(
218        sess: *const adamo_session_t,
219        robot: *const c_char,
220    ) -> *mut adamo_state_t;
221    pub fn adamo_state_set(
222        state: *const adamo_state_t,
223        key: *const c_char,
224        payload: *const u8,
225        payload_len: usize,
226    ) -> i32;
227    pub fn adamo_state_get(
228        state: *const adamo_state_t,
229        key: *const c_char,
230        out_payload: *mut *mut u8,
231        out_len: *mut usize,
232    ) -> i32;
233    pub fn adamo_state_delete(state: *const adamo_state_t, key: *const c_char) -> i32;
234    pub fn adamo_state_bytes_free(payload: *mut u8, payload_len: usize);
235    pub fn adamo_state_free(state: *mut adamo_state_t);
236
237    pub fn adamo_task_runner_declare(
238        sess: *const adamo_session_t,
239        robot: *const c_char,
240    ) -> *mut adamo_task_runner_t;
241    pub fn adamo_task_runner_select(
242        runner: *const adamo_task_runner_t,
243        task_set_id: *const c_char,
244        name: *const c_char,
245        ids: *const *const c_char,
246        names: *const *const c_char,
247        count: usize,
248    ) -> i32;
249    pub fn adamo_task_runner_advance(runner: *const adamo_task_runner_t) -> i32;
250    pub fn adamo_task_runner_reset(runner: *const adamo_task_runner_t) -> i32;
251    pub fn adamo_task_runner_free(runner: *mut adamo_task_runner_t);
252
253    pub fn adamo_liveliness_declare(
254        sess: *const adamo_session_t,
255        token_key: *const c_char,
256    ) -> *mut adamo_liveliness_token_t;
257    pub fn adamo_liveliness_token_free(tok: *mut adamo_liveliness_token_t);
258    pub fn adamo_liveliness_get(
259        sess: *const adamo_session_t,
260        pattern: *const c_char,
261        count_out: *mut usize,
262    ) -> *mut *mut c_char;
263    pub fn adamo_liveliness_tokens_free(tokens: *mut *mut c_char, count: usize);
264    pub fn adamo_liveliness_subscribe(
265        sess: *const adamo_session_t,
266        pattern: *const c_char,
267        history: c_int,
268        cb: adamo_liveliness_cb_t,
269        user: *mut c_void,
270    ) -> *mut adamo_liveliness_sub_t;
271    pub fn adamo_liveliness_sub_free(sub: *mut adamo_liveliness_sub_t);
272
273    pub fn adamo_robot_new(
274        api_key: *const c_char,
275        name: *const c_char,
276        protocol: adamo_protocol_t,
277    ) -> *mut adamo_robot_t;
278    pub fn adamo_robot_new_default(
279        api_key: *const c_char,
280        name: *const c_char,
281    ) -> *mut adamo_robot_t;
282    pub fn adamo_video_options_default() -> adamo_video_options_t;
283    pub fn adamo_robot_video(
284        robot: *mut adamo_robot_t,
285        name: *const c_char,
286        width: u32,
287        height: u32,
288        pixel_format: *const c_char,
289        fps: u32,
290        bitrate_kbps: u32,
291        stereo: bool,
292    ) -> *mut adamo_video_track_t;
293    pub fn adamo_robot_video_with_options(
294        robot: *mut adamo_robot_t,
295        name: *const c_char,
296        width: u32,
297        height: u32,
298        pixel_format: *const c_char,
299        fps: u32,
300        bitrate_kbps: u32,
301        stereo: bool,
302        encoder: *const c_char,
303        hw_pipeline: bool,
304    ) -> *mut adamo_video_track_t;
305    pub fn adamo_robot_video_configured(
306        robot: *mut adamo_robot_t,
307        name: *const c_char,
308        opts: *const adamo_video_options_t,
309    ) -> *mut adamo_video_track_t;
310    pub fn adamo_robot_attach_video_v4l2(
311        robot: *mut adamo_robot_t,
312        name: *const c_char,
313        device: *const c_char,
314        width: u32,
315        height: u32,
316        fps: u32,
317        bitrate_kbps: u32,
318        stereo: bool,
319    ) -> i32;
320    pub fn adamo_robot_attach_video_v4l2_configured(
321        robot: *mut adamo_robot_t,
322        name: *const c_char,
323        device: *const c_char,
324        opts: *const adamo_video_options_t,
325    ) -> i32;
326    pub fn adamo_robot_attach_video_gst(
327        robot: *mut adamo_robot_t,
328        name: *const c_char,
329        pipeline: *const c_char,
330        width: u32,
331        height: u32,
332        fps: u32,
333        bitrate_kbps: u32,
334        stereo: bool,
335    ) -> i32;
336    pub fn adamo_robot_attach_video_gst_with_format(
337        robot: *mut adamo_robot_t,
338        name: *const c_char,
339        pipeline: *const c_char,
340        width: u32,
341        height: u32,
342        fps: u32,
343        bitrate_kbps: u32,
344        stereo: bool,
345        source_format: *const c_char,
346    ) -> i32;
347    pub fn adamo_robot_attach_video_gst_configured(
348        robot: *mut adamo_robot_t,
349        name: *const c_char,
350        pipeline: *const c_char,
351        opts: *const adamo_video_options_t,
352    ) -> i32;
353    pub fn adamo_robot_attach_video_shm(
354        robot: *mut adamo_robot_t,
355        name: *const c_char,
356        service: *const c_char,
357        width: u32,
358        height: u32,
359        pixel_format: *const c_char,
360        fps: u32,
361        bitrate_kbps: u32,
362        stereo: bool,
363    ) -> i32;
364    pub fn adamo_robot_attach_video_shm_configured(
365        robot: *mut adamo_robot_t,
366        name: *const c_char,
367        service: *const c_char,
368        opts: *const adamo_video_options_t,
369    ) -> i32;
370    pub fn adamo_video_track_send(
371        track: *mut adamo_video_track_t,
372        payload: *const u8,
373        payload_len: usize,
374    ) -> i32;
375    pub fn adamo_video_track_free(track: *mut adamo_video_track_t);
376    pub fn adamo_robot_run(robot: *mut adamo_robot_t) -> i32;
377    pub fn adamo_robot_free(robot: *mut adamo_robot_t);
378
379    pub fn adamo_detect_encoder() -> *const c_char;
380
381    pub fn adamo_fabric_now_us() -> u64;
382    pub fn adamo_fabric_synced() -> i32;
383    pub fn adamo_relay_rtt_us(sess: *const adamo_session_t, out_us: *mut u64) -> i32;
384
385    pub fn adamo_parse_heartbeat(
386        payload: *const u8,
387        payload_len: usize,
388        out: *mut adamo_latency_stats_t,
389    ) -> i32;
390    pub fn adamo_heartbeat_topic(
391        robot: *const c_char,
392        out: *mut c_char,
393        out_cap: usize,
394    ) -> isize;
395    pub fn adamo_ping_topic(
396        robot: *const c_char,
397        out: *mut c_char,
398        out_cap: usize,
399    ) -> isize;
400    pub fn adamo_pong_topic(
401        robot: *const c_char,
402        out: *mut c_char,
403        out_cap: usize,
404    ) -> isize;
405    pub fn adamo_measure_rtt(
406        sess: *const adamo_session_t,
407        robot: *const c_char,
408        timeout_ms: u64,
409        out_us: *mut u64,
410    ) -> i32;
411}
412
413// Silence `unused_imports` if someone pulls in the crate without calling
414// anything (e.g. docs builds).
415#[doc(hidden)]
416pub const _IMPORTS: (Option<c_int>, Option<*mut c_void>) = (None, None);
adamo_sys/lib.rs

adamo_sys/
lib.rs
