fers_api.rs

Go to the documentation of this file.

// SPDX-License-Identifier: GPL-2.0-only
// Copyright (c) 2025-present FERS Contributors (see AUTHORS.md).
 
//! # Safe Rust FFI Wrapper for `libfers`
//!
//! This module provides a safe, idiomatic Rust interface to the `libfers` C++
//! simulation library. It bridges the gap between the raw C-style FFI (generated
//! by `bindgen`) and the higher-level Rust code used in the Tauri application.
//!
//! ## Safety Guarantees
//!
//! The module ensures the following safety properties:
//!
//! 1. **Automatic Resource Management**: All C-allocated resources (contexts, strings)
//!    are wrapped in RAII types that guarantee cleanup via `Drop`.
//! 2. **Memory Safety**: Raw pointers from C are only dereferenced within `unsafe`
//!    blocks with documented safety invariants.
//! 3. **String Conversion**: All C strings are converted to Rust `String`s with
//!    proper UTF-8 validation and null-termination handling.
//! 4. **Thread Safety**: The `FersContext` is marked as `Send + Sync` because it
//!    will be protected by a `Mutex` in the application layer.
//!
//! ## Error Handling
//!
//! All fallible operations return `Result<T, String>`, where the error string
//! contains a human-readable message retrieved from the C library's thread-local
//! error storage.
 
use std::ffi::{c_void, CStr, CString};
use std::os::raw::c_char;
use std::sync::{
    atomic::{AtomicBool, AtomicU64, Ordering},
    mpsc::Sender,
};
use tauri::{AppHandle, Emitter};
 
/// Raw FFI bindings generated by `bindgen` from `libfers/api.h`.
///
/// This inner module is kept private to prevent direct access to unsafe FFI
/// functions. It contains the raw C function declarations and opaque struct types
/// that mirror the C-API header.
///
/// # Safety
///
/// All items in this module are `unsafe` to use directly. They require:
/// * Valid, non-null pointers for all context handles.
/// * Proper null-termination for all C strings.
/// * Manual memory management (allocation/deallocation).
///
/// The parent module (`fers_api`) provides safe wrappers that enforce these invariants.
mod ffi {
    #![allow(non_upper_case_globals)]
    #![allow(non_camel_case_types)]
    #![allow(non_snake_case)]
    #![allow(dead_code)]
    include!(concat!(env!("OUT_DIR"), "/bindings.rs"));
}
 
static LOG_SEQUENCE: AtomicU64 = AtomicU64::new(1);
const FERS_RUN_CANCELLED: i32 = 2;
const VITA49_DRAIN_MESSAGE: &str = "Waiting for VITA output stream drain...";
 
#[derive(serde::Deserialize, Clone, Debug)]
pub struct Vita49StreamConfig {
    pub host: String,
    pub port: u16,
    pub fullscale: f64,
    pub epoch_unix_nanoseconds: Option<String>,
    pub max_udp_payload: u16,
    pub queue_depth: u32,
    pub trace_enabled: bool,
    pub packet_trace_ring_size: usize,
}
 
pub enum SimulationRunOutcome {
    Completed(String),
    Cancelled(String),
}
 
#[derive(Clone, Debug)]
pub struct Vita49TelemetryMessage {
    pub stats_json: Option<String>,
    pub packet_batch_json: Option<String>,
}
 
pub type Vita49TelemetrySender = Sender<Vita49TelemetryMessage>;
 
/// A smart pointer wrapper for C-allocated strings returned from `libfers`.
///
/// This type ensures that the memory allocated by the C library (via `strdup`)
/// is properly freed when the wrapper goes out of scope, preventing memory leaks.
///
/// # Memory Management
///
/// The wrapped pointer must have been allocated by a `libfers` API function that
/// transfers ownership to the caller (e.g., `fers_get_scenario_as_json`). The
/// `Drop` implementation calls `fers_free_string` to release the memory back to
/// the C allocator.
///
/// # Null Handling
///
/// If the pointer is null, the wrapper treats it as an empty string. This simplifies
/// error handling in cases where null indicates "no data" rather than an error.
struct FersOwnedString(*mut c_char);
 
impl Drop for FersOwnedString {
    /// Frees the underlying C string by calling `fers_free_string`.
    ///
    /// This is automatically invoked when the wrapper goes out of scope,
    /// ensuring that no manual cleanup is required by the caller.
    ///
    /// # Safety
    ///
    /// The pointer must have been allocated by `libfers` (typically via `strdup`)
    /// and must not have been freed already. The `Drop` trait ensures this is
    /// called exactly once per instance.
    fn drop(&mut self) {
        if !self.0.is_null() {
            // SAFETY: The pointer was allocated by `libfers` and is valid until we call `fers_free_string`.
            // We are the sole owner of this pointer.
            unsafe { ffi::fers_free_string(self.0) };
        }
    }
}
 
impl FersOwnedString {
    /// Converts the owned C string to a Rust `String`, consuming the wrapper.
    ///
    /// This method performs UTF-8 validation and copies the string data into a
    /// Rust-managed `String`. The C-allocated memory is freed after the conversion.
    ///
    /// # Returns
    ///
    /// * `Ok(String)` - The converted string if valid UTF-8.
    /// * `Err(std::str::Utf8Error)` - If the C string contains invalid UTF-8 bytes.
    ///
    /// # Example
    ///
    /// ```ignore
    /// let owned = FersOwnedString(some_c_string_ptr);
    /// match owned.into_string() {
    ///     Ok(s) => println!("Got string: {}", s),
    ///     Err(e) => eprintln!("Invalid UTF-8: {}", e),
    /// }
    /// ```
    fn into_string(self) -> Result<String, std::str::Utf8Error> {
        if self.0.is_null() {
            return Ok(String::new());
        }
        // SAFETY: `self.0` is a valid, null-terminated C string from `libfers`.
        // The `CStr::from_ptr` is safe as long as the pointer is valid.
        let c_str = unsafe { CStr::from_ptr(self.0) };
        c_str.to_str().map(|s| s.to_string())
    }
}
 
/// A safe, RAII-style wrapper for the `fers_context_t*` C handle.
///
/// This struct encapsulates the lifetime and ownership of a simulation context
/// created by the `libfers` C++ library. It ensures that:
/// * The context is created via `fers_context_create` on initialization.
/// * The context is destroyed via `fers_context_destroy` when dropped.
/// * The context is never null after successful creation.
///
/// # Thread Safety
///
/// This type implements `Send` and `Sync` because the underlying C++ context will
/// be protected by a `Mutex` in the Tauri application. The C++ `FersContext` class
/// is not thread-safe, but by serializing all access through Rust's `Mutex`, we
/// ensure that only one thread can call methods on the context at a time.
///
/// # Example
///
/// ```ignore
/// use fers_api::FersContext;
///
/// let context = FersContext::new().expect("Failed to create context");
/// context.load_scenario_from_xml_file("scenario.xml")?;
/// let json = context.get_scenario_as_json()?;
/// // Context is automatically destroyed when it goes out of scope
/// ```
pub struct FersContext {
    /// The raw pointer to the C++ context object.
    ///
    /// This must be a raw pointer because `fers_context_t` is an opaque struct.
    /// The `Send` and `Sync` traits are manually implemented because we'll wrap this
    /// context in a Mutex, ensuring that access to the non-thread-safe C++ object
    /// is properly synchronized.
    ptr: *mut ffi::fers_context_t,
}
 
// SAFETY: The FersContext will be protected by a Mutex. All C-API calls on a single
// context are not guaranteed to be thread-safe by themselves, but by enforcing
// serialized access through a Mutex, we make its usage safe across threads.
unsafe impl Send for FersContext {}
unsafe impl Sync for FersContext {}
 
impl Drop for FersContext {
    /// Destroys the underlying C++ context and frees all associated resources.
    ///
    /// This method is automatically called when the `FersContext` goes out of scope.
    /// It delegates to `fers_context_destroy`, which is responsible for cleaning up
    /// the C++ `FersContext` object and its owned `World`.
    ///
    /// # Safety
    ///
    /// The pointer must be valid and non-null. The `Drop` trait guarantees this is
    /// called exactly once, preventing double-free errors.
    fn drop(&mut self) {
        if !self.ptr.is_null() {
            // SAFETY: `self.ptr` is a valid handle created by `fers_context_create`.
            // The `Drop` trait ensures this is called exactly once.
            unsafe { ffi::fers_context_destroy(self.ptr) };
        }
    }
}
 
/// Retrieves and formats the last error message from the `libfers` C-API.
///
/// This helper function is called whenever a C-API function returns an error code.
/// It queries the thread-local error storage via `fers_get_last_error_message`,
/// converts the C string to a Rust `String`, and ensures the memory is freed.
///
/// # Returns
///
/// A human-readable error message. If no error message is available (null pointer),
/// a default message is returned. If the error message contains invalid UTF-8, an
/// error describing the UTF-8 issue is returned instead.
///
/// # Thread Safety
///
/// This function is thread-safe because the error storage in `libfers` is thread-local.
/// Each thread has its own error message buffer.
fn get_last_error() -> String {
    // SAFETY: `fers_get_last_error_message` is a thread-safe FFI function.
    let error_ptr = unsafe { ffi::fers_get_last_error_message() };
    if error_ptr.is_null() {
        "An unknown FFI error occurred.".to_string()
    } else {
        // The FersOwnedString wrapper ensures the memory is freed.
        FersOwnedString(error_ptr)
            .into_string()
            .unwrap_or_else(|e| format!("FFI error message contained invalid UTF-8: {}", e))
    }
}
 
fn take_last_warnings() -> Result<Vec<String>, String> {
    let warnings_ptr = unsafe { ffi::fers_get_last_warning_messages_json() };
    if warnings_ptr.is_null() {
        return Ok(vec![]);
    }
 
    let warnings_json = FersOwnedString(warnings_ptr).into_string().map_err(|e| e.to_string())?;
    serde_json::from_str(&warnings_json)
        .map_err(|e| format!("Failed to decode warning payload from libfers: {}", e))
}
 
/// Data structure for simulation progress events emitted to the frontend.
#[derive(serde::Serialize, Clone)]
struct ProgressPayload {
    message: String,
    current: i32,
    total: i32,
}
 
/// Data structure for raw FERS log lines emitted to the frontend.
#[derive(serde::Serialize, Clone)]
struct LogPayload {
    sequence: u64,
    level: &'static str,
    line: String,
}
 
#[derive(serde::Serialize, serde::Deserialize, Clone, Copy, Debug, Eq, PartialEq)]
#[serde(rename_all = "UPPERCASE")]
pub enum LogLevel {
    Trace,
    Debug,
    Info,
    Warning,
    Error,
    Fatal,
    Off,
}
 
impl LogLevel {
    fn to_ffi(self) -> ffi::fers_log_level_t {
        match self {
            Self::Trace => 0,
            Self::Debug => 1,
            Self::Info => 2,
            Self::Warning => 3,
            Self::Error => 4,
            Self::Fatal => 5,
            Self::Off => 6,
        }
    }
 
    fn from_ffi(level: ffi::fers_log_level_t) -> Self {
        match level {
            0 => Self::Trace,
            1 => Self::Debug,
            2 => Self::Info,
            3 => Self::Warning,
            4 => Self::Error,
            5 => Self::Fatal,
            6 => Self::Off,
            _ => Self::Info,
        }
    }
}
 
fn log_level_label(level: ffi::fers_log_level_t) -> &'static str {
    match level {
        0 => "TRACE",
        1 => "DEBUG",
        2 => "INFO",
        3 => "WARNING",
        4 => "ERROR",
        5 => "FATAL",
        6 => "OFF",
        _ => "UNKNOWN",
    }
}
 
pub fn get_log_level() -> LogLevel {
    let level = unsafe { ffi::fers_get_log_level() };
    LogLevel::from_ffi(level)
}
 
pub fn set_log_level(level: LogLevel) -> Result<(), String> {
    let result = unsafe { ffi::fers_configure_logging(level.to_ffi(), std::ptr::null()) };
    if result == 0 {
        Ok(())
    } else {
        Err(get_last_error())
    }
}
 
/// The C-style callback function registered with the libfers logger.
extern "C" fn fers_log_callback(
    level: ffi::fers_log_level_t,
    line: *const c_char,
    user_data: *mut c_void,
) {
    if user_data.is_null() || line.is_null() {
        return;
    }
 
    // SAFETY: `user_data` is a leaked AppHandle pointer for the lifetime of the Tauri app.
    let app_handle = unsafe { &*(user_data as *const AppHandle) };
 
    // SAFETY: `line` is guaranteed by the C-API callback contract to be valid for this call.
    let line_str = unsafe { CStr::from_ptr(line) }.to_string_lossy().into_owned();
 
    let payload = LogPayload {
        sequence: LOG_SEQUENCE.fetch_add(1, Ordering::Relaxed),
        level: log_level_label(level),
        line: line_str,
    };
 
    let _ = app_handle.emit("fers-log", payload);
}
 
pub fn register_log_callback(app_handle: AppHandle) {
    let app_handle_ptr = Box::into_raw(Box::new(app_handle)) as *mut c_void;
 
    // SAFETY: The callback and leaked AppHandle pointer remain valid for the Tauri app lifetime.
    unsafe {
        ffi::fers_set_log_callback(Some(fers_log_callback), app_handle_ptr);
    }
}
 
/// The C-style callback function passed to `fers_run_simulation`.
///
/// This function is invoked by the C++ core to report progress. It reconstructs the
/// `AppHandle` from the `user_data` pointer and emits a Tauri event to the frontend.
///
/// # Safety
///
/// This function is marked `unsafe` because it dereferences raw pointers (`message`, `user_data`).
/// The caller (the C++ library) must guarantee that `message` is a valid, null-terminated
/// UTF-8 string and that `user_data` is a valid pointer to an `AppHandle`. The pointer
/// is only valid for the duration of the `fers_run_simulation` call.
#[allow(clippy::similar_names)]
extern "C" fn simulation_progress_callback(
    message: *const c_char,
    current: i32,
    total: i32,
    user_data: *mut c_void,
) {
    if user_data.is_null() {
        return;
    }
    // SAFETY: This is safe because we know `user_data` is a pointer to the AppHandle,
    // which is guaranteed to be valid for the lifetime of the simulation call.
    let app_handle = unsafe { &*(user_data as *const AppHandle) };
 
    // SAFETY: `message` is guaranteed by the C-API to be a valid, null-terminated string.
    let message_str = unsafe { CStr::from_ptr(message) }.to_string_lossy().into_owned();
 
    let payload = ProgressPayload { message: message_str, current, total };
 
    // Emit the event to the frontend. If this fails, there's little we can do
    // from the callback, so we just let it panic in debug builds.
    app_handle
        .emit("simulation-progress", payload)
        .expect("Failed to emit simulation-progress event");
}
 
extern "C" fn vita49_lifecycle_callback(
    message: *const c_char,
    _current: i32,
    _total: i32,
    user_data: *mut c_void,
) {
    if user_data.is_null() || message.is_null() {
        return;
    }
 
    let app_handle = unsafe { &*(user_data as *const AppHandle) };
    let message_str = unsafe { CStr::from_ptr(message) }.to_string_lossy().into_owned();
 
    if message_str == VITA49_DRAIN_MESSAGE {
        app_handle
            .emit("vita49-stream-draining", message_str)
            .expect("Failed to emit vita49-stream-draining event");
    }
}
 
extern "C" fn simulation_cancel_callback(user_data: *mut c_void) -> i32 {
    if user_data.is_null() {
        return 0;
    }
 
    let cancel_flag = unsafe { &*(user_data as *const AtomicBool) };
    i32::from(cancel_flag.load(Ordering::Relaxed))
}
 
extern "C" fn vita49_telemetry_callback(
    stats_json: *const c_char,
    packet_batch_json: *const c_char,
    user_data: *mut c_void,
) {
    if user_data.is_null() {
        return;
    }
 
    let sender = unsafe { &*(user_data as *const Vita49TelemetrySender) };
 
    let stats_json = if stats_json.is_null() {
        None
    } else {
        Some(unsafe { CStr::from_ptr(stats_json) }.to_string_lossy().into_owned())
    };
 
    let packet_batch_json = if packet_batch_json.is_null() {
        None
    } else {
        Some(unsafe { CStr::from_ptr(packet_batch_json) }.to_string_lossy().into_owned())
    };
 
    let _ = sender.send(Vita49TelemetryMessage { stats_json, packet_batch_json });
}
 
/// A safe RAII wrapper for the antenna pattern data returned by the C-API.
struct FersAntennaPatternData(*mut ffi::fers_antenna_pattern_data_t);
impl Drop for FersAntennaPatternData {
    fn drop(&mut self) {
        if !self.0.is_null() {
            // SAFETY: The pointer is valid and owned by this struct.
            unsafe { ffi::fers_free_antenna_pattern_data(self.0) };
        }
    }
}
 
/// Data structure for antenna pattern data sent to the frontend.
///
/// This struct flattens the 2D gain data into a 1D vector for easy serialization.
#[derive(serde::Serialize, std::fmt::Debug)]
pub struct AntennaPatternData {
    /// Flattened array of linear gain values (normalized 0.0 to 1.0).
    /// Ordered row-major: Elevation rows, then Azimuth columns.
    gains: Vec<f64>,
    /// Number of samples along the azimuth axis (360 degrees).
    az_count: usize,
    /// Number of samples along the elevation axis (180 degrees).
    el_count: usize,
    /// The peak linear gain found in the pattern, used for normalization.
    max_gain: f64,
}
 
// Helper wrapper for the visual link list
struct FersVisualLinkList(*mut ffi::fers_visual_link_list_t);
 
impl Drop for FersVisualLinkList {
    fn drop(&mut self) {
        if !self.0.is_null() {
            unsafe { ffi::fers_free_preview_links(self.0) };
        }
    }
}
 
/// Represents a visual link segment for 3D rendering.
///
/// This struct maps C-style enums to integers for consumption by the TypeScript frontend.
#[derive(serde::Serialize, std::fmt::Debug)]
pub struct VisualLink {
    /// The type of radio link.
    /// * `0`: Monostatic (Tx -> Tgt -> Rx, where Tx==Rx)
    /// * `1`: Bistatic Illuminator (Tx -> Tgt)
    /// * `2`: Bistatic Scattered (Tgt -> Rx)
    /// * `3`: Direct Interference (Tx -> Rx)
    pub link_type: u8,
    /// The radiometric quality of the link.
    /// * `0`: Strong (SNR > 0 dB)
    /// * `1`: Weak (SNR < 0 dB, visible but sub-noise)
    pub quality: u8,
    /// A pre-formatted label string (e.g., "-95 dBm").
    pub label: String,
    /// The ID of the start component for this segment.
    pub source_id: String,
    /// The ID of the end component for this segment.
    pub dest_id: String,
    /// The ID of the original transmitter (useful for scattered paths).
    pub origin_id: String,
    /// RCS in m^2 for this path. Negative if not applicable (non-monostatic links).
    pub rcs: f64,
    /// Received power in dBm with actual RCS applied. -999 if not applicable.
    pub actual_power_dbm: f64,
    /// Numeric value represented by `label`, in the label's unit.
    pub display_value: f64,
}
 
impl FersContext {
    /// Creates a new `FersContext` by calling the C-API constructor.
    ///
    /// This function allocates a new C++ `FersContext` object on the heap via
    /// `fers_context_create`. The returned context is initially empty and must be
    /// populated by loading a scenario (via `load_scenario_from_xml_file` or
    /// `update_scenario_from_json`).
    ///
    /// # Returns
    ///
    /// * `Some(FersContext)` - If the context was successfully created.
    /// * `None` - If allocation failed (e.g., out of memory) or if the C++ constructor
    ///   threw an exception.
    ///
    /// # Example
    ///
    /// ```ignore
    /// let context = FersContext::new().expect("Failed to create FERS context");
    /// ```
    pub fn new() -> Option<Self> {
        // SAFETY: `fers_context_create` is a simple constructor function with no preconditions.
        let ptr = unsafe { ffi::fers_context_create() };
        if ptr.is_null() {
            None
        } else {
            Some(Self { ptr })
        }
    }
 
    /// Sets the output directory for simulation results.
    ///
    /// # Parameters
    ///
    /// * `dir` - A UTF-8 string containing the path to the output directory.
    ///
    /// # Returns
    ///
    /// * `Ok(())` - If the directory was successfully set.
    /// * `Err(String)` - If an error occurred.
    pub fn set_output_directory(&self, dir: &str) -> Result<(), String> {
        let c_dir = CString::new(dir).map_err(|e| e.to_string())?;
        // SAFETY: We pass a valid context pointer and a null-terminated C string.
        let result = unsafe { ffi::fers_set_output_directory(self.ptr, c_dir.as_ptr()) };
        if result == 0 {
            Ok(())
        } else {
            Err(get_last_error())
        }
    }
 
    pub fn use_hdf5_output(&self) -> Result<(), String> {
        let result = unsafe { ffi::fers_use_hdf5_output(self.ptr) };
        if result == 0 {
            Ok(())
        } else {
            Err(get_last_error())
        }
    }
 
    pub fn enable_vita49_udp_output(&self, host: &str, port: u16) -> Result<(), String> {
        let c_host = CString::new(host).map_err(|e| e.to_string())?;
        let result = unsafe { ffi::fers_enable_vita49_udp_output(self.ptr, c_host.as_ptr(), port) };
        if result == 0 {
            Ok(())
        } else {
            Err(get_last_error())
        }
    }
 
    pub fn set_vita49_fullscale(&self, fullscale: f64) -> Result<(), String> {
        let result = unsafe { ffi::fers_set_vita49_fullscale(self.ptr, fullscale) };
        if result == 0 {
            Ok(())
        } else {
            Err(get_last_error())
        }
    }
 
    pub fn set_vita49_epoch_unix_nanoseconds(&self, epoch: u64) -> Result<(), String> {
        let result = unsafe { ffi::fers_set_vita49_epoch_unix_nanoseconds(self.ptr, epoch) };
        if result == 0 {
            Ok(())
        } else {
            Err(get_last_error())
        }
    }
 
    pub fn set_vita49_max_udp_payload(&self, max_udp_payload: u16) -> Result<(), String> {
        let result = unsafe { ffi::fers_set_vita49_max_udp_payload(self.ptr, max_udp_payload) };
        if result == 0 {
            Ok(())
        } else {
            Err(get_last_error())
        }
    }
 
    pub fn set_vita49_queue_depth(&self, queue_depth: u32) -> Result<(), String> {
        let result = unsafe { ffi::fers_set_vita49_queue_depth(self.ptr, queue_depth) };
        if result == 0 {
            Ok(())
        } else {
            Err(get_last_error())
        }
    }
 
    pub fn set_vita49_packet_trace_enabled(&self, enabled: bool) -> Result<(), String> {
        let result = unsafe {
            ffi::fers_set_vita49_packet_trace_enabled(self.ptr, if enabled { 1 } else { 0 })
        };
        if result == 0 {
            Ok(())
        } else {
            Err(get_last_error())
        }
    }
 
    pub fn configure_vita49_stream(&self, config: &Vita49StreamConfig) -> Result<(), String> {
        self.enable_vita49_udp_output(&config.host, config.port)?;
        self.set_vita49_fullscale(config.fullscale)?;
        if let Some(epoch) = &config.epoch_unix_nanoseconds {
            let parsed_epoch =
                epoch.parse::<u64>().map_err(|e| format!("Invalid VITA49 epoch: {}", e))?;
            self.set_vita49_epoch_unix_nanoseconds(parsed_epoch)?;
        }
        self.set_vita49_max_udp_payload(config.max_udp_payload)?;
        self.set_vita49_queue_depth(config.queue_depth)?;
        self.set_vita49_packet_trace_enabled(config.trace_enabled)?;
        Ok(())
    }
 
    /// Loads a FERS scenario from an XML file into the context.
    ///
    /// This method replaces any existing scenario in the context with the one parsed
    /// from the specified file. The XML is validated against the FERS schema if
    /// validation is enabled in the C++ library.
    ///
    /// # Parameters
    ///
    /// * `filepath` - A UTF-8 string containing the absolute or relative path to the
    ///   FERS XML scenario file.
    ///
    /// # Returns
    ///
    /// * `Ok(())` - If the scenario was successfully loaded and parsed.
    /// * `Err(String)` - If the file could not be read, the XML was invalid, or a
    ///   C++ exception was thrown. The error string contains details.
    ///
    /// # Example
    ///
    /// ```ignore
    /// context.load_scenario_from_xml_file("/path/to/scenario.xml")?;
    /// ```
    pub fn load_scenario_from_xml_file(&self, filepath: &str) -> Result<Vec<String>, String> {
        let c_filepath = CString::new(filepath).map_err(|e| e.to_string())?;
        // SAFETY: We pass a valid context pointer and a null-terminated C string.
        // The function returns 0 on success.
        let result =
            unsafe { ffi::fers_load_scenario_from_xml_file(self.ptr, c_filepath.as_ptr(), 1) };
        if result == 0 {
            take_last_warnings()
        } else {
            Err(get_last_error())
        }
    }
 
    /// Retrieves the current in-memory scenario as a JSON string.
    ///
    /// This method serializes the C++ `World` object into JSON format, which mirrors
    /// the structure used by the frontend. It is typically used to populate the UI
    /// after loading a scenario from XML.
    ///
    /// # Returns
    ///
    /// * `Ok(String)` - The JSON representation of the scenario.
    /// * `Err(String)` - If serialization failed or the JSON contains invalid UTF-8.
    ///
    /// # Memory Management
    ///
    /// The returned string is a Rust-owned `String`. The underlying C-allocated memory
    /// is automatically freed by the `FersOwnedString` wrapper.
    ///
    /// # Example
    ///
    /// ```ignore
    /// let json = context.get_scenario_as_json()?;
    /// let scenario: serde_json::Value = serde_json::from_str(&json)?;
    /// ```
    pub fn get_scenario_as_json(&self) -> Result<String, String> {
        // SAFETY: We pass a valid context pointer. The function returns a C string
        // that we must free.
        let json_ptr = unsafe { ffi::fers_get_scenario_as_json(self.ptr) };
        if json_ptr.is_null() {
            return Err(get_last_error());
        }
        // FersOwnedString takes ownership and will free the memory on drop.
        FersOwnedString(json_ptr).into_string().map_err(|e| e.to_string())
    }
 
    /// Retrieves the current in-memory scenario as a FERS XML string.
    ///
    /// This method serializes the C++ `World` object into the standard FERS XML format.
    /// It is typically used when the user wants to export the scenario (potentially
    /// modified in the UI) back to a file.
    ///
    /// # Returns
    ///
    /// * `Ok(String)` - The XML representation of the scenario.
    /// * `Err(String)` - If serialization failed or the XML contains invalid UTF-8.
    ///
    /// # Memory Management
    ///
    /// The returned string is a Rust-owned `String`. The underlying C-allocated memory
    /// is automatically freed by the `FersOwnedString` wrapper.
    ///
    /// # Example
    ///
    /// ```ignore
    /// let xml = context.get_scenario_as_xml()?;
    /// std::fs::write("exported_scenario.xml", xml)?;
    /// ```
    pub fn get_scenario_as_xml(&self) -> Result<String, String> {
        // SAFETY: We pass a valid context pointer. The function returns a C string
        // that we must free.
        let xml_ptr = unsafe { ffi::fers_get_scenario_as_xml(self.ptr) };
        if xml_ptr.is_null() {
            return Err(get_last_error());
        }
        // FersOwnedString takes ownership and will free the memory on drop.
        FersOwnedString(xml_ptr).into_string().map_err(|e| e.to_string())
    }
 
    /// Updates the in-memory scenario from a JSON string.
    ///
    /// This method is the primary way for the UI to push modified scenario data back
    /// to the C++ simulation engine. It deserializes the JSON and rebuilds the internal
    /// `World` object, replacing any existing scenario.
    ///
    /// # Parameters
    ///
    /// * `json` - A UTF-8 JSON string representing the scenario. The structure must
    ///   match the schema expected by `libfers` (the same format returned by
    ///   `get_scenario_as_json`).
    ///
    /// # Returns
    ///
    /// * `Ok(())` - If the scenario was successfully deserialized and loaded.
    /// * `Err(String)` - If the JSON was malformed, contained invalid data, or a C++
    ///   exception was thrown. The error string contains details.
    ///
    /// # Example
    ///
    /// ```ignore
    /// let modified_json = /* JSON from UI */;
    /// context.update_scenario_from_json(&modified_json)?;
    /// ```
    pub fn update_scenario_from_json(&self, json: &str) -> Result<Vec<String>, String> {
        let c_json = CString::new(json).map_err(|e| e.to_string())?;
        // SAFETY: We pass a valid context pointer and a null-terminated C string.
        // The function returns 0 on success.
        let result = unsafe { ffi::fers_update_scenario_from_json(self.ptr, c_json.as_ptr()) };
        if result == 0 {
            take_last_warnings()
        } else {
            Err(get_last_error())
        }
    }
 
    /// Updates a single platform's paths and name from JSON.
    pub fn update_platform_from_json(
        &self,
        id_str: &str,
        json: &str,
    ) -> Result<Vec<String>, String> {
        let id = id_str.parse::<u64>().map_err(|e| format!("Invalid ID: {}", e))?;
        let c_json = CString::new(json).map_err(|e| e.to_string())?;
        let result = unsafe { ffi::fers_update_platform_from_json(self.ptr, id, c_json.as_ptr()) };
        if result == 0 {
            take_last_warnings()
        } else {
            Err(get_last_error())
        }
    }
 
    /// Updates the global simulation parameters from JSON.
    pub fn update_parameters_from_json(&self, json: &str) -> Result<Vec<String>, String> {
        let c_json = CString::new(json).map_err(|e| e.to_string())?;
        let result = unsafe { ffi::fers_update_parameters_from_json(self.ptr, c_json.as_ptr()) };
        if result == 0 {
            take_last_warnings()
        } else {
            Err(get_last_error())
        }
    }
 
    /// Updates a single antenna from JSON.
    pub fn update_antenna_from_json(&self, json: &str) -> Result<(), String> {
        let c_json = CString::new(json).map_err(|e| e.to_string())?;
        let result = unsafe { ffi::fers_update_antenna_from_json(self.ptr, c_json.as_ptr()) };
        if result == 0 {
            Ok(())
        } else {
            Err(get_last_error())
        }
    }
 
    /// Updates a single waveform from JSON.
    pub fn update_waveform_from_json(&self, json: &str) -> Result<(), String> {
        let c_json = CString::new(json).map_err(|e| e.to_string())?;
        let result = unsafe { ffi::fers_update_waveform_from_json(self.ptr, c_json.as_ptr()) };
        if result == 0 {
            Ok(())
        } else {
            Err(get_last_error())
        }
    }
 
    /// Updates a single transmitter from JSON.
    pub fn update_transmitter_from_json(&self, id_str: &str, json: &str) -> Result<(), String> {
        let id = id_str.parse::<u64>().map_err(|e| format!("Invalid ID: {}", e))?;
        let c_json = CString::new(json).map_err(|e| e.to_string())?;
        let result =
            unsafe { ffi::fers_update_transmitter_from_json(self.ptr, id, c_json.as_ptr()) };
        if result == 0 {
            Ok(())
        } else {
            Err(get_last_error())
        }
    }
 
    /// Updates a single receiver from JSON.
    pub fn update_receiver_from_json(&self, id_str: &str, json: &str) -> Result<(), String> {
        let id = id_str.parse::<u64>().map_err(|e| format!("Invalid ID: {}", e))?;
        let c_json = CString::new(json).map_err(|e| e.to_string())?;
        let result = unsafe { ffi::fers_update_receiver_from_json(self.ptr, id, c_json.as_ptr()) };
        if result == 0 {
            Ok(())
        } else {
            Err(get_last_error())
        }
    }
 
    /// Updates a single target from JSON.
    pub fn update_target_from_json(&self, id_str: &str, json: &str) -> Result<(), String> {
        let id = id_str.parse::<u64>().map_err(|e| format!("Invalid ID: {}", e))?;
        let c_json = CString::new(json).map_err(|e| e.to_string())?;
        let result = unsafe { ffi::fers_update_target_from_json(self.ptr, id, c_json.as_ptr()) };
        if result == 0 {
            Ok(())
        } else {
            Err(get_last_error())
        }
    }
 
    /// Updates a monostatic radar from JSON.
    pub fn update_monostatic_from_json(&self, json: &str) -> Result<(), String> {
        let c_json = CString::new(json).map_err(|e| e.to_string())?;
        let result = unsafe { ffi::fers_update_monostatic_from_json(self.ptr, c_json.as_ptr()) };
        if result == 0 {
            Ok(())
        } else {
            Err(get_last_error())
        }
    }
 
    /// Updates a single timing source from JSON.
    pub fn update_timing_from_json(&self, id_str: &str, json: &str) -> Result<(), String> {
        let id = id_str.parse::<u64>().map_err(|e| format!("Invalid ID: {}", e))?;
        let c_json = CString::new(json).map_err(|e| e.to_string())?;
        let result = unsafe { ffi::fers_update_timing_from_json(self.ptr, id, c_json.as_ptr()) };
        if result == 0 {
            Ok(())
        } else {
            Err(get_last_error())
        }
    }
 
    pub fn run_simulation(
        &self,
        app_handle: &AppHandle,
        cancel_flag: &AtomicBool,
    ) -> Result<SimulationRunOutcome, String> {
        self.use_hdf5_output()?;
        self.run_simulation_ex(
            cancel_flag,
            Some(simulation_progress_callback),
            app_handle as *const _ as *mut c_void,
            None,
        )
    }
 
    pub fn run_vita49_stream(
        &self,
        app_handle: &AppHandle,
        cancel_flag: &AtomicBool,
        config: &Vita49StreamConfig,
        telemetry_sender: Option<&Vita49TelemetrySender>,
    ) -> Result<SimulationRunOutcome, String> {
        self.configure_vita49_stream(config)?;
        self.run_simulation_ex(
            cancel_flag,
            Some(vita49_lifecycle_callback),
            app_handle as *const _ as *mut c_void,
            telemetry_sender,
        )
    }
 
    fn run_simulation_ex(
        &self,
        cancel_flag: &AtomicBool,
        progress_callback: ffi::fers_progress_callback_t,
        progress_user_data_ptr: *mut c_void,
        telemetry_sender: Option<&Vita49TelemetrySender>,
    ) -> Result<SimulationRunOutcome, String> {
        let cancel_user_data_ptr = cancel_flag as *const _ as *mut c_void;
        let telemetry_user_data_ptr = telemetry_sender
            .map(|sender| sender as *const _ as *mut c_void)
            .unwrap_or(std::ptr::null_mut());
        let telemetry_callback: ffi::fers_vita49_telemetry_callback_t =
            if telemetry_sender.is_some() { Some(vita49_telemetry_callback) } else { None };
 
        let result = unsafe {
            ffi::fers_run_simulation_ex(
                self.ptr,
                progress_callback,
                progress_user_data_ptr,
                Some(simulation_cancel_callback),
                cancel_user_data_ptr,
                telemetry_callback,
                telemetry_user_data_ptr,
            )
        };
 
        match result {
            0 => self.get_last_output_metadata_json().map(SimulationRunOutcome::Completed),
            FERS_RUN_CANCELLED => {
                let metadata =
                    self.get_last_output_metadata_json().unwrap_or_else(|_| "{}".to_string());
                Ok(SimulationRunOutcome::Cancelled(metadata))
            }
            _ => Err(get_last_error()),
        }
    }
 
    /// Retrieves JSON metadata for the most recent simulation output files.
    pub fn get_last_output_metadata_json(&self) -> Result<String, String> {
        // SAFETY: We pass a valid context pointer. The returned C string is owned by the caller.
        let metadata_ptr = unsafe { ffi::fers_get_last_output_metadata_json(self.ptr) };
        if metadata_ptr.is_null() {
            return Err(get_last_error());
        }
        FersOwnedString(metadata_ptr).into_string().map_err(|e| e.to_string())
    }
 
    /// Generates a KML file for the current scenario.
    ///
    /// # Parameters
    ///
    /// * `output_path` - The path where the KML file will be saved.
    ///
    /// # Returns
    ///
    /// * `Ok(())` - If the KML file was generated successfully.
    /// * `Err(String)` - If KML generation failed.
    pub fn generate_kml(&self, output_path: &str) -> Result<(), String> {
        let c_output_path = CString::new(output_path).map_err(|e| e.to_string())?;
        // SAFETY: We pass a valid context pointer and a null-terminated C string for the path.
        let result = unsafe { ffi::fers_generate_kml(self.ptr, c_output_path.as_ptr()) };
        if result == 0 {
            Ok(())
        } else {
            Err(get_last_error())
        }
    }
 
    /// Retrieves a sampled gain pattern for a specified antenna.
    ///
    /// # Parameters
    ///
    /// * `antenna_id` - The ID of the antenna asset to sample.
    /// * `az_samples` - The resolution along the azimuth axis.
    /// * `el_samples` - The resolution along the elevation axis.
    /// * `frequency` - The frequency in Hz to use for calculation.
    ///
    /// # Returns
    ///
    /// * `Ok(AntennaPatternData)` - If the pattern was successfully sampled.
    /// * `Err(String)` - If the antenna was not found or an error occurred.
    pub fn get_antenna_pattern(
        &self,
        antenna_id: &str,
        az_samples: usize,
        el_samples: usize,
        frequency: f64,
    ) -> Result<AntennaPatternData, String> {
        let antenna_id_val = antenna_id
            .parse::<u64>()
            .map_err(|e| format!("Invalid antenna ID '{antenna_id}': {e}"))?;
        // SAFETY: We pass a valid context pointer and valid arguments.
        let result_ptr = unsafe {
            ffi::fers_get_antenna_pattern(
                self.ptr,
                antenna_id_val,
                az_samples,
                el_samples,
                frequency,
            )
        };
 
        if result_ptr.is_null() {
            return Err(get_last_error());
        }
 
        let owned_data = FersAntennaPatternData(result_ptr);
 
        // SAFETY: Dereferencing the non-null pointer returned by the FFI.
        // The data is valid for the lifetime of `owned_data`.
        let (gains_ptr, az_count, el_count, max_gain) = unsafe {
            (
                (*owned_data.0).gains,
                (*owned_data.0).az_count,
                (*owned_data.0).el_count,
                (*owned_data.0).max_gain,
            )
        };
        let total_samples = az_count * el_count;
 
        // SAFETY: The gains_ptr is valid for `total_samples` elements.
        let gains_slice = unsafe { std::slice::from_raw_parts(gains_ptr, total_samples) };
 
        Ok(AntennaPatternData { gains: gains_slice.to_vec(), az_count, el_count, max_gain })
    }
 
    pub fn calculate_preview_links(&self, time: f64) -> Result<Vec<VisualLink>, String> {
        let list_ptr = unsafe { ffi::fers_calculate_preview_links(self.ptr, time) };
        if list_ptr.is_null() {
            let err_msg = get_last_error();
            // If we receive a NULL ptr but no error message, it might be a logic error
            // or an unhandled edge case in C++. We default to the retrieved message.
            return Err(err_msg);
        }
 
        let owned_list = FersVisualLinkList(list_ptr);
        let count = unsafe { (*owned_list.0).count };
        let links_ptr = unsafe { (*owned_list.0).links };
 
        let mut result = Vec::with_capacity(count);
        if count > 0 && !links_ptr.is_null() {
            let slice = unsafe { std::slice::from_raw_parts(links_ptr, count) };
            for l in slice {
                let link_type_val = match l.type_ {
                    ffi::fers_link_type_t_FERS_LINK_MONOSTATIC => 0,
                    ffi::fers_link_type_t_FERS_LINK_BISTATIC_TX_TGT => 1,
                    ffi::fers_link_type_t_FERS_LINK_BISTATIC_TGT_RX => 2,
                    ffi::fers_link_type_t_FERS_LINK_DIRECT_TX_RX => 3,
                    _ => 0,
                };
 
                let quality_val = match l.quality {
                    ffi::fers_link_quality_t_FERS_LINK_STRONG => 0,
                    _ => 1,
                };
 
                let label =
                    unsafe { CStr::from_ptr(l.label.as_ptr()) }.to_string_lossy().into_owned();
                let source_id = l.source_id.to_string();
                let dest_id = l.dest_id.to_string();
                let origin_id = l.origin_id.to_string();
 
                result.push(VisualLink {
                    link_type: link_type_val,
                    quality: quality_val,
                    label,
                    source_id,
                    dest_id,
                    origin_id,
                    rcs: l.rcs,
                    actual_power_dbm: l.actual_power_dbm,
                    display_value: l.display_value,
                });
            }
        }
        Ok(result)
    }
}
 
/// A safe wrapper for the stateless `fers_get_interpolated_motion_path` C-API function.
///
/// This function converts Rust-native waypoint data into C-compatible types,
/// calls the FFI function, and then converts the result back into a `Vec` of points,
/// ensuring that all C-allocated memory is properly freed.
///
/// # Parameters
/// * `waypoints` - A vector of motion waypoints from the frontend.
/// * `interp_type` - The interpolation algorithm to use.
/// * `num_points` - The desired number of points in the output path.
///
/// # Returns
/// * `Ok(Vec<InterpolatedPoint>)` - A vector of points representing the calculated path.
/// * `Err(String)` - An error message if the FFI call failed.
pub fn get_interpolated_motion_path(
    waypoints: Vec<crate::MotionWaypoint>,
    interp_type: crate::InterpolationType,
    num_points: usize,
) -> Result<Vec<crate::InterpolatedMotionPoint>, String> {
    if waypoints.is_empty() || num_points == 0 {
        return Ok(Vec::new());
    }
 
    let c_waypoints: Vec<ffi::fers_motion_waypoint_t> = waypoints
        .into_iter()
        .map(|wp| ffi::fers_motion_waypoint_t { time: wp.time, x: wp.x, y: wp.y, z: wp.altitude })
        .collect();
 
    let c_interp_type = match interp_type {
        crate::InterpolationType::Static => ffi::fers_interp_type_t_FERS_INTERP_STATIC,
        crate::InterpolationType::Linear => ffi::fers_interp_type_t_FERS_INTERP_LINEAR,
        crate::InterpolationType::Cubic => ffi::fers_interp_type_t_FERS_INTERP_CUBIC,
    };
 
    // SAFETY: We are calling the stateless FFI function with valid, well-formed arguments.
    // The pointer returned is owned by us and must be freed.
    let result_ptr = unsafe {
        ffi::fers_get_interpolated_motion_path(
            c_waypoints.as_ptr(),
            c_waypoints.len(),
            c_interp_type,
            num_points,
        )
    };
 
    if result_ptr.is_null() {
        return Err(get_last_error());
    }
 
    // RAII wrapper to ensure the C-allocated path is freed.
    struct FersInterpolatedMotionPath(*mut ffi::fers_interpolated_path_t);
 
    impl Drop for FersInterpolatedMotionPath {
        fn drop(&mut self) {
            if !self.0.is_null() {
                // SAFETY: The pointer is valid and owned by this struct.
                unsafe { ffi::fers_free_interpolated_motion_path(self.0) };
            }
        }
    }
 
    let owned_path = FersInterpolatedMotionPath(result_ptr);
 
    // SAFETY: We are accessing the fields of a non-null pointer returned by the FFI.
    // The `count` and `points` fields are guaranteed to be valid for the lifetime of `owned_path`.
    let result_slice =
        unsafe { std::slice::from_raw_parts((*owned_path.0).points, (*owned_path.0).count) };
 
    let points: Vec<crate::InterpolatedMotionPoint> = result_slice
        .iter()
        .map(|p| crate::InterpolatedMotionPoint {
            x: p.x,
            y: p.y,
            z: p.z,
            vx: p.vx,
            vy: p.vy,
            vz: p.vz,
        })
        .collect();
 
    Ok(points)
}
 
/// A safe wrapper for the stateless `fers_get_interpolated_rotation_path` C-API function.
///
/// This function converts Rust-native rotation waypoints into C-compatible types,
/// calls the FFI function, and converts the result back into a `Vec` of points.
/// It handles the mapping between Rust enums and C enums for interpolation types
/// and ensures that the C-allocated array is properly freed.
///
/// # Parameters
/// * `waypoints` - A vector of `RotationWaypoint`s.
/// * `interp_type` - The interpolation algorithm to use.
/// * `num_points` - The desired number of points in the output path.
///
/// # Returns
/// * `Ok(Vec<InterpolatedRotationPoint>)` - A vector of interpolated points.
/// * `Err(String)` - An error message if the FFI call failed.
pub fn get_interpolated_rotation_path(
    waypoints: Vec<crate::RotationWaypoint>,
    interp_type: crate::InterpolationType,
    angle_unit: crate::RotationAngleUnit,
    num_points: usize,
) -> Result<Vec<crate::InterpolatedRotationPoint>, String> {
    if waypoints.is_empty() || num_points == 0 {
        return Ok(Vec::new());
    }
 
    let c_waypoints: Vec<ffi::fers_rotation_waypoint_t> = waypoints
        .into_iter()
        .map(|wp| ffi::fers_rotation_waypoint_t {
            time: wp.time,
            azimuth: wp.azimuth,
            elevation: wp.elevation,
        })
        .collect();
 
    let c_interp_type = match interp_type {
        crate::InterpolationType::Static => ffi::fers_interp_type_t_FERS_INTERP_STATIC,
        crate::InterpolationType::Linear => ffi::fers_interp_type_t_FERS_INTERP_LINEAR,
        crate::InterpolationType::Cubic => ffi::fers_interp_type_t_FERS_INTERP_CUBIC,
    };
    let c_angle_unit = match angle_unit {
        crate::RotationAngleUnit::Deg => ffi::fers_angle_unit_t_FERS_ANGLE_UNIT_DEG,
        crate::RotationAngleUnit::Rad => ffi::fers_angle_unit_t_FERS_ANGLE_UNIT_RAD,
    };
 
    let result_ptr = unsafe {
        ffi::fers_get_interpolated_rotation_path(
            c_waypoints.as_ptr(),
            c_waypoints.len(),
            c_interp_type,
            c_angle_unit,
            num_points,
        )
    };
 
    if result_ptr.is_null() {
        return Err(get_last_error());
    }
 
    struct FersInterpolatedRotationPath(*mut ffi::fers_interpolated_rotation_path_t);
 
    impl Drop for FersInterpolatedRotationPath {
        fn drop(&mut self) {
            if !self.0.is_null() {
                unsafe { ffi::fers_free_interpolated_rotation_path(self.0) };
            }
        }
    }
 
    let owned_path = FersInterpolatedRotationPath(result_ptr);
 
    let result_slice =
        unsafe { std::slice::from_raw_parts((*owned_path.0).points, (*owned_path.0).count) };
 
    let points: Vec<crate::InterpolatedRotationPoint> = result_slice
        .iter()
        .map(|p| crate::InterpolatedRotationPoint { azimuth: p.azimuth, elevation: p.elevation })
        .collect();
 
    Ok(points)
}
 
