Socket/INetAddressing.hh

   1 // $Id$
   2 //
   3 // Copyright (C) 2006
   4 // Fraunhofer Institut fuer offene Kommunikationssysteme (FOKUS)
   5 // Kompetenzzentrum fuer Satelitenkommunikation (SatCom)
   6 //     Stefan Bund <stefan.bund@fokus.fraunhofer.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 INet[46]Address and INet[46]AddressingPolicy public header
  25  */
  26
  27 #ifndef HH_INetAddressing_
  28 #define HH_INetAddressing_ 1
  29
  30 // Custom includes
  31 #include <string>
  32 #include <exception>
  33 #include <netinet/in.h>
  34 #include "SocketPolicy.hh"
  35 #include "ClientSocketHandle.hh"
  36 #include "CommunicationPolicy.hh"
  37 #include "GenericAddressingPolicy.hh"
  38
  39 //#include "INetAddressing.mpp"
  40 ///////////////////////////////hh.p////////////////////////////////////////
  41
  42 namespace senf {
  43
  44     /// \addtogroup addr_group
  45     /// @{
  46
  47     /** \brief IPv4 socket address
  48
  49         INet4Address wrapps the standard sockaddr_in datatype. It provides simple accessor methods
  50         to accss the host and port. It does \e not integrate \c gethostbyname or DNS lookup.
  51
  52         \todo Implement real INet4Address datatype and rename this one to INet4SockAddress ...
  53         \todo Implement more complete interface
  54         \todo  gethostbyname support ?
  55      */
  56     class INet4Address
  57     {
  58     public:
  59         INet4Address();
  60         INet4Address(char const * address); ///< Set address and port
  61                                         /**< See INet4Address(std::string)
  62                                              \throws InvalidINetAddressException
  63                                              \fixme Why do I need this version? Shouldn't the
  64                                              std::string version be enough ? */
  65         INet4Address(std::string address); ///< Set address and port
  66                                         /**< This constructor expects a string of the form
  67                                              'xxx.xxx.xxx.xxx:pppp'. The constructor will use this
  68                                              value to initialize the host and port members. This
  69                                              constructor does \e only support numeric ip addresses
  70                                              not hostnames
  71                                              \param[in] address Address and port
  72                                              \throws InvalidINetAddressException */
  73         INet4Address(std::string host, unsigned port); ///< Set address and port explicitly
  74                                         /**< \param[in] host ip address in dotted-quad notation
  75                                              \param[in] port port number
  76                                              \throws InvalidINetAddressException */
  77
  78
  79         bool operator==(INet4Address const & other) const; ///< Check INet4Address for equality
  80
  81         std::string str() const;        ///< Return "address:port" string
  82         std::string host() const;       ///< Return address in doted quad notation
  83         unsigned port() const;          ///< Return portnumber
  84
  85         void clear();                   ///< Clear address/port to 0.0.0.0:0
  86
  87         /// \name Generic Address Interface
  88         /// @{
  89
  90         struct sockaddr * sockaddr_p();
  91         struct sockaddr const * sockaddr_p() const;
  92         unsigned sockaddr_len() const;
  93
  94         /// @}
  95
  96     private:
  97         void assignString(std::string addr);
  98
  99         struct ::sockaddr_in addr_;
 100     };
 101
 102     /** \brief Write address and port to os
 103
 104         \related INet4Address
 105      */
 106     std::ostream & operator<<(std::ostream & os, INet4Address const & addr);
 107
 108     /** \brief IPv6 network address
 109
 110         INet6Address represents a 128bit IPv6 network address. This class supports all standard
 111         numeric string representations of IPv6 addresses. This class does not integrate with \c
 112         gethostbyname() and so does not support host names.
 113
 114         The conversion constructors allow the use of string constants whereever an INet6Address is
 115         expected. Especially, it is possible to assign a string to an address to change it's value.
 116
 117         \implementation The <tt>char const *</tt> constructor overload is needed to support
 118             string-literals where an INet6Address is expected (the C++ standard does not allow
 119             chaining conversion constructors like char const * -> std::string -> INet6Address)
 120      */
 121     class INet6Address
 122     {
 123     public:
 124         ///////////////////////////////////////////////////////////////////////////
 125         // Types
 126
 127         ///////////////////////////////////////////////////////////////////////////
 128         ///\name Structors and default members
 129         ///@{
 130
 131         INet6Address();                 ///< Create empty address
 132         INet6Address(std::string const & addr); ///< Create address from string representation
 133         INet6Address(char const * addr); ///< Create address from string representation
 134         INet6Address(struct in6_addr const & addr); ///< Create address from in6_addr
 135         template <class Range>
 136         explicit INet6Address(Range const & range); ///< Create address from arbitrary raw data
 137                                         /**< This constructor will copy 16 bytes from the given
 138                                              range and interpret them as a IPv6 address in network
 139                                              byte order. This constructor is used to read an
 140                                              arbitrary address from it's binary representation.
 141
 142                                              \param range arbitrary range, see <a
 143                                                  href="http://www.boost.org/libs/range/index.html">Boost.Range</a>
 144                                           */
 145
 146         ///@}
 147         ///////////////////////////////////////////////////////////////////////////
 148
 149         void clear();                   ///< Clear address
 150         std::string address() const;    ///< Return printable address representation
 151
 152         bool operator==(INet6Address const & other) const; ///< Compare addresses for equality
 153         bool operator!=(INet6Address const & other) const; ///< Inverse of above
 154
 155         struct in6_addr & addr();       ///< Access internal address representation
 156         struct in6_addr const & addr() const;
 157                                         ///< Access internal address representation in const context
 158         struct in6_addr * addr_p();     ///< Get pointer to internal address repr
 159         struct in6_addr const * addr_p() const;
 160                                         ///< Get const pointer to internal address repr
 161         unsigned addr_len() const;      ///< Size of an IPv6 address (16 bytes)
 162
 163     protected:
 164
 165     private:
 166         struct in6_addr addr_;
 167     };
 168
 169
 170     /** \brief Output INet6Address instance as it's string representation
 171      */
 172     std::ostream & operator<<(std::ostream & os, INet6Address const & addr);
 173
 174     /** \brief IPv6 socket address
 175
 176         This class wrapps the standard \c sockaddr_in6 structure. INet6SocketAddress provides access
 177         to all members of the sockaddr_in6 structure. Additionally, INet6SocketAddress supports the
 178         string representation
 179
 180         \par "" <tt>[</tt> <i>address</i> [ <tt>\@</tt> <i>interface</i> ] <tt>]:</tt> <i>port</i>
 181
 182         Where \e address is an arbitrary numeric IPv6 address, \e interface is an optional network
 183         interface name and \e port is the port number. The interface specification is only valid if
 184         \e address is link-local address. The URL representation of an IPv6 address is as above
 185         without the optional interface spec.
 186
 187         INet6SocketAddress supports conversion constructors from it's string
 188         representation. Therefore, wherever a INet6SocketAddress instance is expected, a string may
 189         be used instead.
 190
 191         \implementation The sockaddr_in6 structure has an sin6_flowinfo member. However RFC3493 does
 192             not give the use of this field and specifies, that the field should be ignored ... so
 193             that's what we do. Furthermore, the GNU libc reference states, that this field is not
 194             implemented in the library.
 195
 196         \implementation We need to return the address in host() by value since we need to return a
 197             INet6Address. However, sockaddr_in6 does not have one ...
 198
 199         \implementation The <tt>char const *</tt> constructor overload is needed to support
 200             string-literals where an INet6SocketAddress is expected (the C++ standard does not allow
 201             chaining conversion constructors like <tt>char const *</tt> -> \c std::string -> \c
 202             INet6SocketAddress)
 203
 204         \idea Implement a INet6Address_ref class which has an interface identical to INet6Address
 205         and is convertible to INet6Address (the latter has a conversion constructor taking the
 206         former as arg). This class however references an external in6_addr instead of containing one
 207         itself. This can be used in INet6SocketAddress to increase the performance of some
 208         operations.
 209      */
 210     class INet6SocketAddress
 211     {
 212     public:
 213         ///////////////////////////////////////////////////////////////////////////
 214         // Types
 215
 216         ///////////////////////////////////////////////////////////////////////////
 217         ///\name Structors and default members
 218         ///@{
 219
 220         INet6SocketAddress();           ///< Create empty instance
 221         INet6SocketAddress(std::string const & addr);
 222                                         ///< Initialize/convert from string represenation
 223         INet6SocketAddress(char const * addr); ///< Same as above to support string literals
 224         INet6SocketAddress(INet6Address const & addr, unsigned port);
 225                                         ///< Initialize from address and port
 226         INet6SocketAddress(INet6Address const & addr, unsigned port, std::string const & iface);
 227                                         ///< Initialize explicitly from given parameters
 228         INet6SocketAddress(std::string const & addr, std::string const & iface);
 229                                         ///< Initialize from URL representation and explit interface
 230
 231         ///@}
 232         ///////////////////////////////////////////////////////////////////////////
 233
 234         bool operator==(INet6SocketAddress const & other) const; ///< Check addresses for equality
 235         bool operator!=(INet6SocketAddress const & other) const; ///< Inverse of above
 236
 237         void clear();                   ///< Clear socket address
 238
 239         std::string address() const;    ///< Get printable address representation
 240
 241         INet6Address host() const;      ///< Get address
 242         void host(INet6Address const & addr); ///< Change address
 243
 244         unsigned port() const;          ///< Get port number
 245         void port(unsigned poirt);      ///< Change port number
 246
 247         std::string iface() const;      ///< Get interface name
 248         void iface(std::string const & iface); ///< Change interface
 249
 250         ///\name Generic SocketAddress interface
 251         ///@{
 252
 253         struct sockaddr * sockaddr_p();
 254         struct sockaddr const * sockaddr_p() const;
 255         unsigned sockaddr_len() const;
 256
 257         ///@}
 258
 259     protected:
 260
 261     private:
 262         void assignAddr(std::string const & addr);
 263         void assignIface(std::string const & iface);
 264
 265         struct sockaddr_in6 sockaddr_;
 266     };
 267
 268     /** \brief Output INet6SocketAddress instance as it's string representation
 269      */
 270     std::ostream & operator<<(std::ostream & os, INet6SocketAddress const & addr);
 271
 272     /** \brief Signal invalid INet address syntax
 273
 274         \related INet4Address
 275         \relatesalso INet6Address
 276      */
 277     struct InvalidINetAddressException : public std::exception
 278     { char const * what() const throw() { return "invalid inet address"; } };
 279
 280     /// @}
 281
 282     /// \addtogroup policy_impl_group
 283     /// @{
 284
 285     /** \brief Addressing policy supporting IPv4 addressing
 286
 287         \par Address Type:
 288             INet4Address
 289
 290         This addressing policy implements addressing using Internet V4
 291         addresses.
 292
 293         The various members are directly importet from
 294         GenericAddressingPolicy which see for a detailed
 295         documentation.
 296      */
 297     struct INet4AddressingPolicy
 298         : public AddressingPolicyBase,
 299           private GenericAddressingPolicy<INet4Address>
 300     {
 301         typedef INet4Address Address;
 302
 303         using GenericAddressingPolicy<INet4Address>::peer;
 304         using GenericAddressingPolicy<INet4Address>::local;
 305         using GenericAddressingPolicy<INet4Address>::connect;
 306         using GenericAddressingPolicy<INet4Address>::bind;
 307     };
 308
 309     /** \brief Addressing policy supporting IPv6 addressing
 310
 311         \par Address Type:
 312             INet6SocketAddress
 313
 314         This addressing policy implements addressing using Internet V6
 315         addresses.
 316
 317         The various members are directly importet from
 318         GenericAddressingPolicy which see for a detailed
 319         documentation.
 320      */
 321     struct INet6AddressingPolicy
 322         : public AddressingPolicyBase,
 323           private GenericAddressingPolicy<INet6SocketAddress>
 324     {
 325         typedef INet6SocketAddress Address;
 326
 327         using GenericAddressingPolicy<INet6SocketAddress>::peer;
 328         using GenericAddressingPolicy<INet6SocketAddress>::local;
 329         using GenericAddressingPolicy<INet6SocketAddress>::connect;
 330         using GenericAddressingPolicy<INet6SocketAddress>::bind;
 331     };
 332
 333     /// @}
 334
 335 }
 336
 337 ///////////////////////////////hh.e////////////////////////////////////////
 338 #include "INetAddressing.cci"
 339 #include "INetAddressing.ct"
 340 //#include "INetAddressing.cti"
 341 //#include "INetAddressing.mpp"
 342 #endif
 343
 344 \f
 345 // Local Variables:
 346 // mode: c++
 347 // fill-column: 100
 348 // c-file-style: "senf"
 349 // indent-tabs-mode: nil
 350 // ispell-local-dictionary: "american"
 351 // End: