| helics 3.6.1

Functions
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, and helics::Interface::isValid().

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, and helics::Interface::isValid().

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, and helics::Interface::isValid().

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().