SmartCGMS developer zone

Library interface

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 filter
  • create_metric - creates a metric using given GUID and metric parameters
  • create_signal - creates a signal using given GUID
  • create_approximator - creates a signal approximator with given GUID
  • create_discrete_model - creates a discrete model using given GUID
  • get_filter_descriptors - retrieves a range (begin, end) of available loaded filter descriptors
  • get_metric_descriptors - retrieves a range (begin, end) of available loaded metric descriptors
  • get_model_descriptors - retrieves a range (begin, end) of available loaded model (discrete and signal model) descriptors
  • get_solver_descriptors - retrieves a range (begin, end) of available loaded solver descriptors
  • get_approx_descriptors - retrieves a range (begin, end) of available loaded approximator descriptors
  • get_signal_descriptors - retrieves a range (begin, end) of available loaded signal descriptors
  • add_filters (deprecated) - injects a filter entity from external code
  • create_device_event - allocates a device event from a limited size pool
  • create_persistent_filter_chain_configuration - creates a configuration container for simulation execution
  • execute_filter_configuration - executes a filter configuration (runs a simulation); this blocks, while the simulation runs
  • create_filter_parameter - creates a single filter parameter container
  • create_filter_configuration_link - creates a single filter parameter configuration link
  • solve_generic - runs a solver with given GUID on given setup
  • optimize_parameters - optimize parameters of a single filter in given filter chain configuration
  • optimize_multiple_parameters - optimize parameters of multiple filter in given filter chain configuration
  • Execute_SCGMS_Configuration - "simple" interface - executes given configuration, returns a simulation handle
  • Inject_SCGMS_Event - "simple" interface - injects a new device event into a running simulation
  • Shutdown_SCGMS - "simple" interface - shuts down the simulation, optionally waits for termination
Under usual circumstances, the programmer usually takes advantage of supplied C++ SDK, which resolves, encapsulates and calls all exported functions in a properly managed way, often using higher-level C++ primitives.

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 warning
  • S_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 entity
  • E_ABORT - fatal error, should abort the whole simulation, if returned during one
  • E_UNEXPECTED - the call to this function/method was not expected at this time
  • E_NOINTERFACE - the entity does not support given interface
  • E_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
  • and more...

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.