/** \mainpage The SENF Socket Library
The Socket library provides a high level and object oriented abstraction based on the BSD socket
- API (but not limited to it).
-
+ API (but not limited to it).
+
\autotoc
-
+
\section socket_intro Introduction
\seechapter \ref structure \n
\seechapter \ref usage
-
+
The socket library abstraction is based on several concepts:
\li The basic visible interface is a \link handle_group handle object\endlink
symbol). However, more generic kinds of handles can be defined for more generic functionality.
-
+
\section socket_policy The Policy interface
\seechapter \ref policy_group
provides. This offers highly efficient access to the most important socket functions (like
reading and writing). The policy interface however is a \e static, non-polymorphic interface.
-
+
\section socket_protocol The Protocol interface
\seechapter \ref protocol_group
-
+
The protocol interface provides further protocol dependent and (possibly) polymorphic access to
further socket funcitonality. On the other hand, this type of interface is not as flexible,
\section socket_addr Auxilliary Addressing classes
\seechapter \ref addr_group
-
+
To supplement the socket library, there are a multitude of addressing classes. These come in two
basic groups:
\li Protocol specific addresses (e.g. INet4Address, MACAddress)
Whereas the protocol specific addresses are custom value types which represent their
corresponding low-level address, the socket addresses are based on the corresponding \c sockaddr
- structures.
-
+ structures.
+
\section socket_further Going further
\seechapter \ref extend \n
\seechapter \ref implementation
reducing the policy interface to a minimal sensible subset of the complete API.
\section over_policy The Policy Interface
-
+
The policy of a Socket consists of several parts, called <em>policy axis</em>. Each axis
corresponds to one specific interface aspect of the Socket. The exact meaning of the policy axis
are defined elsewhere (see \ref policy_group). The Protocol will always provide a complete set
defined match those defined in that Socket's protocol. Using such a generic handle decouples the
implementation parts using this handle from the other socket aspects (e.g. you may define a
generic socket handle for TCP based communication leaving the addressingPolicy undefined which
- makes your code independent of the type of addressing, IPv4 or IPv6).
+ makes your code independent of the type of addressing, IPv4 or IPv6).
This can be described as generalized compile-time polymorphism: A base class reference to some
derived class will only give access to a reduced interface (the base class interface) of a
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
\section class_diagram Class Diagram
- <div class="diamap" name="SocketLibrary-classes">
- <span coords="472,667,559,689">\ref IPv4Protocol</span>
- <span coords="29,773,139,794">\ref WritePolicyBase</span>
- <span coords="97,939,238,960">\ref SocketBufferingPolicy</span>
- <span coords="97,390,223,411">\ref NoAddressingPolicy</span>
- <span coords="97,736,217,758">\ref NotReadablePolicy</span>
- <span coords="418,609,613,631">\ref AdressableBSDSocketProtocol</span>
- <span coords="18,895,153,917">\ref BufferingPolicyBase</span>
- <span coords="22,426,148,447">\ref FramingPolicyBase</span>
- <span coords="409,0,495,36">\ref FileBody</span>
- <span coords="97,469,249,491">\ref DatagramFramingPolicy</span>
- <span coords="97,317,240,339">\ref INet6AddressingPolicy</span>
- <span coords="453,544,578,566">\ref BSDSocketProtocol</span>
- <span coords="97,281,240,303">\ref INet4AddressingPolicy</span>
- <span coords="452,177,706,209">\ref ProtocolServerSocketHandle</span>
- <span coords="412,259,486,281">\ref PolicyBase</span>
- <span coords="474,768,557,790">\ref TCPProtocol</span>
- <span coords="97,700,197,722">\ref ReadablePolicy</span>
- <span coords="342,249,654,411">\ref SocketPolicy</span>
- <span coords="0,541,173,563">\ref CommunicationPolicyBase</span>
- <span coords="640,859,736,881">\ref TCPv6Protocol</span>
- <span coords="353,428,453,465">\ref SocketProtocol</span>
- <span coords="97,585,297,606">\ref ConnectedCommunicationPolicy</span>
- <span coords="172,177,420,209">\ref ProtocolClientSocketHandle</span>
- <span coords="472,718,559,739">\ref IPv6Protocol</span>
- <span coords="97,816,192,838">\ref WritablePolicy</span>
- <span coords="383,62,520,98">\ref SocketBody</span>
- <span coords="698,888,798,910">\ref PacketProtocol</span>
- <span coords="97,852,213,874">\ref NotWritablePolicy</span>
- <span coords="31,657,138,679">\ref ReadPolicyBase</span>
- <span coords="213,60,369,91">\ref SocketHandle</span>
- <span coords="197,126,385,158">\ref ClientSocketHandle</span>
- <span coords="97,621,311,642">\ref UnconnectedCommunicationPolicy</span>
- <span coords="567,480,786,526">\ref ConcreteSocketProtocol</span>
- <span coords="582,830,678,852">\ref TCPv4Protocol</span>
- <span coords="97,505,234,527">\ref StreamFramingPolicy</span>
- <span coords="13,238,161,259">\ref AddressingPolicyBase</span>
- <span coords="224,0,294,36">\ref FileHandle</span>
- <span coords="97,353,222,375">\ref LLAddressingPolicy</span>
- <span coords="476,126,671,158">\ref ServerSocketHandle</span>
- </div>
- \htmlonly <img src="SocketLibrary-classes.png" border="0" alt="SocketLibrary-classes" usemap="#SocketLibrary-classes"> \endhtmlonly
+ \diaimage SocketLibrary-classes.dia
\section impl_notes Arbitrary Implementation Notes