A Discrete-Event Network Simulator
API
Loading...
Searching...
No Matches
address.h
Go to the documentation of this file.
1/*
2 * Copyright (c) 2007 INRIA
3 *
4 * SPDX-License-Identifier: GPL-2.0-only
5 *
6 * Author: Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
7 */
8
9#ifndef ADDRESS_H
10#define ADDRESS_H
11
12#include "tag-buffer.h"
13
14#include "ns3/attribute-helper.h"
15#include "ns3/attribute.h"
16
17#include <ostream>
18#include <stdint.h>
19
20namespace ns3
21{
22
23/**
24 * @ingroup network
25 * @defgroup address Address
26 *
27 * Network Address abstractions, including MAC, IPv4 and IPv6.
28 */
29/**
30 * @ingroup address
31 * @brief a polymophic address class
32 *
33 * This class is very similar in design and spirit to the BSD sockaddr
34 * structure: they are both used to hold multiple types of addresses
35 * together with the type of the address.
36 *
37 * A new address class defined by a user needs to:
38 * - allocate a type id with Address::Register
39 * - provide a method to convert his new address to an Address
40 * instance. This method is typically a member method named ConvertTo:
41 * Address MyAddress::ConvertTo () const;
42 * - provide a method to convert an Address instance back to
43 * an instance of his new address type. This method is typically
44 * a static member method of his address class named ConvertFrom:
45 * static MyAddress MyAddress::ConvertFrom (const Address &address);
46 * - the ConvertFrom method is expected to check that the type of the
47 * input Address instance is compatible with its own type.
48 *
49 * Typical code to create a new class type looks like:
50 * @code
51 * // this class represents addresses which are 2 bytes long.
52 * class MyAddress
53 * {
54 * public:
55 * Address ConvertTo () const;
56 * static MyAddress ConvertFrom ();
57 * private:
58 * static uint8_t GetType ();
59 * };
60 *
61 * Address MyAddress::ConvertTo () const
62 * {
63 * return Address (GetType (), m_buffer, 2);
64 * }
65 * MyAddress MyAddress::ConvertFrom (const Address &address)
66 * {
67 * MyAddress ad;
68 * NS_ASSERT (address.CheckCompatible (GetType (), 2));
69 * address.CopyTo (ad.m_buffer, 2);
70 * return ad;
71 * }
72 * uint8_t MyAddress::GetType ()
73 * {
74 * static uint8_t type = Address::Register ();
75 * return type;
76 * }
77 * @endcode
78 *
79 * To convert a specific Address T (e.g., Ipv6Address) to and from an Address type,
80 * a class must implement three public functions:
81 * @code
82 * static T ConvertFrom(const Address& address);
83 * Address ConvertTo() const;
84 * operator Address() const;
85 * @endcode
86 *
87 * @see attribute_Address
88 */
90{
91 public:
92 /**
93 * The maximum size of a byte buffer which
94 * can be stored in an Address instance.
95 */
96 static constexpr uint32_t MAX_SIZE{20};
97
98 /**
99 * Create an invalid address
100 */
101 Address();
102 /**
103 * @brief Create an address from a type and a buffer.
104 *
105 * This constructor is typically invoked from the conversion
106 * functions of various address types when they have to
107 * convert themselves to an Address instance.
108 *
109 * @param type the type of the Address to create
110 * @param buffer a pointer to a buffer of bytes which hold
111 * a serialized representation of the address in network
112 * byte order.
113 * @param len the length of the buffer.
114 */
115 Address(uint8_t type, const uint8_t* buffer, uint8_t len);
116 /**
117 * @brief Create an address from another address.
118 * @param address the address to copy
119 */
120 Address(const Address& address);
121 /**
122 * @brief Basic assignment operator.
123 * @param address the address to copy
124 * @returns the address
125 */
126 Address& operator=(const Address& address);
127
128 /**
129 * @returns true if this address is invalid, false otherwise.
130 *
131 * An address is invalid if and only if it was created
132 * through the default constructor and it was never
133 * re-initialized.
134 */
135 bool IsInvalid() const;
136 /**
137 * @brief Get the length of the underlying address.
138 * @returns the length of the underlying address.
139 */
140 uint8_t GetLength() const;
141 /**
142 * @brief Copy the address bytes into a buffer.
143 * @param buffer buffer to copy the address bytes to.
144 * @returns the number of bytes copied.
145 */
146 uint32_t CopyTo(uint8_t buffer[MAX_SIZE]) const;
147 /**
148 * @param buffer buffer to copy the whole address data structure to
149 * @param len the size of the buffer
150 * @returns the number of bytes copied.
151 *
152 * Copies the type to buffer[0], the length of the address internal buffer
153 * to buffer[1] and copies the internal buffer starting at buffer[2]. len
154 * must be at least the size of the internal buffer plus a byte for the type
155 * and a byte for the length.
156 */
157 uint32_t CopyAllTo(uint8_t* buffer, uint8_t len) const;
158 /**
159 * @param buffer pointer to a buffer of bytes which contain
160 * a serialized representation of the address in network
161 * byte order.
162 * @param len length of buffer
163 * @returns the number of bytes copied.
164 *
165 * Copy the address bytes from buffer into to the internal buffer of this
166 * address instance.
167 */
168 uint32_t CopyFrom(const uint8_t* buffer, uint8_t len);
169 /**
170 * @param buffer pointer to a buffer of bytes which contain
171 * a copy of all the members of this Address class.
172 * @param len the length of the buffer
173 * @returns the number of bytes copied.
174 *
175 * The inverse of CopyAllTo().
176 *
177 * @see CopyAllTo
178 */
179 uint32_t CopyAllFrom(const uint8_t* buffer, uint8_t len);
180 /**
181 * @param type a type id as returned by Address::Register
182 * @param len the length associated to this type id.
183 *
184 * @returns true if the type of the address stored internally
185 * is compatible with the requested type, false otherwise.
186 */
187 bool CheckCompatible(uint8_t type, uint8_t len) const;
188 /**
189 * @param type a type id as returned by Address::Register
190 * @returns true if the type of the address stored internally
191 * is compatible with the requested type, false otherwise.
192 *
193 * This method checks that the types are _exactly_ equal.
194 * This method is really used only by the PacketSocketAddress
195 * and there is little point in using it otherwise so,
196 * you have been warned: DO NOT USE THIS METHOD.
197 */
198 bool IsMatchingType(uint8_t type) const;
199 /**
200 * Allocate a new type id for a new type of address.
201 * @returns a new type id.
202 */
203 static uint8_t Register();
204 /**
205 * Get the number of bytes needed to serialize the underlying Address
206 * Typically, this is GetLength () + 2
207 *
208 * @returns the number of bytes required for an Address in serialized form
209 */
211 /**
212 * Serialize this address in host byte order to a byte buffer
213 *
214 * @param buffer output buffer that gets written with this Address
215 */
216 void Serialize(TagBuffer buffer) const;
217 /**
218 * @param buffer buffer to read address from
219 *
220 * The input address buffer is expected to be in host byte order format.
221 */
222 void Deserialize(TagBuffer buffer);
223
224 private:
225 /**
226 * @brief Equal to operator.
227 *
228 * @param a the first operand
229 * @param b the first operand
230 * @returns true if the operands are equal
231 */
232 friend bool operator==(const Address& a, const Address& b);
233
234 /**
235 * @brief Not equal to operator.
236 *
237 * @param a the first operand
238 * @param b the first operand
239 * @returns true if the operands are not equal
240 */
241 friend bool operator!=(const Address& a, const Address& b);
242
243 /**
244 * @brief Less than operator.
245 *
246 * @param a the first operand
247 * @param b the first operand
248 * @returns true if the operand a is less than operand b
249 */
250 friend bool operator<(const Address& a, const Address& b);
251
252 /**
253 * @brief Stream insertion operator.
254 *
255 * @param os the stream
256 * @param address the address
257 * @returns a reference to the stream
258 */
259 friend std::ostream& operator<<(std::ostream& os, const Address& address);
260
261 /**
262 * @brief Stream extraction operator.
263 *
264 * @param is the stream
265 * @param address the address
266 * @returns a reference to the stream
267 */
268 friend std::istream& operator>>(std::istream& is, Address& address);
269
270 uint8_t m_type; //!< Type of the address
271 uint8_t m_len; //!< Length of the address
272 uint8_t m_data[MAX_SIZE]; //!< The address value
273};
274
276
277bool operator==(const Address& a, const Address& b);
278bool operator!=(const Address& a, const Address& b);
279bool operator<(const Address& a, const Address& b);
280std::ostream& operator<<(std::ostream& os, const Address& address);
281std::istream& operator>>(std::istream& is, Address& address);
282
283} // namespace ns3
284
285#endif /* ADDRESS_H */
a polymophic address class
Definition address.h:90
friend std::istream & operator>>(std::istream &is, Address &address)
Stream extraction operator.
Definition address.cc:257
uint32_t GetSerializedSize() const
Get the number of bytes needed to serialize the underlying Address Typically, this is GetLength () + ...
Definition address.cc:144
void Serialize(TagBuffer buffer) const
Serialize this address in host byte order to a byte buffer.
Definition address.cc:151
uint32_t CopyFrom(const uint8_t *buffer, uint8_t len)
Definition address.cc:95
friend std::ostream & operator<<(std::ostream &os, const Address &address)
Stream insertion operator.
Definition address.cc:235
static constexpr uint32_t MAX_SIZE
The maximum size of a byte buffer which can be stored in an Address instance.
Definition address.h:96
bool IsInvalid() const
Definition address.cc:60
uint8_t m_len
Length of the address.
Definition address.h:271
uint8_t m_data[MAX_SIZE]
The address value.
Definition address.h:272
uint8_t m_type
Type of the address.
Definition address.h:270
Address & operator=(const Address &address)
Basic assignment operator.
Definition address.cc:49
Address()
Create an invalid address.
Definition address.cc:23
friend bool operator!=(const Address &a, const Address &b)
Not equal to operator.
Definition address.cc:195
uint32_t CopyAllFrom(const uint8_t *buffer, uint8_t len)
Definition address.cc:105
bool CheckCompatible(uint8_t type, uint8_t len) const
Definition address.cc:118
static uint8_t Register()
Allocate a new type id for a new type of address.
Definition address.cc:135
uint8_t GetLength() const
Get the length of the underlying address.
Definition address.cc:67
uint32_t CopyTo(uint8_t buffer[MAX_SIZE]) const
Copy the address bytes into a buffer.
Definition address.cc:75
void Deserialize(TagBuffer buffer)
Definition address.cc:160
friend bool operator<(const Address &a, const Address &b)
Less than operator.
Definition address.cc:201
bool IsMatchingType(uint8_t type) const
Definition address.cc:128
friend bool operator==(const Address &a, const Address &b)
Equal to operator.
Definition address.cc:172
uint32_t CopyAllTo(uint8_t *buffer, uint8_t len) const
Definition address.cc:84
read and write tag data
Definition tag-buffer.h:41
#define ATTRIBUTE_HELPER_HEADER(type)
Declare the attribute value, accessor and checkers for class type
Every class exported by the ns3 library is enclosed in the ns3 namespace.
bool operator!=(Callback< R, Args... > a, Callback< R, Args... > b)
Inequality test.
Definition callback.h:658
bool operator==(const EventId &a, const EventId &b)
Definition event-id.h:155
std::ostream & operator<<(std::ostream &os, const Angles &a)
Definition angles.cc:148
std::istream & operator>>(std::istream &is, Angles &a)
Definition angles.cc:172
bool operator<(const EventId &a, const EventId &b)
Definition event-id.h:168