Socket/Protocols/INet/INet4Address.hh

   1 // $Id$
   2 //
   3 // Copyright (C) 2007
   4 // Fraunhofer Institut fuer offene Kommunikationssysteme (FOKUS)
   5 // Kompetenzzentrum fuer Satelitenkommunikation (SatCom)
   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 INet4Address public header */
  25
  26 #ifndef HH_INet4Address_
  27 #define HH_INet4Address_ 1
  28
  29 // Custom includes
  30 #include <iostream>
  31 #include <string>
  32 #include <boost/cstdint.hpp>
  33 #include <boost/function.hpp>
  34 #include <boost/array.hpp>
  35 #include "Utils/SafeBool.hh"
  36
  37 //#include "INet4Address.mpp"
  38 ///////////////////////////////hh.p////////////////////////////////////////
  39
  40 namespace senf {
  41
  42     /** \brief IpV4 Internet address
  43
  44         INet4Address represents a simple IP address. It is modelled as a fixed-size
  45         container/sequence of 4 bytes.
  46
  47         \implementation We awkwardly need to use static named constructors (<tt>from_</tt> members)
  48             instead of ordinarily overloaded constructors for one simple reason: <tt>char *</tt>
  49             doubles as string literal and as arbitrary data iterator. The iterator constructor can
  50             therefore not be distinguished from initialization with a string literal. Therefore we
  51             need to disambiguate using the named constructors.
  52
  53         \todo Add additional classes for CIDR addresses and networks and network math.
  54         \ingroup addr_group
  55       */
  56     class INet4Address
  57         : public boost::array<boost::uint8_t,4>,
  58           public ComparableSafeBool<INet4Address>
  59
  60     {
  61     public:
  62         ///////////////////////////////////////////////////////////////////////////
  63         // Types
  64
  65         typedef uint32_t address_type;  ///< Address representation as number in host byte order
  66         typedef uint32_t inaddr_type;   ///< Legacy address representation in network byte order
  67         typedef boost::function<void (INet4Address const &)> Callback;
  68                                         ///< Callback for asynchronous from_string call
  69
  70         static INet4Address const None; ///< The empty (0) address
  71         static INet4Address const Loopback; ///< The loopback (127.0.0.1) address
  72         static INet4Address const Broadcast; ////< The global broadcast (255.255.255.255) address
  73
  74         enum NoInit_t { noinit };
  75
  76         ///////////////////////////////////////////////////////////////////////////
  77         ///\name Structors and default members
  78         ///@{
  79
  80         INet4Address();                 ///< Construct an empty address
  81         explicit INet4Address(NoInit_t); ///< Construct uninitialized (!) address
  82         explicit INet4Address(address_type value);
  83                                         ///< Construct an address constant
  84
  85         static INet4Address from_string(std::string const & s);
  86                                         ///< Convert string to address
  87                                         /**< This member will try to convert the given string into
  88                                              an IP address. from_string() supports all standard IP
  89                                              literal representations as well es hostnames.
  90                                              \attention This call may block if \a s represents a
  91                                                  hostname which must be looked up via some network
  92                                                  protocol like DNS or NIS
  93                                              \throws SyntaxException if the address cannot be
  94                                                  converted for some reason
  95                                              \param[in] s Address literal or hostname */
  96
  97         static void from_string(std::string const & s, Callback const & cb);
  98                                         ///< Convert string to address (async/non-blocking)
  99                                         /**< This member works like
 100                                              from_string(std::string const &). However unlike
 101                                              from_string(std::string const &), this call will not
 102                                              block. Instead it will call \a cb passing the
 103                                              INet4Address instance as soon as the address has been
 104                                              resolved (which may be immediate if the address
 105                                              represents an IP literal). \par
 106                                              On error, the address passed to \a cb will be empty.
 107                                              \param[in] s Address literal or hostname
 108                                              \param[in] cb Callback to pass the address to
 109                                              \fixme Implement */
 110
 111         template <class InputIterator>
 112         static INet4Address from_data(InputIterator i);
 113                                         ///< Construct address from 4 bytes of raw data
 114                                         /**< from_data will build an address from 4 bytes of raw
 115                                              data as accessed by the iterator. The data must be in
 116                                              network byte order. */
 117         static INet4Address from_inaddr(inaddr_type v);
 118                                         ///< Construct address from integer in network byte order
 119                                         /**< This call is used when interfacing with other legacy
 120                                              code to convert a network byte order address in an
 121                                              integer number into an INet4Address. */
 122
 123         ///@}
 124         ///////////////////////////////////////////////////////////////////////////
 125         ///\name Accessors
 126         ///@{
 127
 128         bool local() const;             ///< \c true, if address is locally administered
 129                                         /**< This call checks, if the address is within one of the
 130                                              IANA private ranges. */
 131         bool loopback() const;          ///< \c true, if address is within the loopback network
 132                                         /**< Checks, whether the address is in the IANA loopback
 133                                              network 10.0.0.0/8 */
 134         bool multicast() const;         ///< \c true, if address is a multicast address
 135                                         /**< Checks, whether the address is in the 224.0.0.0/4
 136                                              network reserved for multicast addresses by the
 137                                              IANA. */
 138         bool broadcast() const;         ///< \c true, if address is 255.255.255.255
 139         bool boolean_test() const;      ///< \c true, if address is non-empty (!= 0.0.0.0)
 140
 141         inaddr_type inaddr() const;     ///< Return the raw network byte order address
 142                                         /**< This member is used to interact with legacy code.
 143                                              \return */
 144         address_type address() const;   ///< Return address represented as integer number
 145                                         /**< This member returns the address as an integer number in
 146                                              host byte order. This representation allows simple
 147                                              network math operations. */
 148
 149         ////@}
 150
 151         struct SyntaxException : public std::exception
 152         { virtual char const * what() const throw() { return "invalid INet4 address syntax"; } };
 153
 154     private:
 155         enum InAddr_t { IsInAddr };
 156         INet4Address(inaddr_type addr, InAddr_t);
 157         inaddr_type & iref();
 158         inaddr_type iref() const;
 159     };
 160
 161     std::ostream & operator<<(std::ostream & os, INet4Address const & addr);
 162
 163 }
 164
 165 ///////////////////////////////hh.e////////////////////////////////////////
 166 #include "INet4Address.cci"
 167 #include "INet4Address.ct"
 168 //#include "INet4Address.cti"
 169 #endif
 170
 171 \f
 172 // Local Variables:
 173 // mode: c++
 174 // fill-column: 100
 175 // comment-column: 40
 176 // c-file-style: "senf"
 177 // indent-tabs-mode: nil
 178 // ispell-local-dictionary: "american"
 179 // compile-command: "scons -u test"
 180 // End: