| helics 3.6.1

Functions
helicsCallbacks.h File Reference

Functions dealing with callbacks for the shared library. More...

`#include "helicsCore.h"`

Go to the source code of this file.

## Functions
void | helicsBrokerSetLoggingCallback (HelicsBroker broker, void(*logger)(int loglevel, const char *identifier, const char *message, void *userData), void *userdata, HelicsError *err)
void | helicsCoreSetLoggingCallback (HelicsCore core, void(*logger)(int loglevel, const char *identifier, const char *message, void *userData), void *userdata, HelicsError *err)
void | helicsFederateSetLoggingCallback (HelicsFederate fed, void(*logger)(int loglevel, const char *identifier, const char *message, void *userData), void *userdata, HelicsError *err)
void | helicsFilterSetCustomCallback (HelicsFilter filter, HelicsMessage(*filtCall)(HelicsMessage message, void *userData), void *userdata, HelicsError *err)
void | helicsTranslatorSetCustomCallback (HelicsTranslator translator, void(*toMessageCall)(HelicsDataBuffer value, HelicsMessage message, void *userData), void(*toValueCall)(HelicsMessage message, HelicsDataBuffer value, void *userData), void *userdata, HelicsError *err)
void | helicsFederateSetQueryCallback (HelicsFederate fed, void(*queryAnswer)(const char *query, int querySize, HelicsQueryBuffer buffer, void *userdata), void *userdata, HelicsError *err)
void | helicsFederateSetTimeRequestEntryCallback (HelicsFederate fed, void(*requestTime)(HelicsTime currentTime, HelicsTime requestTime, HelicsBool iterating, void *userdata), void *userdata, HelicsError *err)
void | helicsFederateSetTimeUpdateCallback (HelicsFederate fed, void(*timeUpdate)(HelicsTime newTime, HelicsBool iterating, void *userdata), void *userdata, HelicsError *err)
void | helicsFederateSetStateChangeCallback (HelicsFederate fed, void(*stateChange)(HelicsFederateState newState, HelicsFederateState oldState, void *userdata), void *userdata, HelicsError *err)
void | helicsFederateSetTimeRequestReturnCallback (HelicsFederate fed, void(*requestTimeReturn)(HelicsTime newTime, HelicsBool iterating, void *userdata), void *userdata, HelicsError *err)
void | helicsFederateInitializingEntryCallback (HelicsFederate fed, void(*initializingEntry)(HelicsBool iterating, void *userdata), void *userdata, HelicsError *err)
void | helicsFederateExecutingEntryCallback (HelicsFederate fed, void(*executingEntry)(void *userdata), void *userdata, HelicsError *err)
void | helicsFederateCosimulationTerminationCallback (HelicsFederate fed, void(*cosimTermination)(void *userdata), void *userdata, HelicsError *err)
void | helicsFederateErrorHandlerCallback (HelicsFederate fed, void(*errorHandler)(int errorCode, const char *errorString, void *userdata), void *userdata, HelicsError *err)
void | helicsCallbackFederateNextTimeCallback (HelicsFederate fed, HelicsTime(*timeUpdate)(HelicsTime time, void *userdata), void *userdata, HelicsError *err)
void | helicsCallbackFederateNextTimeIterativeCallback (HelicsFederate fed, HelicsTime(*timeUpdate)(HelicsTime time, HelicsIterationResult result, HelicsIterationRequest *iteration, void *userdata), void *userdata, HelicsError *err)
void | helicsCallbackFederateInitializeCallback (HelicsFederate fed, HelicsIterationRequest(*initialize)(void *userdata), void *userdata, HelicsError *err)
void | helicsQueryBufferFill (HelicsQueryBuffer buffer, const char *queryResult, int strSize, HelicsError *err)

## Detailed Description

Functions dealing with callbacks for the shared library.

## Function Documentation

## ◆ helicsBrokerSetLoggingCallback()

