00001 /* -*- Mode:C++; c-file-style:"gnu"; indent-tabs-mode:nil; -*- */ 00002 /* 00003 * Copyright (c) 2007 INRIA 00004 * 00005 * This program is free software; you can redistribute it and/or modify 00006 * it under the terms of the GNU General Public License version 2 as 00007 * published by the Free Software Foundation; 00008 * 00009 * This program is distributed in the hope that it will be useful, 00010 * but WITHOUT ANY WARRANTY; without even the implied warranty of 00011 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the 00012 * GNU General Public License for more details. 00013 * 00014 * You should have received a copy of the GNU General Public License 00015 * along with this program; if not, write to the Free Software 00016 * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA 00017 * 00018 * Author: Mathieu Lacage <mathieu.lacage@sophia.inria.fr> 00019 */ 00020 00021 #ifndef ADDRESS_H 00022 #define ADDRESS_H 00023 00024 #include <stdint.h> 00025 #include <ostream> 00026 #include "ns3/attribute.h" 00027 #include "ns3/attribute-helper.h" 00028 #include "ns3/tag-buffer.h" 00029 00030 namespace ns3 { 00031 00032 /** 00033 * \ingroup node 00034 * \defgroup address Address 00035 */ 00036 /** 00037 * \ingroup address 00038 * \brief a polymophic address class 00039 * 00040 * This class is very similar in design and spirit to the BSD sockaddr 00041 * structure: they are both used to hold multiple types of addresses 00042 * together with the type of the address. 00043 * 00044 * A new address class defined by a user needs to: 00045 * - allocate a type id with Address::Register 00046 * - provide a method to convert his new address to an Address 00047 * instance. This method is typically a member method named ConvertTo: 00048 * Address MyAddress::ConvertTo (void) const; 00049 * - provide a method to convert an Address instance back to 00050 * an instance of his new address type. This method is typically 00051 * a static member method of his address class named ConvertFrom: 00052 * static MyAddress MyAddress::ConvertFrom (const Address &address); 00053 * - the ConvertFrom method is expected to check that the type of the 00054 * input Address instance is compatible with its own type. 00055 * 00056 * Typical code to create a new class type looks like: 00057 * \code 00058 * // this class represents addresses which are 2 bytes long. 00059 * class MyAddress 00060 * { 00061 * public: 00062 * Address ConvertTo (void) const; 00063 * static MyAddress ConvertFrom (void); 00064 * private: 00065 * static uint8_t GetType (void); 00066 * }; 00067 * 00068 * Address MyAddress::ConvertTo (void) const 00069 * { 00070 * return Address (GetType (), m_buffer, 2); 00071 * } 00072 * MyAddress MyAddress::ConvertFrom (const Address &address) 00073 * { 00074 * MyAddress ad; 00075 * NS_ASSERT (address.CheckCompatible (GetType (), 2)); 00076 * address.CopyTo (ad.m_buffer, 2); 00077 * return ad; 00078 * } 00079 * uint8_t MyAddress::GetType (void) 00080 * { 00081 * static uint8_t type = Address::Register (); 00082 * return type; 00083 * } 00084 * \endcode 00085 */ 00086 class Address 00087 { 00088 public: 00089 /** 00090 * The maximum size of a byte buffer which 00091 * can be stored in an Address instance. 00092 */ 00093 enum MaxSize_e { 00094 MAX_SIZE = 30 00095 }; 00096 00097 /** 00098 * Create an invalid address 00099 */ 00100 Address (); 00101 /** 00102 * \param type the type of the Address to create 00103 * \param buffer a pointer to a buffer of bytes which hold 00104 * a serialized representation of the address in network 00105 * byte order. 00106 * \param len the length of the buffer. 00107 * 00108 * Create an address from a type and a buffer. This constructor 00109 * is typically invoked from the conversion functions of various 00110 * address types when they have to convert themselves to an 00111 * Address instance. 00112 */ 00113 Address (uint8_t type, const uint8_t *buffer, uint8_t len); 00114 Address (const Address & address); 00115 Address &operator = (const Address &address); 00116 00117 /** 00118 * \returns true if this address is invalid, false otherwise. 00119 * 00120 * An address is invalid if and only if it was created 00121 * through the default constructor and it was never 00122 * re-initialized. 00123 */ 00124 bool IsInvalid (void) const; 00125 /** 00126 * \returns the length of the underlying address. 00127 */ 00128 uint8_t GetLength (void) const; 00129 /** 00130 * \param buffer buffer to copy the address bytes to. 00131 * \returns the number of bytes copied. 00132 */ 00133 uint32_t CopyTo (uint8_t buffer[MAX_SIZE]) const; 00134 /** 00135 * \param buffer buffer to copy the whole address data structure to 00136 * \param len the size of the buffer 00137 * \returns the number of bytes copied. 00138 * 00139 * Copies the type to buffer[0], the length of the address internal buffer 00140 * to buffer[1] and copies the internal buffer starting at buffer[2]. len 00141 * must be at least the size of the internal buffer plus a byte for the type 00142 * and a byte for the length. 00143 */ 00144 uint32_t CopyAllTo (uint8_t *buffer, uint8_t len) const; 00145 /** 00146 * \param buffer pointer to a buffer of bytes which contain 00147 * a serialized representation of the address in network 00148 * byte order. 00149 * \param len length of buffer 00150 * \returns the number of bytes copied. 00151 * 00152 * Copy the address bytes from buffer into to the internal buffer of this 00153 * address instance. 00154 */ 00155 uint32_t CopyFrom (const uint8_t *buffer, uint8_t len); 00156 /** 00157 * \param buffer pointer to a buffer of bytes which contain 00158 * a copy of all the members of this Address class. 00159 * \param len the length of the buffer 00160 * \returns the number of bytes copied. 00161 * 00162 * The inverse of CopyAllTo(). 00163 * 00164 * \see CopyAllTo 00165 */ 00166 uint32_t CopyAllFrom (const uint8_t *buffer, uint8_t len); 00167 /** 00168 * \param type a type id as returned by Address::Register 00169 * \param len the length associated to this type id. 00170 * 00171 * \returns true if the type of the address stored internally 00172 * is compatible with the requested type, false otherwise. 00173 */ 00174 bool CheckCompatible (uint8_t type, uint8_t len) const; 00175 /** 00176 * \param type a type id as returned by Address::Register 00177 * \returns true if the type of the address stored internally 00178 * is compatible with the requested type, false otherwise. 00179 * 00180 * This method checks that the types are _exactly_ equal. 00181 * This method is really used only by the PacketSocketAddress 00182 * and there is little point in using it otherwise so, 00183 * you have been warned: DO NOT USE THIS METHOD. 00184 */ 00185 bool IsMatchingType (uint8_t type) const; 00186 /** 00187 * Allocate a new type id for a new type of address. 00188 * \returns a new type id. 00189 */ 00190 static uint8_t Register (void); 00191 /** 00192 * Get the number of bytes needed to serialize the underlying Address 00193 * Typically, this is GetLength () + 2 00194 * 00195 * \returns the number of bytes required for an Address in serialized form 00196 */ 00197 uint32_t GetSerializedSize (void) const; 00198 /** 00199 * Serialize this address in host byte order to a byte buffer 00200 * 00201 * \param buffer output buffer that gets written with this Address 00202 */ 00203 void Serialize (TagBuffer buffer) const; 00204 /** 00205 * \param buffer buffer to read address from 00206 * 00207 * The input address buffer is expected to be in host byte order format. 00208 */ 00209 void Deserialize (TagBuffer buffer); 00210 00211 private: 00212 friend bool operator == (const Address &a, const Address &b); 00213 friend bool operator < (const Address &a, const Address &b); 00214 friend std::ostream& operator<< (std::ostream& os, const Address & address); 00215 friend std::istream& operator>> (std::istream& is, Address & address); 00216 00217 uint8_t m_type; 00218 uint8_t m_len; 00219 uint8_t m_data[MAX_SIZE]; 00220 }; 00221 00222 /** 00223 * \class ns3::AddressValue 00224 * \brief hold objects of type ns3::Address 00225 */ 00226 00227 ATTRIBUTE_HELPER_HEADER (Address); 00228 00229 bool operator == (const Address &a, const Address &b); 00230 bool operator != (const Address &a, const Address &b); 00231 bool operator < (const Address &a, const Address &b); 00232 std::ostream& operator<< (std::ostream& os, const Address & address); 00233 std::istream& operator>> (std::istream& is, Address & address); 00234 00235 00236 } // namespace ns3 00237 00238 #endif /* ADDRESS_H */