Message specific Heavy API methods

heavy_api_messages.c

/** Returns the byte size of a HvMessage with a number of elements on the heap. */
hv_size_t hv_msg_getByteSize(int numElements);

/** Create a HvMessage on the stack with a number of elements. This message does MUST NOT be freed. */
HvMessage *hv_msg_onStack(hv_uint32_t numElements) {
  return (HvMessage *) hv_alloca(hv_msg_getByteSize(numElements)); // this will not work until Utils.h is included
}

/** Initialise a message with the number of elements and a timestamp (in milliseconds). */
void hv_msg_init(HvMessage *m, int numElements, double timestamp);

/** Returns the number of elements in this message. */
int hv_msg_getNumElements(HvMessage *m);

/** Returns the time at which this message exists (in milliseconds). */
hv_uint32_t hv_msg_getTimestamp(HvMessage *m);

/** Set the time at which this message should be executed (in milliseconds). */
void hv_msg_setTimestamp(HvMessage *m, double timestamp);

/** Returns true of the indexed element is a bang. False otherwise. Index is not bounds checked. */
bool hv_msg_isBang(HvMessage *m, int i);

/** Sets the indexed element to a bang. Index is not bounds checked. */
void hv_msg_setBang(HvMessage *m, int i);

/** Returns true of the indexed element is a float. False otherwise. Index is not bounds checked. */
bool hv_msg_isFloat(HvMessage *m, int i);

/** Returns the indexed element as a float value. Index is not bounds checked. */
float hv_msg_getFloat(HvMessage *m, int i);

/** Sets the indexed element to float value. Index is not bounds checked. */
void hv_msg_setFloat(HvMessage *m, int i, float f);

/** Returns true of the indexed element is a symbol. False otherwise. Index is not bounds checked. */
bool hv_msg_isSymbol(HvMessage *m, int i);

/** Returns the indexed element as a symbol value. Index is not bounds checked. */
char *hv_msg_getSymbol(HvMessage *m, int i);

/** Sets the indexed element to symbol value. Index is not bounds checked. */
void hv_msg_setSymbol(HvMessage *m, int i, const char *s);

/**
 * Returns true if the message has the given format, in number of elements and type. False otherwise.
 * Valid element types are:
 * 'b': bang
 * 'f': float
 * 's': symbol
 *
 * For example, a message with three floats would have a format of "fff". A single bang is "b".
 * A message with two symbols is "ss". These types can be mixed and matched in any way.
 */
bool hv_msg_hasFormat(HvMessage *m, const char *fmt);

/**
 * Returns a basic string representation of the message.
 * The character array MUST be deallocated by the caller.
 */
char *hv_msg_toString(HvMessage *msg);

/** Copy a message onto the stack. The message persists. */
HvMessage *hv_msg_copy(HvMessage *m);

/** Free a copied message. */
void hv_msg_free(HvMessage *m);