ValueFederate.h File Reference

Functions related to value federates for the C api. More...

#include "helicsCore.h"

Go to the source code of this file.

Functions
HelicsInput	helicsFederateRegisterSubscription (HelicsFederate fed, const char *key, const char *units, HelicsError *err)
HelicsPublication	helicsFederateRegisterPublication (HelicsFederate fed, const char *key, HelicsDataTypes type, const char *units, HelicsError *err)
HelicsPublication	helicsFederateRegisterTypePublication (HelicsFederate fed, const char *key, const char *type, const char *units, HelicsError *err)
HelicsPublication	helicsFederateRegisterGlobalPublication (HelicsFederate fed, const char *key, HelicsDataTypes type, const char *units, HelicsError *err)
HelicsPublication	helicsFederateRegisterGlobalTypePublication (HelicsFederate fed, const char *key, const char *type, const char *units, HelicsError *err)
HelicsInput	helicsFederateRegisterInput (HelicsFederate fed, const char *key, HelicsDataTypes type, const char *units, HelicsError *err)
HelicsInput	helicsFederateRegisterTypeInput (HelicsFederate fed, const char *key, const char *type, const char *units, HelicsError *err)
HelicsPublication	helicsFederateRegisterGlobalInput (HelicsFederate fed, const char *key, HelicsDataTypes type, const char *units, HelicsError *err)
HelicsPublication	helicsFederateRegisterGlobalTypeInput (HelicsFederate fed, const char *key, const char *type, const char *units, HelicsError *err)
HelicsPublication	helicsFederateGetPublication (HelicsFederate fed, const char *key, HelicsError *err)
HelicsPublication	helicsFederateGetPublicationByIndex (HelicsFederate fed, int index, HelicsError *err)
HelicsInput	helicsFederateGetInput (HelicsFederate fed, const char *key, HelicsError *err)
HelicsInput	helicsFederateGetInputByIndex (HelicsFederate fed, int index, HelicsError *err)
HELICS_DEPRECATED HelicsInput	helicsFederateGetSubscription (HelicsFederate fed, const char *key, HelicsError *err)
HelicsInput	helicsFederateGetInputByTarget (HelicsFederate fed, const char *target, HelicsError *err)
void	helicsFederateClearUpdates (HelicsFederate fed)
void	helicsFederateRegisterFromPublicationJSON (HelicsFederate fed, const char *json, HelicsError *err)
void	helicsFederatePublishJSON (HelicsFederate fed, const char *json, HelicsError *err)
HelicsBool	helicsPublicationIsValid (HelicsPublication pub)
void	helicsPublicationPublishBytes (HelicsPublication pub, const void *data, int inputDataLength, HelicsError *err)
void	helicsPublicationPublishString (HelicsPublication pub, const char *val, HelicsError *err)
void	helicsPublicationPublishInteger (HelicsPublication pub, int64_t val, HelicsError *err)
void	helicsPublicationPublishBoolean (HelicsPublication pub, HelicsBool val, HelicsError *err)
void	helicsPublicationPublishDouble (HelicsPublication pub, double val, HelicsError *err)
void	helicsPublicationPublishTime (HelicsPublication pub, HelicsTime val, HelicsError *err)
void	helicsPublicationPublishChar (HelicsPublication pub, char val, HelicsError *err)
void	helicsPublicationPublishComplex (HelicsPublication pub, double real, double imag, HelicsError *err)
void	helicsPublicationPublishVector (HelicsPublication pub, const double *vectorInput, int vectorLength, HelicsError *err)
void	helicsPublicationPublishComplexVector (HelicsPublication pub, const double *vectorInput, int vectorLength, HelicsError *err)
void	helicsPublicationPublishNamedPoint (HelicsPublication pub, const char *field, double val, HelicsError *err)
void	helicsPublicationPublishDataBuffer (HelicsPublication pub, HelicsDataBuffer buffer, HelicsError *err)
void	helicsPublicationAddTarget (HelicsPublication pub, const char *target, HelicsError *err)
HelicsBool	helicsInputIsValid (HelicsInput ipt)
void	helicsInputAddTarget (HelicsInput ipt, const char *target, HelicsError *err)
int	helicsInputGetByteCount (HelicsInput ipt)
void	helicsInputGetBytes (HelicsInput ipt, void *data, int maxDataLength, int *actualSize, HelicsError *err)
HelicsDataBuffer	helicsInputGetDataBuffer (HelicsInput inp, HelicsError *err)
int	helicsInputGetStringSize (HelicsInput ipt)
void	helicsInputGetString (HelicsInput ipt, char *outputString, int maxStringLength, int *actualLength, HelicsError *err)
int64_t	helicsInputGetInteger (HelicsInput ipt, HelicsError *err)
HelicsBool	helicsInputGetBoolean (HelicsInput ipt, HelicsError *err)
double	helicsInputGetDouble (HelicsInput ipt, HelicsError *err)
HelicsTime	helicsInputGetTime (HelicsInput ipt, HelicsError *err)
char	helicsInputGetChar (HelicsInput ipt, HelicsError *err)
HelicsComplex	helicsInputGetComplexObject (HelicsInput ipt, HelicsError *err)
void	helicsInputGetComplex (HelicsInput ipt, double *real, double *imag, HelicsError *err)
int	helicsInputGetVectorSize (HelicsInput ipt)
void	helicsInputGetVector (HelicsInput ipt, double data[], int maxLength, int *actualSize, HelicsError *err)
void	helicsInputGetComplexVector (HelicsInput ipt, double data[], int maxLength, int *actualSize, HelicsError *err)
void	helicsInputGetNamedPoint (HelicsInput ipt, char *outputString, int maxStringLength, int *actualLength, double *val, HelicsError *err)
void	helicsInputSetDefaultBytes (HelicsInput ipt, const void *data, int inputDataLength, HelicsError *err)
void	helicsInputSetDefaultString (HelicsInput ipt, const char *defaultString, HelicsError *err)
void	helicsInputSetDefaultInteger (HelicsInput ipt, int64_t val, HelicsError *err)
void	helicsInputSetDefaultBoolean (HelicsInput ipt, HelicsBool val, HelicsError *err)
void	helicsInputSetDefaultTime (HelicsInput ipt, HelicsTime val, HelicsError *err)
void	helicsInputSetDefaultChar (HelicsInput ipt, char val, HelicsError *err)
void	helicsInputSetDefaultDouble (HelicsInput ipt, double val, HelicsError *err)
void	helicsInputSetDefaultComplex (HelicsInput ipt, double real, double imag, HelicsError *err)
void	helicsInputSetDefaultVector (HelicsInput ipt, const double *vectorInput, int vectorLength, HelicsError *err)
void	helicsInputSetDefaultComplexVector (HelicsInput ipt, const double *vectorInput, int vectorLength, HelicsError *err)
void	helicsInputSetDefaultNamedPoint (HelicsInput ipt, const char *defaultName, double val, HelicsError *err)
const char *	helicsInputGetType (HelicsInput ipt)
const char *	helicsInputGetPublicationType (HelicsInput ipt)
int	helicsInputGetPublicationDataType (HelicsInput ipt)
const char *	helicsPublicationGetType (HelicsPublication pub)
const char *	helicsInputGetName (HelicsInput ipt)
HELICS_DEPRECATED const char *	helicsSubscriptionGetTarget (HelicsInput ipt)
const char *	helicsInputGetTarget (HelicsInput ipt)
const char *	helicsPublicationGetName (HelicsPublication pub)
const char *	helicsInputGetUnits (HelicsInput ipt)
const char *	helicsInputGetInjectionUnits (HelicsInput ipt)
const char *	helicsInputGetExtractionUnits (HelicsInput ipt)
const char *	helicsPublicationGetUnits (HelicsPublication pub)
const char *	helicsInputGetInfo (HelicsInput inp)
void	helicsInputSetInfo (HelicsInput inp, const char *info, HelicsError *err)
const char *	helicsInputGetTag (HelicsInput inp, const char *tagname)
void	helicsInputSetTag (HelicsInput inp, const char *tagname, const char *tagvalue, HelicsError *err)
const char *	helicsPublicationGetInfo (HelicsPublication pub)
void	helicsPublicationSetInfo (HelicsPublication pub, const char *info, HelicsError *err)
const char *	helicsPublicationGetTag (HelicsPublication pub, const char *tagname)
void	helicsPublicationSetTag (HelicsPublication pub, const char *tagname, const char *tagvalue, HelicsError *err)
int	helicsInputGetOption (HelicsInput inp, int option)
void	helicsInputSetOption (HelicsInput inp, int option, int value, HelicsError *err)
int	helicsPublicationGetOption (HelicsPublication pub, int option)
void	helicsPublicationSetOption (HelicsPublication pub, int option, int val, HelicsError *err)
void	helicsPublicationSetMinimumChange (HelicsPublication pub, double tolerance, HelicsError *err)
void	helicsInputSetMinimumChange (HelicsInput inp, double tolerance, HelicsError *err)
HelicsBool	helicsInputIsUpdated (HelicsInput ipt)
HelicsTime	helicsInputLastUpdateTime (HelicsInput ipt)
void	helicsInputClearUpdate (HelicsInput ipt)
int	helicsFederateGetPublicationCount (HelicsFederate fed)
int	helicsFederateGetInputCount (HelicsFederate fed)

