12.4 Using Rogue Wave Virtual Streams

The Rogue Wave virtual stream classes provide an interface for persisting data that is independent not only of the source or sink of the byte stream, but also of the precise method of formatting the stream. By choosing different types of virtual streams, you get different types of formatting. Several varieties of virtual streams are available in Tools.h++:

binary virtual streams for single-platform binary formatting
portable ASCII virtual streams for ASCII formatting
endian streams for endian byte ordering
XDR virtual streams for Sun's XDR formatting

Any object that is compatible with Rogue Wave's persistence mechanism (see the Tools.h++ documentation for details) can be persisted to and from a virtual stream. The persistence machinery is very sophisticated, and can handle complicated collections with numerous interrelationships between the components.

The source and sink of bytes for a virtual stream are standard C++ streambufs. When an application uses an RWPortalStreambuf, the virtual stream uses a net library communications channel as the source or sink of bytes. By using a virtual output stream on one end of a connection, and a virtual input stream on the other end of the connection, you can transmit objects across the communications channel. The collection server tutorial uses this technique for communication between a client and a collection server.

Here is some sample code that shows how to construct a portable ASCII virtual stream for output using an RWPortalStreambuf.

RWPortalStreambuf buf(portal);
RWpostream ostrm(&buf);

It is important that the streambuf object buf remains in scope as long as the output stream is being used, since the output stream keeps a pointer to the streambuf. If buf goes out of scope, then the pointer in the output stream becomes invalid, and when the stream attempts to write bytes, your program will fail, likely by crashing.

Here is a code snippet much like the previous one, which sets up a binary virtual stream for input from a portal.

RWPortalStreambuf buf(portal);
RWbistream istrm(&buf);