NeoStats/include/MiniMessage.h

/* NeoStats - IRC Statistical Services
** Copyright (c) 1999-2008 Adam Rutter, Justin Hammond, Mark Hetherington
** http://www.neostats.net/
**
**  Portions Copyright (c) 2000 - 2001 ^Enigma^
**
**  This program is free software; you can redistribute it and/or modify
**  it under the terms of the GNU General Public License as published by
**  the Free Software Foundation; either version 2 of the License, or
**  (at your option) any later version.
**
**  This program is distributed in the hope that it will be useful,
**  but WITHOUT ANY WARRANTY; without even the implied warranty of
**  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
**  GNU General Public License for more details.
**
**  You should have received a copy of the GNU General Public License
**  along with this program; if not, write to the Free Software
**  Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307
**  USA
**
** NeoStats CVS Identification
** $Id$
*/


#ifndef MiniMessage_h
#define MiniMessage_h

#include "MuscleSupport.h"

#ifdef __cplusplus
extern "C" {
#endif

/* My own little boolean type, since C doesn't come with one built in. */
typedef char MBool;
enum {MFalse = 0, MTrue};  /* and boolean values to go in it */

/* This file contains a C API for a "minimalist" implementation of the MUSCLE  */
/* Message dictionary object.  This implementation sacrifices a certain amount */
/* of flexibility and convenience in exchange for a very lightweight           */
/* and efficient implementation.                                               */

/** Definition of our Point class -- two floats */
struct _MPoint {
   float x;
   float y;
};
typedef struct _MPoint MPoint;

/** Definition of our Rect class -- four floats */
struct _MRect {
   float left;
   float top;
   float right;
   float bottom;
};
typedef struct _MRect MRect;

/** Definition of our opaque handle to a MMessage object.  Your
  * code doesn't know what a (MMessage *) points to, and it doesn't care,
  * because all operations on it should happen via calls to the functions
  * that are defined below.
  */
struct _MMessage;
typedef struct _MMessage MMessage;

/** This object is used in field name iterations */
struct _MMessageIterator {
   const MMessage * message;
   void * iterState; 
   uint32 typeCode;
};
typedef struct _MMessageIterator MMessageIterator;

/** Definition of our byte-array class, including size value */
struct _MByteBuffer {
   uint32 numBytes;
   uint8 bytes;  /* Note that this is only the first byte; there are usually more after this one */
};
typedef struct _MByteBuffer MByteBuffer;

/** Allocates and initializes a new MByteBuffer with the specified number of bytes, and returns a pointer to it. 
  * @param numBytes How many bytes to allocate in this buffer.
  * @param clearBytes If MTrue, all the data bytes in the returned MByteBuffer will be zero.
  *                   If MFalse, the bytes' values will be undefined (which is a bit more efficient)
  * @returns a newly allocated MByteBuffer with the specified number of bytes, or NULL on failure.  
  *          If non-NULL, it becomes the the responsibility of the calling code to call FreeMByteBuffer() 
  *          on the MByteBuffer when it is done using it. 
  */
MByteBuffer * MBAllocByteBuffer(uint32 numBytes, MBool clearBytes);

/** Allocates and initializes a new MByteBuffer to contain a copy of the specified NUL-terminated string.
  * @param sourceString The string to copy into the newly allocated byte buffer.
  * @returns A newly allocated MByteBuffer containing a copy of the specified string, or NULL on failure.
  *          Note that the returned MByteBuffer's string will be NUL-terminated too.
  */
MByteBuffer * MBStrdupByteBuffer(const char * sourceString);

/** Attempts to create and return a cloned copy of (cloneMe).
  * @param cloneMe The MByteBuffer to create a copy of.  
  * @returns The newly allocated MByteBuffer, or NULL on failure.
  */
MByteBuffer * MBCloneByteBuffer(const MByteBuffer * cloneMe);

/** Returns MTrue iff the two byte buffers are equal (i.e. both hold the same byte sequence)
  * @param buf1 The first byte buffer to compare.
  * @param buf2 The first byte buffer to compare.
  * @returns True if buf1 has the same byte sequence as buf2, otherwise MFalse.
  */
MBool MBAreByteBuffersEqual(const MByteBuffer * buf1, const MByteBuffer * buf2);

/** Frees a previously created MByteBuffer and all the data that it holds.
  * @param msg The MByteBuffer to free.  If NULL, no action will be taken.
  */
void MBFreeByteBuffer(MByteBuffer * msg);

/** Allocates and initializes a new MMessage with the specified what code, and returns a pointer to it. 
  * @param what Initial 'what' code to give to the MMessage.
  * @returns a newly allocated MMessage, or NULL on failure.  If non-NULL, it becomes the
  *          the responsibility of the calling code to call MMFreeMessage() on the MMessage
  *          when it is done using it. 
  */
MMessage * MMAllocMessage(uint32 what);

/** Attempts to create and return a cloned copy of (cloneMe).
  * @param cloneMe The MMessage to create a copy of.  
  * @returns The newly allocated MMessage, or NULL on failure.
  */
MMessage * MMCloneMessage(const MMessage * cloneMe);

/** Frees a previously created MMessage and all the data that it holds.
  * @param msg The MMessage to free.  If NULL, no action will be taken.
  */
void MMFreeMessage(MMessage * msg);

/** Returns the 'what' code associated with the specified MMessage. 
  * @param msg The MMessage to retrieve the 'what' code of.'
  * @returns The MMessage's what code.
  */
uint32 MMGetWhat(const MMessage * msg);

/** Sets the 'what' code associated with the specified MMessage. 
  * @param msg The MMessage to set the 'what' code of'.
  * @param newWhat The new 'what' code to install.  (Typically a B_*_TYPE value)
  */
void MMSetWhat(MMessage * msg, uint32 newWhat);

/** Removes and frees all of the supplied MMessage's field data.  The MMessage itself
  * is not destroyed, however (use MMFreeMessage() to do that)
  * @param msg The MMessage object to remove all data fields from.
  */
void MMClearMessage(MMessage * msg);

/** Attempts to remove and free the specified field from the given MMessage.
  * @param msg the MMessage object to remove the field from
  * @param fieldName Name of the field to remove and free. 
  * @returns B_NO_ERROR if the field was found and removed, or B_ERROR if it wasn't found.
  */
status_t MMRemoveField(MMessage * msg, const char * fieldName);

/** Attempts to create and install a string field with the specified field name into the MMessage.
  * On success, any previously installed field with the same name will be replaced and freed.
  * @param msg The MMessage to install the new field into.
  * @param retainOldData This flag is relevant only if a string field with the same name already exists.
  *                      If MTrue, as many of the old field's data values as possible will be transferred
  *                      to the new field.  Otherwise, all the old field's data will be destroyed and the
  *                      new field will be created with all NULL string values.
  * @param fieldName Field name of the new field.
  * @param numItems Number of items that the new field should contain room for.
  * @returns A pointer to an array of (numItems) MByteBuffer pointers, or NULL if there was an error.
  *          The returned array belongs to the MMessage, and will be freed by it at the proper time.
  *          The MByteBuffer pointers in the array, when non-NULL, are also considered to belong to the
  *          MMessage, and will have MBFreeByteBuffer() called on them when the field is destroyed.  
  *          NOTE: When setting a value in the array, be sure to allocate its memory using MBAllocByteBuffer()
  *                or MBStrdupByteBuffer(), and be sure to call MBFreeByteBuffer() on the old value before
  *                you replace it.
  */
MByteBuffer ** MMPutStringField(MMessage * msg, MBool retainOldData, const char * fieldName, uint32 numItems);

/** Attempts to create and install a boolean field with the specified field name into the MMessage.
  * On success, any previously installed field with the same name will be replaced and freed.
  * @param msg The MMessage to install the new field into.
  * @param retainOldData This flag is relevant only if a boolean field with the same name already exists.
  *                      If MTrue, as many of the old field's data values as possible will be transferred
  *                      to the new field.  Otherwise, all the old field's data will be destroyed and the
  *                      new field will be created with all data values set to MFalse.
  * @param fieldName Field name of the new field.
  * @param numItems Number of items that the new field should contain room for.
  * @returns A pointer to an array of (numItems) booleans, or NULL if there was an error.
  *          The returned array belongs to the MMessage, and will be freed by it at the proper time.
  */
MBool * MMPutBoolField(MMessage * msg, MBool retainOldData, const char * fieldName, uint32 numItems);

/** Attempts to create and install an int8 field with the specified field name into the MMessage.
  * On success, any previously installed field with the same name will be replaced and freed.
  * @param msg The MMessage to install the new field into.
  * @param retainOldData This flag is relevant only if an int8 field with the same name already exists.
  *                      If MTrue, as many of the old field's data values as possible will be transferred
  *                      to the new field.  Otherwise, all the old field's data will be destroyed and the
  *                      new field will be created with all zero data values.
  * @param fieldName Field name of the new field.
  * @param numItems Number of items that the new field should contain room for.
  * @returns A pointer to an array of (numItems) int8s, or NULL if there was an error.
  *          The returned array belongs to the MMessage, and will be freed by it at the proper time.
  */
int8 * MMPutInt8Field(MMessage * msg, MBool retainOldData, const char * fieldName, uint32 numItems);

/** Attempts to create and install an int16 field with the specified field name into the MMessage.
  * On success, any previously installed field with the same name will be replaced and freed.
  * @param msg The MMessage to install the new field into.
  * @param retainOldData This flag is relevant only if an int16 field with the same name already exists.
  *                      If MTrue, as many of the old field's data values as possible will be transferred
  *                      to the new field.  Otherwise, all the old field's data will be destroyed and the
  *                      new field will be created with all zero data values.
  * @param fieldName Field name of the new field.
  * @param numItems Number of items that the new field should contain room for.
  * @returns A pointer to an array of (numItems) int16s, or NULL if there was an error.
  *          The returned array belongs to the MMessage, and will be freed by it at the proper time.
  */
int16 * MMPutInt16Field(MMessage * msg, MBool retainOldData, const char * fieldName, uint32 numItems);

/** Attempts to create and install an int32 field with the specified field name into the MMessage.
  * On success, any previously installed field with the same name will be replaced and freed.
  * @param msg The MMessage to install the new field into.
  * @param retainOldData This flag is relevant only if an int32 field with the same name already exists.
  *                      If MTrue, as many of the old field's data values as possible will be transferred
  *                      to the new field.  Otherwise, all the old field's data will be destroyed and the
  *                      new field will be created with all zero data values.
  * @param fieldName Field name of the new field.
  * @param numItems Number of items that the new field should contain room for.
  * @returns A pointer to an array of (numItems) int32s, or NULL if there was an error.
  *          The returned array belongs to the MMessage, and will be freed by it at the proper time.
  */
int32 * MMPutInt32Field(MMessage * msg, MBool retainOldData, const char * fieldName, uint32 numItems);

/** Attempts to create and install an int64 field with the specified field name into the MMessage.
  * On success, any previously installed field with the same name will be replaced and freed.
  * @param msg The MMessage to install the new field into.
  * @param retainOldData This flag is relevant only if an int64 field with the same name already exists.
  *                      If MTrue, as many of the old field's data values as possible will be transferred
  *                      to the new field.  Otherwise, all the old field's data will be destroyed and the
  *                      new field will be created with all zero data values.
  * @param fieldName Field name of the new field.
  * @param numItems Number of items that the new field should contain room for.
  * @returns A pointer to an array of (numItems) int64s, or NULL if there was an error.
  *          The returned array belongs to the MMessage, and will be freed by it at the proper time.
  */
int64 * MMPutInt64Field(MMessage * msg, MBool retainOldData, const char * fieldName, uint32 numItems);

/** Attempts to create and install a float field with the specified field name into the MMessage.
  * On success, any previously installed field with the same name will be replaced and freed.
  * @param msg The MMessage to install the new field into.
  * @param retainOldData This flag is relevant only if a float field with the same name already exists.
  *                      If MTrue, as many of the old field's data values as possible will be transferred
  *                      to the new field.  Otherwise, all the old field's data will be destroyed and the
  *                      new field will be created with all zero data values.
  * @param fieldName Field name of the new field.
  * @param numItems Number of items that the new field should contain room for.
  * @returns A pointer to an array of (numItems) floats, or NULL if there was an error.
  *          The returned array belongs to the MMessage, and will be freed by it at the proper time.
  */
float * MMPutFloatField(MMessage * msg, MBool retainOldData, const char * fieldName, uint32 numItems);

/** Attempts to create and install a double field with the specified field name into the MMessage.
  * On success, any previously installed field with the same name will be replaced and freed.
  * @param msg The MMessage to install the new field into.
  * @param retainOldData This flag is relevant only if a double field with the same name already exists.
  *                      If MTrue, as many of the old field's data values as possible will be transferred
  *                      to the new field.  Otherwise, all the old field's data will be destroyed and the
  *                      new field will be created with all zero data values.
  * @param fieldName Field name of the new field.
  * @param numItems Number of items that the new field should contain room for.
  * @returns A pointer to an array of (numItems) doubles, or NULL if there was an error.
  *          The returned array belongs to the MMessage, and will be freed by it at the proper time.
  */
double * MMPutDoubleField(MMessage * msg, MBool retainOldData, const char * fieldName, uint32 numItems);

/** Attempts to create and install a Message field with the specified field name into the MMessage.
  * On success, any previously installed field with the same name will be replaced and freed.
  * @param msg The MMessage to install the new field into.
  * @param retainOldData This flag is relevant only if a Message field with the same name already exists.
  *                      If MTrue, as many of the old field's data values as possible will be transferred
  *                      to the new field.  Otherwise, all the old field's data will be destroyed and the
  *                      new field will be created with all NULL data values.
  * @param fieldName Field name of the new field.
  * @param numItems Number of items that the new field should contain room for.
  * @returns A pointer to an array of (numItems) Messages, or NULL if there was an error.
  *          The returned array belongs to the MMessage, and will be freed by it at the proper time.
  *          NOTE:  Any MMessages that this array points to are considered to be owned by the MMessage
  *                 as well, for as long as they are pointed to by the array.  So when setting the array
  *                 values, be sure to follow pointer semantics, such that any new values are allocated
  *                 off the heap, and be sure to call MMFreeMessage() on any values you replace.
  */
MMessage ** MMPutMessageField(MMessage * msg, MBool retainOldData, const char * fieldName, uint32 numItems);

/** Attempts to create and install a pointer field with the specified field name into the MMessage.
  * On success, any previously installed field with the same name will be replaced and freed.
  * @param msg The MMessage to install the new field into.
  * @param retainOldData This flag is relevant only if a pointer field with the same name already exists.
  *                      If MTrue, as many of the old field's data values as possible will be transferred
  *                      to the new field.  Otherwise, all the old field's data will be destroyed and the
  *                      new field will be created with all NULL data values.
  * @param fieldName Field name of the new field.
  * @param numItems Number of items that the new field should contain room for.
  * @returns A pointer to an array of (numItems) pointers, or NULL if there was an error.
  *          The returned array belongs to the MMessage, and will be freed by it at the proper time.
  */
void ** MMPutPointerField(MMessage * msg, MBool retainOldData, const char * fieldName, uint32 numItems);

/** Attempts to create and install a point field with the specified field name into the MMessage.
  * On success, any previously installed field with the same name will be replaced and freed.
  * @param msg The MMessage to install the new field into.
  * @param retainOldData This flag is relevant only if a point field with the same name already exists.
  *                      If MTrue, as many of the old field's data values as possible will be transferred
  *                      to the new field.  Otherwise, all the old field's data will be destroyed and the
  *                      new field will be created with all zero data values.
  * @param fieldName Field name of the new field.
  * @param numItems Number of items that the new field should contain room for.
  * @returns A pointer to an array of (numItems) points, or NULL if there was an error.
  *          The returned array belongs to the MMessage, and will be freed by it at the proper time.
  */
MPoint * MMPutPointField(MMessage * msg, MBool retainOldData, const char * fieldName, uint32 numItems);

/** Attempts to create and install a rect field with the specified field name into the MMessage.
  * On success, any previously installed field with the same name will be replaced and freed.
  * @param msg The MMessage to install the new field into.
  * @param retainOldData This flag is relevant only if a rect field with the same name already exists.
  *                      If MTrue, as many of the old field's data values as possible will be transferred
  *                      to the new field.  Otherwise, all the old field's data will be destroyed and the
  *                      new field will be created with all zero data values.
  * @param fieldName Field name of the new field.
  * @param numItems Number of items that the new field should contain room for.
  * @returns A pointer to an array of (numItems) rects, or NULL if there was an error.
  *          The returned array belongs to the MMessage, and will be freed by it at the proper time.
  */
MRect * MMPutRectField(MMessage * msg, MBool retainOldData, const char * fieldName, uint32 numItems);

/** Attempts to create and install an untyped data field with the specified field name into the MMessage.
  * On success, any previously installed field with the same name will be replaced and freed.
  * @param msg The MMessage to install the new field into.
  * @param retainOldData This flag is relevant only if a data field with the same name already exists.
  *                      If MTrue, as many of the old field's data values as possible will be transferred
  *                      to the new field.  Otherwise, all the old field's data will be destroyed and the
  *                      new field will be created with all NULL string values.
  * @param fieldName Field name of the new field.
  * @param numItems Number of items that the new field should contain room for.
  * @returns A pointer to an array of (numItems) MByteBuffer pointers, or NULL if there was an error.
  *          The returned array belongs to the MMessage, and will be freed by it at the proper time.
  *          The MByteBuffer pointers in the array, when non-NULL, are also considered to belong to the
  *          MMessage, and will have MBFreeByteBuffer() called on them when the field is destroyed.  
  *          NOTE: When setting a value in the array, be sure to allocate its memory using MBAllocByteBuffer()
  *                or MBStrdupByteBuffer(), and be sure to call MBFreeByteBuffer() on the old value before
  *                you replace it.
  */
MByteBuffer ** MMPutDataField(MMessage * msg, MBool retainOldData, uint32 typeCode, const char * fieldName, uint32 numItems);

/** Returns the number of bytes it would take to hold a flattened representation of (msg). 
  * @param msg MMessage to scan to determine its flattened size.
  * @returns Number of bytes the flattened representation would require.
  */
uint32 MMGetFlattenedSize(const MMessage * msg);

/** Flattens the supplied MMessage into a platform-neutral byte buffer that can be sent out over the
  * network or saved to disk and later reassembled back into an equivalent MMessage object by calling
  * MMUnflattenMessage().
  * @param msg MMessage to produce the byte buffer from.
  * @param outBuf Pointer to the output array to write into.  There must be at least
  *               MMGetFlattenedSize(msg) bytes of storage available at this location,
  *               or memory corruption will result.  The output into this buffer will be in
  *               with the standard MUSCLE flattened byte buffer format.
  */
void MMFlattenMessage(const MMessage * msg, void * outBuf);

/** Unflattens the supplied byte buffer into the supplied MMessage object.
  * @param msg MMessage object to set the state of, based on the contents of the flattened byte buffer.
  * @param inBuf Buffer containing the flattened MMessage bytes, as previously created by 
  *              MMFlattenMessage() (or some other code that writes the flattened MUSCLE Message format).
  * @param bufSizeBytes How many valid bytes of data are available at (inBuf).
  * @returns B_NO_ERROR if the restoration was a success, or B_ERROR otherwise (in which case (msg) will
  *                     likely be left in some valid but only partially restored state)
  */
status_t MMUnflattenMessage(MMessage * msg, const void * inBuf, uint32 bufSizeBytes);

/** Moves the specified field from one MMessage to another.
  * @param sourceMessage The MMessage where the field currently resides.
  * @param fieldName Name of the field to move.
  * @param destMsg The MMessage to move the field to.  If a field with this name already exists
  *                inside (destMsg), it will be replaced and freed.  If (destMsg) is NULL, the
  *                field will be removed from the source Message and freed.
  * @returns B_NO_ERROR on success, or B_ERROR on failure.  
  */
status_t MMMoveField(MMessage * sourceMsg, const char * fieldName, MMessage * destMsg);

/** Copies the specified field from one MMessage to another.
  * @param sourceMessage The MMessage where the field currently resides.
  * @param fieldName Name of the field to copy.
  * @param destMsg The MMessage to copy the field to.  If a field with this name already exists
  *                inside (destMsg), it will be replaced and freed.  If (destMsg) is NULL, this
  *                call will have no effect.
  * @returns B_NO_ERROR on success, or B_ERROR on failure.  
  */
status_t MMCopyField(const MMessage * sourceMsg, const char * fieldName, MMessage * destMsg);

/** Change the name of a field within its Message.
  * @param sourceMessage The MMessage where the field currently resides.
  * @param oldFieldName Current name of the field.
  * @param newFieldName Desired new name of the field.  If a field with this name already exists
  *                inside (sourceMsg), it will be replaced and freed.
  * @returns B_NO_ERROR on success, or B_ERROR on failure.  
  */
status_t MMRenameField(MMessage * sourceMsg, const char * oldFieldName, const char * newFieldName);

/** Retrieves the string field with the given name.
  * @param msg The MMessage to look for the field in.
  * @param fieldName Name of the field to look for.
  * @param optRetNumItems If non-NULL, the number of items in the field will be written into the uint32 this points to.
  * @returns A pointer to the array of MByteBuffers that represents the strings on success, or NULL on failure.
  *          Note that the returned array remains under the ownership of the MMessage object.
  */
MByteBuffer ** MMGetStringField(const MMessage * msg, const char * fieldName, uint32 * optRetNumItems);

/** Retrieves the boolean field with the given name.
  * @param msg The MMessage to look for the field in.
  * @param fieldName Name of the field to look for.
  * @param optRetNumItems If non-NULL, the number of items in the field will be written into the uint32 this points to.
  * @returns A pointer to the array of MBool on success, or NULL on failure (field not found).
  *          Note that the returned array remains under the ownership of the MMessage object.
  */
MBool * MMGetBoolField(const MMessage * msg, const char * fieldName, uint32 * optRetNumItems);

/** Retrieves the int8 field with the given name.
  * @param msg The MMessage to look for the field in.
  * @param fieldName Name of the field to look for.
  * @param optRetNumItems If non-NULL, the number of items in the field will be written into the uint32 this points to.
  * @returns A pointer to the array of int8s on success, or NULL on failure (field not found).
  *          Note that the returned array remains under the ownership of the MMessage object.
  */
int8 * MMGetInt8Field(const MMessage * msg, const char * fieldName, uint32 * optRetNumItems);

/** Retrieves the int16 field with the given name.
  * @param msg The MMessage to look for the field in.
  * @param fieldName Name of the field to look for.
  * @param optRetNumItems If non-NULL, the number of items in the field will be written into the uint32 this points to.
  * @returns A pointer to the array of int16s on success, or NULL on failure (field not found).
  *          Note that the returned array remains under the ownership of the MMessage object.
  */
int16 * MMGetInt16Field(const MMessage * msg, const char * fieldName, uint32 * optRetNumItems);

/** Retrieves the int32 field with the given name.
  * @param msg The MMessage to look for the field in.
  * @param fieldName Name of the field to look for.
  * @param optRetNumItems If non-NULL, the number of items in the field will be written into the uint32 this points to.
  * @returns A pointer to the array of int32s on success, or NULL on failure (field not found).
  *          Note that the returned array remains under the ownership of the MMessage object.
  */
int32 * MMGetInt32Field(const MMessage * msg, const char * fieldName, uint32 * optRetNumItems);

/** Retrieves the int64 field with the given name.
  * @param msg The MMessage to look for the field in.
  * @param fieldName Name of the field to look for.
  * @param optRetNumItems If non-NULL, the number of items in the field will be written into the uint32 this points to.
  * @returns A pointer to the array of int64 on success, or NULL on failure (field not found).
  *          Note that the returned array remains under the ownership of the MMessage object.
  */
int64 * MMGetInt64Field(const MMessage * msg, const char * fieldName, uint32 * optRetNumItems);

/** Retrieves the float field with the given name.
  * @param msg The MMessage to look for the field in.
  * @param fieldName Name of the field to look for.
  * @param optRetNumItems If non-NULL, the number of items in the field will be written into the uint32 this points to.
  * @returns A pointer to the array of floats on success, or NULL on failure (field not found).
  *          Note that the returned array remains under the ownership of the MMessage object.
  */
float * MMGetFloatField(const MMessage * msg, const char * fieldName, uint32 * optRetNumItems);

/** Retrieves the double field with the given name.
  * @param msg The MMessage to look for the field in.
  * @param fieldName Name of the field to look for.
  * @param optRetNumItems If non-NULL, the number of items in the field will be written into the uint32 this points to.
  * @returns A pointer to the array of doubles on success, or NULL on failure (field not found).
  *          Note that the returned array remains under the ownership of the MMessage object.
  */
double * MMGetDoubleField(const MMessage * msg, const char * fieldName, uint32 * optRetNumItems);

/** Retrieves the Message field with the given name.
  * @param msg The MMessage to look for the field in.
  * @param fieldName Name of the field to look for.
  * @param optRetNumItems If non-NULL, the number of items in the field will be written into the uint32 this points to.
  * @returns A pointer to the array of Messages on success, or NULL on failure (field not found).
  *          Note that the returned array remains under the ownership of the MMessage object.
  */
MMessage ** MMGetMessageField(const MMessage * msg, const char * fieldName, uint32 * optRetNumItems);

/** Retrieves the pointer field with the given name.
  * @param msg The MMessage to look for the field in.
  * @param fieldName Name of the field to look for.
  * @param optRetNumItems If non-NULL, the number of items in the field will be written into the uint32 this points to.
  * @returns A pointer to the array of pointers on success, or NULL on failure (field not found).
  *          Note that the returned array remains under the ownership of the MMessage object.
  */
void ** MMGetPointerField(const MMessage * msg, const char * fieldName, uint32 * optRetNumItems);

/** Retrieves the point field with the given name.
  * @param msg The MMessage to look for the field in.
  * @param fieldName Name of the field to look for.
  * @param optRetNumItems If non-NULL, the number of items in the field will be written into the uint32 this points to.
  * @returns A pointer to the array of points on success, or NULL on failure (field not found).
  *          Note that the returned array remains under the ownership of the MMessage object.
  */
MPoint * MMGetPointField(const MMessage * msg, const char * fieldName, uint32 * optRetNumItems);

/** Retrieves the rect field with the given name.
  * @param msg The MMessage to look for the field in.
  * @param fieldName Name of the field to look for.
  * @param optRetNumItems If non-NULL, the number of items in the field will be written into the uint32 this points to.
  * @returns A pointer to the array of rects on success, or NULL on failure (field not found).
  *          Note that the returned array remains under the ownership of the MMessage object.
  */
MRect * MMGetRectField(const MMessage * msg, const char * fieldName, uint32 * optRetNumItems);

/** Retrieves the data field with the given name.
  * @param msg The MMessage to look for the field in.
  * @param typeCode The typecode of the field to look for, or B_ANY_TYPE if you aren't particular about type.
  * @param fieldName Name of the field to look for.
  * @param optRetNumItems If non-NULL, the number of items in the field will be written into the uint32 this points to.
  * @returns A pointer to the array of data items on success, or NULL on failure (field not found).
  *          Note that the returned array remains under the ownership of the MMessage object.
  */
MByteBuffer ** MMGetDataField(const MMessage * msg, uint32 typeCode, const char * fieldName, uint32 * optRetNumItems);

/** Returns information about the type and size of the specified field.
  * @param msg The MMessage to look for the field in.
  * @param fieldName The name of the field to look for.
  * @param typeCode The typecode of the field to look for, or B_ANY_TYPE if you aren't particular about type.
  * @param optRetNumItems If non-NULL, on success the uint32 this points to will have the number of items in the field written into it.
  * @param optRetTypeCode If non-NULL, on success the uint32 this points to will have the type code of the field written into it.
  * @returns B_NO_ERROR if the field was found, or B_ERROR if no field with the specified name and type were present.
  */
status_t MMGetFieldInfo(const MMessage * msg, const char * fieldName, uint32 typeCode, uint32 * optRetNumItems, uint32 * optRetTypeCode);

/** Returns MTrue iff the two MMessage objects are exactly equivalent.  (Note that field ordering is not considered)
  * @param msg1 First MMessage to compare.  Must not be NULL.
  * @param msg2 Second MMessage to compare.  Must not be NULL.
  * @returns MTrue If the two MMessage objects are equal; MFalse otherwise.
  */
MBool MMAreMessagesEqual(const MMessage * msg1, const MMessage * msg2);

/** Prints the contents of this MMessage to stdout.  Useful for debugging.
  * @param msg The MMessage to print the contents of to stdout.
  */
void MMPrintToStream(const MMessage * msg);

/** Returns an iterator object that you can use to iterator over the field names of this MMessage.
  * @param msg The MMessage object over whose field names you wish to iterate.
  * @param typeCode The type of field you are interested in, or B_ANY_TYPE if you aren't particular.
  * @returns the iterator object, suitable, for passing in to the MMGetNextFieldName() function.
  * @note It is an error to remove or replace fields in a MMessage object while iterating over it.
  */
MMessageIterator MMGetFieldNameIterator(const MMessage * msg, uint32 typeCode);

/** Returns the next field name in the field name iteration, or NULL if there are no more field names.
  * @param iteratorPtr This should point to the iterator object that was returned by a MMGetFieldNameIterator() call.
  * @param optRetTypeCode If non-NULL, the uint32 this points to will have the next field's type code written into it.
  * @returns The next field name, or NULL if the iteration is complete.
  */
const char * MMGetNextFieldName(MMessageIterator * iteratorPtr, uint32 * optRetTypeCode);

#ifdef MUSCLE_ENABLE_MEMORY_TRACKING

/** A wrapper for malloc() that allows us to track the number of bytes currently allocated.  
  * Good for catching memory leaks.  Only enabled if MUSCLE_ENABLE_MEMORY_TRACKING is defined; otherwise #defined to malloc().
  */
void * MMalloc(uint32 numBytes);

/** A wrapper for free() that allows us to track the number of bytes currently allocated.
  * Good for catching memory leaks.  Only enabled if MUSCLE_ENABLE_MEMORY_TRACKING is defined; otherwise #defined to free().
  */
void * MFree(void * ptr);

/** A wrapper for realloc() that allows us to track the number of bytes currently allocated.
  * Good for catching memory leaks.  Only enabled if MUSCLE_ENABLE_MEMORY_TRACKING is defined; otherwise #defined to realloc().
  */
void * MRealloc(void * oldBuf, uint32 newSize);

#else
# define MMalloc  malloc
# define MRealloc realloc
# define MFree    free
#endif

/** Returns the current number of allocated bytes. 
  * Good for catching memory leaks.  Only enabled if MUSCLE_ENABLE_MEMORY_TRACKING is defined; otherwise always returns zero.
  */
uint32 MGetNumBytesAllocated();

#ifdef __cplusplus
};
#endif

#endif