The body of a stream message contains a stream of values, where each value has an associated data type.
The data type of a value is one of the XMS data types listed in Table 1.
After an application creates a stream message, the body of the message is write-only. The application assembles the application data into the body by calling the appropriate write methods of the StreamMessage class for C or C++ or of the IStreamMessage interface for .NET. Each time the application writes a value to the message stream, the value and its data type is assembled immediately after the previous value written by the application. XMS maintains an internal cursor to remember the position of the last value that was assembled.
When the application sends the message, the body of the message becomes read-only. In this mode, the application can send the message multiple times.
When an application receives a stream message, the body of the message is read-only. The application can use the appropriate read methods of the StreamMessage class for C or C++ or of the IStreamMessage interface for .NET to read the contents of the message stream. The application reads the values in sequence, and XMS maintains an internal cursor to remember the position of the last value that was read.
Using the C interface only, an application can skip over a value without reading it by calling a read function with a null pointer for the value parameter, or for the buffer parameter if the application calls xmsStreamMsgReadBytes() or xmsStreamMsgReadObject(). For information about how to skip over a value that is a string, see xmsStreamMsgReadString – Read String.
When an application reads a value from the message stream, the value can be converted by XMS into another data type. For example, to read an integer from the message stream, an application can call the Read String method, which returns the integer as a string. The supported conversions are the same as those that are supported when XMS converts a property value from one data type to another. For more information about the supported conversions, therefore, see Implicit conversion of a property value from one data type to another.
If an error occurs while an application is attempting to read a value from the message stream, the cursor is not advanced. The application can recover from the error by attempting to read the value as another data type.
If an application calls the Reset method of the StreamMessage class for C or C++ or of the IStreamMessage interface for .NET when the body of a stream message is write-only, the body becomes read-only. The method also repositions the cursor at the beginning of the message stream.
If an application calls the Clear Body method of the Message class for C or C++ or of the IMessage interface for .NET when the body of a stream message is read-only, the body becomes write-only. The method also clears the body.