helics  2.8.1
Functions
MessageFederate.h File Reference

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

#include "helics.h"

Go to the source code of this file.

Functions

helics_endpoint helicsFederateRegisterEndpoint (helics_federate fed, const char *name, const char *type, helics_error *err)
 
helics_endpoint helicsFederateRegisterGlobalEndpoint (helics_federate fed, const char *name, const char *type, helics_error *err)
 
helics_endpoint helicsFederateGetEndpoint (helics_federate fed, const char *name, helics_error *err)
 
helics_endpoint helicsFederateGetEndpointByIndex (helics_federate fed, int index, helics_error *err)
 
helics_bool helicsEndpointIsValid (helics_endpoint endpoint)
 
void helicsEndpointSetDefaultDestination (helics_endpoint endpoint, const char *dst, helics_error *err)
 
const char * helicsEndpointGetDefaultDestination (helics_endpoint endpoint)
 
void helicsEndpointSendMessageRaw (helics_endpoint endpoint, const char *dst, const void *data, int inputDataLength, helics_error *err)
 
void helicsEndpointSendEventRaw (helics_endpoint endpoint, const char *dst, const void *data, int inputDataLength, helics_time time, helics_error *err)
 
HELICS_DEPRECATED_EXPORT void helicsEndpointSendMessage (helics_endpoint endpoint, helics_message *message, helics_error *err)
 
void helicsEndpointSendMessageObject (helics_endpoint endpoint, helics_message_object message, helics_error *err)
 
void helicsEndpointSendMessageObjectZeroCopy (helics_endpoint endpoint, helics_message_object message, helics_error *err)
 
void helicsEndpointSubscribe (helics_endpoint endpoint, const char *key, helics_error *err)
 
helics_bool helicsFederateHasMessage (helics_federate fed)
 
helics_bool helicsEndpointHasMessage (helics_endpoint endpoint)
 
HELICS_DEPRECATED_EXPORT int helicsFederatePendingMessages (helics_federate fed)
 
int helicsFederatePendingMessageCount (helics_federate fed)
 
HELICS_DEPRECATED_EXPORT int helicsEndpointPendingMessages (helics_endpoint endpoint)
 
int helicsEndpointPendingMessageCount (helics_endpoint endpoint)
 
HELICS_DEPRECATED_EXPORT helics_message helicsEndpointGetMessage (helics_endpoint endpoint)
 
helics_message_object helicsEndpointGetMessageObject (helics_endpoint endpoint)
 
helics_message_object helicsEndpointCreateMessageObject (helics_endpoint endpoint, helics_error *err)
 
HELICS_DEPRECATED_EXPORT helics_message helicsFederateGetMessage (helics_federate fed)
 
helics_message_object helicsFederateGetMessageObject (helics_federate fed)
 
helics_message_object helicsFederateCreateMessageObject (helics_federate fed, helics_error *err)
 
void helicsFederateClearMessages (helics_federate fed)
 
HELICS_DEPRECATED_EXPORT void helicsEndpointClearMessages (helics_endpoint endpoint)
 
const char * helicsEndpointGetType (helics_endpoint endpoint)
 
const char * helicsEndpointGetName (helics_endpoint endpoint)
 
int helicsFederateGetEndpointCount (helics_federate fed)
 
const char * helicsEndpointGetInfo (helics_endpoint end)
 
void helicsEndpointSetInfo (helics_endpoint endpoint, const char *info, helics_error *err)
 
void helicsEndpointSetOption (helics_endpoint endpoint, int option, int value, helics_error *err)
 
int helicsEndpointGetOption (helics_endpoint endpoint, int option)
 
const char * helicsMessageGetSource (helics_message_object message)
 
const char * helicsMessageGetDestination (helics_message_object message)
 
const char * helicsMessageGetOriginalSource (helics_message_object message)
 
const char * helicsMessageGetOriginalDestination (helics_message_object message)
 
helics_time helicsMessageGetTime (helics_message_object message)
 
const char * helicsMessageGetString (helics_message_object message)
 
int helicsMessageGetMessageID (helics_message_object message)
 
helics_bool helicsMessageCheckFlag (helics_message_object message, int flag)
 
int helicsMessageGetRawDataSize (helics_message_object message)
 
void helicsMessageGetRawData (helics_message_object message, void *data, int maxMessageLength, int *actualSize, helics_error *err)
 
void * helicsMessageGetRawDataPointer (helics_message_object message)
 
helics_bool helicsMessageIsValid (helics_message_object message)
 
void helicsMessageSetSource (helics_message_object message, const char *src, helics_error *err)
 
