Using the Socket Library

Whenever you use the socket library, what you will be dealing with are FileHandle derived instances. The socket library relies on reference counting to automatically manage the underlying socket representation. This frees you of having to manage the socket lifetime explicitly.

Creating a Socket Handle

To create a new socket handle (opening a socket), you will need to use
ProtocolClientSocketHandle or ProtocolServerSocketHandle. You will probably not use these
templates as is but use proper typedefs (for example TCPv4ClientSocketHandle or
PacketSocketHandle). The documentation for these socket handles are found in the protocol class
(for example TCPv4SocketProtocol or PacketSocketProtocol).

Writing Reusable Components

To make your code more flexible, you should not pass around your socket in this form. Most of
your code will be using only a small subset of the ProtocolClientSocketHandle or
ProtocolServerSocketHandle API.

If instead of using the fully specified handle type you use a more incomplete type, you allow
your code to be used with all sockets which fulfill the minimal requirements of your code. These
types are based on the ClientSocketHandle and ServerSocketHandle templates which implement the
policy interface without providing the concrete protocol interface.  To use those templates you
may define a special reduced policy or handle for your code. By giving only an incomplete policy
you thereby reduce the interface to that required by your module:

typedef ClientSocketHandle<
    MakeSocketPolicy<
        ReadablePolicy,
        StreamFramingPolicy,
        ConnectedCommunicationPolicy > > MyReadableHandle;

This defines \c MyReadableHandle as a ClientSocketHandle which will have only read
functionality. Your code expects a stream interface (in contrast to a packet or datagram based
interface). You will not have \c write or \c readfrom members. \c write will be disabled since
the WritePolicy is unknown, \c readfrom will be disabled since a socket with the
ConnectedCommunicationPolicy does not have a \c readfrom member.

\see
    \ref policy_group \n
    \ref handle_group \n
    \ref protocol_group