X-Git-Url: http://g0dil.de/git?a=blobdiff_plain;f=Socket%2FMainpage.dox;h=5485c7e76b1d6735c4cf6de1b63086de7aa213c0;hb=b8ca4a544cce3e6023bb56b712a03d6362f2bb79;hp=8e6383b435e6c553d130b70de8a7aca3c619862e;hpb=58e527462abb46e321c94fda65f758b67ac3aef2;p=senf.git diff --git a/Socket/Mainpage.dox b/Socket/Mainpage.dox index 8e6383b..5485c7e 100644 --- a/Socket/Mainpage.dox +++ b/Socket/Mainpage.dox @@ -1,8 +1,8 @@ // $Id$ // -// Copyright (C) 2007 -// Fraunhofer Institute for Open Communication Systems (FOKUS) -// Competence Center NETwork research (NET), St. Augustin, GERMANY +// Copyright (C) 2007 +// Fraunhofer Institute for Open Communication Systems (FOKUS) +// Competence Center NETwork research (NET), St. Augustin, GERMANY // Stefan Bund // // This program is free software; you can redistribute it and/or modify @@ -24,29 +24,73 @@ 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. + 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). - \see - \ref structure \n - \ref usage \n - \ref handle_group \n - \ref policy_group \n - \ref protocol_group \n - \ref addr_group \n - \ref extend \n - \ref implementation */ /** \page structure Overview of the Socket Library Structure @@ -150,7 +194,7 @@ namespace senf { 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 @@ -210,8 +254,8 @@ namespace senf { 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 MyProtocolClientSocketHandle; - typedef ProtocolServerSocketHandle MyProtocolServerSocketHandle; + typedef ProtocolClientSocketHandle MySocketProtocolClientSocketHandle; + typedef ProtocolServerSocketHandle MySocketProtocolServerSocketHandle; \endcode \section extend_policy Extending the policy framework @@ -243,45 +287,52 @@ namespace senf { \see policy_group */ -/** \page glossary Glossary - - - - - - - - - - - - - - - - - - - - - -
policy collection of policy classes, one for each policy axis, instantiation of - the SocketPolicy template
policy axis one aspect defined in the socket policy, typedef and member of the - SocketPolicy template
policy class implementation of a single policy axis, class derived from the - axis base class
complete policy socket policy where each axis is specified completely
incomplete policy socket policy, where at least one axis is not fully - specified
protocol class definition of a protocol as a class, class inheriting from - ConcreteSocketProtocol.
protocol facet a class providing some subset of the protocol interface, class - derived from SocketProtocol but not from ConcreteSocketProtocol
policy interface interface directly provided by - ClientSocketHandle/ServerSocketHandle and defined through the policy
protocol interface interface provided by the protocol class and accessible via - the ProtocolClientSocketHandle::protocol()/ProtocolServerSocketHandle::protocol() - member
- */ - /** \page implementation Implementation notes \section class_diagram Class Diagram - \image html SocketLibrary-classes.png +
+ \ref IPv4Protocol + \ref WritePolicyBase + \ref SocketBufferingPolicy + \ref NoAddressingPolicy + \ref NotReadablePolicy + \ref AdressableBSDSocketProtocol + \ref BufferingPolicyBase + \ref FramingPolicyBase + \ref FileBody + \ref DatagramFramingPolicy + \ref INet6AddressingPolicy + \ref BSDSocketProtocol + \ref INet4AddressingPolicy + \ref ProtocolServerSocketHandle + \ref PolicyBase + \ref TCPProtocol + \ref ReadablePolicy + \ref SocketPolicy + \ref CommunicationPolicyBase + \ref TCPv6Protocol + \ref SocketProtocol + \ref ConnectedCommunicationPolicy + \ref ProtocolClientSocketHandle + \ref IPv6Protocol + \ref WritablePolicy + \ref SocketBody + \ref PacketProtocol + \ref NotWritablePolicy + \ref ReadPolicyBase + \ref SocketHandle + \ref ClientSocketHandle + \ref UnconnectedCommunicationPolicy + \ref ConcreteSocketProtocol + \ref TCPv4Protocol + \ref StreamFramingPolicy + \ref AddressingPolicyBase + \ref FileHandle + \ref LLAddressingPolicy + \ref ServerSocketHandle +
+ \htmlonly SocketLibrary-classes \endhtmlonly \section impl_notes Arbitrary Implementation Notes @@ -307,4 +358,5 @@ namespace senf { // ispell-local-dictionary: "american" // mode: flyspell // mode: auto-fill +// compile-command: "scons -u doc" // End: