| helics 3.6.1

Functions
operation functions

## Functions
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 for working with helics message envelopes.

## Function Documentation

## ◆ helicsMessageAppendData()

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

Append data to the payload.

Parameters

  | message | The message object in question.
  | data | A string containing the message data to append.
  | inputDataLength | The length of the data to input.
  [in,out] | err | An error object to fill out in case of an error.

Referenced by helicscpp::Message::append().

## ◆ helicsMessageClear()

void helicsMessageClear | ( | HelicsMessage | message,
|  | HelicsError * | err
| ) |  |

Reset a message to empty state

Parameters

  message | The message object to copy from.

The message after this function will be empty, with no source or destination

Parameters

  [in,out] | err | An error object to fill out in case of an error.

## ◆ helicsMessageClearFlags()

void helicsMessageClearFlags | ( | HelicsMessage | message | ) |

Clear the flags of a message.

Parameters

  message | The message object in question

## ◆ helicsMessageClone()

HelicsMessage helicsMessageClone | ( | HelicsMessage | message,
|  | HelicsError * | err
| ) |  |

Clone a message object.

Parameters

  | message | The message object to copy from.
  [in,out] | err | An error object to fill out in case of an error.

References HELICS_ERROR_INVALID_ARGUMENT.

Referenced by helicscpp::Message::operator=().

## ◆ helicsMessageCopy()

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

Copy a message object.

Parameters

  | src_message | The message object to copy from.
  | dst_message | The message object to copy to.
  [in,out] | err | An error object to fill out in case of an error.

## ◆ helicsMessageDataBuffer()

HelicsDataBuffer helicsMessageDataBuffer | ( | HelicsMessage | message,
|  | HelicsError * | err
| ) |  |

Get a data buffer to the message object

Parameters

  message | A message object to get the dataBuffer for

Returns
  A HelicsDataBuffer object to the data in a message. Modifying the buffer will directly modify the message contents.

Referenced by helicscpp::Message::dataBuffer().

## ◆ helicsMessageFree()

void helicsMessageFree | ( | HelicsMessage | message | ) |

Free a message object from memory

Parameters

  message | The message object to copy from.

memory for message is managed so not using this function does not create memory leaks, this is an indication to the system that the memory for this message is done being used and can be reused for a new message. helicsFederateClearMessages() can also be used to clear up all stored messages at once

Referenced by helicscpp::Message::newMessageObject(), helicscpp::Message::operator=(), and helicscpp::Message::~Message().

## ◆ helicsMessageGetByteCount()

int helicsMessageGetByteCount | ( | HelicsMessage | message | ) |

Get the size of the data payload in bytes.

Parameters

  message | The message object in question.

Returns
  The size of the data payload.

Referenced by helicscpp::Message::size().

## ◆ helicsMessageGetBytes()

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

Get the raw data for a message object.

Parameters

  | message | A message object to get the data for.
  [out] | data | The memory location of the data.
  | maxMessageLength | The maximum size of information that data can hold.
  [out] | actualSize | The actual length of data copied to data.
  [in,out] | err | A pointer to an error object for catching errors.

References HELICS_ERROR_INSUFFICIENT_SPACE.

## ◆ helicsMessageGetBytesPointer()

void* helicsMessageGetBytesPointer | ( | HelicsMessage | message | ) |

Get a pointer to the raw data of a message.

Parameters

  message | A message object to get the data for.

Returns
  A pointer to the raw data in memory, the pointer may be NULL if the message is not a valid message.

Referenced by helicscpp::Message::data().

## ◆ helicsMessageGetDestination()

const char* helicsMessageGetDestination | ( | HelicsMessage | message | ) |

Get the destination endpoint of a message.

Parameters

  message | The message object in question.

Returns
  A string with the destination endpoint.

Referenced by helicscpp::Message::destination().

## ◆ helicsMessageGetFlagOption()

HelicsBool helicsMessageGetFlagOption | ( | HelicsMessage | message,
|  | int | flag
| ) |  |

Check if a flag is set on a message.

Parameters

  message | The message object in question.
  flag | The flag to check should be between [0,15].

Returns
  The flags associated with a message.

References helics::checkActionFlag(), HELICS_FALSE, and HELICS_TRUE.

Referenced by helicscpp::Message::getFlagOption().

## ◆ helicsMessageGetMessageID()

int helicsMessageGetMessageID | ( | HelicsMessage | message | ) |

Get the messageID of a message.

Parameters

  message | The message object in question.

Returns
  The messageID.

Referenced by helicscpp::Message::messageID().

## ◆ helicsMessageGetOriginalDestination()

const char* helicsMessageGetOriginalDestination | ( | HelicsMessage | message | ) |

Get the original destination endpoint of a message, the destination may have been modified by filters or other actions.

Parameters

  message | The message object in question.

Returns
  A string with the original destination of a message.

Referenced by helicscpp::Message::originalDestination().

## ◆ helicsMessageGetOriginalSource()

const char* helicsMessageGetOriginalSource | ( | HelicsMessage | message | ) |

Get the original source endpoint of a message, the source may have been modified by filters or other actions.

Parameters

  message | The message object in question.

Returns
  A string with the source of a message.

Referenced by helicscpp::Message::originalSource().

## ◆ helicsMessageGetSource()

const char* helicsMessageGetSource | ( | HelicsMessage | message | ) |

Get the source endpoint of a message.

Parameters

  message | The message object in question.

Returns
  A string with the source endpoint.

Referenced by helicscpp::Message::source().

## ◆ helicsMessageGetString()

const char* helicsMessageGetString | ( | HelicsMessage | message | ) |

Get the payload of a message as a string.

Parameters

  message | The message object in question.

Returns
  A string representing the payload of a message.

Referenced by helicscpp::Message::c_str().

## ◆ helicsMessageGetTime()

HelicsTime helicsMessageGetTime | ( | HelicsMessage | message | ) |

Get the helics time associated with a message.

Parameters

  message | The message object in question.

Returns
  The time associated with a message.

References HELICS_TIME_INVALID.

Referenced by helicscpp::Message::time().

## ◆ helicsMessageIsValid()

HelicsBool helicsMessageIsValid | ( | HelicsMessage | message | ) |

A check if the message contains a valid payload.

Parameters

  message | The message object in question.

Returns
  HELICS_TRUE if the message contains a payload.

References HELICS_FALSE, and HELICS_TRUE.

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

## ◆ helicsMessageReserve()

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

Reserve space in a buffer but don't actually resize.

The message data buffer will be reserved but not resized.

Parameters

  | message | The message object in question.
  | reserveSize | The number of bytes to reserve in the message object.
  [in,out] | err | An error object to fill out in case of an error.

Referenced by helicscpp::Message::reserve().

## ◆ helicsMessageResize()

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

Resize the data buffer for a message.

The message data buffer will be resized. There are no guarantees on what is in the buffer in newly allocated space. If the allocated space is not sufficient new allocations will occur.

Parameters

  | message | The message object in question.
  | newSize | The new size in bytes of the buffer.
  [in,out] | err | An error object to fill out in case of an error.

Referenced by helicscpp::Message::resize().

## ◆ helicsMessageSetData()

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

Set the data payload of a message as raw data.

Parameters

  | message | The message object in question.
  | data | A string containing the message data.
  | inputDataLength | The length of the data to input.
  [in,out] | err | An error object to fill out in case of an error.

Referenced by helicscpp::Message::data().

## ◆ helicsMessageSetDataBuffer()

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

Set the data payload of a message from a HelicsDataBuffer Object

Parameters

  | message | The message object in question.
  | data | the dataBuffer containing the appropriate data, if null will clear the message payload
  [in,out] | err | An error object to fill out in case of an error.

Referenced by helicscpp::Message::data().

## ◆ helicsMessageSetDestination()

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

Set the destination of a message.

Parameters

  | message | The message object in question.
  | dst | A string containing the new destination.
  [in,out] | err | An error object to fill out in case of an error.

Referenced by helicscpp::Message::destination().

## ◆ helicsMessageSetFlagOption()

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

Set a flag on a message.

Parameters

  | message | The message object in question.
  | flag | An index of a flag to set on the message.
  | flagValue | The desired value of the flag.
  [in,out] | err | An error object to fill out in case of an error.

References helics::clearActionFlag(), HELICS_ERROR_INVALID_ARGUMENT, HELICS_TRUE, and helics::setActionFlag().

Referenced by helicscpp::Message::setFlag().

## ◆ helicsMessageSetMessageID()

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

Set the message ID for the message.

Normally this is not needed and the core of HELICS will adjust as needed.

Parameters

  | message | The message object in question.
  | messageID | A new message ID.
  [in,out] | err | An error object to fill out in case of an error.

Referenced by helicscpp::Message::messageID().

## ◆ helicsMessageSetOriginalDestination()

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

Set the original destination of a message.

Parameters

  | message | The message object in question.
  | dst | A string containing the new original source.
  [in,out] | err | An error object to fill out in case of an error.

Referenced by helicscpp::Message::originalDestination().

## ◆ helicsMessageSetOriginalSource()

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

Set the original source of a message.

Parameters

  | message | The message object in question.
  | src | A string containing the new original source.
  [in,out] | err | An error object to fill out in case of an error.

Referenced by helicscpp::Message::originalSource().

## ◆ helicsMessageSetSource()

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

Set the source of a message.

Parameters

  | message | The message object in question.
  | src | A string containing the source.
  [in,out] | err | An error object to fill out in case of an error.

Referenced by helicscpp::Message::source().

## ◆ helicsMessageSetString()

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

Set the data payload of a message as a string.

Parameters

  | message | The message object in question.
  | data | A null terminated string containing the message data.
  [in,out] | err | An error object to fill out in case of an error.

Referenced by helicscpp::Message::data().

## ◆ helicsMessageSetTime()

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

Set the delivery time for a message.

Parameters

  | message | The message object in question.
  | time | The time the message should be delivered.
  [in,out] | err | An error object to fill out in case of an error.

Referenced by helicscpp::Message::time().