senf/Socket/Protocols/Raw/EUI64.hh

   1 // $Id$
   2 //
   3 // Copyright (C) 2009
   4 // Fraunhofer Institute for Open Communication Systems (FOKUS)
   5 //
   6 // The contents of this file are subject to the Fraunhofer FOKUS Public License
   7 // Version 1.0 (the "License"); you may not use this file except in compliance
   8 // with the License. You may obtain a copy of the License at
   9 // http://senf.berlios.de/license.html
  10 //
  11 // The Fraunhofer FOKUS Public License Version 1.0 is based on,
  12 // but modifies the Mozilla Public License Version 1.1.
  13 // See the full license text for the amendments.
  14 //
  15 // Software distributed under the License is distributed on an "AS IS" basis,
  16 // WITHOUT WARRANTY OF ANY KIND, either express or implied. See the License
  17 // for the specific language governing rights and limitations under the License.
  18 //
  19 // The Original Code is Fraunhofer FOKUS code.
  20 //
  21 // The Initial Developer of the Original Code is Fraunhofer-Gesellschaft e.V.
  22 // (registered association), Hansastraße 27 c, 80686 Munich, Germany.
  23 // All Rights Reserved.
  24 //
  25 // Contributor(s):
  26 //   Stefan Bund <g0dil@berlios.de>
  27
  28 /** \file
  29     \brief EUI64 public header */
  30
  31 #ifndef HH_SENF_Socket_Protocols_Raw_EUI64_
  32 #define HH_SENF_Socket_Protocols_Raw_EUI64_ 1
  33
  34 // Custom includes
  35 #include <iostream>
  36 #include <boost/cstdint.hpp>
  37 #include <boost/array.hpp>
  38 #include <senf/Utils/Tags.hh>
  39 #include <senf/Utils/safe_bool.hh>
  40
  41 //#include "EUI64.mpp"
  42 //-/////////////////////////////////////////////////////////////////////////////////////////////////
  43
  44 namespace senf {
  45
  46     struct MACAddress;
  47
  48     /** \brief EUI-64 data type
  49
  50         An EUI-64 is a 64 bit (8 octet) id. The id is represented as an 8 byte sequence in network
  51         byte order. An EUI64 can be converted from/to several other representations
  52
  53         <table class="senf">
  54         <tr><td><tt>boost::uint64_t</tt></td>
  55                 <td><tt>senf::EUI64(0x1a2b3c4d5f607182ull)</tt><br/>
  56                     <i>eui64</i><tt>.uint64()</tt></td></tr>
  57         <tr><td><tt>std::string</tt></td>
  58                 <td><tt>senf::EUI64::from_string("1a:2b:3c:4d-5f:60:71:82")</tt><br/>
  59                     <tt>senf::str(</tt><i>eui64</i><tt>)</tt></td></tr>
  60         <tr><td><i>raw data</i><br/>&nbsp;&nbsp;&nbsp;&nbsp;(8 bytes)</td>
  61                 <td><tt>senf::EUI64::from_data(</tt><i>iterator</i><tt>)</tt><br/>
  62                     <i>eui64</i><tt>.begin()</tt></td></tr>
  63         <tr><td>senf::MACAddress<br/>&nbsp;&nbsp;&nbsp;&nbsp;(aka EUI-48)</td>
  64                 <td><tt>senf::EUI64::from_mac(</tt><i>mac-address</i><tt>)</tt><br/>
  65                     <tt>senf::MACAddress::from_eui64(</tt><i>eui64</i><tt>)</tt></td></tr>
  66         </table>
  67
  68         Since senf::EUI64 is based on \c boost::array, you can access the raw data bytes of the
  69         address using \c begin(), \c end() or \c operator[]:
  70         \code
  71         senf::EUI64 eui64 (...);
  72         std::vector<char> data;
  73         data.resize(8);
  74         std::copy(eui64.begin(), eui64.end(), data.begin()); // Copy 8 bytes
  75         \endcode
  76
  77         \see <a href="http://tools.ietf.org/html/rfc4291">RFC 4291</a>
  78
  79         \ingroup addr_group
  80      */
  81     struct EUI64
  82         : public boost::array<boost::uint8_t,8>,
  83           public senf::comparable_safe_bool<EUI64>
  84     {
  85         //-////////////////////////////////////////////////////////////////////////
  86         ///\name Structors and default members
  87         //\{
  88
  89         static EUI64 const None;        ///< The empty (0) address
  90
  91         explicit EUI64(boost::uint64_t v=0u); ///< Construct EUI-64
  92         explicit EUI64(senf::NoInit_t);       ///< Construct <em>uninitialized</em> EUI-64
  93
  94         static EUI64 from_mac(MACAddress const & mac);
  95                                         ///< Construct EUI-64 from senf::MACAddress
  96         static EUI64 from_string(std::string const & s);
  97                                         ///< Construct EUI-64 from string representation
  98                                         /**< The string representation consists of 8 octets in
  99                                              hexadecimal notation separated by ':' or '-'
 100                                              \throws senf::AddressSyntaxException */
 101         template <class InputIterator>
 102         static EUI64 from_data(InputIterator i);
 103                                         ///< Construct EUI-64 from 8 data octets
 104                                         /**< The iterator \a i must point to a sequence of 8
 105                                              octets in network byte order. */
 106
 107         //\}
 108         //-////////////////////////////////////////////////////////////////////////
 109
 110         bool isMACCompatible() const;   ///< \c true, if EUI64 is MAC compatible, \c false otherwise
 111                                         /**< An EUI64 is MAC compatible if bytes 4th and 5th byte
 112                                              (in network byte order) are 0xfffe. */
 113         bool local() const;             ///< \c true if the \e local bit is set, \c false otherwise
 114                                         /**< The \e local bit is the second least significant bit of
 115                                              the first octet (bit 6 in standard RFC bit numbering).
 116                                           */
 117         bool group() const;             ///< \c true if the \e group bit is set, \c false otherwise
 118                                         /**< The \e group bit is the least significant bit of the
 119                                              first octet (bit 7 in standard RFC bit numbering). */
 120         bool boolean_test() const;      ///< \c true, if EUI64 is != 0, \c false otherwise
 121         boost::uint64_t uint64() const; ///< Return EUI64 as integer number
 122     };
 123
 124     /** \brief Write out EUI64 in it's string representation to stream
 125         \related senf::EUI64
 126      */
 127     std::ostream & operator<<(std::ostream & os, EUI64 const & v);
 128
 129     /** \brief Read EUI64 string representation from stream
 130         \related senf::EUI64
 131      */
 132     std::istream & operator>>(std::istream & is, EUI64 & v);
 133
 134 }
 135
 136 //-/////////////////////////////////////////////////////////////////////////////////////////////////
 137 #include "EUI64.cci"
 138 //#include "EUI64.ct"
 139 #include "EUI64.cti"
 140 #endif
 141
 142 \f
 143 // Local Variables:
 144 // mode: c++
 145 // fill-column: 100
 146 // comment-column: 40
 147 // c-file-style: "senf"
 148 // indent-tabs-mode: nil
 149 // ispell-local-dictionary: "american"
 150 // compile-command: "scons -u test"
 151 // End: