A text stream is an instance of os_tstream . The os_tstream class inherits from the standard iostream class, and thus inherits all of the iostream behaviors. When an os_tstream is constructed, it is associated with a socket via an intermediate adapter object called an os_adapter . When an item is streamed to an os_tstream , the item is converted into text format and then sent to the I/O device via the adapter. This technique fully decouples the text streaming mechanism from details of any particular I/O device. Refer to the "Device Adapters" section of IO for more information.

The following figure illustrates the data flow for text streams using a device adapter.

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

Additionally, Streaming<ToolKit> contains device adapters for IOStreams, so you can create text streams on the following.

To construct an os_tstream and associate it with a particular I/O device, supply an adapter to the device 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 text stream on an fstream .

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

os_tstream 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 os_adapter you need. Therefore, you can omit the call to os_adapter_for() . The following example constructs a text stream on an os_tcp_socket .

Note that, although you can use any device supported by an adapter with a text stream, certain IOStream operations can fail due to restrictions of the underlying device. For example, repositioning requests on a socket-based text stream fail, because seeking is not supported on sockets.

Example <ospace/stream/examples/tstreams.cpp>


  // Example tstream server.

#include <iostream>
#include <ospace/network.h>
#include <ospace/stream.h>

void
main()
  {
  os_network_toolkit init_network;
  os_streaming_toolkit init_streaming;

  // Open a server socket.
  os_tcp_connection_server server( os_socket_address( 3006 ) );
  os_tcp_socket socket;
  server.accept( socket ); // Accept incoming connection.

  os_tstream stream( socket ); // Create a text stream on the socket.
  char* txt = "This is a line of text.";
  int num = 42;
  cout << "Writing: " << txt << endl << num << endl;
  stream << txt << endl << num << endl; // Write text and number.
  }

Writing: This is a line of text.
42

Example <ospace/stream/examples/tstreamc.cpp>


  // Example tstream client.

#include <iostream>
#include <ospace/network.h>
#include <ospace/stream.h>

void
main()
  {
  os_network_toolkit init_network;
  os_streaming_toolkit init_streaming;

// Connect to server on my host at port 3006.
  os_tcp_socket socket;
  socket.connect_to( os_socket_address( 3006 ) );

  os_tstream stream( socket ); // Create a text stream on the socket.
  char buffer[ 32 ];
  int num = -1;

  // Read a line of text and a number.
  stream.getline( buffer, sizeof( buffer ) );
  stream >> num;
  cout << "Read: " << buffer << endl << num << endl;
  }

Read: This is a line of text.
42