diff --git a/Socket/Mainpage.dox b/Socket/Mainpage.dox index fe67997ee84c58c02a2e8af4bfc16fe8f686558b..8f8f736b4de7eb88122e3ebba4cec9147ef44ab1 100644 --- a/Socket/Mainpage.dox +++ b/Socket/Mainpage.dox @@ -53,13 +53,17 @@ namespace senf { 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 + 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 socket which fulfill the - minimal requirements of your code. - - This works, by defining a special reduced policy or handle for - your code: + 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: \code typedef ClientSocketHandle< diff --git a/Socket/SocketPolicy.hh b/Socket/SocketPolicy.hh index be96da217a891f94528ff2430d6baf77bc99140b..6ef298149ccb7ce657f3eef5993829e0523d1d93 100644 --- a/Socket/SocketPolicy.hh +++ b/Socket/SocketPolicy.hh @@ -76,14 +76,18 @@ <dd>configures, if and how buffering is configured for a socket</dd> </dl> - Every Policy value is identified by a class type. The policy - classes themselves built an inheritance hierarchy for each policy - axis. For each policy axis, the root of this tree is the class - named \e Policy \c Base (e.g. \p AddressingPolicyBase). - - The senf::SocketPolicy defines the complete policy of a socket. It + In a concrete policy, each of these policy axis is assigned a value, + the policy value. This value is identified by a class type. For example, + possible values for <em>framingPolicy</em> are <tt>DatagramFramingPolicy</tt> + or <tt>StreamFramingPolicy</tt> which are classes derived from the axis + base class <tt>FramingPolicyBase</tt>. This base class doubles as + <tt>UnspecifiedFramingPolicy</tt> (which is just a typedef alias). + If a policy axis is assigned this Unspecified type, the axis is left + unspecified, the policy will be incomplete. + + The senf::SocketPolicy tempalte defines the complete policy of a socket. It combines a set of policy classes, one for each policy - axis. Together, they define the behavior of a socket handle. The + axis as described above. Together, they define the behavior of a socket handle. The socket handle instances do not implement any socket functionality themselves instead defering the implementation to the policy classes. The SocketHandle interface is therefore \e not @@ -100,8 +104,13 @@ compatible. If they are, the more derived SocketHandle can be converted (assigned to) the more basic SocketHandle. + \doc Example (concrete policy, incomplete policy, compatibility/assignment) + \section policy_group_details The Policy Framework Classes + \doc Policy should be Axis here. Make clear, that this information is only + needed when extending the library. + In the following discussion we will use the following conventions: \li \e Policy is one or \c AddressingPolicy, \c FramingPolicy, \c CommunicationPolicy, \c ReadPolicy, \c WritePolicy or \c diff --git a/Socket/SocketProtocol.hh b/Socket/SocketProtocol.hh index 165d66832e7e2a178d01804e58119ade84fe4f6a..1935b6ee06191860abb7fadf15071a0631ea3599 100644 --- a/Socket/SocketProtocol.hh +++ b/Socket/SocketProtocol.hh @@ -225,6 +225,8 @@ namespace senf { protocols themselves, they are combined to build concrete protocols. This structure will remove a lot of code duplication. It is important to ensure, that the protocol facets do not overlap, since otherwise there will be problems resolving overlapping members. + + \doc init_client init_server */ template <class SocketPolicy> class ConcreteSocketProtocol