api.h File Reference

#include <stddef.h>
#include <stdint.h>

Include dependency graph for api.h:

This graph shows which files directly or indirectly include this file:

Go to the source code of this file.

Classes
struct	fers_antenna_pattern_data_t
	Represents a sampled 2D antenna gain pattern. More...
struct	fers_motion_waypoint_t
	Represents a single waypoint for a motion path. More...
struct	fers_rotation_waypoint_t
	Represents a single waypoint for a rotation path. More...
struct	fers_interpolated_point_t
	Represents a single interpolated point on a motion path. More...
struct	fers_interpolated_rotation_point_t
	Represents a single interpolated point on a rotation path. More...
struct	fers_interpolated_path_t
	A container for an array of interpolated motion path points. More...
struct	fers_interpolated_rotation_path_t
	A container for an array of interpolated rotation path points. More...
struct	fers_visual_link_t
	Represents a single renderable line segment metadata. More...
struct	fers_visual_link_list_t
	A container for a list of visual links. More...

Typedefs
typedef struct fers_context	fers_context_t
typedef void(*	fers_progress_callback_t) (const char *message, int current, int total, void *user_data)
	A function pointer type for progress reporting callbacks.
typedef void(*	fers_log_callback_t) (fers_log_level_t level, const char *line, void *user_data)
	A function pointer type for receiving formatted log lines.

Enumerations
enum	fers_log_level_t {   FERS_LOG_TRACE , FERS_LOG_DEBUG , FERS_LOG_INFO , FERS_LOG_WARNING ,   FERS_LOG_ERROR , FERS_LOG_FATAL , FERS_LOG_OFF }
	Log levels for the FERS library. More...
enum	fers_interp_type_t { FERS_INTERP_STATIC , FERS_INTERP_LINEAR , FERS_INTERP_CUBIC }
	Defines the interpolation methods available for path generation. More...
enum	fers_angle_unit_t { FERS_ANGLE_UNIT_DEG , FERS_ANGLE_UNIT_RAD }
	Units used for external rotation angles and rates. More...
enum	fers_link_quality_t { FERS_LINK_STRONG , FERS_LINK_WEAK }
	Quality of the radio link based on SNR. More...
enum	fers_link_type_t { FERS_LINK_MONOSTATIC , FERS_LINK_BISTATIC_TX_TGT , FERS_LINK_BISTATIC_TGT_RX , FERS_LINK_DIRECT_TX_RX }
	Type of visual link to render. More...

Functions
fers_context_t *	fers_context_create ()
	Creates a new FERS simulation context.
void	fers_context_destroy (fers_context_t *context)
	Destroys a FERS simulation context and releases all associated memory.
int	fers_set_output_directory (fers_context_t *context, const char *out_dir)
	Sets the output directory for simulation results.
int	fers_configure_logging (fers_log_level_t level, const char *log_file_path)
	Configures the internal logger.
fers_log_level_t	fers_get_log_level ()
	Returns the current internal logger level.
void	fers_set_log_callback (fers_log_callback_t callback, void *user_data)
	Registers a callback for formatted log lines.
void	fers_log (fers_log_level_t level, const char *message)
	Submits a log message to the library's unified logging system.
int	fers_set_thread_count (unsigned num_threads)
	Sets the number of worker threads for the simulation.
int	fers_load_scenario_from_xml_file (fers_context_t *context, const char *xml_filepath, int validate)
	Loads a scenario into the context from a FERS XML file.
int	fers_load_scenario_from_xml_string (fers_context_t *context, const char *xml_content, int validate)
	Loads a scenario into the context from a FERS XML string.
char *	fers_get_scenario_as_json (fers_context_t *context)
	Serializes the current simulation scenario into a JSON string.
char *	fers_get_scenario_as_xml (fers_context_t *context)
	Serializes the current simulation scenario into a FERS XML string.
char *	fers_get_last_output_metadata_json (fers_context_t *context)
	Returns JSON metadata for the most recent simulation output files.
int	fers_update_scenario_from_json (fers_context_t *context, const char *scenario_json)
	Updates the simulation scenario from a JSON string.
int	fers_update_platform_from_json (fers_context_t *context, uint64_t id, const char *json)
	Updates a single platform's paths and name from JSON without full context recreation.
int	fers_update_parameters_from_json (fers_context_t *context, const char *json)
	Updates the global simulation parameters from JSON without full context recreation.
int	fers_update_antenna_from_json (fers_context_t *context, const char *json)
	Updates a single antenna from JSON without full context recreation.
int	fers_update_waveform_from_json (fers_context_t *context, const char *json)
	Updates a single waveform from JSON without full context recreation.
int	fers_update_transmitter_from_json (fers_context_t *context, uint64_t id, const char *json)
	Updates a single transmitter from JSON without full context recreation.
int	fers_update_receiver_from_json (fers_context_t *context, uint64_t id, const char *json)
	Updates a single receiver from JSON without full context recreation.
int	fers_update_target_from_json (fers_context_t *context, uint64_t id, const char *json)
	Updates a single target from JSON without full context recreation.
int	fers_update_monostatic_from_json (fers_context_t *context, const char *json)
	Updates a monostatic radar from JSON without full context recreation.
int	fers_update_timing_from_json (fers_context_t *context, uint64_t id, const char *json)
	Updates a single timing source from JSON without full context recreation.
char *	fers_get_last_error_message ()
	Retrieves the last error message that occurred on the current thread.
char *	fers_get_last_warning_messages_json ()
	Returns the last deduplicated rotation-unit warning list for the calling thread as JSON.
void	fers_free_string (char *str)
	Frees a string that was allocated and returned by the libfers API.
int	fers_run_simulation (fers_context_t *context, fers_progress_callback_t callback, void *user_data)
	Runs the simulation defined in the provided context.
int	fers_generate_kml (const fers_context_t *context, const char *output_kml_filepath)
	Generates a KML file for visualizing the scenario in the context.
fers_antenna_pattern_data_t *	fers_get_antenna_pattern (const fers_context_t *context, uint64_t antenna_id, size_t az_samples, size_t el_samples, double frequency_hz)
	Samples the gain pattern of a specified antenna and provides the data.
void	fers_free_antenna_pattern_data (fers_antenna_pattern_data_t *data)
	Frees the memory allocated for an antenna pattern data structure.
fers_interpolated_path_t *	fers_get_interpolated_motion_path (const fers_motion_waypoint_t *waypoints, size_t waypoint_count, fers_interp_type_t interp_type, size_t num_points)
	Calculates an interpolated motion path from a set of waypoints.
void	fers_free_interpolated_motion_path (fers_interpolated_path_t *path)
	Frees the memory allocated for an interpolated motion path.
fers_interpolated_rotation_path_t *	fers_get_interpolated_rotation_path (const fers_rotation_waypoint_t *waypoints, size_t waypoint_count, fers_interp_type_t interp_type, fers_angle_unit_t angle_unit, size_t num_points)
	Calculates an interpolated rotation path from a set of waypoints.
void	fers_free_interpolated_rotation_path (fers_interpolated_rotation_path_t *path)
	Frees the memory allocated for an interpolated rotation path.
fers_visual_link_list_t *	fers_calculate_preview_links (const fers_context_t *context, double time)
	Calculates visual links for a specific simulation time.
void	fers_free_preview_links (fers_visual_link_list_t *list)
	Frees the memory allocated for a preview link list.

Typedef Documentation

fers_context_t

typedef struct fers_context fers_context_t

Definition at line 26 of file api.h.

fers_log_callback_t

typedef void(* fers_log_callback_t) (fers_log_level_t level, const char *line, void *user_data)

A function pointer type for receiving formatted log lines.

Parameters

level	The severity level of the log line.
line	The full formatted log line, without a trailing newline.
user_data	An opaque pointer passed back to the caller.

Definition at line 103 of file api.h.

fers_progress_callback_t

typedef void(* fers_progress_callback_t) (const char *message, int current, int total, void *user_data)

A function pointer type for progress reporting callbacks.

This callback can be implemented by the client to receive progress updates during long-running operations like fers_run_simulation.

Parameters

message	A descriptive message about the current operation.
current	The current progress step.
total	The total number of steps for the operation.
user_data	An opaque pointer passed back to the caller, useful for maintaining state (e.g., a class instance or application handle).

Definition at line 40 of file api.h.

Enumeration Type Documentation

fers_angle_unit_t

enum fers_angle_unit_t

Units used for external rotation angles and rates.

Enumerator
FERS_ANGLE_UNIT_DEG
FERS_ANGLE_UNIT_RAD

Definition at line 456 of file api.h.

{
    FERS_ANGLE_UNIT_DEG,
    FERS_ANGLE_UNIT_RAD
} fers_angle_unit_t;

fers_interp_type_t

enum fers_interp_type_t

Defines the interpolation methods available for path generation.

This enum provides a language-agnostic way to specify the desired interpolation algorithm when calling the path generation functions.

Enumerator
FERS_INTERP_STATIC
FERS_INTERP_LINEAR
FERS_INTERP_CUBIC

Definition at line 446 of file api.h.

{
    FERS_INTERP_STATIC,
    FERS_INTERP_LINEAR,
    FERS_INTERP_CUBIC
} fers_interp_type_t;

fers_link_quality_t

enum fers_link_quality_t

Quality of the radio link based on SNR.

Enumerator
FERS_LINK_STRONG
FERS_LINK_WEAK

Definition at line 583 of file api.h.

{
    FERS_LINK_STRONG, // SNR > 0 dB
    FERS_LINK_WEAK // SNR < 0 dB (Geometric possibility but sub-noise)
} fers_link_quality_t;

fers_link_type_t

enum fers_link_type_t

Type of visual link to render.

Enumerator
FERS_LINK_MONOSTATIC
FERS_LINK_BISTATIC_TX_TGT
FERS_LINK_BISTATIC_TGT_RX
FERS_LINK_DIRECT_TX_RX

Definition at line 592 of file api.h.

{
    FERS_LINK_MONOSTATIC, // Combined Tx/Rx path
    FERS_LINK_BISTATIC_TX_TGT, // Illuminator path
    FERS_LINK_BISTATIC_TGT_RX, // Scattered path
    FERS_LINK_DIRECT_TX_RX // Interference path
} fers_link_type_t;

fers_log_level_t

enum fers_log_level_t

Log levels for the FERS library.

Enumerator
FERS_LOG_TRACE
FERS_LOG_DEBUG
FERS_LOG_INFO
FERS_LOG_WARNING
FERS_LOG_ERROR
FERS_LOG_FATAL
FERS_LOG_OFF

Definition at line 85 of file api.h.

{
    FERS_LOG_TRACE,
    FERS_LOG_DEBUG,
    FERS_LOG_INFO,
    FERS_LOG_WARNING,
    FERS_LOG_ERROR,
    FERS_LOG_FATAL,
    FERS_LOG_OFF
} fers_log_level_t;

Function Documentation

fers_calculate_preview_links()

fers_visual_link_list_t * fers_calculate_preview_links	(	const fers_context_t *	context,
		double	time
	)

Calculates visual links for a specific simulation time.

Parameters

context	The simulation context.
time	The simulation time in seconds.

Returns

A pointer to a link list. Caller must free with fers_free_preview_links.

Definition at line 1137 of file api.cpp.

{
    last_error_message.clear();
    if (context == nullptr)
    {
        last_error_message = "Invalid context passed to fers_calculate_preview_links";
        LOG(logging::Level::ERROR, last_error_message);
        return nullptr;
    }
 
    try
    {
        const auto* ctx = reinterpret_cast<const FersContext*>(context);
        // Call the core physics logic in channel_model.cpp
        const auto cpp_links = simulation::calculatePreviewLinks(*ctx->getWorld(), time);
 
        // Convert C++ vector to C-API struct
        auto* result = new fers_visual_link_list_t();
        result->count = cpp_links.size();
 
        if (!cpp_links.empty())
        {
            result->links = new fers_visual_link_t[result->count];
            for (size_t i = 0; i < result->count; ++i)
            {
                const auto& src = cpp_links[i];
                auto& dst = result->links[i];
 
                // Map enums
                switch (src.type)
                {
                case simulation::LinkType::Monostatic:
                    dst.type = FERS_LINK_MONOSTATIC;
                    break;
                case simulation::LinkType::BistaticTxTgt:
                    dst.type = FERS_LINK_BISTATIC_TX_TGT;
                    break;
                case simulation::LinkType::BistaticTgtRx:
                    dst.type = FERS_LINK_BISTATIC_TGT_RX;
                    break;
                case simulation::LinkType::DirectTxRx:
                    dst.type = FERS_LINK_DIRECT_TX_RX;
                    break;
                }
 
                dst.quality = (src.quality == simulation::LinkQuality::Strong) ? FERS_LINK_STRONG : FERS_LINK_WEAK;
 
                // Safe string copy
                std::strncpy(dst.label, src.label.c_str(), sizeof(dst.label) - 1);
                dst.label[sizeof(dst.label) - 1] = '\0';
 
                dst.source_id = static_cast<uint64_t>(src.source_id);
                dst.dest_id = static_cast<uint64_t>(src.dest_id);
                dst.origin_id = static_cast<uint64_t>(src.origin_id);
            }
        }
        else
        {
            result->links = nullptr;
        }
        return result;
    }
    catch (const std::exception& e)
    {
        handle_api_exception(e, "fers_calculate_preview_links");
        return nullptr;
    }
}

References simulation::BistaticTgtRx, simulation::BistaticTxTgt, simulation::calculatePreviewLinks(), simulation::DirectTxRx, logging::ERROR, FERS_LINK_BISTATIC_TGT_RX, FERS_LINK_BISTATIC_TX_TGT, FERS_LINK_DIRECT_TX_RX, FERS_LINK_MONOSTATIC, FERS_LINK_STRONG, FERS_LINK_WEAK, handle_api_exception(), last_error_message, LOG, simulation::Monostatic, simulation::Strong, and fers_visual_link_t::type.

Here is the call graph for this function:

fers_configure_logging()

int fers_configure_logging	(	fers_log_level_t	level,
		const char *	log_file_path
	)

Configures the internal logger.

Parameters

level	The minimum severity level to log.
log_file_path	Optional path to a log file. Pass NULL to disable file logging.

Returns

0 on success, non-zero on error.

Definition at line 188 of file api.cpp.

{
    last_error_message.clear();
    try
    {
        logging::logger.setLevel(map_api_log_level(level));
        if ((log_file_path != nullptr) && ((*log_file_path) != 0))
        {
            auto result = logging::logger.logToFile(log_file_path);
            if (!result)
            {
                last_error_message = result.error();
                return 1;
            }
        }
        return 0;
    }
    catch (const std::exception& e)
    {
        handle_api_exception(e, "fers_configure_logging");
        return 1;
    }
}

References handle_api_exception(), last_error_message, logging::logger, logging::Logger::logToFile(), map_api_log_level(), and logging::Logger::setLevel().

Referenced by main().

Here is the call graph for this function:

Here is the caller graph for this function:

fers_context_create()

fers_context_t * fers_context_create

(

)

Creates a new FERS simulation context.

Allocates and initializes a new, empty simulation context in memory. This context serves as the container for a scenario loaded via one of the fers_load_... or fers_update_... functions.

Note

In a C API, RAII is not available. The caller is responsible for destroying the returned context using fers_context_destroy() to prevent resource leaks.

Returns

A non-null opaque pointer (handle) to the simulation context on success. Returns NULL on failure (e.g., out of memory).

Definition at line 88 of file api.cpp.

{
    last_error_message.clear();
    discard_warning_capture();
    try
    {
        return new fers_context_t();
    }
    catch (const std::bad_alloc& e)
    {
        handle_api_exception(e, "fers_context_create");
        return nullptr;
    }
    catch (const std::exception& e)
    {
        handle_api_exception(e, "fers_context_create");
        return nullptr;
    }
}

References discard_warning_capture(), handle_api_exception(), and last_error_message.

Referenced by main().

Here is the call graph for this function:

Here is the caller graph for this function:

fers_context_destroy()

void fers_context_destroy

(

fers_context_t *

context

)

Destroys a FERS simulation context and releases all associated memory.

This function must be called for every context created by fers_context_create() to ensure proper cleanup of the underlying C++ objects. Accessing the context handle after calling this function results in undefined behavior.

Parameters

context

A valid pointer to a fers_context_t handle. If context is NULL, the function performs no action for safety and does not set an error.

Definition at line 108 of file api.cpp.

{
    if (context == nullptr)
    {
        return;
    }
    delete context;
}

Referenced by main().

Here is the caller graph for this function:

fers_free_antenna_pattern_data()

void fers_free_antenna_pattern_data

(

fers_antenna_pattern_data_t *

data

)

Frees the memory allocated for an antenna pattern data structure.

Parameters

data	A pointer to the fers_antenna_pattern_data_t struct to free.

Definition at line 1126 of file api.cpp.

{
    if (data != nullptr)
    {
        delete[] data->gains;
        delete data;
    }
}

References fers_antenna_pattern_data_t::gains.

fers_free_interpolated_motion_path()

void fers_free_interpolated_motion_path

(

fers_interpolated_path_t *

path

)

Frees the memory allocated for an interpolated motion path.

Parameters

path	A pointer to the fers_interpolated_path_t struct to free.

Definition at line 933 of file api.cpp.

{
    if (path != nullptr)
    {
        delete[] path->points;
        delete path;
    }
}

References fers_interpolated_path_t::points.

fers_free_interpolated_rotation_path()

void fers_free_interpolated_rotation_path

(

fers_interpolated_rotation_path_t *

path

)

Frees the memory allocated for an interpolated rotation path.

Parameters

path	A pointer to the fers_interpolated_rotation_path_t struct to free.

Definition at line 1029 of file api.cpp.

{
    if (path != nullptr)
    {
        delete[] path->points;
        delete path;
    }
}

References fers_interpolated_rotation_path_t::points.

fers_free_preview_links()

void fers_free_preview_links

(

fers_visual_link_list_t *

list

)

Frees the memory allocated for a preview link list.

Parameters

list	The list to free.

Definition at line 1206 of file api.cpp.

{
    if (list != nullptr)
    {
        delete[] list->links;
        delete list;
    }
}

References fers_visual_link_list_t::links.

fers_free_string()

void fers_free_string

(

char *

str

)

Frees a string that was allocated and returned by the libfers API.

This function must be used to release memory for any string returned by functions like fers_get_scenario_as_json or fers_get_last_error_message. It exists to ensure that the memory deallocation mechanism (free) matches the allocation mechanism (strdup/malloc) used within the C++ library, preventing potential crashes from mismatched allocators across language boundaries.

Parameters

str	A pointer to the string to be freed. If str is NULL, no action is taken.

Definition at line 752 of file api.cpp.

{
    if (str != nullptr)
    {
        free(str);
    }
}

Referenced by main().

Here is the caller graph for this function:

fers_generate_kml()

int fers_generate_kml	(	const fers_context_t *	context,
		const char *	output_kml_filepath
	)

Generates a KML file for visualizing the scenario in the context.

This utility exists to provide a simple, out-of-the-box method for users to validate and visualize the geographic layout and motion paths of their scenarios in common external tools like Google Earth.

Parameters

context	A valid fers_context_t handle containing a loaded scenario.
output_kml_filepath	A null-terminated UTF-8 string for the output KML file path.

Returns

0 on success, a non-zero error code on failure. Use fers_get_last_error_message() to retrieve error details.

Definition at line 798 of file api.cpp.

{
    last_error_message.clear();
    if ((context == nullptr) || (output_kml_filepath == nullptr))
    {
        last_error_message = "Invalid arguments: context or output_kml_filepath is NULL.";
        LOG(logging::Level::ERROR, last_error_message);
        return -1;
    }
 
    const auto* ctx = reinterpret_cast<const FersContext*>(context);
 
    try
    {
        if (serial::KmlGenerator::generateKml(*ctx->getWorld(), output_kml_filepath))
        {
            return 0; // Success
        }
 
        last_error_message = "KML generation failed for an unknown reason.";
        LOG(logging::Level::ERROR, last_error_message);
        return 2; // Generation failed
    }
    catch (const std::exception& e)
    {
        handle_api_exception(e, "fers_generate_kml");
        return 1; // Exception thrown
    }
}

References logging::ERROR, serial::KmlGenerator::generateKml(), handle_api_exception(), last_error_message, and LOG.

Referenced by main().

Here is the call graph for this function:

Here is the caller graph for this function:

fers_get_antenna_pattern()

fers_antenna_pattern_data_t * fers_get_antenna_pattern	(	const fers_context_t *	context,
		uint64_t	antenna_id,
		size_t	az_samples,
		size_t	el_samples,
		double	frequency_hz
	)

Samples the gain pattern of a specified antenna and provides the data.

This function calculates the antenna's far-field gain at a specified resolution over the full sphere of directions (azimuth and elevation). The resulting gain values are linear (not in dB) and normalized relative to the pattern's peak gain. This is a stateless utility useful for UI previews and analysis.

Parameters

context	A valid fers_context_t handle containing a loaded scenario with the antenna.
antenna_id	The unique ID of the antenna asset to sample.
az_samples	The desired number of sample points along the azimuth axis. Must be at least 2 to span the full azimuth range.
el_samples	The desired number of sample points along the elevation axis. Must be at least 2 to span the full elevation range.
frequency_hz	The frequency in Hz to use for gain calculation (affects aperture antennas).

Returns

A pointer to a fers_antenna_pattern_data_t struct containing the results. Returns NULL on failure (e.g., antenna not found). The caller owns the returned struct and must free it with fers_free_antenna_pattern_data.

Definition at line 1040 of file api.cpp.

{
    last_error_message.clear();
    if ((context == nullptr) || az_samples < 2 || el_samples < 2)
    {
        last_error_message = "Invalid arguments: context must be non-null and sample counts must be >= 2.";
        LOG(logging::Level::ERROR, last_error_message);
        return nullptr;
    }
 
    try
    {
        const auto* ctx = reinterpret_cast<const FersContext*>(context);
        antenna::Antenna* ant = ctx->getWorld()->findAntenna(static_cast<SimId>(antenna_id));
 
        if (ant == nullptr)
        {
            last_error_message = "Antenna ID '" + std::to_string(antenna_id) + "' not found in the world.";
            LOG(logging::Level::ERROR, last_error_message);
            return nullptr;
        }
 
        // TODO: Currently only using the first-found waveform. This is incorrect but also difficult to represent
        //       correctly in scenarios with multiple waveforms as the gain for squarehorn and parabolic antennas
        // depends on        the wavelength. Hence a decision needs to be made about whether to return multiple patterns
        // per waveform or       have the user specify a representative wavelength in the UI per antenna.
        // Calculate wavelength from the provided frequency.
        // Default to 1GHz (0.3m) if frequency is invalid/zero, though the UI should prevent this
        // for antennas that strictly require it (Horn/Parabolic).
        RealType wavelength = 0.3;
        if (frequency_hz > 0.0)
        {
            wavelength = params::c() / frequency_hz;
        }
 
        auto* data = new fers_antenna_pattern_data_t();
        data->az_count = az_samples;
        data->el_count = el_samples;
        const size_t total_samples = az_samples * el_samples;
        data->gains = new double[total_samples];
 
        // The reference angle (boresight) is implicitly the local X-axis in the FERS engine.
        // We pass a zero rotation to get the gain relative to this boresight.
        const math::SVec3 ref_angle(1.0, 0.0, 0.0);
        double max_gain = 0.0;
 
        const RealType az_denominator = static_cast<RealType>(az_samples - 1);
        const RealType el_denominator = static_cast<RealType>(el_samples - 1);
 
        for (size_t i = 0; i < el_samples; ++i)
        {
            // Elevation from -PI/2 to PI/2
            const RealType elevation = (static_cast<RealType>(i) / el_denominator) * PI - (PI / 2.0);
            for (size_t j = 0; j < az_samples; ++j)
            {
                // Azimuth from -PI to PI
                const RealType azimuth = (static_cast<RealType>(j) / az_denominator) * 2.0 * PI - PI;
                const math::SVec3 sample_angle(1.0, azimuth, elevation);
                const RealType gain = ant->getGain(sample_angle, ref_angle, wavelength);
                data->gains[i * az_samples + j] = gain;
                max_gain = std::max(gain, max_gain);
            }
        }
 
        data->max_gain = max_gain;
 
        // Normalize the gains
        if (max_gain > 0)
        {
            for (size_t i = 0; i < total_samples; ++i)
            {
                data->gains[i] /= max_gain;
            }
        }
 
        return data;
    }
    catch (const std::exception& e)
    {
        handle_api_exception(e, "fers_get_antenna_pattern");
        return nullptr;
    }
}

