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 (const std::string &display_string)
 Factory function for any address family. More...
 
static Address parse (const std::string &display_string, NotLocal)
 Factory function for Family::ipv4 or Family::ipv6. More...
 
static Address parse (const std::string &host_part_string, unsigned int port)
 Factory function for Family::ipv4 or Family::ipv6. More...
 
static Address parse (const std::string &host_part_string, const std::string &port)
 Factory function for Family::ipv4 or Family::ipv6. More...
 
static bool isFamilyLocal (const std::string &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 (const std::string &display_string, std::string *reason=nullptr)
 Returns true if the transport-address display string is valid. More...
 
static bool validString (const std::string &display_string, NotLocal, std::string *reason=nullptr)
 Returns true if the transport-address display string is valid. More...
 
static bool validStrings (const std::string &ip, const std::string &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 61 of file gaddress.h.

Member Enumeration Documentation

◆ Family

enum class GNet::Address::Family
strong

Definition at line 64 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 409 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 419 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 484 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 249 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 205 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 358 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 468 of file gaddress.cpp.

◆ family()

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

Returns the address family enumeration.

Definition at line 476 of file gaddress.cpp.

◆ hostPartString()

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

Returns a printable string that represents the network address.

Definition at line 367 of file gaddress.cpp.

◆ is4()

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

Returns true if family() is ipv4.

Definition at line 314 of file gaddress.cpp.

◆ is6()

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

Returns true if family() is ipv6.

Definition at line 319 of file gaddress.cpp.

◆ isAny()

bool GNet::Address::isAny ( ) const

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

Definition at line 305 of file gaddress.cpp.

◆ isFamilyLocal()

bool GNet::Address::isFamilyLocal ( const std::string &  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 200 of file gaddress.cpp.

◆ isLinkLocal()

bool GNet::Address::isLinkLocal ( ) const

Returns true if this is a link-local address.

Definition at line 276 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 267 of file gaddress.cpp.

◆ isLoopback()

bool GNet::Address::isLoopback ( ) const

Returns true if this is a loopback address.

Definition at line 258 of file gaddress.cpp.

◆ isMulticast()

bool GNet::Address::isMulticast ( ) const

Returns true if this is a multicast address.

Definition at line 286 of file gaddress.cpp.

◆ isUniqueLocal()

bool GNet::Address::isUniqueLocal ( ) const

Returns true if this is a locally administered address.

Definition at line 296 of file gaddress.cpp.

◆ length()

socklen_t GNet::Address::length ( ) const

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

Definition at line 428 of file gaddress.cpp.

◆ loopback()

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

Returns a loopback address.

Definition at line 210 of file gaddress.cpp.

◆ operator G::BasicAddress()

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

Returns a G::BasicAddress.

Definition at line 215 of file gaddress.cpp.

◆ operator!=()

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

Comparison operator.

Definition at line 342 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 333 of file gaddress.cpp.

◆ parse() [1/4]

GNet::Address GNet::Address::parse ( const std::string &  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 ( const std::string &  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 ( const std::string &  host_part_string,
const std::string &  port 
)
static

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

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

Definition at line 194 of file gaddress.cpp.

◆ parse() [4/4]

GNet::Address GNet::Address::parse ( const std::string &  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 437 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 376 of file gaddress.cpp.

◆ same()

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

Comparison function.

Definition at line 324 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 348 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 446 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 220 of file gaddress.cpp.

◆ setScopeId()

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

Sets the scope-id.

Definition at line 240 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 230 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 460 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 455 of file gaddress.cpp.

◆ validString() [1/2]

bool GNet::Address::validString ( const std::string &  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 393 of file gaddress.cpp.

◆ validString() [2/2]

bool GNet::Address::validString ( const std::string &  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 385 of file gaddress.cpp.

◆ validStrings()

bool GNet::Address::validStrings ( const std::string &  ip,
const std::string &  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 400 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 492 of file gaddress.cpp.


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