Message Buffer or Stream Classes

---

Message buffer or stream classes are used to describe the source from which a message is being decoded or the target to which a message is being encoded. The base interface for these classes is OSMessageBufferIF. Classes for message buffers or streams specific to encoding or decoding and for different encoding rules (for example, XML) are derived from this base class. An instance of one of these derived classes along with an instance of the class generated for a particular XSD type are needed to encode or decode a message.

Message buffers for encoding can be either static or dynamic. A static buffer is simply a byte array in memory. It is generally the better performing case because no dynamic memory allocations are required. However, the user must know in advance the amount of memory that will be required to hold an encoded message. There is no fixed formula to determine this number. XML encoding involves the additions of tags and attributes and other decorations to the provided data that will increase the size beyond the initial size of the populated data structures. The way to find out is either by trial-and-error (an error will be signaled if the provided buffer is not large enough) or by using a very large buffer in comparison to the size of the data. A static buffer is described using a message buffer class object by passing the byte array address and size to the constructor.

A dynamic buffer is specified by using the default constructor. This tells the encoder that it is to allocate memory for the message. It does this by allocating an initial amount of memory and when this is used up, it expands the buffer by reallocating. This can be an expensive operation in terms of performance, especially if a large number of reallocations are required. Special methods are provided that allow the initial and incremental allocation sizes to be tuned for better performance. See the run-time class reference guide for further details on this.

In either case, after a message is encoded, it is necessary to get the start address and length of the message. In the static buffer case for XML, the start address of the message is simply the start address of the buffer. But in the dynamic case, a function call is required to get the start address of the message after encoding is complete. The getMsgPtr method is provided for this purpose.