Socket/Protocols/BSDSocketAddress.hh

   1 // $Id$
   2 //
   3 // Copyright (C) 2008
   4 // Fraunhofer Institute for Open Communication Systems (FOKUS)
   5 // Competence Center NETwork research (NET), St. Augustin, GERMANY
   6 //     Stefan Bund <g0dil@berlios.de>
   7 //
   8 // This program is free software; you can redistribute it and/or modify
   9 // it under the terms of the GNU General Public License as published by
  10 // the Free Software Foundation; either version 2 of the License, or
  11 // (at your option) any later version.
  12 //
  13 // This program is distributed in the hope that it will be useful,
  14 // but WITHOUT ANY WARRANTY; without even the implied warranty of
  15 // MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  16 // GNU General Public License for more details.
  17 //
  18 // You should have received a copy of the GNU General Public License
  19 // along with this program; if not, write to the
  20 // Free Software Foundation, Inc.,
  21 // 59 Temple Place - Suite 330, Boston, MA  02111-1307, USA.
  22
  23 /** \file
  24     \brief BSDSocketAddress public header */
  25
  26 #ifndef HH_SENF_Socket_Protocols_BSDSocketAddress_
  27 #define HH_SENF_Socket_Protocols_BSDSocketAddress_ 1
  28
  29 // Custom includes
  30 #include "../../Utils/safe_bool.hh"
  31 #include <sys/socket.h>
  32 #include <iostream>
  33
  34 //#include "BSDSocketAddress.mpp"
  35 ///////////////////////////////hh.p////////////////////////////////////////
  36
  37 namespace senf {
  38
  39     /** \brief Socket addressing, BSD style
  40
  41         BSDSocketAddress is the base class of all BSD \c sockaddr based addressing classes. The \c
  42         sockaddr addressing interface is split into several parts
  43
  44         \li The BSDSocketAddress provides a read-only and generic \c sockaddr interface
  45         \li Address family specific derived classes implement addressing of a specific type. These
  46             are INet4SocketAddress (\c AF_INET), INet6SocketAddress (\c AF_INET6), UNSocketAddress
  47             (\c AF_UNIX) and LLSocketAddress (\c AF_PACKET)
  48         \li GenericBSDSocketAddress provides writable support for generic addresses.
  49
  50         It is \e not possible to create or store BSDSocketAddress instances: You must either store
  51         an address in one of the specifically typed subclasses or using GenericBSDSocketAddress.
  52
  53         A BSDSocketAddress or GenericBSDSocketAddress can be cast (like a downcast) to (the correct)
  54         type specific cast using sockaddr_cast:
  55
  56         \code
  57         void foo(senf::BSDSOcketAddress const & addr)
  58         {
  59             if (addr.family() == senf::INet4SocketAddress::addressFamily) {
  60                 senf::INet4SocketAddress i4addr (
  61                     senf::sockaddr_cast<senf::INet4SocketAddress>(addr) );
  62                 ...
  63             }
  64         }
  65         \endcode
  66
  67         All these classes provide a generic \c sockaddr API to interface with legacy \c sockaddr
  68         based code (e.g. the BSD socket API). In this base-class, this interface is read-only, the
  69         derived classes however provide a read-write interface.
  70
  71         \ingroup addr_group
  72       */
  73     class BSDSocketAddress
  74         : public senf::comparable_safe_bool<BSDSocketAddress>
  75     {
  76     public:
  77         bool operator==(BSDSocketAddress const & other) const; ///< Compare two arbitrary addresses
  78                                         /**< For addresses to be considered equal, they must have
  79                                              the same family, length and the data must be
  80                                              identical. */
  81         bool operator!=(BSDSocketAddress const & other) const; ///< Inverse of operator==
  82
  83         bool boolean_test() const;      ///< Return \c true, if address is not empty
  84                                         /**< An address is considered empty if
  85                                              \li the family is AF_UNSPEC
  86                                              \li or the size is 0
  87                                              \li or all data bytes are 0 */
  88
  89         short family() const;           ///< Return the address family.
  90                                         /**< This value is found in the \c addressFamily member of
  91                                              each typed derived class
  92                                              (e.g. INet4Address::addressFamily) */
  93
  94         ///////////////////////////////////////////////////////////////////////////
  95         ///\name Generic sockaddr interface
  96         ///\{
  97
  98         struct sockaddr const * sockaddr_p() const;
  99         socklen_t socklen() const;
 100         socklen_t const * socklen_p() const;
 101
 102         ///\}
 103
 104     protected:
 105         BSDSocketAddress(socklen_t len, short family);
 106         BSDSocketAddress(BSDSocketAddress const & other);
 107         BSDSocketAddress & operator=(BSDSocketAddress const & other);
 108
 109         struct sockaddr * sockaddr_p();
 110         socklen_t * socklen_p();
 111
 112         void socklen(socklen_t len);
 113
 114     private:
 115
 116         socklen_t len_;
 117     };
 118
 119     /** \brief Safe socket address down-cast
 120
 121         sockaddr_cast allows to safely cast a socket address to it's derived type. Only the family
 122         specific derived addressing classes are permissible for \a Target.
 123
 124         This cast is especially useful to cast a GenericBSDSocketAddress to it's concrete type.
 125
 126         \related BSDSocketAddress
 127      */
 128     template <class Target>
 129     Target & sockaddr_cast(BSDSocketAddress & source);
 130
 131     /** \brief Safe socket address down-cast (const)
 132         \see sockaddr_cast()
 133         \related BSDSocketAddress
 134      */
 135     template <class Target>
 136     Target const & sockaddr_cast(BSDSocketAddress const & source);
 137
 138     /** \brief Output generic socket address
 139
 140         This stream operator will output a generic BSDSocketAddress in a family depending format.
 141
 142         \related BSDSocketAddress
 143      */
 144     std::ostream & operator<<(std::ostream & os, BSDSocketAddress const & addr);
 145
 146     /** \brief Generic BSD \c sockaddr storage
 147
 148         While BSDSocketAddress provides read-only generic \c sockaddr access,
 149         GenericBSDSocketAddress allows to store (write) arbitrary socket addresses. (It is
 150         internally based on \c sockaddr_storage).
 151
 152         To access the stored address, use sockaddr_cast to cast the GenericBSDSocketAddress to the
 153         correct family specific address class.
 154
 155         \ingroup addr_group
 156       */
 157     class GenericBSDSocketAddress
 158         : public BSDSocketAddress
 159     {
 160     public:
 161         ///////////////////////////////////////////////////////////////////////////
 162         ///\name Structors and default members
 163         ///@{
 164
 165         GenericBSDSocketAddress();
 166         GenericBSDSocketAddress(BSDSocketAddress const & other);
 167         GenericBSDSocketAddress& operator=(const BSDSocketAddress & other);
 168
 169         GenericBSDSocketAddress(const GenericBSDSocketAddress& other);
 170         GenericBSDSocketAddress& operator=(const GenericBSDSocketAddress& other);
 171
 172         ///@}
 173         ///////////////////////////////////////////////////////////////////////////
 174         ///\name Generic sockaddr interface
 175         ///\{
 176
 177         struct sockaddr const * sockaddr_p() const;
 178         struct sockaddr * sockaddr_p();
 179
 180         using BSDSocketAddress::socklen_p;
 181
 182         ///\}
 183
 184     protected:
 185
 186     private:
 187         struct sockaddr_storage addr_;
 188     };
 189
 190 }
 191
 192 ///////////////////////////////hh.e////////////////////////////////////////
 193 #include "BSDSocketAddress.cci"
 194 //#include "BSDSocketAddress.ct"
 195 //#include "BSDSocketAddress.cti"
 196 #endif
 197
 198 \f
 199 // Local Variables:
 200 // mode: c++
 201 // fill-column: 100
 202 // comment-column: 40
 203 // c-file-style: "senf"
 204 // indent-tabs-mode: nil
 205 // ispell-local-dictionary: "american"
 206 // compile-command: "scons -u test"
 207 // End: