Added close() method to stream classes.

[sockstream.git] / doc / design.xml

<?xml version="1.0"?>
<!DOCTYPE doc SYSTEM "/usr/local/xslt/doc.dtd">
<doc style="main.css"
     xmlns:xi="http://www.w3.org/2001/XInclude">

<!--
      Network Communication Class Library
      Original author :  Arjen Baart - arjen@andromeda.nl
      Version         : 0.1

      This document is prepared for XMLDoc. Transform to HTML,
      LaTeX, Postscript or plain text with XMLDoc utilities and
      XSLT sheets from http://www.andromeda.nl/projects/xmldoc/
-->

<report>
<titlepage>
   <title>Network Communication Class Library</title>
   <subtitle>Iostreams and sockets in C++</subtitle>

   <author>Arjen Baart <code>&lt;arjen@andromeda.nl&gt;</code></author>
   <date>Mar 09, 2012</date>
   <docinfo>
      <infoitem label="Version">0.2</infoitem>
      <infoitem label="Organization">Andromeda Technology &amp; Automation</infoitem>
   </docinfo>
   <abstract>
   The network communication class library encapsulates the UNIX socket layer
   for network communication.
   </abstract>
</titlepage>

<toc/>


<chapter>
<heading>Problem Statement</heading>
<para>
The way processes communicate on the internet is through the use of -sockets-.
The socket layer provides the interface between user processes and the network
protocol stacks in the kernel of an operating system. A process can use a large
variation of sockets, depending on the type of communication such as streams or
datagrams or depending on the address familiy that is used like IPv6 or UNIX.
</para>
<para>
When two processes communicate through sockets, there is a socket on either side
of the communication link. In other words, each process has its own socket while
the underlying network stacks transfer the data from one socket to the other
and vice versa. Which sockets take part in the communication is determined by
the -host- and the -service- on which the socket resides. In many cases, the
-service- also dictates the way the information is exchanged between the processes
that hold the sockets.
</para>
<para>
In C++ standard iostream classes and objects exist to perform input and output
operations on the controlling terminal of a process ('cin' and 'cout'), on files
and device streams and on blocks of memory holding character strings.
The socket stream classes provide this functionality for sockets in a way that
is intended to be easy to use for the application programmer.
Classes similar to the fstream and stringstream classes implement reading and writing
data to and from sockets.
At the highest level, an application is able to read data directly by specifying
a URL, for example:
<verbatim>
   string page;
   link = isockstream("http://www.andromeda.nl/index.html");
   link >> page;
</verbatim>
At a slightly lower level, an application program would open a stream which
connects to a host or address and a specific service.
On the other hand, a server application would create a listening socket on
a socket address and a service.
Such a socket waits for incoming connection requests and after accepting a connection,
a new socket is created through which the actual communication takes place.
The new socket can then be used in creating an iostream object.
Note that there can never be data transfer through a listening socket.

</para>
<para>
A socket needs an address to listen on or to connect to. Depending on the address
family used, a socket address has a different set of attributes, such as a pathname
for UNIX local addresses or an IP address and port number for internet addresses.
Also, diffrent kinds of addresses have different sets of operations defined on them.

</para>
<para>
Internally, sockets use numerical addresses and port numbers, whereas human users
and programmers may prefer names for these entities. The conversion of such names
into numbers and vice versa involves resolving through lookup systems such as DNS.
A host is usually identifeid by its name and has one or more addresses, IPv4, IPv6
or other possible addresses. Although a host can have multiple addresses, a socket
can connect to only one address. A service can have a similar problem. One service,
as identified by name, may be available on multiple ports. It is in general up to an
application to make appropriate selections in a multitude of addresses, although
sensible defaults may be provided by address objects.

</para>

<section>
<heading>TODO:</heading>

<itemize>
<item>higher-level protocols such as http</item>
<item>SSL/TLS support</item>
</itemize>

</section>

</chapter>


<chapter>
<heading>CLASSES</heading>

<para>
The following class diagram shows the classes and their relationships:
</para>

 <picture src='classes.png' eps='classes' scale='0.7'/>

<para>
The top-level classes are very similar to the standard iostream classes.
The classes sockstream, isockstream, osockstream and sockbuf are almost the
same as their fstream, ifstream, ofstream and filebuf counterparts.
The key class in the hierarchy is the sockbuf class that holds a close relation
to the Socket class and performs the actual I/O operations.
Depending on the type of communication, two types of Socket objects are possible:
Stream and Datagram.
</para>
<para>
The SocketAddress determines what a Socket connects to or listens to.
For most Sockets, a SocketAddress basicly consists of a port and an IP address
which are determined from the Service and Host for which the socket is
intended. Only UNIX domain sockets are defined by a single pathname of the
socket device.
Depending on the address family that is used for the Socket Address, one of the
three kinds of Socket Address is used to connect a socket: UNIX, IPv4 or IPv6.
It is up to an application programmer to figure out where a Sockets connects to
and create an appropriate type of SocketAddress to which a Socket can connect
or listen.
</para>
<para>
Classes to help an application setup a Socket Address are Host and Service, which
perform lookup functions as implemented in getaddrinfo(3).
</para>

