a polymophic address class More...

#include "address.h"

Collaboration diagram for ns3::Address:

Classes
struct	KeyHash
	Structure necessary to hash KindType, used as the key for the m_typeRegistry map. More...

Public Member Functions
	Address ()
	Create an invalid address.
	Address (const Address &address)
	Create an address from another address.
	Address (uint8_t type, const uint8_t *buffer, uint8_t len)
	Create an address from a type and a buffer.
bool	CheckCompatible (uint8_t type, uint8_t len) const
uint32_t	CopyAllFrom (const uint8_t *buffer, uint8_t len)
uint32_t	CopyAllTo (uint8_t *buffer, uint8_t len) const
uint32_t	CopyFrom (const uint8_t *buffer, uint8_t len)
uint32_t	CopyTo (uint8_t buffer[MAX_SIZE]) const
	Copy the address bytes into a buffer.
void	Deserialize (TagBuffer buffer)
uint8_t	GetLength () const
	Get the length of the underlying address.
uint32_t	GetSerializedSize () const
	Get the number of bytes needed to serialize the underlying Address Typically, this is GetLength () + 2.
bool	IsInvalid () const
bool	IsMatchingType (uint8_t type) const
Address &	operator= (const Address &address)
	Basic assignment operator.
void	Serialize (TagBuffer buffer) const
	Serialize this address in host byte order to a byte buffer.
void	SetType (const std::string &kind, uint8_t length)
	Set the address type.

Static Public Member Functions
static uint8_t	Register (const std::string &kind, uint8_t length)
	Allocate a new type id for a new type of address.

Static Public Attributes
static constexpr uint32_t	MAX_SIZE {20}
	The maximum size of a byte buffer which can be stored in an Address instance.

Private Types
using	KindType = std::pair<std::string, uint8_t>
	Key for the address registry: kind (string) / type (uint8_t).
using	KindTypeRegistry = std::unordered_map<KindType, uint8_t, Address::KeyHash>
	Type of the address registry.

Private Attributes
uint8_t	m_data [MAX_SIZE]
	The address value.
uint8_t	m_len
	Length of the address.
uint8_t	m_type
	Type of the address.

Static Private Attributes
static KindTypeRegistry	m_typeRegistry
	Container of allocated address types.
static constexpr uint8_t	UNASSIGNED_TYPE {0}
	Unassigned Address type is reserved. Defined for clarity.

Friends
bool	operator!= (const Address &a, const Address &b)
	Not equal to operator.
bool	operator< (const Address &a, const Address &b)
	Less than operator.
std::ostream &	operator<< (std::ostream &os, const Address &address)
	Stream insertion operator.
bool	operator== (const Address &a, const Address &b)
	Equal to operator.
std::istream &	operator>> (std::istream &is, Address &address)
	Stream extraction operator.

Detailed Description

a polymophic address class

This class is very similar in design and spirit to the BSD sockaddr structure: they are both used to hold multiple types of addresses together with the type of the address.

A new address class defined by a user needs to:

allocate a type id with Address::Register
provide a method to convert his new address to an Address instance. This method is typically a member method named ConvertTo: Address MyAddress::ConvertTo () const;
provide a method to convert an Address instance back to an instance of his new address type. This method is typically a static member method of his address class named ConvertFrom: static MyAddress MyAddress::ConvertFrom (const Address &address);
the ConvertFrom method is expected to check that the type of the input Address instance is compatible with its own type.

Typical code to create a new class type looks like:

// this class represents addresses which are 2 bytes long.
class MyAddress
{
public:
  Address ConvertTo () const;
  static MyAddress ConvertFrom ();
private:
  static uint8_t GetType ();
};
 
Address MyAddress::ConvertTo () const
{
  return Address (GetType (), m_buffer, 2);
}
 
MyAddress MyAddress::ConvertFrom (const Address &address)
{
  MyAddress ad;
  NS_ASSERT (address.CheckCompatible (GetType (), 2));
  address.CopyTo (ad.m_buffer, 2);
  return ad;
}
 
uint8_t MyAddress::GetType ()
{
  static uint8_t type = Address::Register ("AddressType", 2);
  return type;
}

To convert a specific Address T (e.g., Ipv6Address) to and from an Address type, a class must implement three public functions:

static T ConvertFrom(const Address& address);
Address ConvertTo() const;
operator Address() const;

Furthermore, the specific address must call the static function Address::Register(kind, length). This is typically done in a static function like GetType.

The kind/length pair is used to set the address type when this is not known a-priori. The typical use-case is when you decode a header where the address kind is known, but its length is specified in the header itself. The concrete example is the ARP or NDP headers, where you have a MAC address with a variable length. In these cases the code will be (assuming the address is a MAC address):

Address addr;
addr.SetType("MacAddress", addressLen);
ReadFrom(i, addr, addressLen);

It is forbidden to have two specific addresses sharing the same kind and length.

See also: Address Attribute

Definition at line 110 of file address.h.

Member Typedef Documentation

◆ KindType

using ns3::Address::KindType = std::pair<std::string, uint8_t>

private

Key for the address registry: kind (string) / type (uint8_t).

Definition at line 116 of file address.h.

◆ KindTypeRegistry

using ns3::Address::KindTypeRegistry = std::unordered_map<KindType, uint8_t, Address::KeyHash>

private

Type of the address registry.

Definition at line 137 of file address.h.

Constructor & Destructor Documentation

◆ Address() [1/3]

ns3::Address::Address ( )

Create an invalid address.

Definition at line 25 of file address.cc.

References m_len, m_type, NS_LOG_FUNCTION, and UNASSIGNED_TYPE.

Referenced by Address(), operator!=, operator<, operator<<, operator=(), operator==, and operator>>.

Here is the caller graph for this function:

◆ Address() [2/3]

ns3::Address::Address	(	uint8_t	type,
		const uint8_t *	buffer,
		uint8_t	len )

Create an address from a type and a buffer.

This constructor is typically invoked from the conversion functions of various address types when they have to convert themselves to an Address instance.

Parameters

type	the type of the Address to create
buffer	a pointer to a buffer of bytes which hold a serialized representation of the address in network byte order.
len	the length of the buffer.

Definition at line 33 of file address.cc.

References m_data, m_len, m_type, MAX_SIZE, NS_ASSERT_MSG, NS_LOG_FUNCTION, and UNASSIGNED_TYPE.

◆ Address() [3/3]

ns3::Address::Address ( const Address & address )

Create an address from another address.

Parameters

address the address to copy

Definition at line 43 of file address.cc.

References Address(), m_data, m_len, m_type, MAX_SIZE, and NS_ASSERT.

Here is the call graph for this function:

Member Function Documentation

◆ CheckCompatible()

bool ns3::Address::CheckCompatible	(	uint8_t	type,
		uint8_t	len ) const

Parameters

type	a type id as returned by Address::Register
len	the length associated to this type id.

Returns: true if the type of the address stored internally is compatible with the requested type, false otherwise.

Definition at line 141 of file address.cc.

References m_len, m_type, MAX_SIZE, NS_ASSERT, and NS_LOG_FUNCTION.

Referenced by ns3::Inet6SocketAddress::ConvertFrom(), and ns3::Inet6SocketAddress::IsMatchingType().

Here is the caller graph for this function:

◆ CopyAllFrom()

uint32_t ns3::Address::CopyAllFrom	(	const uint8_t *	buffer,
		uint8_t	len )

Parameters

buffer	pointer to a buffer of bytes which contain a copy of all the members of this Address class.
len	the length of the buffer

Returns: the number of bytes copied.

The inverse of CopyAllTo().

See also: CopyAllTo

Definition at line 128 of file address.cc.

References m_data, m_len, m_type, NS_ASSERT, and NS_LOG_FUNCTION.

Referenced by ns3::PacketSocketAddress::ConvertFrom().

Here is the caller graph for this function:

◆ CopyAllTo()

uint32_t ns3::Address::CopyAllTo	(	uint8_t *	buffer,
		uint8_t	len ) const

Parameters

buffer	buffer to copy the whole address data structure to
len	the size of the buffer

Returns: the number of bytes copied.

Copies the type to buffer[0], the length of the address internal buffer to buffer[1] and copies the internal buffer starting at buffer[2]. len must be at least the size of the internal buffer plus a byte for the type and a byte for the length.

Definition at line 105 of file address.cc.

References m_data, m_len, m_type, NS_ASSERT, and NS_LOG_FUNCTION.

◆ CopyFrom()

uint32_t ns3::Address::CopyFrom	(	const uint8_t *	buffer,
		uint8_t	len )

Parameters

buffer	pointer to a buffer of bytes which contain a serialized representation of the address in network byte order.
len	length of buffer

Returns: the number of bytes copied.

Copy the address bytes from buffer into to the internal buffer of this address instance.

Definition at line 116 of file address.cc.

References m_data, m_len, m_type, MAX_SIZE, NS_ASSERT_MSG, NS_LOG_FUNCTION, and UNASSIGNED_TYPE.

Referenced by ns3::ReadFrom().

Here is the caller graph for this function:

◆ CopyTo()

uint32_t ns3::Address::CopyTo ( uint8_t buffer[MAX_SIZE] ) const

Copy the address bytes into a buffer.

Parameters

buffer buffer to copy the address bytes to.

Returns: the number of bytes copied.

Definition at line 96 of file address.cc.

References m_data, m_len, MAX_SIZE, NS_ASSERT, and NS_LOG_FUNCTION.

Referenced by ns3::IdentifierOption::IdentifierOption(), ns3::DhcpServer::AddStaticDhcpEntry(), ns3::OpenFlowSwitchNetDevice::BufferFromPacket(), ns3::Inet6SocketAddress::ConvertFrom(), ns3::SixLowPanNetDevice::Get16MacFrom48Mac(), ns3::ArpQueueDiscItem::Hash(), ns3::Duid::Initialize(), ns3::lrwpan::LrWpanNetDevice::Send(), ns3::UanNetDevice::Send(), ns3::Dhcp6Header::Serialize(), ns3::DhcpClient::StartApplication(), and ns3::WriteTo().

Here is the caller graph for this function:

◆ Deserialize()

void ns3::Address::Deserialize ( TagBuffer buffer )

Parameters

buffer buffer to read address from

The input address buffer is expected to be in host byte order format.

Definition at line 184 of file address.cc.

References m_data, m_len, m_type, MAX_SIZE, NS_ASSERT, NS_LOG_FUNCTION, ns3::TagBuffer::Read(), and ns3::TagBuffer::ReadU8().

Here is the call graph for this function:

◆ GetLength()

uint8_t ns3::Address::GetLength ( ) const

Get the length of the underlying address.

Returns: the length of the underlying address.

Definition at line 88 of file address.cc.

References m_len, MAX_SIZE, NS_ASSERT, and NS_LOG_FUNCTION.

Referenced by ns3::IdentifierOption::IdentifierOption(), ns3::DhcpServer::AddStaticDhcpEntry(), ns3::ArpQueueDiscItem::Hash(), ns3::Duid::Initialize(), operator<, ns3::Icmpv6L4Protocol::SendRedirection(), ns3::DhcpClient::StartApplication(), and ns3::WriteTo().

Here is the caller graph for this function:

◆ GetSerializedSize()

uint32_t ns3::Address::GetSerializedSize ( ) const

Get the number of bytes needed to serialize the underlying Address Typically, this is GetLength () + 2.

Returns: the number of bytes required for an Address in serialized form

Definition at line 168 of file address.cc.

References m_len, and NS_LOG_FUNCTION.

◆ IsInvalid()

bool ns3::Address::IsInvalid ( ) const

Returns: true if this address is invalid, false otherwise.

An address is invalid if and only if it was created through the default constructor and it was never re-initialized.

Definition at line 81 of file address.cc.

References m_len, m_type, NS_LOG_FUNCTION, and UNASSIGNED_TYPE.