void helicsMessageSetDestination (helics_message_object message, const char *dst, helics_error *err)
 
void helicsMessageSetOriginalSource (helics_message_object message, const char *src, helics_error *err)
 
void helicsMessageSetOriginalDestination (helics_message_object message, const char *dst, helics_error *err)
 
void helicsMessageSetTime (helics_message_object message, helics_time time, helics_error *err)
 
void helicsMessageResize (helics_message_object message, int newSize, helics_error *err)
 
void helicsMessageReserve (helics_message_object message, int reserveSize, helics_error *err)
 
void helicsMessageSetMessageID (helics_message_object message, int32_t messageID, helics_error *err)
 
void helicsMessageClearFlags (helics_message_object message)
 
void helicsMessageSetFlagOption (helics_message_object message, int flag, helics_bool flagValue, helics_error *err)
 
void helicsMessageSetString (helics_message_object message, const char *str, helics_error *err)
 
void helicsMessageSetData (helics_message_object message, const void *data, int inputDataLength, helics_error *err)
 
void helicsMessageAppendData (helics_message_object message, const void *data, int inputDataLength, helics_error *err)
 
void helicsMessageCopy (helics_message_object src_message, helics_message_object dst_message, helics_error *err)
 
helics_message_object helicsMessageClone (helics_message_object message, helics_error *err)
 
void helicsMessageFree (helics_message_object message)
 
void helicsMessageClear (helics_message_object message, helics_error *err)
 

Detailed Description

Functions related to message federates for the C api.

Function Documentation

◆ helicsEndpointClearMessages()

HELICS_DEPRECATED_EXPORT void helicsEndpointClearMessages ( helics_endpoint  endpoint)

Clear all message from an endpoint.

Deprecated:
This function does nothing and will be removed. Use helicsFederateClearMessages to free all messages, or helicsMessageFree to clear an individual message.
Parameters
endpointThe endpoint object to operate on.

◆ helicsEndpointCreateMessageObject()

helics_message_object helicsEndpointCreateMessageObject ( helics_endpoint  endpoint,
helics_error 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
endpointThe endpoint object to associate the message with. @forcpponly
[in,out]errAn error object to fill out in case of an error. @endforcpponly
Returns
A new helics_message_object.

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

◆ helicsEndpointGetDefaultDestination()

const char* helicsEndpointGetDefaultDestination ( helics_endpoint  endpoint)

Get the default destination for an endpoint.

Parameters
endpointThe endpoint to set the destination for.
Returns
A string with the default destination.

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

◆ helicsEndpointGetInfo()

const char* helicsEndpointGetInfo ( helics_endpoint  end)

Get the data in the info field of a filter.

Parameters
endThe filter to query.
Returns
A string with the info field string.

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

◆ helicsEndpointGetMessage()

HELICS_DEPRECATED_EXPORT helics_message helicsEndpointGetMessage ( helics_endpoint  endpoint)

Receive a packet from a particular endpoint.

Deprecated:
This function is deprecated and will be removed in Helics 3.0. Use helicsEndpointGetMessageObject instead.
Parameters
[in]endpointThe identifier for the endpoint.
Returns
A message object.

◆ helicsEndpointGetMessageObject()

helics_message_object helicsEndpointGetMessageObject ( helics_endpoint  endpoint)

Receive a packet from a particular endpoint.

Parameters
[in]endpointThe identifier for the endpoint.
Returns
A message object.

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

◆ helicsEndpointGetName()

const char* helicsEndpointGetName ( helics_endpoint  endpoint)

Get the name of an endpoint.

Parameters
endpointThe endpoint object in question.
Returns
The name of the endpoint.

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

◆ helicsEndpointGetOption()

int helicsEndpointGetOption ( helics_endpoint  endpoint,
int  option 
)

Set a handle option on an endpoint.

Parameters
endpointThe endpoint to modify.
optionInteger code for the option to set /ref helics_handle_options.
Returns
the value of the option, for boolean options will be 0 or 1

◆ helicsEndpointGetType()

const char* helicsEndpointGetType ( helics_endpoint  endpoint)

Get the type specified for an endpoint.

Parameters
endpointThe endpoint object in question.
Returns
The defined type of the endpoint.

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

◆ helicsEndpointHasMessage()

helics_bool helicsEndpointHasMessage ( helics_endpoint  endpoint)

Check if a given endpoint has any unread messages.

Parameters
endpointThe endpoint to check.
Returns
helics_true if the endpoint has a message, helics_false otherwise.

◆ helicsEndpointIsValid()

helics_bool helicsEndpointIsValid ( helics_endpoint  endpoint)

Check if an endpoint is valid.

Parameters
endpointThe endpoint object to check.
Returns
helics_true if the Endpoint object represents a valid endpoint.

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

◆ helicsEndpointPendingMessageCount()

int helicsEndpointPendingMessageCount ( helics_endpoint  endpoint)

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

Parameters
endpointThe endpoint to query.

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

◆ helicsEndpointPendingMessages()

HELICS_DEPRECATED_EXPORT int helicsEndpointPendingMessages ( helics_endpoint  endpoint)

Deprecated, please use helicsEndpointPendingMessageCount instead. Returns the number of pending receives for all endpoints of a particular federate.

Parameters
endpointThe endpoint to query.

◆ helicsEndpointSendEventRaw()

void helicsEndpointSendEventRaw ( helics_endpoint  endpoint,
const char *  dst,
const void *  data,
int  inputDataLength,
helics_time  time,
helics_error err 
)

Send a message at a specific time to the specified destination.

Parameters
endpointThe endpoint to send the data from.
dstThe target destination. @forcpponly nullptr to use the default destination. @endforcpponly @beginpythononly "" to use the default destination. @endpythononly
dataThe data to send. @forcpponly
inputDataLengthThe length of the data to send. @endforcpponly
timeThe time the message should be sent. @forcpponly
[in,out]errA pointer to an error object for catching errors. @endforcpponly

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

◆ helicsEndpointSendMessage()

HELICS_DEPRECATED_EXPORT void helicsEndpointSendMessage ( helics_endpoint  endpoint,
helics_message message,
helics_error err 
)

Send a message object from a specific endpoint.

Deprecated:
Use helicsEndpointSendMessageObject instead.
Parameters
endpointThe endpoint to send the data from.
messageThe actual message to send. @forcpponly
[in,out]errA pointer to an error object for catching errors. @endforcpponly

◆ helicsEndpointSendMessageObject()

void helicsEndpointSendMessageObject ( helics_endpoint  endpoint,
helics_message_object  message,
helics_error err 
)

Send a message object from a specific endpoint.

Parameters
endpointThe endpoint to send the data from.
messageThe actual message to send which will be copied. @forcpponly
[in,out]errA pointer to an error object for catching errors. @endforcpponly

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

◆ helicsEndpointSendMessageObjectZeroCopy()

void helicsEndpointSendMessageObjectZeroCopy ( helics_endpoint  endpoint,
helics_message_object  message,
helics_error 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
endpointThe endpoint to send the data from.
messageThe actual message to send which will be copied. @forcpponly
[in,out]errA pointer to an error object for catching errors. @endforcpponly

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

◆ helicsEndpointSendMessageRaw()

void helicsEndpointSendMessageRaw ( helics_endpoint  endpoint,
const char *  dst,
const void *  data,
int  inputDataLength,
helics_error err 
)

Send a message to the specified destination.

Parameters
endpointThe endpoint to send the data from.
dstThe target destination. @forcpponly nullptr to use the default destination. @endforcpponly @beginpythononly "" to use the default destination. @endpythononly
dataThe data to send. @forcpponly
inputDataLengthThe length of the data to send.
[in,out]errA pointer to an error object for catching errors. @endforcpponly

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

◆ helicsEndpointSetDefaultDestination()

void helicsEndpointSetDefaultDestination ( helics_endpoint  endpoint,
const char *  dst,
helics_error err 
)

Set the default destination for an endpoint if no other endpoint is given.

Parameters
endpointThe endpoint to set the destination for.
dstA string naming the desired default endpoint. @forcpponly
[in,out]errA pointer to an error object for catching errors. @endforcpponly

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

◆ helicsEndpointSetInfo()

void helicsEndpointSetInfo ( helics_endpoint  endpoint,
const char *  info,
helics_error err 
)

Set the data in the info field for a filter.

Parameters
endpointThe endpoint to query.
infoThe string to set. @forcpponly
[in,out]errAn error object to fill out in case of an error. @endforcpponly

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

◆ helicsEndpointSetOption()

void helicsEndpointSetOption ( helics_endpoint  endpoint,
int  option,
int  value,
helics_error err 
)

Set a handle option on an endpoint.

Parameters
endpointThe endpoint to modify.
optionInteger code for the option to set /ref helics_handle_options.
valueThe value to set the option to. @forcpponly
[in,out]errAn error object to fill out in case of an error. @endforcpponly

◆ helicsEndpointSubscribe()

void helicsEndpointSubscribe ( helics_endpoint  endpoint,
const char *  key,
helics_error err 
)

Subscribe an endpoint to a publication.

Parameters
endpointThe endpoint to use.
keyThe name of the publication. @forcpponly
[in,out]errA pointer to an error object for catching errors. @endforcpponly

◆ helicsFederateClearMessages()

void helicsFederateClearMessages ( helics_federate  fed)

Clear all stored messages from a federate.

This clears messages retrieved through helicsFederateGetMessage or helicsFederateGetMessageObject

Parameters
fedThe federate to clear the message for.

◆ helicsFederateCreateMessageObject()

helics_message_object helicsFederateCreateMessageObject ( helics_federate  fed,
helics_error 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
fedthe federate object to associate the message with @forcpponly
[in,out]errAn error object to fill out in case of an error. @endforcpponly
Returns
A helics_message_object containing the message data.

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

◆ helicsFederateGetEndpoint()

helics_endpoint helicsFederateGetEndpoint ( helics_federate  fed,
const char *  name,
helics_error err 
)

Get an endpoint object from a name.

Parameters
fedThe message federate object to use to get the endpoint.
nameThe name of the endpoint. @forcpponly
[in,out]errThe error object to complete if there is an error. @endforcpponly
Returns
A helics_endpoint object. @forcpponly The object will not be valid and err will contain an error code if no endpoint with the specified name exists. @endforcpponly

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

◆ helicsFederateGetEndpointByIndex()

helics_endpoint helicsFederateGetEndpointByIndex ( helics_federate  fed,
int  index,
helics_error err 
)

Get an endpoint by its index, typically already created via registerInterfaces file or something of that nature.

Parameters
fedThe federate object in which to create a publication.
indexThe index of the publication to get. @forcpponly
[in,out]errA pointer to an error object for catching errors. @endforcpponly
Returns
A helics_endpoint. @forcpponly It will be NULL if given an invalid index. @endforcpponly

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

◆ helicsFederateGetEndpointCount()

int helicsFederateGetEndpointCount ( helics_federate  fed)

Get the number of endpoints in a federate.

Parameters
fedThe 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()

HELICS_DEPRECATED_EXPORT helics_message helicsFederateGetMessage ( helics_federate  fed)

Receive a communication message for any endpoint in the federate.

Deprecated:
This function is deprecated and will be removed in Helics 3.0. Use helicsFederateGetMessageObject instead.

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 unique_ptr to a Message object containing the message data.

◆ helicsFederateGetMessageObject()

helics_message_object helicsFederateGetMessageObject ( helics_federate  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 helics_message_object which references the data in the message.

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

◆ helicsFederateHasMessage()

helics_bool helicsFederateHasMessage ( helics_federate  fed)

Check if the federate has any outstanding messages.

Parameters
fedThe federate to check.
Returns
helics_true if the federate has a message waiting, helics_false otherwise.

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

◆ helicsFederatePendingMessageCount()

int helicsFederatePendingMessageCount ( helics_federate  fed)

Returns the number of pending receives for the specified destination endpoint.

Parameters
fedThe federate to get the number of waiting messages from.

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

◆ helicsFederatePendingMessages()

HELICS_DEPRECATED_EXPORT int helicsFederatePendingMessages ( helics_federate  fed)

Deprecated, please use helicsFederatePendingMessageCount instead. Returns the number of pending receives for the specified destination endpoint.

Parameters
fedThe federate to get the number of waiting messages from.

◆ helicsFederateRegisterEndpoint()

helics_endpoint helicsFederateRegisterEndpoint ( helics_federate  fed,
const char *  name,
const char *  type,
helics_error 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
fedThe federate object in which to create an endpoint must have been created with helicsCreateMessageFederate or helicsCreateCombinationFederate.
nameThe identifier for the endpoint. This will be prepended with the federate name for the global identifier.
typeA string describing the expected type of the publication (may be NULL). @forcpponly
[in,out]errA pointer to an error object for catching errors. @endforcpponly
Returns
An object containing the endpoint. @forcpponly nullptr on failure. @endforcpponly

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

◆ helicsFederateRegisterGlobalEndpoint()

helics_endpoint helicsFederateRegisterGlobalEndpoint ( helics_federate  fed,
const char *  name,
const char *  type,
helics_error 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
fedThe federate object in which to create an endpoint must have been created with helicsCreateMessageFederate or helicsCreateCombinationFederate.
nameThe identifier for the endpoint, the given name is the global identifier.
typeA string describing the expected type of the publication (may be NULL). @forcpponly
[in,out]errA pointer to an error object for catching errors. @endforcpponly
Returns
An object containing the endpoint. @forcpponly nullptr on failure. @endforcpponly

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