euroscope-sys 0.0.1

Raw FFI bindings and C++ glue shim for the EuroScope plugin SDK
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54

//! Raw FFI surface for the EuroScope plugin SDK.
//!
//! This crate owns the C++ glue shim (`src/shim/`, compiled by `build.rs`) and
//! exposes its flat `extern "C"` entry points to Rust. It is deliberately
//! `unsafe` and untyped — the safe, idiomatic API lives in the `euroscope`
//! crate, which is what application plugins should depend on.
//!
//! ## The two halves of the boundary
//!
//! * **`es_*` (module [`ffi`]):** wrappers *the shim provides*, i.e. Rust -> ES calls. One module
//!   per EuroScope class, re-exported flat here.
//! * **`rust_*` (see [`callbacks`]):** callbacks *the shim expects Rust to provide*, i.e. ES ->
//!   Rust. `euroscope::register_plugin!` emits `#[no_mangle]` definitions for these; the signatures
//!   are documented there.

use std::ffi::c_void;

pub mod ffi;
pub use ffi::*;

/// An opaque pointer to an EuroScope handle object (`CFlightPlan`, `CPlugIn`,
/// `CController`, …). Only valid for as long as EuroScope says — usually the
/// callback that produced it. The safe `euroscope` crate encodes those rules.
pub type EsHandle = *mut c_void;

/// Opaque pointer to a live `CFlightPlan`.
pub type FlightPlanPtr = EsHandle;
/// Opaque pointer to the shim's `CPlugIn` instance.
pub type PluginPtr = EsHandle;

/// Reference documentation for the `rust_*` symbols the shim imports. These are
/// *defined* by `euroscope::register_plugin!` in the final `cdylib`.
pub mod callbacks {
    use std::ffi::{c_char, c_int, c_void};

    use super::{FlightPlanPtr, PluginPtr};

    /// Plugin identity handed to the shim before the `CPlugIn` base is
    /// constructed. Layout must match `RustPluginMeta` in `shim/core.cpp`.
    #[repr(C)]
    pub struct RustPluginMeta {
        pub name: *const c_char,
        pub version: *const c_char,
        pub author: *const c_char,
        pub copyright: *const c_char,
    }

    /// Signature aliases, purely to document the contract.
    pub type MetadataFn = extern "C" fn(out: *mut RustPluginMeta);
    pub type CreateFn = extern "C" fn(plugin: PluginPtr) -> *mut c_void;
    pub type DestroyFn = extern "C" fn(state: *mut c_void);
    pub type OnTimerFn = extern "C" fn(state: *mut c_void, counter: c_int);
    pub type OnFlightPlanDataUpdateFn = extern "C" fn(state: *mut c_void, fp: FlightPlanPtr);
}