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

#include "helicsCore.h"

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

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

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

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

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

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

HelicsBool	helicsEndpointIsValid (HelicsEndpoint endpoint)

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

const char *	helicsEndpointGetDefaultDestination (HelicsEndpoint endpoint)

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

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

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

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

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

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

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

HelicsBool	helicsFederateHasMessage (HelicsFederate fed)

HelicsBool	helicsEndpointHasMessage (HelicsEndpoint endpoint)

int	helicsFederatePendingMessageCount (HelicsFederate fed)

int	helicsEndpointPendingMessageCount (HelicsEndpoint endpoint)

HelicsMessage	helicsEndpointGetMessage (HelicsEndpoint endpoint)

HelicsMessage	helicsEndpointCreateMessage (HelicsEndpoint endpoint, HelicsError *err)

void	helicsEndpointClearMessages (HelicsEndpoint endpoint)

HelicsMessage	helicsFederateGetMessage (HelicsFederate fed)

HelicsMessage	helicsFederateCreateMessage (HelicsFederate fed, HelicsError *err)

void	helicsFederateClearMessages (HelicsFederate fed)

const char *	helicsEndpointGetType (HelicsEndpoint endpoint)

const char *	helicsEndpointGetName (HelicsEndpoint endpoint)

int	helicsFederateGetEndpointCount (HelicsFederate fed)

const char *	helicsEndpointGetInfo (HelicsEndpoint end)

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

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

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

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

int	helicsEndpointGetOption (HelicsEndpoint endpoint, int option)

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

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

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

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

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

const char *	helicsMessageGetSource (HelicsMessage message)

const char *	helicsMessageGetDestination (HelicsMessage message)

const char *	helicsMessageGetOriginalSource (HelicsMessage message)

const char *	helicsMessageGetOriginalDestination (HelicsMessage message)

HelicsTime	helicsMessageGetTime (HelicsMessage message)

const char *	helicsMessageGetString (HelicsMessage message)

int	helicsMessageGetMessageID (HelicsMessage message)

HelicsBool	helicsMessageGetFlagOption (HelicsMessage message, int flag)

int	helicsMessageGetByteCount (HelicsMessage message)

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

void *	helicsMessageGetBytesPointer (HelicsMessage message)

HelicsDataBuffer	helicsMessageDataBuffer (HelicsMessage message, HelicsError *err)

HelicsBool	helicsMessageIsValid (HelicsMessage message)

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

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

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

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

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

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

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

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

void	helicsMessageClearFlags (HelicsMessage message)

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

void	helicsMessageSetString (HelicsMessage message, const char data, HelicsError err)

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

void	helicsMessageSetDataBuffer (HelicsMessage message, HelicsDataBuffer data, HelicsError *err)

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

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

HelicsMessage	helicsMessageClone (HelicsMessage message, HelicsError *err)

void	helicsMessageFree (HelicsMessage message)

void	helicsMessageClear (HelicsMessage message, HelicsError *err)

Detailed Description

Functions related to message federates for the C api.

Function Documentation

◆ helicsEndpointAddDestinationFilter()

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.
[in,out]	err	An error object to fill out in case of an error.

◆ helicsEndpointAddDestinationTarget()

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
[in,out]	err	An error object to fill out in case of an error.

◆ helicsEndpointAddSourceFilter()

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
[in,out]	err	An error object to fill out in case of an error.

◆ helicsEndpointAddSourceTarget()

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
[in,out]	err	An error object to fill out in case of an error.

◆ helicsEndpointClearMessages()

void helicsEndpointClearMessages ( HelicsEndpoint endpoint )

Clear all stored messages stored from an endpoint.

This clears messages retrieved through helicsEndpointGetMessage or helicsEndpointCreateMessage

Parameters

endpoint The endpoint to clear the message for.

◆ helicsEndpointCreateMessage()

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.

Parameters

	endpoint	The endpoint object to associate the message with.
[in,out]	err	An error object to fill out in case of an error.

Returns: A new HelicsMessage.

Referenced by helicscpp::Endpoint::createMessage(), and helicscpp::Message::newMessageObject().

◆ helicsEndpointGetDefaultDestination()

const char* helicsEndpointGetDefaultDestination ( HelicsEndpoint endpoint )

Get the default destination for an endpoint.

Parameters

endpoint The endpoint to set the destination for.

Returns: A string with the default destination.

Referenced by helicscpp::Endpoint::getDefaultDestination().

◆ helicsEndpointGetInfo()

const char* helicsEndpointGetInfo ( HelicsEndpoint end )

Get the local information field of an endpoint.

Parameters

end	The endpoint to query.

Returns: A string with the info field string.

Referenced by helicscpp::Endpoint::getInfo().

◆ helicsEndpointGetMessage()

HelicsMessage helicsEndpointGetMessage ( HelicsEndpoint endpoint )

Receive a packet from a particular endpoint.

Parameters

[in] endpoint The identifier for the endpoint.

Returns: A message object.

Referenced by helicscpp::Endpoint::getMessage().

◆ helicsEndpointGetName()

const char* helicsEndpointGetName ( HelicsEndpoint endpoint )

Get the name of an endpoint.

Parameters

endpoint The endpoint object in question.

Returns: The name of the endpoint.

Referenced by helicscpp::Endpoint::getName().

◆ helicsEndpointGetOption()

int helicsEndpointGetOption	(	HelicsEndpoint	endpoint,
		int	option
	)

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.

Returns: the value of the option, for boolean options will be 0 or 1

References HELICS_FALSE.

◆ helicsEndpointGetTag()

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

Get the data in a specified tag of an endpoint

Parameters

endpoint	The endpoint to query.
tagname	The name of the tag to query.

Returns: A string with the tag data.