Detailed Description

Functions related to value federates for the C api.

Function Documentation

helicsFederateClearUpdates()

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.

Referenced by helicscpp::ValueFederate::clearUpdates().

helicsFederateGetInput()

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

Get an input object from a key.

Parameters

	fed	The value federate object to use to get the publication.
	key	The name of the input.
[in,out]	err	The error object to complete if there is an error.

Returns

A HelicsInput object, the object will not be valid and err will contain an error code if no input with the specified key exists.

References HELICS_ERROR_INVALID_ARGUMENT.

Referenced by helicscpp::ValueFederate::getInput().

helicsFederateGetInputByIndex()

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.

Parameters

	fed	The federate object in which to create a publication.
	index	The index of the publication to get.
[in,out]	err	A pointer to an error object for catching errors.

Returns

A HelicsInput, which will be NULL if an invalid index.

References HELICS_ERROR_INVALID_ARGUMENT.

Referenced by helicscpp::ValueFederate::getInput().

helicsFederateGetInputByTarget()

HelicsInput helicsFederateGetInputByTarget	(	HelicsFederate	fed,
		const char *	target,
		HelicsError *	err
	)

Get an input object from a target.

Parameters

	fed	The value federate object to use to get the input.
	target	The name of the publication that an input is targeting.
[in,out]	err	The error object to complete if there is an error.

Returns

A HelicsInput object, the object will not be valid and err will contain an error code if no input with the specified key exists.

References HELICS_ERROR_INVALID_ARGUMENT.

Referenced by helicscpp::ValueFederate::getInputByTarget(), and helicsFederateGetSubscription().

helicsFederateGetInputCount()

int helicsFederateGetInputCount

(

HelicsFederate

fed

)

Get the number of inputs in a federate.

Returns

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

Referenced by helicscpp::ValueFederate::getInputCount().

helicsFederateGetPublication()

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

Get a publication object from a key.

Parameters

	fed	The value federate object to use to get the publication.
	key	The name of the publication.
[in,out]	err	The error object to complete if there is an error.

Returns

A HelicsPublication object, the object will not be valid and err will contain an error code if no publication with the specified key exists.

References HELICS_ERROR_INVALID_ARGUMENT, and helics::Interface::isValid().

Referenced by helicscpp::ValueFederate::getPublication().

helicsFederateGetPublicationByIndex()

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.

Parameters

	fed	The federate object in which to create a publication.
	index	The index of the publication to get.
[in,out]	err	A pointer to an error object for catching errors.

Returns

A HelicsPublication.

References HELICS_ERROR_INVALID_ARGUMENT, and helics::Interface::isValid().

Referenced by helicscpp::ValueFederate::getPublication().

helicsFederateGetPublicationCount()

int helicsFederateGetPublicationCount

(

HelicsFederate

fed

)

Get the number of publications in a federate.

Returns

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

Referenced by helicscpp::ValueFederate::getPublicationCount().

helicsFederateGetSubscription()

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

Get an input object from a subscription target. DEPRECATED: use helicsFederateGetInputByTarget instead

Parameters

	fed	The value federate object to use to get the publication.
	key	The name of the publication that a subscription is targeting.
[in,out]	err	The error object to complete if there is an error.

Returns

A HelicsInput object, the object will not be valid and err will contain an error code if no input with the specified key exists.

References helicsFederateGetInputByTarget().

helicsFederatePublishJSON()

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.
[in,out]	err	The error object to complete if there is an error.

Referenced by helicscpp::ValueFederate::publishJSON().

helicsFederateRegisterFromPublicationJSON()

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

Register the publications via JSON publication string.

Parameters

	fed	The value federate object to use to register the publications.
	json	The JSON publication string.
[in,out]	err	The error object to complete if there is an error.

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

Referenced by helicscpp::ValueFederate::registerFromPublicationJSON().

helicsFederateRegisterGlobalInput()

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 inputs and publications.

Parameters

	fed	The federate object in which to create a publication.
	key	The identifier for the input (may be NULL).
	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).
[in,out]	err	A pointer to an error object for catching errors.

Returns

An object containing the input.

References HELICS_DATA_TYPE_ANY, HELICS_DATA_TYPE_CHAR, HELICS_DATA_TYPE_JSON, HELICS_DATA_TYPE_RAW, HELICS_DATA_TYPE_STRING, HELICS_ERROR_INVALID_ARGUMENT, helicsFederateRegisterGlobalTypeInput(), and helics::typeNameStringRef().

Referenced by helicscpp::ValueFederate::registerGlobalInput().

helicsFederateRegisterGlobalPublication()

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 inputs and publications.

Parameters

	fed	The federate object in which to create a publication.
	key	The identifier for the publication (may be NULL).
	type	A code identifying the type of the input see /ref HelicsDataTypes for available options.
	units	A string listing the units of the publication (may be NULL).
[in,out]	err	A pointer to an error object for catching errors.

Returns

An object containing the publication.