#[cfg(test)]
mod tests {
    use super::*;
    use std::io::Write;
    use tempfile::NamedTempFile;
 
    /// A minimal, valid FERS JSON scenario that the core engine can parse.
    fn minimal_valid_json() -> &'static str {
        r#"{
                "simulation": {
                    "parameters": {
                        "starttime": 0.0,
                        "endtime": 1.0,
                        "rate": 1000.0,
                        "origin": { "latitude": 0.0, "longitude": 0.0, "altitude": 0.0 },
                        "coordinatesystem": { "frame": "ENU" }
                    }
                }
            }"#
    }
 
    /// A scenario with assets and platforms for testing granular updates.
    fn scenario_with_assets_json() -> &'static str {
        r#"{
                "simulation": {
                    "parameters": {
                        "starttime": 0.0, "endtime": 1.0, "rate": 1000.0,
                        "origin": { "latitude": 0.0, "longitude": 0.0, "altitude": 0.0 },
                        "coordinatesystem": { "frame": "ENU" }
                    },
                    "waveforms": [
                        { "id": 10, "name": "w1", "power": 1000.0, "carrier_frequency": 1e9, "cw": {} }
                    ],
                    "antennas": [
                        { "id": 20, "name": "a1", "pattern": "isotropic" }
                    ],
                    "platforms": [
                        {
                            "id": 100, "name": "tx_plat",
                            "motionpath": { "interpolation": "static", "positionwaypoints": [ { "time": 0.0, "x": 0.0, "y": 0.0, "altitude": 0.0 } ] },
                            "rotationpath": { "interpolation": "static", "rotationwaypoints": [ { "time": 0.0, "azimuth": 0.0, "elevation": 0.0 } ] },
                            "components": []
                        }
                    ]
                }
            }"#
    }
 
    #[test]
    fn test_context_creation_and_destruction() {
        // Implicitly tests FersContext::new() and Drop (via fers_context_destroy)
        let context = FersContext::new();
        assert!(context.is_some(), "Failed to create FersContext via FFI");
    }
 
    #[test]
    fn test_update_scenario_from_invalid_json() {
        let context = FersContext::new().unwrap();
        let result = context.update_scenario_from_json("{ malformed_json...");
        assert!(result.is_err());
        let err_msg = result.unwrap_err();
        assert!(
            err_msg.contains("JSON parsing/deserialization error"),
            "Unexpected error message: {}",
            err_msg
        );
    }
 
    #[test]
    fn test_update_and_get_scenario() {
        let context = FersContext::new().unwrap();
        let result = context.update_scenario_from_json(minimal_valid_json());
        assert!(result.is_ok(), "Failed to update scenario from valid JSON");
 
        // Ensure retrieving it back as JSON works and memory is managed
        let json_back = context.get_scenario_as_json().unwrap();
        assert!(json_back.contains("parameters"), "JSON export missing expected data");
 
        // Ensure retrieving it back as XML works
        let xml_back = context.get_scenario_as_xml().unwrap();
        assert!(xml_back.contains("<simulation"), "XML export missing root element");
    }
 
    #[test]
    fn test_update_scenario_returns_rotation_unit_warnings() {
        let context = FersContext::new().unwrap();
        let mut scenario: serde_json::Value =
            serde_json::from_str(scenario_with_assets_json()).unwrap();
        scenario["simulation"]["parameters"]["rotationangleunit"] =
            serde_json::Value::String("rad".into());
        scenario["simulation"]["platforms"][0]["rotationpath"]["rotationwaypoints"][0]["azimuth"] =
            serde_json::Value::from(90.0);
 
        let warnings = context
            .update_scenario_from_json(&scenario.to_string())
            .expect("Scenario update with warnings should still succeed");
 
        assert_eq!(warnings.len(), 1);
        assert!(warnings[0].contains("rotation waypoint 0"));
        assert!(warnings[0].contains("'azimuth'"));
    }
 
    #[test]
    fn test_load_scenario_from_xml_file() {
        let context = FersContext::new().unwrap();
        let mut temp_file = NamedTempFile::new().unwrap();
        let minimal_xml = r#"<simulation name="TestAPI"><parameters><starttime>0</starttime><endtime>1</endtime><rate>1000</rate><origin latitude="0" longitude="0" altitude="0"/><coordinatesystem frame="ENU"/></parameters><antenna name="api_iso" pattern="isotropic"/></simulation>"#;
        temp_file.write_all(minimal_xml.as_bytes()).unwrap();
 
        let result = context.load_scenario_from_xml_file(temp_file.path().to_str().unwrap());
        assert!(result.is_ok(), "Failed to load minimal valid XML from file");
    }
 
    #[test]
    fn test_generate_kml() {
        let context = FersContext::new().unwrap();
        context.update_scenario_from_json(minimal_valid_json()).unwrap();
 
        let temp_kml = NamedTempFile::new().unwrap();
        let result = context.generate_kml(temp_kml.path().to_str().unwrap());
        assert!(result.is_ok(), "KML generation failed");
 
        // Verify data was actually written to the file by the C++ core
        let metadata = std::fs::metadata(temp_kml.path()).unwrap();
        assert!(metadata.len() > 0, "KML file was created but is empty");
    }
 
    #[test]
    fn test_get_interpolated_motion_path() {
        let waypoints = vec![
            crate::MotionWaypoint { time: 0.0, x: 0.0, y: 0.0, altitude: 0.0 },
            crate::MotionWaypoint { time: 10.0, x: 10.0, y: 20.0, altitude: 30.0 },
        ];
 
        let points =
            get_interpolated_motion_path(waypoints, crate::InterpolationType::Linear, 3).unwrap();
 
        assert_eq!(points.len(), 3);
        // Linear interpolation midpoint logic check
        assert_eq!(points[1].x, 5.0);
        assert_eq!(points[1].y, 10.0);
        assert_eq!(points[1].z, 15.0);
        assert_eq!(points[1].vx, 1.0);
        assert_eq!(points[1].vy, 2.0);
        assert_eq!(points[1].vz, 3.0);
    }
 
    #[test]
    fn test_get_interpolated_rotation_path() {
        let waypoints = vec![
            crate::RotationWaypoint { time: 0.0, azimuth: 0.0, elevation: 0.0 },
            crate::RotationWaypoint { time: 10.0, azimuth: 90.0, elevation: 20.0 },
        ];
 
        let points = get_interpolated_rotation_path(
            waypoints,
            crate::InterpolationType::Linear,
            crate::RotationAngleUnit::Deg,
            3,
        )
        .unwrap();
 
        assert_eq!(points.len(), 3);
        // Linear interpolation midpoint logic check
        assert_eq!(points[1].azimuth, 45.0);
        assert_eq!(points[1].elevation, 10.0);
    }
 
    #[test]
    fn test_get_antenna_pattern_invalid_id() {
        let context = FersContext::new().unwrap();
        context.update_scenario_from_json(minimal_valid_json()).unwrap();
 
        // The minimal JSON has no antennas, so ID "99" should definitively fail.
        let result = context.get_antenna_pattern("99", 10, 10, 1e9);
        assert!(result.is_err());
        assert!(result.unwrap_err().contains("not found"));
    }
 
    #[test]
    fn test_calculate_preview_links_empty() {
        let context = FersContext::new().unwrap();
        context.update_scenario_from_json(minimal_valid_json()).unwrap();
 
        // Run on an empty scenario without platforms, shouldn't crash, should return empty vec.
        let links = context.calculate_preview_links(0.0).unwrap();
        assert_eq!(links.len(), 0);
    }
    #[test]
    fn test_fers_owned_string_null() {
        // Test that a null pointer safely converts to an empty string
        let null_str = FersOwnedString(std::ptr::null_mut());
        let result = null_str.into_string();
        assert_eq!(result.unwrap(), "");
 
        // Test that dropping a null pointer doesn't panic or segfault
        let drop_str = FersOwnedString(std::ptr::null_mut());
        drop(drop_str);
    }
 
    #[test]
    fn test_raii_null_drops() {
        // Test that dropping null pointers in our internal RAII wrappers is safe
        let ant_data = FersAntennaPatternData(std::ptr::null_mut());
        drop(ant_data);
 
        let link_list = FersVisualLinkList(std::ptr::null_mut());
        drop(link_list);
    }
 
    #[test]
    fn test_get_interpolated_paths_empty() {
        // Test empty waypoints
        let motion =
            get_interpolated_motion_path(vec![], crate::InterpolationType::Linear, 5).unwrap();
        assert!(motion.is_empty());
 
        let rotation = get_interpolated_rotation_path(
            vec![],
            crate::InterpolationType::Linear,
            crate::RotationAngleUnit::Deg,
            5,
        )
        .unwrap();
        assert!(rotation.is_empty());
 
        // Test zero num_points
        let wp_m = vec![crate::MotionWaypoint { time: 0.0, x: 0.0, y: 0.0, altitude: 0.0 }];
        let motion2 =
            get_interpolated_motion_path(wp_m, crate::InterpolationType::Linear, 0).unwrap();
        assert!(motion2.is_empty());
 
        let wp_r = vec![crate::RotationWaypoint { time: 0.0, azimuth: 0.0, elevation: 0.0 }];
        let rotation2 = get_interpolated_rotation_path(
            wp_r,
            crate::InterpolationType::Linear,
            crate::RotationAngleUnit::Deg,
            0,
        )
        .unwrap();
        assert!(rotation2.is_empty());
    }
 
    #[test]
    fn test_granular_updates() {
        let context = FersContext::new().unwrap();
        context.update_scenario_from_json(scenario_with_assets_json()).unwrap();
 
        // Platform update
        let plat_json = r#"{
                "id": 100,
                "name": "UpdatedPlatform",
                "motionpath": { "interpolation": "static", "positionwaypoints": [] },
                "rotationpath": { "interpolation": "static", "rotationwaypoints": [] }
            }"#;
        let result = context.update_platform_from_json("100", plat_json);
        assert!(result.is_ok(), "Failed to update platform: {:?}", result.err());
 
        // Antenna update
        let ant_json =
            r#"{ "id": 20, "name": "UpdatedAntenna", "pattern": "isotropic", "efficiency": 0.5 }"#;
        let result = context.update_antenna_from_json(ant_json);
        assert!(result.is_ok(), "Failed to update antenna: {:?}", result.err());
 
        // Waveform update
        let wf_json = r#"{ "id": 10, "name": "UpdatedWaveform", "power": 500.0, "carrier_frequency": 1e9, "cw": {} }"#;
        let result = context.update_waveform_from_json(wf_json);
        assert!(result.is_ok(), "Failed to update waveform: {:?}", result.err());
 
        // Verify changes
        let updated_scenario = context.get_scenario_as_json().unwrap();
        assert!(updated_scenario.contains("UpdatedPlatform"));
        assert!(updated_scenario.contains("UpdatedAntenna"));
        assert!(updated_scenario.contains("UpdatedWaveform"));
    }
 
    #[test]
    fn test_granular_updates_invalid() {
        let context = FersContext::new().unwrap();
        context.update_scenario_from_json(scenario_with_assets_json()).unwrap();
 
        assert!(context.update_platform_from_json("999", "{}").is_err());
        assert!(context.update_antenna_from_json("{bad").is_err());
        assert!(context.update_waveform_from_json("{bad").is_err());
    }
 
    #[test]
    fn test_get_antenna_pattern_success() {
        let context = FersContext::new().unwrap();
        let scenario = r#"{
            "simulation": {
                "parameters": {
                    "starttime": 0.0, "endtime": 1.0, "rate": 1000.0,
                    "origin": { "latitude": 0.0, "longitude": 0.0, "altitude": 0.0 },
                    "coordinatesystem": { "frame": "ENU" }
                },
                "antennas": [
                    { "id": 1, "name": "iso", "pattern": "isotropic" }
                ]
            }
        }"#;
        context.update_scenario_from_json(scenario).unwrap();
 
        let pattern = context.get_antenna_pattern("1", 4, 4, 1e9).unwrap();
        assert_eq!(pattern.az_count, 4);
        assert_eq!(pattern.el_count, 4);
        assert_eq!(pattern.gains.len(), 16);
        assert!(pattern.max_gain > 0.0);
    }
 
    #[test]
    fn test_calculate_preview_links_success() {
        let context = FersContext::new().unwrap();
        let scenario = r#"{
            "simulation": {
                "parameters": {
                    "starttime": 0.0, "endtime": 1.0, "rate": 1000.0,
                    "origin": { "latitude": 0.0, "longitude": 0.0, "altitude": 0.0 },
                    "coordinatesystem": { "frame": "ENU" }
                },
                "waveforms": [
                    { "id": 10, "name": "w1", "power": 1000.0, "carrier_frequency": 1e9, "cw": {} }
                ],
                "antennas": [
                    { "id": 20, "name": "a1", "pattern": "isotropic" }
                ],
                "timings": [
                    { "id": 30, "name": "t1", "frequency": 1e6 }
                ],
                "platforms": [
                    {
                        "id": 100, "name": "tx_plat",
                        "motionpath": { "interpolation": "static", "positionwaypoints": [ { "time": 0.0, "x": 0.0, "y": 0.0, "altitude": 0.0 } ] },
                        "rotationpath": { "interpolation": "static", "rotationwaypoints": [ { "time": 0.0, "azimuth": 0.0, "elevation": 0.0 } ] },
                        "components": [ { "transmitter": { "id": 101, "name": "tx1", "waveform": 10, "antenna": 20, "timing": 30, "cw_mode": {} } } ]
                    },
                    {
                        "id": 200, "name": "rx_plat",
                        "motionpath": { "interpolation": "static", "positionwaypoints": [ { "time": 0.0, "x": 100.0, "y": 0.0, "altitude": 0.0 } ] },
                        "rotationpath": { "interpolation": "static", "rotationwaypoints": [ { "time": 0.0, "azimuth": 0.0, "elevation": 0.0 } ] },
                        "components": [ { "receiver": { "id": 201, "name": "rx1", "antenna": 20, "timing": 30, "cw_mode": {}, "noise_temp": 290.0 } } ]
                    }
                ]
            }
        }"#;
        context.update_scenario_from_json(scenario).unwrap();
 
        let links = context.calculate_preview_links(0.0).unwrap();
        assert!(!links.is_empty());
 
        let direct_link =
            links.iter().find(|l| l.link_type == 3).expect("Expected a direct interference link");
        assert_eq!(direct_link.source_id, "101");
        assert_eq!(direct_link.dest_id, "201");
        assert!(direct_link.display_value > -999.0);
    }
}