Message Class Reference

The Message class is a tree of Nodes that represent a message defined by a Document.

Constructors

Message()	Create an empty message with no Document. Before anything useful can be done, setDocument() must be called.
Message(Document const & document)	Create an empty message from a Document.
Message(Message const & message)	Create a message from another.

Methods

void setDocument(Document const & document)	Set the Message's document.
Document const & document() const	Return a reference to the Message's Document.
*Node oob() const**	Return the Out-of-Band Node or 0 if none exists.
int size() const	Return the number of Nodes of this Message.
virtual int length() const	Return the length in bits of this Message.
bool empty() const	Returns true if the Message is empty. This means it has no data. To see if the Message has a Document associated with it, call document().empty().
void clear()	Clear the Message, making it empty.
BitString const & bitString() const	Returns a reference to the Message's data.
*virtual Node find(const char * name) const**	Return the first top-level Node by its name. 0 is returned if the field does not exist. This is the same as calling firstNode()->find(). Complexity of O(n).
*const char xml()**	Returns an XML representation of the Message. The return value will be valid for the life of the Message, or until an xml() method is called again.
*size_t xml(char dest, size_t length)**	Provides an XML representation of the Message. At most length bytes will be copied into dest. Returns the desired length of the buffer required to hold the entire xml representation.
*const char text(const char * fstring = "30n 6l 8v 10h s", bool headerOnly = false) const**	Returns a textual representation of the Message. The return value will be valid for the life of the Message, or until a text() method is called again. See the other text() method for parameter descriptions.
*size_t code(char dest, size_t length, const char * base = "msg") const**	Return a C++ representation of the Message. Experimental.
*const char code(const char * = "msg") const**	Returns a C++ representation of the Message. The return value will be valid for the life of the Message, or until a code() method is called again. Experimental.
int validate()	Iterate through all the Nodes in the Message to validate. The return value is the number of invalid nodes. Complexity of O(n).
bool valid() const	Returns true if there were no invalid nodes the last time validate() was called.
void reserve(unsigned size = 1024)	Reserve space for the Message's data. size is in bits. This is used to reserve space for encoding. See trim().
void trim()	Resize the Message to remove any unused bits that were reserved via reserve().
*Node firstNode() const**	Return a pointer to the first node in the message.
*Node lastNode()**	Return a pointer to the last node in the message.
*Node endNode()**	Return a pointer to the node one past the last node in the message.
*Node nextNode(Node * node)**	Return the next node as it occurs in sequential order in the message.
*Node prevNode(Node * node)**	Return the previous node as it occurs in sequential order in the message.

Operators

bool operator==(Message & m)	Equality operator. This will return true if the data of the two Messages are equal, even if the Messages do not reference the same Document.
bool operator!=(Message & m)	Inequality operator.
Message &operator=(Message const &value)	Message assigment operator. This will make both Messages data and Document be identical.
Message &operator=(BitString const &value)	BitString assignment operator.
*Node &operator[](const char name)**	Return a Node by its name. An exception is thrown if the field does not exist in the current scope. Complexity is O(n), where n is the number of nodes in the current scope.
Node &operator[](int index)	Return a Node by its logical index. It is up to the caller to make sure the index is in the correct range. (i.e., it's less than size()).

Detail

Before anything useful can be done, a Message must first reference a document.

#include <IT/Xenon.h>

Message m; // create empty Message with no Document reference
Document doc("myProtocol.xddl");
m.setDocument(doc);

The Message can now be assigned data. For example, if you want to decode an entire message:

BitString bs = myGetMessage();
m = bs;

Now m has been populated with the BitString, and individual fields can be accessed.

Node & n = m["Neighbor Count"];

An exception is thrown if the Node named Neighbor Count is not found. Use find() to check if a Node exists.

Using the bracket operator, nested Nodes can be accessed:

Node & l1 = m["Neighbor List"][1]["Location"];
Node & l2 = m["Neighbor List"][2]["Location"];

Assigning values to nodes can be done as you would expect:

m["Neighbor List"][1]["Location"] = 5;

The data of a Message can be extracted using the bitString() method.