E-MailRelay

Classes | Public Types | Public Member Functions | Static Public Member Functions | List of all members
GNet::Address Class Reference

The GNet::Address class encapsulates a TCP/UDP transport address. More...

`#include <gaddress.h>`

## Classes
struct | Domain
| Overload discriminator for Address::supports() More...
struct | NotLocal
| Overload discriminator for Address::parse() More...

## Public Types
enum class | Family { ipv4 , ipv6 , local }

## Public Member Functions
| Address (const Address &)
| Copy constructor. More...
| Address (const AddressStorage &)
| Constructor taking a storage object. More...
| Address (const sockaddr *addr, socklen_t len)
| Constructor using a given sockaddr. More...
| Address (const sockaddr *addr, socklen_t len, bool fixup)
| An overload that conditionally applies the bsd ipv6 scope-id fixup. More...
| Address (Family, unsigned int port)
| Constructor for a wildcard address like INADDR_ANY with the given port number. More...
| Address (Address &&) noexcept
| Move constructor.
| ~Address ()
| Destructor.
Address & | operator= (const Address &)
| Assignment operator. More...
Address & | operator= (Address &&) noexcept
| Move assignment operator.
| operator G::BasicAddress () const
| Returns a G::BasicAddress. More...
const sockaddr * | address () const
| Returns the sockaddr address. More...
sockaddr * | address ()
| This is a non-const version of address() for compiling on systems which are not properly const-clean. More...
socklen_t | length () const
| Returns the size of the sockaddr address. See address(). More...
std::string | displayString (bool with_scope_id=false) const
| Returns a printable string that represents the transport address. More...
std::string | hostPartString () const
| Returns a printable string that represents the network address. More...
std::string | queryString () const
| Returns a string that can be used as a prefix for rDNS or DNSBL queries. More...
unsigned int | port () const
| Returns port part of the address. More...
Family | family () const noexcept
| Returns the address family enumeration. More...
int | af () const noexcept
| Returns the address family number such as AF_INET or AFINET6. More...
bool | sameHostPart (const Address &other) const
| Returns true if the two addresses have the same host part (ie. More...
Address & | setPort (unsigned int port)
| Sets the port number. More...
bool | setZone (const std::string &)
| Sets the zone. More...
Address & | setScopeId (unsigned long)
| Sets the scope-id. More...
unsigned long | scopeId (unsigned long default_=0UL) const
| Returns the scope-id. More...
G::StringArray | wildcards () const
| Returns an ordered list of wildcard strings that match this address. More...
unsigned int | bits () const
| Returns the number of leading bits set, relevant only to netmask addresses. More...
bool | isLoopback () const
| Returns true if this is a loopback address. More...
bool | isLinkLocal () const
| Returns true if this is a link-local address. More...
bool | isUniqueLocal () const
| Returns true if this is a locally administered address. More...
bool | isAny () const
| Returns true if this is the address family's 'any' address. More...
bool | isLocal (std::string &reason) const
| Returns true if this seems to be a 'local' address, ie. More...
bool | isMulticast () const
| Returns true if this is a multicast address. More...
bool | is4 () const noexcept
| Returns true if family() is ipv4. More...
bool | is6 () const noexcept
| Returns true if family() is ipv6. More...
bool | same (const Address &, bool ipv6_compare_with_scope) const
| Comparison function. More...
bool | operator== (const Address &) const
| Comparison operator. More...
bool | operator!= (const Address &) const
| Comparison operator. More...
void | swap (Address &other) noexcept
| Swaps this with other. More...

## Static Public Member Functions
static bool | supports (Family) noexcept
| Returns true if the implementation supports the given address family. More...
static bool | supports (int af, int dummy) noexcept
| Returns true if the implementation supports the given address family given as AF_INET etc. More...
static bool | supports (const Domain &, int domain) noexcept
| Returns true if the implementation supports the given address domain given as PF_INET etc. More...
static Address | parse (std::string_view display_string)
| Factory function for any address family. More...
static Address | parse (std::string_view display_string, NotLocal)
| Factory function for Family::ipv4 or Family::ipv6. More...
static Address | parse (std::string_view host_part_string, unsigned int port)
| Factory function for Family::ipv4 or Family::ipv6. More...
static Address | parse (std::string_view host_part_string, std::string_view port)
| Factory function for Family::ipv4 or Family::ipv6. More...
static bool | isFamilyLocal (std::string_view display_string) noexcept
| Returns true if the given address display string looks will parse to Family::local and Family::local is supported. More...
static Address | defaultAddress ()
| Returns a default address, being the IPv4 wildcard address with a zero port number. More...
static Address | loopback (Family, unsigned int port=0U)
| Returns a loopback address. More...
static int | domain (Family) noexcept
| Returns the address 'domain' for the given family, eg. More...
static bool | validPort (unsigned int n)
| Returns true if the port number is within the valid range. More...
static bool | validString (std::string_view display_string, std::string *reason=nullptr)
| Returns true if the transport-address display string is valid. More...
static bool | validString (std::string_view display_string, NotLocal, std::string *reason=nullptr)
| Returns true if the transport-address display string is valid. More...
static bool | validStrings (std::string_view ip, std::string_view port_string, std::string *reason=nullptr)
| Returns true if the combined network-address string and port string is valid. More...
static bool | validData (const sockaddr *, socklen_t len)
| Returns true if the sockaddr data is valid. More...

## Detailed Description

The GNet::Address class encapsulates a TCP/UDP transport address.

The address is exposed as a 'sockaddr' structure for low-level socket operations.

A multi-pimple pattern is used for the implementation, with implementation classes including GNet::Address4 and GNet::Address6. In an IPv4-only build the GNet::Address6 can be forward-declared but not defined, with all methods forwarded to the GNet::Address4 sub-object.

Unix domain addresses are supported by the GNet::AddressLocal implementation class. Port numbers are not expected when parsing and port numbers are not included in the display string. Unix domain addresses are only allowed to be absolute filesystem paths starting with '/' and with no unprintable characters, or the well-defined zero-length address (for unbound sockets) which is given the display string of "/". Paths with funny characters or linux-specific abstract addresses (see man unix(7)) will throw.

See also
  GNet::Resolver

Definition at line 62 of file gaddress.h.

## Member Enumeration Documentation

## ◆ Family

enum class GNet::Address::Family
| strong

Definition at line 65 of file gaddress.h.

## Constructor & Destructor Documentation

## ◆ Address() [1/5]

GNet::Address::Address | ( | const Address & | other | ) |

Copy constructor.

Definition at line 144 of file gaddress.cpp.

## ◆ Address() [2/5]

GNet::Address::Address | ( | const AddressStorage & | storage | ) |
| explicit

Constructor taking a storage object.

Definition at line 88 of file gaddress.cpp.

## ◆ Address() [3/5]

GNet::Address::Address | ( | const sockaddr * | addr,
|  | socklen_t | len
| ) |  |

Constructor using a given sockaddr.

Throws an exception if an invalid structure. See also: validData()

Definition at line 83 of file gaddress.cpp.

## ◆ Address() [4/5]

GNet::Address::Address | ( | const sockaddr * | addr,
|  | socklen_t | len,
|  | bool | fixup
| ) |  |

An overload that conditionally applies the bsd ipv6 scope-id fixup.

Definition at line 67 of file gaddress.cpp.

## ◆ Address() [5/5]

GNet::Address::Address | ( | Family | f,
|  | unsigned int | port
| ) |  |

Constructor for a wildcard address like INADDR_ANY with the given port number.

Throws an exception if an invalid port number. Postcondition: isAny()

See also
  validPort()

Definition at line 55 of file gaddress.cpp.

## Member Function Documentation

## ◆ address() [1/2]

sockaddr * GNet::Address::address | ( |  | ) |

This is a non-const version of address() for compiling on systems which are not properly const-clean.

Definition at line 407 of file gaddress.cpp.

## ◆ address() [2/2]

const sockaddr * GNet::Address::address | ( |  | ) | const

Returns the sockaddr address.

Typically used when making socket system calls. Never returns nullptr.

Definition at line 417 of file gaddress.cpp.

## ◆ af()

int GNet::Address::af | ( |  | ) | const
| noexcept

Returns the address family number such as AF_INET or AFINET6.

Definition at line 482 of file gaddress.cpp.

## ◆ bits()

unsigned int GNet::Address::bits | ( |  | ) | const

Returns the number of leading bits set, relevant only to netmask addresses.

Definition at line 247 of file gaddress.cpp.

## ◆ defaultAddress()

GNet::Address GNet::Address::defaultAddress | ( |  | ) |
| static

Returns a default address, being the IPv4 wildcard address with a zero port number.

Definition at line 203 of file gaddress.cpp.

## ◆ displayString()

std::string GNet::Address::displayString | ( | bool | with_scope_id = `false` | ) | const

Returns a printable string that represents the transport address.

Definition at line 356 of file gaddress.cpp.

## ◆ domain()

int GNet::Address::domain | ( | Family | family | ) |
| static noexcept

Returns the address 'domain' for the given family, eg.

PF_INET for Family::ipv4.

Definition at line 466 of file gaddress.cpp.

## ◆ family()

GNet::Address::Family GNet::Address::family | ( |  | ) | const
| noexcept

Returns the address family enumeration.

Definition at line 474 of file gaddress.cpp.

## ◆ hostPartString()

std::string GNet::Address::hostPartString | ( |  | ) | const

Returns a printable string that represents the network address.

Definition at line 365 of file gaddress.cpp.

## ◆ is4()

bool GNet::Address::is4 | ( |  | ) | const
| noexcept

Returns true if family() is ipv4.

Definition at line 312 of file gaddress.cpp.

## ◆ is6()

bool GNet::Address::is6 | ( |  | ) | const
| noexcept

Returns true if family() is ipv6.

Definition at line 317 of file gaddress.cpp.

## ◆ isAny()

bool GNet::Address::isAny | ( |  | ) | const

Returns true if this is the address family's 'any' address.

Definition at line 303 of file gaddress.cpp.

## ◆ isFamilyLocal()

bool GNet::Address::isFamilyLocal | ( | std::string_view | display_string | ) |
| static noexcept

Returns true if the given address display string looks will parse to Family::local and Family::local is supported.

The address may still fail to parse if it is invalid.

Definition at line 198 of file gaddress.cpp.

## ◆ isLinkLocal()

bool GNet::Address::isLinkLocal | ( |  | ) | const

Returns true if this is a link-local address.

Definition at line 274 of file gaddress.cpp.

## ◆ isLocal()

bool GNet::Address::isLocal | ( | std::string & | reason | ) | const

Returns true if this seems to be a 'local' address, ie.

an address that is likely to be more trusted. Returns an explanation by reference otherwise.

Definition at line 265 of file gaddress.cpp.

## ◆ isLoopback()

bool GNet::Address::isLoopback | ( |  | ) | const

Returns true if this is a loopback address.

Definition at line 256 of file gaddress.cpp.

## ◆ isMulticast()

bool GNet::Address::isMulticast | ( |  | ) | const

Returns true if this is a multicast address.

Definition at line 284 of file gaddress.cpp.

## ◆ isUniqueLocal()

bool GNet::Address::isUniqueLocal | ( |  | ) | const

Returns true if this is a locally administered address.

Definition at line 294 of file gaddress.cpp.

## ◆ length()

socklen_t GNet::Address::length | ( |  | ) | const

Returns the size of the sockaddr address. See address().

Definition at line 426 of file gaddress.cpp.

## ◆ loopback()

GNet::Address GNet::Address::loopback | ( | Family | f,
|  | unsigned int | port = `0U`
| ) |  |
| static

Returns a loopback address.

Definition at line 208 of file gaddress.cpp.

## ◆ operator G::BasicAddress()

GNet::Address::operator G::BasicAddress | ( |  | ) | const

Returns a G::BasicAddress.

Definition at line 213 of file gaddress.cpp.

## ◆ operator!=()

bool GNet::Address::operator!= | ( | const Address & | other | ) | const

Comparison operator.

Definition at line 340 of file gaddress.cpp.

## ◆ operator=()

GNet::Address & GNet::Address::operator= | ( | const Address & | other | ) |

Assignment operator.

Definition at line 169 of file gaddress.cpp.

## ◆ operator==()

bool GNet::Address::operator== | ( | const Address & | other | ) | const

Comparison operator.

Definition at line 331 of file gaddress.cpp.

## ◆ parse() [1/4]

GNet::Address GNet::Address::parse | ( | std::string_view | display_string | ) |
| static

Factory function for any address family.

Throws if an invalid string. See also validString().

Definition at line 178 of file gaddress.cpp.

## ◆ parse() [2/4]

GNet::Address GNet::Address::parse | ( | std::string_view | display_string,
|  | Address::NotLocal |
| ) |  |
| static

Factory function for Family::ipv4 or Family::ipv6.

Throws if an invalid string. See also validString().

Definition at line 183 of file gaddress.cpp.

## ◆ parse() [3/4]

GNet::Address GNet::Address::parse | ( | std::string_view | host_part_string,
|  | std::string_view | port
| ) |  |
| static

Factory function for Family::ipv4 or Family::ipv6.

Throws if an invalid string. See also validStrings().

Definition at line 193 of file gaddress.cpp.

## ◆ parse() [4/4]

GNet::Address GNet::Address::parse | ( | std::string_view | host_part_string,
|  | unsigned int | port
| ) |  |
| static

Factory function for Family::ipv4 or Family::ipv6.

Throws if an invalid string. See also validStrings().

Definition at line 188 of file gaddress.cpp.

## ◆ port()

unsigned int GNet::Address::port | ( |  | ) | const

Returns port part of the address.

Definition at line 435 of file gaddress.cpp.

## ◆ queryString()

std::string GNet::Address::queryString | ( |  | ) | const

Returns a string that can be used as a prefix for rDNS or DNSBL queries.

Definition at line 374 of file gaddress.cpp.

## ◆ same()

bool GNet::Address::same | ( | const Address & | other,
|  | bool | ipv6_compare_with_scope
| ) |  | const

Comparison function.

Definition at line 322 of file gaddress.cpp.

## ◆ sameHostPart()

bool GNet::Address::sameHostPart | ( | const Address & | other | ) | const

Returns true if the two addresses have the same host part (ie.

the network address, ignoring the port number).

Definition at line 346 of file gaddress.cpp.

## ◆ scopeId()

unsigned long GNet::Address::scopeId | ( | unsigned long | default_ = `0UL` | ) | const

Returns the scope-id.

Returns the default if scope-ids are not supported by the underlying address type.

Definition at line 444 of file gaddress.cpp.

## ◆ setPort()

GNet::Address & GNet::Address::setPort | ( | unsigned int | port | ) |

Sets the port number.

Throws an exception if an invalid port number (ie. too big).

Definition at line 218 of file gaddress.cpp.

## ◆ setScopeId()

GNet::Address & GNet::Address::setScopeId | ( | unsigned long | ipv6_scope_id | ) |

Sets the scope-id.

Definition at line 238 of file gaddress.cpp.

## ◆ setZone()

bool GNet::Address::setZone | ( | const std::string & | ipv6_zone | ) |

Sets the zone.

The parameter is normally a decimal string representation of the zone-id, aka scope-id (eg. "1"), but if not numeric then it is treated as an interface name which is mapped to a zone-id by if_nametoindex(3). Returns false on error. Returns true if zones are not used by the address family.

Definition at line 228 of file gaddress.cpp.

## ◆ supports() [1/3]

bool GNet::Address::supports | ( | const Domain & | ,
|  | int | domain
| ) |  |
| static noexcept

Returns true if the implementation supports the given address domain given as PF_INET etc.

Definition at line 50 of file gaddress.cpp.

## ◆ supports() [2/3]

bool GNet::Address::supports | ( | Family | f | ) |
| static noexcept

Returns true if the implementation supports the given address family.

Definition at line 33 of file gaddress.cpp.

## ◆ supports() [3/3]

bool GNet::Address::supports | ( | int | af,
|  | int | dummy
| ) |  |
| static noexcept

Returns true if the implementation supports the given address family given as AF_INET etc.

Definition at line 45 of file gaddress.cpp.

## ◆ swap()

void GNet::Address::swap | ( | Address & | other | ) |
| noexcept

Swaps this with other.

Definition at line 161 of file gaddress.cpp.

## ◆ validData()

bool GNet::Address::validData | ( | const sockaddr * | addr,
|  | socklen_t | len
| ) |  |
| static

Returns true if the sockaddr data is valid.

This can be used to avoid exceptions from the relevant constructor.

Definition at line 458 of file gaddress.cpp.

## ◆ validPort()

bool GNet::Address::validPort | ( | unsigned int | n | ) |
| static

Returns true if the port number is within the valid range.

This can be used to avoid exceptions from the relevant constructors.

Definition at line 453 of file gaddress.cpp.

## ◆ validString() [1/2]

bool GNet::Address::validString | ( | std::string_view | display_string,
|  | NotLocal | ,
|  | std::string * | reason = `nullptr`
| ) |  |
| static

Returns true if the transport-address display string is valid.

This can be used to avoid exceptions from the relevant constructor.

Definition at line 391 of file gaddress.cpp.

## ◆ validString() [2/2]

bool GNet::Address::validString | ( | std::string_view | display_string,
|  | std::string * | reason = `nullptr`
| ) |  |
| static

Returns true if the transport-address display string is valid.

This can be used to avoid exceptions from the relevant constructor.

Definition at line 383 of file gaddress.cpp.

## ◆ validStrings()

bool GNet::Address::validStrings | ( | std::string_view | ip,
|  | std::string_view | port_string,
|  | std::string * | reason = `nullptr`
| ) |  |
| static

Returns true if the combined network-address string and port string is valid.

This can be used to avoid exceptions from the relevant constructor.

Definition at line 398 of file gaddress.cpp.

## ◆ wildcards()

G::StringArray GNet::Address::wildcards | ( |  | ) | const

Returns an ordered list of wildcard strings that match this address.

The fully-address-specific string (eg. "192.168.0.1") comes first, and the most general match-all wildcard like "*.*.*.*" or "128.0.0.0/1" comes last.

Definition at line 490 of file gaddress.cpp.

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

- /tmp/slackdce/slackrepo.HKsbdz/build_emailrelay/emailrelay-2.6/src/gnet/gaddress.h
- /tmp/slackdce/slackrepo.HKsbdz/build_emailrelay/emailrelay-2.6/src/gnet/gaddress.cpp