Referenced by ns3::Duid::Initialize(), ns3::ThreeGppHttpServer::SetLocal(), ns3::SourceApplication::SetRemote(), ns3::ThreeGppHttpClient::SetRemote(), ns3::UdpClient::SetRemote(), ns3::UdpEchoClient::SetRemote(), and ns3::UdpTraceClient::SetRemote().

Here is the caller graph for this function:

◆ IsMatchingType()

bool ns3::Address::IsMatchingType ( uint8_t type ) const

Parameters

type	a type id as returned by Address::Register

Returns: true if the type of the address stored internally is compatible with the requested type, false otherwise.

This method checks that the types are exactly equal. This method is really used only by the PacketSocketAddress and there is little point in using it otherwise so, you have been warned: DO NOT USE THIS METHOD.

Definition at line 149 of file address.cc.

References m_type, and NS_LOG_FUNCTION.

◆ operator=()

Address & ns3::Address::operator= ( const Address & address )

Basic assignment operator.

Parameters

address the address to copy

Returns: the address

Definition at line 52 of file address.cc.

References Address(), m_data, m_len, m_type, MAX_SIZE, and NS_ASSERT.

Here is the call graph for this function:

◆ Register()

uint8_t ns3::Address::Register	(	const std::string &	kind,
		uint8_t	length )

static

Allocate a new type id for a new type of address.

Each address-like class that needs to be converted to/from an Address needs to register itself once. This is typically done in the GetType function.

The address kind and length are typically used during the buffer deserialization, where the exact address type is unknown, and only its kind and length are known, e.g., if you parse an ARP reply.

It is not allowed to have two different addresses with the same kind and length.

Parameters

length	address length
kind	address kind, such as "MacAddress"

Returns: a new type id.

Definition at line 156 of file address.cc.

References m_typeRegistry, NS_ASSERT_MSG, NS_LOG_FUNCTION, and UNASSIGNED_TYPE.

Referenced by ns3::Inet6SocketAddress::GetType(), ns3::InetSocketAddress::GetType(), ns3::Ipv4Address::GetType(), ns3::Ipv6Address::GetType(), ns3::Mac16Address::GetType(), ns3::Mac48Address::GetType(), ns3::Mac64Address::GetType(), ns3::Mac8Address::GetType(), and ns3::PacketSocketAddress::GetType().

Here is the caller graph for this function:

◆ Serialize()

void ns3::Address::Serialize ( TagBuffer buffer ) const

Serialize this address in host byte order to a byte buffer.

Parameters

buffer output buffer that gets written with this Address

Definition at line 175 of file address.cc.

References m_data, m_len, m_type, NS_LOG_FUNCTION, ns3::TagBuffer::Write(), and ns3::TagBuffer::WriteU8().

Here is the call graph for this function:

◆ SetType()

void ns3::Address::SetType	(	const std::string &	kind,
		uint8_t	length )

Set the address type.

Works only if the type is not yet set.

See also: Register()

Parameters

length	address length
kind	address kind

Definition at line 63 of file address.cc.

References m_type, m_typeRegistry, NS_ASSERT_MSG, NS_LOG_FUNCTION, and UNASSIGNED_TYPE.

◆ operator!=

bool operator!=	(	const Address &	a,
		const Address &	b )

friend

Not equal to operator.

Parameters

a	the first operand
b	the first operand

Returns: true if the operands are not equal

Definition at line 210 of file address.cc.

References Address().

◆ operator<

bool operator<	(	const Address &	a,
		const Address &	b )

friend

Less than operator.

Parameters

a	the first operand
b	the first operand

Returns: true if the operand a is less than operand b

Definition at line 215 of file address.cc.

References Address(), GetLength(), m_data, m_len, m_type, and NS_ASSERT.

◆ operator<<

std::ostream & operator<<	(	std::ostream &	os,
		const Address &	address )

friend

Stream insertion operator.

Parameters

os	the stream
address	the address

Returns: a reference to the stream

Definition at line 249 of file address.cc.

References Address().

◆ operator==

bool operator==	(	const Address &	a,
		const Address &	b )

friend

Equal to operator.

Parameters

a	the first operand
b	the first operand

Returns: true if the operands are equal

Definition at line 196 of file address.cc.

References Address(), m_data, m_len, and m_type.

◆ operator>>

std::istream & operator>>	(	std::istream &	is,
		Address &	address )

friend

Stream extraction operator.

Parameters

is	the stream
address	the address

Returns: a reference to the stream

Definition at line 273 of file address.cc.

References Address(), MAX_SIZE, NS_ASSERT, and v.

Member Data Documentation

◆ m_data

uint8_t ns3::Address::m_data[MAX_SIZE]

private

The address value.

Definition at line 354 of file address.h.

Referenced by Address(), Address(), CopyAllFrom(), CopyAllTo(), CopyFrom(), CopyTo(), Deserialize(), operator<, operator=(), operator==, and Serialize().

◆ m_len

uint8_t ns3::Address::m_len

private

Length of the address.

Definition at line 353 of file address.h.

Referenced by Address(), Address(), Address(), CheckCompatible(), CopyAllFrom(), CopyAllTo(), CopyFrom(), CopyTo(), Deserialize(), GetLength(), GetSerializedSize(), IsInvalid(), operator<, operator=(), operator==, and Serialize().

◆ m_type

uint8_t ns3::Address::m_type

private

Type of the address.

Definition at line 352 of file address.h.

Referenced by Address(), Address(), Address(), CheckCompatible(), CopyAllFrom(), CopyAllTo(), CopyFrom(), Deserialize(), IsInvalid(), IsMatchingType(), operator<, operator=(), operator==, Serialize(), and SetType().

◆ m_typeRegistry

Address::KindTypeRegistry ns3::Address::m_typeRegistry

staticprivate

Container of allocated address types.

The data is ordered by KindType (a {kind, length} pair), and sores the address type.

Definition at line 144 of file address.h.

Referenced by Register(), and SetType().

◆ MAX_SIZE

uint32_t ns3::Address::MAX_SIZE {20}

staticconstexpr

The maximum size of a byte buffer which can be stored in an Address instance.

Definition at line 154 of file address.h.

Referenced by Address(), Address(), ns3::TcpHeader::CalculateHeaderChecksum(), ns3::UdpHeader::CalculateHeaderChecksum(), CheckCompatible(), ns3::PacketSocketAddress::ConvertFrom(), ns3::PacketSocketAddress::ConvertTo(), CopyFrom(), CopyTo(), Deserialize(), GetLength(), ns3::PacketSocketAddress::GetType(), operator=(), operator>>, ns3::ReadFrom(), and ns3::WriteTo().

◆ UNASSIGNED_TYPE

uint8_t ns3::Address::UNASSIGNED_TYPE {0}

staticconstexprprivate

Unassigned Address type is reserved. Defined for clarity.

Definition at line 147 of file address.h.

Referenced by Address(), Address(), CopyFrom(), IsInvalid(), Register(), and SetType().

The documentation for this class was generated from the following files:

src/network/model/address.h
src/network/model/address.cc

Classes

Public Member Functions

Static Public Member Functions

Static Public Attributes

Private Types

Private Attributes

Static Private Attributes

Friends

Detailed Description

Member Typedef Documentation

◆ KindType

◆ KindTypeRegistry

Constructor & Destructor Documentation

◆ Address() [1/3]

◆ Address() [2/3]

◆ Address() [3/3]

Member Function Documentation

◆ CheckCompatible()

◆ CopyAllFrom()

◆ CopyAllTo()

◆ CopyFrom()

◆ CopyTo()

◆ Deserialize()

◆ GetLength()

◆ GetSerializedSize()

◆ IsInvalid()

◆ IsMatchingType()

◆ operator=()

◆ Register()

◆ Serialize()

◆ SetType()

Friends And Related Symbol Documentation

◆ operator!=

◆ operator<

◆ operator<<

◆ operator==

◆ operator>>

Member Data Documentation

◆ m_data

◆ m_len

◆ m_type

◆ m_typeRegistry

◆ MAX_SIZE

◆ UNASSIGNED_TYPE