References HELICS_DATA_TYPE_RAW, HELICS_DATA_TYPE_TIME, HELICS_ERROR_INVALID_ARGUMENT, helicsFederateRegisterGlobalTypePublication(), and helics::typeNameStringRef().

Referenced by helicscpp::ValueFederate::registerGlobalPublication().

helicsFederateRegisterGlobalTypeInput()

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

Register an input with an arbitrary type.

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

Parameters

	fed	The federate object in which to create an input.
	key	The identifier for the input (may be NULL).
	type	A string defining the type of the input (may be NULL).
	units	A string listing the units of the input (may be NULL).
[in,out]	err	A pointer to an error object for catching errors.

Returns

An object containing the input.

Referenced by helicsFederateRegisterGlobalInput(), and helicscpp::ValueFederate::registerGlobalInput().

helicsFederateRegisterGlobalTypePublication()

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 inputs and publications.

Parameters

	fed	The federate object in which to create a publication.
	key	The identifier for the publication (may be NULL).
	type	A string describing the expected type of the publication (may be NULL).
	units	A string listing the units of the publication (may be NULL).
[in,out]	err	A pointer to an error object for catching errors.

Returns

An object containing the publication.

Referenced by helicsFederateRegisterGlobalPublication(), and helicscpp::ValueFederate::registerGlobalPublication().

helicsFederateRegisterInput()

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 inputs, and publications.

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 (may be NULL).
	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).
[in,out]	err	A pointer to an error object for catching errors.

Returns

An object containing the input.

References HELICS_DATA_TYPE_ANY, HELICS_DATA_TYPE_CHAR, HELICS_DATA_TYPE_JSON, HELICS_DATA_TYPE_RAW, HELICS_DATA_TYPE_STRING, HELICS_ERROR_INVALID_ARGUMENT, helicsFederateRegisterTypeInput(), and helics::typeNameStringRef().

helicsFederateRegisterPublication()

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 inputs and publications.

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 (may be NULL).
	type	A code identifying the type of the input see /ref HelicsDataTypes for available options.
	units	A string listing the units of the publication (may be NULL).
[in,out]	err	A pointer to an error object for catching errors.

Returns

An object containing the publication.

References HELICS_DATA_TYPE_CHAR, HELICS_DATA_TYPE_JSON, HELICS_DATA_TYPE_RAW, HELICS_DATA_TYPE_STRING, HELICS_ERROR_INVALID_ARGUMENT, helicsFederateRegisterTypePublication(), and helics::typeNameStringRef().

Referenced by helicscpp::ValueFederate::registerInput(), and helicscpp::ValueFederate::registerPublication().

helicsFederateRegisterSubscription()

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

input/publication registration Create an input and add a publication target.

this method is a wrapper method to create and unnamed input and add a publication target to it

Parameters

	fed	The federate object in which to create an input, must have been created with /ref helicsCreateValueFederate or /ref helicsCreateCombinationFederate.
	key	The identifier matching a publication to add as an input target.
	units	A string listing the units of the input (may be NULL).
[in,out]	err	A pointer to an error object for catching errors.

Returns

An object containing the input.

Referenced by helicscpp::ValueFederate::registerSubscription().

helicsFederateRegisterTypeInput()

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 inputs, and publications.

Parameters

	fed	The federate object in which to create an input.
	key	The identifier for the input (may be NULL).
	type	A string describing the expected type of the input (may be NULL).
	units	A string listing the units of the input maybe NULL.
[in,out]	err	A pointer to an error object for catching errors.

Returns

An object containing the publication.

Referenced by helicsFederateRegisterInput(), and helicscpp::ValueFederate::registerInput().

helicsFederateRegisterTypePublication()

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 inputs and publications.

Parameters

	fed	The federate object in which to create a publication.
	key	The identifier for the publication (may be NULL).
	type	A string labeling the type of the publication (may be NULL).
	units	A string listing the units of the publication (may be NULL).
[in,out]	err	A pointer to an error object for catching errors.

Returns

An object containing the publication.

Referenced by helicsFederateRegisterPublication(), and helicscpp::ValueFederate::registerPublication().

helicsInputClearUpdate()

void helicsInputClearUpdate

(

HelicsInput

ipt

)

Clear the updated flag from an input.

Referenced by helicscpp::Input::clearUpdate().

helicsInputIsUpdated()

HelicsBool helicsInputIsUpdated

(

HelicsInput

ipt

)

Check if a particular input was updated.

Returns

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

References HELICS_FALSE, and HELICS_TRUE.

Referenced by helicscpp::Input::isUpdated().

helicsInputLastUpdateTime()

HelicsTime helicsInputLastUpdateTime

(

HelicsInput

ipt

)

Get the last time a input was updated.

References HELICS_TIME_INVALID.

Referenced by helicscpp::Input::getLastUpdateTime().