References params::c(), logging::ERROR, antenna::Antenna::getGain(), handle_api_exception(), last_error_message, LOG, and PI.

Here is the call graph for this function:

fers_get_interpolated_motion_path()

fers_interpolated_path_t * fers_get_interpolated_motion_path	(	const fers_motion_waypoint_t *	waypoints,
		size_t	waypoint_count,
		fers_interp_type_t	interp_type,
		size_t	num_points
	)

Calculates an interpolated motion path from a set of waypoints.

This function is a stateless utility that computes the path without needing a full simulation context. It is useful for UI previews.

Parameters

waypoints	An array of fers_motion_waypoint_t structs.
waypoint_count	The number of waypoints in the array.
interp_type	The interpolation algorithm to use.
num_points	The desired number of points in the output interpolated path.

Returns

A pointer to a fers_interpolated_path_t struct containing the results. Returns NULL on failure. The caller owns the returned struct and must free it with fers_free_interpolated_motion_path.

Definition at line 858 of file api.cpp.

{
    last_error_message.clear();
    if ((waypoints == nullptr) || waypoint_count == 0 || num_points == 0)
    {
        last_error_message = "Invalid arguments: waypoints cannot be null and counts must be > 0.";
        LOG(logging::Level::ERROR, last_error_message);
        return nullptr;
    }
    if (interp_type == FERS_INTERP_CUBIC && waypoint_count < 2)
    {
        last_error_message = "Cubic interpolation requires at least 2 waypoints.";
        LOG(logging::Level::ERROR, last_error_message);
        return nullptr;
    }
 
    try
    {
        math::Path path;
        path.setInterp(to_cpp_interp_type(interp_type));
 
        for (size_t i = 0; i < waypoint_count; ++i)
        {
            math::Coord c;
            c.t = waypoints[i].time;
            c.pos.x = waypoints[i].x;
            c.pos.y = waypoints[i].y;
            c.pos.z = waypoints[i].z;
            path.addCoord(c);
        }
 
        path.finalize();
 
        auto* result_path = new fers_interpolated_path_t();
        result_path->points = new fers_interpolated_point_t[num_points];
        result_path->count = num_points;
 
        const double start_time = waypoints[0].time;
        const double end_time = waypoints[waypoint_count - 1].time;
        const double duration = end_time - start_time;
 
        // Handle static case separately
        if (waypoint_count < 2 || duration <= 0)
        {
            const math::Vec3 pos = path.getPosition(start_time);
            for (size_t i = 0; i < num_points; ++i)
            {
                result_path->points[i] = {pos.x, pos.y, pos.z, 0.0, 0.0, 0.0};
            }
            return result_path;
        }
 
        const double time_step =
            duration / static_cast<double>(num_points > 1 ? num_points - 1 : static_cast<size_t>(1));
 
        for (size_t i = 0; i < num_points; ++i)
        {
            const double t = start_time + static_cast<double>(i) * time_step;
            const math::Vec3 pos = path.getPosition(t);
            const math::Vec3 vel = path.getVelocity(t);
            result_path->points[i] = {pos.x, pos.y, pos.z, vel.x, vel.y, vel.z};
        }
 
        return result_path;
    }
    catch (const std::exception& e)
    {
        handle_api_exception(e, "fers_get_interpolated_motion_path");
        return nullptr;
    }
}

References math::Path::addCoord(), logging::ERROR, FERS_INTERP_CUBIC, math::Path::finalize(), math::Path::getPosition(), math::Path::getVelocity(), handle_api_exception(), last_error_message, LOG, math::Path::setInterp(), fers_motion_waypoint_t::time, to_cpp_interp_type(), fers_motion_waypoint_t::x, math::Vec3::x, fers_motion_waypoint_t::y, math::Vec3::y, fers_motion_waypoint_t::z, and math::Vec3::z.

Here is the call graph for this function:

fers_get_interpolated_rotation_path()

fers_interpolated_rotation_path_t * fers_get_interpolated_rotation_path	(	const fers_rotation_waypoint_t *	waypoints,
		size_t	waypoint_count,
		fers_interp_type_t	interp_type,
		fers_angle_unit_t	angle_unit,
		size_t	num_points
	)

Calculates an interpolated rotation path from a set of waypoints.

This function is a stateless utility for UI previews.

Parameters

waypoints	An array of fers_rotation_waypoint_t structs.
waypoint_count	The number of waypoints in the array.
interp_type	The interpolation algorithm to use (STATIC, LINEAR, CUBIC).
angle_unit	The unit used by the waypoint angles and desired output angles.
num_points	The desired number of points in the output interpolated path.

Returns

A pointer to a fers_interpolated_rotation_path_t struct containing the results. Returns NULL on failure. The caller owns the returned struct and must free it with fers_free_interpolated_rotation_path.

Definition at line 942 of file api.cpp.

{
    last_error_message.clear();
    last_warning_messages.clear();
    serial::rotation_warning_utils::clear_captured_warnings();
    if ((waypoints == nullptr) || waypoint_count == 0 || num_points == 0)
    {
        last_error_message = "Invalid arguments: waypoints cannot be null and counts must be > 0.";
        LOG(logging::Level::ERROR, last_error_message);
        return nullptr;
    }
    if (interp_type == FERS_INTERP_CUBIC && waypoint_count < 2)
    {
        last_error_message = "Cubic interpolation requires at least 2 waypoints.";
        LOG(logging::Level::ERROR, last_error_message);
        return nullptr;
    }
 
    try
    {
        const auto unit =
            angle_unit == FERS_ANGLE_UNIT_RAD ? params::RotationAngleUnit::Radians : params::RotationAngleUnit::Degrees;
        math::RotationPath path;
        path.setInterp(to_cpp_rot_interp_type(interp_type));
 
        for (size_t i = 0; i < waypoint_count; ++i)
        {
            serial::rotation_warning_utils::maybe_warn_about_rotation_value(
                waypoints[i].azimuth, unit, serial::rotation_warning_utils::ValueKind::Angle, "C-API",
                std::format("rotation waypoint {}", i), "azimuth");
            serial::rotation_warning_utils::maybe_warn_about_rotation_value(
                waypoints[i].elevation, unit, serial::rotation_warning_utils::ValueKind::Angle, "C-API",
                std::format("rotation waypoint {}", i), "elevation");
            path.addCoord(serial::rotation_angle_utils::external_rotation_to_internal(
                waypoints[i].azimuth, waypoints[i].elevation, waypoints[i].time, unit));
        }
 
        path.finalize();
 
        auto* result_path = new fers_interpolated_rotation_path_t();
        result_path->points = new fers_interpolated_rotation_point_t[num_points];
        result_path->count = num_points;
 
        const double start_time = waypoints[0].time;
        const double end_time = waypoints[waypoint_count - 1].time;
        const double duration = end_time - start_time;
 
        // Handle static case separately
        if (waypoint_count < 2 || duration <= 0)
        {
            const math::SVec3 rot = path.getPosition(start_time);
            for (size_t i = 0; i < num_points; ++i)
            {
                result_path->points[i] = fers_interpolated_rotation_point_t{
                    serial::rotation_angle_utils::internal_azimuth_to_external(rot.azimuth, unit),
                    serial::rotation_angle_utils::internal_elevation_to_external(rot.elevation, unit)};
            }
            return result_path;
        }
 
        const double time_step =
            duration / static_cast<double>(num_points > 1 ? num_points - 1 : static_cast<size_t>(1));
 
        for (size_t i = 0; i < num_points; ++i)
        {
            const double t = start_time + static_cast<double>(i) * time_step;
            const math::SVec3 rot = path.getPosition(t);
 
            result_path->points[i] = fers_interpolated_rotation_point_t{
                serial::rotation_angle_utils::internal_azimuth_to_external(rot.azimuth, unit),
                serial::rotation_angle_utils::internal_elevation_to_external(rot.elevation, unit)};
        }
 
        return result_path;
    }
    catch (const std::exception& e)
    {
        serial::rotation_warning_utils::clear_captured_warnings();
        handle_api_exception(e, "fers_get_interpolated_rotation_path");
        return nullptr;
    }
}

References math::RotationPath::addCoord(), serial::rotation_warning_utils::Angle, math::SVec3::azimuth, serial::rotation_warning_utils::clear_captured_warnings(), params::Degrees, math::SVec3::elevation, logging::ERROR, serial::rotation_angle_utils::external_rotation_to_internal(), FERS_ANGLE_UNIT_RAD, FERS_INTERP_CUBIC, math::RotationPath::finalize(), math::RotationPath::getPosition(), handle_api_exception(), serial::rotation_angle_utils::internal_azimuth_to_external(), serial::rotation_angle_utils::internal_elevation_to_external(), last_error_message, last_warning_messages, LOG, serial::rotation_warning_utils::maybe_warn_about_rotation_value(), params::Radians, math::RotationPath::setInterp(), fers_rotation_waypoint_t::time, and to_cpp_rot_interp_type().

Here is the call graph for this function:

fers_get_last_error_message()

char * fers_get_last_error_message

(

)

Retrieves the last error message that occurred on the current thread.

Because C++ exceptions cannot safely propagate across the FFI boundary into other languages, this function provides the standard C-style error reporting mechanism. The error state is stored in a thread-local variable to ensure that concurrent API calls from different threads do not overwrite each other's error messages. The error is cleared at the start of each fallible API call.

Note

Memory Management: The returned string's ownership is transferred to the caller. It MUST be freed using fers_free_string() to prevent memory leaks.

Returns

A dynamically allocated, null-terminated C-string containing the last error message, or NULL if no error has occurred.

Definition at line 728 of file api.cpp.

{
    if (last_error_message.empty())
    {
        return nullptr; // No error to report
    }
    // `strdup` allocates with `malloc`, which is part of the C standard ABI,
    // making it safe to transfer ownership across the FFI boundary. The caller
    // must then free this memory using `fers_free_string`.
    return strdup(last_error_message.c_str());
}

References last_error_message.

Referenced by main().

Here is the caller graph for this function:

fers_get_last_output_metadata_json()

char * fers_get_last_output_metadata_json

(

fers_context_t *

context

)

Returns JSON metadata for the most recent simulation output files.

The returned JSON describes generated HDF5 file structure and sample ranges. The caller owns the returned string and must free it with fers_free_string. If no simulation has completed yet, the returned JSON contains an empty files array.

Parameters

context

A valid fers_context_t handle.

Returns

A heap-allocated JSON string, or NULL on error.

Definition at line 427 of file api.cpp.

{
    last_error_message.clear();
    if (context == nullptr)
    {
        last_error_message = "Invalid context provided to fers_get_last_output_metadata_json.";
        LOG(logging::Level::ERROR, last_error_message);
        return nullptr;
    }
 
    const auto* ctx = reinterpret_cast<FersContext*>(context);
    try
    {
        const std::string json_str = ctx->getLastOutputMetadataJson();
        return strdup(json_str.c_str());
    }
    catch (const std::exception& e)
    {
        handle_api_exception(e, "fers_get_last_output_metadata_json");
        return nullptr;
    }
}

References logging::ERROR, FersContext::getLastOutputMetadataJson(), handle_api_exception(), last_error_message, and LOG.

Here is the call graph for this function:

fers_get_last_warning_messages_json()

char * fers_get_last_warning_messages_json

(

)

Returns the last deduplicated rotation-unit warning list for the calling thread as JSON.

The returned value is a JSON array of strings. It is populated by successful XML/JSON load and update calls that detect suspicious rotation values. The caller owns the string and must free it with fers_free_string().

Returns

A dynamically allocated JSON array string, or NULL if no warnings are available.

Definition at line 740 of file api.cpp.

{
    if (last_warning_messages.empty())
    {
        return nullptr;
    }
 
    const std::string warning_json = nlohmann::json(last_warning_messages).dump();
    last_warning_messages.clear();
    return strdup(warning_json.c_str());
}

References last_warning_messages.

fers_get_log_level()

fers_log_level_t fers_get_log_level

(

)

Returns the current internal logger level.

Definition at line 212 of file api.cpp.

{ return map_internal_log_level(logging::logger.getLevel()); }

References logging::logger, and map_internal_log_level().

Here is the call graph for this function:

fers_get_scenario_as_json()

char * fers_get_scenario_as_json

(

fers_context_t *

context

)

Serializes the current simulation scenario into a JSON string.

This function is the primary method for the UI to retrieve the full state of the simulation. JSON is used as the interchange format because it is lightweight, human-readable, and natively supported by web technologies, making it trivial to parse and use in the React/TypeScript frontend.

Note

Memory Management: The returned string is allocated by this library and its ownership is transferred to the caller. It is crucial to free this string using fers_free_string() to prevent memory leaks.

Parameters

context

A valid fers_context_t handle.

Returns

A dynamically allocated, null-terminated C-string containing the JSON representation of the scenario. Returns NULL on failure.

Definition at line 370 of file api.cpp.

{
    last_error_message.clear();
    if (context == nullptr)
    {
        last_error_message = "Invalid context provided to fers_get_scenario_as_json.";
        LOG(logging::Level::ERROR, last_error_message);
        return nullptr;
    }
 
    const auto* ctx = reinterpret_cast<FersContext*>(context);
    try
    {
        const nlohmann::json j = serial::world_to_json(*ctx->getWorld());
        const std::string json_str = j.dump(2);
        // A heap-allocated copy of the string is returned. This is necessary
        // to transfer ownership of the memory across the FFI boundary to a
        // client that will free it using `fers_free_string`.
        return strdup(json_str.c_str());
    }
    catch (const std::exception& e)
    {
        handle_api_exception(e, "fers_get_scenario_as_json");
        return nullptr;
    }
}

References logging::ERROR, handle_api_exception(), last_error_message, LOG, and serial::world_to_json().

Here is the call graph for this function:

fers_get_scenario_as_xml()

char * fers_get_scenario_as_xml

(

fers_context_t *

context

)

Serializes the current simulation scenario into a FERS XML string.

This function enables exporting the in-memory state back into the standard FERS XML file format. This is essential for interoperability with legacy tools and for allowing a user to save a scenario that was created or modified in the UI.

Note

Memory Management: The returned string is dynamically allocated and its ownership is transferred to the caller. It must be freed using fers_free_string() to prevent memory leaks.

Parameters

context

A valid fers_context_t handle.

Returns

A dynamically allocated, null-terminated C-string containing the XML representation of the scenario. Returns NULL on failure.

Definition at line 397 of file api.cpp.

{
    last_error_message.clear();
    if (context == nullptr)
    {
        last_error_message = "Invalid context provided to fers_get_scenario_as_xml.";
        LOG(logging::Level::ERROR, last_error_message);
        return nullptr;
    }
 
    const auto* ctx = reinterpret_cast<FersContext*>(context);
    try
    {
        const std::string xml_str = serial::world_to_xml_string(*ctx->getWorld());
        if (xml_str.empty())
        {
            throw std::runtime_error("XML serialization resulted in an empty string.");
        }
        // `strdup` is used to create a heap-allocated string that can be safely
        // passed across the FFI boundary. The client is responsible for freeing
        // this memory with `fers_free_string`.
        return strdup(xml_str.c_str());
    }
    catch (const std::exception& e)
    {
        handle_api_exception(e, "fers_get_scenario_as_xml");
        return nullptr;
    }
}

References logging::ERROR, handle_api_exception(), last_error_message, LOG, and serial::world_to_xml_string().

Here is the call graph for this function:

fers_load_scenario_from_xml_file()

int fers_load_scenario_from_xml_file	(	fers_context_t *	context,
		const char *	xml_filepath,
		int	validate
	)

Loads a scenario into the context from a FERS XML file.

This is the standard method for initializing a simulation context from a file on disk. It is essential for interoperability with the CLI and legacy workflows that rely on the FERS XML format.

Parameters

context	A valid fers_context_t handle.
xml_filepath	A null-terminated UTF-8 string for the input XML file path.
validate	A boolean (0 or 1) indicating whether to validate the XML against the embedded FERS schema. Validation is recommended to ensure scenario correctness.

Returns

0 on success, a non-zero error code on failure. Use fers_get_last_error_message() to retrieve error details.

Definition at line 274 of file api.cpp.

{
    last_error_message.clear();
    begin_warning_capture();
    if ((context == nullptr) || (xml_filepath == nullptr))
    {
        last_error_message = "Invalid arguments: context or xml_filepath is NULL.";
        LOG(logging::Level::ERROR, last_error_message);
        discard_warning_capture();
        return -1;
    }
 
    auto* ctx = reinterpret_cast<FersContext*>(context);
    try
    {
        // Set default output directory to the scenario file's directory
        std::filesystem::path p(xml_filepath);
        auto parent = p.parent_path();
        if (parent.empty())
            parent = ".";
        ctx->setOutputDir(parent.string());
 
        serial::parseSimulation(xml_filepath, ctx->getWorld(), static_cast<bool>(validate), ctx->getMasterSeeder());
 
        // After parsing, seed the master random number generator. This is done
        // to ensure simulation reproducibility. If the scenario specifies a seed,
        // it is used; otherwise, a non-deterministic seed is generated so that
        // subsequent runs are unique by default.
        if (params::params.random_seed)
        {
            LOG(logging::Level::INFO, "Using master seed from scenario file: {}", *params::params.random_seed);
            ctx->getMasterSeeder().seed(*params::params.random_seed);
        }
        else
        {
            const auto seed = std::random_device{}();
            LOG(logging::Level::INFO, "No master seed provided in scenario. Using random_device seed: {}", seed);
            params::params.random_seed = seed;
            ctx->getMasterSeeder().seed(seed);
        }
        complete_warning_capture();
        return 0; // Success
    }
    catch (const std::exception& e)
    {
        discard_warning_capture();
        handle_api_exception(e, "fers_load_scenario_from_xml_file");
        return 1; // Error
    }
}

References begin_warning_capture(), complete_warning_capture(), discard_warning_capture(), logging::ERROR, handle_api_exception(), logging::INFO, last_error_message, LOG, params::params, serial::parseSimulation(), and params::Parameters::random_seed.

Referenced by main().

Here is the call graph for this function:

Here is the caller graph for this function:

fers_load_scenario_from_xml_string()

int fers_load_scenario_from_xml_string	(	fers_context_t *	context,
		const char *	xml_content,
		int	validate
	)

Loads a scenario into the context from a FERS XML string.

This function provides a way to load a scenario from an in-memory string, avoiding file I/O. It is useful for test harnesses or for UIs that manage scenarios as text content before parsing.

Parameters

context	A valid fers_context_t handle.
xml_content	A null-terminated UTF-8 string containing the FERS scenario in XML format.
validate	A boolean (0 or 1) indicating whether to validate the XML against the embedded FERS schema.

Returns

0 on success, a non-zero error code on failure. Use fers_get_last_error_message() to retrieve error details.

Definition at line 325 of file api.cpp.

{
    last_error_message.clear();
    begin_warning_capture();
    if ((context == nullptr) || (xml_content == nullptr))
    {
        last_error_message = "Invalid arguments: context or xml_content is NULL.";
        LOG(logging::Level::ERROR, last_error_message);
        discard_warning_capture();
        return -1;
    }
 
    auto* ctx = reinterpret_cast<FersContext*>(context);
    try
    {
        serial::parseSimulationFromString(xml_content, ctx->getWorld(), static_cast<bool>(validate),
                                          ctx->getMasterSeeder());
 
        // After parsing, seed the master random number generator. This ensures
        // that if the scenario provides a seed, the simulation will be
        // reproducible. If not, a random seed is used to ensure unique runs.
        if (params::params.random_seed)
        {
            LOG(logging::Level::INFO, "Using master seed from scenario string: {}", *params::params.random_seed);
            ctx->getMasterSeeder().seed(*params::params.random_seed);
        }
        else
        {
            const auto seed = std::random_device{}();
            LOG(logging::Level::INFO, "No master seed provided in scenario. Using random_device seed: {}", seed);
            params::params.random_seed = seed;
            ctx->getMasterSeeder().seed(seed);
        }
 
        complete_warning_capture();
        return 0; // Success
    }
    catch (const std::exception& e)
    {
        discard_warning_capture();
        handle_api_exception(e, "fers_load_scenario_from_xml_string");
        return 1; // Parsing or logic error
    }
}

References begin_warning_capture(), complete_warning_capture(), discard_warning_capture(), logging::ERROR, handle_api_exception(), logging::INFO, last_error_message, LOG, params::params, serial::parseSimulationFromString(), and params::Parameters::random_seed.

Here is the call graph for this function:

fers_log()

void fers_log	(	fers_log_level_t	level,
		const char *	message
	)

Submits a log message to the library's unified logging system.

This ensures CLI messages match the format (timestamps, alignment) of library messages.

Definition at line 225 of file api.cpp.

{
    if (message == nullptr)
        return;
    // We pass a default source_location because C-API calls don't provide C++ source info
    logging::logger.log(map_api_log_level(level), message, std::source_location::current());
}

References logging::Logger::log(), logging::logger, and map_api_log_level().

Here is the call graph for this function:

fers_run_simulation()

int fers_run_simulation	(	fers_context_t *	context,
		fers_progress_callback_t	callback,
		void *	user_data
	)

Runs the simulation defined in the provided context.

This function is synchronous and will block the calling thread until the simulation is complete. This design keeps the API simple. For use in a responsive UI, it is the responsibility of the caller (e.g., the Tauri backend) to invoke this function on a separate worker thread to avoid freezing the user interface.

Parameters

context	A valid fers_context_t handle containing a loaded scenario.
callback	A function pointer to a progress callback. Can be NULL.
user_data	An opaque pointer passed to the callback function.

Returns

0 on success, a non-zero error code on failure. Use fers_get_last_error_message() to retrieve error details.

Definition at line 760 of file api.cpp.

{
    last_error_message.clear();
    if (context == nullptr)
    {
        last_error_message = "Invalid context provided to fers_run_simulation.";
        LOG(logging::Level::ERROR, last_error_message);
        return -1;
    }
 
    auto* ctx = reinterpret_cast<FersContext*>(context);
 
    // Wrap the C-style callback in a std::function for easier use in C++.
    // This also handles the case where the callback is null.
    std::function<void(const std::string&, int, int)> progress_fn;
    if (callback != nullptr)
    {
        progress_fn = [callback, user_data](const std::string& msg, const int current, const int total)
        { callback(msg.c_str(), current, total, user_data); };
    }
 
    try
    {
        pool::ThreadPool pool(params::renderThreads());
 
        ctx->clearLastOutputMetadata();
        const auto output_metadata = core::runEventDrivenSim(ctx->getWorld(), pool, progress_fn, ctx->getOutputDir());
        ctx->setLastOutputMetadata(output_metadata);
 
        return 0;
    }
    catch (const std::exception& e)
    {
        handle_api_exception(e, "fers_run_simulation");
        return 1;
    }
}

References logging::ERROR, handle_api_exception(), last_error_message, LOG, params::renderThreads(), and core::runEventDrivenSim().

Referenced by main().

Here is the call graph for this function:

Here is the caller graph for this function:

fers_set_log_callback()

void fers_set_log_callback	(	fers_log_callback_t	callback,
		void *	user_data
	)

Registers a callback for formatted log lines.

Pass NULL as callback to disable log callbacks.

Definition at line 214 of file api.cpp.

{
    {
        std::scoped_lock lock(log_callback_mutex);
        log_callback = callback;
        log_callback_user_data = user_data;
    }
 
    logging::logger.setCallback(callback == nullptr ? nullptr : forward_log_callback, nullptr);
}

References logging::logger, and logging::Logger::setCallback().

Here is the call graph for this function:

fers_set_output_directory()

int fers_set_output_directory	(	fers_context_t *	context,
		const char *	out_dir
	)

Sets the output directory for simulation results.

Parameters

context	A valid fers_context_t handle.
out_dir	A null-terminated UTF-8 string for the output directory path.

Returns

0 on success, non-zero on error.

Definition at line 252 of file api.cpp.

{
    last_error_message.clear();
    if ((context == nullptr) || (out_dir == nullptr))
    {
        last_error_message = "Invalid arguments: context or out_dir is NULL.";
        LOG(logging::Level::ERROR, last_error_message);
        return -1;
    }
    auto* ctx = reinterpret_cast<FersContext*>(context);
    try
    {
        ctx->setOutputDir(out_dir);
        return 0;
    }
    catch (const std::exception& e)
    {
        handle_api_exception(e, "fers_set_output_directory");
        return 1;
    }
}

References logging::ERROR, handle_api_exception(), last_error_message, LOG, and FersContext::setOutputDir().

Referenced by main().

Here is the call graph for this function:

Here is the caller graph for this function:

fers_set_thread_count()

int fers_set_thread_count

(

unsigned

num_threads

)

Sets the number of worker threads for the simulation.

Parameters

num_threads

The number of threads to use.

Returns

0 on success, non-zero on error. This function clears any previous thread-local error message at entry, like the other fallible API calls.

Definition at line 233 of file api.cpp.

{
    last_error_message.clear();
    try
    {
        if (auto res = params::setThreads(num_threads); !res)
        {
            last_error_message = res.error();
            return 1;
        }
        return 0;
    }
    catch (const std::exception& e)
    {
        handle_api_exception(e, "fers_set_thread_count");
        return 1;
    }
}

References handle_api_exception(), last_error_message, and params::setThreads().

Referenced by main().

Here is the call graph for this function:

Here is the caller graph for this function:

fers_update_antenna_from_json()

int fers_update_antenna_from_json	(	fers_context_t *	context,
		const char *	json
	)

Updates a single antenna from JSON without full context recreation.

Parameters

context	A valid fers_context_t handle.
json	The JSON string for the antenna.

Returns

0 on success, non-zero on failure.

Definition at line 511 of file api.cpp.

{
    last_error_message.clear();
    if ((context == nullptr) || (json == nullptr))
        return -1;
    auto* ctx = reinterpret_cast<FersContext*>(context);
    try
    {
        auto j = nlohmann::json::parse(json);
        auto id = j.at("id").is_string() ? std::stoull(j.at("id").get<std::string>()) : j.at("id").get<uint64_t>();
        auto* ant = ctx->getWorld()->findAntenna(id);
        if (ant == nullptr)
        {
            last_error_message = "Antenna not found";
            return 1;
        }
        serial::update_antenna_from_json(j, ant, *ctx->getWorld());
        return 0;
    }
    catch (const std::exception& e)
    {
        handle_api_exception(e, "fers_update_antenna_from_json");
        return 1;
    }
}

References handle_api_exception(), last_error_message, and serial::update_antenna_from_json().

Here is the call graph for this function:

fers_update_monostatic_from_json()

int fers_update_monostatic_from_json	(	fers_context_t *	context,
		const char *	json
	)

Updates a monostatic radar from JSON without full context recreation.

Parameters

context	A valid fers_context_t handle.
json	The JSON string for the monostatic component.

Returns

0 on success, non-zero on failure.

Definition at line 635 of file api.cpp.

{
    last_error_message.clear();
    if ((context == nullptr) || (json == nullptr))
        return -1;
    auto* ctx = reinterpret_cast<FersContext*>(context);
    try
    {
        auto j = nlohmann::json::parse(json);
        uint64_t tx_id =
            j.at("tx_id").is_string() ? std::stoull(j.at("tx_id").get<std::string>()) : j.at("tx_id").get<uint64_t>();
        uint64_t rx_id =
            j.at("rx_id").is_string() ? std::stoull(j.at("rx_id").get<std::string>()) : j.at("rx_id").get<uint64_t>();
        auto* tx = ctx->getWorld()->findTransmitter(tx_id);
        auto* rx = ctx->getWorld()->findReceiver(rx_id);
        if ((tx == nullptr) || (rx == nullptr))
        {
            last_error_message = "Monostatic components not found";
            return 1;
        }
        serial::update_monostatic_from_json(j, tx, rx, *ctx->getWorld(), ctx->getMasterSeeder());
        return 0;
    }
    catch (const std::exception& e)
    {
        handle_api_exception(e, "fers_update_monostatic_from_json");
        return 1;
    }
}

References handle_api_exception(), last_error_message, and serial::update_monostatic_from_json().

Here is the call graph for this function:

fers_update_parameters_from_json()

int fers_update_parameters_from_json	(	fers_context_t *	context,
		const char *	json
	)

Updates the global simulation parameters from JSON without full context recreation.

Parameters

context	A valid fers_context_t handle.
json	The JSON string for the parameters.

Returns

0 on success, non-zero on failure.

Definition at line 486 of file api.cpp.

{
    last_error_message.clear();
    begin_warning_capture();
    if ((context == nullptr) || (json == nullptr))
    {
        discard_warning_capture();
        return -1;
    }
    auto* ctx = reinterpret_cast<FersContext*>(context);
    try
    {
        auto j = nlohmann::json::parse(json);
        serial::update_parameters_from_json(j, ctx->getMasterSeeder());
        complete_warning_capture();
        return 0;
    }
    catch (const std::exception& e)
    {
        discard_warning_capture();
        handle_api_exception(e, "fers_update_parameters_from_json");
        return 1;
    }
}

References begin_warning_capture(), complete_warning_capture(), discard_warning_capture(), handle_api_exception(), last_error_message, and serial::update_parameters_from_json().

Here is the call graph for this function:

fers_update_platform_from_json()

int fers_update_platform_from_json	(	fers_context_t *	context,
		uint64_t	id,
		const char *	json
	)

Updates a single platform's paths and name from JSON without full context recreation.

Parameters

context	A valid fers_context_t handle.
id	The unique ID of the platform.
json	The JSON string for the platform.

Returns

0 on success, non-zero on failure.

Definition at line 450 of file api.cpp.

{
    last_error_message.clear();
    begin_warning_capture();
    if ((context == nullptr) || (json == nullptr))
    {
        discard_warning_capture();
        return -1;
    }
    auto* ctx = reinterpret_cast<FersContext*>(context);
    try
    {
        auto* p = ctx->getWorld()->findPlatform(id);
        if (p == nullptr)
        {
            last_error_message = "Platform not found";
            discard_warning_capture();
            return 1;
        }
        auto j = nlohmann::json::parse(json);
        serial::update_platform_paths_from_json(j, p);
        if (j.contains("name"))
        {
            p->setName(j.at("name").get<std::string>());
        }
        complete_warning_capture();
        return 0;
    }
    catch (const std::exception& e)
    {
        discard_warning_capture();
        handle_api_exception(e, "fers_update_platform_from_json");
        return 1;
    }
}

References begin_warning_capture(), complete_warning_capture(), discard_warning_capture(), core::World::findPlatform(), FersContext::getWorld(), handle_api_exception(), last_error_message, and serial::update_platform_paths_from_json().

Here is the call graph for this function:

fers_update_receiver_from_json()

int fers_update_receiver_from_json	(	fers_context_t *	context,
		uint64_t	id,
		const char *	json
	)

Updates a single receiver from JSON without full context recreation.

Parameters

context	A valid fers_context_t handle.
id	The unique ID of the receiver.
json	The JSON string for the receiver.

Returns

0 on success, non-zero on failure.

Definition at line 585 of file api.cpp.

{
    last_error_message.clear();
    if ((context == nullptr) || (json == nullptr))
        return -1;
    auto* ctx = reinterpret_cast<FersContext*>(context);
    try
    {
        auto* rx = ctx->getWorld()->findReceiver(id);
        if (rx == nullptr)
        {
            last_error_message = "Receiver not found";
            return 1;
        }
        auto j = nlohmann::json::parse(json);
        serial::update_receiver_from_json(j, rx, *ctx->getWorld(), ctx->getMasterSeeder());
        return 0;
    }
    catch (const std::exception& e)
    {
        handle_api_exception(e, "fers_update_receiver_from_json");
        return 1;
    }
}

References core::World::findReceiver(), FersContext::getWorld(), handle_api_exception(), last_error_message, and serial::update_receiver_from_json().

Here is the call graph for this function:

fers_update_scenario_from_json()

int fers_update_scenario_from_json	(	fers_context_t *	context,
		const char *	scenario_json
	)

Updates the simulation scenario from a JSON string.

This is the primary method for the UI to push its state back to the C++ core. It performs a full replacement of the existing scenario.

Parameters

context	A valid fers_context_t handle.
scenario_json	A null-terminated UTF-8 string containing the FERS scenario in JSON format.

Returns

0 on success. 1 on generic logic error. 2 on JSON parsing/schema validation error. Use fers_get_last_error_message() to retrieve error details.

Definition at line 689 of file api.cpp.

{
    last_error_message.clear();
    begin_warning_capture();
    if ((context == nullptr) || (scenario_json == nullptr))
    {
        last_error_message = "Invalid arguments: context or scenario_json is NULL.";
        LOG(logging::Level::ERROR, last_error_message);
        discard_warning_capture();
        return -1;
    }
 
    auto* ctx = reinterpret_cast<FersContext*>(context);
    try
    {
        const nlohmann::json j = nlohmann::json::parse(scenario_json);
        serial::json_to_world(j, *ctx->getWorld(), ctx->getMasterSeeder());
        complete_warning_capture();
 
        return 0; // Success
    }
    catch (const nlohmann::json::exception& e)
    {
        // A specific catch block for JSON errors is used to provide more
        // detailed feedback to the client (e.g., the UI), which can help
        // developers diagnose schema or data format issues more easily.
        last_error_message = "JSON parsing/deserialization error: " + std::string(e.what());
        LOG(logging::Level::ERROR, "API Error in {}: {}", "fers_update_scenario_from_json", last_error_message);
        discard_warning_capture();
        return 2; // JSON error
    }
    catch (const std::exception& e)
    {
        discard_warning_capture();
        handle_api_exception(e, "fers_update_scenario_from_json");
        return 1; // Generic error
    }
}

References begin_warning_capture(), complete_warning_capture(), discard_warning_capture(), logging::ERROR, handle_api_exception(), serial::json_to_world(), last_error_message, and LOG.

Here is the call graph for this function:

fers_update_target_from_json()

int fers_update_target_from_json	(	fers_context_t *	context,
		uint64_t	id,
		const char *	json
	)

Updates a single target from JSON without full context recreation.

Parameters

context	A valid fers_context_t handle.
id	The unique ID of the target.
json	The JSON string for the target.

Returns

0 on success, non-zero on failure.

Definition at line 610 of file api.cpp.

{
    last_error_message.clear();
    if ((context == nullptr) || (json == nullptr))
        return -1;
    auto* ctx = reinterpret_cast<FersContext*>(context);
    try
    {
        auto* tgt = ctx->getWorld()->findTarget(id);
        if (tgt == nullptr)
        {
            last_error_message = "Target not found";
            return 1;
        }
        auto j = nlohmann::json::parse(json);
        serial::update_target_from_json(j, tgt, *ctx->getWorld(), ctx->getMasterSeeder());
        return 0;
    }
    catch (const std::exception& e)
    {
        handle_api_exception(e, "fers_update_target_from_json");
        return 1;
    }
}

References core::World::findTarget(), FersContext::getWorld(), handle_api_exception(), last_error_message, and serial::update_target_from_json().

Here is the call graph for this function:

fers_update_timing_from_json()

int fers_update_timing_from_json	(	fers_context_t *	context,
		uint64_t	id,
		const char *	json
	)

Updates a single timing source from JSON without full context recreation.

Parameters

context	A valid fers_context_t handle.
id	The unique ID of the timing source.
json	The JSON string for the timing source.

Returns

0 on success, non-zero on failure.

Definition at line 665 of file api.cpp.

{
    last_error_message.clear();
    if ((context == nullptr) || (json == nullptr))
        return -1;
    auto* ctx = reinterpret_cast<FersContext*>(context);
    try
    {
        if (ctx->getWorld()->findTiming(id) == nullptr)
        {
            last_error_message = "Timing not found";
            return 1;
        }
        auto j = nlohmann::json::parse(json);
        serial::update_timing_from_json(j, *ctx->getWorld(), id);
        return 0;
    }
    catch (const std::exception& e)
    {
        handle_api_exception(e, "fers_update_timing_from_json");
        return 1;
    }
}

References handle_api_exception(), last_error_message, and serial::update_timing_from_json().

Here is the call graph for this function:

fers_update_transmitter_from_json()

int fers_update_transmitter_from_json	(	fers_context_t *	context,
		uint64_t	id,
		const char *	json
	)

Updates a single transmitter from JSON without full context recreation.

Parameters

context	A valid fers_context_t handle.
id	The unique ID of the transmitter.
json	The JSON string for the transmitter.

Returns

0 on success, non-zero on failure.

Definition at line 560 of file api.cpp.

{
    last_error_message.clear();
    if ((context == nullptr) || (json == nullptr))
        return -1;
    auto* ctx = reinterpret_cast<FersContext*>(context);
    try
    {
        auto* tx = ctx->getWorld()->findTransmitter(id);
        if (tx == nullptr)
        {
            last_error_message = "Transmitter not found";
            return 1;
        }
        auto j = nlohmann::json::parse(json);
        serial::update_transmitter_from_json(j, tx, *ctx->getWorld(), ctx->getMasterSeeder());
        return 0;
    }
    catch (const std::exception& e)
    {
        handle_api_exception(e, "fers_update_transmitter_from_json");
        return 1;
    }
}

References core::World::findTransmitter(), FersContext::getWorld(), handle_api_exception(), last_error_message, and serial::update_transmitter_from_json().

Here is the call graph for this function:

fers_update_waveform_from_json()

int fers_update_waveform_from_json	(	fers_context_t *	context,
		const char *	json
	)

Updates a single waveform from JSON without full context recreation.

Parameters

context	A valid fers_context_t handle.
json	The JSON string for the waveform.

Returns

0 on success, non-zero on failure.

Definition at line 537 of file api.cpp.

{
    last_error_message.clear();
    if ((context == nullptr) || (json == nullptr))
        return -1;
    auto* ctx = reinterpret_cast<FersContext*>(context);
    try
    {
        auto j = nlohmann::json::parse(json);
        auto wf = serial::parse_waveform_from_json(j);
        if (wf)
        {
            ctx->getWorld()->replace(std::move(wf));
        }
        return 0;
    }
    catch (const std::exception& e)
    {
        handle_api_exception(e, "fers_update_waveform_from_json");
        return 1;
    }
}

References handle_api_exception(), last_error_message, and serial::parse_waveform_from_json().

Here is the call graph for this function: