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 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 write or readfrom members. write will be disabled since the WritePolicy is unknown, readfrom will be disabled since a socket with the ConnectedCommunicationPolicy does not have a readfrom member.

See also:

The Policy Framework
The Handle Hierarchy
The Protocol Classes