+// $Id$
+//
+// Copyright (C) 2007
+// Fraunhofer Institute for Open Communication Systems (FOKUS)
+// Competence Center NETwork research (NET), St. Augustin, GERMANY
+// Stefan Bund <g0dil@berlios.de>
+//
+// This program is free software; you can redistribute it and/or modify
+// it under the terms of the GNU General Public License as published by
+// the Free Software Foundation; either version 2 of the License, or
+// (at your option) any later version.
+//
+// This program is distributed in the hope that it will be useful,
+// but WITHOUT ANY WARRANTY; without even the implied warranty of
+// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
+// GNU General Public License for more details.
+//
+// You should have received a copy of the GNU General Public License
+// along with this program; if not, write to the
+// Free Software Foundation, Inc.,
+// 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA.
+
namespace senf {
/** \mainpage The SENF Socket Library
- The Socket library provides a high level and object oriented abstraction of the BSD socket
- API. The abstraction is based on several concepts:
+ The Socket library provides a high level and object oriented abstraction based on the BSD socket
+ 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
+ \li The basic visible interface is a \link handle_group handle object\endlink
\li The socket interface relies on a \link policy_group policy framework \endlink to configure
it's functionality
\li The rest of the socket API is accessible using a classic inheritance hierarchy of \link
protocol_group protocol classes \endlink
+ \li There is a family of auxilliary \ref addr_group to supplement the socket library
+
+
+ \section socket_handle Socket Handles
+ \seechapter \ref handle_group \n
+ \seechapter \ref concrete_protocol_group
The handle/body architecture provides automatic reference counted management of socket
- instances, the policy framework provides highly efficient access to the most important socket
- functions (like reading and writing) and the inheritance hierarchy provides convenient access to
- the multitude of special and protocol dependent options.
-
- \see \ref structure \n
- \ref usage \n
- \ref handle_group \n
- \ref policy_group \n
- \ref protocol_group \n
- \ref extend \n
- \ref implementation
+ instances. This is the visible interface to the socket library.
+
+ Each specific protocol is used primarily via a protocol specific handle (a typedef
+ symbol). However, more generic kinds of handles can be defined for more generic functionality.
+
+
+
+ \section socket_policy The Policy interface
+ \seechapter \ref policy_group
+
+ The policy framework configures the exact features, a specific type of socket handle
+ 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,
+ generic and fast as the policy interface.
+
+ \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)
+ \li Socket addresses (\c sockaddr) (e.g. INet4SocketAddress, LLSocketAddress)
+
+ 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.
+
+ \section socket_further Going further
+ \seechapter \ref extend \n
+ \seechapter \ref implementation
+
+ The socket library is highly flexible and extensible. The implementation is not restricted to
+ plain BSD sockets: Any type of read/write communication can be wrapped into the socket library
+ (one Example is the TapSocketHandle which provides access to a Linux \c tap device).
+
*/
/** \page structure Overview of the Socket Library Structure
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
+ class. The class still is of it's derived type (and inherently has the complete interface) but
+ only part of it is accessible via the base class reference. Likewise a generic handle (aka base
+ class reference) will only provide a reduced interface (aka base class interface) to the derived
+ class instance (aka socket).
\section over_protocol The Protocol Interface
The protocol interface is provided by a set of <em>protocol facets</em>. Each facet provides a
part of the interface. Whereas the policy interface is strictly defined (the number and type of
- policy axis is fixed and also the possible members provided by the policy interface is fixed),
+ policy axis is fixed and also the possible members provided by the policy interface are fixed),
the protocol interface is much more flexible. Any member needed to provide a complete API for
the specific protocol may be defined, the number and type of facets combined to provide the
complete interface is up to the Protocol implementor. This flexibility is necessary to provide a
However this flexibility comes at a cost: To access the protocol interface the user must know
the exact protocol of the socket. With other words, the protocol is only accessible if the
- handle you use is a protocol specific handle. A protocol specific Handle differs from a generic
- Handle in two ways: It always \e must have a complete policy and it has an additional reference
- to the protocol type of the socket. This reference gives access to the complete policy
+ handle you use is a <em>protocol specific</em> handle. A protocol specific Handle differs from a
+ generic Handle in two ways: It always has a complete policy and it knows the exact protocol type
+ of the socket (which generic handles don't). This allows to access to the complete protocol
interface.
\section over_impl Implementation of the Socket Libarary Structure
outside visible. The Handle is provided by a hierarchy of handle templates. Each Handle template
uses template arguments for the policy and/or protocol as needed (see \ref handle_group).
+ The Handle hierarchy divides the interface into two separate strains: the client interface
+ (senf::ClientSocketHandle and senf::ProtocolClientSocketHandle) provides the interface of a
+ client socket whereas the server interface (senf::ServerSocketHandle and
+ senf::ProtocolServerSocketHandle) provides the interface as used by server sockets.
+
The protocol interface is implemented using inheritance: The Protocol class inherits from each
protocol facet using multiple (virtual public) inheritance. The Protocol class therefore
provides the complete protocol API in a unified (see \ref protocol_group).
-
- The Handle references the policy and the protocol only via it's template argument, the
- information is part of the type. This information is not available as a data member in the
- Handle object.
*/
/** \page usage Using the Socket Library
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 PacketProtocol).
+ (for example TCPv4SocketProtocol or PacketSocketProtocol).
\section usage_reusable Writing Reusable Components
After the protocol class has been defined, you will probably want to provide typedefs for the
new protocol sockets. If the new protocol is connection oriented, this will be like
\code
- typedef ProtocolClientSocketHandle<MyProtocolClass> MyProtocolClientSocketHandle;
- typedef ProtocolServerSocketHandle<MyProtocolClass> MyProtocolServerSocketHandle;
+ typedef ProtocolClientSocketHandle<MySocketProtocolClass> MySocketProtocolClientSocketHandle;
+ typedef ProtocolServerSocketHandle<MySocketProtocolClass> MySocketProtocolServerSocketHandle;
\endcode
\section extend_policy Extending the policy framework
\see policy_group
*/
-/** \page glossary Glossary
-
- <table class="glossary">
-
- <tr><td>policy</td> <td>collection of policy classes, one for each policy axis, instantiation of
- the SocketPolicy template</td></tr>
-
- <tr><td>policy axis</td> <td>one aspect defined in the socket policy, typedef and member of the
- SocketPolicy template</td></tr>
-
- <tr><td>policy class</td> <td>implementation of a single policy axis, class derived from the
- axis base class</td></tr>
-
- <tr><td>complete policy</td> <td>socket policy where each axis is specified completely</td></tr>
-
- <tr><td>incomplete policy</td> <td>socket policy, where at least one axis is not fully
- specified</td></tr>
-
- <tr><td>protocol class</td> <td>definition of a protocol as a class, class inheriting from
- ConcreteSocketProtocol.</td></tr>
-
- <tr><td>protocol facet</td> <td>a class providing some subset of the protocol interface, class
- derived from SocketProtocol but not from ConcreteSocketProtocol</td></tr>
-
- <tr><td>policy interface</td> <td>interface directly provided by
- ClientSocketHandle/ServerSocketHandle and defined through the policy</td>
-
- <tr><td>protocol interface</td> <td>interface provided by the protocol class and accessible via
- the ProtocolClientSocketHandle::protocol()/ProtocolServerSocketHandle::protocol()
- member</td></tr>
-
- </table>
- */
-
/** \page implementation Implementation notes
\section class_diagram Class Diagram
- \image html SocketLibrary-classes.png
+ <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
\section impl_notes Arbitrary Implementation Notes
// ispell-local-dictionary: "american"
// mode: flyspell
// mode: auto-fill
+// compile-command: "scons -u doc"
// End:
projects / senf.git / blobdiff