</chapter>

<chapter>
<heading>SCENARIOS</heading>

<section>
<heading>Make a stream socket connected to a specific host and service</heading>

<enumerate>
<item>Application creates a Host object with the desired hostname.</item>

<item>Host object finds IP addresses and returns the list.</item>

<item>Application selects one IP address from the list.</item>

<item>Application creates a Service object with the desired name or port number.</item>

<item>Service object determines a list of available port addresses.</item>

<item>Application selects one service port from the list.</item>

<item>Application creates an object derived from SocketAddres, using the selected Internet Address and Service.</item>

<item>Application creates a Stream Socket object and tells it to connect to the Socket Address.</item>

</enumerate>

 <picture src='scenarios-1.png' eps='scenarios-1' scale='0.7'/>

</section>
<section>
<heading>Setup a listening stream socket</heading>

<enumerate>
<item>Application creates a Service object with the desired name or port number.</item>

<item>Service object determines a list of available port addresses.</item>

<item>Application selects one service port from the list.</item>

<item>Application creates an object derived from SocketAddres, using the ANY Internet Address and Service.</item>

<item>Application creates a Stream Socket object and tells it to listen on the Socket Address.</item>

</enumerate>

 <picture src='scenarios-2.png' eps='scenarios-2' scale='0.7'/>

</section>
</chapter>

<chapter>
<heading>MEMBERS and METHODS</heading>


<section>
<heading>Socket</heading>

<para>
The Socket represents the device through which the actual communication takes place.
This class encapsulates the socket interface in the UNIX or Linux kernel.
A Socket is itself an abstract base class from which two types of Socket are derived:
A StreamSocket and a DatagramSocket. Each of these classes have special properties
and only the common parts are defined in the Socket base class.
</para>

<subsection>
<heading>Members</heading>

<description>

<item tag='fd'>
The UNIX file descriptor of the socket in the kernel.
</item>

</description>

</subsection>
<subsection>
<heading>Methods</heading>

<description>
<item tag='Socket()'>
Default contructor. Initializes members.
</item>

<item tag='~Socket()'>
Destructor. Closes the UNIX socket.
</item>

<item tag='Listen(SocketAddress)'>
Creates a server socket. Implmented in derived classes.
</item>

<item tag='Close()'>
Close the UNIX socket without destroying the object itself.
</item>
</description>
</subsection>
<subsection>
<heading>Exceptions</heading>
</subsection>

</section>

<section>
<heading>StreamSocket</heading>

<para>
Implements a socket of the SOCK_STREAM type.
Note that a StreamSocket object is either listening for incoming connection requests
or is connected to a peer socket.
</para>

<subsection>
<heading>Methods</heading>

<description>
<item tag='Listen(SocketAddress)'>
Bind the socket to the address and put the socket in the listening state.
</item>

<item tag='Connect(SocketAddress)'>
Make a connection to a server socket.
</item>

<item tag='Socket Accept()'>
Accept a client connection and return the new connected socket.
</item>

<item tag='Read()'>
Input data from the other side.
</item>

<item tag='Write()'>
Output data to the other side.
</item>

</description>
</subsection>
</section>


<section>
<heading>DatagramSocket</heading>

<para>
Implements a socket of the SOCK_DGRAM type.
</para>

<subsection>
<heading>Methods</heading>

<description>
<item tag='Listen(SocketAddress)'>
Bind the socket to the address and wait for incoming messages.
</item>

<item tag='SendTo()'>
Send data to another socket.
</item>

<item tag='ReceiveFrom()'>
Receive data from another socket.
</item>

</description>
</subsection>
</section>

<section>
<heading>SocketAddress</heading>

<para>
The abstract base class for all kinds of socket addresses.
The SocketAddress class provides an interface for binding and connecting
sockets.
</para>
<subsection>
<heading>Methods</heading>
<description>
<item tag='address_family()'>
Return the address family of the socket address.
Since this function is pure virtual, it must be overridden in a derived class.
The dervied classes described in following sections will return AF_UNIX, AF_INET
or AF_INET6.
</item>
<item tag='get_sockaddr()'>
Return the <code>sockaddr</code> pointer that can be used by the <strong>bind(2)</strong>
or <strong>connect(2)</strong> system calls.
</item>
<item tag='get_socklen()'>
Return the length of the <code>sockaddr</code> structure that can be used by the <strong>bind(2)</strong>
or <strong>connect(2)</strong> system calls.
</item>
</description>
</subsection>
<subsection>
<heading>Exceptions</heading>
</subsection>

</section>

<section>
<heading>UNIXSocketAddress</heading>

<para>
Implementation of SocketAddress for UNIX domain sockets.
</para>
<subsection>
<heading>Methods</heading>
<description>
<item tag='UNIXSocketAddress()'>
The constructor.
</item>
</description>
</subsection>
</section>

<section>
<heading>IPv4SocketAddress</heading>

<para>
Implementation of SocketAddress for IPv4 domain sockets.
</para>
<subsection>
<heading>Methods</heading>
<description>
<item tag='IPSocketAddress()'>
The constructor.
</item>
</description>
</subsection>
</section>

<section>
<heading>IPv6SocketAddress</heading>

<para>
Implementation of SocketAddress for IPv6 domain sockets.
</para>
</section>

<section>
<heading>Service</heading>
<para>
A Service is determined by its name, port number and service type (stream or datagram).
</para>
<subsection>
<heading>Methods</heading>
<description>
<item tag='Service()'>
The overloaded constructor can accept a string with a service name or a port number.
</item>
<item tag='FindAddress()'>
Find all port numbers of the service, given its name.
Since a single service can be available on more than one port, this creates a list of
port numbers.
</item>
<item tag='FindName()'>
Find the name of the service that belongs to the first port number in the list
of port numbers.
</item>
</description>
</subsection>
<subsection>
<heading>Exceptions</heading>
</subsection>

</section>

<section>
<heading>Port</heading>
<para>
A Port is determined by its port number and socket type (stream, datagram, etcetera).
</para>
<subsection>
<heading>Members</heading>
<description>
<item tag='port'>
The port number in network byte order.
</item>
<item tag='sockettype'>
The type of socket on which the service is available.
Can be stream (SOCK_STREAM), datagram (SOCK_DGRAM) or any other type as described
in <strong>socket(2)</strong>.
</item>
</description>
</subsection>

<subsection>
<heading>Methods</heading>
<description>
<item tag='get_port()'>
The port number in network byte order.
</item>
<item tag='get_sockettype()'>
The type of socket on which the service is available.
</item>
<item tag='operator unsigned short()'>
The port number in host byte order.
</item>
<item tag='operator ==()'>
</item>
<item tag='operator !=()'>
</item>
</description>
</subsection>
<subsection>
<heading>Exceptions</heading>
</subsection>

</section>

<section>
<heading>Host</heading>

<subsection>
<heading>Methods</heading>
<description>
<item tag='Host()'>
The overloaded constructor can accept a string with a hostname or an InternetAddress
object.
</item>
<item tag='FindAddress()'>
Find all network addresses of the host, given its name.
Since a single host can hold multiple IP addresses, this creates a list of
InternetAddress objects.
</item>
<item tag='FindName()'>
Find the name of the host that belongs to the first IP address in the list
of InternetAddress objects.
</item>
</description>

</subsection>
<subsection>
<heading>Exceptions</heading>
</subsection>

</section>

<section>
<heading>InternetAddress</heading>
</section>

<para>
An InternetAddress object holds an IP address which can be either an IPv4 address or
an IPv6 address.
Its main purpose is to perform the conversion between addresses in network byte order
end textual representations of an IP address.
</para>

<subsection>
<heading>Members</heading>
<description>
<item tag='af'>
The address family, AF_UNSPEC, AF_INET of AF_INET6
</item>
<item tag='inet_addr'>
The address itself, in network byte order. Large enough to hold a IPv6 address (16 bytes).
</item>
</description>
</subsection>

<subsection>
<heading>Methods</heading>
<description>
<item tag='InternetAddress()'>
Constructor creates the IP address from a variaty of forms, including conversion
from a String.
The address family (AF_INET or AF_INET6) is determined from the argument passed to
the constructor.
Possible argument types are <code>struct addrinfo</code> as used by <strong>getaddrinfo(3)</strong>,
<code>struct in_addr</code>, <code>struct in6_addr</code> and <code>String</code>
With the IP address in character string form, the address family is determined by the presence
of colon (:) characters in the IP address, as these can only occur in IPv6 addresses.
See also <strong>inet_pton(3)</strong>
</item>
<item tag='address_family()'>
Returns the address family to which the IP address belongs. Either AF_INET of AF_INET6.
</item>
<item tag='String()'>
Converts the IP address to textual form in a manner like <strong>inet_ntop(3)</strong>.
</item>
<item tag='get_in_addr()'>
Returns an IPv4 address in <code>struct in_addr</code> format.
</item>
<item tag='get_in6_addr()'>
Returns an IPv6 address in <code>struct in6_addr</code> format.
</item>
<item tag='operator ==()'>
Two internet addresses are equal if both the address family and the address
itself of the internet addresses are equal.
</item>
<item tag='operator !=()'>
The opposite of the == operator.
</item>
</description>
</subsection>

<subsection>
<heading>Exceptions</heading>
</subsection>

</chapter>
</report>
</doc>