◆ helicsEndpointGetType()

const char* helicsEndpointGetType ( HelicsEndpoint endpoint )

Get the type specified for an endpoint.

Parameters

endpoint The endpoint object in question.

Returns: The defined type of the endpoint.

Referenced by helicscpp::Endpoint::getType().

◆ helicsEndpointHasMessage()

HelicsBool helicsEndpointHasMessage ( HelicsEndpoint endpoint )

Check if a given endpoint has any unread messages.

Parameters

endpoint The endpoint to check.

Returns: HELICS_TRUE if the endpoint has a message, HELICS_FALSE otherwise.

References HELICS_FALSE, and HELICS_TRUE.

◆ helicsEndpointIsValid()

HelicsBool helicsEndpointIsValid ( HelicsEndpoint endpoint )

Check if an endpoint is valid.

Parameters

endpoint The endpoint object to check.

Returns: HELICS_TRUE if the Endpoint object represents a valid endpoint.

References HELICS_FALSE, and HELICS_TRUE.

Referenced by helicscpp::Endpoint::isValid().

◆ helicsEndpointPendingMessageCount()

int helicsEndpointPendingMessageCount ( HelicsEndpoint endpoint )

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

Parameters

endpoint The endpoint to query.

Referenced by helicscpp::Endpoint::pendingMessageCount().

◆ helicsEndpointRemoveTarget()

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
[in,out]	err	An error object to fill out in case of an error.

◆ helicsEndpointSendBytes()

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

Referenced by helicscpp::Endpoint::send().

◆ helicsEndpointSendBytesAt()

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

Referenced by helicscpp::Endpoint::sendAt().

◆ helicsEndpointSendBytesTo()

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. Use nullptr to send to the default destination.
[in,out]	err	A pointer to an error object for catching errors.

Referenced by helicscpp::Endpoint::sendTo().

◆ helicsEndpointSendBytesToAt()

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. Use nullptr to send to the default destination.
	time	The time the message should be sent.
[in,out]	err	A pointer to an error object for catching errors.

Referenced by helicscpp::Endpoint::sendToAt().

◆ helicsEndpointSendMessage()

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

Referenced by helicscpp::Endpoint::sendMessage().

◆ helicsEndpointSendMessageZeroCopy()

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

Referenced by helicscpp::Endpoint::sendMessageZeroCopy().

◆ helicsEndpointSetDefaultDestination()

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

Referenced by helicscpp::Endpoint::setDefaultDestination().

◆ helicsEndpointSetInfo()

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
[in,out]	err	An error object to fill out in case of an error.

Referenced by helicscpp::Endpoint::setInfo().

◆ helicsEndpointSetOption()

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.
[in,out]	err	An error object to fill out in case of an error.

◆ helicsEndpointSetTag()

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.
[in,out]	err	An error object to fill out in case of an error.

◆ helicsEndpointSubscribe()

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

◆ helicsFederateClearMessages()

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.

References helics::getFedObject().

◆ helicsFederateCreateMessage()

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.

Parameters

	fed	the federate object to associate the message with
[in,out]	err	An error object to fill out in case of an error.

Returns: A HelicsMessage containing the message data.

References helics::getFedObject().

Referenced by helicscpp::MessageFederate::createMessage(), and helicscpp::Message::newMessageObject().

◆ helicsFederateGetEndpoint()

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

Get an endpoint object from a name.

Parameters

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

Returns: A HelicsEndpoint object.

The object will not be valid and err will contain an error code if no endpoint with the specified name exists.

References HELICS_ERROR_INVALID_ARGUMENT.

Referenced by helicscpp::MessageFederate::getEndpoint().

◆ helicsFederateGetEndpointByIndex()

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.

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 HelicsEndpoint.

The HelicsEndpoint returned will be NULL if given an invalid index.

References HELICS_ERROR_INVALID_ARGUMENT.

Referenced by helicscpp::MessageFederate::getEndpoint().

◆ helicsFederateGetEndpointCount()

int helicsFederateGetEndpointCount ( HelicsFederate fed )

Get the number of endpoints in a federate.

Parameters

fed	The message federate to query.

Returns: (-1) if fed was not a valid federate, otherwise returns the number of endpoints.

Referenced by helicscpp::MessageFederate::getEndpointCount().

◆ helicsFederateGetMessage()

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.

Returns: A HelicsMessage which references the data in the message.

References helics::getFedObject().

Referenced by helicscpp::MessageFederate::getMessage().

◆ helicsFederateHasMessage()

HelicsBool helicsFederateHasMessage ( HelicsFederate fed )

Check if the federate has any outstanding messages.

Parameters

fed	The federate to check.

Returns: HELICS_TRUE if the federate has a message waiting, HELICS_FALSE otherwise.

References HELICS_FALSE, and HELICS_TRUE.

Referenced by helicscpp::MessageFederate::hasMessage().

◆ helicsFederatePendingMessageCount()

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.

Referenced by helicscpp::MessageFederate::pendingMessageCount().

◆ helicsFederateRegisterEndpoint()

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.

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

Returns: An object containing the endpoint, or nullptr on failure.

References helics::getFedObject().

Referenced by helicscpp::MessageFederate::registerEndpoint().

◆ helicsFederateRegisterGlobalEndpoint()

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.

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

Returns: An object containing the endpoint, or nullptr on failure.

References helics::getFedObject().

Referenced by helicscpp::MessageFederate::registerGlobalEndpoint().

◆ helicsFederateRegisterGlobalTargetedEndpoint()

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.

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

Returns: An object containing the endpoint, or nullptr on failure.

References helics::getFedObject().

◆ helicsFederateRegisterTargetedEndpoint()

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.

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

Returns: An object containing the endpoint, or nullptr on failure.

References helics::getFedObject().