Tannhäuser API: PdMessage

Tannhauser_tann.h

#pragma mark - Tannhäuser Message
 
#ifndef _TANNHAUSER_MESSAGE_H_
#define _TANNHAUSER_MESSAGE_H_
 
#include <stdbool.h>
 
typedef struct PdMessage PdMessage;

/** Returns the byte size of a PdMessage with a number of elements on the heap. */
size_t th_msg_getByteSize(int numElements);

/** Initialise a message with the number of elements and a timestamp (in milliseconds). */
void th_msg_init(PdMessage *m, int numElements, double timestamp);
 
/** Returns the number of elements in this message. */
int th_msg_getNumElements(PdMessage *m);
 
/** Returns the time at which this message exists (in milliseconds). */
double th_msg_getTimestamp(PdMessage *m);
 
/** Set the time at which this message should be executed (in milliseconds). */
void th_msg_setTimestamp(PdMessage *m, double timestamp);
 
/** Returns true of the indexed element is a bang. False otherwise. Index is not bounds checked. */
bool th_msg_isBang(PdMessage *m, int i);
 
/** Sets the indexed element to a bang. Index is not bounds checked. */
void th_msg_setBang(PdMessage *m, int i);
 
/** Returns true of the indexed element is a float. False otherwise. Index is not bounds checked. */
bool th_msg_isFloat(PdMessage *m, int i);
 
/** Returns the indexed element as a float value. Index is not bounds checked. */
float th_msg_getFloat(PdMessage *m, int i);
 
/** Sets the indexed element to float value. Index is not bounds checked. */
void th_msg_setFloat(PdMessage *m, int i, float f);
 
/** Returns true of the indexed element is a symbol. False otherwise. Index is not bounds checked. */
bool th_msg_isSymbol(PdMessage *m, int i);
 
/** Returns the indexed element as a symbol value. Index is not bounds checked. */
char *th_msg_getSymbol(PdMessage *m, int i);
 
/** Sets the indexed element to symbol value. Index is not bounds checked. */
void th_msg_setSymbol(PdMessage *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 th_msg_hasFormat(PdMessage *m, const char *fmt);
 
/**
 * Returns a basic string representation of the message.
 * The character array MUST be deallocated by the caller.
 */
char *th_msg_toString(PdMessage *msg);
 
/** Copy a message onto the stack. The message persists. */
PdMessage *th_msg_copy(PdMessage *m);
 
/** Free a copied message. */
void th_msg_free(PdMessage *m);
 
#endif // _TANNHAUSER_PDMESSAGE_H_