The scgms
library is a central library for creating and managing entities. It exports the following set of functions:
create_filter
- creates a filter using given GUID and a pointer to next filtercreate_metric
- creates a metric using given GUID and metric parameterscreate_signal
- creates a signal using given GUIDcreate_approximator
- creates a signal approximator with given GUIDcreate_discrete_model
- creates a discrete model using given GUIDget_filter_descriptors
- retrieves a range (begin, end) of available loaded filter descriptorsget_metric_descriptors
- retrieves a range (begin, end) of available loaded metric descriptorsget_model_descriptors
- retrieves a range (begin, end) of available loaded model (discrete and signal model) descriptorsget_solver_descriptors
- retrieves a range (begin, end) of available loaded solver descriptorsget_approx_descriptors
- retrieves a range (begin, end) of available loaded approximator descriptorsget_signal_descriptors
- retrieves a range (begin, end) of available loaded signal descriptorsadd_filters
(deprecated) - injects a filter entity from external codecreate_device_event
- allocates a device event from a limited size poolcreate_persistent_filter_chain_configuration
- creates a configuration container for simulation executionexecute_filter_configuration
- executes a filter configuration (runs a simulation); this blocks, while the simulation runscreate_filter_parameter
- creates a single filter parameter containercreate_filter_configuration_link
- creates a single filter parameter configuration linksolve_generic
- runs a solver with given GUID on given setupoptimize_parameters
- optimize parameters of a single filter in given filter chain configurationoptimize_multiple_parameters
- optimize parameters of multiple filter in given filter chain configurationExecute_SCGMS_Configuration
- "simple" interface - executes given configuration, returns a simulation handleInject_SCGMS_Event
- "simple" interface - injects a new device event into a running simulationShutdown_SCGMS
- "simple" interface - shuts down the simulation, optionally waits for termination
Every interface function or method returns a status code - a HRESULT
. The conventions were adapted from WinAPI standard, including concrete values. All used values
are either taken from appropriate header file on MS Windows, or is additionally defined in SDK file hresult.h
. Most commonly used HRESULT
values:
S_OK
- success, the call succeeded without an error and/or warningS_FALSE
- success (might be partial), but the function does not return any result (may be soft failure, or any other non-standard non-errorneous scenario)E_FAIL
- generic failure; this return code is often accompanied with additional error output (using some kind of log container, device event, ...)E_NOTIMPL
- not implemented; e.g. returned as a result of factory function, that is not able to construct a requested entityE_ABORT
- fatal error, should abort the whole simulation, if returned during oneE_UNEXPECTED
- the call to this function/method was not expected at this timeE_NOINTERFACE
- the entity does not support given interfaceE_INVALIDARG
- invalid argument supplied (not within valid domain)E_OUTOFMEMORY
- unable to complete the request due to the lack of resources (the system is low on memory, or the pre-allocated pool was depleted)E_ILLEGAL_STATE_CHANGE
- attempt to change the state of an entity, which was invalid at the time
A SmartCGMS-compliant library usually exports a function, that resolves descriptors of all implemented entites within the library (e.g. do_get_filter_descriptors
).
Such a function retains two parameters, which are double-indirect and is expected to be filled with valid range of pointers to descriptor structures. For example, take the
do_get_filter_descriptors
function:
scgms::TFilter_Descriptor my_descriptor = ...;
extern "C" HRESULT do_get_filter_descriptors(scgms::TFilter_Descriptor** begin, scgms::TFilter_Descriptor** end)
{
*begin = &my_descriptor;
*end = &my_descriptor + 1;
return S_OK;
}
It is worth noting, that the range definition follows the usual contract, i.e.; the begin
pointer points to the first valid element and the end
pointer
points to one element after the last valid element. It is not included in the range and serves as an upper boundary only.
A SmartCGMS-compliant library also usually exports a function, that creates the requested entity based on given identifier and other parameters (e.g. do_create_filter
). The usual contract of such
function includes the entity GUID and a double indirect pointer, which is expected to be filled with a pointer to newly created entity. For example, take the do_create_filter
function:
extern "C" HRESULT IfaceCalling do_create_filter(const GUID *id, scgms::IFilter *output, scgms::IFilter **filter)
{
if (*id == my_filter_guid)
{
*filter = Create_My_Filter(output);
return (*filter != nullptr) ? S_OK : E_OUTOFMEMORY;
}
return E_NOTIMPL;
}
Both the do_get_*_descriptors
, do_create_*
functions, descriptors and relevant conventions are further described in respective entity documentation pages.