After a message has been encoded, the user must obtain the start address and length of the message in order to do further operations with it. Before a message can be encoded, the user must describe the buffer the message is to be encoded into by specifying a message buffer start address and size. There are three different types of message buffers that can be described:
static: this is a fixed-size byte array into which the message is encoded
dynamic: in this case, the encoder manages the allocation of memory to hold the encoded message
stream: in this case, the encoder writes the encoded data directly to an output stream
The static buffer case 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 trialand- 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.
In the dynamic case, the buffer description passed into the encoder is a null buffer pointer and zero size. 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. For this reason, run-time helper functions are provided that allow the user to control the size increment of buffer expansions. See the C/C++ Run-Time Library Reference Manual for a description of these functions.
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 rtXmlGetEncBufPtr function is provided for this purpose.