Socket/Protocols: Move incorrectly placed members from...

Socket/Protocols: Move incorrectly placed members from AddressableBSDSocketProtocol to BSDSocketProtocol
Socket/Protocols: Add missing DatagramSocketProtocol to some protocols
Socket/Protocols: Extend documentation of addressing classes

Socket/Protocols/BSDSocketProtocol.cc

@@ -57,27 +57,7 @@ prefix_ void senf::BSDSocketProtocol::linger(bool enable, unsigned timeout)
         throw SystemException();
 }
 
-///////////////////////////////////////////////////////////////////////////
-
-prefix_ bool senf::AddressableBSDSocketProtocol::reuseaddr()
-    const
-{
-    int value;
-    socklen_t len (sizeof(value));
-    if (::getsockopt(fd(),SOL_SOCKET,SO_REUSEADDR,&value,&len) < 0)
-        throw SystemException();
-    return value;
-}
-
-prefix_ void senf::AddressableBSDSocketProtocol::reuseaddr(bool value)
-    const
-{
-    int ivalue (value);
-    if (::setsockopt(fd(),SOL_SOCKET,SO_REUSEADDR,&ivalue,sizeof(ivalue)) < 0)
-        throw SystemException();
-}
-
-prefix_ boost::uint8_t senf::AddressableBSDSocketProtocol::priority()
+prefix_ boost::uint8_t senf::BSDSocketProtocol::priority()
     const
 {
     int value;
@@ -87,7 +67,7 @@ prefix_ boost::uint8_t senf::AddressableBSDSocketProtocol::priority()
     return value;
 }
 
-prefix_ void senf::AddressableBSDSocketProtocol::priority(boost::uint8_t value)
+prefix_ void senf::BSDSocketProtocol::priority(boost::uint8_t value)
     const
 {
     int ivalue (value);
@@ -95,7 +75,7 @@ prefix_ void senf::AddressableBSDSocketProtocol::priority(boost::uint8_t value)
         throw SystemException();
 }
 
-prefix_ unsigned senf::AddressableBSDSocketProtocol::rcvbuf()
+prefix_ unsigned senf::BSDSocketProtocol::rcvbuf()
     const
 {
     unsigned size;
@@ -107,14 +87,14 @@ prefix_ unsigned senf::AddressableBSDSocketProtocol::rcvbuf()
     return size/2;
 }
 
-prefix_ void senf::AddressableBSDSocketProtocol::rcvbuf(unsigned size)
+prefix_ void senf::BSDSocketProtocol::rcvbuf(unsigned size)
     const
 {
     if (::setsockopt(fd(),SOL_SOCKET,SO_RCVBUF,&size,sizeof(size)) < 0)
         throw SystemException();
 }
 
-prefix_ unsigned senf::AddressableBSDSocketProtocol::sndbuf()
+prefix_ unsigned senf::BSDSocketProtocol::sndbuf()
     const
 {
     unsigned size;
@@ -126,13 +106,33 @@ prefix_ unsigned senf::AddressableBSDSocketProtocol::sndbuf()
     return size/2;
 }
 
-prefix_ void senf::AddressableBSDSocketProtocol::sndbuf(unsigned size)
+prefix_ void senf::BSDSocketProtocol::sndbuf(unsigned size)
     const
 {
     if (::setsockopt(fd(),SOL_SOCKET,SO_SNDBUF,&size,sizeof(size)) < 0)
         throw SystemException();
 }
 
+///////////////////////////////////////////////////////////////////////////
+
+prefix_ bool senf::AddressableBSDSocketProtocol::reuseaddr()
+    const
+{
+    int value;
+    socklen_t len (sizeof(value));
+    if (::getsockopt(fd(),SOL_SOCKET,SO_REUSEADDR,&value,&len) < 0)
+        throw SystemException();
+    return value;
+}
+
+prefix_ void senf::AddressableBSDSocketProtocol::reuseaddr(bool value)
+    const
+{
+    int ivalue (value);
+    if (::setsockopt(fd(),SOL_SOCKET,SO_REUSEADDR,&ivalue,sizeof(ivalue)) < 0)
+        throw SystemException();
+}
+
 /////////////////////////////cc.e////////////////////////////////////////
 #undef prefix_
 //#include "BSDSocketProtocol.mpp"

Socket/Protocols/BSDSocketProtocol.hh

@@ -59,27 +59,7 @@ namespace senf {
                                              forever.
                                              \param[in] enable \c true to activate linger
                                              \param[in] timeout linger timeout in seconds */
-
-    };
-
-    /** \brief Protocol facet providing basic connection oriented BSD socket functions
-
-        AddressableBSDSocketProtocol provides the BSD socket API as it generically applies to
-        addressable (connection oriented) sockets.
-     */
-    class AddressableBSDSocketProtocol
-        : public virtual SocketProtocol
-    {
-    public:
-        bool reuseaddr() const;         ///< Return current reuseaddr state
-                                        /**< \returns \c true if \c SO_REUSEADDR is currently
-                                             enabled, \c false otherwise*/
-        void reuseaddr(bool value) const; ///< Set reuseraddr state
-                                        /**< A \c true value enables \c SO_REUSEADDR, \c false will
-                                             disable it.
-                                             \param[in] value new \c SO_REUSEADDR state */
-
-        boost::uint8_t priority() const;  ///< Get packet priority assigned to outgoing packets
+       boost::uint8_t priority() const;  ///< Get packet priority assigned to outgoing packets
                                         /**< This call will return the priority value assigned to
                                              packets sent via this socket. Depending on the
                                              protocol, this value may also be placed inside the
@@ -109,6 +89,24 @@ namespace senf {
         void sndbuf(unsigned size) const; ///< Change size of send buffer
                                         /**< \param[in] size new send buffer size */
         
+     };
+
+    /** \brief Protocol facet providing basic connection oriented BSD socket functions
+
+        AddressableBSDSocketProtocol provides the BSD socket API as it generically applies to
+        addressable (connection oriented) sockets.
+     */
+    class AddressableBSDSocketProtocol
+        : public virtual SocketProtocol
+    {
+    public:
+        bool reuseaddr() const;         ///< Return current reuseaddr state
+                                        /**< \returns \c true if \c SO_REUSEADDR is currently
+                                             enabled, \c false otherwise*/
+        void reuseaddr(bool value) const; ///< Set reuseraddr state
+                                        /**< A \c true value enables \c SO_REUSEADDR, \c false will
+                                             disable it.
+                                             \param[in] value new \c SO_REUSEADDR state */
     };
 
     /// @}

Socket/Protocols/INet/ConnectedRawINetSocketHandle.hh

@@ -27,6 +27,7 @@
 #include "INetSocketProtocol.hh"
 #include "RawINetSocketProtocol.hh"
 #include "../../../Socket/Protocols/BSDSocketProtocol.hh"
+#include "../../../Socket/Protocols/DatagramSocketProtocol.hh"
 #include "../../../Socket/FramingPolicy.hh"
 #include "../../../Socket/CommunicationPolicy.hh"
 #include "../../../Socket/ReadWritePolicy.hh"
@@ -77,6 +78,7 @@ namespace senf {
         : public ConcreteSocketProtocol<ConnectedRawV4Socket_Policy, ConnectedRawV4SocketProtocol>,
           public RawINetSocketProtocol,
           public BSDSocketProtocol,
+	  public DatagramSocketProtocol,
           public AddressableBSDSocketProtocol
     {
     public:
@@ -145,6 +147,7 @@ namespace senf {
         : public ConcreteSocketProtocol<ConnectedRawV6Socket_Policy, ConnectedRawV6SocketProtocol>,
           public RawINetSocketProtocol,
           public BSDSocketProtocol,
+	  public DatagramSocketProtocol,
           public AddressableBSDSocketProtocol
     {
     public:

Socket/Protocols/INet/ConnectedUDPSocketHandle.hh

@@ -34,6 +34,7 @@
 #include "INetSocketProtocol.hh"
 #include "UDPSocketProtocol.hh"
 #include "../../../Socket/Protocols/BSDSocketProtocol.hh"
+#include "../../../Socket/Protocols/DatagramSocketProtocol.hh"
 #include "../../../Socket/FramingPolicy.hh"
 #include "../../../Socket/CommunicationPolicy.hh"
 #include "../../../Socket/ReadWritePolicy.hh"
@@ -80,6 +81,7 @@ namespace senf {
         : public ConcreteSocketProtocol<ConnectedUDPv4Socket_Policy, ConnectedUDPv4SocketProtocol>,
           public UDPSocketProtocol,
           public BSDSocketProtocol,
+	  public DatagramSocketProtocol,
           public AddressableBSDSocketProtocol
     {
     public:
@@ -139,6 +141,7 @@ namespace senf {
         : public ConcreteSocketProtocol<ConnectedUDPv6Socket_Policy, ConnectedUDPv6SocketProtocol>,
           public UDPSocketProtocol,
           public BSDSocketProtocol,
+	  public DatagramSocketProtocol,
           public AddressableBSDSocketProtocol
     {
     public:

Socket/Protocols/INet/INet4Address.hh

@@ -46,6 +46,36 @@ namespace senf {
         INet4Address represents a simple IP address. It is modelled as a fixed-size
         container/sequence of 4 bytes.
 
+        The following statements all create the same INet4 address <code>211.194.177.160</code>
+        \code
+        // Used to construct constant INet4 addresses
+        INet4Address(0xD3C2B1A0)
+        
+        // Construct an INet4 address from it's string representation. All the standard address
+        // representations are supported
+        INet4Address::from_string("211.194.177.160")
+        INet4Address::from_string("211.12759456")
+
+        // Construct an INet4 address from raw data. 'from_data' takes an arbitrary iterator (e.g. a
+        // pointer) as argument. Here we use a fixed array but normally you will need this to build
+        // an INet4 address in a packet parser
+        char rawBytes[] = { 0xD3, 0xC2, 0xB1, 0xA0 };
+        INet4Address::from_data(rawBytes)
+
+        // Construct an INet4 address from the standard POSIX representation: a 32-bit integer in
+        // network byte oder. This is used to interface with POSIX routines
+        struct sockaddr_in saddr = ...;
+        INet4Address::from_inaddr(saddr.sin_addr.s_addr)
+        \endcode
+
+        Since INet4Address is based on \c boost::array, you can access the raw data bytes of the
+        address (in network byte order) using \c begin(), \c end() or \c operator[]
+        \code
+        INet4Address ina = ...;
+        Packet::iterator i = ...;
+        std::copy(ina.begin(), ina.end(), i); // Copies 4 bytes
+        \endcode
+
         \see CheckINet4Network \n INet4Network
 
         \implementation We awkwardly need to use static named constructors (<tt>from_</tt> members)

Socket/Protocols/INet/INet6Address.hh

@@ -85,8 +85,31 @@ namespace senf {
         <tr><td><tt>ff70::/12</tt></td>      <td>Multicast address with embedded RP</td> <td>RFC3956</td>    <td></td></tr>
         </table>
 
-        The INet6Address class is based on \c boost::array and is built as a fixed-size sequence of
-        16 bytes.
+        The following statements all create the same INet6 address
+        <code>2001:db8::a0b1:1a2b:3dff:fe4e:5f00</code>:
+        \code
+        \\ Used to construct constant INet6 addresses
+        INet6Address(0x2001u,0xDB8u,0x0u,0xA0B1u 0x1A2Bu,0x3DFFu,0xFE4Eu,0x5F00u)
+
+        // Construct INet6 address from it's string representation
+        INet6Address::from_string("2001:db8::a0b1:1a2b:3dff:fe4e:5f00")
+
+        // Construct an INet6 address from raw data. 'from_data' takes an arbitrary iterator (e.g. a
+        // pointer) as argument. Here we use a fixed array but normally you will need this to build
+        // an INet6 address in a packet parser
+        char rawBytes[] = { 0x20, 0x01, 0x0D, 0xB8, 0x00, 0x00, 0xA0, 0xB1,
+                            0x1a, 0x2b, 0x3d, 0xff, 0xfe, 0x4e, 0xff, 0x00 };
+        INet6Address::from_data(rawBytes)
+        \endcode
+
+        Since INet6Address class is based on \c boost::array and is built as a fixed-size sequence
+        of 16 bytes, you can access the raw data bytes of the address (in network byte order) using
+        \c begin(), \c end() or \c operator[]
+        \code
+        INet6Address ina = ...;
+        Packet::iterator i = ...;
+        std::copy(ina.begin(), ina.end(), i);
+        \endcode
 
         \see CheckINet6Network \n INet6Network
         \ingroup addr_group

Socket/Protocols/INet/INetSocketProtocol.hh

@@ -47,6 +47,8 @@ namespace senf {
     /// \addtogroup protocol_facets_group
     /// @{
 
+    /** \brief Generic addressing type independent INet protocol facet
+     */
     class INetSocketProtocol
         : public virtual SocketProtocol
     {

Socket/Protocols/INet/MulticastSocketProtocol.hh

@@ -39,6 +39,8 @@ namespace senf {
     ///\addtogroup protocol_facets_group
     ///\{
    
+    /** \brief Generic addressing type independent multicast protocol facet
+     */
     class MulticastSocketProtocol 
         : public virtual SocketProtocol
     {
@@ -67,6 +69,8 @@ namespace senf {
                                              data from */
     };
 
+    /** \brief Multicast protocol facet for INet4 addressable multicast enabled sockets
+     */
     class INet4MulticastSocketProtocol
         : public virtual SocketProtocol
     {
@@ -122,6 +126,8 @@ namespace senf {
                                              \param[in] iface interface name */
     };
 
+    /** \brief Multicast protocol facet for INet6 addressable multicast enabled sockets
+     */
     class INet6MulticastSocketProtocol
         : public virtual SocketProtocol
     {

Socket/Protocols/INet/RawINetSocketHandle.hh

@@ -29,6 +29,7 @@
 #include "RawINetSocketProtocol.hh"
 #include "MulticastSocketProtocol.hh"
 #include "../../../Socket/Protocols/BSDSocketProtocol.hh"
+#include "../../../Socket/Protocols/DatagramSocketProtocol.hh"
 #include "../../../Socket/FramingPolicy.hh"
 #include "../../../Socket/CommunicationPolicy.hh"
 #include "../../../Socket/ReadWritePolicy.hh"
@@ -78,6 +79,7 @@ namespace senf {
           public RawINetSocketProtocol,
           public BSDSocketProtocol,
           public AddressableBSDSocketProtocol,
+	  public DatagramSocketProtocol,
           public MulticastSocketProtocol,
           public INet4MulticastSocketProtocol
     {
@@ -146,8 +148,9 @@ namespace senf {
           public RawINetSocketProtocol,
           public BSDSocketProtocol,
           public AddressableBSDSocketProtocol,
+	  public DatagramSocketProtocol,
           public MulticastSocketProtocol,
-          public INet4MulticastSocketProtocol
+          public INet6MulticastSocketProtocol
     {
     public:
         ///////////////////////////////////////////////////////////////////////////

Socket/Protocols/Raw/MACAddress.hh

@@ -45,6 +45,37 @@ namespace senf {
         
         The Ethernet MAC is modelled as a fixed-size container/sequence of 6 bytes.
 
+        The following statements all create the same MAC address <code>00:1A:2B:3C:4D:5F</code>
+        \code
+        // Used to construct constant MAC addresses
+        MACAddress(0x001A2B3C4D5Flu)
+
+        // Construct a MAC address from it's string representation:
+        MACAddress::from_string("00:1a:2b:3c:4d:5f")   // case is ignored
+        MACAddress::from_string("00-1A-2B-3C-4D-5F")   // '-' as separator is allowed too
+
+        // Construct a MAC address from raw data.  'from_data' takes an arbitrary iterator (e.g. a
+        // pointer) as argument. Here we use a fixed array but normally you will need this to build
+        // a MAC address in a packet parser
+        char rawBytes[] = { 0x00, 0x1A, 0x2B, 0x3C, 0x4D, 0x5F };
+        MACAddress::from_data(rawBytes)
+
+        // Construct a MAC from the EUID64 as used by INet6 interfaces.  The eui64 will come from an
+        // INet6 address:
+        MACAddress::from_eui64(0x001A2BFFFE3C4D5Ful)
+        MACAddress::from_eui64(
+            INet6Address(0x2001u,0xDB8u,0x1u,0x0u,0x001Au,0x2BFFu,0xFE3Cu,0x3D5Fu).id())
+        \endcode
+
+        Since MACAddress is based on \c boost::array, you can access the raw data bytes of the
+        address using \c begin(), \c end() or \c operator[]:
+        \code
+        MACAddress mac = ...;
+        Packet::iterator i = ...;
+
+        std::copy(mac.begin(), mac.end(), i); // Copies 6 bytes
+        \endcode
+
         \implementation We awkwardly need to use static named constructors (<tt>from_</tt> members)
             instead of ordinarily overloaded constructors for one simple reason: <tt>char *</tt>
             doubles as string literal and as arbitrary data iterator. The iterator constructor can
@@ -91,7 +122,7 @@ namespace senf {
         bool local() const;             ///< \c true, if address is locally administered
         bool multicast() const;             ///< \c true, if address is a group/multicast address
         bool broadcast() const;         ///< \c true, if address is the broadcast address
-        bool boolean_test() const;      ///< \c true, if address is the zero address
+        bool boolean_test() const;      ///< \c true, if address is not the zero address
 
         boost::uint32_t oui() const;    ///< Return first 3 bytes of the address
         boost::uint32_t nic() const;    ///< Return last 3 bytes of the address

Socket/Protocols/Raw/PacketSocketHandle.hh

@@ -35,6 +35,7 @@
 #include "../../../Socket/CommunicationPolicy.hh"
 #include "../../../Socket/ReadWritePolicy.hh"
 #include "../../../Socket/Protocols/BSDSocketProtocol.hh"
+#include "../../../Socket/Protocols/DatagramSocketProtocol.hh"
 #include "LLAddressing.hh"
 
 //#include "PacketSocketHandle.mpp"
@@ -76,6 +77,7 @@ namespace senf {
      */
     class PacketSocketProtocol
         : public ConcreteSocketProtocol<Packet_Policy, PacketSocketProtocol>,
+	  public DatagramSocketProtocol,
           public BSDSocketProtocol
     {
     public: