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.
 
Addressoperator= (const Address &)
 Assignment operator. More...
 
Addressoperator= (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...
 
AddresssetPort (unsigned int port)
 Sets the port number. More...
 
bool setZone (const std::string &)
 Sets the zone. More...
 
AddresssetScopeId (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)
staticnoexcept

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)
staticnoexcept

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 
)
staticnoexcept

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)
staticnoexcept

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 
)
staticnoexcept

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: