bstream

An os_bstream is an instance of a binary stream that supports the Universal Streaming Service (USS). When an os_bstream is constructed, it is associated with both a protocol and a universal device adapter. The protocol defines how the primitive data types are encoded; common protocols are NDR and ASCII. The device adapter is a portable interface to an underlying I/O device. Refer to IO<ToolKit> for more information.

One common use of Streaming<ToolKit> is simple persistence of objects. Persistence is the ability to save objects to and restore them from disk. Because files represent another device to Streaming<ToolKit>, both persistence and transport of objects are simple. Once an os_bstream is constructed and associated with a particular I/O device, items can be written to the stream using operator<< and read from the stream using operator>> .

The following figure illustrates the data flow of the Universal Streaming Service. The stream converts objects to primitives, which are in turn converted to byte streams using the protocol (NDR by default). The adapter ensures the byte streams are correctly written to the device.

Streaming<ToolKit> is designed to integrate with the following Recursion Software I/O components.

File<ToolKit>
Network<ToolKit>
Pipe<ToolKit>
Platform<ToolKit> for UNIX

In addition, Streaming<ToolKit> contains device adapters for ANSI/ISO IOStreams so you can create binary streams on the following.

fstream
stringstream
ostream (like cout and cerr )
istream (like cin )

To construct an os_bstream and associate it with a particular I/O device, supply a device adapter as its single parameter. Use the function os_adapter_for() to create an os_adapter for a particular I/O device. The following example constructs a binary stream on an fstream .


	fstream file( "file.out", ios::out | ios::trunc );

	os_bstream my_stream( os_adapter_for( file ) );

For convenience, many Recursion Software I/O classes supply a conversion operator that acts as a factory for the necessary os_adapter so you can omit the call to os_adapter_for() . The following example constructs a text stream on an os_tcp_socket .


	os_tcp_socket socket;

	os_bstream my_stream( socket );

Once an os_bstream is constructed and associated with a particular I/O device, items can be written to the stream using operator<< and read from the stream using operator>>. Following is a diagram that illustrates the flow of data.