C API Reference

Enums

HELICS_ITERATION_REQUEST_NO_ITERATION = 0

no iteration is requested

HELICS_ITERATION_REQUEST_FORCE_ITERATION = 1

force iteration return when able

HELICS_ITERATION_REQUEST_ITERATE_IF_NEEDED = 2

only return an iteration if necessary

HELICS_ITERATION_RESULT_NEXT_STEP = 0

the iterations have progressed to the next time

HELICS_ITERATION_RESULT_ERROR = 1

there was an error

HELICS_ITERATION_RESULT_HALTED = 2

the federation has halted

HELICS_ITERATION_RESULT_ITERATING = 3

the federate is iterating at current time

HELICS_STATE_STARTUP = 0

when created the federate is in startup state

HELICS_STATE_INITIALIZATION = 1

entered after the enterInitializingMode call has returned

HELICS_STATE_EXECUTION = 2

entered after the enterExectuationState call has returned

HELICS_STATE_FINALIZE = 3

the federate has finished executing normally final values may be retrieved

HELICS_STATE_ERROR = 4

error state no core communication is possible but values can be retrieved

HELICS_STATE_PENDING_INIT = 5

indicator that the federate is pending entry to initialization state

HELICS_STATE_PENDING_EXEC = 6

state pending EnterExecution State

HELICS_STATE_PENDING_TIME = 7

state that the federate is pending a timeRequest

HELICS_STATE_PENDING_ITERATIVE_TIME = 8

state that the federate is pending an iterative time request

HELICS_STATE_PENDING_FINALIZE = 9

state that the federate is pending a finalize request

HELICS_STATE_FINISHED = 10

state that the federate is finished simulating but still connected

HELICS_CORE_TYPE_DEFAULT = 0

a default core type that will default to something available

HELICS_CORE_TYPE_ZMQ = 1

use the Zero MQ networking protocol

HELICS_CORE_TYPE_MPI = 2

use MPI for operation on a parallel cluster

HELICS_CORE_TYPE_TEST = 3

use the Test core if all federates are in the same process

HELICS_CORE_TYPE_INTERPROCESS = 4

interprocess uses memory mapped files to transfer data (for use when all federates are on the same machine

HELICS_CORE_TYPE_IPC = 5

interprocess uses memory mapped files to transfer data (for use when all federates are on the same machine ipc is the same as /ref HELICS_CORE_TYPE_interprocess

HELICS_CORE_TYPE_TCP = 6

use a generic TCP protocol message stream to send messages

HELICS_CORE_TYPE_UDP = 7

use UDP packets to send the data

HELICS_CORE_TYPE_ZMQ_SS = 10

single socket version of ZMQ core usually for high fed count on the same system

HELICS_CORE_TYPE_NNG = 9

for using the nanomsg communications

HELICS_CORE_TYPE_TCP_SS = 11

a single socket version of the TCP core for more easily handling firewalls

HELICS_CORE_TYPE_HTTP = 12

a core type using http for communication

HELICS_CORE_TYPE_WEBSOCKET = 14

a core using websockets for communication

HELICS_CORE_TYPE_INPROC = 18

an in process core type for handling communications in shared memory it is pretty similar to the test core but stripped from the “test” components

HELICS_CORE_TYPE_NULL = 66

an explicit core type that is recognized but explicitly doesn’t exist, for testing and a few other assorted reasons

HELICS_DATA_TYPE_STRING = 0

a sequence of characters

HELICS_DATA_TYPE_DOUBLE = 1

a double precision floating point number

HELICS_DATA_TYPE_INT = 2

a 64 bit integer

HELICS_DATA_TYPE_COMPLEX = 3

a pair of doubles representing a complex number

HELICS_DATA_TYPE_VECTOR = 4

an array of doubles

HELICS_DATA_TYPE_COMPLEX_VECTOR = 5

a complex vector object

HELICS_DATA_TYPE_NAMED_POINT = 6

a named point consisting of a string and a double

HELICS_DATA_TYPE_BOOLEAN = 7

a boolean data type

HELICS_DATA_TYPE_TIME = 8

time data type

HELICS_DATA_TYPE_RAW = 25

raw data type

HELICS_DATA_TYPE_JSON = 30

type converts to a valid json string

HELICS_DATA_TYPE_MULTI = 33

the data type can change

HELICS_DATA_TYPE_ANY = 25262

open type that can be anything

HELICS_FLAG_OBSERVER = 0

flag indicating that a federate is observe only

HELICS_FLAG_UNINTERRUPTIBLE = 1

flag indicating that a federate can only return requested times

HELICS_FLAG_INTERRUPTIBLE = 2

flag indicating that a federate can be interrupted

HELICS_FLAG_SOURCE_ONLY = 4

flag indicating that a federate/interface is a signal generator only

HELICS_FLAG_ONLY_TRANSMIT_ON_CHANGE = 6

flag indicating a federate/interface should only transmit values if they have changed(binary equivalence)

HELICS_FLAG_ONLY_UPDATE_ON_CHANGE = 8

flag indicating a federate/interface should only trigger an update if a value has changed (binary equivalence)

HELICS_FLAG_WAIT_FOR_CURRENT_TIME_UPDATE = 10

flag indicating a federate should only grant time if all other federates have already passed the requested time

HELICS_FLAG_RESTRICTIVE_TIME_POLICY = 11

flag indicating a federate should operate on a restrictive time policy, which disallows some 2nd order time evaluation and can be useful for certain types of dependency cycles and update patterns, but generally shouldn’t be used as it can lead to some very slow update conditions

HELICS_FLAG_ROLLBACK = 12

flag indicating that a federate has rollback capability

HELICS_FLAG_FORWARD_COMPUTE = 14

flag indicating that a federate performs forward computation and does internal rollback

HELICS_FLAG_REALTIME = 16

flag indicating that a federate needs to run in real time

HELICS_FLAG_SINGLE_THREAD_FEDERATE = 27

flag indicating that the federate will only interact on a single thread

HELICS_FLAG_IGNORE_TIME_MISMATCH_WARNINGS = 67

used to not display warnings on mismatched requested times

HELICS_FLAG_STRICT_CONFIG_CHECKING = 75

specify that checking on configuration files should be strict and throw and error on any invalid values

HELICS_FLAG_USE_JSON_SERIALIZATION = 79

specify that the federate should use json serialization for all data types

HELICS_FLAG_EVENT_TRIGGERED = 81

specify that the federate is event triggered-meaning (all/most) events are triggered by incoming events

HELICS_FLAG_LOCAL_PROFILING_CAPTURE = 96

specify that that federate should capture the profiling data to the local federate logging system

HELICS_FLAG_DELAY_INIT_ENTRY = 45

used to delay a core from entering initialization mode even if it would otherwise be ready

HELICS_FLAG_ENABLE_INIT_ENTRY = 47

used to clear the HELICS_DELAY_INIT_ENTRY flag in cores

HELICS_FLAG_IGNORE = 999

ignored flag used to test some code paths

HELICS_FLAG_SLOW_RESPONDING = 29

flag specifying that a federate, core, or broker may be slow to respond to pings If the federate goes offline there is no good way to detect it so use with caution

HELICS_FLAG_DEBUGGING = 31

flag specifying the federate/core/broker is operating in a user debug mode so deadlock timers and timeout are disabled this flag is a combination of slow_responding and disabling of some timeouts

HELICS_FLAG_TERMINATE_ON_ERROR = 72

specify that a federate error should terminate the federation

HELICS_FLAG_FORCE_LOGGING_FLUSH = 88

specify that the log files should be flushed on every log message

HELICS_FLAG_DUMPLOG = 89

specify that a full log should be dumped into a file

HELICS_FLAG_PROFILING = 93

specify that helics should capture profiling data

HELICS_FLAG_PROFILING_MARKER = 95

flag trigger for generating a profiling marker

HELICS_LOG_LEVEL_NO_PRINT = -4

don’t print anything except a few catastrophic errors

HELICS_LOG_LEVEL_ERROR = 0

only print error level indicators

HELICS_LOG_LEVEL_PROFILING = 2

profiling log level

HELICS_LOG_LEVEL_WARNING = 3

only print warnings and errors

HELICS_LOG_LEVEL_SUMMARY = 6

warning errors and summary level information

HELICS_LOG_LEVEL_CONNECTIONS = 9

summary+ notices about federate and broker connections +messages about network connections

HELICS_LOG_LEVEL_INTERFACES = 12

connections+ interface definitions

HELICS_LOG_LEVEL_TIMING = 15

interfaces + timing message

HELICS_LOG_LEVEL_DATA = 18

timing+ data transfer notices

HELICS_LOG_LEVEL_DEBUG = 21

data+ additional debug message

HELICS_LOG_LEVEL_TRACE = 24

all internal messages

HELICS_ERROR_FATAL = -404

global fatal error for federation

HELICS_ERROR_EXTERNAL_TYPE = -203

an unknown non-helics error was produced

HELICS_ERROR_OTHER = -101

the function produced a helics error of some other type

HELICS_ERROR_USER_ABORT = -27

user system abort

HELICS_ERROR_INSUFFICIENT_SPACE = -18

insufficient space is available to store requested data

HELICS_ERROR_EXECUTION_FAILURE = -14

the function execution has failed

HELICS_ERROR_INVALID_FUNCTION_CALL = -10

the call made was invalid in the present state of the calling object

HELICS_ERROR_INVALID_STATE_TRANSITION = -9

error issued when an invalid state transition occurred

HELICS_ERROR_SYSTEM_FAILURE = -6

the federate has terminated unexpectedly and the call cannot be completed

HELICS_ERROR_DISCARD = -5

the input was discarded and not used for some reason

HELICS_ERROR_INVALID_ARGUMENT = -4

the parameter passed was invalid and unable to be used

HELICS_ERROR_INVALID_OBJECT = -3

indicator that the object used was not a valid object

HELICS_ERROR_CONNECTION_FAILURE = -2

the operation to connect has failed

HELICS_ERROR_REGISTRATION_FAILURE = -1

registration has failed

HELICS_PROPERTY_TIME_DELTA = 137

the property controlling the minimum time delta for a federate

HELICS_PROPERTY_TIME_PERIOD = 140

the property controlling the period for a federate

HELICS_PROPERTY_TIME_OFFSET = 141

the property controlling time offset for the period of federate

HELICS_PROPERTY_TIME_RT_LAG = 143

the property controlling real time lag for a federate the max time a federate can lag real time

HELICS_PROPERTY_TIME_RT_LEAD = 144

the property controlling real time lead for a federate the max time a federate can be ahead of real time

HELICS_PROPERTY_TIME_RT_TOLERANCE = 145

the property controlling real time tolerance for a federate sets both rt_lag and rt_lead

HELICS_PROPERTY_TIME_INPUT_DELAY = 148

the property controlling input delay for a federate

HELICS_PROPERTY_TIME_OUTPUT_DELAY = 150

the property controlling output delay for a federate

HELICS_PROPERTY_INT_MAX_ITERATIONS = 259

integer property controlling the maximum number of iterations in a federate

HELICS_PROPERTY_INT_LOG_LEVEL = 271

integer property controlling the log level in a federate see HelicsLogLevels

HELICS_PROPERTY_INT_FILE_LOG_LEVEL = 272

integer property controlling the log level for file logging in a federate see HelicsLogLevels

HELICS_PROPERTY_INT_CONSOLE_LOG_LEVEL = 274

integer property controlling the log level for file logging in a federate see HelicsLogLevels

HELICS_MULTI_INPUT_NO_OP = 0

time and priority order the inputs from the core library

HELICS_MULTI_INPUT_VECTORIZE_OPERATION = 1

vectorize the inputs either double vector or string vector

HELICS_MULTI_INPUT_AND_OPERATION = 2

all inputs are assumed to be boolean and all must be true to return true

HELICS_MULTI_INPUT_OR_OPERATION = 3

all inputs are assumed to be boolean and at least one must be true to return true

HELICS_MULTI_INPUT_SUM_OPERATION = 4

sum all the inputs

HELICS_MULTI_INPUT_DIFF_OPERATION = 5

do a difference operation on the inputs, first-sum(rest) for double input, vector diff for vector input

HELICS_MULTI_INPUT_MAX_OPERATION = 6

find the max of the inputs

HELICS_MULTI_INPUT_MIN_OPERATION = 7

find the min of the inputs

HELICS_MULTI_INPUT_AVERAGE_OPERATION = 8

take the average of the inputs

HELICS_HANDLE_OPTION_CONNECTION_REQUIRED = 397

specify that a connection is required for an interface and will generate an error if not available

HELICS_HANDLE_OPTION_CONNECTION_OPTIONAL = 402

specify that a connection is NOT required for an interface and will only be made if available no warning will be issues if not available

HELICS_HANDLE_OPTION_SINGLE_CONNECTION_ONLY = 407

specify that only a single connection is allowed for an interface

HELICS_HANDLE_OPTION_MULTIPLE_CONNECTIONS_ALLOWED = 409

specify that multiple connections are allowed for an interface

HELICS_HANDLE_OPTION_BUFFER_DATA = 411

specify that the last data should be buffered and sent on subscriptions after init

HELICS_HANDLE_OPTION_STRICT_TYPE_CHECKING = 414

specify that the types should be checked strictly for pub/sub and filters

HELICS_HANDLE_OPTION_IGNORE_UNIT_MISMATCH = 447

specify that the mismatching units should be ignored

HELICS_HANDLE_OPTION_ONLY_TRANSMIT_ON_CHANGE = 452

specify that an interface will only transmit on change(only applicable to publications)

HELICS_HANDLE_OPTION_ONLY_UPDATE_ON_CHANGE = 454

specify that an interface will only update if the value has actually changed

HELICS_HANDLE_OPTION_IGNORE_INTERRUPTS = 475

specify that an interface does not participate in determining time interrupts

HELICS_HANDLE_OPTION_MULTI_INPUT_HANDLING_METHOD = 507

specify the multi-input processing method for inputs

HELICS_HANDLE_OPTION_INPUT_PRIORITY_LOCATION = 510

specify the source index with the highest priority

HELICS_HANDLE_OPTION_CLEAR_PRIORITY_LIST = 512

specify that the priority list should be cleared or question if it is cleared

HELICS_HANDLE_OPTION_CONNECTIONS = 522

specify the required number of connections or get the actual number of connections

HELICS_FILTER_TYPE_CUSTOM = 0

a custom filter type that executes a user defined callback

HELICS_FILTER_TYPE_DELAY = 1

a filter type that executes a fixed delay on a message

HELICS_FILTER_TYPE_RANDOM_DELAY = 2

a filter type that executes a random delay on the messages

HELICS_FILTER_TYPE_RANDOM_DROP = 3

a filter type that randomly drops messages

HELICS_FILTER_TYPE_REROUTE = 4

a filter type that reroutes a message to a different destination than originally specified

HELICS_FILTER_TYPE_CLONE = 5

a filter type that duplicates a message and sends the copy to a different destination

HELICS_FILTER_TYPE_FIREWALL = 6

a customizable filter type that can perform different actions on a message based on firewall like rules

HELICS_SEQUENCING_MODE_FAST = 0

sequencing mode to operate on priority channels

HELICS_SEQUENCING_MODE_ORDERED = 1

sequencing mode to operate on the normal channels

HELICS_SEQUENCING_MODE_DEFAULT = 2

select the default channel

General

HELICS_EXPORT const char* helicsGetVersion(void)

Get a version string for HELICS.

HELICS_EXPORT const char* helicsGetBuildFlags(void)

Get the build flags used to compile HELICS.

HELICS_EXPORT const char* helicsGetCompilerVersion(void)

Get the compiler version used to compile HELICS.

HELICS_EXPORT HelicsError helicsErrorInitialize(void)

Return an initialized error object.

HELICS_EXPORT void helicsErrorClear(HelicsError * err)

Clear an error object.

clear an error object

HELICS_EXPORT void helicsLoadSignalHandler()

Load a signal handler that handles Ctrl-C and shuts down all HELICS brokers, cores, and federates then exits the process.

HELICS_EXPORT void helicsClearSignalHandler()

Clear HELICS based signal handlers.

HELICS_EXPORT void helicsLoadSignalHandlerCallback(HelicsBool (*handler)(int))

Load a custom signal handler to execute prior to the abort signal handler.

This function is not 100% reliable it will most likely work but uses some functions and techniques that are not 100% guaranteed to work in a signal handler and in worst case it could deadlock. That is somewhat unlikely given usage patterns but it is possible. The callback has signature helics_bool(*handler)(int) and it will take the SIG_INT as an argument and return a boolean. If the boolean return value is helics_true (or the callback is null) the default signal handler is run after the callback finishes; if it is helics_false the default callback is not run and the default signal handler is executed.

HELICS_EXPORT void helicsAbort(int errorCode, const char * errorString)

Execute a global abort by sending an error code to all cores, brokers, and federates that were created through the current library instance.

HELICS_EXPORT HelicsBool helicsIsCoreTypeAvailable(const char * type)

Returns true if core/broker type specified is available in current compilation.

Options include “zmq”, “udp”, “ipc”, “interprocess”, “tcp”, “default”, “mpi”.

Parameters
  • type: A string representing a core type.

HELICS_EXPORT HelicsFederate helicsGetFederateByName(const char * fedName, HelicsError * err)

Get an existing federate object from a core by name.

The federate must have been created by one of the other functions and at least one of the objects referencing the created federate must still be active in the process.

Return
NULL if no fed is available by that name otherwise a HelicsFederate with that name.
Parameters
  • fedName: The name of the federate to retrieve.
  • err: An error object that will contain an error code and string if any error occurred during the execution of the function.

HELICS_EXPORT int helicsGetPropertyIndex(const char * val)

Get a property index for use in /ref helicsFederateInfoSetFlagOption, /ref helicsFederateInfoSetTimeProperty, or /ref helicsFederateInfoSetIntegerProperty

Return
An int with the property code or (-1) if not a valid property.
Parameters
  • val: A string with the property name.

HELICS_EXPORT int helicsGetFlagIndex(const char * val)

Get a property index for use in /ref helicsFederateInfoSetFlagOption, /ref helicsFederateSetFlagOption,

Return
An int with the property code or (-1) if not a valid property.
Parameters
  • val: A string with the option name.

HELICS_EXPORT int helicsGetOptionIndex(const char * val)

Get an option index for use in /ref helicsPublicationSetOption, /ref helicsInputSetOption, /ref helicsEndpointSetOption, /ref helicsFilterSetOption, and the corresponding get functions.

Return
An int with the option index or (-1) if not a valid property.
Parameters
  • val: A string with the option name.

HELICS_EXPORT int helicsGetOptionValue(const char * val)

Get an option value for use in /ref helicsPublicationSetOption, /ref helicsInputSetOption, /ref helicsEndpointSetOption, /ref helicsFilterSetOption.

Return
An int with the option value or (-1) if not a valid value.
Parameters
  • val: A string representing the value.

HELICS_EXPORT void helicsCloseLibrary(void)

Call when done using the helics library. This function will ensure the threads are closed properly. If possible this should be the last call before exiting.

HELICS_EXPORT void helicsCleanupLibrary(void)

Function to do some housekeeping work.

This runs some cleanup routines and tries to close out any residual thread that haven’t been shutdown yet.

Creation

HELICS_EXPORT HelicsCore helicsCreateCore(const char * type, const char * name, const char * initString, HelicsError * err)

Create a core object.

If the core is invalid, err will contain the corresponding error message and the returned object will be NULL.

Return
A HelicsCore object.
Parameters
  • type: The type of the core to create.
  • name: The name of the core. It can be a nullptr or empty string to have a name automatically assigned.
  • initString: An initialization string to send to the core. The format is similar to command line arguments. Typical options include a broker name, the broker address, the number of federates, etc.
  • err: An error object that will contain an error code and string if any error occurred during the execution of the function.

HELICS_EXPORT HelicsCore helicsCreateCoreFromArgs(const char * type, const char * name, int argc, const char *const * argv, HelicsError * err)

Create a core object by passing command line arguments.

Return
A HelicsCore object.
Parameters
  • type: The type of the core to create.
  • name: The name of the core. It can be a nullptr or empty string to have a name automatically assigned.
  • argc: The number of arguments.
  • argv: The list of string values from a command line.
  • err: An error object that will contain an error code and string if any error occurred during the execution of the function.

HELICS_EXPORT HelicsBroker helicsCreateBroker(const char * type, const char * name, const char * initString, HelicsError * err)

Create a broker object.

It will be NULL if there was an error indicated in the err object.

Return
A HelicsBroker object.
Parameters
  • type: The type of the broker to create.
  • name: The name of the broker. It can be a nullptr or empty string to have a name automatically assigned.
  • initString: An initialization string to send to the core-the format is similar to command line arguments. Typical options include a broker address such as broker=”XSSAF” if this is a subbroker, or the number of federates, or the address.
  • err: An error object that will contain an error code and string if any error occurred during the execution of the function.

HELICS_EXPORT HelicsBroker helicsCreateBrokerFromArgs(const char * type, const char * name, int argc, const char *const * argv, HelicsError * err)

Create a core object by passing command line arguments.

Return
A HelicsCore object.
Parameters
  • type: The type of the core to create.
  • name: The name of the core. It can be a nullptr or empty string to have a name automatically assigned.
  • argc: The number of arguments.
  • argv: The list of string values from a command line.
  • err: An error object that will contain an error code and string if any error occurred during the execution of the function.

HELICS_EXPORT HelicsFederate helicsCreateValueFederate(const char * fedName, HelicsFederateInfo fi, HelicsError * err)

Create a value federate from a federate info object.

HelicsFederate objects can be used in all functions that take a HelicsFederate or HelicsFederate object as an argument.

Return
An opaque value federate object.
Parameters
  • fedName: The name of the federate to create, can NULL or an empty string to use the default name from fi or an assigned name.
  • fi: The federate info object that contains details on the federate.
  • err: An error object that will contain an error code and string if any error occurred during the execution of the function.

HELICS_EXPORT HelicsFederate helicsCreateValueFederateFromConfig(const char * configFile, HelicsError * err)

Create a value federate from a JSON file, JSON string, or TOML file.

HelicsFederate objects can be used in all functions that take a HelicsFederate or HelicsFederate object as an argument.

Return
An opaque value federate object.
Parameters
  • configFile: A JSON file or a JSON string or TOML file that contains setup and configuration information.
  • err: An error object that will contain an error code and string if any error occurred during the execution of the function.

HELICS_EXPORT HelicsFederate helicsCreateMessageFederate(const char * fedName, HelicsFederateInfo fi, HelicsError * err)

Create a message federate from a federate info object.

helics_message_federate objects can be used in all functions that take a helics_message_federate or HelicsFederate object as an argument.

Return
An opaque message federate object.
Parameters
  • fedName: The name of the federate to create.
  • fi: The federate info object that contains details on the federate.
  • err: An error object that will contain an error code and string if any error occurred during the execution of the function.

HELICS_EXPORT HelicsFederate helicsCreateMessageFederateFromConfig(const char * configFile, HelicsError * err)

Create a message federate from a JSON file or JSON string or TOML file.

helics_message_federate objects can be used in all functions that take a helics_message_federate or HelicsFederate object as an argument.

Return
An opaque message federate object.
Parameters
  • configFile: A Config(JSON,TOML) file or a JSON string that contains setup and configuration information.
  • err: An error object that will contain an error code and string if any error occurred during the execution of the function.

HELICS_EXPORT HelicsFederate helicsCreateCombinationFederate(const char * fedName, HelicsFederateInfo fi, HelicsError * err)

Create a combination federate from a federate info object.

Combination federates are both value federates and message federates, objects can be used in all functions that take a HelicsFederate, helics_message_federate or HelicsFederate object as an argument

Return
An opaque value federate object nullptr if the object creation failed.
Parameters
  • fedName: A string with the name of the federate, can be NULL or an empty string to pull the default name from fi.
  • fi: The federate info object that contains details on the federate.
  • err: An error object that will contain an error code and string if any error occurred during the execution of the function.

HELICS_EXPORT HelicsFederate helicsCreateCombinationFederateFromConfig(const char * configFile, HelicsError * err)

Create a combination federate from a JSON file or JSON string or TOML file.

Combination federates are both value federates and message federates, objects can be used in all functions that take a HelicsFederate, helics_message_federate or HelicsFederate object as an argument

Return
An opaque combination federate object.
Parameters
  • configFile: A JSON file or a JSON string or TOML file that contains setup and configuration information.
  • err: An error object that will contain an error code and string if any error occurred during the execution of the function.

HELICS_EXPORT HelicsFederateInfo helicsCreateFederateInfo(void)

Create a federate info object for specifying federate information when constructing a federate.

Return
A HelicsFederateInfo object which is a reference to the created object.

HELICS_EXPORT HelicsQuery helicsCreateQuery(const char * target, const char * query)

Create a query object.

A query object consists of a target and query string.

Parameters
  • target: The name of the target to query.
  • query: The query to make of the target.

Broker

HELICS_EXPORT HelicsBroker helicsBrokerClone(HelicsBroker broker, HelicsError * err)

Create a new reference to an existing broker.

This will create a new broker object that references the existing broker it must be freed as well.

Return
A new reference to the same broker.
Parameters
  • broker: An existing HelicsBroker.
  • err: An error object that will contain an error code and string if any error occurred during the execution of the function.

HELICS_EXPORT HelicsBool helicsBrokerIsValid(HelicsBroker broker)

Check if a broker object is a valid object.

Parameters
  • broker: The HelicsBroker object to test.

HELICS_EXPORT HelicsBool helicsBrokerIsConnected(HelicsBroker broker)

Check if a broker is connected.

A connected broker implies it is attached to cores or cores could reach out to communicate.

Return
HELICS_FALSE if not connected.

HELICS_EXPORT void helicsBrokerDataLink(HelicsBroker broker, const char * source, const char * target, HelicsError * err)

Link a named publication and named input using a broker.

Parameters
  • broker: The broker to generate the connection from.
  • source: The name of the publication (cannot be NULL).
  • target: The name of the target to send the publication data (cannot be NULL).
  • err: A HelicsError object, can be NULL if the errors are to be ignored.

HELICS_EXPORT void helicsBrokerAddSourceFilterToEndpoint(HelicsBroker broker, const char * filter, const char * endpoint, HelicsError * err)

Link a named filter to a source endpoint.

Parameters
  • broker: The broker to generate the connection from.
  • filter: The name of the filter (cannot be NULL).
  • endpoint: The name of the endpoint to filter the data from (cannot be NULL).
  • err: A HelicsError object, can be NULL if the errors are to be ignored.

HELICS_EXPORT void helicsBrokerAddDestinationFilterToEndpoint(HelicsBroker broker, const char * filter, const char * endpoint, HelicsError * err)

Link a named filter to a destination endpoint.

Parameters
  • broker: The broker to generate the connection from.
  • filter: The name of the filter (cannot be NULL).
  • endpoint: The name of the endpoint to filter the data going to (cannot be NULL).
  • err: A HelicsError object, can be NULL if the errors are to be ignored.

HELICS_EXPORT void helicsBrokerMakeConnections(HelicsBroker broker, const char * file, HelicsError * err)

Load a file containing connection information.

Parameters
  • broker: The broker to generate the connections from.
  • file: A JSON or TOML file containing connection information.
  • err: A HelicsError object, can be NULL if the errors are to be ignored.

HELICS_EXPORT HelicsBool helicsBrokerWaitForDisconnect(HelicsBroker broker, int msToWait, HelicsError * err)

Wait for the broker to disconnect.

Return
HELICS_TRUE if the disconnect was successful, HELICS_FALSE if there was a timeout.
Parameters
  • broker: The broker to wait for.
  • msToWait: The time out in millisecond (<0 for infinite timeout).
  • err: An error object that will contain an error code and string if any error occurred during the execution of the function.

HELICS_EXPORT const char* helicsBrokerGetIdentifier(HelicsBroker broker)

Get an identifier for the broker.

Return
A string containing the identifier for the broker.
Parameters
  • broker: The broker to query.

HELICS_EXPORT const char* helicsBrokerGetAddress(HelicsBroker broker)

Get the network address associated with a broker.

Return
A string with the network address of the broker.
Parameters
  • broker: The broker to query.

HELICS_EXPORT void helicsBrokerDisconnect(HelicsBroker broker, HelicsError * err)

Disconnect a broker.

Parameters
  • broker: The broker to disconnect.
  • err: An error object that will contain an error code and string if any error occurred during the execution of the function.

HELICS_EXPORT void helicsBrokerDestroy(HelicsBroker broker)

Disconnect and free a broker.

HELICS_EXPORT void helicsBrokerFree(HelicsBroker broker)

Release the memory associated with a broker.

HELICS_EXPORT void helicsBrokerSetGlobal(HelicsBroker broker, const char * valueName, const char * value, HelicsError * err)

Set a federation global value.

This overwrites any previous value for this name.

Parameters
  • broker: The broker to set the global through.
  • valueName: The name of the global to set.
  • value: The value of the global.
  • err: An error object that will contain an error code and string if any error occurred during the execution of the function.

HELICS_EXPORT void helicsBrokerSendCommand(HelicsBroker broker, const char * target, const char * command, HelicsError * err)

Send a command to another helics object through a broker.

Parameters
  • broker: The broker to send the command through.
  • target: The name of the object to send the command to.
  • command: The command to send.
  • err: An error object that will contain an error code and string if any error occurred during the execution of the function.

HELICS_EXPORT void helicsBrokerSetLogFile(HelicsBroker broker, const char * logFileName, HelicsError * err)

Set the log file on a broker.

Parameters
  • broker: The broker to set the log file for.
  • logFileName: The name of the file to log to.
  • err: An error object that will contain an error code and string if any error occurred during the execution of the function.

HELICS_EXPORT void helicsBrokerSetTimeBarrier(HelicsBroker broker, HelicsTime barrierTime, HelicsError * err)

Set a broker time barrier.

Parameters
  • broker: The broker to set the time barrier for.
  • barrierTime: The time to set the barrier at.
  • err: An error object that will contain an error code and string if any error occurred during the execution of the function.

HELICS_EXPORT void helicsBrokerClearTimeBarrier(HelicsBroker broker)

Clear any time barrier on a broker.

Parameters
  • broker: The broker to clear the barriers on.

HELICS_EXPORT void helicsBrokerGlobalError(HelicsBroker broker, int errorCode, const char * errorString, HelicsError * err)

Generate a global error through a broker. This will terminate the federation.

Parameters
  • broker: The broker to generate the global error on.
  • errorCode: The error code to associate with the global error.
  • errorString: An error message to associate with the global error.
  • err: An error object that will contain an error code and string if any error occurred during the execution of the function.

HELICS_EXPORT void helicsBrokerSetLoggingCallback(HelicsBroker broker, void(*logger)(int loglevel, const char *identifier, const char *message, void *userData), void * userdata, HelicsError * err)

Set the logging callback to a broker.

Add a logging callback function to a broker. The logging callback will be called when a message flows into a broker from the core or from a broker.

Parameters
  • broker: The broker object in which to set the callback.
  • logger: A callback with signature void(int, const char *, const char *, void *); the function arguments are loglevel, an identifier, a message string, and a pointer to user data.
  • userdata: A pointer to user data that is passed to the function when executing.
  • err: A pointer to an error object for catching errors.

Core

HELICS_EXPORT HelicsCore helicsCoreClone(HelicsCore core, HelicsError * err)

Create a new reference to an existing core.

This will create a new broker object that references the existing broker. The new broker object must be freed as well.

Return
A new reference to the same broker.
Parameters
  • core: An existing HelicsCore.
  • err: An error object that will contain an error code and string if any error occurred during the execution of the function.

HELICS_EXPORT HelicsBool helicsCoreIsValid(HelicsCore core)

Check if a core object is a valid object.

Parameters
  • core: The HelicsCore object to test.

HELICS_EXPORT HelicsBool helicsCoreWaitForDisconnect(HelicsCore core, int msToWait, HelicsError * err)

Wait for the core to disconnect.

Return
HELICS_TRUE if the disconnect was successful, HELICS_FALSE if there was a timeout.
Parameters
  • core: The core to wait for.
  • msToWait: The time out in millisecond (<0 for infinite timeout).
  • err: An error object that will contain an error code and string if any error occurred during the execution of the function.

HELICS_EXPORT HelicsBool helicsCoreIsConnected(HelicsCore core)

Check if a core is connected.

A connected core implies it is attached to federates or federates could be attached to it

Return
HELICS_FALSE if not connected, HELICS_TRUE if it is connected.

HELICS_EXPORT void helicsCoreDataLink(HelicsCore core, const char * source, const char * target, HelicsError * err)

Link a named publication and named input using a core.

Parameters
  • core: The core to generate the connection from.
  • source: The name of the publication (cannot be NULL).
  • target: The name of the target to send the publication data (cannot be NULL).
  • err: A HelicsError object, can be NULL if the errors are to be ignored.

HELICS_EXPORT void helicsCoreAddSourceFilterToEndpoint(HelicsCore core, const char * filter, const char * endpoint, HelicsError * err)

Link a named filter to a source endpoint.

Parameters
  • core: The core to generate the connection from.
  • filter: The name of the filter (cannot be NULL).
  • endpoint: The name of the endpoint to filter the data from (cannot be NULL).
  • err: A HelicsError object, can be NULL if the errors are to be ignored.

HELICS_EXPORT void helicsCoreAddDestinationFilterToEndpoint(HelicsCore core, const char * filter, const char * endpoint, HelicsError * err)

Link a named filter to a destination endpoint.

Parameters
  • core: The core to generate the connection from.
  • filter: The name of the filter (cannot be NULL).
  • endpoint: The name of the endpoint to filter the data going to (cannot be NULL).
  • err: A HelicsError object, can be NULL if the errors are to be ignored.

HELICS_EXPORT void helicsCoreMakeConnections(HelicsCore core, const char * file, HelicsError * err)

Load a file containing connection information.

Parameters
  • core: The core to generate the connections from.
  • file: A JSON or TOML file containing connection information.
  • err: A HelicsError object, can be NULL if the errors are to be ignored.

HELICS_EXPORT const char* helicsCoreGetIdentifier(HelicsCore core)

Get an identifier for the core.

Return
A string with the identifier of the core.
Parameters
  • core: The core to query.

HELICS_EXPORT const char* helicsCoreGetAddress(HelicsCore core)

Get the network address associated with a core.

Return
A string with the network address of the broker.
Parameters
  • core: The core to query.

HELICS_EXPORT void helicsCoreSetReadyToInit(HelicsCore core, HelicsError * err)

Set the core to ready for init.

This function is used for cores that have filters but no federates so there needs to be a direct signal to the core to trigger the federation initialization.

Parameters
  • core: The core object to enable init values for.
  • err: An error object that will contain an error code and string if any error occurred during the execution of the function.

HELICS_EXPORT HelicsBool helicsCoreConnect(HelicsCore core, HelicsError * err)

Connect a core to the federate based on current configuration.

Return
HELICS_FALSE if not connected, HELICS_TRUE if it is connected.
Parameters
  • core: The core to connect.
  • err: An error object that will contain an error code and string if any error occurred during the execution of the function.

HELICS_EXPORT void helicsCoreDisconnect(HelicsCore core, HelicsError * err)

Disconnect a core from the federation.

Parameters
  • core: The core to query.
  • err: An error object that will contain an error code and string if any error occurred during the execution of the function.

HELICS_EXPORT void helicsCoreDestroy(HelicsCore core)

Disconnect and free a core.

HELICS_EXPORT void helicsCoreFree(HelicsCore core)

Release the memory associated with a core.

HELICS_EXPORT void helicsCoreSetGlobal(HelicsCore core, const char * valueName, const char * value, HelicsError * err)

Set a global value in a core.

This overwrites any previous value for this name.

Parameters
  • core: The core to set the global through.
  • valueName: The name of the global to set.
  • value: The value of the global.
  • err: An error object that will contain an error code and string if any error occurred during the execution of the function.

HELICS_EXPORT void helicsCoreSendCommand(HelicsCore core, const char * target, const char * command, HelicsError * err)

Send a command to another helics object though a core.

Parameters
  • core: The core to send the command through.
  • target: The name of the object to send the command to.
  • command: The command to send.
  • err: An error object that will contain an error code and string if any error occurred during the execution of the function.

HELICS_EXPORT void helicsCoreSetLogFile(HelicsCore core, const char * logFileName, HelicsError * err)

Set the log file on a core.

Parameters
  • core: The core to set the log file for.
  • logFileName: The name of the file to log to.
  • err: An error object that will contain an error code and string if any error occurred during the execution of the function.

HELICS_EXPORT void helicsCoreGlobalError(HelicsCore core, int errorCode, const char * errorString, HelicsError * err)

Generate a global error through a broker. This will terminate the federation.

Parameters
  • core: The core to generate the global error.
  • errorCode: The error code to associate with the global error.
  • errorString: An error message to associate with the global error.
  • err: An error object that will contain an error code and string if any error occurred during the execution of the function.

HELICS_EXPORT void helicsCoreSetLoggingCallback(HelicsCore core, void(*logger)(int loglevel, const char *identifier, const char *message, void *userData), void * userdata, HelicsError * err)

Set the logging callback for a core.

Add a logging callback function to a core. The logging callback will be called when a message flows into a core from the core or from a broker.

Parameters
  • core: The core object in which to set the callback.
  • logger: A callback with signature void(int, const char *, const char *, void *); The function arguments are loglevel, an identifier, a message string, and a pointer to user data.
  • userdata: A pointer to user data that is passed to the function when executing.
  • err: A pointer to an error object for catching errors.

HELICS_EXPORT HelicsFilter helicsCoreRegisterFilter(HelicsCore core, HelicsFilterTypes type, const char * name, HelicsError * err)

Create a source Filter on the specified core.

Filters can be created through a federate or a core, linking through a federate allows a few extra features of name matching to function on the federate interface but otherwise equivalent behavior.

Return
A HelicsFilter object.
Parameters
  • core: The core to register through.
  • type: The type of filter to create /ref HelicsFilterTypes.
  • name: The name of the filter (can be NULL).
  • err: A pointer to an error object for catching errors.

HELICS_EXPORT HelicsFilter helicsCoreRegisterCloningFilter(HelicsCore core, const char * name, HelicsError * err)

Create a cloning Filter on the specified core.

Cloning filters copy a message and send it to multiple locations, source and destination can be added through other functions.

Return
A HelicsFilter object.
Parameters
  • core: The core to register through.
  • name: The name of the filter (can be NULL).
  • err: A pointer to an error object for catching errors.

FederateInfo

HELICS_EXPORT HelicsFederateInfo helicsFederateInfoClone(HelicsFederateInfo fi, HelicsError * err)

Create a federate info object from an existing one and clone the information.

Return
A HelicsFederateInfo object which is a reference to the created object.
Parameters
  • fi: A federateInfo object to duplicate.
  • err: An error object that will contain an error code and string if any error occurred during the execution of the function.

HELICS_EXPORT void helicsFederateInfoLoadFromArgs(HelicsFederateInfo fi, int argc, const char *const * argv, HelicsError * err)

Load federate info from command line arguments.

Parameters
  • fi: A federateInfo object.
  • argc: The number of command line arguments.
  • argv: An array of strings from the command line.
  • err: An error object that will contain an error code and string if any error occurred during the execution of the function.

HELICS_EXPORT void helicsFederateInfoFree(HelicsFederateInfo fi)

Delete the memory associated with a federate info object.

HELICS_EXPORT void helicsFederateInfoSetCoreName(HelicsFederateInfo fi, const char * corename, HelicsError * err)

Set the name of the core to link to for a federate.

Parameters
  • fi: The federate info object to alter.
  • corename: The identifier for a core to link to.
  • err: An error object that will contain an error code and string if any error occurred during the execution of the function.

HELICS_EXPORT void helicsFederateInfoSetCoreInitString(HelicsFederateInfo fi, const char * coreInit, HelicsError * err)

Set the initialization string for the core usually in the form of command line arguments.

Parameters
  • fi: The federate info object to alter.
  • coreInit: A string containing command line arguments to be passed to the core.
  • err: An error object that will contain an error code and string if any error occurred during the execution of the function.

HELICS_EXPORT void helicsFederateInfoSetBrokerInitString(HelicsFederateInfo fi, const char * brokerInit, HelicsError * err)

Set the initialization string that a core will pass to a generated broker usually in the form of command line arguments.

Parameters
  • fi: The federate info object to alter.
  • brokerInit: A string with command line arguments for a generated broker.
  • err: An error object that will contain an error code and string if any error occurred during the execution of the function.

HELICS_EXPORT void helicsFederateInfoSetCoreType(HelicsFederateInfo fi, int coretype, HelicsError * err)

Set the core type by integer code.

Valid values available by definitions in api-data.h.

Parameters
  • fi: The federate info object to alter.
  • coretype: An numerical code for a core type see /ref helics_CoreType.
  • err: An error object that will contain an error code and string if any error occurred during the execution of the function.

HELICS_EXPORT void helicsFederateInfoSetCoreTypeFromString(HelicsFederateInfo fi, const char * coretype, HelicsError * err)

Set the core type from a string.

Parameters
  • fi: The federate info object to alter.
  • coretype: A string naming a core type.
  • err: An error object that will contain an error code and string if any error occurred during the execution of the function.

HELICS_EXPORT void helicsFederateInfoSetBroker(HelicsFederateInfo fi, const char * broker, HelicsError * err)

Set the name or connection information for a broker.

This is only used if the core is automatically created, the broker information will be transferred to the core for connection.

Parameters
  • fi: The federate info object to alter.
  • broker: A string which defines the connection information for a broker either a name or an address.
  • err: An error object that will contain an error code and string if any error occurred during the execution of the function.

HELICS_EXPORT void helicsFederateInfoSetBrokerKey(HelicsFederateInfo fi, const char * brokerkey, HelicsError * err)

Set the key for a broker connection.

This is only used if the core is automatically created, the broker information will be transferred to the core for connection.

Parameters
  • fi: The federate info object to alter.
  • brokerkey: A string containing a key for the broker to connect.
  • err: An error object that will contain an error code and string if any error occurred during the execution of the function.

HELICS_EXPORT void helicsFederateInfoSetBrokerPort(HelicsFederateInfo fi, int brokerPort, HelicsError * err)

Set the port to use for the broker.

This is only used if the core is automatically created, the broker information will be transferred to the core for connection. This will only be useful for network broker connections.

Parameters
  • fi: The federate info object to alter.
  • brokerPort: The integer port number to use for connection with a broker.
  • err: An error object that will contain an error code and string if any error occurred during the execution of the function.

HELICS_EXPORT void helicsFederateInfoSetLocalPort(HelicsFederateInfo fi, const char * localPort, HelicsError * err)

Set the local port to use.

This is only used if the core is automatically created, the port information will be transferred to the core for connection.

Parameters
  • fi: The federate info object to alter.
  • localPort: A string with the port information to use as the local server port can be a number or “auto” or “os_local”.
  • err: An error object that will contain an error code and string if any error occurred during the execution of the function.

HELICS_EXPORT void helicsFederateInfoSetFlagOption(HelicsFederateInfo fi, int flag, HelicsBool value, HelicsError * err)

Set a flag in the info structure.

Valid flags are available /ref helics_federate_flags.

Parameters
  • fi: The federate info object to alter.
  • flag: A numerical index for a flag.
  • value: The desired value of the flag HELICS_TRUE or HELICS_FALSE.
  • err: An error object that will contain an error code and string if any error occurred during the execution of the function.

HELICS_EXPORT void helicsFederateInfoSetSeparator(HelicsFederateInfo fi, char separator, HelicsError * err)

Set the separator character in the info structure.

The separator character is the separation character for local publications/endpoints in creating their global name. For example if the separator character is ‘/’ then a local endpoint would have a globally reachable name of fedName/localName.

Parameters
  • fi: The federate info object to alter.
  • separator: The character to use as a separator.
  • err: An error object that will contain an error code and string if any error occurred during the execution of the function.

HELICS_EXPORT void helicsFederateInfoSetTimeProperty(HelicsFederateInfo fi, int timeProperty, HelicsTime propertyValue, HelicsError * err)

Set the output delay for a federate.

Parameters
  • fi: The federate info object to alter.
  • timeProperty: An integer representation of the time based property to set see /ref helics_properties.
  • propertyValue: The value of the property to set the timeProperty to.
  • err: An error object that will contain an error code and string if any error occurred during the execution of the function.

HELICS_EXPORT void helicsFederateInfoSetIntegerProperty(HelicsFederateInfo fi, int intProperty, int propertyValue, HelicsError * err)

Set an integer property for a federate.

Set known properties.

Parameters
  • fi: The federateInfo object to alter.
  • intProperty: An int identifying the property.
  • propertyValue: The value to set the property to.
  • err: An error object that will contain an error code and string if any error occurred during the execution of the function.

Federate

HELICS_EXPORT void helicsFederateDestroy(HelicsFederate fed)

Disconnect and free a federate.

HELICS_EXPORT HelicsFederate helicsFederateClone(HelicsFederate fed, HelicsError * err)

Create a new reference to an existing federate.

This will create a new HelicsFederate object that references the existing federate. The new object must be freed as well.

Return
A new reference to the same federate.
Parameters
  • fed: An existing HelicsFederate.
  • err: An error object that will contain an error code and string if any error occurred during the execution of the function.

HELICS_EXPORT HelicsBool helicsFederateIsValid(HelicsFederate fed)

Check if a federate_object is valid.

Return
HELICS_TRUE if the federate is a valid active federate, HELICS_FALSE otherwise

HELICS_EXPORT void helicsFederateRegisterInterfaces(HelicsFederate fed, const char * file, HelicsError * err)

Load interfaces from a file.

Parameters
  • fed: The federate to which to load interfaces.
  • file: The name of a file to load the interfaces from either JSON, or TOML.
  • err: An error object that will contain an error code and string if any error occurred during the execution of the function.

HELICS_EXPORT void helicsFederateGlobalError(HelicsFederate fed, int errorCode, const char * errorString, HelicsError * err)

Generate a global error from a federate.

A global error halts the co-simulation completely.

Parameters
  • fed: The federate to create an error in.
  • errorCode: The integer code for the error.
  • errorString: A string describing the error.
  • err: An error object that will contain an error code and string if any error occurred during the execution of the function.

HELICS_EXPORT void helicsFederateLocalError(HelicsFederate fed, int errorCode, const char * errorString, HelicsError * err)

Generate a local error in a federate.

This will propagate through the co-simulation but not necessarily halt the co-simulation, it has a similar effect to finalize but does allow some interaction with a core for a brief time.

Parameters
  • fed: The federate to create an error in.
  • errorCode: The integer code for the error.
  • errorString: A string describing the error.
  • err: An error object that will contain an error code and string if any error occurred during the execution of the function.

HELICS_EXPORT void helicsFederateFinalize(HelicsFederate fed, HelicsError * err)

Disconnect/finalize the federate. This function halts all communication in the federate and disconnects it from the core.

HELICS_EXPORT void helicsFederateFinalizeAsync(HelicsFederate fed, HelicsError * err)

Disconnect/finalize the federate in an async call.

HELICS_EXPORT void helicsFederateFinalizeComplete(HelicsFederate fed, HelicsError * err)

Complete the asynchronous disconnect/finalize call.

HELICS_EXPORT void helicsFederateDisconnect(HelicsFederate fed, HelicsError * err)

Disconnect/finalize the federate. This function halts all communication in the federate and disconnects it from the core. This call is identical to helicsFederateFinalize.

HELICS_EXPORT void helicsFederateDisconnectAsync(HelicsFederate fed, HelicsError * err)

Disconnect/finalize the federate in an async call. This call is identical to helicsFederateFinalizeAsync.

HELICS_EXPORT void helicsFederateDisconnectComplete(HelicsFederate fed, HelicsError * err)

Complete the asynchronous disconnect/finalize call. This call is identical to helicsFederateFinalizeComplete

HELICS_EXPORT void helicsFederateFree(HelicsFederate fed)

Release the memory associated with a federate.

HELICS_EXPORT void helicsFederateEnterInitializingMode(HelicsFederate fed, HelicsError * err)

Enter the initialization state of a federate.

The initialization state allows initial values to be set and received if the iteration is requested on entry to the execution state. This is a blocking call and will block until the core allows it to proceed.

Parameters
  • fed: The federate to operate on.
  • err: An error object that will contain an error code and string if any error occurred during the execution of the function.

HELICS_EXPORT void helicsFederateEnterInitializingModeAsync(HelicsFederate fed, HelicsError * err)

Non blocking alternative to helicsFederateEnterInitializingMode.

The function helicsFederateEnterInitializationModeFinalize must be called to finish the operation.

Parameters
  • fed: The federate to operate on.
  • err: An error object that will contain an error code and string if any error occurred during the execution of the function.

HELICS_EXPORT HelicsBool helicsFederateIsAsyncOperationCompleted(HelicsFederate fed, HelicsError * err)

Check if the current Asynchronous operation has completed.

Return
HELICS_FALSE if not completed, HELICS_TRUE if completed.
Parameters
  • fed: The federate to operate on.
  • err: An error object that will contain an error code and string if any error occurred during the execution of the function.

HELICS_EXPORT void helicsFederateEnterInitializingModeComplete(HelicsFederate fed, HelicsError * err)

Finalize the entry to initialize mode that was initiated with /ref heliceEnterInitializingModeAsync.

Parameters
  • fed: The federate desiring to complete the initialization step.
  • err: An error object that will contain an error code and string if any error occurred during the execution of the function.

HELICS_EXPORT void helicsFederateEnterExecutingMode(HelicsFederate fed, HelicsError * err)

Request that the federate enter the Execution mode.

This call is blocking until granted entry by the core object. On return from this call the federate will be at time 0. For an asynchronous alternative call see /ref helicsFederateEnterExecutingModeAsync.

Parameters
  • fed: A federate to change modes.
  • err: An error object that will contain an error code and string if any error occurred during the execution of the function.

HELICS_EXPORT void helicsFederateEnterExecutingModeAsync(HelicsFederate fed, HelicsError * err)

Request that the federate enter the Execution mode.

This call is non-blocking and will return immediately. Call /ref helicsFederateEnterExecutingModeComplete to finish the call sequence.

Parameters
  • fed: The federate object to complete the call.
  • err: An error object that will contain an error code and string if any error occurred during the execution of the function.

HELICS_EXPORT void helicsFederateEnterExecutingModeComplete(HelicsFederate fed, HelicsError * err)

Complete the call to /ref helicsFederateEnterExecutingModeAsync.

Parameters
  • fed: The federate object to complete the call.
  • err: An error object that will contain an error code and string if any error occurred during the execution of the function.

HELICS_EXPORT HelicsIterationResult helicsFederateEnterExecutingModeIterative(HelicsFederate fed, HelicsIterationRequest iterate, HelicsError * err)

Request an iterative time.

This call allows for finer grain control of the iterative process than /ref helicsFederateRequestTime. It takes a time and iteration request, and returns a time and iteration status.

Return
An iteration structure with field containing the time and iteration status.
Parameters
  • fed: The federate to make the request of.
  • iterate: The requested iteration mode.
  • err: An error object that will contain an error code and string if any error occurred during the execution of the function.

HELICS_EXPORT void helicsFederateEnterExecutingModeIterativeAsync(HelicsFederate fed, HelicsIterationRequest iterate, HelicsError * err)

Request an iterative entry to the execution mode.

This call allows for finer grain control of the iterative process than /ref helicsFederateRequestTime. It takes a time and iteration request, and returns a time and iteration status

Parameters
  • fed: The federate to make the request of.
  • iterate: The requested iteration mode.
  • err: An error object that will contain an error code and string if any error occurred during the execution of the function.

HELICS_EXPORT HelicsIterationResult helicsFederateEnterExecutingModeIterativeComplete(HelicsFederate fed, HelicsError * err)

Complete the asynchronous iterative call into ExecutionMode.

Return
An iteration object containing the iteration time and iteration_status.
Parameters
  • fed: The federate to make the request of.
  • err: An error object that will contain an error code and string if any error occurred during the execution of the function.

HELICS_EXPORT HelicsFederateState helicsFederateGetState(HelicsFederate fed, HelicsError * err)

Get the current state of a federate.

Return
State the resulting state if void return HELICS_OK.
Parameters
  • fed: The federate to query.
  • err: An error object that will contain an error code and string if any error occurred during the execution of the function.

HELICS_EXPORT HelicsCore helicsFederateGetCore(HelicsFederate fed, HelicsError * err)

Get the core object associated with a federate.

Return
A core object, nullptr if invalid.
Parameters
  • fed: A federate object.
  • err: An error object that will contain an error code and string if any error occurred during the execution of the function.

HELICS_EXPORT HelicsTime helicsFederateRequestTime(HelicsFederate fed, HelicsTime requestTime, HelicsError * err)

Request the next time for federate execution.

Return
The time granted to the federate, will return HELICS_TIME_MAXTIME if the simulation has terminated or is invalid.
Parameters
  • fed: The federate to make the request of.
  • requestTime: The next requested time.
  • err: An error object that will contain an error code and string if any error occurred during the execution of the function.

HELICS_EXPORT HelicsTime helicsFederateRequestTimeAdvance(HelicsFederate fed, HelicsTime timeDelta, HelicsError * err)

Request the next time for federate execution.

Return
The time granted to the federate, will return HELICS_TIME_MAXTIME if the simulation has terminated or is invalid
Parameters
  • fed: The federate to make the request of.
  • timeDelta: The requested amount of time to advance.
  • err: An error object that will contain an error code and string if any error occurred during the execution of the function.

HELICS_EXPORT HelicsTime helicsFederateRequestNextStep(HelicsFederate fed, HelicsError * err)

Request the next time step for federate execution.

Feds should have setup the period or minDelta for this to work well but it will request the next time step which is the current time plus the minimum time step.

Return
The time granted to the federate, will return HELICS_TIME_MAXTIME if the simulation has terminated or is invalid
Parameters
  • fed: The federate to make the request of.
  • err: An error object that will contain an error code and string if any error occurred during the execution of the function.

HELICS_EXPORT HelicsTime helicsFederateRequestTimeIterative(HelicsFederate fed, HelicsTime requestTime, HelicsIterationRequest iterate, HelicsIterationResult * outIteration, HelicsError * err)

Request an iterative time.

This call allows for finer grain control of the iterative process than /ref helicsFederateRequestTime. It takes a time and and iteration request, and returns a time and iteration status.

Return
The granted time, will return HELICS_TIME_MAXTIME if the simulation has terminated along with the appropriate iteration result.
Parameters
  • fed: The federate to make the request of.
  • requestTime: The next desired time.
  • iterate: The requested iteration mode.
  • outIteration: The iteration specification of the result.
  • err: An error object that will contain an error code and string if any error occurred during the execution of the function.

HELICS_EXPORT void helicsFederateRequestTimeAsync(HelicsFederate fed, HelicsTime requestTime, HelicsError * err)

Request the next time for federate execution in an asynchronous call.

Call /ref helicsFederateRequestTimeComplete to finish the call.

Parameters
  • fed: The federate to make the request of.
  • requestTime: The next requested time.
  • err: An error object that will contain an error code and string if any error occurred during the execution of the function.

HELICS_EXPORT HelicsTime helicsFederateRequestTimeComplete(HelicsFederate fed, HelicsError * err)

Complete an asynchronous requestTime call.

Return
The time granted to the federate, will return HELICS_TIME_MAXTIME if the simulation has terminated.
Parameters
  • fed: The federate to make the request of.
  • err: An error object that will contain an error code and string if any error occurred during the execution of the function.

HELICS_EXPORT void helicsFederateRequestTimeIterativeAsync(HelicsFederate fed, HelicsTime requestTime, HelicsIterationRequest iterate, HelicsError * err)

Request an iterative time through an asynchronous call.

This call allows for finer grain control of the iterative process than /ref helicsFederateRequestTime. It takes a time and iteration request, and returns a time and iteration status. Call /ref helicsFederateRequestTimeIterativeComplete to finish the process.

Parameters
  • fed: The federate to make the request of.
  • requestTime: The next desired time.
  • iterate: The requested iteration mode.
  • err: An error object that will contain an error code and string if any error occurred during the execution of the function.

HELICS_EXPORT HelicsTime helicsFederateRequestTimeIterativeComplete(HelicsFederate fed, HelicsIterationResult * outIterate, HelicsError * err)

Complete an iterative time request asynchronous call.

Return
The granted time, will return HELICS_TIME_MAXTIME if the simulation has terminated.
Parameters
  • fed: The federate to make the request of.
  • outIterate: The iteration specification of the result.
  • err: An error object that will contain an error code and string if any error occurred during the execution of the function.

HELICS_EXPORT const char* helicsFederateGetName(HelicsFederate fed)

Get the name of the federate.

Return
A pointer to a string with the name.
Parameters
  • fed: The federate object to query.

HELICS_EXPORT void helicsFederateSetTimeProperty(HelicsFederate fed, int timeProperty, HelicsTime time, HelicsError * err)

Set a time based property for a federate.

Parameters
  • fed: The federate object to set the property for.
  • timeProperty: A integer code for a time property.
  • time: The requested value of the property.
  • err: An error object that will contain an error code and string if any error occurred during the execution of the function.

HELICS_EXPORT void helicsFederateSetFlagOption(HelicsFederate fed, int flag, HelicsBool flagValue, HelicsError * err)

Set a flag for the federate.

Parameters
  • fed: The federate to alter a flag for.
  • flag: The flag to change.
  • flagValue: The new value of the flag. 0 for false, !=0 for true.
  • err: An error object that will contain an error code and string if any error occurred during the execution of the function.

HELICS_EXPORT void helicsFederateSetSeparator(HelicsFederate fed, char separator, HelicsError * err)

Set the separator character in a federate.

The separator character is the separation character for local publications/endpoints in creating their global name. For example if the separator character is ‘/’ then a local endpoint would have a globally reachable name of fedName/localName.

Parameters
  • fed: The federate info object to alter.
  • separator: The character to use as a separator.
  • err: An error object that will contain an error code and string if any error occurred during the execution of the function.

HELICS_EXPORT void helicsFederateSetIntegerProperty(HelicsFederate fed, int intProperty, int propertyVal, HelicsError * err)

Set an integer based property of a federate.

Parameters
  • fed: The federate to change the property for.
  • intProperty: The property to set.
  • propertyVal: The value of the property.
  • err: An error object that will contain an error code and string if any error occurred during the execution of the function.

HELICS_EXPORT HelicsTime helicsFederateGetTimeProperty(HelicsFederate fed, int timeProperty, HelicsError * err)

Get the current value of a time based property in a federate.

Parameters
  • fed: The federate query.
  • timeProperty: The property to query.
  • err: An error object that will contain an error code and string if any error occurred during the execution of the function.

HELICS_EXPORT HelicsBool helicsFederateGetFlagOption(HelicsFederate fed, int flag, HelicsError * err)

Get a flag value for a federate.

Return
The value of the flag.
Parameters
  • fed: The federate to get the flag for.
  • flag: The flag to query.
  • err: A pointer to an error object for catching errors.

HELICS_EXPORT int helicsFederateGetIntegerProperty(HelicsFederate fed, int intProperty, HelicsError * err)

Get the current value of an integer property (such as a logging level).

Return
The value of the property.
Parameters
  • fed: The federate to get the flag for.
  • intProperty: A code for the property to set /ref helics_handle_options.
  • err: A pointer to an error object for catching errors.

HELICS_EXPORT HelicsTime helicsFederateGetCurrentTime(HelicsFederate fed, HelicsError * err)

Get the current time of the federate.

Return
The current time of the federate.
Parameters
  • fed: The federate object to query.
  • err: A pointer to an error object for catching errors.

HELICS_EXPORT void helicsFederateSetGlobal(HelicsFederate fed, const char * valueName, const char * value, HelicsError * err)

Set a federation global value through a federate.

This overwrites any previous value for this name.

Parameters
  • fed: The federate to set the global through.
  • valueName: The name of the global to set.
  • value: The value of the global.
  • err: A pointer to an error object for catching errors.

HELICS_EXPORT void helicsFederateSetTag(HelicsFederate fed, const char * tagName, const char * value, HelicsError * err)

Set a federate tag value.

This overwrites any previous value for this tag.

Parameters
  • fed: The federate to set the tag for.
  • tagName: The name of the tag to set.
  • value: The value of the tag.
  • err: A pointer to an error object for catching errors.

HELICS_EXPORT const char* helicsFederateGetTag(HelicsFederate fed, const char * tagName, HelicsError * err)

Get a federate tag value.

Parameters
  • fed: The federate to get the tag for.
  • tagName: The name of the tag to query.
  • err: A pointer to an error object for catching errors.

HELICS_EXPORT void helicsFederateAddDependency(HelicsFederate fed, const char * fedName, HelicsError * err)

Add a time dependency for a federate. The federate will depend on the given named federate for time synchronization.

Parameters
  • fed: The federate to add the dependency for.
  • fedName: The name of the federate to depend on.
  • err: A pointer to an error object for catching errors.

HELICS_EXPORT void helicsFederateSetLogFile(HelicsFederate fed, const char * logFile, HelicsError * err)

Set the logging file for a federate (actually on the core associated with a federate).

Parameters
  • fed: The federate to set the log file for.
  • logFile: The name of the log file.
  • err: A pointer to an error object for catching errors.

HELICS_EXPORT void helicsFederateLogErrorMessage(HelicsFederate fed, const char * logmessage, HelicsError * err)

Log an error message through a federate.

Parameters
  • fed: The federate to log the error message through.
  • logmessage: The message to put in the log.
  • err: A pointer to an error object for catching errors.

HELICS_EXPORT void helicsFederateLogWarningMessage(HelicsFederate fed, const char * logmessage, HelicsError * err)

Log a warning message through a federate.

Parameters
  • fed: The federate to log the warning message through.
  • logmessage: The message to put in the log.
  • err: A pointer to an error object for catching errors.

HELICS_EXPORT void helicsFederateLogInfoMessage(HelicsFederate fed, const char * logmessage, HelicsError * err)

Log an info message through a federate.

Parameters
  • fed: The federate to log the info message through.
  • logmessage: The message to put in the log.
  • err: A pointer to an error object for catching errors.

HELICS_EXPORT void helicsFederateLogDebugMessage(HelicsFederate fed, const char * logmessage, HelicsError * err)

Log a debug message through a federate.

Parameters
  • fed: The federate to log the debug message through.
  • logmessage: The message to put in the log.
  • err: A pointer to an error object for catching errors.

HELICS_EXPORT void helicsFederateLogLevelMessage(HelicsFederate fed, int loglevel, const char * logmessage, HelicsError * err)

Log a message through a federate.

Parameters
  • fed: The federate to log the message through.
  • loglevel: The level of the message to log see /ref helics_log_levels.
  • logmessage: The message to put in the log.
  • err: A pointer to an error object for catching errors.

HELICS_EXPORT void helicsFederateSendCommand(HelicsFederate fed, const char * target, const char * command, HelicsError * err)

Send a command to another helics object through a federate.

Parameters
  • fed: The federate to send the command through.
  • target: The name of the object to send the command to.
  • command: The command to send.
  • err: An error object that will contain an error code and string if any error occurred during the execution of the function.

HELICS_EXPORT const char* helicsFederateGetCommand(HelicsFederate fed, HelicsError * err)

Get a command sent to the federate.

Return
A string with the command for the federate, if the string is empty no command is available.
Parameters
  • fed: The federate to get the command for.
  • err: An error object that will contain an error code and string if any error occurred during the execution of the function.

HELICS_EXPORT const char* helicsFederateGetCommandSource(HelicsFederate fed, HelicsError * err)

Get the source of the most recently retrieved command sent to the federate.

Return
A string with the command for the federate, if the string is empty no command is available.
Parameters
  • fed: The federate to get the command for.
  • err: An error object that will contain an error code and string if any error occurred during the execution of the function.

HELICS_EXPORT const char* helicsFederateWaitCommand(HelicsFederate fed, HelicsError * err)

Get a command sent to the federate. Blocks until a command is received.

Return
A string with the command for the federate, if the string is empty no command is available.
Parameters
  • fed: The federate to get the command for.
  • err: An error object that will contain an error code and string if any error occurred during the execution of the function.

HELICS_EXPORT void helicsFederateSetLoggingCallback(HelicsFederate fed, void(*logger)(int loglevel, const char *identifier, const char *message, void *userData), void * userdata, HelicsError * err)

Set the logging callback for a federate.

Add a logging callback function to a federate. The logging callback will be called when a message flows into a federate from the core or from a federate.

Parameters
  • fed: The federate object in which to create a subscription must have been created with helicsCreateValueFederate or helicsCreateCombinationFederate.
  • logger: A callback with signature void(int, const char *, const char *, void *); The function arguments are loglevel, an identifier string, a message string, and a pointer to user data.
  • userdata: A pointer to user data that is passed to the function when executing.
  • err: A pointer to an error object for catching errors.

HELICS_EXPORT void helicsFederateSetQueryCallback(HelicsFederate fed, void(*queryAnswer)(const char *query, int querySize, HelicsQueryBuffer buffer, void *userdata), void * userdata, HelicsError * err)

Set callback for queries executed against a federate.

There are many queries that HELICS understands directly, but it is occasionally useful to have a federate be able to respond to specific queries with answers specific to a federate.

Parameters
  • fed: The federate to set the callback for.
  • queryAnswer: A callback with signature const char *(const char *query, int querySize,int *answerSize, void *userdata); The function arguments are the query string requesting an answer along with its size, the string is not guaranteed to be null terminated answerSize is an outputParameter intended to filled out by the userCallback and should contain the length of the return string. The return pointer can be NULL if no answer is given and HELICS will generate the appropriate response.
  • userdata: A pointer to user data that is passed to the function when executing.
  • err: A pointer to an error object for catching errors.

ValueFederate

HELICS_EXPORT HelicsInput helicsFederateRegisterSubscription(HelicsFederate fed, const char * key, const char * units, HelicsError * err)

sub/pub registration Create a subscription.

The subscription becomes part of the federate and is destroyed when the federate is freed so there are no separate free functions for subscriptions and publications.

Return
An object containing the subscription.
Parameters
  • fed: The federate object in which to create a subscription, must have been created with /ref helicsCreateValueFederate or /ref helicsCreateCombinationFederate.
  • key: The identifier matching a publication to get a subscription for.
  • units: A string listing the units of the subscription (may be NULL).
  • err: A pointer to an error object for catching errors.

HELICS_EXPORT HelicsPublication helicsFederateRegisterPublication(HelicsFederate fed, const char * key, HelicsDataTypes type, const char * units, HelicsError * err)

Register a publication with a known type.

The publication becomes part of the federate and is destroyed when the federate is freed so there are no separate free functions for subscriptions and publications.

Return
An object containing the publication.
Parameters
  • fed: The federate object in which to create a publication.
  • key: The identifier for the publication the global publication key will be prepended with the federate name.
  • type: A code identifying the type of the input see /ref HelicsDataTypes for available options.
  • units: A string listing the units of the subscription (may be NULL).
  • err: A pointer to an error object for catching errors.

HELICS_EXPORT HelicsPublication helicsFederateRegisterTypePublication(HelicsFederate fed, const char * key, const char * type, const char * units, HelicsError * err)

Register a publication with a defined type.

The publication becomes part of the federate and is destroyed when the federate is freed so there are no separate free functions for subscriptions and publications.

Return
An object containing the publication.
Parameters
  • fed: The federate object in which to create a publication.
  • key: The identifier for the publication.
  • type: A string labeling the type of the publication.
  • units: A string listing the units of the subscription (may be NULL).
  • err: A pointer to an error object for catching errors.

HELICS_EXPORT HelicsPublication helicsFederateRegisterGlobalPublication(HelicsFederate fed, const char * key, HelicsDataTypes type, const char * units, HelicsError * err)

Register a global named publication with an arbitrary type.

The publication becomes part of the federate and is destroyed when the federate is freed so there are no separate free functions for subscriptions and publications.

Return
An object containing the publication.
Parameters
  • fed: The federate object in which to create a publication.
  • key: The identifier for the publication.
  • type: A code identifying the type of the input see /ref HelicsDataTypes for available options.
  • units: A string listing the units of the subscription (may be NULL).
  • err: A pointer to an error object for catching errors.

HELICS_EXPORT HelicsPublication helicsFederateRegisterGlobalTypePublication(HelicsFederate fed, const char * key, const char * type, const char * units, HelicsError * err)

Register a global publication with a defined type.

The publication becomes part of the federate and is destroyed when the federate is freed so there are no separate free functions for subscriptions and publications.

Return
An object containing the publication.
Parameters
  • fed: The federate object in which to create a publication.
  • key: The identifier for the publication.
  • type: A string describing the expected type of the publication.
  • units: A string listing the units of the subscription (may be NULL).
  • err: A pointer to an error object for catching errors.

HELICS_EXPORT HelicsInput helicsFederateRegisterInput(HelicsFederate fed, const char * key, HelicsDataTypes type, const char * units, HelicsError * err)

Register a named input.

The input becomes part of the federate and is destroyed when the federate is freed so there are no separate free functions for subscriptions, inputs, and publications.

Return
An object containing the input.
Parameters
  • fed: The federate object in which to create an input.
  • key: The identifier for the publication the global input key will be prepended with the federate name.
  • type: A code identifying the type of the input see /ref HelicsDataTypes for available options.
  • units: A string listing the units of the input (may be NULL).
  • err: A pointer to an error object for catching errors.

HELICS_EXPORT HelicsInput helicsFederateRegisterTypeInput(HelicsFederate fed, const char * key, const char * type, const char * units, HelicsError * err)

Register an input with a defined type.

The input becomes part of the federate and is destroyed when the federate is freed so there are no separate free functions for subscriptions, inputs, and publications.

Return
An object containing the publication.
Parameters
  • fed: The federate object in which to create an input.
  • key: The identifier for the input.
  • type: A string describing the expected type of the input.
  • units: A string listing the units of the input maybe NULL.
  • err: A pointer to an error object for catching errors.

HELICS_EXPORT HelicsPublication helicsFederateRegisterGlobalInput(HelicsFederate fed, const char * key, HelicsDataTypes type, const char * units, HelicsError * err)

Register a global named input.

The publication becomes part of the federate and is destroyed when the federate is freed so there are no separate free functions for subscriptions and publications.

Return
An object containing the publication.
Parameters
  • fed: The federate object in which to create a publication.
  • key: The identifier for the publication.
  • type: A code identifying the type of the input see /ref HelicsDataTypes for available options.
  • units: A string listing the units of the subscription maybe NULL.
  • err: A pointer to an error object for catching errors.

HELICS_EXPORT HelicsPublication helicsFederateRegisterGlobalTypeInput(HelicsFederate fed, const char * key, const char * type, const char * units, HelicsError * err)

Register a global publication with an arbitrary type.

The publication becomes part of the federate and is destroyed when the federate is freed so there are no separate free functions for subscriptions and publications.

Return
An object containing the publication.
Parameters
  • fed: The federate object in which to create a publication.
  • key: The identifier for the publication.
  • type: A string defining the type of the input.
  • units: A string listing the units of the subscription maybe NULL.
  • err: A pointer to an error object for catching errors.

HELICS_EXPORT HelicsPublication helicsFederateGetPublication(HelicsFederate fed, const char * key, HelicsError * err)

Get a publication object from a key.

Return
A HelicsPublication object, the object will not be valid and err will contain an error code if no publication with the specified key exists.
Parameters
  • fed: The value federate object to use to get the publication.
  • key: The name of the publication.
  • err: The error object to complete if there is an error.

HELICS_EXPORT HelicsPublication helicsFederateGetPublicationByIndex(HelicsFederate fed, int index, HelicsError * err)

Get a publication by its index, typically already created via registerInterfaces file or something of that nature.

Return
A HelicsPublication.
Parameters
  • fed: The federate object in which to create a publication.
  • index: The index of the publication to get.
  • err: A pointer to an error object for catching errors.

HELICS_EXPORT HelicsInput helicsFederateGetInput(HelicsFederate fed, const char * key, HelicsError * err)

Get an input object from a key.

Return
A HelicsInput object, the object will not be valid and err will contain an error code if no input with the specified key exists.
Parameters
  • fed: The value federate object to use to get the publication.
  • key: The name of the input.
  • err: The error object to complete if there is an error.

HELICS_EXPORT HelicsInput helicsFederateGetInputByIndex(HelicsFederate fed, int index, HelicsError * err)

Get an input by its index, typically already created via registerInterfaces file or something of that nature.

Return
A HelicsInput, which will be NULL if an invalid index.
Parameters
  • fed: The federate object in which to create a publication.
  • index: The index of the publication to get.
  • err: A pointer to an error object for catching errors.

HELICS_EXPORT HelicsInput helicsFederateGetSubscription(HelicsFederate fed, const char * key, HelicsError * err)

Get an input object from a subscription target.

Return
A HelicsInput object, the object will not be valid and err will contain an error code if no input with the specified key exists.
Parameters
  • fed: The value federate object to use to get the publication.
  • key: The name of the publication that a subscription is targeting.
  • err: The error object to complete if there is an error.

HELICS_EXPORT void helicsFederateClearUpdates(HelicsFederate fed)

Clear all the update flags from a federates inputs.

Parameters
  • fed: The value federate object for which to clear update flags.

HELICS_EXPORT void helicsFederateRegisterFromPublicationJSON(HelicsFederate fed, const char * json, HelicsError * err)

Register the publications via JSON publication string.

This would be the same JSON that would be used to publish data.

Parameters
  • fed: The value federate object to use to register the publications.
  • json: The JSON publication string.
  • err: The error object to complete if there is an error.

HELICS_EXPORT void helicsFederatePublishJSON(HelicsFederate fed, const char * json, HelicsError * err)

Publish data contained in a JSON file or string.

Parameters
  • fed: The value federate object through which to publish the data.
  • json: The publication file name or literal JSON data string.
  • err: The error object to complete if there is an error.

HELICS_EXPORT int helicsFederateGetPublicationCount(HelicsFederate fed)

Get the number of publications in a federate.

Return
(-1) if fed was not a valid federate otherwise returns the number of publications.

HELICS_EXPORT int helicsFederateGetInputCount(HelicsFederate fed)

Get the number of subscriptions in a federate.

Return
(-1) if fed was not a valid federate otherwise returns the number of subscriptions.

Publication

HELICS_EXPORT HelicsBool helicsPublicationIsValid(HelicsPublication pub)

Check if a publication is valid.

Return
HELICS_TRUE if the publication is a valid publication.
Parameters
  • pub: The publication to check.

HELICS_EXPORT void helicsPublicationPublishBytes(HelicsPublication pub, const void * data, int inputDataLength, HelicsError * err)

Publish raw data from a char * and length.

Parameters
  • pub: The publication to publish for.
  • data: A pointer to the raw data.
  • inputDataLength: The size in bytes of the data to publish.
  • err: A pointer to an error object for catching errors.

HELICS_EXPORT void helicsPublicationPublishString(HelicsPublication pub, const char * str, HelicsError * err)

Publish a string.

Parameters
  • pub: The publication to publish for.
  • str: The string to publish.
  • err: A pointer to an error object for catching errors.

HELICS_EXPORT void helicsPublicationPublishInteger(HelicsPublication pub, int64_t val, HelicsError * err)

Publish an integer value.

Parameters
  • pub: The publication to publish for.
  • val: The numerical value to publish.
  • err: A pointer to an error object for catching errors.

HELICS_EXPORT void helicsPublicationPublishBoolean(HelicsPublication pub, HelicsBool val, HelicsError * err)

Publish a Boolean Value.

Parameters
  • pub: The publication to publish for.
  • val: The boolean value to publish.
  • err: A pointer to an error object for catching errors.

HELICS_EXPORT void helicsPublicationPublishDouble(HelicsPublication pub, double val, HelicsError * err)

Publish a double floating point value.

Parameters
  • pub: The publication to publish for.
  • val: The numerical value to publish.
  • err: A pointer to an error object for catching errors.

HELICS_EXPORT void helicsPublicationPublishTime(HelicsPublication pub, HelicsTime val, HelicsError * err)

Publish a time value.

Parameters
  • pub: The publication to publish for.
  • val: The numerical value to publish.
  • err: A pointer to an error object for catching errors.

HELICS_EXPORT void helicsPublicationPublishChar(HelicsPublication pub, char val, HelicsError * err)

Publish a single character.

Parameters
  • pub: The publication to publish for.
  • val: The numerical value to publish.
  • err: A pointer to an error object for catching errors.

HELICS_EXPORT void helicsPublicationPublishComplex(HelicsPublication pub, double real, double imag, HelicsError * err)

Publish a complex value (or pair of values).

Parameters
  • pub: The publication to publish for.
  • real: The real part of a complex number to publish.
  • imag: The imaginary part of a complex number to publish.
  • err: A pointer to an error object for catching errors.

HELICS_EXPORT void helicsPublicationPublishVector(HelicsPublication pub, const double * vectorInput, int vectorLength, HelicsError * err)

Publish a vector of doubles.

Parameters
  • pub: The publication to publish for.
  • vectorInput: A pointer to an array of double data.
  • vectorLength: The number of points to publish.
  • err: A pointer to an error object for catching errors.

HELICS_EXPORT void helicsPublicationPublishNamedPoint(HelicsPublication pub, const char * str, double val, HelicsError * err)

Publish a named point.

Parameters
  • pub: The publication to publish for.
  • str: A string for the name to publish.
  • val: A double for the value to publish.
  • err: A pointer to an error object for catching errors.

HELICS_EXPORT void helicsPublicationAddTarget(HelicsPublication pub, const char * target, HelicsError * err)

Add a named input to the list of targets a publication publishes to.

Parameters
  • pub: The publication to add the target for.
  • target: The name of an input that the data should be sent to.
  • err: A pointer to an error object for catching errors.

HELICS_EXPORT const char* helicsPublicationGetType(HelicsPublication pub)

Get the type of a publication.

Return
A void enumeration, HELICS_OK if everything worked.
Parameters
  • pub: The publication to query.

HELICS_EXPORT const char* helicsPublicationGetName(HelicsPublication pub)

Get the name of a publication.

This will be the global key used to identify the publication to the federation.

Return
A const char with the publication name.
Parameters
  • pub: The publication to query.

HELICS_EXPORT const char* helicsPublicationGetUnits(HelicsPublication pub)

Get the units of a publication.

Return
A void enumeration, HELICS_OK if everything worked.
Parameters
  • pub: The publication to query.

HELICS_EXPORT const char* helicsPublicationGetInfo(HelicsPublication pub)

Get the data in the info field of an publication.

Return
A string with the info field string.
Parameters
  • pub: The publication to query.

HELICS_EXPORT void helicsPublicationSetInfo(HelicsPublication pub, const char * info, HelicsError * err)

Set the data in the info field for a publication.

Parameters
  • pub: The publication to set the info field for.
  • info: The string to set.
  • err: An error object to fill out in case of an error.

HELICS_EXPORT const char* helicsPublicationGetTag(HelicsPublication pub, const char * tagname)

Get the data in a specified tag of a publication.

Return
A string with the tag data.
Parameters
  • pub: The publication object to query.
  • tagname: The name of the tag to query.

HELICS_EXPORT void helicsPublicationSetTag(HelicsPublication pub, const char * tagname, const char * tagvalue, HelicsError * err)

Set the data in a specific tag for a publication.

Parameters
  • pub: The publication object to set a tag for.
  • tagname: The name of the tag to set.
  • tagvalue: The string value to associate with a tag.
  • err: An error object to fill out in case of an error.

HELICS_EXPORT int helicsPublicationGetOption(HelicsPublication pub, int option)

Get the value of an option for a publication

Return
A string with the info field string.
Parameters
  • pub: The publication to query.
  • option: The value to query see /ref helics_handle_options.

HELICS_EXPORT void helicsPublicationSetOption(HelicsPublication pub, int option, int val, HelicsError * err)

Set the value of an option for a publication

Parameters
  • pub: The publication to query.
  • option: Integer code for the option to set /ref helics_handle_options.
  • val: The value to set the option to.
  • err: An error object to fill out in case of an error.

HELICS_EXPORT void helicsPublicationSetMinimumChange(HelicsPublication pub, double tolerance, HelicsError * err)

Set the minimum change detection tolerance.

Parameters
  • pub: The publication to modify.
  • tolerance: The tolerance level for publication, values changing less than this value will not be published.
  • err: An error object to fill out in case of an error.

Input

HELICS_EXPORT HelicsBool helicsInputIsValid(HelicsInput ipt)

Check if an input is valid.

Return
HELICS_TRUE if the Input object represents a valid input.
Parameters
  • ipt: The input to check.

HELICS_EXPORT void helicsInputAddTarget(HelicsInput ipt, const char * target, HelicsError * err)

Add a publication to the list of data that an input subscribes to.

Parameters
  • ipt: The named input to modify.
  • target: The name of a publication that an input should subscribe to.
  • err: A pointer to an error object for catching errors.

HELICS_EXPORT int helicsInputGetByteCount(HelicsInput ipt)

Get the size of the raw value for subscription.

Return
The size of the raw data/string in bytes.

HELICS_EXPORT void helicsInputGetBytes(HelicsInput ipt, void * data, int maxDataLength, int * actualSize, HelicsError * err)

Get the raw data for the latest value of a subscription.

Parameters
  • ipt: The input to get the data for.
  • data: The memory location of the data
  • maxDataLength: The maximum size of information that data can hold.
  • actualSize: The actual length of data copied to data.
  • err: A pointer to an error object for catching errors.

HELICS_EXPORT int helicsInputGetStringSize(HelicsInput ipt)

Get the size of a value for subscription assuming return as a string.

Return
The size of the string.

HELICS_EXPORT void helicsInputGetString(HelicsInput ipt, char * outputString, int maxStringLength, int * actualLength, HelicsError * err)

Get a string value from a subscription.

Parameters
  • ipt: The input to get the data for.
  • outputString: Storage for copying a null terminated string.
  • maxStringLength: The maximum size of information that str can hold.
  • actualLength: The actual length of the string.
  • err: Error term for capturing errors.

HELICS_EXPORT int64_t helicsInputGetInteger(HelicsInput ipt, HelicsError * err)

Get an integer value from a subscription.

Return
An int64_t value with the current value of the input.
Parameters
  • ipt: The input to get the data for.
  • err: A pointer to an error object for catching errors.

HELICS_EXPORT HelicsBool helicsInputGetBoolean(HelicsInput ipt, HelicsError * err)

Get a boolean value from a subscription.

Return
A boolean value of current input value.
Parameters
  • ipt: The input to get the data for.
  • err: A pointer to an error object for catching errors.

HELICS_EXPORT double helicsInputGetDouble(HelicsInput ipt, HelicsError * err)

Get a double value from a subscription.

Return
The double value of the input.
Parameters
  • ipt: The input to get the data for.
  • err: A pointer to an error object for catching errors.

HELICS_EXPORT HelicsTime helicsInputGetTime(HelicsInput ipt, HelicsError * err)

Get a time value from a subscription.

Return
The resulting time value.
Parameters
  • ipt: The input to get the data for.
  • err: A pointer to an error object for catching errors.

HELICS_EXPORT char helicsInputGetChar(HelicsInput ipt, HelicsError * err)

Get a single character value from an input.

Return
The resulting character value. NAK (negative acknowledgment) symbol returned on error
Parameters
  • ipt: The input to get the data for.
  • err: A pointer to an error object for catching errors.

HELICS_EXPORT HelicsComplex helicsInputGetComplexObject(HelicsInput ipt, HelicsError * err)

Get a complex object from an input object.

Return
A HelicsComplex structure with the value.
Parameters
  • ipt: The input to get the data for.
  • err: A helics error object, if the object is not empty the function is bypassed otherwise it is filled in if there is an error.

HELICS_EXPORT void helicsInputGetComplex(HelicsInput ipt, double * real, double * imag, HelicsError * err)

Get a pair of double forming a complex number from a subscriptions.

Parameters
  • ipt: The input to get the data for.
  • real: Memory location to place the real part of a value.
  • imag: Memory location to place the imaginary part of a value.
  • err: An error object that will contain an error code and string if any error occurred during the execution of the function. On error the values will not be altered.

HELICS_EXPORT int helicsInputGetVectorSize(HelicsInput ipt)

Get the size of a value for subscription assuming return as an array of doubles.

Return
The number of doubles in a returned vector.

HELICS_EXPORT void helicsInputGetVector(HelicsInput ipt, double data[], int maxLength, int * actualSize, HelicsError * err)

Get a vector from a subscription.

Parameters
  • ipt: The input to get the result for.
  • data: The location to store the data.
  • maxLength: The maximum size of the vector.
  • actualSize: Location to place the actual length of the resulting vector.
  • err: An error object that will contain an error code and string if any error occurred during the execution of the function.

HELICS_EXPORT void helicsInputGetNamedPoint(HelicsInput ipt, char * outputString, int maxStringLength, int * actualLength, double * val, HelicsError * err)

Get a named point from a subscription.

Parameters
  • ipt: The input to get the result for.
  • outputString: Storage for copying a null terminated string.
  • maxStringLength: The maximum size of information that str can hold.
  • actualLength: The actual length of the string
  • val: The double value for the named point.
  • err: An error object that will contain an error code and string if any error occurred during the execution of the function.

HELICS_EXPORT void helicsInputSetDefaultBytes(HelicsInput ipt, const void * data, int inputDataLength, HelicsError * err)

Set the default as a raw data array.

Parameters
  • ipt: The input to set the default for.
  • data: A pointer to the raw data to use for the default.
  • inputDataLength: The size of the raw data.
  • err: An error object that will contain an error code and string if any error occurred during the execution of the function.

HELICS_EXPORT void helicsInputSetDefaultString(HelicsInput ipt, const char * str, HelicsError * err)

Set the default as a string.

Parameters
  • ipt: The input to set the default for.
  • str: A pointer to the default string.
  • err: An error object that will contain an error code and string if any error occurred during the execution of the function.

HELICS_EXPORT void helicsInputSetDefaultInteger(HelicsInput ipt, int64_t val, HelicsError * err)

Set the default as an integer.

Parameters
  • ipt: The input to set the default for.
  • val: The default integer.
  • err: An error object that will contain an error code and string if any error occurred during the execution of the function.

HELICS_EXPORT void helicsInputSetDefaultBoolean(HelicsInput ipt, HelicsBool val, HelicsError * err)

Set the default as a boolean.

Parameters
  • ipt: The input to set the default for.
  • val: The default boolean value.
  • err: An error object that will contain an error code and string if any error occurred during the execution of the function.

HELICS_EXPORT void helicsInputSetDefaultTime(HelicsInput ipt, HelicsTime val, HelicsError * err)

Set the default as a time.

Parameters
  • ipt: The input to set the default for.
  • val: The default time value.
  • err: An error object that will contain an error code and string if any error occurred during the execution of the function.

HELICS_EXPORT void helicsInputSetDefaultChar(HelicsInput ipt, char val, HelicsError * err)

Set the default as a char.

Parameters
  • ipt: The input to set the default for.
  • val: The default char value.
  • err: An error object that will contain an error code and string if any error occurred during the execution of the function.

HELICS_EXPORT void helicsInputSetDefaultDouble(HelicsInput ipt, double val, HelicsError * err)

Set the default as a double.

Parameters
  • ipt: The input to set the default for.
  • val: The default double value.
  • err: An error object that will contain an error code and string if any error occurred during the execution of the function.

HELICS_EXPORT void helicsInputSetDefaultComplex(HelicsInput ipt, double real, double imag, HelicsError * err)

Set the default as a complex number.

Parameters
  • ipt: The input to set the default for.
  • real: The default real value.
  • imag: The default imaginary value.
  • err: An error object that will contain an error code and string if any error occurred during the execution of the function.

HELICS_EXPORT void helicsInputSetDefaultVector(HelicsInput ipt, const double * vectorInput, int vectorLength, HelicsError * err)

Set the default as a vector of doubles.

Parameters
  • ipt: The input to set the default for.
  • vectorInput: A pointer to an array of double data.
  • vectorLength: The number of points to publish.
  • err: An error object that will contain an error code and string if any error occurred during the execution of the function.

HELICS_EXPORT void helicsInputSetDefaultNamedPoint(HelicsInput ipt, const char * str, double val, HelicsError * err)

Set the default as a NamedPoint.

Parameters
  • ipt: The input to set the default for.
  • str: A pointer to a string representing the name.
  • val: A double value for the value of the named point.
  • err: An error object that will contain an error code and string if any error occurred during the execution of the function.

HELICS_EXPORT const char* helicsInputGetType(HelicsInput ipt)

Get the type of an input.

Return
A void enumeration, HELICS_OK if everything worked.
Parameters
  • ipt: The input to query.

HELICS_EXPORT const char* helicsInputGetPublicationType(HelicsInput ipt)

Get the type the publisher to an input is sending.

Return
A const char * with the type name.
Parameters
  • ipt: The input to query.

HELICS_EXPORT const char* helicsInputGetName(HelicsInput ipt)

Get the key of an input.

Return
A const char with the input name.
Parameters
  • ipt: The input to query.

HELICS_EXPORT const char* helicsSubscriptionGetTarget(HelicsInput ipt)

Get the target of a subscription.

Return
A const char with the subscription target.

HELICS_EXPORT const char* helicsInputGetUnits(HelicsInput ipt)

Get the units of an input.

Return
A void enumeration, HELICS_OK if everything worked.
Parameters
  • ipt: The input to query.

HELICS_EXPORT const char* helicsInputGetInjectionUnits(HelicsInput ipt)

Get the units of the publication that an input is linked to.

Return
A void enumeration, HELICS_OK if everything worked.
Parameters
  • ipt: The input to query.

HELICS_EXPORT const char* helicsInputGetExtractionUnits(HelicsInput ipt)

Get the units of an input.

The same as helicsInputGetUnits.

Return
A void enumeration, HELICS_OK if everything worked.
Parameters
  • ipt: The input to query.

HELICS_EXPORT const char* helicsInputGetInfo(HelicsInput inp)

Get the data in the info field of an input.

Return
A string with the info field string.
Parameters
  • inp: The input to query.

HELICS_EXPORT void helicsInputSetInfo(HelicsInput inp, const char * info, HelicsError * err)

Set the data in the info field for an input.

Parameters
  • inp: The input to query.
  • info: The string to set.
  • err: An error object to fill out in case of an error.

HELICS_EXPORT const char* helicsInputGetTag(HelicsInput inp, const char * tagname)

Get the data in a specified tag of an input.

Return
A string with the tag data.
Parameters
  • inp: The input object to query.
  • tagname: The name of the tag to get the value for.

HELICS_EXPORT void helicsInputSetTag(HelicsInput inp, const char * tagname, const char * tagvalue, HelicsError * err)

Set the data in a specific tag for an input.

Parameters
  • inp: The input object to query.
  • tagname: The string to set.
  • tagvalue: The string value to associate with a tag.
  • err: An error object to fill out in case of an error.

HELICS_EXPORT int helicsInputGetOption(HelicsInput inp, int option)

Get the current value of an input handle option

Return
An integer value with the current value of the given option.
Parameters
  • inp: The input to query.
  • option: Integer representation of the option in question see /ref helics_handle_options.

HELICS_EXPORT void helicsInputSetOption(HelicsInput inp, int option, int value, HelicsError * err)

Set an option on an input

Parameters
  • inp: The input to query.
  • option: The option to set for the input /ref helics_handle_options.
  • value: The value to set the option to.
  • err: An error object to fill out in case of an error.

HELICS_EXPORT void helicsInputSetMinimumChange(HelicsInput inp, double tolerance, HelicsError * err)

Set the minimum change detection tolerance.

Parameters
  • inp: The input to modify.
  • tolerance: The tolerance level for registering an update, values changing less than this value will not show as being updated.
  • err: An error object to fill out in case of an error.

HELICS_EXPORT HelicsBool helicsInputIsUpdated(HelicsInput ipt)

Check if a particular subscription was updated.

Return
HELICS_TRUE if it has been updated since the last value retrieval.

HELICS_EXPORT HelicsTime helicsInputLastUpdateTime(HelicsInput ipt)

Get the last time a subscription was updated.

HELICS_EXPORT void helicsInputClearUpdate(HelicsInput ipt)

Clear the updated flag from an input.

MessageFederate

HELICS_EXPORT HelicsEndpoint helicsFederateRegisterEndpoint(HelicsFederate fed, const char * name, const char * type, HelicsError * err)

Create an endpoint.

The endpoint becomes part of the federate and is destroyed when the federate is freed so there are no separate free functions for endpoints.

Return
An object containing the endpoint.
    nullptr on failure.
Parameters
  • fed: The federate object in which to create an endpoint must have been created with helicsCreateMessageFederate or helicsCreateCombinationFederate.
  • name: The identifier for the endpoint. This will be prepended with the federate name for the global identifier.
  • type: A string describing the expected type of the publication (may be NULL).
  • err: A pointer to an error object for catching errors.

HELICS_EXPORT HelicsEndpoint helicsFederateRegisterGlobalEndpoint(HelicsFederate fed, const char * name, const char * type, HelicsError * err)

Create an endpoint.

The endpoint becomes part of the federate and is destroyed when the federate is freed so there are no separate free functions for endpoints.

Return
An object containing the endpoint.
    nullptr on failure.
Parameters
  • fed: The federate object in which to create an endpoint must have been created with helicsCreateMessageFederate or helicsCreateCombinationFederate.
  • name: The identifier for the endpoint, the given name is the global identifier.
  • type: A string describing the expected type of the publication (may be NULL).
  • err: A pointer to an error object for catching errors.

HELICS_EXPORT HelicsEndpoint helicsFederateRegisterTargetedEndpoint(HelicsFederate fed, const char * name, const char * type, HelicsError * err)

Create a targeted endpoint. Targeted endpoints have specific destinations predefined and do not allow sending messages to other endpoints

The endpoint becomes part of the federate and is destroyed when the federate is freed so there are no separate free functions for endpoints.

Return
An object containing the endpoint.
    nullptr on failure.
Parameters
  • fed: The federate object in which to create an endpoint must have been created with helicsCreateMessageFederate or helicsCreateCombinationFederate.
  • name: The identifier for the endpoint. This will be prepended with the federate name for the global identifier.
  • type: A string describing the expected type of the publication (may be NULL).
  • err: A pointer to an error object for catching errors.

HELICS_EXPORT HelicsEndpoint helicsFederateRegisterGlobalTargetedEndpoint(HelicsFederate fed, const char * name, const char * type, HelicsError * err)

Create a global targeted endpoint, Targeted endpoints have specific destinations predefined and do not allow sending messages to other endpoints

The endpoint becomes part of the federate and is destroyed when the federate is freed so there are no separate free functions for endpoints.

Return
An object containing the endpoint.
    nullptr on failure.
Parameters
  • fed: The federate object in which to create an endpoint must have been created with helicsCreateMessageFederate or helicsCreateCombinationFederate.
  • name: The identifier for the endpoint, the given name is the global identifier.
  • type: A string describing the expected type of the publication (may be NULL).
  • err: A pointer to an error object for catching errors.

HELICS_EXPORT HelicsEndpoint helicsFederateGetEndpoint(HelicsFederate fed, const char * name, HelicsError * err)

Get an endpoint object from a name.

Return
A HelicsEndpoint object.
    The object will not be valid and err will contain an error code if no endpoint with the specified name exists.
Parameters
  • fed: The message federate object to use to get the endpoint.
  • name: The name of the endpoint.
  • err: The error object to complete if there is an error.

HELICS_EXPORT HelicsEndpoint helicsFederateGetEndpointByIndex(HelicsFederate fed, int index, HelicsError * err)

Get an endpoint by its index, typically already created via registerInterfaces file or something of that nature.

Return
A HelicsEndpoint.
    It will be NULL if given an invalid index.
Parameters
  • fed: The federate object in which to create a publication.
  • index: The index of the publication to get.
  • err: A pointer to an error object for catching errors.

HELICS_EXPORT HelicsBool helicsFederateHasMessage(HelicsFederate fed)

Check if the federate has any outstanding messages.

Return
HELICS_TRUE if the federate has a message waiting, HELICS_FALSE otherwise.
Parameters
  • fed: The federate to check.

HELICS_EXPORT int helicsFederatePendingMessageCount(HelicsFederate fed)

Returns the number of pending receives for the specified destination endpoint.

Parameters
  • fed: The federate to get the number of waiting messages from.

HELICS_EXPORT HelicsMessage helicsFederateGetMessage(HelicsFederate fed)

Receive a communication message for any endpoint in the federate.

The return order will be in order of endpoint creation. So all messages that are available for the first endpoint, then all for the second, and so on. Within a single endpoint, the messages are ordered by time, then source_id, then order of arrival.

Return
A HelicsMessage which references the data in the message.

HELICS_EXPORT HelicsMessage helicsFederateCreateMessage(HelicsFederate fed, HelicsError * err)

Create a new empty message object.

The message is empty and isValid will return false since there is no data associated with the message yet.

Return
A HelicsMessage containing the message data.
Parameters
  • fed: the federate object to associate the message with
  • err: An error object to fill out in case of an error.

HELICS_EXPORT void helicsFederateClearMessages(HelicsFederate fed)

Clear all stored messages from a federate.

This clears messages retrieved through helicsEndpointGetMessage or helicsFederateGetMessage

Parameters
  • fed: The federate to clear the message for.

HELICS_EXPORT int helicsFederateGetEndpointCount(HelicsFederate fed)

Get the number of endpoints in a federate.

Return
(-1) if fed was not a valid federate, otherwise returns the number of endpoints.
Parameters
  • fed: The message federate to query.

Endpoint

HELICS_EXPORT HelicsBool helicsEndpointIsValid(HelicsEndpoint endpoint)

Check if an endpoint is valid.

Return
HELICS_TRUE if the Endpoint object represents a valid endpoint.
Parameters
  • endpoint: The endpoint object to check.

HELICS_EXPORT void helicsEndpointSetDefaultDestination(HelicsEndpoint endpoint, const char * dst, HelicsError * err)

Set the default destination for an endpoint if no other endpoint is given.

Parameters
  • endpoint: The endpoint to set the destination for.
  • dst: A string naming the desired default endpoint.
  • err: A pointer to an error object for catching errors.

HELICS_EXPORT const char* helicsEndpointGetDefaultDestination(HelicsEndpoint endpoint)

Get the default destination for an endpoint.

Return
A string with the default destination.
Parameters
  • endpoint: The endpoint to set the destination for.

HELICS_EXPORT void helicsEndpointSendBytes(HelicsEndpoint endpoint, const void * data, int inputDataLength, HelicsError * err)

Send a message to the targeted destination.

Parameters
  • endpoint: The endpoint to send the data from.
  • data: The data to send.
  • inputDataLength: The length of the data to send.
  • err: A pointer to an error object for catching errors.

HELICS_EXPORT void helicsEndpointSendBytesTo(HelicsEndpoint endpoint, const void * data, int inputDataLength, const char * dst, HelicsError * err)

Send a message to the specified destination.

Parameters
  • endpoint: The endpoint to send the data from.
  • data: The data to send.
  • inputDataLength: The length of the data to send.
  • dst: The target destination.
            nullptr to use the default destination.
    
  • err: A pointer to an error object for catching errors.

HELICS_EXPORT void helicsEndpointSendBytesToAt(HelicsEndpoint endpoint, const void * data, int inputDataLength, const char * dst, HelicsTime time, HelicsError * err)

Send a message to the specified destination at a specific time.

Parameters
  • endpoint: The endpoint to send the data from.
  • data: The data to send.
  • inputDataLength: The length of the data to send.
  • dst: The target destination.
            nullptr to use the default destination.
    
  • time: The time the message should be sent.
  • err: A pointer to an error object for catching errors.

HELICS_EXPORT void helicsEndpointSendBytesAt(HelicsEndpoint endpoint, const void * data, int inputDataLength, HelicsTime time, HelicsError * err)

Send a message at a specific time to the targeted destinations

Parameters
  • endpoint: The endpoint to send the data from.
  • data: The data to send.
  • inputDataLength: The length of the data to send.
  • time: The time the message should be sent.
  • err: A pointer to an error object for catching errors.

HELICS_EXPORT void helicsEndpointSendMessage(HelicsEndpoint endpoint, HelicsMessage message, HelicsError * err)

Send a message object from a specific endpoint.

Parameters
  • endpoint: The endpoint to send the data from.
  • message: The actual message to send which will be copied.
  • err: A pointer to an error object for catching errors.

HELICS_EXPORT void helicsEndpointSendMessageZeroCopy(HelicsEndpoint endpoint, HelicsMessage message, HelicsError * err)

Send a message object from a specific endpoint, the message will not be copied and the message object will no longer be valid after the call.

Parameters
  • endpoint: The endpoint to send the data from.
  • message: The actual message to send which will be copied.
  • err: A pointer to an error object for catching errors.

HELICS_EXPORT void helicsEndpointSubscribe(HelicsEndpoint endpoint, const char * key, HelicsError * err)

Subscribe an endpoint to a publication.

Parameters
  • endpoint: The endpoint to use.
  • key: The name of the publication.
  • err: A pointer to an error object for catching errors.

HELICS_EXPORT HelicsBool helicsEndpointHasMessage(HelicsEndpoint endpoint)

Check if a given endpoint has any unread messages.

Return
HELICS_TRUE if the endpoint has a message, HELICS_FALSE otherwise.
Parameters
  • endpoint: The endpoint to check.

HELICS_EXPORT int helicsEndpointPendingMessageCount(HelicsEndpoint endpoint)

Returns the number of pending receives for all endpoints of a particular federate.

Parameters
  • endpoint: The endpoint to query.

HELICS_EXPORT HelicsMessage helicsEndpointGetMessage(HelicsEndpoint endpoint)

Receive a packet from a particular endpoint.

Return
A message object.
Parameters
  • endpoint: The identifier for the endpoint.

HELICS_EXPORT HelicsMessage helicsEndpointCreateMessage(HelicsEndpoint endpoint, HelicsError * err)

Create a new empty message object.

The message is empty and isValid will return false since there is no data associated with the message yet.

Return
A new HelicsMessage.
Parameters
  • endpoint: The endpoint object to associate the message with.
  • err: An error object to fill out in case of an error.

HELICS_EXPORT const char* helicsEndpointGetType(HelicsEndpoint endpoint)

Get the type specified for an endpoint.

Return
The defined type of the endpoint.
Parameters
  • endpoint: The endpoint object in question.

HELICS_EXPORT const char* helicsEndpointGetName(HelicsEndpoint endpoint)

Get the name of an endpoint.

Return
The name of the endpoint.
Parameters
  • endpoint: The endpoint object in question.

HELICS_EXPORT const char* helicsEndpointGetInfo(HelicsEndpoint end)

Get the local information field of an endpoint.

Return
A string with the info field string.
Parameters
  • end: The endpoint to query.

HELICS_EXPORT void helicsEndpointSetInfo(HelicsEndpoint endpoint, const char * info, HelicsError * err)

Set the data in the interface information field for an endpoint.

Parameters
  • endpoint: The endpoint to set the information for
  • info: The string to store in the field
  • err: An error object to fill out in case of an error.

HELICS_EXPORT const char* helicsEndpointGetTag(HelicsEndpoint endpoint, const char * tagname)

Get the data in a specified tag of an endpoint

Return
A string with the tag data.
Parameters
  • endpoint: The endpoint to query.
  • tagname: The name of the tag to query.

HELICS_EXPORT void helicsEndpointSetTag(HelicsEndpoint endpoint, const char * tagname, const char * tagvalue, HelicsError * err)

Set the data in a specific tag for an endpoint.

Parameters
  • endpoint: The endpoint to query.
  • tagname: The string to set.
  • tagvalue: The string value to associate with a tag.
  • err: An error object to fill out in case of an error.

HELICS_EXPORT void helicsEndpointSetOption(HelicsEndpoint endpoint, int option, int value, HelicsError * err)

Set a handle option on an endpoint.

Parameters
  • endpoint: The endpoint to modify.
  • option: Integer code for the option to set /ref helics_handle_options.
  • value: The value to set the option to.
  • err: An error object to fill out in case of an error.

HELICS_EXPORT int helicsEndpointGetOption(HelicsEndpoint endpoint, int option)

Set a handle option on an endpoint.

Return
the value of the option, for boolean options will be 0 or 1
Parameters
  • endpoint: The endpoint to modify.
  • option: Integer code for the option to set /ref helics_handle_options.

HELICS_EXPORT void helicsEndpointAddSourceTarget(HelicsEndpoint endpoint, const char * targetEndpoint, HelicsError * err)

add a source target to an endpoint, Specifying an endpoint to receive undirected messages from

Parameters
  • endpoint: The endpoint to modify.
  • targetEndpoint: the endpoint to get messages from
  • err: An error object to fill out in case of an error.

HELICS_EXPORT void helicsEndpointAddDestinationTarget(HelicsEndpoint endpoint, const char * targetEndpoint, HelicsError * err)

add a destination target to an endpoint, Specifying an endpoint to send undirected messages to

Parameters
  • endpoint: The endpoint to modify.
  • targetEndpoint: the name of the endpoint to send messages to
  • err: An error object to fill out in case of an error.

HELICS_EXPORT void helicsEndpointRemoveTarget(HelicsEndpoint endpoint, const char * targetEndpoint, HelicsError * err)

remove an endpoint from being targeted

Parameters
  • endpoint: The endpoint to modify.
  • targetEndpoint: the name of the endpoint to send messages to
  • err: An error object to fill out in case of an error.

HELICS_EXPORT void helicsEndpointAddSourceFilter(HelicsEndpoint endpoint, const char * filterName, HelicsError * err)

add a source Filter to an endpoint

Parameters
  • endpoint: The endpoint to modify.
  • filterName: the name of the filter to add
  • err: An error object to fill out in case of an error.

HELICS_EXPORT void helicsEndpointAddDestinationFilter(HelicsEndpoint endpoint, const char * filterName, HelicsError * err)

add a destination filter to an endpoint

Parameters
  • endpoint: The endpoint to modify.
  • filterName: The name of the filter to add.
  • err: An error object to fill out in case of an error.

Message

HELICS_EXPORT const char* helicsMessageGetSource(HelicsMessage message)

Get the source endpoint of a message.

Return
A string with the source endpoint.
Parameters
  • message: The message object in question.

HELICS_EXPORT const char* helicsMessageGetDestination(HelicsMessage message)

Get the destination endpoint of a message.

Return
A string with the destination endpoint.
Parameters
  • message: The message object in question.

HELICS_EXPORT const char* helicsMessageGetOriginalSource(HelicsMessage message)

Get the original source endpoint of a message, the source may have been modified by filters or other actions.

Return
A string with the source of a message.
Parameters
  • message: The message object in question.

HELICS_EXPORT const char* helicsMessageGetOriginalDestination(HelicsMessage message)

Get the original destination endpoint of a message, the destination may have been modified by filters or other actions.

Return
A string with the original destination of a message.
Parameters
  • message: The message object in question.

HELICS_EXPORT HelicsTime helicsMessageGetTime(HelicsMessage message)

Get the helics time associated with a message.

Return
The time associated with a message.
Parameters
  • message: The message object in question.

HELICS_EXPORT const char* helicsMessageGetString(HelicsMessage message)

Get the payload of a message as a string.

Return
A string representing the payload of a message.
Parameters
  • message: The message object in question.

HELICS_EXPORT int helicsMessageGetMessageID(HelicsMessage message)

Get the messageID of a message.

Return
The messageID.
Parameters
  • message: The message object in question.

HELICS_EXPORT HelicsBool helicsMessageGetFlagOption(HelicsMessage message, int flag)

Check if a flag is set on a message.

Return
The flags associated with a message.
Parameters
  • message: The message object in question.
  • flag: The flag to check should be between [0,15].

HELICS_EXPORT int helicsMessageGetByteCount(HelicsMessage message)

Get the size of the data payload in bytes.

Return
The size of the data payload.
Parameters
  • message: The message object in question.

HELICS_EXPORT void helicsMessageGetBytes(HelicsMessage message, void * data, int maxMessageLength, int * actualSize, HelicsError * err)

Get the raw data for a message object.

Parameters
  • message: A message object to get the data for.
  • data: The memory location of the data.
  • maxMessageLength: The maximum size of information that data can hold.
  • actualSize: The actual length of data copied to data.
  • err: A pointer to an error object for catching errors.

HELICS_EXPORT HelicsBool helicsMessageIsValid(HelicsMessage message)

A check if the message contains a valid payload.

Return
HELICS_TRUE if the message contains a payload.
Parameters
  • message: The message object in question.

HELICS_EXPORT void helicsMessageSetSource(HelicsMessage message, const char * src, HelicsError * err)

Set the source of a message.

Parameters
  • message: The message object in question.
  • src: A string containing the source.
  • err: An error object to fill out in case of an error.

HELICS_EXPORT void helicsMessageSetDestination(HelicsMessage message, const char * dst, HelicsError * err)

Set the destination of a message.

Parameters
  • message: The message object in question.
  • dst: A string containing the new destination.
  • err: An error object to fill out in case of an error.

HELICS_EXPORT void helicsMessageSetOriginalSource(HelicsMessage message, const char * src, HelicsError * err)

Set the original source of a message.

Parameters
  • message: The message object in question.
  • src: A string containing the new original source.
  • err: An error object to fill out in case of an error.

HELICS_EXPORT void helicsMessageSetOriginalDestination(HelicsMessage message, const char * dst, HelicsError * err)

Set the original destination of a message.

Parameters
  • message: The message object in question.
  • dst: A string containing the new original source.
  • err: An error object to fill out in case of an error.

HELICS_EXPORT void helicsMessageSetTime(HelicsMessage message, HelicsTime time, HelicsError * err)

Set the delivery time for a message.

Parameters
  • message: The message object in question.
  • time: The time the message should be delivered.
  • err: An error object to fill out in case of an error.

HELICS_EXPORT void helicsMessageResize(HelicsMessage message, int newSize, HelicsError * err)

Resize the data buffer for a message.

The message data buffer will be resized. There are no guarantees on what is in the buffer in newly allocated space. If the allocated space is not sufficient new allocations will occur.

Parameters
  • message: The message object in question.
  • newSize: The new size in bytes of the buffer.
  • err: An error object to fill out in case of an error.

HELICS_EXPORT void helicsMessageReserve(HelicsMessage message, int reserveSize, HelicsError * err)

Reserve space in a buffer but don’t actually resize.

The message data buffer will be reserved but not resized.

Parameters
  • message: The message object in question.
  • reserveSize: The number of bytes to reserve in the message object.
  • err: An error object to fill out in case of an error.

HELICS_EXPORT void helicsMessageSetMessageID(HelicsMessage message, int32_t messageID, HelicsError * err)

Set the message ID for the message.

Normally this is not needed and the core of HELICS will adjust as needed.

Parameters
  • message: The message object in question.
  • messageID: A new message ID.
  • err: An error object to fill out in case of an error.

HELICS_EXPORT void helicsMessageClearFlags(HelicsMessage message)

Clear the flags of a message.

Parameters
  • message: The message object in question

HELICS_EXPORT void helicsMessageSetFlagOption(HelicsMessage message, int flag, HelicsBool flagValue, HelicsError * err)

Set a flag on a message.

Parameters
  • message: The message object in question.
  • flag: An index of a flag to set on the message.
  • flagValue: The desired value of the flag.
  • err: An error object to fill out in case of an error.

HELICS_EXPORT void helicsMessageSetString(HelicsMessage message, const char * str, HelicsError * err)

Set the data payload of a message as a string.

Parameters
  • message: The message object in question.
  • str: A string containing the message data.
  • err: An error object to fill out in case of an error.

HELICS_EXPORT void helicsMessageSetData(HelicsMessage message, const void * data, int inputDataLength, HelicsError * err)

Set the data payload of a message as raw data.

Parameters
  • message: The message object in question.
  • data: A string containing the message data.
  • inputDataLength: The length of the data to input.
  • err: An error object to fill out in case of an error.

HELICS_EXPORT void helicsMessageAppendData(HelicsMessage message, const void * data, int inputDataLength, HelicsError * err)

Append data to the payload.

Parameters
  • message: The message object in question.
  • data: A string containing the message data to append.
  • inputDataLength: The length of the data to input.
  • err: An error object to fill out in case of an error.

HELICS_EXPORT void helicsMessageCopy(HelicsMessage src_message, HelicsMessage dst_message, HelicsError * err)

Copy a message object.

Parameters
  • src_message: The message object to copy from.
  • dst_message: The message object to copy to.
  • err: An error object to fill out in case of an error.

HELICS_EXPORT HelicsMessage helicsMessageClone(HelicsMessage message, HelicsError * err)

Clone a message object.

Parameters
  • message: The message object to copy from.
  • err: An error object to fill out in case of an error.

HELICS_EXPORT void helicsMessageFree(HelicsMessage message)

Free a message object from memory

memory for message is managed so not using this function does not create memory leaks, this is an indication to the system that the memory for this message is done being used and can be reused for a new message.

helicsFederateClearMessages() can also be used to clear up all stored messages at once
Parameters
  • message: The message object to copy from.

HELICS_EXPORT void helicsMessageClear(HelicsMessage message, HelicsError * err)

Reset a message to empty state

The message after this function will be empty, with no source or destination

Parameters
  • message: The message object to copy from.

Parameters
  • err: An error object to fill out in case of an error.

FilterFederate

HELICS_EXPORT HelicsFilter helicsFederateRegisterFilter(HelicsFederate fed, HelicsFilterTypes type, const char * name, HelicsError * err)

Create a source Filter on the specified federate.

Filters can be created through a federate or a core, linking through a federate allows a few extra features of name matching to function on the federate interface but otherwise equivalent behavior

Return
A HelicsFilter object.
Parameters
  • fed: The federate to register through.
  • type: The type of filter to create /ref HelicsFilterTypes.
  • name: The name of the filter (can be NULL).
  • err: A pointer to an error object for catching errors.

HELICS_EXPORT HelicsFilter helicsFederateRegisterGlobalFilter(HelicsFederate fed, HelicsFilterTypes type, const char * name, HelicsError * err)

Create a global source filter through a federate.

Filters can be created through a federate or a core, linking through a federate allows a few extra features of name matching to function on the federate interface but otherwise equivalent behavior.

Return
A HelicsFilter object.
Parameters
  • fed: The federate to register through.
  • type: The type of filter to create /ref HelicsFilterTypes.
  • name: The name of the filter (can be NULL).
  • err: A pointer to an error object for catching errors.

HELICS_EXPORT HelicsFilter helicsFederateRegisterCloningFilter(HelicsFederate fed, const char * name, HelicsError * err)

Create a cloning Filter on the specified federate.

Cloning filters copy a message and send it to multiple locations, source and destination can be added through other functions.

Return
A HelicsFilter object.
Parameters
  • fed: The federate to register through.
  • name: The name of the filter (can be NULL).
  • err: A pointer to an error object for catching errors.

HELICS_EXPORT HelicsFilter helicsFederateRegisterGlobalCloningFilter(HelicsFederate fed, const char * name, HelicsError * err)

Create a global cloning Filter on the specified federate.

Cloning filters copy a message and send it to multiple locations, source and destination can be added through other functions.

Return
A HelicsFilter object.
Parameters
  • fed: The federate to register through.
  • name: The name of the filter (can be NULL).
  • err: A pointer to an error object for catching errors.

HELICS_EXPORT int helicsFederateGetFilterCount(HelicsFederate fed)

Get the number of filters registered through a federate.

Return
A count of the number of filters registered through a federate.
Parameters
  • fed: The federate object to use to get the filter.

HELICS_EXPORT HelicsFilter helicsFederateGetFilter(HelicsFederate fed, const char * name, HelicsError * err)

Get a filter by its name, typically already created via registerInterfaces file or something of that nature.

Return
A HelicsFilter object, the object will not be valid and err will contain an error code if no filter with the specified name exists.
Parameters
  • fed: The federate object to use to get the filter.
  • name: The name of the filter.
  • err: The error object to complete if there is an error.

HELICS_EXPORT HelicsFilter helicsFederateGetFilterByIndex(HelicsFederate fed, int index, HelicsError * err)

Get a filter by its index, typically already created via registerInterfaces file or something of that nature.

Return
A HelicsFilter, which will be NULL if an invalid index is given.
Parameters
  • fed: The federate object in which to create a publication.
  • index: The index of the publication to get.
  • err: A pointer to an error object for catching errors.

Filter

HELICS_EXPORT void helicsFilterSetCustomCallback(HelicsFilter filter, void(*filtCall)( HelicsMessage message, void *userData), void * userdata, HelicsError * err)

Set a general callback for a custom filter.

Add a custom filter callback for creating a custom filter operation in the C shared library.

Parameters
  • filter: The filter object to set the callback for.
  • filtCall: A callback with signature helics_message_object(helics_message_object, void *); The function arguments are the message to filter and a pointer to user data. The filter should return a new message.
  • userdata: A pointer to user data that is passed to the function when executing.
  • err: A pointer to an error object for catching errors.

HELICS_EXPORT HelicsBool helicsFilterIsValid(HelicsFilter filt)

Check if a filter is valid.

Return
HELICS_TRUE if the Filter object represents a valid filter.
Parameters
  • filt: The filter object to check.

HELICS_EXPORT const char* helicsFilterGetName(HelicsFilter filt)

Get the name of the filter and store in the given string.

get the name of the filter

Return
A string with the name of the filter.
Parameters
  • filt: The given filter.

HELICS_EXPORT void helicsFilterSet(HelicsFilter filt, const char * prop, double val, HelicsError * err)

Set a property on a filter.

Parameters
  • filt: The filter to modify.
  • prop: A string containing the property to set.
  • val: A numerical value for the property.
  • err: A pointer to an error object for catching errors.

HELICS_EXPORT void helicsFilterSetString(HelicsFilter filt, const char * prop, const char * val, HelicsError * err)

Set a string property on a filter.

Parameters
  • filt: The filter to modify.
  • prop: A string containing the property to set.
  • val: A string containing the new value.
  • err: A pointer to an error object for catching errors.

HELICS_EXPORT void helicsFilterAddDestinationTarget(HelicsFilter filt, const char * dst, HelicsError * err)

Add a destination target to a filter.

All messages going to a destination are copied to the delivery address(es).

Parameters
  • filt: The given filter to add a destination target to.
  • dst: The name of the endpoint to add as a destination target.
  • err: A pointer to an error object for catching errors.

HELICS_EXPORT void helicsFilterAddSourceTarget(HelicsFilter filt, const char * source, HelicsError * err)

Add a source target to a filter.

All messages coming from a source are copied to the delivery address(es).

Parameters
  • filt: The given filter.
  • source: The name of the endpoint to add as a source target.
  • err: A pointer to an error object for catching errors.

HELICS_EXPORT void helicsFilterAddDeliveryEndpoint(HelicsFilter filt, const char * deliveryEndpoint, HelicsError * err)

Add a delivery endpoint to a cloning filter.

All cloned messages are sent to the delivery address(es).

Parameters
  • filt: The given filter.
  • deliveryEndpoint: The name of the endpoint to deliver messages to.
  • err: A pointer to an error object for catching errors.

HELICS_EXPORT void helicsFilterRemoveTarget(HelicsFilter filt, const char * target, HelicsError * err)

Remove a destination target from a filter.

Parameters
  • filt: The given filter.
  • target: The named endpoint to remove as a target.
  • err: A pointer to an error object for catching errors.

HELICS_EXPORT void helicsFilterRemoveDeliveryEndpoint(HelicsFilter filt, const char * deliveryEndpoint, HelicsError * err)

Remove a delivery destination from a cloning filter.

Parameters
  • filt: The given filter (must be a cloning filter).
  • deliveryEndpoint: A string with the delivery endpoint to remove.
  • err: A pointer to an error object for catching errors.

HELICS_EXPORT const char* helicsFilterGetInfo(HelicsFilter filt)

Get the data in the info field of a filter.

Return
A string with the info field string.
Parameters
  • filt: The given filter.

HELICS_EXPORT void helicsFilterSetInfo(HelicsFilter filt, const char * info, HelicsError * err)

Set the data in the info field for a filter.

Parameters
  • filt: The given filter.
  • info: The string to set.
  • err: An error object to fill out in case of an error.

HELICS_EXPORT const char* helicsFilterGetTag(HelicsFilter filt, const char * tagname)

Get the data in a specified tag of a filter.

Return
A string with the tag data.
Parameters
  • filt: The filter to query.
  • tagname: The name of the tag to query.

HELICS_EXPORT void helicsFilterSetTag(HelicsFilter filt, const char * tagname, const char * tagvalue, HelicsError * err)

Set the data in a specific tag for a filter.

Parameters
  • filt: The filter object to set the tag for.
  • tagname: The string to set.
  • tagvalue: the string value to associate with a tag.
  • err: An error object to fill out in case of an error.

HELICS_EXPORT void helicsFilterSetOption(HelicsFilter filt, int option, int value, HelicsError * err)

Set an option value for a filter.

Parameters
  • filt: The given filter.
  • option: The option to set /ref helics_handle_options.
  • value: The value of the option commonly 0 for false 1 for true.
  • err: An error object to fill out in case of an error.

HELICS_EXPORT int helicsFilterGetOption(HelicsFilter filt, int option)

Get a handle option for the filter.

Parameters
  • filt: The given filter to query.
  • option: The option to query /ref helics_handle_options.

Query

HELICS_EXPORT const char* helicsQueryExecute(HelicsQuery query, HelicsFederate fed, HelicsError * err)

Execute a query.

The call will block until the query finishes which may require communication or other delays.

Return
A pointer to a string. The string will remain valid until the query is freed or executed again.
    The return will be nullptr if fed or query is an invalid object, the return string will be "#invalid" if the query itself was
invalid.
Parameters
  • query: The query object to use in the query.
  • fed: A federate to send the query through.
  • err: An error object that will contain an error code and string if any error occurred during the execution of the function.

HELICS_EXPORT const char* helicsQueryCoreExecute(HelicsQuery query, HelicsCore core, HelicsError * err)

Execute a query directly on a core.

The call will block until the query finishes which may require communication or other delays.

Return
A pointer to a string. The string will remain valid until the query is freed or executed again.
    The return will be nullptr if core or query is an invalid object, the return string will be "#invalid" if the query itself was
invalid.
Parameters
  • query: The query object to use in the query.
  • core: The core to send the query to.
  • err: An error object that will contain an error code and string if any error occurred during the execution of the function.

HELICS_EXPORT const char* helicsQueryBrokerExecute(HelicsQuery query, HelicsBroker broker, HelicsError * err)

Execute a query directly on a broker.

The call will block until the query finishes which may require communication or other delays.

Return
A pointer to a string. The string will remain valid until the query is freed or executed again.
    The return will be nullptr if broker or query is an invalid object, the return string will be "#invalid" if the query itself was
invalid
Parameters
  • query: The query object to use in the query.
  • broker: The broker to send the query to.
  • err: An error object that will contain an error code and string if any error occurred during the execution of the function.

HELICS_EXPORT void helicsQueryExecuteAsync(HelicsQuery query, HelicsFederate fed, HelicsError * err)

Execute a query in a non-blocking call.

Parameters
  • query: The query object to use in the query.
  • fed: A federate to send the query through.
  • err: An error object that will contain an error code and string if any error occurred during the execution of the function.

HELICS_EXPORT const char* helicsQueryExecuteComplete(HelicsQuery query, HelicsError * err)

Complete the return from a query called with /ref helicsExecuteQueryAsync.

The function will block until the query completes /ref isQueryComplete can be called to determine if a query has completed or not.

Return
A pointer to a string. The string will remain valid until the query is freed or executed again.
    The return will be nullptr if query is an invalid object
Parameters
  • query: The query object to complete execution of.
  • err: An error object that will contain an error code and string if any error occurred during the execution of the function.

HELICS_EXPORT HelicsBool helicsQueryIsCompleted(HelicsQuery query)

Check if an asynchronously executed query has completed.

This function should usually be called after a QueryExecuteAsync function has been called.

Return
Will return HELICS_TRUE if an asynchronous query has completed or a regular query call was made with a result, and false if an asynchronous query has not completed or is invalid
Parameters
  • query: The query object to check if completed.

HELICS_EXPORT void helicsQuerySetTarget(HelicsQuery query, const char * target, HelicsError * err)

Update the target of a query.

Parameters
  • query: The query object to change the target of.
  • target: the name of the target to query
  • err: An error object that will contain an error code and string if any error occurred during the execution of the function.

HELICS_EXPORT void helicsQuerySetQueryString(HelicsQuery query, const char * queryString, HelicsError * err)

Update the queryString of a query.

Parameters
  • query: The query object to change the target of.
  • queryString: the new queryString
  • err: An error object that will contain an error code and string if any error occurred during the execution of the function.

HELICS_EXPORT void helicsQuerySetOrdering(HelicsQuery query, int32_t mode, HelicsError * err)

Update the ordering mode of the query, fast runs on priority channels, ordered goes on normal channels but goes in sequence

Parameters
  • query: The query object to change the order for.
  • mode: 0 for fast, 1 for ordered
  • err: An error object that will contain an error code and string if any error occurred during the execution of the function.

HELICS_EXPORT void helicsQueryFree(HelicsQuery query)

Free the memory associated with a query object.

HELICS_EXPORT void helicsQueryBufferFill(HelicsQueryBuffer buffer, const char * str, int strSize, HelicsError * err)

Set the data for a query callback.

There are many queries that HELICS understands directly, but it is occasionally useful to have a federate be able to respond to specific queries with answers specific to a federate.

Parameters
  • buffer: The buffer received in a helicsQueryCallback.
  • str: Pointer to the data to fill the buffer with.
  • strSize: The size of the string.
  • err: A pointer to an error object for catching errors.