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.