Communication

TCPStream is a standard C++ stream to push data to and take data from a TCP connection. A TCPStream assumes a half-duplex mode, so to speak. This is the mode in which all transaction- or request-reply- oriented TCP protocols -- HTTP, SMTP, POP, NNTP, RPC over TCP, to name just very few -- operate. This mode implies that reads and writes from/to a channel can share the same buffer. A "get" operation tacitly flushes all the data deposited by prior "put" operations. Similarly a "put" operation discards all the previously read but not yet consumed data.

The functionality of TCPStreams is identical to that of an fstream: the only difference is that it may take really a while for an i/o operation on a TCP channel to finish. It is unreasonable to make the whole application wait. Thus an application is given a chance to tell a TCP buffer being created that it does not want the network i/o to block. Application does it by deriving and instantiating a NetCallback object. If the currently registered NetCallback::async_io_hint() returns true, a newly created TCP socket is turned into a (POSIX) non-blocking mode; when the stream wants to flush/fill its buffer and the operation can't be completed immediately, the stream calls NetCallback::yield(). When this function returns, the stream gives another try to the input/output operation.

With the TCPStream, you can check your POP3 mail like this:

 TCPstream link;
 link.connect(SocketAddr("hostname",110));
 if( !link.is_open() || !link )
 _error("Failed to establish the connection");
 link << "USER " << user_name << endl;
 int resp_code; char buffer[100];
 link >> resp_code;
 if( ! link.get(buffer,sizeof(buffer)-1,'\r').good() )
 _error("error reading a response line from the link");
 if( resp_code >= 300 )
 _error("bummer");
 ...etc...

See a validation code file vTCPstream.cc for more examples.

TCP streams are helpful on a server side as well. See vTCPstream_server.cc for a sample (forking) server.