//
// 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.
+// The contents of this file are subject to the Fraunhofer FOKUS Public License
+// Version 1.0 (the "License"); you may not use this file except in compliance
+// with the License. You may obtain a copy of the License at
+// http://senf.berlios.de/license.html
//
-// 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.
+// The Fraunhofer FOKUS Public License Version 1.0 is based on,
+// but modifies the Mozilla Public License Version 1.1.
+// See the full license text for the amendments.
//
-// 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.
+// Software distributed under the License is distributed on an "AS IS" basis,
+// WITHOUT WARRANTY OF ANY KIND, either express or implied. See the License
+// for the specific language governing rights and limitations under the License.
+//
+// The Original Code is Fraunhofer FOKUS code.
+//
+// The Initial Developer of the Original Code is Fraunhofer-Gesellschaft e.V.
+// (registered association), Hansastraße 27 c, 80686 Munich, Germany.
+//
+// Contributor(s):
+// Stefan Bund <g0dil@berlios.de>
+
namespace senf {
/** \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
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
+ \li There is a family of auxiliary \ref addr_group to supplement the socket library
\section socket_handle Socket Handles
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,
+ further socket functionality. 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
+ \section socket_addr Auxiliary 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
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
+ \section over_impl Implementation of the Socket Library Structure
In the Implementation, the socket policy is identified by an instance of the senf::SocketPolicy
template. The Socket representation is internally represented in a senf::SocketBody which is not
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
projects / senf.git / blobdiff