Top: Networking: ipstream

#include <pinet.h>

ipstream::ipstream();
ipstream::ipstream(ipaddress ip, int port);
ipstream::ipstream(string host, int port);
ipstream::~ipstream();

void ipstream::open();
void ipstream::close();
void ipstream::cancel();
bool ipstream::waitfor(int milliseconds);

ipaddress ipstream::get/set_ip();
string    ipstream::get/set_host();
int       ipstream::get/set_port();
ipaddress ipstream::get_myip();
int       ipstream::get_myport();

The ipstream class implements full-duplex streaming communication between IP hosts. Ipstream incorporates iobase, instm and outstm interfaces and adds two more properties: peer IP address and peer port number. This means, you can work with ipstream the same way you work with infile and outfile, except that you specify the target IP address or the symbolic hostname along with the port number instead of the filename when constructing an object. Besides, the rules of object-oriented inheritance allow you to manipulate ipstream objects in those parts of your code which are only 'familiar' with the basic instm and outstm interfaces.

In order to open a connection and exchange data you need to set target (peer host) address and the port number. The peer address can be either a symbolic DNS name or a numeric IPv4 address. Regardless of which one of these two properties you set first, the ipstream object can perform DNS resolving as necessary and return both properties on your request.

Ipstream adds the following status codes: IO_RESOLVING, IO_RESOLVED, IO_CONNECTING, IO_CONNECTED (see also iobase for the status codes common to all streams).

On Unix the library startup code blocks SIGPIPE, so that all error conditions on sockets always raise exceptions of type (estream*).

ipstream::ipstream() is the default constructor.

ipstream::ipstream(ipaddress ip, int port) constructs an ipstream object and assigns the peer ip/port values.

ipstream::ipstream(string host, int port) constructs an ipstream object and assigns the peer host name and port values. Before actually opening the stream ipstream resolves the host name to a numeric IP address. Host can be either a symbolic DNS name or even a numeric address in a string form (e.g. "somehost.com" or "192.168.1.1").

ipstream::~ipstream() cancels the connection immediately and destroys the object. To shut down the connection 'gracefully' you should call close() before destroying the object or before the program goes beyond the scope of a static/local ipstream object.

void ipstream::open() opens a connection with the peer. host or ip along with port properties must be set before opening the stream.

void ipstream::close() closes the stream 'gracefully', and in some situations may be time-consuming. Although all stream objects in PTypes are being closed by the destructors automatically, it is recommended to explicitly call close() for socket objects.

void ipstream::cancel() closes the stream immediately. If the connection was successful, calling cancel() may leave the peer host in a waiting state for a long time.

bool ipstream::waitfor(int milliseconds) waits on the socket until either data is available for reading (returns true) or the time specified in the parameter has elapsed, in which case it returns false.

ipaddress ipstream::get/set_ip() sets/retrieves the peer address in a numerical form. If the object was constructed using a symbolic name, get_ip() may perform a DNS lookup (only once).

string ipstream::get/set_host() sets/retrieves the peer address in a symbolic form. If the object was constructed using a numeric IP address, get_host() may perform a reverse DNS lookup.

int ipstream::get/set_port() sets/retrieves the peer port number.

ipaddress ipstream::get_myip() returns the local address associated with the socket.

int ipstream::get_myport() returns the local port number associated with the socket.

See also: iobase, instm, outstm, ipstmserver, Utilities, Examples