euroscope_sys/
lib.rs

1//! Raw FFI surface for the EuroScope plugin SDK.
2//!
3//! This crate owns the C++ glue shim (`src/shim/`, compiled by `build.rs`) and
4//! exposes its flat `extern "C"` entry points to Rust. It is deliberately
5//! `unsafe` and untyped — the safe, idiomatic API lives in the `euroscope`
6//! crate, which is what application plugins should depend on.
7//!
8//! ## The two halves of the boundary
9//!
10//! * **`es_*` (module [`ffi`]):** wrappers *the shim provides*, i.e. Rust -> ES calls. One module
11//!   per EuroScope class, re-exported flat here.
12//! * **`rust_*` (see [`callbacks`]):** callbacks *the shim expects Rust to provide*, i.e. ES ->
13//!   Rust. `euroscope::register_plugin!` emits `#[no_mangle]` definitions for these; the signatures
14//!   are documented there.
15
16use std::ffi::c_void;
17
18pub mod ffi;
19pub use ffi::*;
20
21/// An opaque pointer to an EuroScope handle object (`CFlightPlan`, `CPlugIn`,
22/// `CController`, …). Only valid for as long as EuroScope says — usually the
23/// callback that produced it. The safe `euroscope` crate encodes those rules.
24pub type EsHandle = *mut c_void;
25
26/// Opaque pointer to a live `CFlightPlan`.
27pub type FlightPlanPtr = EsHandle;
28/// Opaque pointer to the shim's `CPlugIn` instance.
29pub type PluginPtr = EsHandle;
30
31/// Reference documentation for the `rust_*` symbols the shim imports. These are
32/// *defined* by `euroscope::register_plugin!` in the final `cdylib`.
33pub mod callbacks {
34    use std::ffi::{c_char, c_int, c_void};
35
36    use super::{FlightPlanPtr, PluginPtr};
37
38    /// Plugin identity handed to the shim before the `CPlugIn` base is
39    /// constructed. Layout must match `RustPluginMeta` in `shim/core.cpp`.
40    #[repr(C)]
41    pub struct RustPluginMeta {
42        pub name: *const c_char,
43        pub version: *const c_char,
44        pub author: *const c_char,
45        pub copyright: *const c_char,
46    }
47
48    /// Signature aliases, purely to document the contract.
49    pub type MetadataFn = extern "C" fn(out: *mut RustPluginMeta);
50    pub type CreateFn = extern "C" fn(plugin: PluginPtr) -> *mut c_void;
51    pub type DestroyFn = extern "C" fn(state: *mut c_void);
52    pub type OnTimerFn = extern "C" fn(state: *mut c_void, counter: c_int);
53    pub type OnFlightPlanDataUpdateFn = extern "C" fn(state: *mut c_void, fp: FlightPlanPtr);
54}
euroscope_sys/lib.rs

euroscope_sys/
lib.rs
