Birds Bot Manager (BBM)

Message Queue Class Description  (MQueue)

MQueue is a simple message queue implementation. New Messages can be appended to the end of
the queue, and messages can be retrieved from the queue by their index.

MQueue supports two basic types of messages: unstructured and structured.

Unstructured messages are simply a block of binary data. The client can retrieve a ptr 
to the data and the size of the block, but the MQueue imposes no constraints on the content
of the data block for the message.

Structured messages are composed of a sequence of components of type Int, Float or String.
Components can be added only to the last message in the queue with the methods AddInt(), AddFloat(), 
AddString().

Components are retrieved from the "current" message in order via GetInt(), GetFloat() and GetString().
The "current" message is set using or GetMessage().

Structured messages were introduced so as to closely match the HL engine Message abstraction.

Constructor:

	queue = new MQueue;

	There are no arguments to the constructor.

Adding / Retrieving unstructured messages:

	queue->Append(int type, int id, char *buffer, int size);

	queue->Get(int index, int *type, int *id, char **buffer, int *size);

		"index" is the message number in the queue.
		"type" and "id" are arbitrary user-supplied integer values

Adding a Structured message to the queue:

	queue->StartMessage(int type, int id);

		"type" and "id" are arbitrary user-supplied integers.

		As a side effect this method sets the "current" message to this message.

	queue->AddInt(int ivalue)
	queue->AddFloat(float fvalue)
	queue->AddCoord(float *coords)
	queue->AddString(char *str)

		Appends the given component to the end of the current message.

Retrieving a structured message and its components:

	queue->GetMessage(int index, int *type, int *id);

		Retrieves the type and id for the nominated message and also sets the
		"current" message to this message.

	int ivalue   =  queue->GetInt();
	float fvalue =  queue->GetFloat();
	float *fvalue = queue->GetCoords();
	char *str    =  queue->GetString();

		Retrieves the next component of the "current" message. Each call automatically
		increments along to the next component.

		*Note*
		Where a ptr type is returned this is valid only until Delete() is called
		on the queue. If you need the value for longer than this then you must copy
		it away.

Miscellaneous methods

	int num = queue->Count()

		returns the number of messages in the queue.

	int c = queue->Peek()

		Returns a character representing the type of the next component to be
		read. c will be 'I' 'F' 'C' or 'S' if there is a component waiting to be read,
		or 0 otherwise.

	queue->Print()

		Calls an internal print() routine that dumps out the entire contents of
		the queue into the console output file.

	queue->Print(int index)

		As for Print(), except that only the nominated message is printed.

	queue->Checkpoint()
	queue->Delete()

		Checkpoint() remembers the current entries in the queue, and Delete() deletes
		all the entries up to the checkpoint. After a Delete(), only messages which were
		added after the last Checkpoint() will be present in the queue.

		Calling Delete() without setting a Checkpoint() will delete all messages in the queue.

	queue->CopyQueue(MQueue *other)

		Appends all the messages from the "other" queue onto the end of our queue.