void helicsBrokerSetLoggingCallback | ( | HelicsBroker | broker,
|  | void(*)(int loglevel, const char *identifier, const char *message, void *userData) | logger,
|  | 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.
  [in,out] | err | A pointer to an error object for catching errors.

## ◆ helicsCallbackFederateInitializeCallback()

void helicsCallbackFederateInitializeCallback | ( | HelicsFederate | fed,
|  | HelicsIterationRequest(*)(void *userdata) | initialize,
|  | void * | userdata,
|  | HelicsError * | err
| ) |  |

Set callback for initialization.

This callback will be executed when computing whether to iterate in initialization mode.

Parameters

  | fed | The federate to set the callback for.
  | initialize | A callback with signature HelicsIterationRequest(void *userdata);
  | userdata | A pointer to user data that is passed to the function when executing.
  [in,out] | err | A pointer to an error object for catching errors.

## ◆ helicsCallbackFederateNextTimeCallback()

void helicsCallbackFederateNextTimeCallback | ( | HelicsFederate | fed,
|  | HelicsTime(*)(HelicsTime time, void *userdata) | timeUpdate,
|  | void * | userdata,
|  | HelicsError * | err
| ) |  |

Set callback for the next time update.

This callback will be triggered to compute the next time update for a callback federate.

Parameters

  | fed | The federate to set the callback for.
  | timeUpdate | A callback with signature HelicsTime(HelicsTime time, void *userdata);
  | userdata | A pointer to user data that is passed to the function when executing.
  [in,out] | err | A pointer to an error object for catching errors.

## ◆ helicsCallbackFederateNextTimeIterativeCallback()

void helicsCallbackFederateNextTimeIterativeCallback | ( | HelicsFederate | fed,
|  | HelicsTime(*)(HelicsTime time, HelicsIterationResult result, HelicsIterationRequest *iteration, void *userdata) | timeUpdate,
|  | void * | userdata,
|  | HelicsError * | err
| ) |  |

Set callback for the next time update with iteration capability.

This callback will be triggered to compute the next time update for a callback federate.

Parameters

  | fed | The federate to set the callback for.
  | timeUpdate | A callback with signature HelicsTime(HelicsTime time, HelicsIterationResult result, HelicsIterationRequest* iteration, void *userdata);
  | userdata | A pointer to user data that is passed to the function when executing.
  [in,out] | err | A pointer to an error object for catching errors.

## ◆ helicsCoreSetLoggingCallback()

void helicsCoreSetLoggingCallback | ( | HelicsCore | core,
|  | void(*)(int loglevel, const char *identifier, const char *message, void *userData) | logger,
|  | 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.
  [in,out] | err | A pointer to an error object for catching errors.

## ◆ helicsFederateCosimulationTerminationCallback()

void helicsFederateCosimulationTerminationCallback | ( | HelicsFederate | fed,
|  | void(*)(void *userdata) | cosimTermination,
|  | void * | userdata,
|  | HelicsError * | err
| ) |  |

Set callback for cosimulation termination.

This callback will be executed once when the time advancement of the federate/co-simulation has terminated. This may be called as part of the finalize operation, or when a maxTime signal is returned from requestTime or when an error is encountered.

Parameters

  | fed | The federate to set the callback for.
  | cosimTermination | A callback with signature void(void *userdata);
  | userdata | A pointer to user data that is passed to the function when executing.
  [in,out] | err | A pointer to an error object for catching errors.

## ◆ helicsFederateErrorHandlerCallback()

void helicsFederateErrorHandlerCallback | ( | HelicsFederate | fed,
|  | void(*)(int errorCode, const char *errorString, void *userdata) | errorHandler,
|  | void * | userdata,
|  | HelicsError * | err
| ) |  |

Set callback for error handling.

This callback will be called when a federate error is encountered.

Parameters

  | fed | The federate to set the callback for.
  | errorHandler | A callback with signature void(int errorCode, const char *errorString, void *userdata);
  | userdata | A pointer to user data that is passed to the function when executing.
  [in,out] | err | A pointer to an error object for catching errors.

## ◆ helicsFederateExecutingEntryCallback()

void helicsFederateExecutingEntryCallback | ( | HelicsFederate | fed,
|  | void(*)(void *userdata) | executingEntry,
|  | void * | userdata,
|  | HelicsError * | err
| ) |  |

Set callback for the entry to ExecutingMode.

This callback will be executed once on first entry to executingMode

Parameters

  | fed | The federate to set the callback for.
  | executingEntry | A callback with signature void(void *userdata);
  | userdata | A pointer to user data that is passed to the function when executing.
  [in,out] | err | A pointer to an error object for catching errors.

## ◆ helicsFederateInitializingEntryCallback()

void helicsFederateInitializingEntryCallback | ( | HelicsFederate | fed,
|  | void(*)(HelicsBool iterating, void *userdata) | initializingEntry,
|  | void * | userdata,
|  | HelicsError * | err
| ) |  |

Set callback for the entry to initializingMode.

This callback will be executed when the initializingMode is entered

Parameters

  | fed | The federate to set the callback for.
  | initializingEntry | A callback with signature void(HelicsBool iterating, void *userdata); the bool parameter is set to true if the entry is iterative, therefore the first time this is called the bool is false and all subsequent times it is true.
  | userdata | A pointer to user data that is passed to the function when executing.
  [in,out] | err | A pointer to an error object for catching errors.

References HELICS_FALSE, and HELICS_TRUE.

## ◆ helicsFederateSetLoggingCallback()

void helicsFederateSetLoggingCallback | ( | HelicsFederate | fed,
|  | void(*)(int loglevel, const char *identifier, const char *message, void *userData) | logger,
|  | 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.
  [in,out] | err | A pointer to an error object for catching errors.

## ◆ helicsFederateSetQueryCallback()

void helicsFederateSetQueryCallback | ( | HelicsFederate | fed,
|  | void(*)(const char *query, int querySize, HelicsQueryBuffer buffer, void *userdata) | queryAnswer,
|  | 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, HelicsQueryBuffer buffer, void *userdata); The function arguments include the query string requesting an answer along with its size; the string is not guaranteed to be null terminated. HelicsQueryBuffer is the buffer intended to filled out by the userCallback. The buffer can be empty if the query is not recognized and HELICS will generate the appropriate response. The buffer is used to ensure memory ownership separation between user code and HELICS code. The HelicsQueryBufferFill method can be used to load a string into the buffer.
  | userdata | A pointer to user data that is passed to the function when executing.
  [in,out] | err | A pointer to an error object for catching errors.

## ◆ helicsFederateSetStateChangeCallback()

void helicsFederateSetStateChangeCallback | ( | HelicsFederate | fed,
|  | void(*)(HelicsFederateState newState, HelicsFederateState oldState, void *userdata) | stateChange,
|  | void * | userdata,
|  | HelicsError * | err
| ) |  |

Set callback for the federate mode change.

This callback will be executed every time the operating mode of the federate changes.

Parameters

  | fed | The federate to set the callback for.
  | stateChange | A callback with signature void(HelicsFederateState newState, HelicsFederateState oldState, void *userdata); The function arguments are the new state, the old state, and pointer to the userdata.
  | userdata | A pointer to user data that is passed to the function when executing.
  [in,out] | err | A pointer to an error object for catching errors.

## ◆ helicsFederateSetTimeRequestEntryCallback()

void helicsFederateSetTimeRequestEntryCallback | ( | HelicsFederate | fed,
|  | void(*)(HelicsTime currentTime, HelicsTime requestTime, HelicsBool iterating, void *userdata) | requestTime,
|  | void * | userdata,
|  | HelicsError * | err
| ) |  |

Set callback for the time request.

This callback will be executed when a valid time request is made. It is intended for the possibility of embedded data grabbers in a callback to simplify user code.

Parameters

  | fed | The federate to set the callback for.
  | requestTime | A callback with signature void(HelicsTime currentTime, HelicsTime requestTime, bool iterating, void *userdata); The function arguments are the current time value, the requested time value, a bool indicating that the time is iterating, and pointer to the userdata.
  | userdata | A pointer to user data that is passed to the function when executing.
  [in,out] | err | A pointer to an error object for catching errors.

References HELICS_FALSE, and HELICS_TRUE.

## ◆ helicsFederateSetTimeRequestReturnCallback()

void helicsFederateSetTimeRequestReturnCallback | ( | HelicsFederate | fed,
|  | void(*)(HelicsTime newTime, HelicsBool iterating, void *userdata) | requestTimeReturn,
|  | void * | userdata,
|  | HelicsError * | err
| ) |  |

Set callback for the time request return.

This callback will be executed after all other callbacks for a time request return. This callback will be the last thing executed before returning control to the user program. The difference between this and the TimeUpdate callback is the order of execution. The timeUpdate callback is executed prior to individual interface callbacks, this callback is executed after all others.

Parameters

  | fed | The federate to set the callback for.
  | requestTimeReturn | A callback with signature void(HelicsTime newTime, bool iterating, void *userdata); The function arguments are the new time value, a bool indicating that the time is iterating, and pointer to the userdata.
  | userdata | A pointer to user data that is passed to the function when executing.
  [in,out] | err | A pointer to an error object for catching errors.

References HELICS_FALSE, and HELICS_TRUE.

## ◆ helicsFederateSetTimeUpdateCallback()

void helicsFederateSetTimeUpdateCallback | ( | HelicsFederate | fed,
|  | void(*)(HelicsTime newTime, HelicsBool iterating, void *userdata) | timeUpdate,
|  | void * | userdata,
|  | HelicsError * | err
| ) |  |

Set callback for the time update.

This callback will be executed every time the simulation time is updated starting on entry to executing mode.

Parameters

  | fed | The federate to set the callback for.
  | timeUpdate | A callback with signature void(HelicsTime newTime, bool iterating, void *userdata); The function arguments are the new time value, a bool indicating that the time is iterating, and pointer to the userdata.
  | userdata | A pointer to user data that is passed to the function when executing.
  [in,out] | err | A pointer to an error object for catching errors.

References HELICS_FALSE, and HELICS_TRUE.

## ◆ helicsFilterSetCustomCallback()

void helicsFilterSetCustomCallback | ( | HelicsFilter | filter,
|  | HelicsMessage(*)(HelicsMessage message, void *userData) | filtCall,
|  | 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.
  [in,out] | err | A pointer to an error object for catching errors.

References HELICS_ERROR_INVALID_OBJECT.

## ◆ helicsQueryBufferFill()

void helicsQueryBufferFill | ( | HelicsQueryBuffer | buffer,
|  | const char * | queryResult,
|  | 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.
  | queryResult | Pointer to the data with the query result to fill the buffer with.
  | strSize | The size of the string.
  [in,out] | err | A pointer to an error object for catching errors.

References HELICS_ERROR_INVALID_OBJECT.

## ◆ helicsTranslatorSetCustomCallback()

void helicsTranslatorSetCustomCallback | ( | HelicsTranslator | translator,
|  | void(*)(HelicsDataBuffer value, HelicsMessage message, void *userData) | toMessageCall,
|  | void(*)(HelicsMessage message, HelicsDataBuffer value, void *userData) | toValueCall,
|  | void * | userdata,
|  | HelicsError * | err
| ) |  |

Set a general callback for a custom translator.

Add a pair of custom callbacks for running a translator operation in the C shared library.

Parameters

  | translator | The translator object to set the callbacks for.
  | toMessageCall | A callback with signature void(HelicsDataBuffer, HelicsMessage, void *); The function arguments are raw Value data, the messageObject to fill out and a pointer to user data.
  | toValueCall | A callback with signature void(HelicsMessage, HelicsDataBuffer, void *); The function arguments are a message object, the data buffer to fill out and a pointer to user data.
  | userdata | A pointer to user data that is passed to the functions when executing.
  [in,out] | err | A pointer to an error object for catching errors.

References HELICS_ERROR_INVALID_OBJECT.